/ 
SDL-2.541_05
River stage two • 23 direct dependents • 25 total dependents
/ SDLx::App

NAME

SDLx::App - The root window of an SDL application

CATEGORY

Extension

SYNOPSIS

use SDL;
use SDLx::App;
use SDL::Event;
use SDL::Events;

# this is all the code we need to have a working app!
my $app = SDLx::App->new;

# we can also specify many useful things in the constructor
my $app = SDLx::App->new(
    title      => 'My Great Game',
    width      => 1024,
    height     => 600,
    dt         => 0.05,
    centered   => 1,
    no_frame   => 1,
    async_blit => 1,
);

# our app also comes with an SDLx::Controller

# add a handler handle events such as keypresses
$app->add_event_handler(
    sub {
         my ($event) = @_;
         # handle the event here
    }
);

# add a handler to move our objects in response to time
$app->add_move_handler(
    sub {
        # handle moving objects here
    }
);

# add a handler to show our objects on the screen
$app->add_show_handler(
    sub {
        # handle drawing objects here
    }
);

# finally, start the app run loop with the added handlers
$app->run();

For a full explanation of the run loop and other Controller related methods, please see SDLx::Controller.

DESCRIPTION

The SDLx::App provides methods for the root window of your SDL application, as well as many related convenience methods. It is a subclass of both SDLx::Surface and SDLx::Controller, providing all the methods they both provide.

METHODS

new

my $app = SDLx::App->new(
    width  => 640,
    height => 480,
    depth  => 32,

    title          => "Application Title",
    icon_title     => "App Title",
    icon           => "icon.bmp",
    icon_color_key => [255, 255, 0],

    # two ways to do init. init video is assumed regardless
    init => SDL_INIT_AUDIO | SDL_INIT_JOYSTICK,
    init => [ 'audio', 'joystick' ],

    # normal libsdl access to flags
    flags => SDL_SWSURFACE | SDL_ANYFORMAT,
    # or parameter access to flags
    sw_surface => 1,
    hw_surface => 1,
    async_blit => 1,
    any_format => 1,
    hw_palette => 1,
    double_buf => 1,
    fullscreen => 1,
    open_gl    => 1,
    resizable  => 1,
    no_frame   => 1,

    # window position
    centered => 1,
    position => [ 150, 100 ],

    hide_cursor  => 1,
    grab_input => 1,

    # don't initialize an SDLx::Controller for the app
    no_controller => 1,

    # store your goodies in the app if you like
    stash => {},

    # and everything from SDLx::Controller
    dt             => 0.1,
    min_t          => 1 / 60,
    delay          => 0,
    stop_handler   => \&SDLx::Controller::default_stop_handler,
    event          => SDL::Event->new(),
    event_handlers => [],
    move_handlers  => [],
    show_handlers  => [],
    time           => 0,
);

Initializes SDL with SDLx::App::init, creates the root window with SDL::Video::set_video_mode, initializes an SDLx::Controller belonging to the app, and performs many other app management tasks all as specified by named parameters. Returns an SDLx::Surface of the new app.

The complete set of parameters are shown in the code above and explained in detail below. When constructing the app's SDLx::Controller all parameters specified are also given to SDLx::Controller->new, so should be specified here. See SDLx::Controller.

width

The window width, in pixels. Defaults to 640. Alias: w.

height

The window height, in pixels. Defaults to 480. Alias: h.

depth

The surface's color depth, in bits per pixel. Should be 8, 16, 24 or 32. If not defined, defaults to 32 and specifies the SDL_ANYFORMAT flag. Alias: d.

title

The window's title, as a string. Defaults to the "icon_title" if defined, or the file name.

icon_title

The application's icon title, as a string. Defaults to the "title" if defined, or the file name. This will only have an effect under certain operating systems.

icon

The application's icon. Set with the "icon" method.

icon_color_key

You can optionally use this when specifying the icon parameter to set its color key (transparent pixel).

init

The SDL subsystems to initialize, as a product of the SDL init constants or an array ref. The video subsystem is initialized no matter what, and does not need to be specified. The specified value is passed to SDLx::App::init, so see that for more details. Defaults to SDL_INIT_EVERYTHING. Alias: initialize.

flags

SDL::Video flags to specify when calling SDL::Video::set_video_mode. Flags should be bitwise or'ed together when passing more than one (flags = FOO|BAR>). All flags have a corresponding named parameter which can be used instead of specifying them here, and are explained below. Defaults to no flags, or to SDL_ANYFORMAT if the depth parameter was undefined. Alias: f.

