/lib/pods/SDL.pod

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