[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="#CATEGORY">CATEGORY</a></li>
<li><a href="#SUPPORTED_FORMATS">SUPPORTED FORMATS </a></li>
<li><a href="#LOADING_METHODS">LOADING METHODS</a>
<ul><li><a href="#load">load</a>
<ul><li><a href="#Return">Return</a></li>
</ul>
</li>
<li><a href="#load_typed_rw">load_typed_rw</a>
<ul><li><a href="#Transparency">Transparency </a></li>
<li><a href="#Return-2">Return </a></li>
</ul>
</li>
<li><a href="#is_TYPE">is_[TYPE]</a>
<ul><li><a href="#Return-3">Return</a></li>
<li><a href="#Example">Example</a></li>
</ul>
</li>
<li><a href="#load_TYPE_rw">load_[TYPE]_rw</a>
<ul><li><a href="#Return-4">Return</a></li>
<li><a href="#Example-2">Example</a></li>
</ul>
</li>
<li><a href="#read_XPM_from_array">read_XPM_from_array</a>
<ul><li><a href="#Return-5">Return</a></li>
<li><a href="#Example-3">Example</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#MISC_METHODS">MISC METHODS</a>
<ul><li><a href="#linked_version">linked_version</a>
<ul><li><a href="#Return-6">Return</a></li>
<li><a href="#Example-4">Example</a></li>
</ul>
</li>
<li><a href="#init">init</a>
<ul><li><a href="#Flags">Flags</a></li>
<li><a href="#Return-7">Return</a></li>
<li><a href="#Example-5">Example</a></li>
</ul>
</li>
<li><a href="#quit">quit</a>
<ul><li><a href="#Example-6">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>
<li><a href="#SEE_ALSO">SEE ALSO</a></li>
<li><a href="#AUTHORS">AUTHORS</a>
</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="CATEGORY">CATEGORY</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="CATEGORY_CONTENT">
<p>Image</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</dt>
	<dd>
		<p>TrueVision Targa (MUST have .tga) </p>
	</dd>
	<dt>BMP</dt>
	<dd>
		<p>Windows Bitmap(.bmp) </p>
	</dd>
	<dt>PNM</dt>
	<dd>
		<p>Portable Anymap (.pnm)
.pbm = Portable BitMap (mono)
.pgm = Portable GreyMap (256 greys)
.ppm = Portable PixMap (full color)</p>
	</dd>
	<dt>XPM</dt>
	<dd>
		<p>X11 Pixmap (.xpm) can be #included directly in code
This is NOT the same as XBM(X11 Bitmap) format, which is for monocolor images. </p>
	</dd>
	<dt>XCF</dt>
	<dd>
		<p>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. </p>
	</dd>
	<dt>PCX</dt>
	<dd>
		<p>ZSoft IBM PC Paintbrush (.pcx) </p>
	</dd>
	<dt>GIF</dt>
	<dd>
		<p>CompuServe Graphics Interchange Format (.gif) </p>
	</dd>
	<dt>JPG</dt>
	<dd>
		<p>Joint Photographic Experts Group JFIF format (.jpg or .jpeg) </p>
	</dd>
	<dt>TIF</dt>
	<dd>
		<p>Tagged Image File Format (.tif or .tiff) </p>
	</dd>
	<dt>LBM</dt>
	<dd>
		<p>Interleaved Bitmap (.lbm or .iff) FORM : ILBM or PBM(packed bitmap), HAM6, HAM8, and 24bit types are not supported. </p>
	</dd>
	<dt>PNG</dt>
	<dd>
		<p>Portable Network Graphics (.png) </p>
	</dd>
	<dt>XV</dt>
	<dt>ICO</dt>
	<dt>CUR</dt>
</dl>


</div>
<h1 id="LOADING_METHODS">LOADING METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="LOADING_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 <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.  </p>
<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 
<a href="/SDL-Image.html#init">SDL::Image::init</a> to load support for your image format.</p>
<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 
the surface afterwards by calling:</p>
<p><a href="/SDL-Video.html#set_color_key">SDL::Video::set_color_key</a></p>
<pre>  my $image = SDL::Image::load( $some_png_file );
  SDL::Video::set_color_key($image, SDL_RLEACCEL, $image-&gt;format-&gt;colorkey);

</pre>

</div>
<h3 id="Return">Return</h3>
<div id="Return_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.html#get_error">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">
<pre>  SDL::Image::load_typed_rw($src, $freesrc, $type);

</pre>
<dl>
	<dt>src</dt>
	<dd>
		<p>The source <a href="SDL-RWops.html">SDL::RWops</a> as a pointer. The image is loaded from this. </p>
	</dd>
	<dt>freesrc</dt>
	<dd>
		<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>
	</dd>
	<dt>type</dt>
	<dd>
		<p>A string that indicates which format type to interpret the image as.</p>
		<p>Here is a list of the currently recognized strings (case is not important):</p>
		<p>
			<dl>
				<dt>&quot;BMP&quot;</dt>
				<dt>&quot;CUR&quot;</dt>
				<dt>&quot;GIF&quot;</dt>
				<dt>&quot;ICO&quot;</dt>
				<dt>&quot;JPG&quot;</dt>
				<dt>&quot;LBM&quot;</dt>
				<dt>&quot;PCX&quot;</dt>
				<dt>&quot;PNG&quot;</dt>
				<dt>&quot;PNM&quot;</dt>
				<dt>&quot;TGA&quot;</dt>
				<dt>&quot;TIF&quot;</dt>
				<dt>&quot;XCF&quot;</dt>
				<dt>&quot;XPM&quot;</dt>
				<dt>&quot;XV&quot;</dt>
			</dl>
		</p>
	</dd>
</dl>
<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.</p>
<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 
<a href="/SDL-Image.html#init">SDL::Image::init</a> to load support for your image format.</p>
<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 
the surface afterwards by calling: <a href="/SDL-Video.html#set_color_key">SDL::Video::set_color_key</a></p>

</div>
<h3 id="Transparency">Transparency </h3>
<div id="Transparency_CONTENT">
<pre>  use SDL;
  use SDL::RWOps;
  use SDL::Image;

  my $file2 = SDL::RWOps-&gt;new_file(&quot;test/data/menu.png&quot;, &quot;rb&quot;);
  my $image = SDL::Image::load_typed_rw($file2, 1, &quot;PNG&quot;);

  SDL::Video::set_color_key($image, SDL_RLEACCEL, $image-&gt;format-&gt;colorkey);

</pre>

</div>
<h3 id="Return-2">Return </h3>
<div id="Return_CONTENT-2">
<p>The image as a new <a href="SDL-Surface.html">SDL::Surface</a>. NULL is returned on errors. </p>

</div>
<h2 id="is_TYPE">is_[TYPE]</h2>
<div id="is_TYPE_CONTENT">
<p>Test for valid, supported image files:</p>
<dl>
	<dt>is_ICO</dt>
	<dt>is_CUR</dt>
	<dt>is_PNG</dt>
	<dt>is_BMP</dt>
	<dt>is_GIF</dt>
	<dt>is_JPG</dt>
	<dt>is_LBM</dt>
	<dt>is_PCX</dt>
	<dt>is_PNM </dt>
	<dt>is_TIF</dt>
	<dt>is_XCF</dt>
	<dt>is_XPM</dt>
	<dt>is_XV</dt>
</dl>
<p>These functions take a <a href="SDL-RWOps.html">SDL::RWOps</a> as a parameter.</p>

</div>
<h3 id="Return-3">Return</h3>
<div id="Return_CONTENT-3">
<p>1 if the image is a valid [TYPE]  and the [TYPE] format support is compiled into SDL_image. 0 is returned otherwise. </p>

</div>
<h3 id="Example">Example</h3>
<div id="Example_CONTENT">
<pre> use SDL::RWOps;
 use SDL::Image;

 my $file = SDL::RWOps-&gt;new_file(&quot;file&quot;, &quot;rb&quot;);

 print &quot;Image is BMP&quot; if ( SDL::is_BMP );

</pre>

</div>
<h2 id="load_TYPE_rw">load_[TYPE]_rw</h2>
<div id="load_TYPE_rw_CONTENT">
<p>Specific loader for known formats:</p>
<dl>
	<dt>load_ICO_rw</dt>
	<dt>load_CUR_rw</dt>
	<dt>load_PNG_rw</dt>
	<dt>load_BMP_rw</dt>
	<dt>load_GIF_rw</dt>
	<dt>load_JPG_rw</dt>
	<dt>load_LBM_rw</dt>
	<dt>load_PCX_rw</dt>
	<dt>load_PNM_rw </dt>
	<dt>load_TIF_rw</dt>
	<dt>load_XCF_rw</dt>
	<dt>load_XPM_rw</dt>
	<dt>load_XV_rw</dt>
</dl>
<p>These functions take a <a href="SDL-RWop.html">SDL::RWop</a> as a parameter</p>

</div>
<h3 id="Return-4">Return</h3>
<div id="Return_CONTENT-4">
<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>

</div>
<h3 id="Example-2">Example</h3>
<div id="Example_CONTENT-2">
<pre> use SDL;
 use SDL::RWOps;
 use SDL::Image;

 my $file = SDL::RWOps-&gt;new_file(&quot;file.png&quot;, &quot;rb&quot;);  

 my $image = SDL::Image::load_PNG_rw($file);

 die SDL::get_error if (!$image);  

</pre>

</div>
<h2 id="read_XPM_from_array">read_XPM_from_array</h2>
<div id="read_XPM_from_array_CONTENT">
<pre> my $picture = SDL::Image::read_XPM_from_array(\@XPM, $width);

</pre>
<p>This functions takes the reference of an array in the valid @XPM format. Also the $width of the XPM image.</p>

</div>
<h3 id="Return-5">Return</h3>
<div id="Return_CONTENT-5">
<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>

</div>
<h3 id="Example-3">Example</h3>
<div id="Example_CONTENT-3">
<pre>	my @XPM= (
	'30 30 9 1',
	' 	c #FFFFFF',
	'.	c #EFEFEF',
	'+	c #CFCFCF',
	'@	c #9F9F9F',
	'#	c #808080',
	'$	c #505050',
	'%	c #202020',
	'&amp;	c #000000',
	'*	c #303030',
	'                              ',
	'                              ',
	'                              ',
	'                              ',
	'                              ',
	'                              ',
	'                              ',
	'                              ',
	'                              ',
	'           .+@##@+.           ',
	'          .@$%&amp;&amp;%$@.          ',
	'         .@*&amp;&amp;&amp;&amp;&amp;&amp;*@.         ',
	'         +$&amp;&amp;&amp;&amp;&amp;&amp;&amp;&amp;$+         ',
	'         @%&amp;&amp;&amp;&amp;&amp;&amp;&amp;&amp;%@         ',
	'         #&amp;&amp;&amp;&amp;&amp;&amp;&amp;&amp;&amp;&amp;#         ',
	'         #&amp;&amp;&amp;&amp;&amp;&amp;&amp;&amp;&amp;&amp;#         ',
	'         @%&amp;&amp;&amp;&amp;&amp;&amp;&amp;&amp;%@         ',
	'         +$&amp;&amp;&amp;&amp;&amp;&amp;&amp;&amp;$+         ',
	'         .@*&amp;&amp;&amp;&amp;&amp;&amp;*@.         ',
	'          .@$%&amp;&amp;%$@.          ',
	'           .+@##@+.           ',
	'                              ',
	'                              ',
	'                              ',
	'                              ',
	'                              ',
	'                              ',
	'                              ',
	'                              ',
	'                              ',);

	my $picture = SDL::Image::read_XPM_from_array(\@XPM, 30);

</pre>

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

</div>
<h2 id="linked_version">linked_version</h2>
<div id="linked_version_CONTENT">
<p>Provides the version of linked sdl_image library.</p>

</div>
<h3 id="Return-6">Return</h3>
<div id="Return_CONTENT-6">
<p>Returns a <a href="SDL-Version.html">SDL::Version</a> object</p>

</div>
<h3 id="Example-4">Example</h3>
<div id="Example_CONTENT-4">
<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 </dt>
	<dt>IMG_INIT_PNG </dt>
	<dt>IMG_INIT_TIF</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.</p>
<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 
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>
<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>
<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>

</div>
<h3 id="Return-7">Return</h3>
<div id="Return_CONTENT-7">
<p>A bitmask of all the currently inited image loaders.</p>

</div>
<h3 id="Example-5">Example</h3>
<div id="Example_CONTENT-5">
<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="quit">quit</h2>
<div id="quit_CONTENT">
<p><strong>For version SDL_image 1.2.10 and up</strong></p>
<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>

</div>
<h3 id="Example-6">Example</h3>
<div id="Example_CONTENT-6">
<pre> use SDL::Image;
 SDL::Image::init(IMG_INIT_JPG); #loads JPG support
 SDL::Image::load(&quot;file.png&quot;); #loads PNG support
 SDL::Image::quit(); #unloads everything

</pre>

</div>
<h2 id="set_error">set_error</h2>
<div id="set_error_CONTENT">
<p>Same as <a href="/SDL.html#set_error">SDL::set_error</a></p>

</div>
<h2 id="get_error">get_error</h2>
<div id="get_error_CONTENT">
<p>Same as <a href="/SDL.html#get_error">SDL::get_error</a></p>

</div>
<h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="SEE_ALSO_CONTENT">
<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>

</div>
<h1 id="AUTHORS">AUTHORS</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="AUTHORS_CONTENT">
<p>See <a href="/SDL.html#AUTHORS">/SDL.html#AUTHORS</a>.</p>

</div>
</div>
Commit	Line	Data
944366c3	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>
944366c3	7	<li><a href="#CATEGORY">CATEGORY</a></li>
5241ab5e	8	<li><a href="#SUPPORTED_FORMATS">SUPPORTED FORMATS </a></li>
5241ab5e	9	<li><a href="#LOADING_METHODS">LOADING METHODS</a>
4e9f9db6	10	<ul><li><a href="#load">load</a>
	11	<ul><li><a href="#Return">Return</a></li>
	12	</ul>
	13	</li>
5241ab5e	14	<li><a href="#load_typed_rw">load_typed_rw</a>
001e1287	15	<ul><li><a href="#Transparency">Transparency </a></li>
4e9f9db6	16	<li><a href="#Return-2">Return </a></li>
5241ab5e	17	</ul>
	18	</li>
	19	<li><a href="#is_TYPE">is_[TYPE]</a>
4e9f9db6	20	<ul><li><a href="#Return-3">Return</a></li>
001e1287	21	<li><a href="#Example">Example</a></li>
5241ab5e	22	</ul>
	23	</li>
	24	<li><a href="#load_TYPE_rw">load_[TYPE]_rw</a>
4e9f9db6	25	<ul><li><a href="#Return-4">Return</a></li>
001e1287	26	<li><a href="#Example-2">Example</a></li>
5241ab5e	27	</ul>
	28	</li>
	29	<li><a href="#read_XPM_from_array">read_XPM_from_array</a>
4e9f9db6	30	<ul><li><a href="#Return-5">Return</a></li>
001e1287	31	<li><a href="#Example-3">Example</a></li>
5241ab5e	32	</ul>
	33	</li>
	34	</ul>
	35	</li>
	36	<li><a href="#MISC_METHODS">MISC METHODS</a>
4e9f9db6	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>
944366c3	42	<li><a href="#init">init</a>
944366c3	43	<ul><li><a href="#Flags">Flags</a></li>
4e9f9db6	44	<li><a href="#Return-7">Return</a></li>
4e9f9db6	45	<li><a href="#Example-5">Example</a></li>
001e1287	46	</ul>
	47	</li>
	48	<li><a href="#quit">quit</a>
4e9f9db6	49	<ul><li><a href="#Example-6">Example</a></li>
944366c3	50	</ul>
	51	</li>
	52	<li><a href="#set_error">set_error</a></li>
37dfe383	53	<li><a href="#get_error">get_error</a></li>
944366c3	54	</ul>
944366c3	55	</li>
c7e8d3c6	56	<li><a href="#SEE_ALSO">SEE ALSO</a></li>
c7e8d3c6	57	<li><a href="#AUTHORS">AUTHORS</a>
37dfe383	58	</li>
944366c3	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>
5241ab5e	72	<h1 id="CATEGORY">CATEGORY</h1><p><a href="#TOP" class="toplink">Top</a></p>
5241ab5e	73	<div id="CATEGORY_CONTENT">
2672acfc	74	<p>Image</p>
5241ab5e	75
5241ab5e	76	</div>
944366c3	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>
37dfe383	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?)
1dbe1697	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
1dbe1697	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>
37dfe383	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>
1dbe1697	125	<p>Interleaved Bitmap (.lbm or .iff) FORM : ILBM or PBM(packed bitmap), HAM6, HAM8, and 24bit types are not supported. </p>
37dfe383	126	</dd>
	127	<dt>PNG</dt>
	128	<dd>
	129	<p>Portable Network Graphics (.png) </p>
	130	</dd>
	131	<dt>XV</dt>
