SDL::Image (3)

Leading comments

Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)

Standard preamble:
========================================================================

(The comments found at the beginning of the groff file "man3/SDL::Image.3pm".)

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

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

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.

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

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

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.

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 [

] and the [] 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.

is returned on errors, like if the [] 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

image.

Return

The image as a new SDL::Surface.

is returned on errors, like if 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

'd set of image formats to support by loading a library now. The values you may 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

and/or images you can call IMG_Init with the right IMG_INIT_* flags '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

and 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::Surface, SDL::Video, SDL::RWOps

AUTHORS

See `` in .