pods::SDL::Image(3) User Contributed Perl Documentation pods::SDL::Image(3)NAME
SDL::Image - Bindings for the SDL_Image library
DESCRIPTION
SDL::Image allows you to load many different format of images into
memory as an SDL::Surface.
CATEGORY
Image
SUPPORTED FORMATS
The following types are supported:
TGA TrueVision Targa (MUST have .tga)
BMP Windows Bitmap(.bmp)
PNM Portable Anymap (.pnm) .pbm = Portable BitMap (mono) .pgm =
Portable GreyMap (256 greys) .ppm = Portable PixMap (full color)
XPM X11 Pixmap (.xpm) can be #included directly in code This is NOT the
same as XBM(X11 Bitmap) format, which is for monocolor images.
XCF GIMP native (.xcf) (XCF = eXperimental Computing Facility?) This
format is always changing, and since there's no library supplied by
the GIMP project to load XCF, the loader may frequently fail to
load much of any image from an XCF file. It's better to load this
in GIMP and convert to a better supported image format.
PCX ZSoft IBM PC Paintbrush (.pcx)
GIF CompuServe Graphics Interchange Format (.gif)
JPG Joint Photographic Experts Group JFIF format (.jpg or .jpeg)
TIF Tagged Image File Format (.tif or .tiff)
LBM Interleaved Bitmap (.lbm or .iff) FORM : ILBM or PBM(packed
bitmap), HAM6, HAM8, and 24bit types are not supported.
PNG Portable Network Graphics (.png)
XV
ICO
CUR
LOADING METHODS
load
my $surface = SDL::Image::load( $file );
$file Image file name to load a surface from.
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 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.
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 SDL::Image::init to load support for your image format.
Note: If the image format supports a transparent pixel, SDL::Image will
set the colorkey for the surface. You can enable RLE acceleration on
the surface afterwards by calling:
SDL::Video::set_color_key
my $image = SDL::Image::load( $some_png_file );
SDL::Video::set_color_key($image, SDL_RLEACCEL, $image->format->colorkey);
Return
An image as a SDL::Surface. NULL 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.
load_typed_rw
SDL::Image::load_typed_rw($src, $freesrc, $type);
src The source SDL::RWops as a pointer. The image is loaded from this.
freesrc
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.
type
A string that indicates which format type to interpret the image
as.
Here is a list of the currently recognized strings (case is not
important):
"BMP"
"CUR"
"GIF"
"ICO"
"JPG"
"LBM"
"PCX"
"PNG"
"PNM"
"TGA"
"TIF"
"XCF"
"XPM"
"XV"
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 SDL::Image::init to load support for your image format.
Note: If the image format supports a transparent pixel, SDL::Image will
set the colorkey for the surface. You can enable RLE acceleration on
the surface afterwards by calling: SDL::Video::set_color_key
Transparency
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);
Return
The image as a new SDL::Surface. NULL is returned on errors.
is_[TYPE]
Test for valid, supported image files:
is_ICO
is_CUR
is_PNG
is_BMP
is_GIF
is_JPG
is_LBM
is_PCX
is_PNM
is_TIF
is_XCF
is_XPM
is_XV
These functions take a SDL::RWOps as a parameter.
Return
1 if the image is a valid [TYPE] and the [TYPE] format support is
compiled into SDL_image. 0 is returned otherwise.
Example
use SDL::RWOps;
use SDL::Image;
my $file = SDL::RWOps->new_file("file", "rb");
print "Image is BMP" if ( SDL::is_BMP );
load_[TYPE]_rw
Specific loader for known formats:
load_ICO_rw
load_CUR_rw
load_PNG_rw
load_BMP_rw
load_GIF_rw
load_JPG_rw
load_LBM_rw
load_PCX_rw
load_PNM_rw
load_TIF_rw
load_XCF_rw
load_XPM_rw
load_XV_rw
These functions take a SDL::RWop as a parameter
Return
The image as a new SDL::Surface. NULL is returned on errors, like if
the [TYPE] is not supported, or a read error.
Example
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);
read_XPM_from_array
my $picture = SDL::Image::read_XPM_from_array(\@XPM, $width);
This functions takes the reference of an array in the valid @XPM
format. Also the $width of the XPM image.
Return
The image as a new SDL::Surface. NULL is returned on errors, like if
XPM is not supported, or a read error.
Example
my @XPM= (
'30 30 9 1',
' c #FFFFFF',
'. c #EFEFEF',
'+ c #CFCFCF',
'@ c #9F9F9F',
'# c #808080',
'$ c #505050',
'% c #202020',
'& c #000000',
'* c #303030',
' ',
' ',
' ',
' ',
' ',
' ',
' ',
' ',
' ',
' .+@##@+. ',
' .@$%&&%$@. ',
' .@*&&&&&&*@. ',
' +$&&&&&&&&$+ ',
' @%&&&&&&&&%@ ',
' #&&&&&&&&&&# ',
' #&&&&&&&&&&# ',
' @%&&&&&&&&%@ ',
' +$&&&&&&&&$+ ',
' .@*&&&&&&*@. ',
' .@$%&&%$@. ',
' .+@##@+. ',
' ',
' ',
' ',
' ',
' ',
' ',
' ',
' ',
' ',);
my $picture = SDL::Image::read_XPM_from_array(\@XPM, 30);
MISC METHODS
linked_version
Provides the version of linked sdl_image library.
Return
Returns a SDL::Version object
Example
my $version = SDL::Image::linked_version();
print $version->major.' '.$version->minor.' '.$version->patch;
init
For version SDL_image 1.2.10 and up
Flags
bitwise OR'd set of image formats to support by loading a library now.
The values you may OR together to pass in are:
IMG_INIT_JPG
IMG_INIT_PNG
IMG_INIT_TIF
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.
Return
A bitmask of all the currently inited image loaders.
Example
use SDL::Image;
my $flags = IMG_INIT_JPG | IMG_INIT_PNG | IMG_INIT_JPG;
my $inited = SDL::Image::init($flags);
quit
For version SDL_image 1.2.10 and up
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 JPG, PNG, and TIF image formats. You only
need to call this function once, no matter how many times
SDL::Image::init was called.
Example
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
set_error
Same as SDL::set_error
get_error
Same as SDL::get_error
SEE ALSO
SDL, SDL::Surface, SDL::Video, SDL::RWOps
AUTHORS
See "AUTHORS" in SDL.
perl v5.18.1 2013-09-28 pods::SDL::Image(3)
