The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
SDL2-FFI-0.08
River stage zero No dependents
/ SDL2::Image

NAME

SDL2::Image - SDL Image Loading Library

SYNOPSIS

    use SDL2::Image;

DESCRIPTION

This extension to SDL2 can load images as SDL surfaces and textures. The following formats 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)

Functions

These may be imported by name or with the :all tag.

SDL_IMAGE_VERSION( ... )

Macro to determine compile-time version of the SDL_image library.

Expected parameters include:

x - a pointer to a SDL2::Version struct to initialize

SDL_IMAGE_VERSION_ATLEAST( ... )

Evaluates to true if compiled with SDL at least major.minor.patch.

        if ( SDL_IMAGE_VERSION_ATLEAST( 2, 0, 5 ) ) {
                # Some feature that requires 2.0.5+
        }

Expected parameters include:

major
minor
patch

IMG_Linked_Version( )

This function gets the version of the dynamically linked SDL_image library.

    my $link_version = IMG_Linked_Version();
    printf "running with SDL_image version: %d.%d.%d\n",
        $link_version->major, $link_version->minor, $link_version->patch;

It should NOT be used to fill a version structure, instead you should use the SDL_IMAGE_VERSION( ... ) macro.

Returns a SDL2::Version object.

IMG_Init( ... )

Loads dynamic libraries and prepares them for use.

    if ( !( IMG_Init(IMG_INIT_PNG) & IMG_INIT_PNG ) ) {
        printf( "could not initialize SDL_image: %s\n", IMG_GetError() );
        return !1;
    }

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 flags of 0 to retrieve whether support was built-in or not loaded yet.

Expected parameters include:

flags

Flags should be one or more flags from IMG_InitFlags OR'd together.

IMG_INIT_JPG
IMG_INIT_PNG
IMG_INIT_TIF

Returns the flags successfully initialized, or 0 on failure.

IMG_Quit( )

Unloads libraries loaded with IMG_Init( ... ).

IMG_LoadTyped_RW( ... )

Load an image from an SDL data source.

    # load sample.tga into image
    my $image = IMG_LoadTyped_RW( SDL_RWFromFile( 'sample.tga', 'rb' ), 1, 'TGA' );
    if ( !$image ) {
        printf( "IMG_LoadTyped_RW: %s\n", IMG_GetError() );

        # handle error
    }

If the image format supports a transparent pixel, SDL will set the colorkey for the surface. You can enable RLE acceleration on the surface afterwards by calling:

    SDL_SetColorKey( $image, SDL_RLEACCEL, $image->format->colorkey );

Expected parameters include:

src - The source SDL2::RWops the image is to be loaded from
freesrc - SDL_image will close and free src for you if this is a non-zero value
type - a string that indicates which format type to interpret the image as

The list of the currently recognized strings includes (case is not important):

BMP
CUR
GIF
ICO
JPG
LBM
PCX
PNG
PNM
TGA
TIF
XCF
XPM
XV

Returns a new SDL2::Surface on success.

IMG_Load( ... )

Loads a file for use as an image in a new surface.

    # load sample.png into image
    my $image = IMG_Load("sample.png");
    if ( !defined $image ) {
        printf( "IMG_Load: %s\n", IMG_GetError() );

        # handle error
    }

This actually calls IMG_LoadTyped_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. Don't forget to SDL_FreeSurface( ... ) the returned surface pointer when you are through with it.

Expected parameters include:

file - image file name to load a surface from

Returns a new SDL2::Surface on success.

IMG_Load_RW( ... )

Load an image src for use as a surface.

    # load sample.png in to image
    my $image = IMG_Load_RW( SDL_RWFromFile( "sample.png", "rb" ), 1 );
    if ( !$image ) {
        printf( "IMG_Load_RW: %s\n", IMG_GetError() );

        # handle error
    }

This can load all supported image formats, except TGA.

Expected parameters include:

src - The source SDL2::RWops the image is to be loaded from
freesrc - SDL_image will close and free src for you if this is a non-zero value

