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