sdl2.sdlimage - Python bindings for SDL_image
py-sdl2 provides bindings for SDL2_image, a library designed for use with SDL2
that adds support for loading a wide range of different common (and uncommon)
image formats for easy use with SDL2. In addition, SDL2_image includes functions
for saving SDL_Surface
objects to PNG and/or JPEG images.
Table Of Contents
Note
If using an alternative rendering system that doesn’t use SDL surfaces as input (e.g. PyOpenGL), the Pillow imaging library may be a better fit for your project.
Initialization and library information functions
- sdl2.sdlimage.IMG_Init(flags)[source]
Initializes the SDL2_image library.
Calling this function enables support for the JPEG, PNG, TIF, and/or WebP image formats as requested by the init flags. All other image formats can be loaded or used regardless of whether this has been called.
The following init flags are supported:
Format
Init flag
JPEG
IMG_INIT_JPG
PNG
IMG_INIT_PNG
TIFF
IMG_INIT_TIF
WebP
IMG_INIT_WEBP
This can be called multiple times to enable support for these formats separately, or can initialize multiple formats at once by passing a set of flags as a bitwise OR. You can also call this function with 0 as a flag to check which image libraries have already been loaded, or to test whether a given image format is available on the current system:
# Initialize JPEG and PNG support separately for flag in [IMG_INIT_JPG, IMG_INIT_PNG]: IMG_Init(flag) err = IMG_GetError() # check for any errors loading library if len(err): print(err) # Initialize JPEG and PNG support at the same time flags = IMG_INIT_JPG | IMG_INIT_PNG IMG_Init(flags) if IMG_Init(0) != flags: # verify both libraries loaded properly print(IMG_GetError())
- sdl2.sdlimage.IMG_Quit()[source]
De-initializes the SDL2_image library.
Calling this function disables JPEG, PNG, TIF, and WEBP support and frees all associated memory. Once this has been called, you can re-initialize support for those image formats using
IMG_Init()
and the corresponding init flags.You only need to call this function once, no matter how many times
IMG_Init()
was called.
- sdl2.sdlimage.IMG_GetError()
Returns the most recently encountered SDL2 error message, if any.
This function is a simple wrapper around
SDL_GetError()
.- Retuns
A UTF-8 encoded string describing the most recent SDL2 error.
- Return type
- sdl2.sdlimage.IMG_SetError(fmt)
Sets the most recent SDL2 error message to a given string.
This function is a simple wrapper around
SDL_SetError()
.
Image format-checking functions
These functions are used to check whether an SDL file object
(SDL_RWops
) is a valid image file of a given format. Note that
all of these functions will return 0 if SDL2_image was not built with
support for that format, even if it is a valid image of that type, so be
cautious when using these for formats like WEBP, JPEG, PNG, and TIFF, which
are optional when building SDL2_image.
- sdl2.sdlimage.IMG_isICO(src)[source]
Tests whether a file object contains an ICO (Windows icon) image.
The ICO format
- Parameters
src (
SDL_RWops
) – The file object to check.- Returns
1 if BMPs are supported and file is a valid ICO, otherwise 0.
- Return type
- sdl2.sdlimage.IMG_isCUR(src)[source]
Tests whether a file object contains a CUR (Windows cursor) image.
- Parameters
src (
SDL_RWops
) – The file object to check.- Returns
1 if BMPs are supported and file is a valid CUR, otherwise 0.
- Return type
- sdl2.sdlimage.IMG_isBMP(src)[source]
Tests whether a file object contains a BMP (Windows bitmap) image.
- Parameters
src (
SDL_RWops
) – The file object to check.- Returns
1 if BMPs are supported and file is a valid BMP, otherwise 0.
- Return type
- sdl2.sdlimage.IMG_isGIF(src)[source]
Tests whether a file object contains a GIF image.
- Parameters
src (
SDL_RWops
) – The file object to check.- Returns
1 if GIFs are supported and file is a valid GIF, otherwise 0.
- Return type
- sdl2.sdlimage.IMG_isJPG(src)[source]
Tests whether a file object contains a JPEG image.
- Parameters
src (
SDL_RWops
) – The file object to check.- Returns
1 if JPEGs are supported and file is a valid JPEG, otherwise 0.
- Return type
- sdl2.sdlimage.IMG_isLBM(src)[source]
Tests whether a file object contains an LBM (Interleaved Bitmap) image.
- Parameters
src (
SDL_RWops
) – The file object to check.- Returns
1 if LBMs are supported and file is a valid LBM, otherwise 0.
- Return type
- sdl2.sdlimage.IMG_isPCX(src)[source]
Tests whether a file object contains a PCX (IBM PC Paintbrush) image.
- Parameters
src (
SDL_RWops
) – The file object to check.- Returns
1 if PCXs are supported and file is a valid PCX, otherwise 0.
- Return type
- sdl2.sdlimage.IMG_isPNG(src)[source]
Tests whether a file object contains a PNG image.
- Parameters
src (
SDL_RWops
) – The file object to check.- Returns
1 if PNGs are supported and file is a valid PNG, otherwise 0.
- Return type
- sdl2.sdlimage.IMG_isPNM(src)[source]
Tests whether a file object contains a PNM (Portable Anymap) image.
- Parameters
src (
SDL_RWops
) – The file object to check.- Returns
1 if PNMs are supported and file is a valid PNM, otherwise 0.
- Return type
- sdl2.sdlimage.IMG_isSVG(src)[source]
Tests whether a file object contains an SVG image.
Note
This function is only available in SDL_image 2.0.2 or later.
- Parameters
src (
SDL_RWops
) – The file object to check.- Returns
1 if SVGs are supported and file is a valid SVG, otherwise 0.
- Return type
- sdl2.sdlimage.IMG_isTIF(src)[source]
Tests whether a file object contains a TIFF image.
- Parameters
src (
SDL_RWops
) – The file object to check.- Returns
1 if TIFFs are supported and file is a valid TIFF, otherwise 0.
- Return type
- sdl2.sdlimage.IMG_isXCF(src)[source]
Tests whether a file object contains an XCF (native GIMP format) image.
Note
XCF support is currently missing in official macOS binaries
- Parameters
src (
SDL_RWops
) – The file object to check.- Returns
1 if XCFs are supported and file is a valid XCF, otherwise 0.
- Return type
- sdl2.sdlimage.IMG_isXPM(src)[source]
Tests whether a file object contains an XPM (X11 Pixmap) image.
- Parameters
src (
SDL_RWops
) – The file object to check.- Returns
1 if XPMs are supported and file is a valid XPM, otherwise 0.
- Return type
General image loading functions
- sdl2.sdlimage.IMG_Load(file)[source]
Loads an image file to a new surface.
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 keep the loaded images around until you are really done with them, as disk speed and image conversion to a surface can be slow.
Once you are done with a loaded image, you can call
SDL_FreeSurface()
on the returned surface pointer to free up the memory associated with it.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.contents.format.colorkey)
Note
If the loader for the image’s format requires initialization (e.g. PNG) and it is not already initialized, this function will attempt to load it automatically.
- Parameters
file (bytes) – A UTF8-encoded bytestring containing the path to the image file to load.
- Returns
A pointer to the new surface containing the image, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlimage.IMG_Load_RW(src, freesrc)[source]
Loads an image file from an SDL2 file object to a new surface.
This can load all supported formats, except TGA. See
IMG_Load()
for more information.- Parameters
src (
SDL_RWops
) – The file object from which to load the image.freesrc (int) – If non-zero, the input file object will be closed and freed after it has been read.
- Returns
A pointer to the new surface containing the image, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlimage.IMG_LoadTyped_RW(src, freesrc, type)[source]
Loads an image file from an SDL2 file object as a specific format.
This function allows you to explicitly specify the format type of the image to load. Here are the different possible image format strings:
Format String
Format Type
b”TGA”
TrueVision Targa
b”CUR”
Windows Cursor
b”ICO”
Windows Icon
b”BMP”
Windows Bitmap
b”GIF”
Graphics Interchange Format
b”JPG”
JPEG
b”LBM”
Interleaved Bitmap
b”PCX”
IBM PC Paintbrush
b”PNG”
Portable Network Graphics
b”PNM”
Portable Anymap
b”SVG”
Scalable Vector Graphics
b”TIF”
Tagged Image File Format
b”XCF”
GIMP native format
b”XPM”
X11 Pixmap
b”XV”
XV Thumbnail
b”WEBP”
WebP
See
IMG_Load()
for more information.- Parameters
- Returns
A pointer to the new surface containing the image, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlimage.IMG_LoadTexture(renderer, file)[source]
Loads an image file to a new texture using a given renderer.
This function 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 keep the loaded images around until you are really done with them, as disk speed and image conversion to a texture can be slow.
Once you are done with a loaded image, you can call
SDL_DestroyTexture()
on the returned texture pointer to free up the memory associated with it.Note
If the image loader for the format of the given image requires initialization (e.g. PNG) and it is not already initialized, this function will attempt to load it automatically.
- Parameters
renderer (
SDL_Renderer
) – The SDL rendering context with which to create the texture.file (bytes) – A UTF8-encoded bytestring containing the path to the image file to load.
- Returns
A pointer to the new texture containing the image, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Texture
)
- sdl2.sdlimage.IMG_LoadTexture_RW(renderer, src, freesrc)[source]
Loads an image from a file object to a texture using a given renderer.
This function can load all supported formats, except TGA. See
IMG_LoadTexture()
for more information.- Parameters
renderer (
SDL_Renderer
) – The SDL rendering context with which to create the texture.src (
SDL_RWops
) – The file object from which to load the image.freesrc (int) – If non-zero, the input file object will be closed and freed after it has been read.
- Returns
A pointer to the new texture containing the image, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Texture
)
- sdl2.sdlimage.IMG_LoadTextureTyped_RW(renderer, src, freesrc, type)[source]
Loads an image file from a file object to a texture as a specific format.
This function allows you to explicitly specify the format type of the image to load. The different possible format strings are listed in the documentation for
IMG_LoadTyped_RW()
.See
IMG_LoadTexture()
for more information.- Parameters
renderer (
SDL_Renderer
) – The SDL rendering context with which to create the texture.src (
SDL_RWops
) – The file object from which to load the image.freesrc (int) – If non-zero, the input file object will be closed and freed after it has been read.
type (bytes) – A bytestring indicating the image format with which the file object should be loaded.
- Returns
A pointer to the new texture containing the image, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Texture
)
Format-specific image loading functions
- sdl2.sdlimage.IMG_LoadICO_RW(src)[source]
Loads an ICO (Windows icon) image from an SDL file object.
Use the
IMG_GetError()
function to check for any errors.- Parameters
src (
SDL_RWops
) – The file object from which to load the ICO.- Returns
A pointer to a new surface containing the image, or
None
if there was an error.- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlimage.IMG_LoadCUR_RW(src)[source]
Loads a CUR (Windows cursor) image from an SDL file object.
Use the
IMG_GetError()
function to check for any errors.- Parameters
src (
SDL_RWops
) – The file object from which to load the CUR.- Returns
A pointer to a new surface containing the image, or
None
if there was an error.- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlimage.IMG_LoadBMP_RW(src)[source]
Loads a BMP (Windows bitmap) image from an SDL file object.
Use the
IMG_GetError()
function to check for any errors.- Parameters
src (
SDL_RWops
) – The file object from which to load the BMP.- Returns
A pointer to a new surface containing the image, or
None
if there was an error.- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlimage.IMG_LoadGIF_RW(src)[source]
Loads a GIF (Graphics Interchange Format) image from an SDL file object.
Use the
IMG_GetError()
function to check for any errors.- Parameters
src (
SDL_RWops
) – The file object from which to load the GIF.- Returns
A pointer to a new surface containing the image, or
None
if there was an error.- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlimage.IMG_LoadJPG_RW(src)[source]
Loads a JPEG image from an SDL file object.
Use the
IMG_GetError()
function to check for any errors.- Parameters
src (
SDL_RWops
) – The file object from which to load the JPEG.- Returns
A pointer to a new surface containing the image, or
None
if there was an error.- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlimage.IMG_LoadLBM_RW(src)[source]
Loads an LBM (Interleaved Bitmap) image from an SDL file object.
Use the
IMG_GetError()
function to check for any errors.- Parameters
src (
SDL_RWops
) – The file object from which to load the LBM.- Returns
A pointer to a new surface containing the image, or
None
if there was an error.- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlimage.IMG_LoadPCX_RW(src)[source]
Loads a PCX (IBM PC Paintbrush) image from an SDL file object.
Use the
IMG_GetError()
function to check for any errors.- Parameters
src (
SDL_RWops
) – The file object from which to load the PCX.- Returns
A pointer to a new surface containing the image, or
None
if there was an error.- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlimage.IMG_LoadPNG_RW(src)[source]
Loads a PNG image from an SDL file object.
Use the
IMG_GetError()
function to check for any errors.- Parameters
src (
SDL_RWops
) – The file object from which to load the PNG.- Returns
A pointer to a new surface containing the image, or
None
if there was an error.- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlimage.IMG_LoadPNM_RW(src)[source]
Loads a PNM (Portable Anymap) image from an SDL file object.
Use the
IMG_GetError()
function to check for any errors.- Parameters
src (
SDL_RWops
) – The file object from which to load the PNM.- Returns
A pointer to a new surface containing the image, or
None
if there was an error.- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlimage.IMG_LoadSVG_RW(src)[source]
Loads an SVG image from an SDL file object.
Note
This function is only available in SDL_image 2.0.2 or later.
Use the
IMG_GetError()
function to check for any errors.- Parameters
src (
SDL_RWops
) – The file object from which to load the SVG.- Returns
A pointer to a new surface containing the image, or
None
if there was an error.- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlimage.IMG_LoadTGA_RW(src)[source]
Loads a TGA (TrueVision Targa) image from an SDL file object.
Use the
IMG_GetError()
function to check for any errors.- Parameters
src (
SDL_RWops
) – The file object from which to load the TGA.- Returns
A pointer to a new surface containing the image, or
None
if there was an error.- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlimage.IMG_LoadTIF_RW(src)[source]
Loads a TIFF (Tagged Image File Format) image from an SDL file object.
Use the
IMG_GetError()
function to check for any errors.- Parameters
src (
SDL_RWops
) – The file object from which to load the TIFF.- Returns
A pointer to a new surface containing the image, or
None
if there was an error.- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlimage.IMG_LoadXCF_RW(src)[source]
Loads an TIFF (native GIMP format) image from an SDL file object.
Use the
IMG_GetError()
function to check for any errors.- Parameters
src (
SDL_RWops
) – The file object from which to load the XCF.- Returns
A pointer to a new surface containing the image, or
None
if there was an error.- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlimage.IMG_LoadXPM_RW(src)[source]
Loads an XPM (X11 Pixmap) image from an SDL file object.
Use the
IMG_GetError()
function to check for any errors.- Parameters
src (
SDL_RWops
) – The file object from which to load the XPM.- Returns
A pointer to a new surface containing the image, or
None
if there was an error.- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlimage.IMG_LoadXV_RW(src)[source]
Loads an XV thumbnail (XV Visual Schnauzer) from an SDL file object.
Use the
IMG_GetError()
function to check for any errors.- Parameters
src (
SDL_RWops
) – The file object from which to load the XV.- Returns
A pointer to a new surface containing the image, or
None
if there was an error.- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlimage.IMG_LoadWEBP_RW(src)[source]
Loads a WebP image from an SDL file object.
Use the
IMG_GetError()
function to check for any errors.- Parameters
src (
SDL_RWops
) – The file object from which to load the WebP.- Returns
A pointer to a new surface containing the image, or
None
if there was an error.- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlimage.IMG_ReadXPMFromArray(xpm)[source]
Loads an X11 Pixmap from an array to a new surface.
The XPM format consists of a C header with an array of strings defining the dimensions, colors, and pixels of a pixel art image: this is the data format that this function expects to be passed.
The input string for this function must be cast to a
ctypes.c_char_p
(pointer to a character array) and passed by reference usingctypes.byref()
.- Parameters
xpm (byref(
ctypes.c_char_p
)) – A pointer to a ctypes string defining an XPM image.- Returns
A pointer to a new surface containing the image, or
None
if there was an error.- Return type
POINTER(
SDL_Surface
)
Image writing functions
- sdl2.sdlimage.IMG_SavePNG(surface, file)[source]
Saves an SDL surface to a PNG file.
Note
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.- Parameters
surface (
SDL_Surface
) – The surface to be saved to PNG.file (bytes) – A UTF-8 encoded bytestring containing the path at which to save the PNG.
- Returns
0 on success or a negative error code on failure, can call
IMG_GetError()
for more information.- Return type
- sdl2.sdlimage.IMG_SavePNG_RW(surface, dst, freedst)[source]
Saves an SDL surface to a file object containing a PNG.
See
IMG_SavePNG()
for more information.- Parameters
surface (
SDL_Surface
) – The surface to be saved to PNG.dst (
SDL_RWops
) – The destination file object for the saved PNG.freedst (int) – 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, can call
IMG_GetError()
for more information.- Return type
- sdl2.sdlimage.IMG_SaveJPG(surface, file, quality)[source]
Saves an SDL surface to a JPEG file at a given quality.
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 withIMG_GetError()
.Note
As of SDL_image 2.0.5, JPEG saving is not supported by the official libsdl.org macOS binaries.
- Parameters
- Returns
0 on success or a negative error code on failure, can call
IMG_GetError()
for more information.- Return type
- sdl2.sdlimage.IMG_SaveJPG_RW(surface, dst, freedst, quality)[source]
Saves an SDL surface to a file object containing a JPEG.
Note
As of SDL_image 2.0.5, JPEG saving is not supported by the official libsdl.org macOS binaries.
- Parameters
- Returns
0 on success or a negative error code on failure, can call
IMG_GetError()
for more information.- Return type
Module constants
- sdl2.sdlimage.IMG_MAJOR_VERSION
Latest SDL2_image library major number supported by PySDL2.
- sdl2.sdlimage.IMG_MINOR_VERSION
Latest SDL2_image library minor number supported by PySDL2.
- sdl2.sdlimage.IMG_PATCHLEVEL
Latest SDL2_image library patch level number supported by PySDL2.
- sdl2.sdlimage.IMG_INIT_JPG
IMG_Init()
flag to enable support for the JPEG image format.
- sdl2.sdlimage.IMG_INIT_PNG
IMG_Init()
flag to enable support for the PNG image format.
- sdl2.sdlimage.IMG_INIT_TIF
IMG_Init()
flag to enable support for the TIFF image format.
- sdl2.sdlimage.IMG_INIT_WEBP
IMG_Init()
flag to enable support for the WEBP image format.