Returns a new SDL2::Surface on success.

IMG_LoadTexture( ... )

Load an image file for use as a texture.

    # load sample.png in to texture
    my $texture = IMG_LoadTexture( $renderer, "sample.png" );
    if ( !$texture ) {
        printf( "IMG_LoadTexture: %s\n", IMG_GetError() );

        # handle error
    }

Expected parameters include:

renderer - an existing SDL2::Renderer object
file - the source filename of the image is to be loaded

Returns a SDL2::Texture object on success.

IMG_LoadTexture_RW( ... )

Load an image src for use as a texture.

    # load sample.png in to texture
    my $texture = IMG_LoadTexture_RW( $renderer, SDL_RWFromFile( "sample.png", "rb" ), 1 );
    if ( !$texture ) {
        printf( "IMG_LoadTexture: %s\n", IMG_GetError() );

        # handle error
    }

Expected parameters include:

renderer - an existing SDL2::Renderer object
src - the source SDL2::RWops the image is to be loaded from
freesrc - SDL_image will close and free src for you if this is a non-zero value

Returns a SDL2::Texture object on success.

IMG_LoadTextureTyped_RW( ... )

Load an image src for use as a texture.

    # load sample.png in to texture
    my $texture
        = IMG_LoadTextureTyped_RW( $renderer, SDL_RWFromFile( 'sample.png', 'rb' ), 1, 'PNG' );
    if ( !$texture ) {
        printf( "IMG_LoadTexture: %s\n", IMG_GetError() );

        # handle error
    }

Expected parameters include:

renderer - an existing SDL2::Renderer object
src - the source SDL2::RWops the image is to be loaded from
freesrc - SDL_image will close and free src for you if this is a non-zero value
type - a string that indicates which format type to interpret the image as

Returns a SDL2::Texture object on success.

IMG_isICO( ... )

If the BMP format is supported, then the image data is tested to see if it is readable as an ICO, otherwise it returns false (zero).

Expected parameters include:

src - the source SDL2::RWops the image is to be loaded from

Returns 1 if the image is an ICO and the BMP format support is compiled into SDL_image. 0 is returned otherwise.

IMG_isCUR( ... )

If the BMP format is supported, then the image data is tested to see if it is readable as a CUR, otherwise it returns false (zero).

Expected parameters include:

src - the source SDL2::RWops the image is to be loaded from

Returns 1 if the image is a CUR and the BMP format support is compiled into SDL_image. 0 is returned otherwise.

IMG_isBMP( ... )

If the BMP format is supported, then the image data is tested to see if it is readable as a BMP, otherwise it returns false (zero).

Expected parameters include:

src - the source SDL2::RWops the image is to be loaded from

Returns 1 if the image is a BMP and the BMP format support is compiled into SDL_image. 0 is returned otherwise.

IMG_isGIF( ... )

If the GIF format is supported, then the image data is tested to see if it is readable as a GIF, otherwise it returns false (zero).

Expected parameters include:

src - the source SDL2::RWops the image is to be loaded from

Returns 1 if the image is a GIF and the GIF format support is compiled into SDL_image. 0 is returned otherwise.

IMG_isJPG( ... )

If the JPG format is supported, then the image data is tested to see if it is readable as a JPG, otherwise it returns false (zero).

Expected parameters include:

src - the source SDL2::RWops the image is to be loaded from

Returns 1 if the image is a JPG and the JPG format support is compiled into SDL_image. 0 is returned otherwise.

IMG_isLBM( ... )

If the LBM format is supported, then the image data is tested to see if it is readable as a LBM, otherwise it returns false (zero).

Expected parameters include:

src - the source SDL2::RWops the image is to be loaded from

Returns 1 if the image is a LBM and the LBM format support is compiled into SDL_image. 0 is returned otherwise.

IMG_isPCX( ... )

If the PCX format is supported, then the image data is tested to see if it is readable as a PCX, otherwise it returns false (zero).

