Commit | Line | Data |
896b04ee |
1 | =head1 NAME |
2 | |
3 | SDL_perl - Simple DirectMedia Layer for Perl |
4 | |
5 | =head1 SYNOPSIS |
6 | |
7 | use SDL; |
8 | |
9 | =head1 DESCRIPTION |
10 | |
11 | SDL_perl is a package of perl modules that provides both functional and object orient |
12 | interfaces to the Simple DirectMedia Layer for Perl 5. This package does take some |
13 | liberties with the SDL API, and attempts to adhere to the spirit of both the SDL |
14 | and Perl. This document describes the low-level functional SDL_perl API. For the |
15 | object oriented programming interface please see the documentation provided on a |
16 | per class basis. |
17 | |
18 | =head1 The SDL Perl 2009 Development Team |
19 | |
20 | =head2 Documentation |
21 | |
22 | Nick: magnet |
23 | |
24 | =head2 Perl Development |
25 | |
26 | Nick: Garu |
27 | Name: Breno G. de Oliveira |
28 | |
29 | Nick: Dngor |
30 | Name: Rocco Caputo |
31 | |
32 | Nick: nferraz |
33 | Name: Nelson Ferraz |
34 | |
35 | Nick: acme |
36 | Name: Leon Brocard |
37 | |
38 | Nick: FROGGS |
39 | Name: Tobias Leich |
40 | |
41 | =head2 Maintainance |
42 | |
43 | Nick: kthakore |
44 | Name: Kartik Thakore |
45 | |
46 | =head1 MacOSX Experimental Usage |
47 | |
48 | Please get libsdl packages from Fink |
49 | |
50 | perl Build.PL |
51 | perl Build test |
52 | perl Build bundle |
53 | perl Build install |
54 | |
55 | =head2 Running SDL Perl Scripts in MacOSX |
56 | |
57 | First set the PERL5LIB environment variable to the dependencies of your script |
58 | |
59 | %export PERL5LIB=$PERL5LIB:./lib |
60 | |
61 | Use the SDLPerl executable made in the bundle and call your scripts |
62 | |
63 | %SDLPerl.app/Contents/MacOS/SDLPerl yourScript.pl |
64 | |
65 | =head1 Functions exported by SDL.pm |
66 | |
67 | =head2 init(flags) |
68 | |
69 | As with the C language API, SDL_perl initializes the SDL environment through |
70 | the C<SDL::init> subroutine. This routine takes a mode flag constructed through |
71 | the bitwise OR product of the following constants: |
72 | |
73 | =over 4 |
74 | |
75 | =item * |
76 | INIT_AUDIO |
77 | |
78 | =item * |
79 | INIT_VIDEO |
80 | |
81 | =item * |
82 | INIT_CDROM |
83 | |
84 | =item * |
85 | INIT_EVERYTHING |
86 | |
87 | =item * |
88 | INIT_NOPARACHUTE |
89 | |
90 | =item * |
91 | INIT_JOYSTICK |
92 | |
93 | =item * |
94 | INIT_TIMER |
95 | |
96 | =back |
97 | |
98 | C<SDL::Init> returns 0 on success, or -1 on error. |
99 | |
100 | =head2 init_subsystem(flags) |
101 | |
102 | After SDL has been initialized with SDL::init you may initialize uninitialized subsystems with SDL::init_subsystem. |
103 | The flags parameter is the same as that used in SDL::init. |
104 | |
105 | SDL::init_subsystem returns 0 on success, or -1 on error. |
106 | |
107 | =head2 quit_subsystem(flags) |
108 | |
109 | SDL::quit_subsystem allows you to shut down a subsystem that has been previously initialized by SDL::init or SDL::init_subsystem. |
110 | The flags tells SDL::quit_subSystem which subsystems to shut down, it uses the same values that are passed to SDL::init. |
111 | |
112 | SDL::quit_subsystem doesn't returns any value. |
113 | |
114 | =head2 quit |
115 | |
116 | Shuts down all SDL subsystems, unloads the dynamically linked library and frees the allocated resources. This should always be called before you exit. |
117 | |
118 | SDL::quit doesn't returns any value. |
119 | |
120 | =head2 was_init(flags) |
121 | |
122 | SDL::was_init allows you to see which SDL subsytems have been initialized. |
123 | flags is a bitwise OR'd combination of the subsystems you wish to check (see SDL::init for a list of subsystem flags). |
124 | 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). |
125 | |
126 | |
127 | =head2 get_error() |
128 | |
129 | The last error message set by the SDL library can be retrieved using the subroutine |
130 | C<SDL::get_error>, which returns a scalar containing the text of the message if any. |
131 | |
132 | =head2 set_error(error) *need to be coded |
133 | |
134 | SDL::get_error sets the SDL error to a printf style formatted string. |
135 | it doesn't returns any values. |
136 | |
137 | =head2 error(code) * need to be coded |
138 | |
139 | Sets the SDL error message to one of several predefined strings specified by code. |
140 | |
141 | code can be : |
142 | |
143 | =over 4 |
144 | |
145 | SDL_errorcode The corresponding error string |
146 | |
147 | SDL_ENOMEM Out of memory |
148 | SDL_EFREAD Error reading from datastream |
149 | SDL_EFWRITE Error writing to datastream |
150 | SDL_EFSEEK Error seeking in datastream |
151 | SDL_UNSUPPORTED Unknown SDL error |
152 | SDL_LASTERROR Unknown SDL error |
153 | any other value Unknown SDL error |
154 | |
155 | |
156 | Note 1: SDL_LASTERROR marks the highest numbered predefined error. |
157 | Note 2: SDL also defines SDL_OutOfMemory() and SDL_Unsupported() for internal use |
158 | which are equivalent to SDL_Error(SDL_ENOMEM) and SDL_Error(SDL_UNSUPPORTED) respectively. |
159 | |
160 | =back |
161 | |
162 | SDL::Error doesn't returns any value. |
163 | |
164 | |
165 | =head2 clear_error() * need to be coded |
166 | |
167 | SDL::clear_error deletes all information about the last internal SDL error. Useful if the error has been handled by the program. |
168 | it doesn't returns any value. |
169 | |
170 | =head2 load_object() |
171 | |
172 | Need to be coded. |
173 | |
174 | =head2 load_function() |
175 | |
176 | Need to be coded. |
177 | |
178 | =head2 unload_object() |
179 | |
180 | Need to be coded. |
181 | |
182 | =head2 VERSION() |
183 | |
184 | Need to be coded. |
185 | |
186 | =head2 version() |
187 | |
188 | Need to be coded. |
189 | |
190 | =head2 linked_version |
191 | |
192 | Need to be coded. |
193 | |
194 | =head2 get_error() |
195 | |
196 | The last error message set by the SDL library can be retrieved using the subroutine |
197 | C<SDL::get_error>, which returns a scalar containing the text of the message if any. |
198 | |
199 | =head2 delay(ms) |
200 | |
201 | This subroutine allows an application to delay further operations for atleast a |
202 | number of milliseconds provided as the argument. The actual delay may be longer |
203 | than the specified depending on the underlying OS. |
204 | |
205 | |
206 | |