5241ab5e	132	<dt>ICO</dt>
5241ab5e	133	<dt>CUR</dt>
944366c3	134	</dl>
944366c3	135
5241ab5e	136
	137
	138
944366c3	139
944366c3	140	</div>
5241ab5e	141	<h1 id="LOADING_METHODS">LOADING METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p>
5241ab5e	142	<div id="LOADING_METHODS_CONTENT">
944366c3	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>
1dbe1697	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 ".tga". 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>
37dfe383	160	<pre> my $image = SDL::Image::load( $some_png_file );
37dfe383	161	SDL::Video::set_color_key($image, SDL_RLEACCEL, $image->format->colorkey);
944366c3	162
37dfe383	163	</pre>
944366c3	164
944366c3	165	</div>
4e9f9db6	166	<h3 id="Return">Return</h3>
4e9f9db6	167	<div id="Return_CONTENT">
1dbe1697	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
1dbe1697	169	<a href="/SDL.html#get_error">SDL::get_error</a> to get cause of error.</p>
944366c3	170
	171	</div>
	172	<h2 id="load_typed_rw">load_typed_rw</h2>
	173	<div id="load_typed_rw_CONTENT">
5241ab5e	174	<pre> SDL::Image::load_typed_rw($src, $freesrc, $type);
	175
	176	</pre>
	177	<dl>
	178	<dt>src</dt>
	179	<dd>
