/lib/pods/SDL/Image.pod

  1
  2=pod
  3
  4=head1 NAME
  5
  6SDL::Image - Bindings for the SDL_Image library
  7
  8=head1 DESCRIPTION
  9
 10SDL::Image allows you to load many different format of images into memory as an SDL::Surface.
 11
 12=head1 CATEGORY
 13
 14Image
 15
 16=head1 SUPPORTED FORMATS 
 17
 18The following types are supported:
 19
 20=over
 21
 22=item TGA
 23
 24TrueVision Targa (MUST have .tga) 
 25
 26=item BMP
 27
 28Windows Bitmap(.bmp) 
 29
 30=item PNM
 31
 32Portable Anymap (.pnm)
 33.pbm = Portable BitMap (mono)
 34.pgm = Portable GreyMap (256 greys)
 35.ppm = Portable PixMap (full color)
 36
 37=item XPM
 38
 39X11 Pixmap (.xpm) can be #included directly in code
 40This is NOT the same as XBM(X11 Bitmap) format, which is for monocolor images. 
 41
 42=item XCF
 43
 44GIMP native (.xcf) (XCF = eXperimental Computing Facility?)
 45This format is always changing, and since there's no library supplied by the GIMP project to load XCF, the loader may frequently fail to load much 
 46of any image from an XCF file. It's better to load this in GIMP and convert to a better supported image format. 
 47
 48=item PCX
 49
 50ZSoft IBM PC Paintbrush (.pcx) 
 51
 52=item GIF
 53
 54CompuServe Graphics Interchange Format (.gif) 
 55
 56=item JPG
 57
 58Joint Photographic Experts Group JFIF format (.jpg or .jpeg) 
 59
 60=item TIF
 61
 62Tagged Image File Format (.tif or .tiff) 
 63
 64=item LBM
 65
 66Interleaved Bitmap (.lbm or .iff) FORM : ILBM or PBM(packed bitmap), HAM6, HAM8, and 24bit types are not supported. 
 67
 68=item PNG
 69
 70Portable Network Graphics (.png) 
 71
 72=item XV
 73
 74=item ICO
 75
 76=item CUR
 77
 78=back
 79
 80
 81=head1 LOADING METHODS
 82
 83=head2 load
 84
 85 my $surface = SDL::Image::load( $file );
 86
 87$file Image file name to load a surface from. 
 88 
 89Load file for use as an image in a new L<SDL::Surface>. This actually calls L<SDL::Image::load_typed_rw|SDL::Image/"load_typed_rw">, with the 
 90file extension used as the type string. This can load all supported image files, including TGA as long as the filename ends with ".tga". It is 
 91best to call this outside of event loops, and rather keep the loaded images around until you are really done with them, as disk speed and image 
 92conversion to a surface is not that speedy.  
 93
 94B<Note>: If the image format loader requires initialization, it will attempt to do that the first time it is needed if you have not already called 
 95L<SDL::Image::init|SDL::Image/"init"> to load support for your image format.
 96
 97B<Note>: If the image format supports a transparent pixel, L<SDL::Image> will set the colorkey for the surface. You can enable RLE acceleration on 
 98the surface afterwards by calling:
 99
