Provided by: libsdl-perl_2.546-3build1_amd64 bug

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.