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

For a list of supported image formats, see the `IMG_LoadTyped_RW()` documentation.

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)

  Initializes the SDL_image library.

  Calling this function enables support for the JPEG, PNG, TIF, WebP, JPEG XL, and/or AVIF 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 | Since
  --- | --- | ---
  JPEG | `IMG_INIT_JPG` | 2.0.0
  PNG | `IMG_INIT_PNG` | 2.0.0
  TIFF | `IMG_INIT_TIF` | 2.0.0
  WebP | `IMG_INIT_WEBP` | 2.0.0
  JPEG XL | `IMG_INIT_JXL` | 2.6.0
  AVIF | `IMG_INIT_AVIF` | 2.6.0

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

  Note

  AVIF and JPEG XL support are not included in the official SDL_image binaries, and are likewise not enabled on most Linux distributions.

  Parameters:

    flags (int) – A bitwise OR’d set of the flags of the image formats to load support for.

  Returns:

    A bitmask of all the currently initialized image loaders.

  Return type:

    int

sdl2.sdlimage.IMG_Quit()

  De-initializes the SDL_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:

    bytes

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

  Parameters:

    fmt (bytes) – A UTF-8 encoded string containing the error message to set.

  Retuns:

    Always returns `-1`.

  Return type:

    int

sdl2.sdlimage.IMG_Linked_Version()

  Gets the version of the dynamically-linked SDL_image library.

  Returns:

    A pointer to a structure containing the version of the SDL_image library currently in use.

  Return type:

    POINTER(`SDL_version`)

## 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, AVIF, JXL, and TIFF, which are optional when building SDL2_image.

sdl2.sdlimage.IMG_isAVIF(src)

  Tests whether a file object contains an AVIF image.

  Note: Added in SDL_image 2.6.0

  Parameters:

    src (`SDL_RWops`) – The file object to check.

  Returns:

    1 if AVIFs are supported and file is a valid AVIF, otherwise 0.

  Return type:

    int

sdl2.sdlimage.IMG_isICO(src)

  Tests whether a file object contains an ICO (Windows icon) image.

  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:

    int

sdl2.sdlimage.IMG_isCUR(src)

  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:

    int

sdl2.sdlimage.IMG_isBMP(src)

  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:

    int

sdl2.sdlimage.IMG_isGIF(src)

  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:

    int

sdl2.sdlimage.IMG_isJPG(src)

  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:

    int

sdl2.sdlimage.IMG_isJXL(src)

  Tests whether a file object contains a JPEG XL image.

  Note: Added in SDL_image 2.6.0

  Parameters:

    src (`SDL_RWops`) – The file object to check.

  Returns:

    1 if JPEG XL is supported and file is a valid JXL, otherwise 0.

  Return type:

    int

sdl2.sdlimage.IMG_isLBM(src)

  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:

    int

sdl2.sdlimage.IMG_isPCX(src)

  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:

    int

sdl2.sdlimage.IMG_isPNG(src)

  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:

    int

sdl2.sdlimage.IMG_isPNM(src)

  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:

    int

sdl2.sdlimage.IMG_isSVG(src)

  Tests whether a file object contains an SVG image.

  Note: Added in SDL_image 2.0.2

  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:

    int

sdl2.sdlimage.IMG_isQOI(src)

  Tests whether a file object contains a QOI image.

  Note: Added in SDL_image 2.6.0

  Parameters:

    src (`SDL_RWops`) – The file object to check.

  Returns:

    1 if QOI is supported and file is a valid QOI, otherwise 0.

  Return type:

    int

sdl2.sdlimage.IMG_isTIF(src)

  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:

    int

sdl2.sdlimage.IMG_isXCF(src)

  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:

    int

sdl2.sdlimage.IMG_isXPM(src)

  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:

    int

sdl2.sdlimage.IMG_isXV(src)

  Tests whether a file object contains an XV (XV Visual Schnauzer) image.

  Parameters:

    src (`SDL_RWops`) – The file object to check.

  Returns:

    1 if XVs are supported and file is a valid XV, otherwise 0.

  Return type:

    int