Expected parameters include:

src - the source SDL2::RWops the image is to be loaded from

Returns 1 if the image is a PCX and the PCX format support is compiled into SDL_image. 0 is returned otherwise.

IMG_isPNG( ... )

If the PNG format is supported, then the image data is tested to see if it is readable as a PNG, otherwise it returns false (zero).

Expected parameters include:

src - the source SDL2::RWops the image is to be loaded from

Returns 1 if the image is a PNG and the PNG format support is compiled into SDL_image. 0 is returned otherwise.

IMG_isPNM( ... )

If the PNM format is supported, then the image data is tested to see if it is readable as a PNM, otherwise it returns false (zero).

Expected parameters include:

src - the source SDL2::RWops the image is to be loaded from

Returns 1 if the image is a PNM and the PNM format support is compiled into SDL_image. 0 is returned otherwise.

IMG_isSVG( ... )

If the SVG format is supported, then the image data is tested to see if it is readable as a SVG, otherwise it returns false (zero).

Expected parameters include:

src - the source SDL2::RWops the image is to be loaded from

Returns 1 if the image is a SVG and the SVG format support is compiled into SDL_image. 0 is returned otherwise.

IMG_isTIF( ... )

If the TIF format is supported, then the image data is tested to see if it is readable as a TIF, otherwise it returns false (zero).

Expected parameters include:

src - the source SDL2::RWops the image is to be loaded from

Returns 1 if the image is a TIF and the TIF format support is compiled into SDL_image. 0 is returned otherwise.

IMG_isXCF( ... )

If the XCF format is supported, then the image data is tested to see if it is readable as a XCF, otherwise it returns false (zero).

Expected parameters include:

src - the source SDL2::RWops the image is to be loaded from

Returns 1 if the image is a XCF and the XCF format support is compiled into SDL_image. 0 is returned otherwise.

IMG_isXPM( ... )

If the XPM format is supported, then the image data is tested to see if it is readable as a XPM, otherwise it returns false (zero).

Expected parameters include:

src - the source SDL2::RWops the image is to be loaded from

Returns 1 if the image is a XPM and the XPM format support is compiled into SDL_image. 0 is returned otherwise.

IMG_isXV( ... )

If the XV format is supported, then the image data is tested to see if it is readable as a XV thumbnail, otherwise it returns false (zero).

Expected parameters include:

src - the source SDL2::RWops the image is to be loaded from

Returns 1 if the image is a XV thumbnail and the XV format support is compiled into SDL_image. 0 is returned otherwise.

IMG_isWEBP( ... )

If the WebP format is supported, then the image data is tested to see if it is readable as a WebP, otherwise it returns false (zero).

Expected parameters include:

src - the source SDL2::RWops the image is to be loaded from

Returns 1 if the image is a WebP and the WebP image format support is compiled into SDL_image. 0 is returned otherwise.

IMG_LoadICO_RW( ... )

Load src as a ICO image for use as a surface, if ICO support is compiled into the SDL_image library.

Expected parameters include:

src - the source SDL2::RWops object

Returns a new SDL2::Surface structure on success.

IMG_LoadCUR_RW( ... )

Load src as a CUR image for use as a surface, if CUR support is compiled into the SDL_image library.

Expected parameters include:

src - the source SDL2::RWops object

Returns a new SDL2::Surface structure on success.

IMG_LoadBMP_RW( ... )

Load src as a BMP image for use as a surface, if BMP support is compiled into the SDL_image library.

Expected parameters include:

src - the source SDL2::RWops object

Returns a new SDL2::Surface structure on success.

IMG_LoadGIF_RW( ... )

Load src as a GIF image for use as a surface, if GIF support is compiled into the SDL_image library.

Expected parameters include:

src - the source SDL2::RWops object

Returns a new SDL2::Surface structure on success.

IMG_LoadJPG_RW( ... )

Load src as a JPG image for use as a surface, if JPG support is compiled into the SDL_image library.

