SDL::Image(3pm)

1SDL::Image(3)         User Contributed Perl Documentation        SDL::Image(3)
2
3
4

NAME

6       SDL::Image - Bindings for the SDL_Image library
7

DESCRIPTION

9       SDL::Image allows you to load many different format of images into
10       memory as an SDL::Surface.
11

SUPPORTED FORMATS

16       The following types are supported:
17
18       TGA TrueVision Targa (MUST have .tga)
19
20       BMP Windows Bitmap(.bmp)
21
22       PNM Portable Anymap (.pnm) .pbm = Portable BitMap (mono) .pgm =
23           Portable GreyMap (256 greys) .ppm = Portable PixMap (full color)
24
25       XPM X11 Pixmap (.xpm) can be #included directly in code This is NOT the
26           same as XBM(X11 Bitmap) format, which is for monocolor images.
27
28       XCF GIMP native (.xcf) (XCF = eXperimental Computing Facility?)  This
29           format is always changing, and since there's no library supplied by
30           the GIMP project to load XCF, the loader may frequently fail to
31           load much of any image from an XCF file. It's better to load this
32           in GIMP and convert to a better supported image format.
33
34       PCX ZSoft IBM PC Paintbrush (.pcx)
35
36       GIF CompuServe Graphics Interchange Format (.gif)
37
38       JPG Joint Photographic Experts Group JFIF format (.jpg or .jpeg)
39
40       TIF Tagged Image File Format (.tif or .tiff)
41
42       LBM Interleaved Bitmap (.lbm or .iff) FORM : ILBM or PBM(packed
43           bitmap), HAM6, HAM8, and 24bit types are not supported.
44
45       PNG Portable Network Graphics (.png)
46
47       XV
48       ICO
49       CUR
50

LOADING METHODS

52   load
53        my $surface = SDL::Image::load( $file );
54
55       $file Image file name to load a surface from.
56
57       Load file for use as an image in a new SDL::Surface. This actually
58       calls SDL::Image::load_typed_rw, with the file extension used as the
59       type string. This can load all supported image files, including TGA as
60       long as the filename ends with ".tga". It is best to call this outside
61       of event loops, and rather keep the loaded images around until you are
62       really done with them, as disk speed and image conversion to a surface
63       is not that speedy.
64
65       Note: If the image format loader requires initialization, it will
66       attempt to do that the first time it is needed if you have not already
67       called SDL::Image::init to load support for your image format.
68
69       Note: If the image format supports a transparent pixel, SDL::Image will
70       set the colorkey for the surface. You can enable RLE acceleration on
71       the surface afterwards by calling:
72
73       SDL::Video::set_color_key
74
75         my $image = SDL::Image::load( $some_png_file );
76         SDL::Video::set_color_key($image, SDL_RLEACCEL, $image->format->colorkey);
77
78       Return
79
80       An image as a SDL::Surface. NULL is returned on errors, such as no
81       support built for the image, or a file reading error. Use
82       SDL::get_error to get cause of error.
83
84   load_typed_rw
85         SDL::Image::load_typed_rw($src, $freesrc, $type);
86
87       src The source SDL::RWops as a pointer. The image is loaded from this.
88
89       freesrc
90           A non-zero value mean is will automatically close/free the src for
91           you. Since SDL Perl cannot handle the memory inside this function
92           you would most likely want 1 here.
93
94       type
95           A string that indicates which format type to interpret the image
96           as.
97
98           Here is a list of the currently recognized strings (case is not
99           important):
100
101           "BMP"
102           "CUR"
103           "GIF"
104           "ICO"
105           "JPG"
106           "LBM"
107           "PCX"
108           "PNG"
109           "PNM"
110           "TGA"
111           "TIF"
112           "XCF"
113           "XPM"
114           "XV"
115
116       Load src for use as a surface. This can load all supported image
117       formats. This method does not guarantee that the format specified by
118       type is the format of the loaded image, except in the case when TGA
119       format is specified (or any other non-magicable format in the future).
120       Using SDL_RWops is not covered here, but they enable you to load from
121       almost any source.
122
123       Note: If the image format loader requires initialization, it will
124       attempt to do that the first time it is needed if you have not already
125       called SDL::Image::init to load support for your image format.
126
127       Note: If the image format supports a transparent pixel, SDL::Image will
128       set the colorkey for the surface. You can enable RLE acceleration on
129       the surface afterwards by calling: SDL::Video::set_color_key
130
131       Transparency
132
133         use SDL;
134         use SDL::RWOps;
135         use SDL::Image;
136
137         my $file2 = SDL::RWOps->new_file("test/data/menu.png", "rb");
138         my $image = SDL::Image::load_typed_rw($file2, 1, "PNG");
139
140         SDL::Video::set_color_key($image, SDL_RLEACCEL, $image->format->colorkey);
141
142       Return
143
144       The image as a new SDL::Surface. NULL is returned on errors.
145
146   is_[TYPE]
147       Test for valid, supported image files:
148
149       is_ICO
150       is_CUR
151       is_PNG
152       is_BMP
153       is_GIF
154       is_JPG
155       is_LBM
156       is_PCX
157       is_PNM
158       is_TIF
159       is_XCF
160       is_XPM
161       is_XV
162
163       These functions take a SDL::RWOps as a parameter.
164
165       Return
166
167       1 if the image is a valid [TYPE]  and the [TYPE] format support is
168       compiled into SDL_image. 0 is returned otherwise.
169
170       Example
171
172        use SDL::RWOps;
173        use SDL::Image;
174
175        my $file = SDL::RWOps->new_file("file", "rb");
176
177        print "Image is BMP" if ( SDL::is_BMP );
178
179   load_[TYPE]_rw
180       Specific loader for known formats:
181
182       load_ICO_rw
183       load_CUR_rw
184       load_PNG_rw
185       load_BMP_rw
186       load_GIF_rw
187       load_JPG_rw
188       load_LBM_rw
189       load_PCX_rw
190       load_PNM_rw
191       load_TIF_rw
192       load_XCF_rw
193       load_XPM_rw
194       load_XV_rw
195
196       These functions take a SDL::RWop as a parameter
197
198       Return
199
200       The image as a new SDL::Surface. NULL is returned on errors, like if
201       the [TYPE] is not supported, or a read error.
202
203       Example
204
205        use SDL;
206        use SDL::RWOps;
207        use SDL::Image;
208
209        my $file = SDL::RWOps->new_file("file.png", "rb");
210
211        my $image = SDL::Image::load_PNG_rw($file);
212
213        die SDL::get_error if (!$image);
214
215   read_XPM_from_array
216        my $picture = SDL::Image::read_XPM_from_array(\@XPM, $width);
217
218       This functions takes the reference of an array in the valid @XPM
219       format. Also the $width of the XPM image.
220
221       Return
222
223       The image as a new SDL::Surface. NULL is returned on errors, like if
224       XPM is not supported, or a read error.
225
226       Example
227
228               my @XPM= (
229               '30 30 9 1',
230               '       c #FFFFFF',
231               '.      c #EFEFEF',
232               '+      c #CFCFCF',
233               '@      c #9F9F9F',
234               '#      c #808080',
235               '$      c #505050',
236               '%      c #202020',
237               '&      c #000000',
238               '*      c #303030',
239               '                              ',
240               '                              ',
241               '                              ',
242               '                              ',
243               '                              ',
244               '                              ',
245               '                              ',
246               '                              ',
247               '                              ',
248               '           .+@##@+.           ',
249               '          .@$%&&%$@.          ',
250               '         .@*&&&&&&*@.         ',
251               '         +$&&&&&&&&$+         ',
252               '         @%&&&&&&&&%@         ',
253               '         #&&&&&&&&&&#         ',
254               '         #&&&&&&&&&&#         ',
255               '         @%&&&&&&&&%@         ',
256               '         +$&&&&&&&&$+         ',
257               '         .@*&&&&&&*@.         ',
258               '          .@$%&&%$@.          ',
259               '           .+@##@+.           ',
260               '                              ',
261               '                              ',
262               '                              ',
263               '                              ',
264               '                              ',
265               '                              ',
266               '                              ',
267               '                              ',
268               '                              ',);
269
270               my $picture = SDL::Image::read_XPM_from_array(\@XPM, 30);
271