sw_surface

The SDL_SWSURFACE flag, as a boolean. If true, creates the surface in system memory. This is best used when you plan to do per-pixel manipulations, or blit surfaces with alpha channels. Aliases: software_surface, sw.

hw_surface

The SDL_HWSURFACE flag, as a boolean. If true, creates the surface in video memory. This is best used when the surfaces you'll be blitting are also hardware surfaces. SDL copies the surfaces from video memory to system memory when you lock them, and back when you unlock them, which can cause a major performance hit. If the video driver does not support hardware surfaces, a software surface will be returned instead. Many platforms can only provide hardware surfaces when using SDL_FULLSCREEN. Aliases: hardware_surface, hw.

async_blit

The SDL_ASYNCBLIT flag, as a boolean. If true, enables the use of asynchronous updates of the display surface. This will usually slow down blitting on single-CPU machines, but can speed up blitting on multi-CPU machines. Alias: asynchronous_blit.

any_format

The SDL_ANYFORMAT flag, as a boolean. If a video surface of the requested bits-per-pixel (bpp) is not available SDL will normally emulate one with a shadow surface. Passing a true value prevents this and causes SDL to use the video surface, regardless of its pixel depth. This flag is specified automatically when the "depth" parameter is undefined.

hw_palette

The SDL_HWPALETTE flag, as a boolean. If true, gives SDL exclusive palette access. Without this flag you may not always get the exact colors you request with SDL::Video::set_colors or SDL::Video::set_palette. Alias: hardware_palette.

double_buf

The SDL_DOUBLEBUF flag, as a boolean. If true, enables hardware double buffering; faster, but only valid with a hardware surface. flip should be used to flip the buffers and update the screen. All drawing will take place on the surface that is not being displayed. If double buffering could not be enabled then flip will just perform an update_rect on the entire screen. Aliases: double_buffer, dbl_buf.

fullscreen

The SDL_FULLSCREEN flag, as a boolean. If true, SDL will attempt to use a fullscreen mode, changing the hardware resolution to the resolution of the display surface. If, for whatever reason, this change is not possible the next higher resolution will be used and the display surface centered on a black background. Aliases: full_screen, full.

open_gl

The SDL_OPENGL flag, as a boolean. If true, creates an OpenGL rendering context. This uses any gl attributes specified and any others set with "gl_attribute". Aliases: opengl, gl.

resizable

The SDL_RESIZABLE flag, as a boolean. If true, creates a resizable window. When the window is resized by the user a SDL_VIDEORESIZE event is generated and "resize" should be called with the new size.

no_frame

The SDL_NOFRAME flag, as a boolean. If true, SDL attempts to create a window with no title bar or frame decoration. Fullscreen modes automatically have this flag set.

centered

A boolean value. If true, creates the window centered on the screen. SDL does this with the SDL_VIDEO_CENTERED environment variable which is set using $ENV{SDL_VIDEO_CENTERED}. Alias: center.

position

The position of the window on the screen, as an array ref. The array ref should be two elements long, specifying x and y values, in pixels, used to position the window on the screen. Implemented using $ENV{SDL_VIDEO_WINDOW_POS}. Alias: pos.

hide_cursor

A boolean value. If true, hides the cursor on the video surface using "show_cursor". A surface can then instead be blitted to the display at the location of the cursor. Alias: no_cursor.

grab_input

A boolean value. If true, SDL attempts to confine the cursor to the window using "grab_input". Also, nearly all keyboard input will be passed directly to the application, and not interpreted by any window manager present.

no_controller

A boolean value. If true, does not initialize an SDLx::Controller for the app. Care should then be taken to not use any of SDLx::Controllers methods.

stash

A place to store any information you need the app to hold. This can then be returned and set with "stash". If not specified, defaults to an empty hash ref.

init

SDLx::App->init( SDL::SDL_INIT_TIMER | SDL::SDL_INIT_AUDIO | ... );
SDLx::App->init( [ 'timer', 'audio', 'video', 'cd_rom', 'cdrom', 'joystick',
                   'everything', 'all', 'no_parachute', 'event_thread' ]  );

This is used internally by "new" to init SDL with SDL::init. If any subsystems are already initialized, it will use SDL::init_sub_system instead. You should use this whenever you need to init anything outside calls to "new", as it will always do what you want.

