Header file for SDL_image library. More...

Collaboration diagram for Load images from several formats:

Classes
struct	SDL::AnimationParam
	Safely wrap Animation for non owning parameters. More...

class	SDL::Animation
	Animated image support. More...

struct	SDL::AnimationRef
	Semi-safe reference for Animation. More...

Macros
#define	SDL_IMAGE_VERSION
	This is the version number macro for the current SDL_image version. More...

#define	SDL_IMAGE_VERSION_ATLEAST(X, Y, Z)
	This macro will evaluate to true if compiled with SDL_image at least X.Y.Z. More...

Typedefs
using	SDL::AnimationRaw = IMG_Animation *
	Alias to raw representation for Animation.

Functions
Surface	SDL::LoadSurfaceTyped (IOStreamParam src, StringParam type, bool closeio=false)
	Load an image from an SDL data source into a software surface. More...

Surface	SDL::LoadSurface (StringParam file)
	Load an image from a filesystem path into a software surface. More...

Surface	SDL::LoadSurface (IOStreamParam src, bool closeio=false)
	Load an image from an SDL data source into a software surface. More...

Texture	SDL::LoadTexture (RendererParam renderer, StringParam file)
	Load an image from a filesystem path into a GPU texture. More...

Texture	SDL::LoadTexture (RendererParam renderer, IOStreamParam src, bool closeio=false)
	Load an image from an SDL data source into a GPU texture. More...

Texture	SDL::LoadTextureTyped (RendererParam renderer, IOStreamParam src, StringParam type, bool closeio=false)
	Load an image from an SDL data source into a GPU texture. More...

bool	SDL::isAVIF (IOStreamParam src)
	Detect AVIF image data on a readable/seekable IOStream. More...

bool	SDL::isICO (IOStreamParam src)
	Detect ICO image data on a readable/seekable IOStream. More...

bool	SDL::isCUR (IOStreamParam src)
	Detect CUR image data on a readable/seekable IOStream. More...

bool	SDL::isBMP (IOStreamParam src)
	Detect BMP image data on a readable/seekable IOStream. More...

bool	SDL::isGIF (IOStreamParam src)
	Detect GIF image data on a readable/seekable IOStream. More...

bool	SDL::isJPG (IOStreamParam src)
	Detect JPG image data on a readable/seekable IOStream. More...

bool	SDL::isJXL (IOStreamParam src)
	Detect JXL image data on a readable/seekable IOStream. More...

bool	SDL::isLBM (IOStreamParam src)
	Detect LBM image data on a readable/seekable IOStream. More...

bool	SDL::isPCX (IOStreamParam src)
	Detect PCX image data on a readable/seekable IOStream. More...

bool	SDL::isPNG (IOStreamParam src)
	Detect PNG image data on a readable/seekable IOStream. More...

bool	SDL::isPNM (IOStreamParam src)
	Detect PNM image data on a readable/seekable IOStream. More...

bool	SDL::isSVG (IOStreamParam src)
	Detect SVG image data on a readable/seekable IOStream. More...

bool	SDL::isQOI (IOStreamParam src)
	Detect QOI image data on a readable/seekable IOStream. More...

bool	SDL::isTIF (IOStreamParam src)
	Detect TIFF image data on a readable/seekable IOStream. More...

bool	SDL::isXCF (IOStreamParam src)
	Detect XCF image data on a readable/seekable IOStream. More...

bool	SDL::isXPM (IOStreamParam src)
	Detect XPM image data on a readable/seekable IOStream. More...

bool	SDL::isXV (IOStreamParam src)
	Detect XV image data on a readable/seekable IOStream. More...

bool	SDL::isWEBP (IOStreamParam src)
	Detect WEBP image data on a readable/seekable IOStream. More...

Surface	SDL::LoadAVIF (IOStreamParam src)
	Load a AVIF image directly. More...

Surface	SDL::LoadICO (IOStreamParam src)
	Load a ICO image directly. More...

Surface	SDL::LoadCUR (IOStreamParam src)
	Load a CUR image directly. More...

Surface	SDL::LoadBMP (IOStreamParam src)
	Load a BMP image directly. More...

Surface	SDL::LoadGIF (IOStreamParam src)
	Load a GIF image directly. More...

Surface	SDL::LoadJPG (IOStreamParam src)
	Load a JPG image directly. More...

Surface	SDL::LoadJXL (IOStreamParam src)
	Load a JXL image directly. More...

Surface	SDL::LoadLBM (IOStreamParam src)
	Load a LBM image directly. More...

Surface	SDL::LoadPCX (IOStreamParam src)
	Load a PCX image directly. More...

Surface	SDL::LoadPNG (IOStreamParam src)
	Load a PNG image directly. More...

Surface	SDL::LoadPNM (IOStreamParam src)
	Load a PNM image directly. More...

Surface	SDL::LoadSVG (IOStreamParam src)
	Load a SVG image directly. More...

Surface	SDL::LoadQOI (IOStreamParam src)
	Load a QOI image directly. More...

Surface	SDL::LoadTGA (IOStreamParam src)
	Load a TGA image directly. More...

Surface	SDL::LoadTIF (IOStreamParam src)
	Load a TIFF image directly. More...

Surface	SDL::LoadXCF (IOStreamParam src)
	Load a XCF image directly. More...

Surface	SDL::LoadXPM (IOStreamParam src)
	Load a XPM image directly. More...

Surface	SDL::LoadXV (IOStreamParam src)
	Load a XV image directly. More...

Surface	SDL::LoadWEBP (IOStreamParam src)
	Load a WEBP image directly. More...

Surface	SDL::LoadSizedSVG (IOStreamParam src, const PointRaw &size)
	Load an SVG image, scaled to a specific size. More...

Surface	SDL::ReadXPMFromArray (char **xpm)
	Load an XPM image from a memory array. More...

Surface	SDL::ReadXPMFromArrayToRGB888 (char **xpm)
	Load an XPM image from a memory array. More...

void	SDL::SaveAVIF (SurfaceParam surface, StringParam file, int quality)
	Save an Surface into a AVIF image file. More...

void	SDL::SaveAVIF (SurfaceParam surface, IOStreamParam dst, int quality, bool closeio=false)
	Save an Surface into AVIF image data, via an IOStream. More...

void	SDL::SavePNG (SurfaceParam surface, StringParam file)
	Save an Surface into a PNG image file. More...

void	SDL::SavePNG (SurfaceParam surface, IOStreamParam dst, bool closeio=false)
	Save an Surface into PNG image data, via an IOStream. More...

void	SDL::SaveJPG (SurfaceParam surface, StringParam file, int quality)
	Save an Surface into a JPEG image file. More...

void	SDL::SaveJPG (SurfaceParam surface, IOStreamParam dst, int quality, bool closeio=false)
	Save an Surface into JPEG image data, via an IOStream. More...

Animation	SDL::LoadAnimation (StringParam file)
	Load an animation from a file. More...

Animation	SDL::LoadAnimation (IOStreamParam src, bool closeio=false)
	Load an animation from an IOStream. More...

Animation	SDL::LoadAnimationTyped (IOStreamParam src, StringParam type, bool closeio=false)
	Load an animation from an SDL datasource. More...

void	SDL::FreeAnimation (AnimationRaw anim)
	Dispose of an Animation and free its resources. More...

Animation	SDL::LoadGIFAnimation (IOStreamParam src)
	Load a GIF animation directly. More...