55bbf7a2	180	<p>The source <a href="SDL-RWops.html">SDL::RWops</a> as a pointer. The image is loaded from this. </p>
5241ab5e	181	</dd>
	182	<dt>freesrc</dt>
	183	<dd>
1dbe1697	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
1dbe1697	185	likely want 1 here.</p>
5241ab5e	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>"BMP"</dt>
	194	<dt>"CUR"</dt>
	195	<dt>"GIF"</dt>
	196	<dt>"ICO"</dt>
	197	<dt>"JPG"</dt>
	198	<dt>"LBM"</dt>
	199	<dt>"PCX"</dt>
	200	<dt>"PNG"</dt>
	201	<dt>"PNM"</dt>
	202	<dt>"TGA"</dt>
	203	<dt>"TIF"</dt>
	204	<dt>"XCF"</dt>
	205	<dt>"XPM"</dt>
	206	<dt>"XV"</dt>
	207	</dl>
	208	</p>
	209	</dd>
	210	</dl>
1dbe1697	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>
001e1287	218
	219	</div>
	220	<h3 id="Transparency">Transparency </h3>
	221	<div id="Transparency_CONTENT">
5241ab5e	222	<pre> use SDL;
	223	use SDL::RWOps;
	224	use SDL::Image;
	225
	226	my $file2 = SDL::RWOps->new_file("test/data/menu.png", "rb");
	227	my $image = SDL::Image::load_typed_rw($file2, 1, "PNG");
	228
	229	SDL::Video::set_color_key($image, SDL_RLEACCEL, $image->format->colorkey);
	230
	231	</pre>
	232
	233	</div>