If a number is specified, it will initialize SDL in the same way as SDL::init describes. If an array ref is specified, each element should be a string corresponding to a flag to specify. The strings and their corresponding flags are shown in the table below. See SDL::init for descriptions of what each flag does.

flag                    string          alias
====================    ============    ======
SDL_INIT_TIMER          timer
SDL_INIT_AUDIO          audio
SDL_INIT_VIDEO          video
SDL_INIT_CDROM          cd_rom          cdrom
SDL_INIT_JOYSTICK       joystick
SDL_INIT_EVERYTHING     everything      all
SDL_INIT_NOPARACHUTE    no_parachute
SDL_INIT_EVENTTHREAD    event_thread

screen_size

my ($screen_w, $screen_h, $screen_d) = SDLx::App->screen_size();

Returns the width, height and depth of the user's screen using SDL::Video::get_video_info. This can be called before or after calling "new". Initializing the video subsystem will be handled correctly no matter what thanks to SDLx::App::init.

set_video_mode

my $app = SDLx::App->set_video_mode( $w, $h, $d, $f );
$app->set_video_mode( $w, $h, $d, $f );

The first form is used internally by "new" to create the new SDL display surface. The second form can be used to change the video mode of an existing app. See SDL::Video::set_video_mode for a description on what the four arguments do.

resize

$app->resize( $w, $h );

Resizes the app to the specified width and height. The surface's depth and flags will remain the same.

fullscreen

$app->fullscreen();

Toggles the app in and out of fullscreen mode in a cross-platform-friendly way. Returns false if the app fails to go fullscreen for some reason. Otherwise, returns true.

iconify

$app->iconify();

Attempts to minimize the window with SDL::Video::wm_iconify_window. The exact behavior depends on the operating system.

title

my ( $title, $icon_title ) = $app->title();
$app->title( $title, $icon_title );

If no arguments are specified, returns a list of the title and the icon title. If arguments are specified, the titles will be set instead. Specify undef to keep the title or icon title the same, or a string to modify them.

icon

SDLx::App->icon( $filename, $color );
SDLx::App->icon( $surface, $color );

Sets the window's icon. This must be called before creating the display surface, so SDL::Image can not be used. If a filename is specified, it is loaded with SDL::Video::load_BMP. Otherwise, the first argument should be a surface. Win32 icons must be 32x32. The $color argument is optional and, if specified, is used to set the icon's color key (transparent pixel). It should be an RGB color as either a number or array ref.

error

my $error = $app->error();
$app->error( @error );
$app->error( undef );

With no arguments, returns the current SDL error using SDL::get_error. With one or more arguments, sets the SDL error to the sprintf formatted string. With undef as the one and only argument, clears the SDL error. This can be used when you are done with the error.

warp_cursor

$app->warp_cursor( $x, $y );

Moves the cursor to the specified coordinates on the application window. If an argument is not specified, it will default to 0.

show_cursor

my $is_cursor_shown = $app->show_cursor();
$app->show_cursor( $show );

With no arguments, returns a value that will be true if the cursor is currently being shown or false otherwise. With an argument, the cursor will be shown if it is true or hidden otherwise.

grab_input

my $is_grabbing_input = $app->grab_input();
$app->grab_input( $grab );

Grab input attempts to confine the cursor to the window. Also, nearly all keyboard input will be passed directly to the application, and not interpreted by any window manager present. If no arguments are specified, returns a boolean that will be true if grab input is on or false if it is off. If an argument is specified, grab input will be turned on if it is true or off otherwise.

sync

$app->sync();

Swaps the OpenGL buffers and does a full update of the screen with SDL::Video::GL_swap_buffers if OpenGL is being used. This is preferable to swapping the SDL buffers. Otherwise, just swaps the SDL buffers using SDL::Video::flip.

gl_attribute

my $value = $app->( $attribute );
$app->gl_attribute( $attribute, $value );

With one argument, returns the value of the specified attribute using SDL::Video::GL_get_attribute. With a value argument, sets the specified attribute to the specified value using SDL::Video::GL_set_attribute. The attribute argument should be one of the SDL::Video::SDL_GL_* constants. See SDL::Video::GL_set_attribute for more details.

AUTHORS

See "AUTHORS" in SDL.

SEE ALSO

SDLx::Controller, SDLx::Surface, SDL::Video, SDL::Event, SDL::Mouse