Expected parameters include:

src - the source SDL2::RWops object

Returns a new SDL2::Surface structure on success.

IMG_LoadLBM_RW( ... )

Load src as a LBM image for use as a surface, if LBM support is compiled into the SDL_image library.

Expected parameters include:

src - the source SDL2::RWops object

Returns a new SDL2::Surface structure on success.

IMG_LoadPCX_RW( ... )

Load src as a PCX image for use as a surface, if PCX support is compiled into the SDL_image library.

Expected parameters include:

src - the source SDL2::RWops object

Returns a new SDL2::Surface structure on success.

IMG_LoadPNG_RW( ... )

Load src as a PNG image for use as a surface, if PNG support is compiled into the SDL_image library.

Expected parameters include:

src - the source SDL2::RWops object

Returns a new SDL2::Surface structure on success.

IMG_LoadPNM_RW( ... )

Load src as a PNM image for use as a surface, if PNM support is compiled into the SDL_image library.

Expected parameters include:

src - the source SDL2::RWops object

Returns a new SDL2::Surface structure on success.

IMG_LoadSVG_RW( ... )

Load src as a SVG image for use as a surface, if SVG support is compiled into the SDL_image library.

Expected parameters include:

src - the source SDL2::RWops object

Returns a new SDL2::Surface structure on success.

IMG_LoadTGA_RW( ... )

Load src as a TGA image for use as a surface, if TGA support is compiled into the SDL_image library.

Expected parameters include:

src - the source SDL2::RWops object

Returns a new SDL2::Surface structure on success.

IMG_LoadTIF_RW( ... )

Load src as a TIF image for use as a surface, if TIF support is compiled into the SDL_image library.

Expected parameters include:

src - the source SDL2::RWops object

Returns a new SDL2::Surface structure on success.

IMG_LoadXCF_RW( ... )

Load src as a XCF image for use as a surface, if XCF support is compiled into the SDL_image library.

Expected parameters include:

src - the source SDL2::RWops object

Returns a new SDL2::Surface structure on success.

IMG_LoadXPM_RW( ... )

Load src as a XPM image for use as a surface, if XPM support is compiled into the SDL_image library.

Expected parameters include:

src - the source SDL2::RWops object

Returns a new SDL2::Surface structure on success.

IMG_LoadXV_RW( ... )

Load src as a XV image for use as a surface, if XV support is compiled into the SDL_image library.

Expected parameters include:

src - the source SDL2::RWops object

Returns a new SDL2::Surface structure on success.

IMG_LoadWEBP_RW( ... )

Load src as a WEBP image for use as a surface, if WEBP support is compiled into the SDL_image library.

Expected parameters include:

src - the source SDL2::RWops object

Returns a new SDL2::Surface structure on success.

IMG_ReadXPMFromArray( ... )

Load xpm as a XPM image for use as a surface, if XPM support is compiled into the SDL_image library.

        my $image = IMG_ReadXPMFromArray( @sample_xpm );
        if( !$image ) {
                printf "IMG_ReadXPMFromArray: %s\n", IMG_GetError();
                # handle error
        }

XPM files may be embedded in source code. See eg/xpm.pl for an example.

Expected parameters include:

<xpm> - the source xpm data

The XPM image is loaded from this list of strings.

Returns a new SDL2::Surface structure on success.

IMG_SavePNG( ... )

Saves the contents of an SDL2::Surface to a PNG file.

This should work regardless of whether PNG support was successfully initialized with IMG_Init( ... ), but the full set of PNG features may not be available.

Expected parameters include:

surface - an SDL2::Surface object containing the image to be saved
<file> - UTF-8 encoded string containing the path to save the PNG to

Returns 0 on success or a negative error code on failure.

IMG_SavePNG_RW( ... )

Sends the contents of an SDL2::Surface to a SDL2::RWops as a PNG file.

This should work regardless of whether PNG support was successfully initialized with IMG_Init( ... ), but the full set of PNG features may not be available.