4e9f9db6	234	<h3 id="Return-2">Return </h3>
4e9f9db6	235	<div id="Return_CONTENT-2">
55bbf7a2	236	<p>The image as a new <a href="SDL-Surface.html">SDL::Surface</a>. NULL is returned on errors. </p>
944366c3	237
	238	</div>
	239	<h2 id="is_TYPE">is_[TYPE]</h2>
	240	<div id="is_TYPE_CONTENT">
5241ab5e	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>
55bbf7a2	257	<p>These functions take a <a href="SDL-RWOps.html">SDL::RWOps</a> as a parameter.</p>
001e1287	258
001e1287	259	</div>
4e9f9db6	260	<h3 id="Return-3">Return</h3>
4e9f9db6	261	<div id="Return_CONTENT-3">
001e1287	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">
5241ab5e	267	<pre> use SDL::RWOps;
	268	use SDL::Image;
	269
	270	my $file = SDL::RWOps->new_file("file", "rb");
	271
	272	print "Image is BMP" if ( SDL::is_BMP );
	273
5241ab5e	274	</pre>
	275
	276	</div>
944366c3	277	<h2 id="load_TYPE_rw">load_[TYPE]_rw</h2>
944366c3	278	<div id="load_TYPE_rw_CONTENT">
5241ab5e	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>
55bbf7a2	295	<p>These functions take a <a href="SDL-RWop.html">SDL::RWop</a> as a parameter</p>
5241ab5e	296
5241ab5e	297	</div>
4e9f9db6	298	<h3 id="Return-4">Return</h3>
4e9f9db6	299	<div id="Return_CONTENT-4">
55bbf7a2	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>
5241ab5e	301
5241ab5e	302	</div>
001e1287	303	<h3 id="Example-2">Example</h3>
001e1287	304	<div id="Example_CONTENT-2">
5241ab5e	305	<pre> use SDL;
	306	use SDL::RWOps;
	307	use SDL::Image;
	308
	309	my $file = SDL::RWOps->new_file("file.png", "rb");
	310
	311	my $image = SDL::Image::load_PNG_rw($file);
	312
	313	die SDL::get_error if (!$image);
	314
	315	</pre>
