---
name: "IMG_Load"
section: "3"
platform: "linux"
package: "libsdl3-image-doc"
version: "3.2.4+ds-1+deb13u1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/IMG_Load"
---

# IMG\_Load(3)

Load an image from a filesystem path into a software surface.

## NAME

IMG\_Load - Load an image from a filesystem path into a software surface.

## HEADER FILE

Defined in SDL3\_image/SDL\_image.h

## SYNOPSIS

```
#include "SDL3_image/SDL_image.h"
```

**SDL\_Surface \* IMG\_Load(const char \*file);**

## DESCRIPTION

An SDL\_Surface is a buffer of pixels in memory accessible by the CPU. Use this if you plan to hand the data to something else or manipulate it further in code.

There are no guarantees about what format the new SDL\_Surface data will be; in many cases, SDL\_image will attempt to supply a surface that exactly matches the provided image, but in others it might have to convert (either because the image is in a format that SDL doesn't directly support or because it's compressed data that could reasonably uncompress to various formats and SDL\_image had to pick one). You can inspect an SDL\_Surface for its specifics, and use SDL\_ConvertSurface to then migrate to any supported format.

If the image format supports a transparent pixel, SDL will set the colorkey for the surface. You can enable RLE acceleration on the surface afterwards by calling: SDL\_SetSurfaceColorKey(image, SDL\_RLEACCEL, image-\>format-\>colorkey);

There is a separate function to read files from an SDL\_IOStream, if you need an i/o abstraction to provide data from anywhere instead of a simple filesystem read; that function is  **IMG\_Load\_IO** ().

If you are using SDL's 2D rendering API, there is an equivalent call to load images directly into an SDL\_Texture for use by the GPU without using a software surface: call  **IMG\_LoadTexture** () instead.

When done with the returned surface, the app should dispose of it with a call to

SDL\_DestroySurface ⟨URL: https://wiki.libsdl.org/SDL3/SDL\_DestroySurface ⟩

().

## FUNCTION PARAMETERS

- *file*

  a path on the filesystem to load an image from.

## RETURN VALUE

Returns a new SDL surface, or NULL on error.

## AVAILABILITY

This function is available since SDL\_image 3.0.0.

## SEE ALSO

**•**(3), [**IMG\_LoadTyped\_IO**(3)](/IMG_LoadTyped_IO/3.md), **•**(3), [**IMG\_Load\_IO**(3)](/IMG_Load_IO/3.md), **•**SDL\_DestroySurface**(3)**