Expected parameters include:

surface - an SDL2::Surface object containing the image to be saved
<dst> - a SDL2::RWops object to save the PNG to
freedst - if non-zero, the destination file object will be closed once the PNG has been written

Returns 0 on success or a negative error code on failure.

IMG_SaveJPG( ... )

Saves the contents of an SDL2::Surface to a JPEG file.

JPEG support must be already initialized using IMG_Init( ... ) before this function can be used, otherwise this function will fail without an explicit error that can be retrieved with IMG_GetError( ).

Expected parameters include:

surface - an SDL2::Surface object containing the image to be saved
<file> - UTF-8 encoded string containing the path to save the JPEG to
quality - the quality at which to compress the JPEG, from 0 to 100 inclusive

Returns 0 on success or a negative error code on failure.

IMG_SaveJPG_RW( ... )

Sends the contents of an SDL2::Surface to a SDL2::RWops as a JPEG file.

JPEG support must be already initialized using IMG_Init( ... ) before this function can be used, otherwise this function will fail without an explicit error that can be retrieved with IMG_GetError( ).

Expected parameters include:

surface - an SDL2::Surface object containing the image to be saved
<dst> - a SDL2::RWops object to save the JPEG to
freedst - if non-zero, the destination file object will be closed once the JPEG has been written
quality - the quality at which to compress the JPEG, from 0 to 100 inclusive

Returns 0 on success or a negative error code on failure.

IMG_LoadAnimation( ... )

Load an animated image from an existing file.

Note that this function is only defined on SDL_image 2.0.6+.

Expected parameters include:

file - image file name to load an animated image from

Returns a new SDL2::Image::Animation object on success.

IMG_LoadAnimation_RW( ... )

Load an animated image from an SDL data source.

Note that this function is only defined on SDL_image 2.0.6+.

Expected parameters include:

src - the source SDL2::RWops the animated GIF is to be loaded from
freesrc - SDL_image will close and free src for you if this is a non-zero value

Returns a new SDL2::Image::Animation object on success.

IMG_LoadAnimationTyped_RW( ... )

Load an animated image from an SDL data source.

Note that this function is only defined on SDL_image 2.0.6+.

Expected parameters include:

src - the source SDL2::RWops the animated GIF is to be loaded from
freesrc - SDL_image will close and free src for you if this is a non-zero value
type - a string that indicates which format type to interpret the image as

Currently, the following types are understood:

GIF

Returns a new SDL2::Image::Animation object on success.

IMG_FreeAnimation( ... )

Frees an initialized SDL2::Image::Animation structure from memory.

Note that this function is only defined on SDL_image 2.0.6+.

Expected parameters include:

anim - the SDL2::Image::Animation to release from memory

IMG_LoadGIFAnimation_RW( ... )

Loads an animated GIF image from an SDL2::RWops object.

Note that this function is only defined on SDL_image 2.0.6+.

Expected parameters include:

src - the source SDL2::RWops the animated GIF is to be loaded from

Returns a SDL2::Image::Animation on success.

IMG_SetError( ... )

Wrapper around SDL_SetError( ... ).

IMG_GetError( )

Wrapper around SDL_GetError( ).

Defined values and Enumerations

These might actually be useful and may be imported with the listed tags.

Version information

SDL_IMAGE_MAJOR_VERSION
SDL_IMAGE_MINOR_VERSION
SDL_IMAGE_PATCHLEVEL
SDL_IMAGE_COMPILEDVERSION - Version number for the current SDL_image version

IMG_InitFlags

IMG_INIT_JPG
IMG_INIT_PNG
IMG_INIT_TIF
IMG_INIT_WEBP

LICENSE

Copyright (C) Sanko Robinson.

This library is free software; you can redistribute it and/or modify it under the terms found in the Artistic License 2. Other copyrights, terms, and conditions may apply to data transmitted through this module.

AUTHOR

Sanko Robinson <sanko@cpan.org>