[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></li>
<li><a href="#Returns">Returns</a></li>
<li><a href="#load_typed_rw">load_typed_rw</a>
<ul><li><a href="#Transparency">Transparency </a></li>
<li><a href="#Return">Return </a></li>
</ul>
</li>
<li><a href="#is_TYPE">is_[TYPE]</a>
<ul><li><a href="#Return-2">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-2">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-2-2">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></li>
<li><a href="#init">init</a>
<ul><li><a href="#Flags">Flags</a></li>
<li><a href="#Return-2-3">Return</a></li>
<li><a href="#Example-4">Example</a></li>
</ul>
</li>
<li><a href="#quit">quit</a>
<ul><li><a href="#Example-5">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>SDL, 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::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 <a href="/SDL-Image::init.html">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::set_color_key.html">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>
<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">
<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::init.html">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::set_color_key.html">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">Return </h3>
<div id="Return_CONTENT">
<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-2">Return</h3>
<div id="Return_CONTENT-2">
<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-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, 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-2-2">Return</h3>
<div id="Return_CONTENT-2-2">
<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. 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 </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-2-3">Return</h3>
<div id="Return_CONTENT-2-3">
<p>A bitmask of all the currently inited image loaders.</p>

</div>
<h3 id="Example-4">Example</h3>
<div id="Example_CONTENT-4">
<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::init.html">SDL::Image::init</a> or loading an image with dynamic support required. You may call this function when <a href="/SDL-Image::load.html">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::init.html">SDL::Image::init</a> was called. </p>

</div>
<h3 id="Example-5">Example</h3>
<div id="Example_CONTENT-5">
<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-set_error.html">SDL::set_error</a></p>

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