944366c3	316
	317	</div>
	318	<h2 id="read_XPM_from_array">read_XPM_from_array</h2>
	319	<div id="read_XPM_from_array_CONTENT">
5241ab5e	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>
4e9f9db6	326	<h3 id="Return-5">Return</h3>
4e9f9db6	327	<div id="Return_CONTENT-5">
55bbf7a2	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>
5241ab5e	329
5241ab5e	330	</div>
001e1287	331	<h3 id="Example-3">Example</h3>
001e1287	332	<div id="Example_CONTENT-3">
5241ab5e	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	'& c #000000',
	343	'* c #303030',
	344	' ',
	345	' ',
	346	' ',
	347	' ',
	348	' ',
	349	' ',
	350	' ',
	351	' ',
	352	' ',
	353	' .+@##@+. ',
	354	' .@$%&&%$@. ',
	355	' .@&&&&&&@. ',
	356	' +$&&&&&&&&$+ ',
	357	' @%&&&&&&&&%@ ',
	358	' #&&&&&&&&&&# ',
	359	' #&&&&&&&&&&# ',
	360	' @%&&&&&&&&%@ ',
	361	' +$&&&&&&&&$+ ',
	362	' .@&&&&&&@. ',
	363	' .@$%&&%$@. ',
	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">
944366c3	382
	383	</div>
	384	<h2 id="linked_version">linked_version</h2>
	385	<div id="linked_version_CONTENT">