MISC METHODS

273   linked_version
274       Provides the version of linked sdl_image library.
275
276       Return
277
278       Returns a SDL::Version object
279
280       Example
281
282               my $version = SDL::Image::linked_version();
283               print $version->major.' '.$version->minor.' '.$version->patch;
284
285   init
286       For version SDL_image 1.2.10 and up
287
288       Flags
289
290       bitwise OR'd set of image formats to support by loading a library now.
291       The values you may OR together to pass in are:
292
293       IMG_INIT_JPG
294       IMG_INIT_PNG
295       IMG_INIT_TIF
296
297       Initialize by loading support as indicated by the flags, or at least
298       return success if support is already loaded. You may call this multiple
299       times, which will actually require you to call IMG_Quit just once to
300       clean up. You may call this function with a 0 to retrieve whether
301       support was built-in or not loaded yet.
302
303       Note: to load JPG, PNG, and/or TIF images you can call IMG_Init with
304       the right IMG_INIT_* flags OR'd together before you program gets busy,
305       to prevent a later hiccup while it loads the library, and to check that
306       you do have the support that you need before you try and use it.
307
308       Note: No initialization is needed nor performed when using the
309       SDL::Image::is_JPG, SDL::Image::is_PNG, and SDL::Image::is_TIF
310       functions.
311
312       Note: this function does not always set the error string, so do not
313       depend on SDL::Image::get_error being meaningful all the time.
314
315       Return
316
317       A bitmask of all the currently inited image loaders.
318
319       Example
320
321         use SDL::Image;
322         my $flags = IMG_INIT_JPG | IMG_INIT_PNG | IMG_INIT_JPG;
323         my $inited = SDL::Image::init($flags);
324
325   quit
326       For version SDL_image 1.2.10 and up
327
328       This function cleans up all dynamically loaded library handles, freeing
329       memory. If support is required again it will be initialized again,
330       either by SDL::Image::init or loading an image with dynamic support
331       required. You may call this function when SDL::Image::load functions
332       are no longer needed for the JPG, PNG, and TIF image formats. You only
333       need to call this function once, no matter how many times
334       SDL::Image::init was called.
335
336       Example
337
338        use SDL::Image;
339        SDL::Image::init(IMG_INIT_JPG); #loads JPG support
340        SDL::Image::load("file.png"); #loads PNG support
341        SDL::Image::quit(); #unloads everything
342
343   set_error
344       Same as SDL::set_error
345
346   get_error
347       Same as SDL::get_error
348

AUTHORS

353       See "AUTHORS" in SDL.
354
355
356
357perl v5.36.0                      2023-03-10                     SDL::Image(3)

NAME

DESCRIPTION

CATEGORY

SUPPORTED FORMATS

LOADING METHODS

MISC METHODS

SEE ALSO

AUTHORS