100L<SDL::Video::set_color_key|SDL::Video/"set_color_key">
101 
102  my $image = SDL::Image::load( $some_png_file );
103  SDL::Video::set_color_key($image, SDL_RLEACCEL, $image->format->colorkey);
104
105=head3 Return
106
107An image as a L<SDL::Surface>. NULL is returned on errors, such as no support built for the image, or a file reading error. Use 
108L<SDL::get_error|SDL/"get_error"> to get cause of error.
109
110=head2 load_typed_rw
111
112  SDL::Image::load_typed_rw($src, $freesrc, $type);
113
114=over
115
116=item src
117
118The source L<SDL::RWops> as a pointer. The image is loaded from this. 
119
120=item freesrc
121
122A non-zero value mean is will automatically close/free the src for you. Since SDL Perl cannot handle the memory inside this function you would most 
123likely want 1 here.
124
125=item type
126
127A string that indicates which format type to interpret the image as.
128
129Here is a list of the currently recognized strings (case is not important):
130
131=over
132
133=item "BMP"
134
135=item "CUR"
136
137=item "GIF"
138
139=item "ICO"
140
141=item "JPG"
142
143=item "LBM"
144
145=item "PCX"
146
147=item "PNG"
148
149=item "PNM"
150
151=item "TGA"
152
153=item "TIF"
154
155=item "XCF"
156
157=item "XPM"
158
159=item "XV"
160
161=back
162
163=back 
164
165Load src for use as a surface. This can load all supported image formats. This method does not guarantee that the format specified by type is the 
166format of the loaded image, except in the case when TGA format is specified (or any other non-magicable format in the future). Using SDL_RWops is 
167not covered here, but they enable you to load from almost any source.
168
169B<Note>: If the image format loader requires initialization, it will attempt to do that the first time it is needed if you have not already called 
170L<SDL::Image::init|SDL::Image/"init"> to load support for your image format.
171
172B<Note>: If the image format supports a transparent pixel, L<SDL::Image> will set the colorkey for the surface. You can enable RLE acceleration on 
173the surface afterwards by calling: L<SDL::Video::set_color_key|SDL::Video/"set_color_key">
174
175=head3 Transparency 
176
177  use SDL;
178  use SDL::RWOps;
179  use SDL::Image;
180
181  my $file2 = SDL::RWOps->new_file("test/data/menu.png", "rb");
182  my $image = SDL::Image::load_typed_rw($file2, 1, "PNG");
183
184  SDL::Video::set_color_key($image, SDL_RLEACCEL, $image->format->colorkey);
185
186=head3 Return 
187
188The image as a new L<SDL::Surface>. NULL is returned on errors. 
189 
190=head2 is_[TYPE]
191
192Test for valid, supported image files:
193
194=over
195
196=item is_ICO
197
198=item is_CUR
199
200=item is_PNG
201
202=item is_BMP
203
204=item is_GIF
205
206=item is_JPG
207
208=item is_LBM
209
210=item is_PCX
211
212=item is_PNM 
213
214=item is_TIF
215
216=item is_XCF
217
218=item is_XPM
219
220=item is_XV
221
222=back
223
224These functions take a L<SDL::RWOps> as a parameter.
225
226=head3 Return
227
2281 if the image is a valid [TYPE]  and the [TYPE] format support is compiled into SDL_image. 0 is returned otherwise. 
229
230=head3 Example
231
232 use SDL::RWOps;
233 use SDL::Image;
234
235 my $file = SDL::RWOps->new_file("file", "rb");
236 
237 print "Image is BMP" if ( SDL::is_BMP );
238
239=head2 load_[TYPE]_rw
240
241Specific loader for known formats:
242
243=over
244
245=item load_ICO_rw
246
247=item load_CUR_rw
248
249=item load_PNG_rw
250
251=item load_BMP_rw
252
253=item load_GIF_rw
254
255=item load_JPG_rw
256
257=item load_LBM_rw
258
259=item load_PCX_rw
260
261=item load_PNM_rw 
262
263=item load_TIF_rw
264
265=item load_XCF_rw
266
267=item load_XPM_rw
268
269=item load_XV_rw
270
271=back
272
273These functions take a L<SDL::RWop> as a parameter
274
275=head3 Return
276
277The image as a new L<SDL::Surface>. NULL is returned on errors, like if the [TYPE] is not supported, or a read error.
278
279=head3 Example
280
281 use SDL;
282 use SDL::RWOps;
283 use SDL::Image;
284
285 my $file = SDL::RWOps->new_file("file.png", "rb");  
286
287 my $image = SDL::Image::load_PNG_rw($file);
288 
289 die SDL::get_error if (!$image);  
290 
291=head2 read_XPM_from_array
292
293 my $picture = SDL::Image::read_XPM_from_array(\@XPM, $width);
294
295This functions takes the reference of an array in the valid @XPM format. Also the $width of the XPM image.
296
297=head3 Return
298
299The image as a new L<SDL::Surface>. NULL is returned on errors, like if XPM is not supported, or a read error. 
300
301=head3 Example
302
303	my @XPM= (
304	'30 30 9 1',
305	' 	c #FFFFFF',
306	'.	c #EFEFEF',
307	'+	c #CFCFCF',
308	'@	c #9F9F9F',
309	'#	c #808080',
310	'$	c #505050',
311	'%	c #202020',
312	'&	c #000000',
313	'*	c #303030',
314	'                              ',
315	'                              ',
316	'                              ',
317	'                              ',
318	'                              ',
319	'                              ',
320	'                              ',
321	'                              ',
322	'                              ',
323	'           .+@##@+.           ',
324	'          .@$%&&%$@.          ',
325	'         .@*&&&&&&*@.         ',
326	'         +$&&&&&&&&$+         ',
327	'         @%&&&&&&&&%@         ',
328	'         #&&&&&&&&&&#         ',
329	'         #&&&&&&&&&&#         ',
330	'         @%&&&&&&&&%@         ',
331	'         +$&&&&&&&&$+         ',
332	'         .@*&&&&&&*@.         ',
333	'          .@$%&&%$@.          ',
334	'           .+@##@+.           ',
335	'                              ',
336	'                              ',
337	'                              ',
338	'                              ',
339	'                              ',
340	'                              ',
341	'                              ',
342	'                              ',
343	'                              ',);
344	
345	my $picture = SDL::Image::read_XPM_from_array(\@XPM, 30);
346
347=head1 MISC METHODS
348
349=head2 linked_version
350
351Provides the version of linked sdl_image library.
352
353=head3 Return
354
355Returns a L<SDL::Version> object
356
357=head3 Example
358
359	my $version = SDL::Image::linked_version();
360	print $version->major.' '.$version->minor.' '.$version->patch;
361
362=head2 init
363
364B<For version SDL_image 1.2.10 and up>
365
366=head3 Flags
367
368bitwise OR'd set of image formats to support by loading a library now. The values you may OR together to pass in are: 
369
370=over
371
372=item IMG_INIT_JPG 
373
374=item IMG_INIT_PNG 
375
376=item IMG_INIT_TIF
377
378=back
379
380Initialize by loading support as indicated by the flags, or at least return success if support is already loaded. You may call this multiple times, 
381which will actually require you to call IMG_Quit just once to clean up. You may call this function with a 0 to retrieve whether support was built-in 
382or not loaded yet.
383
384B<Note>: to load JPG, PNG, and/or TIF images you can call IMG_Init with the right IMG_INIT_* flags OR'd together before you program gets busy, to 
385prevent a later hiccup while it loads the library, and to check that you do have the support that you need before you try and use it.
386
387B<Note>: No initialization is needed nor performed when using the SDL::Image::is_JPG, SDL::Image::is_PNG, and SDL::Image::is_TIF functions.
388
389B<Note>: this function does not always set the error string, so do not depend on SDL::Image::get_error being meaningful all the time.  
390
391=head3 Return
392
393A bitmask of all the currently inited image loaders.
394
395=head3 Example
396
397  use SDL::Image;
398  my $flags = IMG_INIT_JPG | IMG_INIT_PNG | IMG_INIT_JPG;
399  my $inited = SDL::Image::init($flags);
400
401=head2 quit
402
403B<For version SDL_image 1.2.10 and up>
404
405This function cleans up all dynamically loaded library handles, freeing memory. If support is required again it will be initialized again, either 
406by L<SDL::Image::init|SDL::Image/"init"> or loading an image with dynamic support required. You may call this function when 
407L<SDL::Image::load|SDL::Image/"load"> functions are no longer needed for the JPG, PNG, and TIF image formats. You only need to call this function 
408once, no matter how many times L<SDL::Image::init|SDL::Image/"init"> was called. 
409
410=head3 Example
411
412 use SDL::Image;
413 SDL::Image::init(IMG_INIT_JPG); #loads JPG support
414 SDL::Image::load("file.png"); #loads PNG support
415 SDL::Image::quit(); #unloads everything
416
417=head2 set_error
418
419Same as L<SDL::set_error|SDL/"set_error">
420
421=head2 get_error
422
423Same as L<SDL::get_error|SDL/"get_error">
424
425=head1 SEE ALSO
426
427L<SDL>, L<SDL::Surface>, L<SDL::Video>, L<SDL::RWOps>
428
429=head1 AUTHORS
430
431See L<SDL/AUTHORS>.
432
433=cut