Animation	SDL::LoadWEBPAnimation (IOStreamParam src)
	Load a WEBP animation directly. More...

	SDL::Surface::Surface (StringParam file)
	Load an image from a filesystem path into a software surface. More...

	SDL::Surface::Surface (IOStreamParam src, bool closeio=false)
	Load an image from an SDL data source into a software surface. More...

	SDL::Texture::Texture (RendererParam renderer, StringParam file)
	Load an image from a filesystem path into a GPU texture. More...

	SDL::Texture::Texture (RendererParam renderer, IOStreamParam src, bool closeio=false)
	Load an image from an SDL data source into a GPU texture. More...

void	SDL::Animation::Free ()
	Dispose of an Animation and free its resources. More...

Detailed Description

A simple library to load images of various formats as SDL surfaces

Macro Definition Documentation

◆ SDL_IMAGE_VERSION

#define SDL_IMAGE_VERSION

Value:

SDL_VERSIONNUM( \

SDL_IMAGE_MAJOR_VERSION, SDL_IMAGE_MINOR_VERSION, SDL_IMAGE_MICRO_VERSION)

SDL_VERSIONNUM

#define SDL_VERSIONNUM(major, minor, patch)

This macro turns the version numbers into a numeric value.

Definition: SDL3pp_version.h:57

◆ SDL_IMAGE_VERSION_ATLEAST

#define SDL_IMAGE_VERSION_ATLEAST	(	X,
		Y,
		Z
	)

Value:

  ((SDL_IMAGE_MAJOR_VERSION >= X) &&                                           \
   (SDL_IMAGE_MAJOR_VERSION > X || SDL_IMAGE_MINOR_VERSION >= Y) &&            \
   (SDL_IMAGE_MAJOR_VERSION > X || SDL_IMAGE_MINOR_VERSION > Y ||              \
    SDL_IMAGE_MICRO_VERSION >= Z))

Function Documentation

◆ Free()

void SDL::Animation::Free ( )

inline

The provided anim pointer is not valid once this call returns.

Since: This function is available since SDL_image 3.0.0.

See also: Animation.Animation; LoadAnimationTyped

◆ FreeAnimation()

void SDL::FreeAnimation ( AnimationRaw anim )

inline

The provided anim pointer is not valid once this call returns.

Parameters

anim	Animation to dispose of.

Since: This function is available since SDL_image 3.0.0.

See also: Animation.Animation; LoadAnimationTyped

◆ isAVIF()

bool SDL::isAVIF ( IOStreamParam src )

inline

This function attempts to determine if a file is a given filetype, reading the least amount possible from the IOStream (usually a few bytes).

There is no distinction made between "not the filetype in question" and basic i/o errors.

This function will always attempt to seek src back to where it started when this function was called, but it will not report any errors in doing so, but assuming seeking works, this means you can immediately use this with a different IMG_isTYPE function, or load the image without further seeking.

You do not need to call this function to load data; SDL_image can work to determine file type in many cases in its standard load functions.

Parameters

src	a seekable/readable IOStream to provide image data.

Returns: non-zero if this is AVIF data, zero otherwise.

Since: This function is available since SDL_image 3.0.0.

See also: isAVIF; isICO; isCUR; isBMP; isGIF; isJPG; isJXL; isLBM; isPCX; isPNG; isPNM; isSVG; isQOI; isTIF; isXCF; isXPM; isXV; isWEBP

◆ isBMP()

bool SDL::isBMP ( IOStreamParam src )

inline

This function attempts to determine if a file is a given filetype, reading the least amount possible from the IOStream (usually a few bytes).

There is no distinction made between "not the filetype in question" and basic i/o errors.

This function will always attempt to seek src back to where it started when this function was called, but it will not report any errors in doing so, but assuming seeking works, this means you can immediately use this with a different IMG_isTYPE function, or load the image without further seeking.

You do not need to call this function to load data; SDL_image can work to determine file type in many cases in its standard load functions.

Parameters

src	a seekable/readable IOStream to provide image data.

Returns: non-zero if this is BMP data, zero otherwise.

Since: This function is available since SDL_image 3.0.0.

See also: isAVIF; isICO; isCUR; isGIF; isJPG; isJXL; isLBM; isPCX; isPNG; isPNM; isSVG; isQOI; isTIF; isXCF; isXPM; isXV; isWEBP

◆ isCUR()

bool SDL::isCUR ( IOStreamParam src )

inline

This function attempts to determine if a file is a given filetype, reading the least amount possible from the IOStream (usually a few bytes).

There is no distinction made between "not the filetype in question" and basic i/o errors.

This function will always attempt to seek src back to where it started when this function was called, but it will not report any errors in doing so, but assuming seeking works, this means you can immediately use this with a different IMG_isTYPE function, or load the image without further seeking.

You do not need to call this function to load data; SDL_image can work to determine file type in many cases in its standard load functions.

Parameters

src	a seekable/readable IOStream to provide image data.

Returns: non-zero if this is CUR data, zero otherwise.

Since: This function is available since SDL_image 3.0.0.

See also: isAVIF; isICO; isBMP; isGIF; isJPG; isJXL; isLBM; isPCX; isPNG; isPNM; isSVG; isQOI; isTIF; isXCF; isXPM; isXV; isWEBP

◆ isGIF()

bool SDL::isGIF ( IOStreamParam src )

inline

This function attempts to determine if a file is a given filetype, reading the least amount possible from the IOStream (usually a few bytes).

There is no distinction made between "not the filetype in question" and basic i/o errors.

This function will always attempt to seek src back to where it started when this function was called, but it will not report any errors in doing so, but assuming seeking works, this means you can immediately use this with a different IMG_isTYPE function, or load the image without further seeking.

You do not need to call this function to load data; SDL_image can work to determine file type in many cases in its standard load functions.

Parameters

src	a seekable/readable IOStream to provide image data.

Returns: non-zero if this is GIF data, zero otherwise.

Since: This function is available since SDL_image 3.0.0.

See also: isAVIF; isICO; isCUR; isBMP; isJPG; isJXL; isLBM; isPCX; isPNG; isPNM; isSVG; isQOI; isTIF; isXCF; isXPM; isXV; isWEBP

◆ isICO()

bool SDL::isICO ( IOStreamParam src )

inline

This function attempts to determine if a file is a given filetype, reading the least amount possible from the IOStream (usually a few bytes).

There is no distinction made between "not the filetype in question" and basic i/o errors.

This function will always attempt to seek src back to where it started when this function was called, but it will not report any errors in doing so, but assuming seeking works, this means you can immediately use this with a different IMG_isTYPE function, or load the image without further seeking.

You do not need to call this function to load data; SDL_image can work to determine file type in many cases in its standard load functions.

Parameters

src	a seekable/readable IOStream to provide image data.

Returns: non-zero if this is ICO data, zero otherwise.

Since: This function is available since SDL_image 3.0.0.

See also: isAVIF; isCUR; isBMP; isGIF; isJPG; isJXL; isLBM; isPCX; isPNG; isPNM; isSVG; isQOI; isTIF; isXCF; isXPM; isXV; isWEBP

◆ isJPG()

bool SDL::isJPG ( IOStreamParam src )

inline

This function attempts to determine if a file is a given filetype, reading the least amount possible from the IOStream (usually a few bytes).

There is no distinction made between "not the filetype in question" and basic i/o errors.

