[Top] [Contents] [Index] [ ? ]

SDL_image 1.2.8

1. Overview  The README from the SDL_image distribution

2. Getting Started  Using SDL_image

3. Functions  Functions supported by the SDL_image API
4. Defines  Defined values/macros in the SDL_image API

Index  Index of selected words

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1. Overview

A Little Bit About Me

I am currently, as I write this document, a programmer for Raytheon. There I do all sorts of communications, network, GUI, and other general programming tasks in C/C++ on the Solaris, Linux, and Windows Operating Systems.

Feel free to contact me: JonathanCAtkins@gmail.com

I am also usually on IRC at irc.freenode.net in the #SDL channel as LIM

Why is this for you?

Images provide the basic visual building blocks for any user interface. Colors and fun shapes are the stuff that we as kids looked at for hours at a time while trying to shoot down big aliens and rescue pixelated princesses. Now it's our turn to make the images that others will remember later in life perhaps. Now how do we get this dang images into our SDL programs, and be flexible in the handling of the images so that we don't even have to worry about what various formats they may be in? This is where SDLimage makes all of our lives easier. This document doesn't help you make artwork, but it will give you the functional knowledge on how to get that art into your game. Now go forth and make your Stick Figure of Justice, someone else might fill in for your lack of artistry, at least you won't have to make much of an effort to include the new and better art into your code.

This is the README, updated by me for accuracy, in the SDL_image source archive.

 
SDL_image 1.2

The latest version of this library is available from:
SDL_image Homepage

This is a simple library to load images of various formats as SDL surfaces.
This library supports ICO(Icon)/CUR(Cursor)/BMP, PNM (PPM/PGM/PBM), XPM,
LBM(IFF ILBM), PCX, GIF, JPEG, PNG, TGA, TIFF, and XV thumbnail formats.

API:
#include "SDL_image.h"

	SDL_Surface *IMG_Load(const char *file);
or
	SDL_Surface *IMG_Load_RW(SDL_RWops *src, int freesrc);
or
	SDL_Surface *IMG_LoadTyped_RW(SDL_RWops *src, int freesrc, char *type);

where type is a string specifying the format (i.e. "PNG" or "pcx").
Note that IMG_Load_RW cannot load TGA images.

To create a surface from an XPM image included in C source, use:

	SDL_Surface *IMG_ReadXPMFromArray(char **xpm);

An example program 'showimage' is included, with source in showimage.c

JPEG support requires the JPEG library:
    IJG Homepage
PNG support requires the PNG library:
    PNG Homepage
  and the Zlib library:
    Zlib Homepage
TIFF support requires the TIFF library:
    SGI TIFF FTP Site

If you have these libraries installed in non-standard places, you can
try adding those paths to the configure script, e.g.
sh ./configure CPPFLAGS="-I/somewhere/include" LDFLAGS="-L/somewhere/lib"
If this works, you may need to add /somewhere/lib to your LD_LIBRARY_PATH
so shared library loading works correctly.

This library is under the GNU Library General Public License, see the file
"COPYING" for details.  Certain image loaders may be under a different
license, see the individual image loader source files for details.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2. Getting Started

This assumes you have gotten SDL_image and installed it on your system. SDL_image has an README document in the source distribution to help you get it compiled and installed. Well it at least points you to locations for the source code of some of the image libraries SDL_image can use. Most of the other image formats are builtin to SDL_image.

Generally, in UNIX-like environments, installation consists of:

 
./configure
make
make install

SDL_image supports loading and decoding images from the following formats:

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)

You may also want to look at some demonstration code which may be downloaded from:
http://www.jonatkins.org/SDL_image/

2.1 Includes  The include files to use for SDL_image
2.2 Compiling  Using the SDL_image library and header file.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.1 Includes

To use SDL_image functions in a C/C++ source code file, you must use the SDL_image.h include file:

#include "SDL_image.h"


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.2 Compiling

To link with SDL_image you should use sdl-config to get the required SDL compilation options. After that, compiling with SDL_image is quite easy.
Note: Some systems may not have the SDL_image library and include file in the same place as the SDL library and includes are located, in that case you will need to add more -I and -L paths to these command lines.

Simple Example for compiling an object file:

cc -c `sdl-config --cflags` mysource.c

Simple Example for compiling an object file:

cc -o myprogram mysource.o `sdl-config --libs` -lSDL_image

Now myprogram is ready to run.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3. Functions

These are the functions in the SDL_image API.

3.1 General  Versioning, Initialization and Cleanup
3.2 Loading  From Image Data to SDL_Surface
3.3 Info  Image Type Detection
3.4 Errors  Error Handling


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.1 General

These functions query, initialize, and cleanup the SDL_image library.

3.1.1 IMG_Linked_Version  Get version number
3.1.2 IMG_Init  Initialize SDL_image
3.1.3 IMG_Quit  Cleanup SDL_image


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.1.1 IMG_Linked_Version

const SDL_version *IMG_Linked_Version()
void SDL_IMAGE_VERSION(SDL_version *compile_version)

This works similar to SDL_Linked_Version and SDL_VERSION.
Using these you can compare the runtime version to the version that you compiled with.
These functions/macros do not require any library initialization calls before using them.

 
SDL_version compile_version;
const SDL_version *link_version=IMG_Linked_Version();
SDL_IMAGE_VERSION(&compile_version);
printf("compiled with SDL_image version: %d.%d.%d\n", 
        compile_version.major,
        compile_version.minor,
        compile_version.patch);
printf("running with SDL_image version: %d.%d.%d\n", 
        link_version->major,
        link_version->minor,
        link_version->patch);

See Also:
3.1.2 IMG_Init


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.1.2 IMG_Init

int IMG_Init(int flags)

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 IMG_isJPG, IMG_isPNG, and IMG_isTIF functions.
Note: this function does not always set the error string, so do not depend on IMG_GetError being meaningful all the time.