sdl2.sdlimage.IMG_isWEBP(src)

  Tests whether a file object contains a WebP image.

  Parameters:

    src (`SDL_RWops`) – The file object to check.

  Returns:

    1 if WebPs are supported and file is a valid WebP, otherwise 0.

  Return type:

    int

## General image loading functions

sdl2.sdlimage.IMG_Load(file)

  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)

  Loads an image file from an SDL 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)

  Loads an image file from an SDL 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
  b”QOI” | Quite OK Image
  b”JXL” | JPEG XL
  b”AVIF” | AV1 Image File Format

  Note that loading QOI, JXL, and AVIF images requires SDL_image 2.6.0 or newer. 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.

    - type (bytes) – A bytestring indicating the image format with which the file object should be loaded.

  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)

  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)

  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)

  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_LoadAVIF_RW(src)

  Loads an AVIF image from an SDL file object.

  Use the `IMG_GetError()` function to check for any errors.

  Note: Added in SDL_image 2.6.0

  Parameters:

    src (`SDL_RWops`) – The file object from which to load the AVIF.

  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_LoadICO_RW(src)

  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)

  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)

  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)

  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)

  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_LoadJXL_RW(src)

  Loads a JPEG XL image from an SDL file object.

  Use the `IMG_GetError()` function to check for any errors.

  Note: Added in SDL_image 2.6.0

  Parameters:

    src (`SDL_RWops`) – The file object from which to load the JPEG XL.

  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)

  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)

  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)

  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)

  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)

  Loads an SVG image from an SDL file object.

  Note that this function only loads SVGs at their self-reported resolutions. To load an SVG at an arbitrary resolution, see `IMG_LoadSizedSVG_RW()`. Use the `IMG_GetError()` function to check for any errors.

  Note: Added in SDL_image 2.0.2

  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_LoadSizedSVG_RW(src, width, height)

  Loads an SVG image at a given size from an SDL file object.

  Use the `IMG_GetError()` function to check for any errors.

  Note: Added in SDL_image 2.6.0

  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_LoadQOI_RW(src)

  Loads a QOI image from an SDL file object.

  Use the `IMG_GetError()` function to check for any errors.

  Note: Added in SDL_image 2.6.0

  Parameters:

    src (`SDL_RWops`) – The file object from which to load the QOI.

  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)

  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)

  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)

  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)

  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)

  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)

  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)

  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 using `ctypes.byref()`.

  Note that this function will return an 8-bit indexed (palette) surface when possible. To obtain a 32-bit RGB surface from an XPM array, use the `IMG_ReadXPMFromArrayToRGB888()` function.

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

sdl2.sdlimage.IMG_ReadXPMFromArrayToRGB888(xpm)

  Loads an X11 Pixmap from an array to a new 32-bit surface.

  This function is the same as `IMG_ReadXPMFromArray()` except that it always returns a 32-bit ARGB surface.

  Note: Added in SDL_image 2.6.0

  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)

  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:

    int

sdl2.sdlimage.IMG_SavePNG_RW(surface, dst, freedst)

  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:

    int

sdl2.sdlimage.IMG_SaveJPG(surface, file, quality)

  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 with `IMG_GetError()`.

  Note

  JPEG saving was not supported in the official libsdl.org macOS binaries until SDL_image 2.6.0.

  Parameters:

    - surface (`SDL_Surface`) – The surface to be saved to JPEG.

    - file (bytes) – A UTF-8 encoded bytestring containing the path at which to save the PNG.

    - quality (int) – The compression level of the saved JPEG, from 1 (lowest quality) to 100 (highest quality).

  Returns:

    0 on success or a negative error code on failure, can call `IMG_GetError()` for more information.

  Return type:

    int

sdl2.sdlimage.IMG_SaveJPG_RW(surface, dst, freedst, quality)

  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:

    - surface (`SDL_Surface`) – The surface to be saved to JPEG.

    - file (bytes) – A UTF-8 encoded bytestring containing the path at which to save the PNG.

    - quality (int) – The compression level of the saved JPEG, from 1 (lowest quality) to 100 (highest quality).

  Returns:

    0 on success or a negative error code on failure, can call `IMG_GetError()` for more information.

  Return type:

    int

## Animation objects and functions