This function will always attempt to seek src back to where it started when this function was called, but it will not report any errors in doing so, but assuming seeking works, this means you can immediately use this with a different IMG_isTYPE function, or load the image without further seeking.

You do not need to call this function to load data; SDL_image can work to determine file type in many cases in its standard load functions.

Parameters

src	a seekable/readable IOStream to provide image data.

Returns: non-zero if this is JPG data, zero otherwise.

Since: This function is available since SDL_image 3.0.0.

See also: isAVIF; isICO; isCUR; isBMP; isGIF; isJXL; isLBM; isPCX; isPNG; isPNM; isSVG; isQOI; isTIF; isXCF; isXPM; isXV; isWEBP

◆ isJXL()

bool SDL::isJXL ( IOStreamParam src )

inline

This function attempts to determine if a file is a given filetype, reading the least amount possible from the IOStream (usually a few bytes).

There is no distinction made between "not the filetype in question" and basic i/o errors.

This function will always attempt to seek src back to where it started when this function was called, but it will not report any errors in doing so, but assuming seeking works, this means you can immediately use this with a different IMG_isTYPE function, or load the image without further seeking.

You do not need to call this function to load data; SDL_image can work to determine file type in many cases in its standard load functions.

Parameters

src	a seekable/readable IOStream to provide image data.

Returns: non-zero if this is JXL data, zero otherwise.

Since: This function is available since SDL_image 3.0.0.

See also: isAVIF; isICO; isCUR; isBMP; isGIF; isJPG; isLBM; isPCX; isPNG; isPNM; isSVG; isQOI; isTIF; isXCF; isXPM; isXV; isWEBP

◆ isLBM()

bool SDL::isLBM ( IOStreamParam src )

inline

This function attempts to determine if a file is a given filetype, reading the least amount possible from the IOStream (usually a few bytes).

There is no distinction made between "not the filetype in question" and basic i/o errors.

This function will always attempt to seek src back to where it started when this function was called, but it will not report any errors in doing so, but assuming seeking works, this means you can immediately use this with a different IMG_isTYPE function, or load the image without further seeking.

You do not need to call this function to load data; SDL_image can work to determine file type in many cases in its standard load functions.

Parameters

src	a seekable/readable IOStream to provide image data.

Returns: non-zero if this is LBM data, zero otherwise.

Since: This function is available since SDL_image 3.0.0.

See also: isAVIF; isICO; isCUR; isBMP; isGIF; isJPG; isJXL; isPCX; isPNG; isPNM; isSVG; isQOI; isTIF; isXCF; isXPM; isXV; isWEBP

◆ isPCX()

bool SDL::isPCX ( IOStreamParam src )

inline

This function attempts to determine if a file is a given filetype, reading the least amount possible from the IOStream (usually a few bytes).

There is no distinction made between "not the filetype in question" and basic i/o errors.

This function will always attempt to seek src back to where it started when this function was called, but it will not report any errors in doing so, but assuming seeking works, this means you can immediately use this with a different IMG_isTYPE function, or load the image without further seeking.

You do not need to call this function to load data; SDL_image can work to determine file type in many cases in its standard load functions.

Parameters

src	a seekable/readable IOStream to provide image data.

Returns: non-zero if this is PCX data, zero otherwise.

Since: This function is available since SDL_image 3.0.0.

See also: isAVIF; isICO; isCUR; isBMP; isGIF; isJPG; isJXL; isLBM; isPNG; isPNM; isSVG; isQOI; isTIF; isXCF; isXPM; isXV; isWEBP

◆ isPNG()

bool SDL::isPNG ( IOStreamParam src )

inline

This function attempts to determine if a file is a given filetype, reading the least amount possible from the IOStream (usually a few bytes).

There is no distinction made between "not the filetype in question" and basic i/o errors.

This function will always attempt to seek src back to where it started when this function was called, but it will not report any errors in doing so, but assuming seeking works, this means you can immediately use this with a different IMG_isTYPE function, or load the image without further seeking.

You do not need to call this function to load data; SDL_image can work to determine file type in many cases in its standard load functions.

Parameters

src	a seekable/readable IOStream to provide image data.

Returns: non-zero if this is PNG data, zero otherwise.

Since: This function is available since SDL_image 3.0.0.

See also: isAVIF; isICO; isCUR; isBMP; isGIF; isJPG; isJXL; isLBM; isPCX; isPNM; isSVG; isQOI; isTIF; isXCF; isXPM; isXV; isWEBP

◆ isPNM()

bool SDL::isPNM ( IOStreamParam src )

inline

This function attempts to determine if a file is a given filetype, reading the least amount possible from the IOStream (usually a few bytes).

There is no distinction made between "not the filetype in question" and basic i/o errors.

This function will always attempt to seek src back to where it started when this function was called, but it will not report any errors in doing so, but assuming seeking works, this means you can immediately use this with a different IMG_isTYPE function, or load the image without further seeking.

You do not need to call this function to load data; SDL_image can work to determine file type in many cases in its standard load functions.

Parameters

src	a seekable/readable IOStream to provide image data.

Returns: non-zero if this is PNM data, zero otherwise.

Since: This function is available since SDL_image 3.0.0.

See also: isAVIF; isICO; isCUR; isBMP; isGIF; isJPG; isJXL; isLBM; isPCX; isPNG; isSVG; isQOI; isTIF; isXCF; isXPM; isXV; isWEBP

◆ isQOI()

bool SDL::isQOI ( IOStreamParam src )

inline

This function attempts to determine if a file is a given filetype, reading the least amount possible from the IOStream (usually a few bytes).

There is no distinction made between "not the filetype in question" and basic i/o errors.

This function will always attempt to seek src back to where it started when this function was called, but it will not report any errors in doing so, but assuming seeking works, this means you can immediately use this with a different IMG_isTYPE function, or load the image without further seeking.

You do not need to call this function to load data; SDL_image can work to determine file type in many cases in its standard load functions.

Parameters

src	a seekable/readable IOStream to provide image data.

Returns: non-zero if this is QOI data, zero otherwise.

Since: This function is available since SDL_image 3.0.0.

See also: isAVIF; isICO; isCUR; isBMP; isGIF; isJPG; isJXL; isLBM; isPCX; isPNG; isPNM; isSVG; isTIF; isXCF; isXPM; isXV; isWEBP

◆ isSVG()

bool SDL::isSVG ( IOStreamParam src )

inline

This function attempts to determine if a file is a given filetype, reading the least amount possible from the IOStream (usually a few bytes).

There is no distinction made between "not the filetype in question" and basic i/o errors.

This function will always attempt to seek src back to where it started when this function was called, but it will not report any errors in doing so, but assuming seeking works, this means you can immediately use this with a different IMG_isTYPE function, or load the image without further seeking.

You do not need to call this function to load data; SDL_image can work to determine file type in many cases in its standard load functions.

Parameters

src	a seekable/readable IOStream to provide image data.

Returns: non-zero if this is SVG data, zero otherwise.

Since: This function is available since SDL_image 3.0.0.

See also: isAVIF; isICO; isCUR; isBMP; isGIF; isJPG; isJXL; isLBM; isPCX; isPNG; isPNM; isQOI; isTIF; isXCF; isXPM; isXV; isWEBP

◆ isTIF()

bool SDL::isTIF ( IOStreamParam src )

inline

