Added Image docs

[sdlgit/SDL-Site.git] / pages / SDL-Image.html-inc

<div class="pod">
<!-- INDEX START -->
<h3 id="TOP">Index</h3>

<ul><li><a href="#NAME">NAME</a></li>
<li><a href="#DESCRIPTION">DESCRIPTION</a></li>
<li><a href="#SUPPORTED_FORMATS">SUPPORTED FORMATS </a></li>
<li><a href="#CATEGORY">CATEGORY</a></li>
<li><a href="#METHODS">METHODS</a>
<ul><li><a href="#load">load</a></li>
<li><a href="#Returns">Returns</a></li>
<li><a href="#load_typed_rw">load_typed_rw</a></li>
<li><a href="#is_TYPE">is_[TYPE]</a></li>
<li><a href="#load_TYPE_rw">load_[TYPE]_rw</a></li>
<li><a href="#read_XPM_from_array">read_XPM_from_array</a></li>
<li><a href="#linked_version">linked_version</a></li>
<li><a href="#init">init</a>
<ul><li><a href="#Flags">Flags</a></li>
<li><a href="#Return">Return</a></li>
<li><a href="#Example">Example</a></li>
</ul>
</li>
<li><a href="#set_error">set_error</a></li>
<li><a href="#get_error">get_error</a>
</li>
</ul>
</li>
</ul><hr />
<!-- INDEX END -->

<h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="NAME_CONTENT">
<p>SDL::Image - Bindings for the SDL_Image library</p>

</div>
<h1 id="DESCRIPTION">DESCRIPTION</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="DESCRIPTION_CONTENT">
<p>SDL::Image allows you to load many different format of images into memory as an SDL::Surface.</p>

</div>
<h1 id="SUPPORTED_FORMATS">SUPPORTED FORMATS </h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="SUPPORTED_FORMATS_CONTENT">
<p>The following types are supported:</p>
<dl>
	<dt>*
TGA
    TrueVision Targa (MUST have .tga) </dt>
	<dt>* 
BMP
    Windows Bitmap(.bmp) </dt>
	<dt>*
PNM
    Portable Anymap (.pnm)
    .pbm = Portable BitMap (mono)
    .pgm = Portable GreyMap (256 greys)
    .ppm = Portable PixMap (full color)</dt>
	<dt>* 
XPM
    X11 Pixmap (.xpm) can be #included directly in code
    This is NOT the same as XBM(X11 Bitmap) format, which is for monocolor images. </dt>
	<dt>* 
XCF
    GIMP native (.xcf) (XCF = eXperimental Computing Facility?)
    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. </dt>
	<dt>* 
PCX
    ZSoft IBM PC Paintbrush (.pcx) </dt>
	<dt>*
GIF
    CompuServe Graphics Interchange Format (.gif) </dt>
	<dt>*
JPG
    Joint Photographic Experts Group JFIF format (.jpg or .jpeg) </dt>
	<dt>* 
TIF
    Tagged Image File Format (.tif or .tiff) </dt>
	<dt>*
LBM
    Interleaved Bitmap (.lbm or .iff) FORM : ILBM or PBM(packed bitmap)
    HAM6, HAM8, and 24bit types are not supported. </dt>
	<dt>*
PNG
    Portable Network Graphics (.png) =item *</dt>
	<dt>* 
XV
     ???</dt>
</dl>

</div>
<h1 id="CATEGORY">CATEGORY</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="CATEGORY_CONTENT">
<p>TODO, SDL, Image</p>

</div>
<h1 id="METHODS">METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="METHODS_CONTENT">

</div>
<h2 id="load">load</h2>
<div id="load_CONTENT">
<pre> my $surface = SDL::Image::load( $file );

</pre>
<p>$file Image file name to load a surface from. </p>
<p>Load file for use as an image in a new <a href="/SDL-Surface.html">SDL::Surface</a>. This actually calls <code>IMG_LoadTyped_RW</code> the binded function to <a href="/SDL-Image::load_typed_rw.html">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.  
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 IMG_Init to load support for your image format.
Note: If the image format supports a transparent pixel, SDL_image will set the colorkey for the surface. You can enable RLE acceleration on the surface afterwards by calling:
SDL::Video::set_color_key($image, SDL_RLEACCEL, $image-&gt;format-&gt;colorkey);</p>





</div>
<h2 id="Returns">Returns</h2>
<div id="Returns_CONTENT">
<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 <a href="/SDL-get_error.html">SDL::get_error</a> to get cause of error.</p>

</div>
<h2 id="load_typed_rw">load_typed_rw</h2>
<div id="load_typed_rw_CONTENT">

</div>
<h2 id="is_TYPE">is_[TYPE]</h2>
<div id="is_TYPE_CONTENT">

</div>
<h2 id="load_TYPE_rw">load_[TYPE]_rw</h2>
<div id="load_TYPE_rw_CONTENT">

</div>
<h2 id="read_XPM_from_array">read_XPM_from_array</h2>
<div id="read_XPM_from_array_CONTENT">

</div>
<h2 id="linked_version">linked_version</h2>
<div id="linked_version_CONTENT">
<p>Provides the version of linked sdl_image library. see <a href="/SDL-Version.html">SDL::Version</a></p>
<pre>	my $version = SDL::Image::linked_version();
	print $version-&gt;major.' '.$version-&gt;minor.' '.$version-&gt;patch;

</pre>

</div>
<h2 id="init">init</h2>
<div id="init_CONTENT">
<p><strong>For version SDL_image 1.2.10 and up</strong></p>








</div>
<h3 id="Flags">Flags</h3>
<div id="Flags_CONTENT">
<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>
<dl>
	<dt>*
 IMG_INIT_JPG = 0x00000001</dt>
	<dt>*
 IMG_INIT_PNG = 0x00000002</dt>
	<dt>*
 IMG_INIT_TIF = 0x00000004  </dt>
</dl>
<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.
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.
Note: No initialization is needed nor performed when using the SDL::Image::is_JPG, SDL::Image::is_PNG, and SDL::Image::is_TIF functions.
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>

</div>
<h3 id="Return">Return</h3>
<div id="Return_CONTENT">
<p>A bitmask of all the currentl initted image loaders.</p>

</div>
<h3 id="Example">Example</h3>
<div id="Example_CONTENT">
<pre>  use SDL::Image;
  my $flags = IMG_INIT_JPG | IMG_INIT_PNG | IMG_INIT_JPG;
  my $inited = SDL::Image::init($flags);




</pre>

</div>
<h2 id="set_error">set_error</h2>
<div id="set_error_CONTENT">

</div>
<h2 id="get_error">get_error</h2>
<div id="get_error_CONTENT">

</div>
</div>