/lib/pods/SDL.pod
http://github.com/PerlGameDev/SDL · Unknown · 290 lines · 166 code · 124 blank · 0 comment · 0 complexity · 7063c10fec068e8e4ddcea023da10468 MD5 · raw file
- =pod
- =head1 NAME
- SDL - Simple DirectMedia Layer for Perl
- =head1 CATEGORY
- Core
- =head1 SYNOPSIS
- use SDL;
- =head1 DESCRIPTION
- SDL_perl is a package of Perl modules that provide both functional and object oriented interfaces to the Simple DirectMedia Layer for Perl 5.
- This package takes some liberties with the SDL API, and attempts to adhere to the spirit of both the SDL and Perl.
- This document describes the low-level functional SDL Perl API.
- For the object oriented programming interface please see the documentation provided on a per-class basis.
- =head1 CONSTANTS
- The constants are not exported by default. You can export them by doing:
- use SDL ':all';
- or access them directly:
- SDL::SDL_INIT_AUDIO;
- or by choosing the export tags below:
- Export tag: ':init'
- SDL_INIT_AUDIO
- SDL_INIT_VIDEO
- SDL_INIT_CDROM
- SDL_INIT_EVERYTHING
- SDL_INIT_NOPARACHUTE
- SDL_INIT_JOYSTICK
- SDL_INIT_TIMER
- =head1 METHODS
- =head2 init
- SDL::init( $flags );
- As with the C language API, SDL Perl initializes the SDL environment with the C<SDL::init> subroutine.
- This routine takes a mode flag constructed through the bitwise OR product of the C<SDL_INIT_*> constants.
- The C<$flags> tell C<SDL::init> which subsystems to initialize.
- SDL::init(SDL_INIT_AUDIO | SDL_INIT_JOYSTICK);
- C<SDL::init> returns C<0> on success, or C<-1> on error.
- =head2 init_sub_system
- SDL::init_sub_system( $flags );
- After SDL has been initialized with C<SDL::init> you may initialize any uninitialized subsystems with C<SDL::init_sub_system>.
- The C<$flags> tell C<SDL::init_sub_system> which subsystems to initialize, and are taken in the same way as C<SDL::init>.
- C<SDL::init_sub_system> returns C<0> on success, or C<-1> on error.
- =head2 quit_sub_system
- SDL::quit_sub_system( $flags );
- C<SDL::quit_sub_system> allows you to shut down a subsystem that has been previously initialized by C<SDL::init> or C<SDL::init_sub_system>.
- The C<$flags> tell C<SDL::quit_sub_system> which subsystems to shut down, and are taken in the same way as C<SDL::init>.
- C<SDL::quit_sub_system> doesn't return any values.
- =head2 quit
- SDL::quit;
- C<SDL::quit> Shuts down all SDL subsystems, unloads the dynamically linked library and frees the allocated resources.
- B<Note:> This will be called automatically when Perl exits. You don't need to call this, except if you want to initialize SDL again after this.
- C<SDL::quit> doesn't return any values.
- =head2 was_init
- my $flags = SDL::was_init( $flags );
- C<SDL::was_init> allows you to see which SDL subsystems have been initialized.
- The C<$flags> tell C<SDL::was_init> which subsystems to check, and are taken in the same way as C<SDL::init>.
- C<SDL::was_init> returns a mask of the initialized subsystems it checks.
- If C<$flags> is C<0> or C<SDL_INIT_EVERYTHING>, a mask of all initialized subsystems will be returned (this does not include C<SDL_INIT_EVENTTHREAD> or C<SDL_INIT_NOPARACHUTE>).
- use SDL ':all';
- my $mask = SDL::was_init(SDL_INIT_AUDIO | SDL_INIT_JOYSTICK);
- if($mask & SDL_INIT_AUDIO and $mask & SDL_INIT_JOYSTICK) {
- # Both subsystems are initialized!
- }
- =head2 get_error
- my $error = SDL::get_error;
- Returns a scalar value containing the last error message set by the SDL library (if any).
- =head2 set_error_real
- SDL::set_error_real( $printf_format, @values )
- C<SDL::set_error_real> sets the SDL error to a C<printf> style formatted string.
- C<SDL::set_error_real> doesn't return any values.
- =head2 clear_error
- SDL::clear_error;
- C<SDL::clear_error> deletes all information about the last SDL error.
- This is useful if the error has been handled by the program.
- C<SDL::clear_error> doesn't return any values.
- =head2 version
- my $version = SDL::version;
- Returns an C<SDL::Version> object of the SDL library at compile-time.
- use SDL;
- use SDL::Version;
- my $v = SDL::version;
- printf("got version: %d.%d.%d\n", $v->major, $v->minor, $v->patch);
- =head2 linked_version
- C<SDL::linked_version> works in the same way as C<SDL::version>, but returns an C<SDL::Version> object of the SDL library at link-time.
- =head2 get_ticks
- my $ticks = SDL::get_ticks;
- Returns the number of milliseconds since SDL library initialization.
- This value wraps around if the program runs for more than 49.7 days
- =head2 get_handle
- my $win32_handle = SDL::get_handle;
- A video surface must be inited to get a handle.
- =head2 delay
- SDL::delay( $ms );
- C<SDL::delay> waits the specified number of milliseconds before returning.
- The actual delay may be longer than specified depending on the underlying OS.
- C<SDL::delay> doesn't return anything.
- # Delay for half a second
- SDL::delay(500);
- =head1 SDL Manual: Getting Started
- A new book has been started to provide a complete tutorial for SDL. See L<http://bit.ly/hvxc9V>.
- =head1 AUTHORS
- =head2 Project Founder
- David J. Goehrig
- =head2 Current Maintainers
- Kartik Thakore (kthakore)
- Tobias Leich (FROGGS)
- =head2 Core Developers and Contributors
- The following people have dedicated blood sweat and tears to making SDL Perl possible.
- See the L<impact graph|https://github.com/PerlGameDev/SDL/graphs/impact> on our github repository.
- Andy Bakun <sdlperl@thwartedefforts.org>
- Benedikt Meurer <bmeurer@fwdn.de>
- Blaise Roth (Blaizer) <blaizer@cpan.org>
- Breno G. de Oliveira (garu)
- Brian Cassidy (bricas)
- chromatic <chromatic@wgz.org>
- Daniel Mantovani <daniel.oliveira.mantovani@gmail.com>
- Daniel Ruoso http://daniel.ruoso.com/
- David J. Goehrig <dgoehrig@cpan.org>
- Dustin Mays (dorkfish) <dork.fish.wat.@gmail.com>
- Fedora
- Gabor Szabo (szabgab) <szabgab@gmail.com>
- Guillaue Cottenceau (gc) <gc@mandrakesoft.com>
- Heikki MehtE<195>nen (hmehta/hejki) <heikki@mehtanen.fi>
- James King
- James Wright <jwright@cpan.org>
- Jeffrey T. Palmer (jtpalmer) <jeffrey.t.palmer@gmail.com>
- Kartik Thakore (kthakore) <thakore.kartik@gmail.com>
- KatrinaTheLamia
- kmx <kmx@cpan.org>
- Luke
- Michael Lamertz <mike@perl-ronin.de>
- morgoth.666
- Peter BARABAS <z0d@artifact.hu>
- Russell Valentine <russ_allegro@yahoo.com>
- Ryan Hanlon
- Stephane Desneux <sdx@desneux.com>
- Tels <http://www.bloodgate.com>
- Thomas Tongue
- Tobias Leich (FROGGS)
- Tony C
- Yuval Kogman (nothingmuch)
- Wayne Keenan <wayne@metaverse.fsnet.co.uk>
- If you would like to contribute to SDL Perl, please post a message on the mailing list:
- sdl-devel@perl.org
- And request access to the github repository. Or drop us a line on #sdl over at irc.perl.org
- =head1 COPYRIGHT & LICENSE
- Copyright 2002-2010 SDL Authors as listed above, all rights reserved.
- This program is free software; you can redistribute it and/or modify it
- under the same terms as Perl itself.
- =head1 DISCLAIMER OF WARRANTY
- BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
- FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
- OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
- PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
- EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
- WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
- ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
- YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
- NECESSARY SERVICING, REPAIR, OR CORRECTION.
- IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
- WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
- REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE
- LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL,
- OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
- THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
- RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
- FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
- SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
- SUCH DAMAGES.