This function attempts to determine if a file is a given filetype, reading the least amount possible from the IOStream (usually a few bytes).

There is no distinction made between "not the filetype in question" and basic i/o errors.

This function will always attempt to seek src back to where it started when this function was called, but it will not report any errors in doing so, but assuming seeking works, this means you can immediately use this with a different IMG_isTYPE function, or load the image without further seeking.

You do not need to call this function to load data; SDL_image can work to determine file type in many cases in its standard load functions.

Parameters

src	a seekable/readable IOStream to provide image data.

Returns: non-zero if this is TIFF data, zero otherwise.

Since: This function is available since SDL_image 3.0.0.

See also: isAVIF; isICO; isCUR; isBMP; isGIF; isJPG; isJXL; isLBM; isPCX; isPNG; isPNM; isSVG; isQOI; isXCF; isXPM; isXV; isWEBP

◆ isWEBP()

bool SDL::isWEBP ( IOStreamParam src )

inline

This function attempts to determine if a file is a given filetype, reading the least amount possible from the IOStream (usually a few bytes).

There is no distinction made between "not the filetype in question" and basic i/o errors.

This function will always attempt to seek src back to where it started when this function was called, but it will not report any errors in doing so, but assuming seeking works, this means you can immediately use this with a different IMG_isTYPE function, or load the image without further seeking.

You do not need to call this function to load data; SDL_image can work to determine file type in many cases in its standard load functions.

Parameters

src	a seekable/readable IOStream to provide image data.

Returns: non-zero if this is WEBP data, zero otherwise.

Since: This function is available since SDL_image 3.0.0.

See also: isAVIF; isICO; isCUR; isBMP; isGIF; isJPG; isJXL; isLBM; isPCX; isPNG; isPNM; isSVG; isQOI; isTIF; isXCF; isXPM; isXV

◆ isXCF()

bool SDL::isXCF ( IOStreamParam src )

inline

This function attempts to determine if a file is a given filetype, reading the least amount possible from the IOStream (usually a few bytes).

There is no distinction made between "not the filetype in question" and basic i/o errors.

This function will always attempt to seek src back to where it started when this function was called, but it will not report any errors in doing so, but assuming seeking works, this means you can immediately use this with a different IMG_isTYPE function, or load the image without further seeking.

You do not need to call this function to load data; SDL_image can work to determine file type in many cases in its standard load functions.

Parameters

src	a seekable/readable IOStream to provide image data.

Returns: non-zero if this is XCF data, zero otherwise.

Since: This function is available since SDL_image 3.0.0.

See also: isAVIF; isICO; isCUR; isBMP; isGIF; isJPG; isJXL; isLBM; isPCX; isPNG; isPNM; isSVG; isQOI; isTIF; isXPM; isXV; isWEBP

◆ isXPM()

bool SDL::isXPM ( IOStreamParam src )

inline

This function attempts to determine if a file is a given filetype, reading the least amount possible from the IOStream (usually a few bytes).

There is no distinction made between "not the filetype in question" and basic i/o errors.

This function will always attempt to seek src back to where it started when this function was called, but it will not report any errors in doing so, but assuming seeking works, this means you can immediately use this with a different IMG_isTYPE function, or load the image without further seeking.

You do not need to call this function to load data; SDL_image can work to determine file type in many cases in its standard load functions.

Parameters

src	a seekable/readable IOStream to provide image data.

Returns: non-zero if this is XPM data, zero otherwise.

Since: This function is available since SDL_image 3.0.0.

See also: isAVIF; isICO; isCUR; isBMP; isGIF; isJPG; isJXL; isLBM; isPCX; isPNG; isPNM; isSVG; isQOI; isTIF; isXCF; isXV; isWEBP

◆ isXV()

bool SDL::isXV ( IOStreamParam src )

inline

This function attempts to determine if a file is a given filetype, reading the least amount possible from the IOStream (usually a few bytes).

There is no distinction made between "not the filetype in question" and basic i/o errors.

This function will always attempt to seek src back to where it started when this function was called, but it will not report any errors in doing so, but assuming seeking works, this means you can immediately use this with a different IMG_isTYPE function, or load the image without further seeking.

You do not need to call this function to load data; SDL_image can work to determine file type in many cases in its standard load functions.

Parameters

src	a seekable/readable IOStream to provide image data.

Returns: non-zero if this is XV data, zero otherwise.

Since: This function is available since SDL_image 3.0.0.

See also: isAVIF; isICO; isCUR; isBMP; isGIF; isJPG; isJXL; isLBM; isPCX; isPNG; isPNM; isSVG; isQOI; isTIF; isXCF; isXPM; isWEBP

◆ LoadAnimation() [1/2]

Animation SDL::LoadAnimation	(	IOStreamParam	src,
		bool	closeio = `false`
	)

inline

If closeio is true, src will be closed before returning, whether this function succeeds or not. SDL_image reads everything it needs from src during this call in any case.

When done with the returned animation, the app should dispose of it with a call to Animation.Free().

Parameters

src	an IOStream that data will be read from.
closeio	true to close/free the IOStream before returning, false to leave it open.

Returns: a new Animation, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: Animation.Free

◆ LoadAnimation() [2/2]

Animation SDL::LoadAnimation ( StringParam file )

inline

When done with the returned animation, the app should dispose of it with a call to Animation.Free().

Parameters

file	path on the filesystem containing an animated image.

Returns: a new Animation, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: Animation.Free

◆ LoadAnimationTyped()

Animation SDL::LoadAnimationTyped	(	IOStreamParam	src,
		StringParam	type,
		bool	closeio = `false`
	)

inline

Even though this function accepts a file type, SDL_image may still try other decoders that are capable of detecting file type from the contents of the image data, but may rely on the caller-provided type string for formats that it cannot autodetect. If type is nullptr, SDL_image will rely solely on its ability to guess the format.

If closeio is true, src will be closed before returning, whether this function succeeds or not. SDL_image reads everything it needs from src during this call in any case.

When done with the returned animation, the app should dispose of it with a call to Animation.Free().

Parameters

src	an IOStream that data will be read from.
type	a filename extension that represent this data ("GIF", etc).
closeio	true to close/free the IOStream before returning, false to leave it open.

Returns: a new Animation, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: Animation.Animation; Animation.Free

◆ LoadAVIF()

Surface SDL::LoadAVIF ( IOStreamParam src )

inline

If you know you definitely have a AVIF image, you can call this function, which will skip SDL_image's file format detection routines. Generally it's better to use the abstract interfaces; also, there is only an IOStream interface available here.

Parameters

src	an IOStream to load image data from.

Returns: SDL surface, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: LoadICO; LoadCUR; LoadBMP; LoadGIF; LoadJPG; LoadJXL; LoadLBM; LoadPCX; LoadPNG; LoadPNM; LoadSVG; LoadQOI; LoadTGA; LoadTIF; LoadXCF; LoadXPM; LoadXV; LoadWEBP

◆ LoadBMP()

Surface SDL::LoadBMP ( IOStreamParam src )

inline

If you know you definitely have a BMP image, you can call this function, which will skip SDL_image's file format detection routines. Generally it's better to use the abstract interfaces; also, there is only an IOStream interface available here.

Parameters

src	an IOStream to load image data from.

Returns: SDL surface, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: LoadAVIF; LoadICO; LoadCUR; LoadGIF; LoadJPG; LoadJXL; LoadLBM; LoadPCX; LoadPNG; LoadPNM; LoadSVG; LoadQOI; LoadTGA; LoadTIF; LoadXCF; LoadXPM; LoadXV; LoadWEBP

