pages/SDL-Image.html-inc

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