4e9f9db6	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">
55bbf7a2	391	<p>Returns a <a href="SDL-Version.html">SDL::Version</a> object</p>
4e9f9db6	392
	393	</div>
	394	<h3 id="Example-4">Example</h3>
	395	<div id="Example_CONTENT-4">
944366c3	396	<pre> my $version = SDL::Image::linked_version();
	397	print $version->major.' '.$version->minor.' '.$version->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
944366c3	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>
37dfe383	411	<dt>IMG_INIT_JPG </dt>
	412	<dt>IMG_INIT_PNG </dt>
	413	<dt>IMG_INIT_TIF</dt>
944366c3	414	</dl>
1dbe1697	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>
944366c3	422
944366c3	423	</div>
4e9f9db6	424	<h3 id="Return-7">Return</h3>
4e9f9db6	425	<div id="Return_CONTENT-7">
5241ab5e	426	<p>A bitmask of all the currently inited image loaders.</p>
944366c3	427
944366c3	428	</div>
4e9f9db6	429	<h3 id="Example-5">Example</h3>
4e9f9db6	430	<div id="Example_CONTENT-5">
944366c3	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
944366c3	435	</pre>
	436
	437	</div>
5241ab5e	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>
1dbe1697	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>
001e1287	445
001e1287	446	</div>
4e9f9db6	447	<h3 id="Example-6">Example</h3>
4e9f9db6	448	<div id="Example_CONTENT-6">
5241ab5e	449	<pre> use SDL::Image;
	450	SDL::Image::init(IMG_INIT_JPG); #loads JPG support
	451	SDL::Image::load("file.png"); #loads PNG support
	452	SDL::Image::quit(); #unloads everything
	453
	454	</pre>
	455
	456	</div>
944366c3	457	<h2 id="set_error">set_error</h2>
944366c3	458	<div id="set_error_CONTENT">
1dbe1697	459	<p>Same as <a href="/SDL.html#set_error">SDL::set_error</a></p>
944366c3	460
	461	</div>
	462	<h2 id="get_error">get_error</h2>
	463	<div id="get_error_CONTENT">
1dbe1697	464	<p>Same as <a href="/SDL.html#get_error">SDL::get_error</a></p>
944366c3	465
944366c3	466	</div>
37dfe383	467	<h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p>
37dfe383	468	<div id="SEE_ALSO_CONTENT">
55bbf7a2	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>
37dfe383	470
37dfe383	471	</div>
c7e8d3c6	472	<h1 id="AUTHORS">AUTHORS</h1><p><a href="#TOP" class="toplink">Top</a></p>
c7e8d3c6	473	<div id="AUTHORS_CONTENT">
1dbe1697	474	<p>See <a href="/SDL.html#AUTHORS">/SDL.html#AUTHORS</a>.</p>
c7e8d3c6	475
c7e8d3c6	476	</div>
944366c3	477	</div>