.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "pods::SDL::Image 3pm"
.TH pods::SDL::Image 3pm "2018-11-01" "perl v5.28.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
SDL::Image \- Bindings for the SDL_Image library
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
SDL::Image allows you to load many different format of images into memory as an SDL::Surface.
.SH "CATEGORY"
.IX Header "CATEGORY"
Image
.SH "SUPPORTED FORMATS"
.IX Header "SUPPORTED FORMATS"
The following types are supported:
.IP "\s-1TGA\s0" 4
.IX Item "TGA"
TrueVision Targa (\s-1MUST\s0 have .tga)
.IP "\s-1BMP\s0" 4
.IX Item "BMP"
Windows Bitmap(.bmp)
.IP "\s-1PNM\s0" 4
.IX Item "PNM"
Portable Anymap (.pnm)
\&.pbm = Portable BitMap (mono)
\&.pgm = Portable GreyMap (256 greys)
\&.ppm = Portable PixMap (full color)
.IP "\s-1XPM\s0" 4
.IX Item "XPM"
X11 Pixmap (.xpm) can be #included directly in code
This is \s-1NOT\s0 the same as \s-1XBM\s0(X11 Bitmap) format, which is for monocolor images.
.IP "\s-1XCF\s0" 4
.IX Item "XCF"
\&\s-1GIMP\s0 native (.xcf) (\s-1XCF\s0 = eXperimental Computing Facility?)
This format is always changing, and since there's no library supplied by the \s-1GIMP\s0 project to load \s-1XCF,\s0 the loader may frequently fail to load much 
of any image from an \s-1XCF\s0 file. It's better to load this in \s-1GIMP\s0 and convert to a better supported image format.
.IP "\s-1PCX\s0" 4
.IX Item "PCX"
ZSoft \s-1IBM PC\s0 Paintbrush (.pcx)
.IP "\s-1GIF\s0" 4
.IX Item "GIF"
CompuServe Graphics Interchange Format (.gif)
.IP "\s-1JPG\s0" 4
.IX Item "JPG"
Joint Photographic Experts Group \s-1JFIF\s0 format (.jpg or .jpeg)
.IP "\s-1TIF\s0" 4
.IX Item "TIF"
Tagged Image File Format (.tif or .tiff)
.IP "\s-1LBM\s0" 4
.IX Item "LBM"
Interleaved Bitmap (.lbm or .iff) \s-1FORM : ILBM\s0 or \s-1PBM\s0(packed bitmap), \s-1HAM6, HAM8,\s0 and 24bit types are not supported.
.IP "\s-1PNG\s0" 4
.IX Item "PNG"
Portable Network Graphics (.png)
.IP "\s-1XV\s0" 4
.IX Item "XV"
.PD 0
.IP "\s-1ICO\s0" 4
.IX Item "ICO"
.IP "\s-1CUR\s0" 4
.IX Item "CUR"
.PD
.SH "LOADING METHODS"
.IX Header "LOADING METHODS"
.SS "load"
.IX Subsection "load"
.Vb 1
\& my $surface = SDL::Image::load( $file );
.Ve
.PP
\&\f(CW$file\fR Image file name to load a surface from.
.PP
Load file for use as an image in a new SDL::Surface. This actually calls SDL::Image::load_typed_rw, with the 
file extension used as the type string. This can load all supported image files, including \s-1TGA\s0 as long as the filename ends with \*(L".tga\*(R". 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.
.PP
\&\fBNote\fR: 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 
SDL::Image::init to load support for your image format.
.PP
\&\fBNote\fR: If the image format supports a transparent pixel, SDL::Image will set the colorkey for the surface. You can enable \s-1RLE\s0 acceleration on 
the surface afterwards by calling:
.PP
SDL::Video::set_color_key
.PP
.Vb 2
\&  my $image = SDL::Image::load( $some_png_file );
\&  SDL::Video::set_color_key($image, SDL_RLEACCEL, $image\->format\->colorkey);
.Ve
.PP
\fIReturn\fR
.IX Subsection "Return"
.PP
An image as a SDL::Surface. \s-1NULL\s0 is returned on errors, such as no support built for the image, or a file reading error. Use 
SDL::get_error to get cause of error.
.SS "load_typed_rw"
.IX Subsection "load_typed_rw"
.Vb 1
\&  SDL::Image::load_typed_rw($src, $freesrc, $type);
.Ve
.IP "src" 4
.IX Item "src"
The source SDL::RWops as a pointer. The image is loaded from this.
.IP "freesrc" 4
.IX Item "freesrc"
A non-zero value mean is will automatically close/free the src for you. Since \s-1SDL\s0 Perl cannot handle the memory inside this function you would most 
likely want 1 here.
.IP "type" 4
.IX Item "type"
A string that indicates which format type to interpret the image as.
.Sp
Here is a list of the currently recognized strings (case is not important):
.RS 4
.ie n .IP """\s-1BMP""\s0" 4
.el .IP "``\s-1BMP''\s0" 4
.IX Item "BMP"
.PD 0
.ie n .IP """\s-1CUR""\s0" 4
.el .IP "``\s-1CUR''\s0" 4
.IX Item "CUR"
.ie n .IP """\s-1GIF""\s0" 4
.el .IP "``\s-1GIF''\s0" 4
.IX Item "GIF"
.ie n .IP """\s-1ICO""\s0" 4
.el .IP "``\s-1ICO''\s0" 4
.IX Item "ICO"
.ie n .IP """\s-1JPG""\s0" 4
.el .IP "``\s-1JPG''\s0" 4
.IX Item "JPG"
.ie n .IP """\s-1LBM""\s0" 4
.el .IP "``\s-1LBM''\s0" 4
.IX Item "LBM"
.ie n .IP """\s-1PCX""\s0" 4
.el .IP "``\s-1PCX''\s0" 4
.IX Item "PCX"
.ie n .IP """\s-1PNG""\s0" 4
.el .IP "``\s-1PNG''\s0" 4
.IX Item "PNG"
.ie n .IP """\s-1PNM""\s0" 4
.el .IP "``\s-1PNM''\s0" 4
.IX Item "PNM"
.ie n .IP """\s-1TGA""\s0" 4
.el .IP "``\s-1TGA''\s0" 4
.IX Item "TGA"
.ie n .IP """\s-1TIF""\s0" 4
.el .IP "``\s-1TIF''\s0" 4
.IX Item "TIF"
.ie n .IP """\s-1XCF""\s0" 4
.el .IP "``\s-1XCF''\s0" 4
.IX Item "XCF"
.ie n .IP """\s-1XPM""\s0" 4
.el .IP "``\s-1XPM''\s0" 4
.IX Item "XPM"
.ie n .IP """\s-1XV""\s0" 4
.el .IP "``\s-1XV''\s0" 4
.IX Item "XV"
.RE
.RS 4
.RE
.PD
.PP
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 \s-1TGA\s0 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.
.PP
\&\fBNote\fR: 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 
SDL::Image::init to load support for your image format.
.PP
\&\fBNote\fR: If the image format supports a transparent pixel, SDL::Image will set the colorkey for the surface. You can enable \s-1RLE\s0 acceleration on 
the surface afterwards by calling: SDL::Video::set_color_key
.PP
\fITransparency\fR
.IX Subsection "Transparency"
.PP
.Vb 3
\&  use SDL;
\&  use SDL::RWOps;
\&  use SDL::Image;
\&
\&  my $file2 = SDL::RWOps\->new_file("test/data/menu.png", "rb");
\&  my $image = SDL::Image::load_typed_rw($file2, 1, "PNG");
\&
\&  SDL::Video::set_color_key($image, SDL_RLEACCEL, $image\->format\->colorkey);
.Ve
.PP
\fIReturn\fR
.IX Subsection "Return"
.PP
The image as a new SDL::Surface. \s-1NULL\s0 is returned on errors.
.SS "is_[\s-1TYPE\s0]"
.IX Subsection "is_[TYPE]"
Test for valid, supported image files:
.IP "is_ICO" 4
.IX Item "is_ICO"
.PD 0
.IP "is_CUR" 4
.IX Item "is_CUR"
.IP "is_PNG" 4
.IX Item "is_PNG"
.IP "is_BMP" 4
.IX Item "is_BMP"
.IP "is_GIF" 4
.IX Item "is_GIF"
.IP "is_JPG" 4
.IX Item "is_JPG"
.IP "is_LBM" 4
.IX Item "is_LBM"
.IP "is_PCX" 4
.IX Item "is_PCX"
.IP "is_PNM" 4
.IX Item "is_PNM"
.IP "is_TIF" 4
.IX Item "is_TIF"
.IP "is_XCF" 4
.IX Item "is_XCF"
.IP "is_XPM" 4
.IX Item "is_XPM"
.IP "is_XV" 4
.IX Item "is_XV"
.PD
.PP
These functions take a SDL::RWOps as a parameter.
.PP
\fIReturn\fR
.IX Subsection "Return"
.PP
1 if the image is a valid [\s-1TYPE\s0]  and the [\s-1TYPE\s0] format support is compiled into SDL_image. 0 is returned otherwise.
.PP
\fIExample\fR
.IX Subsection "Example"
.PP
.Vb 2
\& use SDL::RWOps;
\& use SDL::Image;
\&
\& my $file = SDL::RWOps\->new_file("file", "rb");
\& 
\& print "Image is BMP" if ( SDL::is_BMP );
.Ve
.SS "load_[\s-1TYPE\s0]_rw"
.IX Subsection "load_[TYPE]_rw"
Specific loader for known formats:
.IP "load_ICO_rw" 4
.IX Item "load_ICO_rw"
.PD 0
.IP "load_CUR_rw" 4
.IX Item "load_CUR_rw"
.IP "load_PNG_rw" 4
.IX Item "load_PNG_rw"
.IP "load_BMP_rw" 4
.IX Item "load_BMP_rw"
.IP "load_GIF_rw" 4
.IX Item "load_GIF_rw"
.IP "load_JPG_rw" 4
.IX Item "load_JPG_rw"
.IP "load_LBM_rw" 4
.IX Item "load_LBM_rw"
.IP "load_PCX_rw" 4
.IX Item "load_PCX_rw"
.IP "load_PNM_rw" 4
.IX Item "load_PNM_rw"
.IP "load_TIF_rw" 4
.IX Item "load_TIF_rw"
.IP "load_XCF_rw" 4
.IX Item "load_XCF_rw"
.IP "load_XPM_rw" 4
.IX Item "load_XPM_rw"
.IP "load_XV_rw" 4
.IX Item "load_XV_rw"
.PD
.PP
These functions take a SDL::RWop as a parameter
.PP
\fIReturn\fR
.IX Subsection "Return"
.PP
The image as a new SDL::Surface. \s-1NULL\s0 is returned on errors, like if the [\s-1TYPE\s0] is not supported, or a read error.
.PP
\fIExample\fR
.IX Subsection "Example"
.PP
.Vb 3
\& use SDL;
\& use SDL::RWOps;
\& use SDL::Image;
\&
\& my $file = SDL::RWOps\->new_file("file.png", "rb");  
\&
\& my $image = SDL::Image::load_PNG_rw($file);
\& 
\& die SDL::get_error if (!$image);
.Ve
.SS "read_XPM_from_array"
.IX Subsection "read_XPM_from_array"
.Vb 1
\& my $picture = SDL::Image::read_XPM_from_array(\e@XPM, $width);
.Ve
.PP
This functions takes the reference of an array in the valid \f(CW@XPM\fR format. Also the \f(CW$width\fR of the \s-1XPM\s0 image.
.PP
\fIReturn\fR
.IX Subsection "Return"
.PP
The image as a new SDL::Surface. \s-1NULL\s0 is returned on errors, like if \s-1XPM\s0 is not supported, or a read error.
.PP
\fIExample\fR
.IX Subsection "Example"
.PP
.Vb 10
\&        my @XPM= (
\&        \*(Aq30 30 9 1\*(Aq,
\&        \*(Aq       c #FFFFFF\*(Aq,
\&        \*(Aq.      c #EFEFEF\*(Aq,
\&        \*(Aq+      c #CFCFCF\*(Aq,
\&        \*(Aq@      c #9F9F9F\*(Aq,
\&        \*(Aq#      c #808080\*(Aq,
\&        \*(Aq$      c #505050\*(Aq,
\&        \*(Aq%      c #202020\*(Aq,
\&        \*(Aq&      c #000000\*(Aq,
\&        \*(Aq*      c #303030\*(Aq,
\&        \*(Aq                              \*(Aq,
\&        \*(Aq                              \*(Aq,
\&        \*(Aq                              \*(Aq,
\&        \*(Aq                              \*(Aq,
\&        \*(Aq                              \*(Aq,
\&        \*(Aq                              \*(Aq,
\&        \*(Aq                              \*(Aq,
\&        \*(Aq                              \*(Aq,
\&        \*(Aq                              \*(Aq,
\&        \*(Aq           .+@##@+.           \*(Aq,
\&        \*(Aq          .@$%&&%$@.          \*(Aq,
\&        \*(Aq         .@*&&&&&&*@.         \*(Aq,
\&        \*(Aq         +$&&&&&&&&$+         \*(Aq,
\&        \*(Aq         @%&&&&&&&&%@         \*(Aq,
\&        \*(Aq         #&&&&&&&&&&#         \*(Aq,
\&        \*(Aq         #&&&&&&&&&&#         \*(Aq,
\&        \*(Aq         @%&&&&&&&&%@         \*(Aq,
\&        \*(Aq         +$&&&&&&&&$+         \*(Aq,
\&        \*(Aq         .@*&&&&&&*@.         \*(Aq,
\&        \*(Aq          .@$%&&%$@.          \*(Aq,
\&        \*(Aq           .+@##@+.           \*(Aq,
\&        \*(Aq                              \*(Aq,
\&        \*(Aq                              \*(Aq,
\&        \*(Aq                              \*(Aq,
\&        \*(Aq                              \*(Aq,
\&        \*(Aq                              \*(Aq,
\&        \*(Aq                              \*(Aq,
\&        \*(Aq                              \*(Aq,
\&        \*(Aq                              \*(Aq,
\&        \*(Aq                              \*(Aq,);
\&        
\&        my $picture = SDL::Image::read_XPM_from_array(\e@XPM, 30);
.Ve
.SH "MISC METHODS"
.IX Header "MISC METHODS"
.SS "linked_version"
.IX Subsection "linked_version"
Provides the version of linked sdl_image library.
.PP
\fIReturn\fR
.IX Subsection "Return"
.PP
Returns a SDL::Version object
.PP
\fIExample\fR
.IX Subsection "Example"
.PP
.Vb 2
\&        my $version = SDL::Image::linked_version();
\&        print $version\->major.\*(Aq \*(Aq.$version\->minor.\*(Aq \*(Aq.$version\->patch;
.Ve
.SS "init"
.IX Subsection "init"
\&\fBFor version SDL_image 1.2.10 and up\fR
.PP
\fIFlags\fR
.IX Subsection "Flags"
.PP
bitwise \s-1OR\s0'd set of image formats to support by loading a library now. The values you may \s-1OR\s0 together to pass in are:
.IP "\s-1IMG_INIT_JPG\s0" 4
.IX Item "IMG_INIT_JPG"
.PD 0
.IP "\s-1IMG_INIT_PNG\s0" 4
.IX Item "IMG_INIT_PNG"
.IP "\s-1IMG_INIT_TIF\s0" 4
.IX Item "IMG_INIT_TIF"
.PD
.PP
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.
.PP
\&\fBNote\fR: to load \s-1JPG, PNG,\s0 and/or \s-1TIF\s0 images you can call IMG_Init with the right IMG_INIT_* flags \s-1OR\s0'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.
.PP
\&\fBNote\fR: No initialization is needed nor performed when using the SDL::Image::is_JPG, SDL::Image::is_PNG, and SDL::Image::is_TIF functions.
.PP
\&\fBNote\fR: this function does not always set the error string, so do not depend on SDL::Image::get_error being meaningful all the time.
.PP
\fIReturn\fR
.IX Subsection "Return"
.PP
A bitmask of all the currently inited image loaders.
.PP
\fIExample\fR
.IX Subsection "Example"
.PP
.Vb 3
\&  use SDL::Image;
\&  my $flags = IMG_INIT_JPG | IMG_INIT_PNG | IMG_INIT_JPG;
\&  my $inited = SDL::Image::init($flags);
.Ve
.SS "quit"
.IX Subsection "quit"
\&\fBFor version SDL_image 1.2.10 and up\fR
.PP
This function cleans up all dynamically loaded library handles, freeing memory. If support is required again it will be initialized again, either 
by SDL::Image::init or loading an image with dynamic support required. You may call this function when 
SDL::Image::load functions are no longer needed for the \s-1JPG, PNG,\s0 and \s-1TIF\s0 image formats. You only need to call this function 
once, no matter how many times SDL::Image::init was called.
.PP
\fIExample\fR
.IX Subsection "Example"
.PP
.Vb 4
\& use SDL::Image;
\& SDL::Image::init(IMG_INIT_JPG); #loads JPG support
\& SDL::Image::load("file.png"); #loads PNG support
\& SDL::Image::quit(); #unloads everything
.Ve
.SS "set_error"
.IX Subsection "set_error"
Same as SDL::set_error
.SS "get_error"
.IX Subsection "get_error"
Same as SDL::get_error
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1SDL\s0, SDL::Surface, SDL::Video, SDL::RWOps
.SH "AUTHORS"
.IX Header "AUTHORS"
See \*(L"\s-1AUTHORS\*(R"\s0 in \s-1SDL\s0.