Returns: a bitmask of all the currently initted image loaders.

 
// load support for the JPG and PNG image formats
int flags=IMG_INIT_JPG|IMG_INIT_PNG;
int initted=IMG_Init(flags);
if(initted&flags != flags) {
    printf("IMG_Init: Failed to init required jpg and png support!\n");
    printf("IMG_Init: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.1.3 IMG_Quit


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.1.3 IMG_Quit

void IMG_Quit()

This function cleans up all dynamically loaded library handles, freeing memory. If support is required again it will be initialized again, either by IMG_Init or loading an image with dynamic support required. You may call this function when IMG_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 IMG_Init was called.

 
// unload the dynamically loaded image libraries
IMG_Quit();

See Also:
3.1.2 IMG_Init


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2 Loading

These functions create an SDL_Surface from image data either from a file, or SDL_RWop, or from an array of data in memory.

Automagic Loading
3.2.1 IMG_Load  Load from a file
3.2.2 IMG_Load_RW  Load using a SDL_RWop
3.2.3 IMG_LoadTyped_RW  Load more format specifically with a SDL_RWop
Specific Loaders
3.2.6 IMG_LoadBMP_RW  Load BMP using a SDL_RWop
3.2.4 IMG_LoadCUR_RW  Load CUR using a SDL_RWop
3.2.11 IMG_LoadGIF_RW  Load GIF using a SDL_RWop
3.2.5 IMG_LoadICO_RW  Load ICO using a SDL_RWop
3.2.12 IMG_LoadJPG_RW  Load JPG using a SDL_RWop
3.2.16 IMG_LoadLBM_RW  Load LBM using a SDL_RWop
3.2.10 IMG_LoadPCX_RW  Load PCX using a SDL_RWop
3.2.14 IMG_LoadPNG_RW  Load PNG using a SDL_RWop
3.2.7 IMG_LoadPNM_RW  Load PNM using a SDL_RWop
3.2.15 IMG_LoadTGA_RW  Load TGA using a SDL_RWop
3.2.13 IMG_LoadTIF_RW  Load TIF using a SDL_RWop
3.2.9 IMG_LoadXCF_RW  Load XCF using a SDL_RWop
3.2.8 IMG_LoadXPM_RW  Load XPM using a SDL_RWop
3.2.17 IMG_LoadXV_RW  Load XV using a SDL_RWop
Array Loaders
3.2.18 IMG_ReadXPMFromArray  Load XPM from compiled XPM data


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.1 IMG_Load

SDL_Surface *IMG_Load(const char *file)

file
Image file name to load a surface from.

Load file for use as an image in a new surface. 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.
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 IMG_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_SetColorKey(image, SDL_RLEACCEL, image->format->colorkey);

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, such as no support built for the image, or a file reading error.

 
// load sample.png into image
SDL_Surface *image;
image=IMG_Load("sample.png");
if(!image) {
    printf("IMG_Load: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.1.2 IMG_Init, 3.2.2 IMG_Load_RW, 3.2.3 IMG_LoadTyped_RW


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.2 IMG_Load_RW

SDL_Surface *IMG_Load_RW(SDL_RWops *src, int freesrc)

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.

Load src for use as a surface. This can load all supported image formats, except TGA. 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 IMG_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_SetColorKey(image, SDL_RLEACCEL, image->format->colorkey);

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors.

 
// load sample.png in to image
SDL_Surface *image;
image=IMG_Load_RW(SDL_RWFromFile("sample.png", "rb"), 1);
if(!image) {
    printf("IMG_Load_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.1.2 IMG_Init, 3.2.1 IMG_Load, 3.2.3 IMG_LoadTyped_RW


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.3 IMG_LoadTyped_RW

SDL_Surface *IMG_LoadTyped_RW(SDL_RWops *src, int freesrc, char *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.
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 IMG_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_SetColorKey(image, SDL_RLEACCEL, image->format->colorkey);

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors.

 
// load sample.tga into image
SDL_Surface *image;
image=IMG_LoadTyped_RW(SDL_RWFromFile("sample.tga", "rb"), 1, "TGA");
if(!image) {
    printf("IMG_LoadTyped_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.1.2 IMG_Init, 3.2.1 IMG_Load, 3.2.2 IMG_Load_RW


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.4 IMG_LoadCUR_RW

SDL_Surface *IMG_LoadCUR_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The icon image is loaded from this.

Load src as a Windows Cursor image for use as a surface, if BMP support is compiled into the SDL_image library. The CUR's mask is put into to per pixel alpha in the surface. For files with multiple images, the first one found with the highest color count is chosen.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if BMP is not supported, or a read error.

 
// load sample.cur into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.cur", "rb");
image=IMG_LoadCUR_RW(rwop);
if(!image) {
    printf("IMG_LoadCUR_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW, 3.3.1 IMG_isCUR


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.5 IMG_LoadICO_RW

SDL_Surface *IMG_LoadICO_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The icon image is loaded from this.

Load src as a Windows Icon image for use as a surface, if BMP support is compiled into the SDL_image library. The ICO's mask is put into to per pixel alpha in the surface. For files with multiple images, the first one found with the highest color count is chosen.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if BMP is not supported, or a read error.

 
// load sample.ico into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.ico", "rb");
image=IMG_LoadICO_RW(rwop);
if(!image) {
    printf("IMG_LoadICO_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW, 3.3.2 IMG_isICO


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.6 IMG_LoadBMP_RW

SDL_Surface *IMG_LoadBMP_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The BMP image is loaded from this.

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

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if BMP is not supported, or a read error.

 
// load sample.bmp into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.bmp", "rb");
image=IMG_LoadBMP_RW(rwop);
if(!image) {
    printf("IMG_LoadBMP_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW, 3.3.3 IMG_isBMP


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.7 IMG_LoadPNM_RW

SDL_Surface *IMG_LoadPNM_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The PNM image is loaded from this.

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

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if PNM is not supported, or a read error.

 
// load sample.pnm into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.pnm", "rb");
image=IMG_LoadPNM_RW(rwop);
if(!image) {
    printf("IMG_LoadPNM_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW, 3.3.4 IMG_isPNM


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.8 IMG_LoadXPM_RW

SDL_Surface *IMG_LoadXPM_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The XPM image is loaded from this.

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

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if XPM is not supported, or a read error.

 
// load sample.xpm into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.xpm", "rb");
image=IMG_LoadXPM_RW(rwop);
if(!image) {
    printf("IMG_LoadXPM_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW, 3.2.18 IMG_ReadXPMFromArray, 3.3.5 IMG_isXPM


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.9 IMG_LoadXCF_RW

SDL_Surface *IMG_LoadXCF_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The XCF image is loaded from this.

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

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if XCF is not supported, or a read error.

 
// load sample.xcf into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.xcf", "rb");
image=IMG_LoadXCF_RW(rwop);
if(!image) {
    printf("IMG_LoadXCF_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW, 3.3.6 IMG_isXCF


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.10 IMG_LoadPCX_RW

SDL_Surface *IMG_LoadPCX_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The PCX image is loaded from this.

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

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if PCX is not supported, or a read error.

 
// load sample.pcx into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.pcx", "rb");
image=IMG_LoadPCX_RW(rwop);
if(!image) {
    printf("IMG_LoadPCX_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW, 3.3.7 IMG_isPCX


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.11 IMG_LoadGIF_RW

SDL_Surface *IMG_LoadGIF_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The GIF image is loaded from this.

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

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if GIF is not supported, or a read error.

 
// load sample.gif into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.gif", "rb");
image=IMG_LoadGIF_RW(rwop);
if(!image) {
    printf("IMG_LoadGIF_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW, 3.3.8 IMG_isGIF


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.12 IMG_LoadJPG_RW

SDL_Surface *IMG_LoadJPG_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The JPG image is loaded from this.

Load src as a JPG image for use as a surface, if JPG support is compiled into the SDL_image library.
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 IMG_Init to load support for your image format.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if JPG is not supported, or a read error.

 
// load sample.jpg into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.jpg", "rb");
image=IMG_LoadJPG_RW(rwop);
if(!image) {
    printf("IMG_LoadJPG_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.1.2 IMG_Init, 3.2.3 IMG_LoadTyped_RW, 3.3.9 IMG_isJPG


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.13 IMG_LoadTIF_RW

SDL_Surface *IMG_LoadTIF_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The TIF image is loaded from this.

Load src as a TIF image for use as a surface, if TIF support is compiled into the SDL_image library.
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 IMG_Init to load support for your image format.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if TIF is not supported, or a read error.

 
// load sample.tif into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.tif", "rb");
image=IMG_LoadTIF_RW(rwop);
if(!image) {
    printf("IMG_LoadTIF_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.1.2 IMG_Init, 3.2.3 IMG_LoadTyped_RW, 3.3.10 IMG_isTIF


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.14 IMG_LoadPNG_RW

SDL_Surface *IMG_LoadPNG_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The PNG image is loaded from this.

Load src as a PNG image for use as a surface, if PNG support is compiled into the SDL_image library.
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 IMG_Init to load support for your image format.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if PNG is not supported, or a read error.

 
// load sample.png into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.png", "rb");
image=IMG_LoadPNG_RW(rwop);
if(!image) {
    printf("IMG_LoadPNG_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.1.2 IMG_Init, 3.2.3 IMG_LoadTyped_RW, 3.3.11 IMG_isPNG


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.15 IMG_LoadTGA_RW

SDL_Surface *IMG_LoadTGA_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The TGA image is loaded from this.

Load src as a TGA image for use as a surface, if TGA support is compiled into the SDL_image library. If you try to load a non TGA image, you might succeed even when it's not TGA image formatted data, this is because the TGA has no magic, which is a way of identifying a filetype from a signature in it's contents. So be careful with this.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if TGA is not supported, or a read error.

 
// load sample.tga into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.tga", "rb");
image=IMG_LoadTGA_RW(rwop);
if(!image) {
    printf("IMG_LoadTGA_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.16 IMG_LoadLBM_RW

SDL_Surface *IMG_LoadLBM_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The LBM image is loaded from this.

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

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if LBM is not supported, or a read error.

 
// load sample.lbm into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.lbm", "rb");
image=IMG_LoadLBM_RW(rwop);
if(!image) {
    printf("IMG_LoadLBM_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW, 3.3.12 IMG_isLBM


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.17 IMG_LoadXV_RW

SDL_Surface *IMG_LoadXV_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The XV image is loaded from this.

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

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if XV is not supported, or a read error.

 
// load sample.xv into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.xv", "rb");
image=IMG_LoadXV_RW(rwop);
if(!image) {
    printf("IMG_LoadXV_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW, 3.3.13 IMG_isXV


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.18 IMG_ReadXPMFromArray

SDL_Surface *IMG_ReadXPMFromArray(char **xpm)

xpm
The source xpm data. The XPM image is loaded from this. XPM files are C header files that define a char **variable, that variable name is what you use here.

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

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if XPM is not supported, or a read error.

 
// load sample.xpm into image
#include "sample.xpm"
SDL_Surface *image;
image=IMG_ReadXPMFromArray(sample_xpm);
if(!image) {
    printf("IMG_ReadXPMFromArray: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.8 IMG_LoadXPM_RW


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3 Info

These functions are tests for specific file formats. They also show if the format is supported in the linked SDL_image library, assuming you have a valid image of that type.

3.3.3 IMG_isBMP  Test for valid, supportted BMP file
3.3.1 IMG_isCUR  Test for valid, supportted CUR file
3.3.8 IMG_isGIF  Test for valid, supportted GIF file
3.3.2 IMG_isICO  Test for valid, supportted ICO file
3.3.9 IMG_isJPG  Test for valid, supportted JPG file
3.3.12 IMG_isLBM  Test for valid, supportted LBM file
3.3.7 IMG_isPCX  Test for valid, supportted PCX file
3.3.11 IMG_isPNG  Test for valid, supportted PNG file
3.3.4 IMG_isPNM  Test for valid, supportted PNM file
3.3.10 IMG_isTIF  Test for valid, supportted TIF file
3.3.6 IMG_isXCF  Test for valid, supportted XCF file
3.3.5 IMG_isXPM  Test for valid, supportted XPM file
3.3.13 IMG_isXV  Test for valid, supportted XV file


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3.1 IMG_isCUR

int IMG_isCUR(SDL_RWops *src)

src

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

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

 
// Test sample.cur to see if it is a CUR
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.cur", "rb");
if(IMG_isCUR(rwop))
	printf("sample.cur is a CUR file.\n");
else
	printf("sample.cur is not a CUR file, or BMP support is not available.\n");

See Also:
3.2.4 IMG_LoadCUR_RW, 3.2.3 IMG_LoadTyped_RW


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3.2 IMG_isICO

int IMG_isICO(SDL_RWops *src)

src

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

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

 
// Test sample.ico to see if it is an ICO
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.ico", "rb");
if(IMG_isICO(rwop))
	printf("sample.ico is an ICO file.\n");
else
	printf("sample.ico is not an ICO file, or BMP support is not available.\n");

See Also:
3.2.5 IMG_LoadICO_RW, 3.2.3 IMG_LoadTyped_RW


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3.3 IMG_isBMP

int IMG_isBMP(SDL_RWops *src)

src

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

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

 
// Test sample.bmp to see if it is a BMP
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.bmp", "rb");
if(IMG_isBMP(rwop))
	printf("sample.bmp is a BMP file.\n");
else
	printf("sample.bmp is not a BMP file, or BMP support is not available.\n");

See Also:
3.2.6 IMG_LoadBMP_RW, 3.2.3 IMG_LoadTyped_RW


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3.4 IMG_isPNM

int IMG_isPNM(SDL_RWops *src)

src

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

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

 
// Test sample.pnm to see if it is a PNM
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.pnm", "rb");
if(IMG_isPNM(rwop))
	printf("sample.pnm is a PNM file.\n");
else
	printf("sample.pnm is not a PNM file, or PNM support is not available.\n");

See Also:
3.2.7 IMG_LoadPNM_RW, 3.2.3 IMG_LoadTyped_RW


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3.5 IMG_isXPM

int IMG_isXPM(SDL_RWops *src)

src

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

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

 
// Test sample.xpm to see if it is a XPM
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.xpm", "rb");
if(IMG_isXPM(rwop))
	printf("sample.xpm is a XPM file.\n");
else
	printf("sample.xpm is not a XPM file, or XPM support is not available.\n");

See Also:
3.2.8 IMG_LoadXPM_RW, 3.2.3 IMG_LoadTyped_RW


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3.6 IMG_isXCF

int IMG_isXCF(SDL_RWops *src)

src

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

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

 
// Test sample.xcf to see if it is a XCF
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.xcf", "rb");
if(IMG_isXCF(rwop))
	printf("sample.xcf is a XCF file.\n");
else
	printf("sample.xcf is not a XCF file, or XCF support is not available.\n");

See Also:
3.2.9 IMG_LoadXCF_RW, 3.2.3 IMG_LoadTyped_RW


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3.7 IMG_isPCX

int IMG_isPCX(SDL_RWops *src)

src

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

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

 
// Test sample.pcx to see if it is a PCX
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.pcx", "rb");
if(IMG_isPCX(rwop))
	printf("sample.pcx is a PCX file.\n");
else
	printf("sample.pcx is not a PCX file, or PCX support is not available.\n");

See Also:
3.2.10 IMG_LoadPCX_RW, 3.2.3 IMG_LoadTyped_RW


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3.8 IMG_isGIF

int IMG_isGIF(SDL_RWops *src)

src

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

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

 
// Test sample.gif to see if it is a GIF
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.gif", "rb");
if(IMG_isGIF(rwop))
	printf("sample.gif is a GIF file.\n");
else
	printf("sample.gif is not a GIF file, or GIF support is not available.\n");

See Also:
3.2.11 IMG_LoadGIF_RW, 3.2.3 IMG_LoadTyped_RW


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3.9 IMG_isJPG

int IMG_isJPG(SDL_RWops *src)

src

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

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

 
// Test sample.jpg to see if it is a JPG
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.jpg", "rb");
if(IMG_isJPG(rwop))
	printf("sample.jpg is a JPG file.\n");
else
	printf("sample.jpg is not a JPG file, or JPG support is not available.\n");

See Also:
3.2.12 IMG_LoadJPG_RW, 3.2.3 IMG_LoadTyped_RW


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3.10 IMG_isTIF

int IMG_isTIF(SDL_RWops *src)

src

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

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

 
// Test sample.tif to see if it is a TIF
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.tif", "rb");
if(IMG_isTIF(rwop))
	printf("sample.tif is a TIF file.\n");
else
	printf("sample.tif is not a TIF file, or TIF support is not available.\n");

See Also:
3.2.13 IMG_LoadTIF_RW, 3.2.3 IMG_LoadTyped_RW


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3.11 IMG_isPNG

int IMG_isPNG(SDL_RWops *src)

src

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

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

 
// Test sample.png to see if it is a PNG
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.png", "rb");
if(IMG_isPNG(rwop))
	printf("sample.png is a PNG file.\n");
else
	printf("sample.png is not a PNG file, or PNG support is not available.\n");

See Also:
3.2.14 IMG_LoadPNG_RW, 3.2.3 IMG_LoadTyped_RW


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3.12 IMG_isLBM

int IMG_isLBM(SDL_RWops *src)

src

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

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

 
// Test sample.lbm to see if it is a LBM
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.lbm", "rb");
if(IMG_isLBM(rwop))
	printf("sample.lbm is a LBM file.\n");
else
	printf("sample.lbm is not a LBM file, or LBM support is not available.\n");

See Also:
3.2.16 IMG_LoadLBM_RW, 3.2.3 IMG_LoadTyped_RW


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3.13 IMG_isXV

int IMG_isXV(SDL_RWops *src)

src

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

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

 
// Test sample.xv to see if it is an XV thumbnail
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.xv", "rb");
if(IMG_isXV(rwop))
	printf("sample.xv is an XV file.\n");
else
	printf("sample.xv is not an XV file, or XV support is not available.\n");

See Also:
3.2.17 IMG_LoadXV_RW, 3.2.3 IMG_LoadTyped_RW


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.4 Errors

These functions are used for error status strings that should help the user and developer understand why a function failed.

3.4.1 IMG_SetError  Set the current error string
3.4.2 IMG_GetError  Get the current error string


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.4.1 IMG_SetError

void IMG_SetError(const char *fmt, ...)

This is the same as SDL_SetError, which sets the error string which may be fetched with IMG_GetError (or SDL_GetError). This functions acts like printf, except that it is limited to SDL_ERRBUFIZE(1024) chars in length. It only accepts the following format types: %s, %d, %f, %p. No variations are supported, like %.2f would not work. For any more specifics read the SDL docs.

 
int myimagefunc(int i) {
    IMG_SetError("myimagefunc is not implemented! %d was passed in.",i);
    return(-1);
}

See Also:
3.4.2 IMG_GetError


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.4.2 IMG_GetError

char *IMG_GetError()

This is the same as SDL_GetError, which returns the last error set as a string which you may use to tell the user what happened when an error status has been returned from an SDL_image function call.

Returns: a char pointer (string) containing a humam readble version or the reason for the last error that occured.

 
printf("Oh My Goodness, an error : %s", IMG_GetError());

See Also:
3.4.1 IMG_SetError


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4. Defines

IMG_MAJOR_VERSION
1
SDL_image library major number at compilation time
IMG_MINOR_VERSION
2
SDL_image library minor number at compilation time
IMG_PATCHLEVEL
8
SDL_image library patch level at compilation time
IMG_INIT_JPG
1
IMG_Init JPG image format support flag
IMG_INIT_PNG
2
IMG_Init PNG image format support flag
IMG_INIT_TIF
4
IMG_Init TIF image format support flag


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Index

Jump to:   I   R   S  

Index Entry Section

I
IMG_GetError3.4.2 IMG_GetError
IMG_Init3.1.2 IMG_Init
IMG_INIT_JPG4. Defines
IMG_INIT_PNG4. Defines
IMG_INIT_TIF4. Defines
IMG_isBMP3.3.3 IMG_isBMP
IMG_isCUR3.3.1 IMG_isCUR
IMG_isGIF3.3.8 IMG_isGIF
IMG_isICO3.3.2 IMG_isICO
IMG_isJPG3.3.9 IMG_isJPG
IMG_isLBM3.3.12 IMG_isLBM
IMG_isPCX3.3.7 IMG_isPCX
IMG_isPNG3.3.11 IMG_isPNG
IMG_isPNM3.3.4 IMG_isPNM
IMG_isTIF3.3.10 IMG_isTIF
IMG_isXCF3.3.6 IMG_isXCF
IMG_isXPM3.3.5 IMG_isXPM
IMG_isXV3.3.13 IMG_isXV
IMG_Linked_Version3.1.1 IMG_Linked_Version
IMG_Load3.2.1 IMG_Load
IMG_Load_RW3.2.2 IMG_Load_RW
IMG_LoadBMP_RW3.2.6 IMG_LoadBMP_RW
IMG_LoadCUR_RW3.2.4 IMG_LoadCUR_RW
IMG_LoadGIF_RW3.2.11 IMG_LoadGIF_RW
IMG_LoadICO_RW3.2.5 IMG_LoadICO_RW
IMG_LoadJPG_RW3.2.12 IMG_LoadJPG_RW
IMG_LoadLBM_RW3.2.16 IMG_LoadLBM_RW
IMG_LoadPCX_RW3.2.10 IMG_LoadPCX_RW
IMG_LoadPNG_RW3.2.14 IMG_LoadPNG_RW
IMG_LoadPNM_RW3.2.7 IMG_LoadPNM_RW
IMG_LoadTGA_RW3.2.15 IMG_LoadTGA_RW
IMG_LoadTIF_RW3.2.13 IMG_LoadTIF_RW
IMG_LoadTyped_RW3.2.3 IMG_LoadTyped_RW
IMG_LoadXCF_RW3.2.9 IMG_LoadXCF_RW
IMG_LoadXPM_RW3.2.8 IMG_LoadXPM_RW
IMG_LoadXV_RW3.2.17 IMG_LoadXV_RW
IMG_MAJOR_VERSION4. Defines
IMG_MINOR_VERSION4. Defines
IMG_PATCHLEVEL4. Defines
IMG_Quit3.1.3 IMG_Quit
IMG_ReadXPMFromArray3.2.18 IMG_ReadXPMFromArray
IMG_SetError3.4.1 IMG_SetError

R
README1. Overview

S
sdl-config2.2 Compiling
SDL_IMAGE_VERSION3.1.1 IMG_Linked_Version
SDL_Surface3.2 Loading

Jump to:   I   R   S  


[Top] [Contents] [Index] [ ? ]

Table of Contents


[Top] [Contents] [Index] [ ? ]

Short Table of Contents

1. Overview
2. Getting Started
3. Functions
4. Defines
Index

[Top] [Contents] [Index] [ ? ]

About this document

This document was generated on November, 3 2009 using texi2html

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ < ] Back previous section in reading order 1.2.2
[ > ] Forward next section in reading order 1.2.4
[ << ] FastBack previous or up-and-previous section 1.1
[ Up ] Up up section 1.2
[ >> ] FastForward next or up-and-next section 1.3
[Top] Top cover (top) of document  
[Contents] Contents table of contents  
[Index] Index concept index  
[ ? ] About this page  

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

This document was generated on November, 3 2009 using texi2html