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
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.