SDLx::App - The root window of an SDL application
Extension
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.
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.
SDLx::App
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.
The window width, in pixels. Defaults to 640. Alias: w.
w
The window height, in pixels. Defaults to 480. Alias: h.
h
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.
d
The window's title, as a string. Defaults to the "icon_title" if defined, or the file name.
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.
The application's icon. Set with the "icon" method.
You can optionally use this when specifying the icon parameter to set its color key (transparent pixel).
icon
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.
initialize
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.
flags =
depth
f
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.
software_surface
sw
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.
hardware_surface
hw
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.
asynchronous_blit
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.
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.
hardware_palette
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.
double_buffer
dbl_buf
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.
full_screen
full
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.
gl
opengl
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.
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.
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.
SDL_VIDEO_CENTERED
$ENV{SDL_VIDEO_CENTERED}
center
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.
x
y
$ENV{SDL_VIDEO_WINDOW_POS}
pos
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.
no_cursor
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.
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.
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.
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
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.
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.
$app->resize( $w, $h );
Resizes the app to the specified width and height. The surface's depth and flags will remain the same.
$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.
$app->iconify();
Attempts to minimize the window with SDL::Video::wm_iconify_window. The exact behavior depends on the operating system.
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.
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.
$color
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.
sprintf
undef
$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.
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.
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.
$app->sync();
SDLx::App::sync encapsulates the various methods of synchronizing the screen with the current video buffer. SDLx::App::sync will do a fullscreen update, using the double buffer or OpenGL buffer if applicable. This is preferred to calling flip on the application window.
SDLx::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.
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.
See "AUTHORS" in SDL.
SDLx::Controller, SDLx::Surface, SDL::Video, SDL::Event, SDL::Mouse
To install SDL, copy and paste the appropriate command in to your terminal.
cpanm
cpanm SDL
CPAN shell
perl -MCPAN -e shell install SDL
For more information on module installation, please visit the detailed CPAN module installation guide.