/lib/pods/SDL.pod

http://github.com/PerlGameDev/SDL · Unknown · 290 lines · 166 code · 124 blank · 0 comment · 0 complexity · 7063c10fec068e8e4ddcea023da10468 MD5 · raw file

  1. =pod
  2. =head1 NAME
  3. SDL - Simple DirectMedia Layer for Perl
  4. =head1 CATEGORY
  5. Core
  6. =head1 SYNOPSIS
  7. use SDL;
  8. =head1 DESCRIPTION
  9. SDL_perl is a package of Perl modules that provide both functional and object oriented interfaces to the Simple DirectMedia Layer for Perl 5.
  10. This package takes some liberties with the SDL API, and attempts to adhere to the spirit of both the SDL and Perl.
  11. This document describes the low-level functional SDL Perl API.
  12. For the object oriented programming interface please see the documentation provided on a per-class basis.
  13. =head1 CONSTANTS
  14. The constants are not exported by default. You can export them by doing:
  15. use SDL ':all';
  16. or access them directly:
  17. SDL::SDL_INIT_AUDIO;
  18. or by choosing the export tags below:
  19. Export tag: ':init'
  20. SDL_INIT_AUDIO
  21. SDL_INIT_VIDEO
  22. SDL_INIT_CDROM
  23. SDL_INIT_EVERYTHING
  24. SDL_INIT_NOPARACHUTE
  25. SDL_INIT_JOYSTICK
  26. SDL_INIT_TIMER
  27. =head1 METHODS
  28. =head2 init
  29. SDL::init( $flags );
  30. As with the C language API, SDL Perl initializes the SDL environment with the C<SDL::init> subroutine.
  31. This routine takes a mode flag constructed through the bitwise OR product of the C<SDL_INIT_*> constants.
  32. The C<$flags> tell C<SDL::init> which subsystems to initialize.
  33. SDL::init(SDL_INIT_AUDIO | SDL_INIT_JOYSTICK);
  34. C<SDL::init> returns C<0> on success, or C<-1> on error.
  35. =head2 init_sub_system
  36. SDL::init_sub_system( $flags );
  37. After SDL has been initialized with C<SDL::init> you may initialize any uninitialized subsystems with C<SDL::init_sub_system>.
  38. The C<$flags> tell C<SDL::init_sub_system> which subsystems to initialize, and are taken in the same way as C<SDL::init>.
  39. C<SDL::init_sub_system> returns C<0> on success, or C<-1> on error.
  40. =head2 quit_sub_system
  41. SDL::quit_sub_system( $flags );
  42. 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>.
  43. 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>.
  44. C<SDL::quit_sub_system> doesn't return any values.
  45. =head2 quit
  46. SDL::quit;
  47. C<SDL::quit> Shuts down all SDL subsystems, unloads the dynamically linked library and frees the allocated resources.
  48. 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.
  49. C<SDL::quit> doesn't return any values.
  50. =head2 was_init
  51. my $flags = SDL::was_init( $flags );
  52. C<SDL::was_init> allows you to see which SDL subsystems have been initialized.
  53. The C<$flags> tell C<SDL::was_init> which subsystems to check, and are taken in the same way as C<SDL::init>.
  54. C<SDL::was_init> returns a mask of the initialized subsystems it checks.
  55. 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>).
  56. use SDL ':all';
  57. my $mask = SDL::was_init(SDL_INIT_AUDIO | SDL_INIT_JOYSTICK);
  58. if($mask & SDL_INIT_AUDIO and $mask & SDL_INIT_JOYSTICK) {
  59. # Both subsystems are initialized!
  60. }
  61. =head2 get_error
  62. my $error = SDL::get_error;
  63. Returns a scalar value containing the last error message set by the SDL library (if any).
  64. =head2 set_error_real
  65. SDL::set_error_real( $printf_format, @values )
  66. C<SDL::set_error_real> sets the SDL error to a C<printf> style formatted string.
  67. C<SDL::set_error_real> doesn't return any values.
  68. =head2 clear_error
  69. SDL::clear_error;
  70. C<SDL::clear_error> deletes all information about the last SDL error.
  71. This is useful if the error has been handled by the program.
  72. C<SDL::clear_error> doesn't return any values.
  73. =head2 version
  74. my $version = SDL::version;
  75. Returns an C<SDL::Version> object of the SDL library at compile-time.
  76. use SDL;
  77. use SDL::Version;
  78. my $v = SDL::version;
  79. printf("got version: %d.%d.%d\n", $v->major, $v->minor, $v->patch);
  80. =head2 linked_version
  81. 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.
  82. =head2 get_ticks
  83. my $ticks = SDL::get_ticks;
  84. Returns the number of milliseconds since SDL library initialization.
  85. This value wraps around if the program runs for more than 49.7 days
  86. =head2 get_handle
  87. my $win32_handle = SDL::get_handle;
  88. A video surface must be inited to get a handle.
  89. =head2 delay
  90. SDL::delay( $ms );
  91. C<SDL::delay> waits the specified number of milliseconds before returning.
  92. The actual delay may be longer than specified depending on the underlying OS.
  93. C<SDL::delay> doesn't return anything.
  94. # Delay for half a second
  95. SDL::delay(500);
  96. =head1 SDL Manual: Getting Started
  97. A new book has been started to provide a complete tutorial for SDL. See L<http://bit.ly/hvxc9V>.
  98. =head1 AUTHORS
  99. =head2 Project Founder
  100. David J. Goehrig
  101. =head2 Current Maintainers
  102. Kartik Thakore (kthakore)
  103. Tobias Leich (FROGGS)
  104. =head2 Core Developers and Contributors
  105. The following people have dedicated blood sweat and tears to making SDL Perl possible.
  106. See the L<impact graph|https://github.com/PerlGameDev/SDL/graphs/impact> on our github repository.
  107. Andy Bakun <sdlperl@thwartedefforts.org>
  108. Benedikt Meurer <bmeurer@fwdn.de>
  109. Blaise Roth (Blaizer) <blaizer@cpan.org>
  110. Breno G. de Oliveira (garu)
  111. Brian Cassidy (bricas)
  112. chromatic <chromatic@wgz.org>
  113. Daniel Mantovani <daniel.oliveira.mantovani@gmail.com>
  114. Daniel Ruoso http://daniel.ruoso.com/
  115. David J. Goehrig <dgoehrig@cpan.org>
  116. Dustin Mays (dorkfish) <dork.fish.wat.@gmail.com>
  117. Fedora
  118. Gabor Szabo (szabgab) <szabgab@gmail.com>
  119. Guillaue Cottenceau (gc) <gc@mandrakesoft.com>
  120. Heikki MehtE<195>nen (hmehta/hejki) <heikki@mehtanen.fi>
  121. James King
  122. James Wright <jwright@cpan.org>
  123. Jeffrey T. Palmer (jtpalmer) <jeffrey.t.palmer@gmail.com>
  124. Kartik Thakore (kthakore) <thakore.kartik@gmail.com>
  125. KatrinaTheLamia
  126. kmx <kmx@cpan.org>
  127. Luke
  128. Michael Lamertz <mike@perl-ronin.de>
  129. morgoth.666
  130. Peter BARABAS <z0d@artifact.hu>
  131. Russell Valentine <russ_allegro@yahoo.com>
  132. Ryan Hanlon
  133. Stephane Desneux <sdx@desneux.com>
  134. Tels <http://www.bloodgate.com>
  135. Thomas Tongue
  136. Tobias Leich (FROGGS)
  137. Tony C
  138. Yuval Kogman (nothingmuch)
  139. Wayne Keenan <wayne@metaverse.fsnet.co.uk>
  140. If you would like to contribute to SDL Perl, please post a message on the mailing list:
  141. sdl-devel@perl.org
  142. And request access to the github repository. Or drop us a line on #sdl over at irc.perl.org
  143. =head1 COPYRIGHT & LICENSE
  144. Copyright 2002-2010 SDL Authors as listed above, all rights reserved.
  145. This program is free software; you can redistribute it and/or modify it
  146. under the same terms as Perl itself.
  147. =head1 DISCLAIMER OF WARRANTY
  148. BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
  149. FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
  150. OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
  151. PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
  152. EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  153. WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
  154. ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
  155. YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
  156. NECESSARY SERVICING, REPAIR, OR CORRECTION.
  157. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
  158. WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
  159. REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE
  160. LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL,
  161. OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
  162. THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
  163. RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
  164. FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
  165. SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
  166. SUCH DAMAGES.