◆ LoadCUR()

Surface SDL::LoadCUR ( IOStreamParam src )

inline

If you know you definitely have a CUR image, you can call this function, which will skip SDL_image's file format detection routines. Generally it's better to use the abstract interfaces; also, there is only an IOStream interface available here.

Parameters

src	an IOStream to load image data from.

Returns: SDL surface, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: LoadAVIF; LoadICO; LoadBMP; LoadGIF; LoadJPG; LoadJXL; LoadLBM; LoadPCX; LoadPNG; LoadPNM; LoadSVG; LoadQOI; LoadTGA; LoadTIF; LoadXCF; LoadXPM; LoadXV; LoadWEBP

◆ LoadGIF()

Surface SDL::LoadGIF ( IOStreamParam src )

inline

If you know you definitely have a GIF image, you can call this function, which will skip SDL_image's file format detection routines. Generally it's better to use the abstract interfaces; also, there is only an IOStream interface available here.

Parameters

src	an IOStream to load image data from.

Returns: SDL surface, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: LoadAVIF; LoadICO; LoadCUR; LoadBMP; LoadJPG; LoadJXL; LoadLBM; LoadPCX; LoadPNG; LoadPNM; LoadSVG; LoadQOI; LoadTGA; LoadTIF; LoadXCF; LoadXPM; LoadXV; LoadWEBP

◆ LoadGIFAnimation()

Animation SDL::LoadGIFAnimation ( IOStreamParam src )

inline

If you know you definitely have a GIF image, you can call this function, which will skip SDL_image's file format detection routines. Generally it's better to use the abstract interfaces; also, there is only an IOStream interface available here.

Parameters

src	an IOStream that data will be read from.

Returns: a new Animation, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: Animation.Animation; LoadAnimationTyped; Animation.Free

◆ LoadICO()

Surface SDL::LoadICO ( IOStreamParam src )

inline

If you know you definitely have a ICO image, you can call this function, which will skip SDL_image's file format detection routines. Generally it's better to use the abstract interfaces; also, there is only an IOStream interface available here.

Parameters

src	an IOStream to load image data from.

Returns: SDL surface, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: LoadAVIF; LoadCUR; LoadBMP; LoadGIF; LoadJPG; LoadJXL; LoadLBM; LoadPCX; LoadPNG; LoadPNM; LoadSVG; LoadQOI; LoadTGA; LoadTIF; LoadXCF; LoadXPM; LoadXV; LoadWEBP

◆ LoadJPG()

Surface SDL::LoadJPG ( IOStreamParam src )

inline

If you know you definitely have a JPG image, you can call this function, which will skip SDL_image's file format detection routines. Generally it's better to use the abstract interfaces; also, there is only an IOStream interface available here.

Parameters

src	an IOStream to load image data from.

Returns: SDL surface, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: LoadAVIF; LoadICO; LoadCUR; LoadBMP; LoadGIF; LoadJXL; LoadLBM; LoadPCX; LoadPNG; LoadPNM; LoadSVG; LoadQOI; LoadTGA; LoadTIF; LoadXCF; LoadXPM; LoadXV; LoadWEBP

◆ LoadJXL()

Surface SDL::LoadJXL ( IOStreamParam src )

inline

If you know you definitely have a JXL image, you can call this function, which will skip SDL_image's file format detection routines. Generally it's better to use the abstract interfaces; also, there is only an IOStream interface available here.

Parameters

src	an IOStream to load image data from.

Returns: SDL surface, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: LoadAVIF; LoadICO; LoadCUR; LoadBMP; LoadGIF; LoadJPG; LoadLBM; LoadPCX; LoadPNG; LoadPNM; LoadSVG; LoadQOI; LoadTGA; LoadTIF; LoadXCF; LoadXPM; LoadXV; LoadWEBP

◆ LoadLBM()

Surface SDL::LoadLBM ( IOStreamParam src )

inline

If you know you definitely have a LBM image, you can call this function, which will skip SDL_image's file format detection routines. Generally it's better to use the abstract interfaces; also, there is only an IOStream interface available here.

Parameters

src	an IOStream to load image data from.

Returns: SDL surface, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: LoadAVIF; LoadICO; LoadCUR; LoadBMP; LoadGIF; LoadJPG; LoadJXL; LoadPCX; LoadPNG; LoadPNM; LoadSVG; LoadQOI; LoadTGA; LoadTIF; LoadXCF; LoadXPM; LoadXV; LoadWEBP

◆ LoadPCX()

Surface SDL::LoadPCX ( IOStreamParam src )

inline

If you know you definitely have a PCX image, you can call this function, which will skip SDL_image's file format detection routines. Generally it's better to use the abstract interfaces; also, there is only an IOStream interface available here.

Parameters

src	an IOStream to load image data from.

Returns: SDL surface, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: LoadAVIF; LoadICO; LoadCUR; LoadBMP; LoadGIF; LoadJPG; LoadJXL; LoadLBM; LoadPNG; LoadPNM; LoadSVG; LoadQOI; LoadTGA; LoadTIF; LoadXCF; LoadXPM; LoadXV; LoadWEBP

◆ LoadPNG()

Surface SDL::LoadPNG ( IOStreamParam src )

inline

If you know you definitely have a PNG image, you can call this function, which will skip SDL_image's file format detection routines. Generally it's better to use the abstract interfaces; also, there is only an IOStream interface available here.

Parameters

src	an IOStream to load image data from.

Returns: SDL surface, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: LoadAVIF; LoadICO; LoadCUR; LoadBMP; LoadGIF; LoadJPG; LoadJXL; LoadLBM; LoadPCX; LoadPNM; LoadSVG; LoadQOI; LoadTGA; LoadTIF; LoadXCF; LoadXPM; LoadXV; LoadWEBP

◆ LoadPNM()

Surface SDL::LoadPNM ( IOStreamParam src )

inline

If you know you definitely have a PNM image, you can call this function, which will skip SDL_image's file format detection routines. Generally it's better to use the abstract interfaces; also, there is only an IOStream interface available here.

Parameters

src	an IOStream to load image data from.

Returns: SDL surface, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: LoadAVIF; LoadICO; LoadCUR; LoadBMP; LoadGIF; LoadJPG; LoadJXL; LoadLBM; LoadPCX; LoadPNG; LoadSVG; LoadQOI; LoadTGA; LoadTIF; LoadXCF; LoadXPM; LoadXV; LoadWEBP

◆ LoadQOI()

Surface SDL::LoadQOI ( IOStreamParam src )

inline

If you know you definitely have a QOI image, you can call this function, which will skip SDL_image's file format detection routines. Generally it's better to use the abstract interfaces; also, there is only an IOStream interface available here.

Parameters

src	an IOStream to load image data from.

Returns: SDL surface, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: LoadAVIF; LoadICO; LoadCUR; LoadBMP; LoadGIF; LoadJPG; LoadJXL; LoadLBM; LoadPCX; LoadPNG; LoadPNM; LoadSVG; LoadTGA; LoadTIF; LoadXCF; LoadXPM; LoadXV; LoadWEBP

◆ LoadSizedSVG()

Surface SDL::LoadSizedSVG	(	IOStreamParam	src,
		const PointRaw &	size
	)

inline

