--- name: "SDL::Image" section: "3pm" platform: "linux" package: "libsdl-perl" version: "2.548-5+b1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/SDL::Image" --- # SDL::Image(3pm) Bindings for the SDL\_Image library ## 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.