# sdl2.ext.image - Importing and Exporting Image Files

The `sdl2.ext.image` module provides some simple functions for importing images as SDL surfaces and exporting SDL surfaces to image files.

The basic functions `load_bmp()` and `save_bmp()` load and save BMP files, and are guaranteed to be available on all systems supported by PySDL2. The `load_img()` function can be used to import additional image formats (e.g. JPEG, PNG), but requires that the SDL_image library is installed on the target system (can be installed as a Python dependency with `pysdl2-dll` on platforms that support it).

In addition to importing images from files, this module also provides the `pillow_to_surface()` function for converting `Image` objects from the Pillow Python library to SDL surfaces.

sdl2.ext.image.load_bmp(path)

  Imports a BMP (bitmap image) file as an SDL surface.

  Because BMP importing and exporting is part of the core SDL2 library, this function is guaranteed to be available on all platforms and installations that support PySDL2.

  Parameters:

    path (str) – The relative (or absolute) path to the BMP image to import.

  Returns:

    An SDL surface containing the imported image.

  Return type:

    `SDL_Surface`

sdl2.ext.image.load_img(path, as_argb=True)

  Imports an image file as an SDL surface using the SDL_image library.

  This function supports a wide range of image formats, including GIF, BMP, JPEG, PNG, TIFF, and WebP. For a full list, consult the SDL_image documentation.

  By default, this function also converts the imported surface to 32-bit ARGB format for consistency across functions and better compatibility with SDL2 renderers. To disable ARGB conversion, set the `as_argb` parameter to `False`.

  Note

  Because SDL_image is not part of the core SDL2 library, this function will only work on systems where the SDL_image library is installed. Additionally, support for PNG, JPEG, TIFF, and WebP in SDL_image is dynamic and are not guaranteed to be available on all systems.

  Parameters:

    - path (str) – The relative (or absolute) path to the image to import.

    - as_argb (bool, optional) – Whether the obtained surface should be converted to 32-bit ARGB pixel format or left as-is. Defaults to `True` (convert to ARGB).

  Returns:

    An SDL surface containing the imported image.

  Return type:

    `SDL_Surface`

sdl2.ext.image.load_svg(path, width=0, height=0, as_argb=True)

  Loads an SVG image at a given resolution, preserving aspect ratio.

  Only one dimension (height or width) will have any effect on a given image as the aspect ratio will always be preserved (e.g. setting an output size of 200x150 on a 100x100 SVG will result in a 200x200 surface).

  If both dimensions are specified, whichever one results in a larger output surface will be used. If neither height or width are specified, the SVG will be loaded at its original internal resolution.

  Note

  SVG support in SDL2_image is currently focused on simple images and does not support font rendering. More complex or modern SVG files may not render correctly.

  Note: This function requires SDL2_image 2.6.0 or newer.

  Parameters:

    - path (str) – The relative (or absolute) path to the image to import.

    - width (int, optional) – The width (in pixels) at which to load the SVG.

    - height (int, optional) – The height (in pixels) at which to load the SVG.

    - as_argb (bool, optional) – Whether the obtained surface should be converted to 32-bit ARGB pixel format or left as-is. Defaults to `True` (convert to ARGB).

  Returns:

    An SDL surface containing the imported SVG.

  Return type:

    `SDL_Surface`

sdl2.ext.image.save_bmp(source, path, overwrite=False)

  Exports an SDL surface to a BMP (bitmap image) file.

  Because BMP importing and exporting is part of the core SDL2 library, this function is guaranteed to be available on all platforms and installations that support PySDL2.

  Parameters:

    - source (`SDL_Surface`) – The surface to save as a BMP file.

    - path (str) – The relative (or absolute) path to which the BMP should be saved.

    - overwrite (bool, optional) – Whether the image should be overwritten if a file at that path already exists. Defaults to False.

sdl2.ext.image.pillow_to_surface(img, as_argb=True)

  Converts a `PIL.Image.Image` object to an SDL surface.

  This function returns a copy of the original object’s pixel data, meaning that the original Image can be modified or deleted without affecting the returned surface (and vice versa).

  By default, this function also converts the surface to 32-bit ARGB format for consistency across functions and better compatibility with SDL2 renderers. To disable ARGB conversion, set the `as_argb` parameter to `False`.

  Parameters:

    - img (`PIL.Image.Image`) – The Image object to convert to an SDL surface.

    - as_argb (bool, optional) – Whether the obtained surface should be converted to 32-bit ARGB pixel format or left as-is. Defaults to `True` (convert to ARGB).

  Returns:

    An SDL surface copy of the PIL image.

  Return type:

    `SDL_Surface`

sdl2.ext.image.load_image(fname, enforce=None)

  [Deprecated] Imports an image file as an SDL surface.

  This function uses either the SDL_image library or the Pillow Python package for importing images, using SDL2’s built-in BMP loader as a fall-back if neither are available.

  Warning

  Due to a long-standing bug, the resulting image surfaces can have different pixel formats depending on which backend was used, making behavior unpredictable across different systems. As such this function is deprecated, and is only maintained to avoid breaking existing code. For new projects, the `load_bmp()`, `load_img()`, and/or `pillow_to_surface()` functions should be used instead.

  Parameters:

    - fname (str) – The relative (or absolute) path to the image to import.

    - enforce (str, optional) – A string indicating the specific backend to use for loading images. Can be either “PIL” for Pillow-only, “SDL” for SDL2 and SDL_image only, or `None` for no enforced backend. Defaults to `None`.

  Returns:

    An SDL surface containing the imported image.

  Return type:

    `SDL_Surface`