Since SVG files are resolution-independent, you specify the size you would like the output image to be and it will be generated at those dimensions.

Either width or height may be 0 and the image will be auto-sized to preserve aspect ratio.

Parameters

src	an IOStream to load SVG data from.
size	desired width and height of the generated surface, in pixels.

Returns: a new SDL surface, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

◆ LoadSurface() [1/2]

Surface SDL::LoadSurface	(	IOStreamParam	src,
		bool	closeio = `false`
	)

inline

An 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 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 Surface for its specifics, and use Surface.Convert 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: Surface.SetColorKey(image, SDL_RLEACCEL, image->format->colorkey);

If closeio is true, src will be closed before returning, whether this function succeeds or not. SDL_image reads everything it needs from src during this call in any case.

There is a separate function to read files from disk without having to deal with IOStream: Surface.Surface("filename.jpg") will call this function and manage those details for you, determining the file type from the filename's extension.

There is also LoadSurfaceTyped(), which is equivalent to this function except a file extension (like "BMP", "JPG", etc) can be specified, in case SDL_image cannot autodetect the file format.

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

Parameters

src	an IOStream that data will be read from.
closeio	true to close/free the IOStream before returning, false to leave it open.

Returns: a new SDL surface, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: Surface.Surface; LoadSurfaceTyped; Surface.Destroy

◆ LoadSurface() [2/2]

Surface SDL::LoadSurface ( StringParam file )

inline

An 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 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 Surface for its specifics, and use Surface.Convert 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: Surface.SetColorKey(image, SDL_RLEACCEL, image->format->colorkey);

There is a separate function to read files from an IOStream, if you need an i/o abstraction to provide data from anywhere instead of a simple filesystem read; that function is Surface.Surface().

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

Parameters

file	a path on the filesystem to load an image from.

Returns: a new SDL surface, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: LoadSurfaceTyped; Surface.Surface; Surface.Destroy

◆ LoadSurfaceTyped()

Surface SDL::LoadSurfaceTyped	(	IOStreamParam	src,
		StringParam	type,
		bool	closeio = `false`
	)

inline

An 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 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 Surface for its specifics, and use Surface.Convert 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: Surface.SetColorKey(image, SDL_RLEACCEL, image->format->colorkey);

If closeio is true, src will be closed before returning, whether this function succeeds or not. SDL_image reads everything it needs from src during this call in any case.

Even though this function accepts a file type, SDL_image may still try other decoders that are capable of detecting file type from the contents of the image data, but may rely on the caller-provided type string for formats that it cannot autodetect. If type is nullptr, SDL_image will rely solely on its ability to guess the format.

There is a separate function to read files from disk without having to deal with IOStream: Surface.Surface("filename.jpg") will call this function and manage those details for you, determining the file type from the filename's extension.

There is also Surface.Surface(), which is equivalent to this function except that it will rely on SDL_image to determine what type of data it is loading, much like passing a nullptr for type.

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

Parameters

src	an IOStream that data will be read from.
type	a filename extension that represent this data ("BMP", "GIF", "PNG", etc).
closeio	true to close/free the IOStream before returning, false to leave it open.

Returns: a new SDL surface, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: Surface.Surface; Surface.Surface; Surface.Destroy

◆ LoadSVG()

Surface SDL::LoadSVG ( IOStreamParam src )

inline

If you know you definitely have a SVG image, you can call this function, which will skip SDL_image's file format detection routines. Generally it's better to use the abstract interfaces; also, there is only an IOStream interface available here.

Parameters

src	an IOStream to load image data from.

Returns: SDL surface, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: LoadAVIF; LoadICO; LoadCUR; LoadBMP; LoadGIF; LoadJPG; LoadJXL; LoadLBM; LoadPCX; LoadPNG; LoadPNM; LoadQOI; LoadTGA; LoadTIF; LoadXCF; LoadXPM; LoadXV; LoadWEBP

◆ LoadTexture() [1/2]

Texture SDL::LoadTexture	(	RendererParam	renderer,
		IOStreamParam	src,
		bool	closeio = `false`
	)

inline

An Texture represents an image in GPU memory, usable by SDL's 2D Render API. This can be significantly more efficient than using a CPU-bound Surface if you don't need to manipulate the image directly after loading it.

If the loaded image has transparency or a colorkey, a texture with an alpha channel will be created. Otherwise, SDL_image will attempt to create an Texture in the most format that most reasonably represents the image data (but in many cases, this will just end up being 32-bit RGB or 32-bit RGBA).

If closeio is true, src will be closed before returning, whether this function succeeds or not. SDL_image reads everything it needs from src during this call in any case.

There is a separate function to read files from disk without having to deal with IOStream: Texture.Texture(renderer, "filename.jpg") will call this function and manage those details for you, determining the file type from the filename's extension.

There is also LoadTextureTyped(), which is equivalent to this function except a file extension (like "BMP", "JPG", etc) can be specified, in case SDL_image cannot autodetect the file format.

If you would rather decode an image to an Surface (a buffer of pixels in CPU memory), call Surface.Surface() instead.

Parameters

renderer	the Renderer to use to create the GPU texture.
src	an IOStream that data will be read from.
closeio	true to close/free the IOStream before returning, false to leave it open.

Returns: a new texture, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: Texture.Texture; LoadTextureTyped; Texture.Destroy

◆ LoadTexture() [2/2]

Texture SDL::LoadTexture	(	RendererParam	renderer,
		StringParam	file
	)

inline

An Texture represents an image in GPU memory, usable by SDL's 2D Render API. This can be significantly more efficient than using a CPU-bound Surface if you don't need to manipulate the image directly after loading it.

If the loaded image has transparency or a colorkey, a texture with an alpha channel will be created. Otherwise, SDL_image will attempt to create an Texture in the most format that most reasonably represents the image data (but in many cases, this will just end up being 32-bit RGB or 32-bit RGBA).

There is a separate function to read files from an IOStream, if you need an i/o abstraction to provide data from anywhere instead of a simple filesystem read; that function is Texture.Texture().

If you would rather decode an image to an Surface (a buffer of pixels in CPU memory), call Surface.Surface() instead.

Parameters

renderer	the Renderer to use to create the GPU texture.
file	a path on the filesystem to load an image from.

Returns: a new texture, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: LoadTextureTyped; Texture.Texture

◆ LoadTextureTyped()

Texture SDL::LoadTextureTyped	(	RendererParam	renderer,
		IOStreamParam	src,
		StringParam	type,
		bool	closeio = `false`
	)

inline

An Texture represents an image in GPU memory, usable by SDL's 2D Render API. This can be significantly more efficient than using a CPU-bound Surface if you don't need to manipulate the image directly after loading it.

If the loaded image has transparency or a colorkey, a texture with an alpha channel will be created. Otherwise, SDL_image will attempt to create an Texture in the most format that most reasonably represents the image data (but in many cases, this will just end up being 32-bit RGB or 32-bit RGBA).

If closeio is true, src will be closed before returning, whether this function succeeds or not. SDL_image reads everything it needs from src during this call in any case.

Even though this function accepts a file type, SDL_image may still try other decoders that are capable of detecting file type from the contents of the image data, but may rely on the caller-provided type string for formats that it cannot autodetect. If type is nullptr, SDL_image will rely solely on its ability to guess the format.

There is a separate function to read files from disk without having to deal with IOStream: Texture.Texture("filename.jpg") will call this function and manage those details for you, determining the file type from the filename's extension.

