[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>
</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 <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.  
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.
Note: 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>
<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.
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.
Note: 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.
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-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>
</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>
37dfe383	56	<li><a href="#SEE_ALSO">SEE ALSO</a>
37dfe383	57	</li>
944366c3	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>
5241ab5e	71	<h1 id="CATEGORY">CATEGORY</h1><p><a href="#TOP" class="toplink">Top</a></p>
5241ab5e	72	<div id="CATEGORY_CONTENT">
2672acfc	73	<p>Image</p>
5241ab5e	74
5241ab5e	75	</div>
944366c3	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>
37dfe383	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>
5241ab5e	131	<dt>ICO</dt>
5241ab5e	132	<dt>CUR</dt>
944366c3	133	</dl>
944366c3	134
5241ab5e	135
	136
	137
944366c3	138
944366c3	139	</div>
5241ab5e	140	<h1 id="LOADING_METHODS">LOADING METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p>
5241ab5e	141	<div id="LOADING_METHODS_CONTENT">
944366c3	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>
55bbf7a2	150	<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.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 ".tga". 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.
92e293d6	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.
55bbf7a2	152	Note: 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:
92e293d6	153	<a href="/SDL-Video.html#set_color_key">SDL::Video::set_color_key</a></p>
37dfe383	154	<pre> my $image = SDL::Image::load( $some_png_file );
37dfe383	155	SDL::Video::set_color_key($image, SDL_RLEACCEL, $image->format->colorkey);
944366c3	156
37dfe383	157	</pre>
944366c3	158
944366c3	159	</div>
4e9f9db6	160	<h3 id="Return">Return</h3>
4e9f9db6	161	<div id="Return_CONTENT">
55bbf7a2	162	<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>
944366c3	163
	164	</div>
	165	<h2 id="load_typed_rw">load_typed_rw</h2>
	166	<div id="load_typed_rw_CONTENT">
5241ab5e	167	<pre> SDL::Image::load_typed_rw($src, $freesrc, $type);
	168
	169	</pre>
	170	<dl>
	171	<dt>src</dt>
	172	<dd>
55bbf7a2	173	<p>The source <a href="SDL-RWops.html">SDL::RWops</a> as a pointer. The image is loaded from this. </p>
5241ab5e	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>"BMP"</dt>
	186	<dt>"CUR"</dt>
	187	<dt>"GIF"</dt>
	188	<dt>"ICO"</dt>
	189	<dt>"JPG"</dt>
	190	<dt>"LBM"</dt>
	191	<dt>"PCX"</dt>
	192	<dt>"PNG"</dt>
	193	<dt>"PNM"</dt>
	194	<dt>"TGA"</dt>
	195	<dt>"TIF"</dt>
	196	<dt>"XCF"</dt>
	197	<dt>"XPM"</dt>
	198	<dt>"XV"</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.
92e293d6	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.
55bbf7a2	205	Note: 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:
92e293d6	206	<a href="/SDL-Video.html#set_color_key">SDL::Video::set_color_key</a></p>
001e1287	207
	208	</div>
	209	<h3 id="Transparency">Transparency </h3>
	210	<div id="Transparency_CONTENT">
5241ab5e	211	<pre> use SDL;
	212	use SDL::RWOps;
	213	use SDL::Image;
	214
	215	my $file2 = SDL::RWOps->new_file("test/data/menu.png", "rb");
	216	my $image = SDL::Image::load_typed_rw($file2, 1, "PNG");
	217
	218	SDL::Video::set_color_key($image, SDL_RLEACCEL, $image->format->colorkey);
	219
	220	</pre>
	221
	222	</div>
4e9f9db6	223	<h3 id="Return-2">Return </h3>
4e9f9db6	224	<div id="Return_CONTENT-2">
55bbf7a2	225	<p>The image as a new <a href="SDL-Surface.html">SDL::Surface</a>. NULL is returned on errors. </p>
944366c3	226
	227	</div>
	228	<h2 id="is_TYPE">is_[TYPE]</h2>
	229	<div id="is_TYPE_CONTENT">
5241ab5e	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>
55bbf7a2	246	<p>These functions take a <a href="SDL-RWOps.html">SDL::RWOps</a> as a parameter.</p>
001e1287	247
001e1287	248	</div>
4e9f9db6	249	<h3 id="Return-3">Return</h3>
4e9f9db6	250	<div id="Return_CONTENT-3">
001e1287	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">
5241ab5e	256	<pre> use SDL::RWOps;
	257	use SDL::Image;
	258
	259	my $file = SDL::RWOps->new_file("file", "rb");
	260
	261	print "Image is BMP" if ( SDL::is_BMP );
	262
5241ab5e	263	</pre>
	264
	265	</div>
944366c3	266	<h2 id="load_TYPE_rw">load_[TYPE]_rw</h2>
944366c3	267	<div id="load_TYPE_rw_CONTENT">
5241ab5e	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>
55bbf7a2	284	<p>These functions take a <a href="SDL-RWop.html">SDL::RWop</a> as a parameter</p>
5241ab5e	285
5241ab5e	286	</div>
4e9f9db6	287	<h3 id="Return-4">Return</h3>
4e9f9db6	288	<div id="Return_CONTENT-4">
55bbf7a2	289	<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	290
5241ab5e	291	</div>
001e1287	292	<h3 id="Example-2">Example</h3>
001e1287	293	<div id="Example_CONTENT-2">
5241ab5e	294	<pre> use SDL;
	295	use SDL::RWOps;
	296	use SDL::Image;
	297
	298	my $file = SDL::RWOps->new_file("file.png", "rb");
	299
	300	my $image = SDL::Image::load_PNG_rw($file);
	301
	302	die SDL::get_error if (!$image);
	303
	304	</pre>
944366c3	305
	306	</div>
	307	<h2 id="read_XPM_from_array">read_XPM_from_array</h2>
	308	<div id="read_XPM_from_array_CONTENT">
5241ab5e	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>
4e9f9db6	315	<h3 id="Return-5">Return</h3>
4e9f9db6	316	<div id="Return_CONTENT-5">
55bbf7a2	317	<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	318
5241ab5e	319	</div>
001e1287	320	<h3 id="Example-3">Example</h3>
001e1287	321	<div id="Example_CONTENT-3">
5241ab5e	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	'& c #000000',
	332	'* c #303030',
	333	' ',
	334	' ',
	335	' ',
	336	' ',
	337	' ',
	338	' ',
	339	' ',
	340	' ',
	341	' ',
	342	' .+@##@+. ',
	343	' .@$%&&%$@. ',
	344	' .@&&&&&&@. ',
	345	' +$&&&&&&&&$+ ',
	346	' @%&&&&&&&&%@ ',
	347	' #&&&&&&&&&&# ',
	348	' #&&&&&&&&&&# ',
	349	' @%&&&&&&&&%@ ',
	350	' +$&&&&&&&&$+ ',
	351	' .@&&&&&&@. ',
	352	' .@$%&&%$@. ',
	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">
944366c3	371
	372	</div>
	373	<h2 id="linked_version">linked_version</h2>
	374	<div id="linked_version_CONTENT">
4e9f9db6	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">
55bbf7a2	380	<p>Returns a <a href="SDL-Version.html">SDL::Version</a> object</p>
4e9f9db6	381
	382	</div>
	383	<h3 id="Example-4">Example</h3>
	384	<div id="Example_CONTENT-4">
944366c3	385	<pre> my $version = SDL::Image::linked_version();
	386	print $version->major.' '.$version->minor.' '.$version->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
944366c3	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>
37dfe383	400	<dt>IMG_INIT_JPG </dt>
	401	<dt>IMG_INIT_PNG </dt>
	402	<dt>IMG_INIT_TIF</dt>
944366c3	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>
4e9f9db6	410	<h3 id="Return-7">Return</h3>
4e9f9db6	411	<div id="Return_CONTENT-7">
5241ab5e	412	<p>A bitmask of all the currently inited image loaders.</p>
944366c3	413
944366c3	414	</div>
4e9f9db6	415	<h3 id="Example-5">Example</h3>
4e9f9db6	416	<div id="Example_CONTENT-5">
944366c3	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
944366c3	421	</pre>
	422
	423	</div>
5241ab5e	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>
92e293d6	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>
001e1287	428
001e1287	429	</div>
4e9f9db6	430	<h3 id="Example-6">Example</h3>
4e9f9db6	431	<div id="Example_CONTENT-6">
5241ab5e	432	<pre> use SDL::Image;
	433	SDL::Image::init(IMG_INIT_JPG); #loads JPG support
	434	SDL::Image::load("file.png"); #loads PNG support
	435	SDL::Image::quit(); #unloads everything
	436
	437	</pre>
	438
	439	</div>
944366c3	440	<h2 id="set_error">set_error</h2>
944366c3	441	<div id="set_error_CONTENT">
92e293d6	442	<p>Same as <a href="/SDL.html#set_error">SDL::set_error</a></p>
944366c3	443
	444	</div>
	445	<h2 id="get_error">get_error</h2>
	446	<div id="get_error_CONTENT">
92e293d6	447	<p>Same as <a href="/SDL.html#get_error">SDL::get_error</a></p>
944366c3	448
944366c3	449	</div>
37dfe383	450	<h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p>
37dfe383	451	<div id="SEE_ALSO_CONTENT">
55bbf7a2	452	<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	453
37dfe383	454	</div>
944366c3	455	</div>