Commit | Line | Data |
bfd90409 |
1 | #!/usr/bin/env perl |
2 | # |
3 | # SDL.pm |
4 | # |
5 | # Copyright (C) 2005 David J. Goehrig <dgoehrig@cpan.org> |
91e7ec4e |
6 | # Copyright (C) 2009 Kartik Thakore <kthakore@cpan.org> |
bfd90409 |
7 | # ------------------------------------------------------------------------------ |
8 | # |
9 | # This library is free software; you can redistribute it and/or |
10 | # modify it under the terms of the GNU Lesser General Public |
11 | # License as published by the Free Software Foundation; either |
12 | # version 2.1 of the License, or (at your option) any later version. |
13 | # |
14 | # This library is distributed in the hope that it will be useful, |
15 | # but WITHOUT ANY WARRANTY; without even the implied warranty of |
16 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
17 | # Lesser General Public License for more details. |
18 | # |
19 | # You should have received a copy of the GNU Lesser General Public |
20 | # License along with this library; if not, write to the Free Software |
21 | # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA |
22 | # |
23 | # ------------------------------------------------------------------------------ |
24 | # |
25 | # Please feel free to send questions, suggestions or improvements to: |
26 | # |
91e7ec4e |
27 | # Kartik Thakore |
28 | # kthakore@cpan.org |
bfd90409 |
29 | # |
30 | |
31 | package SDL; |
32 | |
33 | use strict; |
084b921f |
34 | use warnings; |
35 | use Carp; |
36 | |
bfd90409 |
37 | use vars qw($VERSION @ISA @EXPORT @EXPORT_OK); |
38 | |
39 | require Exporter; |
40 | require DynaLoader; |
41 | |
42 | use SDL_perl; |
43 | use SDL::Constants; |
44 | |
45 | BEGIN { |
46 | @ISA = qw(Exporter DynaLoader); |
47 | @EXPORT = qw( in verify &NULL ); |
48 | }; |
49 | |
659a4733 |
50 | # Give our caller SDL::Constant's stuff as well as ours. |
51 | sub import { |
52 | my $self = shift; |
53 | |
54 | $self->export_to_level(1, @_); |
55 | SDL::Constants->export_to_level(1); |
56 | } |
05c6b11c |
57 | $VERSION = '2.3'; |
bfd90409 |
58 | |
59 | print "$VERSION" if (defined($ARGV[0]) && ($ARGV[0] eq '--SDLperl')); |
60 | |
fe6d1297 |
61 | $SDL::DEBUG=0; |
bfd90409 |
62 | |
63 | sub NULL { |
64 | return 0; |
65 | } |
66 | |
67 | sub in { |
68 | my ($k,@t) = @_; |
1cf7cae7 |
69 | return 0 unless defined $k; |
5c44eb34 |
70 | my $r = ((scalar grep { defined $_ && $_ eq $k } @t) <=> 0); |
03aadbe5 |
71 | return 0 if $r eq ''; |
72 | return $r; |
73 | |
bfd90409 |
74 | } |
75 | |
76 | sub verify (\%@) { |
77 | my ($options,@valid_options) = @_; |
78 | for (keys %$options) { |
084b921f |
79 | croak "Invalid option $_\n" unless in ($_, @valid_options); |
bfd90409 |
80 | } |
81 | } |
82 | |
83 | |
84 | 1; |
85 | __END__ |
86 | |
87 | =head1 NAME |
88 | |
89 | SDL_perl - Simple DirectMedia Layer for Perl |
90 | |
91 | =head1 SYNOPSIS |
92 | |
93 | use SDL; |
94 | |
95 | =head1 DESCRIPTION |
96 | |
97 | SDL_perl is a package of perl modules that provides both functional and object orient |
98 | interfaces to the Simple DirectMedia Layer for Perl 5. This package does take some |
99 | liberties with the SDL API, and attempts to adhere to the spirit of both the SDL |
100 | and Perl. This document describes the low-level functional SDL_perl API. For the |
101 | object oriented programming interface please see the documentation provided on a |
102 | per class basis. |
103 | |
91e7ec4e |
104 | =head1 The SDL Perl 2009 Development Team |
105 | |
106 | =head2 Documentation |
107 | |
108 | Nick: magnet |
109 | |
110 | =head2 Perl Development |
111 | |
112 | Nick: Garu |
113 | Name: Breno G. de Oliveira |
114 | |
115 | Nick: Dngor |
116 | Name: Rocco Caputo |
117 | |
118 | Nick: nferraz |
119 | Name: Nelson Ferraz |
120 | |
6f188ec8 |
121 | Nick: acme |
9f6a22d0 |
122 | Name: Leon Brocard |
6f188ec8 |
123 | |
124 | Nick: FROGGS |
125 | Name: Tobias Leich |
9f6a22d0 |
126 | |
91e7ec4e |
127 | =head2 Maintainance |
128 | |
129 | Nick: kthakore |
91e7ec4e |
130 | Name: Kartik Thakore |
131 | |
132 | =head1 MacOSX Experimental Usage |
133 | |
134 | Please get libsdl packages from Fink |
135 | |
136 | perl Build.PL |
137 | perl Build test |
1a5654d1 |
138 | perl Build bundle |
91e7ec4e |
139 | perl Build install |
140 | |
141 | =head2 Running SDL Perl Scripts in MacOSX |
142 | |
143 | First set the PERL5LIB environment variable to the dependencies of your script |
144 | |
145 | %export PERL5LIB=$PERL5LIB:./lib |
146 | |
147 | Use the SDLPerl executable made in the bundle and call your scripts |
148 | |
149 | %SDLPerl.app/Contents/MacOS/SDLPerl yourScript.pl |
150 | |
151 | =head1 Functions exported by SDL.pm |
152 | |
7b31a037 |
153 | =head2 init(flags) |
bfd90409 |
154 | |
155 | As with the C language API, SDL_perl initializes the SDL environment through |
7b31a037 |
156 | the C<SDL::init> subroutine. This routine takes a mode flag constructed through |
def010aa |
157 | the bitwise OR product of the following constants: |
bfd90409 |
158 | |
159 | =over 4 |
24379be6 |
160 | |
bfd90409 |
161 | =item * |
def010aa |
162 | INIT_AUDIO |
bfd90409 |
163 | |
164 | =item * |
def010aa |
165 | INIT_VIDEO |
bfd90409 |
166 | |
167 | =item * |
def010aa |
168 | INIT_CDROM |
bfd90409 |
169 | |
170 | =item * |
def010aa |
171 | INIT_EVERYTHING |
bfd90409 |
172 | |
173 | =item * |
def010aa |
174 | INIT_NOPARACHUTE |
bfd90409 |
175 | |
176 | =item * |
def010aa |
177 | INIT_JOYSTICK |
bfd90409 |
178 | |
179 | =item * |
def010aa |
180 | INIT_TIMER |
bfd90409 |
181 | |
182 | =back |
183 | |
184 | C<SDL::Init> returns 0 on success, or -1 on error. |
185 | |
7b31a037 |
186 | =head2 init_subsystem(flags) |
bfd90409 |
187 | |
7b31a037 |
188 | After SDL has been initialized with SDL::init you may initialize uninitialized subsystems with SDL::init_subsystem. |
189 | The flags parameter is the same as that used in SDL::init. |
bfd90409 |
190 | |
7b31a037 |
191 | SDL::init_subsystem returns 0 on success, or -1 on error. |
bfd90409 |
192 | |
7b31a037 |
193 | =head2 quit_subsystem(flags) |
bfd90409 |
194 | |
7b31a037 |
195 | SDL::quit_subsystem allows you to shut down a subsystem that has been previously initialized by SDL::init or SDL::init_subsystem. |
196 | The flags tells SDL::quit_subSystem which subsystems to shut down, it uses the same values that are passed to SDL::init. |
bfd90409 |
197 | |
7b31a037 |
198 | SDL::quit_subsystem doesn't returns any value. |
bfd90409 |
199 | |
7b31a037 |
200 | =head2 quit |
bfd90409 |
201 | |
7b31a037 |
202 | Shuts down all SDL subsystems, unloads the dynamically linked library and frees the allocated resources. This should always be called before you exit. |
bfd90409 |
203 | |
7b31a037 |
204 | SDL::quit doesn't returns any value. |
bfd90409 |
205 | |
7b31a037 |
206 | =head2 was_init(flags) |
bfd90409 |
207 | |
7b31a037 |
208 | SDL::was_init allows you to see which SDL subsytems have been initialized. |
209 | flags is a bitwise OR'd combination of the subsystems you wish to check (see SDL::init for a list of subsystem flags). |
210 | If 'flags' is 0 or SDL_INIT_EVERYTHING, it returns a mask of all initialized subsystems (this does not include SDL_INIT_EVENTTHREAD or SDL_INIT_NOPARACHUTE). |
bfd90409 |
211 | |
bfd90409 |
212 | |
7b31a037 |
213 | =head2 get_error() |
bfd90409 |
214 | |
7b31a037 |
215 | The last error message set by the SDL library can be retrieved using the subroutine |
216 | C<SDL::get_error>, which returns a scalar containing the text of the message if any. |
bfd90409 |
217 | |
7b31a037 |
218 | =head2 set_error(error) *need to be coded |
bfd90409 |
219 | |
7b31a037 |
220 | SDL::get_error sets the SDL error to a printf style formatted string. |
221 | it doesn't returns any values. |
bfd90409 |
222 | |
7b31a037 |
223 | =head2 error(code) * need to be coded |
bfd90409 |
224 | |
7b31a037 |
225 | Sets the SDL error message to one of several predefined strings specified by code. |
bfd90409 |
226 | |
7b31a037 |
227 | code can be : |
bfd90409 |
228 | |
229 | =over 4 |
230 | |
7b31a037 |
231 | SDL_errorcode The corresponding error string |
bfd90409 |
232 | |
7b31a037 |
233 | SDL_ENOMEM Out of memory |
234 | SDL_EFREAD Error reading from datastream |
235 | SDL_EFWRITE Error writing to datastream |
236 | SDL_EFSEEK Error seeking in datastream |
237 | SDL_UNSUPPORTED Unknown SDL error |
238 | SDL_LASTERROR Unknown SDL error |
239 | any other value Unknown SDL error |
bfd90409 |
240 | |
bfd90409 |
241 | |
7b31a037 |
242 | Note 1: SDL_LASTERROR marks the highest numbered predefined error. |
243 | Note 2: SDL also defines SDL_OutOfMemory() and SDL_Unsupported() for internal use |
244 | which are equivalent to SDL_Error(SDL_ENOMEM) and SDL_Error(SDL_UNSUPPORTED) respectively. |
bfd90409 |
245 | |
246 | =back |
247 | |
7b31a037 |
248 | SDL::Error doesn't returns any value. |
bfd90409 |
249 | |
bfd90409 |
250 | |
7b31a037 |
251 | =head2 clear_error() * need to be coded |
bfd90409 |
252 | |
7b31a037 |
253 | SDL::clear_error deletes all information about the last internal SDL error. Useful if the error has been handled by the program. |
254 | it doesn't returns any value. |
bfd90409 |
255 | |
15a6855a |
256 | =head2 load_object() |
bfd90409 |
257 | |
7b31a037 |
258 | Need to be coded. |
bfd90409 |
259 | |
15a6855a |
260 | =head2 load_function() |
bfd90409 |
261 | |
7b31a037 |
262 | Need to be coded. |
bfd90409 |
263 | |
7b31a037 |
264 | =head2 unload_object() |
bfd90409 |
265 | |
7b31a037 |
266 | Need to be coded. |
bfd90409 |
267 | |
7b31a037 |
268 | =head2 VERSION() |
bfd90409 |
269 | |
7b31a037 |
270 | Need to be coded. |
bfd90409 |
271 | |
7b31a037 |
272 | =head2 version() |
bfd90409 |
273 | |
7b31a037 |
274 | Need to be coded. |
bfd90409 |
275 | |
7b31a037 |
276 | =head2 linked_version |
bfd90409 |
277 | |
7b31a037 |
278 | Need to be coded. |
bfd90409 |
279 | |
7b31a037 |
280 | =head2 get_error() |
bfd90409 |
281 | |
7b31a037 |
282 | The last error message set by the SDL library can be retrieved using the subroutine |
283 | C<SDL::get_error>, which returns a scalar containing the text of the message if any. |
bfd90409 |
284 | |
7b31a037 |
285 | =head2 delay(ms) |
bfd90409 |
286 | |
7b31a037 |
287 | This subroutine allows an application to delay further operations for atleast a |
288 | number of milliseconds provided as the argument. The actual delay may be longer |
289 | than the specified depending on the underlying OS. |
bfd90409 |
290 | |
bfd90409 |
291 | |
bfd90409 |
292 | |