There is also Texture.Texture(), which is equivalent to this function except that it will rely on SDL_image to determine what type of data it is loading, much like passing a nullptr for type.

If you would rather decode an image to an Surface (a buffer of pixels in CPU memory), call LoadSurfaceTyped() instead.

Parameters

renderer	the Renderer to use to create the GPU texture.
src	an IOStream that data will be read from.
type	a filename extension that represent this data ("BMP", "GIF", "PNG", etc).
closeio	true to close/free the IOStream before returning, false to leave it open.

Returns: a new texture, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: Texture.Texture; Texture.Destroy

◆ LoadTGA()

Surface SDL::LoadTGA ( IOStreamParam src )

inline

If you know you definitely have a TGA image, you can call this function, which will skip SDL_image's file format detection routines. Generally it's better to use the abstract interfaces; also, there is only an IOStream interface available here.

Parameters

src	an IOStream to load image data from.

Returns: SDL surface, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: LoadAVIF; LoadICO; LoadCUR; LoadBMP; LoadGIF; LoadJPG; LoadJXL; LoadLBM; LoadPCX; LoadPNG; LoadPNM; LoadSVG; LoadQOI; LoadTIF; LoadXCF; LoadXPM; LoadXV; LoadWEBP

◆ LoadTIF()

Surface SDL::LoadTIF ( IOStreamParam src )

inline

If you know you definitely have a TIFF image, you can call this function, which will skip SDL_image's file format detection routines. Generally it's better to use the abstract interfaces; also, there is only an IOStream interface available here.

Parameters

src	an IOStream to load image data from.

Returns: SDL surface, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: LoadAVIF; LoadICO; LoadCUR; LoadBMP; LoadGIF; LoadJPG; LoadJXL; LoadLBM; LoadPCX; LoadPNG; LoadPNM; LoadSVG; LoadQOI; LoadTGA; LoadXCF; LoadXPM; LoadXV; LoadWEBP

◆ LoadWEBP()

Surface SDL::LoadWEBP ( IOStreamParam src )

inline

If you know you definitely have a WEBP image, you can call this function, which will skip SDL_image's file format detection routines. Generally it's better to use the abstract interfaces; also, there is only an IOStream interface available here.

Parameters

src	an IOStream to load image data from.

Returns: SDL surface, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: LoadAVIF; LoadICO; LoadCUR; LoadBMP; LoadGIF; LoadJPG; LoadJXL; LoadLBM; LoadPCX; LoadPNG; LoadPNM; LoadSVG; LoadQOI; LoadTGA; LoadTIF; LoadXCF; LoadXPM; LoadXV

◆ LoadWEBPAnimation()

Animation SDL::LoadWEBPAnimation ( IOStreamParam src )

inline

If you know you definitely have a WEBP image, you can call this function, which will skip SDL_image's file format detection routines. Generally it's better to use the abstract interfaces; also, there is only an IOStream interface available here.

Parameters

src	an IOStream that data will be read from.

Returns: a new Animation, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: Animation.Animation; LoadAnimationTyped; Animation.Free

◆ LoadXCF()

Surface SDL::LoadXCF ( IOStreamParam src )

inline

If you know you definitely have a XCF image, you can call this function, which will skip SDL_image's file format detection routines. Generally it's better to use the abstract interfaces; also, there is only an IOStream interface available here.

Parameters

src	an IOStream to load image data from.

Returns: SDL surface, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: LoadAVIF; LoadICO; LoadCUR; LoadBMP; LoadGIF; LoadJPG; LoadJXL; LoadLBM; LoadPCX; LoadPNG; LoadPNM; LoadSVG; LoadQOI; LoadTGA; LoadTIF; LoadXPM; LoadXV; LoadWEBP

◆ LoadXPM()

Surface SDL::LoadXPM ( IOStreamParam src )

inline

If you know you definitely have a XPM image, you can call this function, which will skip SDL_image's file format detection routines. Generally it's better to use the abstract interfaces; also, there is only an IOStream interface available here.

Parameters

src	an IOStream to load image data from.

Returns: SDL surface, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: LoadAVIF; LoadICO; LoadCUR; LoadBMP; LoadGIF; LoadJPG; LoadJXL; LoadLBM; LoadPCX; LoadPNG; LoadPNM; LoadSVG; LoadQOI; LoadTGA; LoadTIF; LoadXCF; LoadXV; LoadWEBP

◆ LoadXV()

Surface SDL::LoadXV ( IOStreamParam src )

inline

If you know you definitely have a XV image, you can call this function, which will skip SDL_image's file format detection routines. Generally it's better to use the abstract interfaces; also, there is only an IOStream interface available here.

Parameters

src	an IOStream to load image data from.

Returns: SDL surface, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: LoadAVIF; LoadICO; LoadCUR; LoadBMP; LoadGIF; LoadJPG; LoadJXL; LoadLBM; LoadPCX; LoadPNG; LoadPNM; LoadSVG; LoadQOI; LoadTGA; LoadTIF; LoadXCF; LoadXPM; LoadWEBP

◆ ReadXPMFromArray()

Surface SDL::ReadXPMFromArray ( char ** xpm )

inline

The returned surface will be an 8bpp indexed surface, if possible, otherwise it will be 32bpp. If you always want 32-bit data, use ReadXPMFromArrayToRGB888() instead.

Parameters

xpm	a null-terminated array of strings that comprise XPM data.

Returns: a new SDL surface, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: ReadXPMFromArrayToRGB888

◆ ReadXPMFromArrayToRGB888()

Surface SDL::ReadXPMFromArrayToRGB888 ( char ** xpm )

inline

The returned surface will always be a 32-bit RGB surface. If you want 8-bit indexed colors (and the XPM data allows it), use ReadXPMFromArray() instead.

When done with the returned surface, the app should dispose of it with a call to Surface.Destroy().

Parameters

xpm	a null-terminated array of strings that comprise XPM data.

Returns: a new SDL surface, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: ReadXPMFromArray

◆ SaveAVIF() [1/2]

void SDL::SaveAVIF	(	SurfaceParam	surface,
		IOStreamParam	dst,
		int	quality,
		bool	closeio = `false`
	)

inline

If you just want to save to a filename, you can use SaveAVIF() instead.

If closeio is true, dst will be closed before returning, whether this function succeeds or not.

Parameters

surface	the SDL surface to save.
dst	the IOStream to save the image data to.
quality	the desired quality, ranging between 0 (lowest) and 100 (highest).
closeio	true to close/free the IOStream before returning, false to leave it open.

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.0.0.

◆ SaveAVIF() [2/2]

void SDL::SaveAVIF	(	SurfaceParam	surface,
		StringParam	file,
		int	quality
	)

inline

If the file already exists, it will be overwritten.

Parameters

surface	the SDL surface to save.
file	path on the filesystem to write new file to.
quality	the desired quality, ranging between 0 (lowest) and 100 (highest).

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.0.0.

◆ SaveJPG() [1/2]

void SDL::SaveJPG	(	SurfaceParam	surface,
		IOStreamParam	dst,
		int	quality,
		bool	closeio = `false`
	)

inline

If you just want to save to a filename, you can use SaveJPG() instead.

If closeio is true, dst will be closed before returning, whether this function succeeds or not.

Parameters