class sdl2.sdlimage.IMG_Animation

  A structure containing the frame data for an animation.

  When working with this data structure in Python, you need to be careful not to access an out-of-range frame or delay number to avoid illegal memory access problems. To convert the animation data to a more Pythonic format, you can do something similar to the example below:

      # Load animation and verify it loaded correctly
      anim = sdlimage.IMG_LoadAnimation("test.gif").contents
      if not anim:
          err = sdlimage.IMG_GetError()
          raise RuntimeError(err.encode("utf-8"))

      # Load frames/delays from the IMG_Animation structure to lists
      frames = []
      delays = []
      for frame in range(anim.count):
          frames.append(anim.frames[frame].contents)
          delays.append(anim.delays[frame])

  Note that even if you copy the frame surfaces into a Python list, the pixel data will still be stored within the animation object. As such, you cannot call `IMG_FreeAnimation()` on an object until you are fully done with its data.

  w

    The width (in pixels) of the animation.

    Type:

      int

  h

    The height (in pixels) of the animation.

    Type:

      int

  count

    The number of frames in the animation.

    Type:

      int

  frames

    An array of pointers (of length `count`) to the SDL surfaces for the frames of the animation.

    Type:

      POINTER(POINTER(`SDL_Surface`))

  delays

    An array (of length `count`) containing the delays (in milliseconds) between each frame in the animation.

    Type:

      POINTER(int)

sdl2.sdlimage.IMG_LoadAnimation(file)

  Loads an animated image from a file.

  For more information on how to work with imported animations, see the `IMG_Animation` documentation. As of SDL_image 2.6.0, this currently only supports GIF animations.

  Note: Added in SDL_image 2.6.0

  Parameters:

    file (bytes) – A UTF8-encoded bytestring containing the path to the animation file to load.

  Returns:

    A pointer to an animation object, or a null pointer if there was an error.

  Return type:

    POINTER(`IMG_Animation`)

sdl2.sdlimage.IMG_LoadAnimation_RW(src, freesrc)

  Loads an animated image from an SDL file object.

  For more information on how to work with imported animations, see the `IMG_Animation` documentation. As of SDL_image 2.6.0, this currently only supports GIF animations.

  Note: Added in SDL_image 2.6.0

  Parameters:

    - src (`SDL_RWops`) – The file object from which to load the animation.

    - freesrc (int) – If non-zero, the input file object will be closed and freed after it has been read.

  Returns:

    A pointer to an animation object, or a null pointer if there was an error.

  Return type:

    POINTER(`IMG_Animation`)

sdl2.sdlimage.IMG_LoadAnimationTyped_RW(src, freesrc, type)

  Loads an animated image from an SDL file object as a specific format.

  For more information on how to work with imported animations, see the `IMG_Animation` documentation. As of SDL_image 2.6.0, the only supported animation type is `b'GIF'`.

  Note: Added in SDL_image 2.6.0

  Parameters:

    - src (`SDL_RWops`) – The file object from which to load the animation.

    - 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 animation format with which the file object should be loaded.

  Returns:

    A pointer to an animation object, or a null pointer if there was an error.

  Return type:

    POINTER(`IMG_Animation`)

sdl2.sdlimage.IMG_LoadGIFAnimation_RW(src)

  Loads a GIF animation from an SDL file object.

  For more information on how to work with imported animations, see the `IMG_Animation` documentation. Use the `IMG_GetError()` function to check for any errors.

  Note: Added in SDL_image 2.6.0

  Parameters:

    src (`SDL_RWops`) – The file object from which to load the GIF.

  Returns:

    A pointer to an animation object, or a a null pointer if there was an error.

  Return type:

    POINTER(`IMG_Animation`)

sdl2.sdlimage.IMG_FreeAnimation(anim)

  Closes and frees the memory associated with a given animation.

  This function should be called on an animation after you are done with it. An `IMG_Animation` and its frame data cannot be used after it has been closed.

  Note: Added in SDL_image 2.6.0

  Parameters:

    anim (`IMG_Animation`) – The animation object to close.

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

sdl2.sdlimage.IMG_INIT_JXL

  `IMG_Init()` flag to enable support for the JPEG XL image format.

sdl2.sdlimage.IMG_INIT_AVIF

  `IMG_Init()` flag to enable support for the AVIF image format.