surface	the SDL surface to save.
dst	the IOStream to save the image data to.
quality	[0; 33] is Lowest quality, [34; 66] is Middle quality, [67; 100] is Highest quality.
closeio	true to close/free the IOStream before returning, false to leave it open.

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.0.0.

◆ SaveJPG() [2/2]

void SDL::SaveJPG	(	SurfaceParam	surface,
		StringParam	file,
		int	quality
	)

inline

If the file already exists, it will be overwritten.

Parameters

surface	the SDL surface to save.
file	path on the filesystem to write new file to.
quality	[0; 33] is Lowest quality, [34; 66] is Middle quality, [67; 100] is Highest quality.

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.0.0.

◆ SavePNG() [1/2]

void SDL::SavePNG	(	SurfaceParam	surface,
		IOStreamParam	dst,
		bool	closeio = `false`
	)

inline

If you just want to save to a filename, you can use SavePNG() instead.

If closeio is true, dst will be closed before returning, whether this function succeeds or not.

Parameters

surface	the SDL surface to save.
dst	the IOStream to save the image data to.
closeio	true to close/free the IOStream before returning, false to leave it open.

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.0.0.

◆ SavePNG() [2/2]

void SDL::SavePNG	(	SurfaceParam	surface,
		StringParam	file
	)

inline

If the file already exists, it will be overwritten.

Parameters

surface	the SDL surface to save.
file	path on the filesystem to write new file to.

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.0.0.

See also: SavePNG

◆ Surface() [1/2]

SDL::Surface::Surface	(	IOStreamParam	src,
		bool	closeio = `false`
	)

inline

An 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 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 Surface for its specifics, and use Surface.Convert 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: Surface.SetColorKey(image, SDL_RLEACCEL, image->format->colorkey);

If closeio is true, src will be closed before returning, whether this function succeeds or not. SDL_image reads everything it needs from src during this call in any case.

There is a separate function to read files from disk without having to deal with IOStream: Surface.Surface("filename.jpg") will call this function and manage those details for you, determining the file type from the filename's extension.

There is also LoadSurfaceTyped(), which is equivalent to this function except a file extension (like "BMP", "JPG", etc) can be specified, in case SDL_image cannot autodetect the file format.

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

Parameters

src	an IOStream that data will be read from.
closeio	true to close/free the IOStream before returning, false to leave it open.

Postcondition: a new SDL surface, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: Surface.Surface; LoadSurfaceTyped; Surface.Destroy

◆ Surface() [2/2]

SDL::Surface::Surface ( StringParam file )

inline

An 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 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 Surface for its specifics, and use Surface.Convert 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: Surface.SetColorKey(image, SDL_RLEACCEL, image->format->colorkey);

There is a separate function to read files from an IOStream, if you need an i/o abstraction to provide data from anywhere instead of a simple filesystem read; that function is Surface.Surface().

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

Parameters

file	a path on the filesystem to load an image from.

Postcondition: a new SDL surface, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: LoadSurfaceTyped; Surface.Surface; Surface.Destroy

◆ Texture() [1/2]

SDL::Texture::Texture	(	RendererParam	renderer,
		IOStreamParam	src,
		bool	closeio = `false`
	)

inline

An Texture represents an image in GPU memory, usable by SDL's 2D Render API. This can be significantly more efficient than using a CPU-bound Surface if you don't need to manipulate the image directly after loading it.

If the loaded image has transparency or a colorkey, a texture with an alpha channel will be created. Otherwise, SDL_image will attempt to create an Texture in the most format that most reasonably represents the image data (but in many cases, this will just end up being 32-bit RGB or 32-bit RGBA).

If closeio is true, src will be closed before returning, whether this function succeeds or not. SDL_image reads everything it needs from src during this call in any case.

There is a separate function to read files from disk without having to deal with IOStream: Texture.Texture(renderer, "filename.jpg") will call this function and manage those details for you, determining the file type from the filename's extension.

There is also LoadTextureTyped(), which is equivalent to this function except a file extension (like "BMP", "JPG", etc) can be specified, in case SDL_image cannot autodetect the file format.

If you would rather decode an image to an Surface (a buffer of pixels in CPU memory), call Surface.Surface() instead.

Parameters

renderer	the Renderer to use to create the GPU texture.
src	an IOStream that data will be read from.
closeio	true to close/free the IOStream before returning, false to leave it open.

Postcondition: a new texture, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: Texture.Texture; LoadTextureTyped; Texture.Destroy

◆ Texture() [2/2]

SDL::Texture::Texture	(	RendererParam	renderer,
		StringParam	file
	)

inline

An Texture represents an image in GPU memory, usable by SDL's 2D Render API. This can be significantly more efficient than using a CPU-bound Surface if you don't need to manipulate the image directly after loading it.

If the loaded image has transparency or a colorkey, a texture with an alpha channel will be created. Otherwise, SDL_image will attempt to create an Texture in the most format that most reasonably represents the image data (but in many cases, this will just end up being 32-bit RGB or 32-bit RGBA).

There is a separate function to read files from an IOStream, if you need an i/o abstraction to provide data from anywhere instead of a simple filesystem read; that function is Texture.Texture().

If you would rather decode an image to an Surface (a buffer of pixels in CPU memory), call Surface.Surface() instead.

Parameters

renderer	the Renderer to use to create the GPU texture.
file	a path on the filesystem to load an image from.

Postcondition: a new texture, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: LoadTextureTyped; Texture.Texture

Classes

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ SDL_IMAGE_VERSION

◆ SDL_IMAGE_VERSION_ATLEAST

Function Documentation

◆ Free()

◆ FreeAnimation()

◆ isAVIF()

◆ isBMP()

◆ isCUR()

◆ isGIF()

◆ isICO()

◆ isJPG()

◆ isJXL()

◆ isLBM()

◆ isPCX()

◆ isPNG()

◆ isPNM()

◆ isQOI()

◆ isSVG()

◆ isTIF()

◆ isWEBP()

◆ isXCF()

◆ isXPM()

◆ isXV()

◆ LoadAnimation() [1/2]

◆ LoadAnimation() [2/2]

◆ LoadAnimationTyped()

◆ LoadAVIF()

◆ LoadBMP()

◆ LoadCUR()

◆ LoadGIF()

◆ LoadGIFAnimation()

◆ LoadICO()

◆ LoadJPG()

◆ LoadJXL()

◆ LoadLBM()

◆ LoadPCX()

◆ LoadPNG()

◆ LoadPNM()

◆ LoadQOI()

◆ LoadSizedSVG()

◆ LoadSurface() [1/2]

◆ LoadSurface() [2/2]

◆ LoadSurfaceTyped()

◆ LoadSVG()

◆ LoadTexture() [1/2]

◆ LoadTexture() [2/2]

◆ LoadTextureTyped()

◆ LoadTGA()

◆ LoadTIF()

◆ LoadWEBP()

◆ LoadWEBPAnimation()

◆ LoadXCF()

◆ LoadXPM()

◆ LoadXV()

◆ ReadXPMFromArray()

◆ ReadXPMFromArrayToRGB888()

◆ SaveAVIF() [1/2]

◆ SaveAVIF() [2/2]

◆ SaveJPG() [1/2]

◆ SaveJPG() [2/2]

◆ SavePNG() [1/2]

◆ SavePNG() [2/2]

◆ Surface() [1/2]

◆ Surface() [2/2]

◆ Texture() [1/2]

◆ Texture() [2/2]