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

struct	SDL::AnimationConstParam
	Safely wrap Animation for non owning const parameters. More...

struct	SDL::AnimationEncoderParam
	Safely wrap AnimationEncoder for non owning parameters. More...

struct	SDL::AnimationDecoderParam
	Safely wrap AnimationDecoder for non owning parameters. More...

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

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

class	SDL::AnimationEncoder
	An object representing the encoder context. More...

struct	SDL::AnimationEncoderRef
	Semi-safe reference for AnimationEncoder. More...

class	SDL::AnimationDecoder
	An object representing animation decoder. More...

struct	SDL::AnimationDecoderRef
	Semi-safe reference for AnimationDecoder. 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.

using	SDL::AnimationEncoderRaw = IMG_AnimationEncoder *
	Alias to raw representation for AnimationEncoder.

using	SDL::AnimationDecoderRaw = IMG_AnimationDecoder *
	Alias to raw representation for AnimationDecoder.

using	SDL::AnimationDecoderStatus = IMG_AnimationDecoderStatus
	An enum representing the status of an animation decoder. More...

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

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

Surface	SDL::LoadSurfaceTyped (IOStreamParam src, StringParam type, 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 texture. More...

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

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

GPUTexture	SDL::LoadGPUTexture (GPUDeviceParam device, GPUCopyPass copy_pass, StringParam file, int width=nullptr, int height=nullptr)
	Load an image from a filesystem path into a GPU texture. More...

GPUTexture	SDL::LoadGPUTexture (GPUDeviceParam device, GPUCopyPass copy_pass, IOStreamParam src, bool closeio=false, int width=nullptr, int height=nullptr)
	Load an image from an SDL data source into a GPU texture. More...

GPUTexture	SDL::LoadGPUTextureTyped (GPUDeviceParam device, GPUCopyPass copy_pass, IOStreamParam src, StringParam type, bool closeio=false, int width=nullptr, int height=nullptr)
	Load an image from an SDL data source into a GPU texture. More...

Surface	SDL::GetClipboardImage ()
	Get the image currently in the clipboard. More...

bool	SDL::isANI (IOStreamParam src)
	Detect ANI animated cursor data on a readable/seekable IOStream. More...

bool	SDL::isAVIF (IOStreamParam src)
	Detect AVIF 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::isICO (IOStreamParam src)
	Detect ICO 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::isQOI (IOStreamParam src)
	Detect QOI 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::isTIF (IOStreamParam src)
	Detect TIFF image data on a readable/seekable IOStream. More...

bool	SDL::isWEBP (IOStreamParam src)
	Detect WEBP 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...

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

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

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

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

Surface	SDL::LoadICO (IOStreamParam src)
	Load a ICO 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::LoadSizedSVG (IOStreamParam src, const PointRaw &size)
	Load an SVG image, scaled to a specific size. 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::LoadWEBP (IOStreamParam src)
	Load a WEBP 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::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::Save (SurfaceParam surface, StringParam file)
	Save an Surface into an image file. More...

void	SDL::SaveTyped (SurfaceParam surface, IOStreamParam dst, StringParam type, bool closeio=false)
	Save an Surface into formatted image data, via an IOStream. 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::SaveBMP (SurfaceParam surface, StringParam file)
	Save an Surface into a BMP image file. More...

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

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

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

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

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

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

void	SDL::SaveICO (SurfaceParam surface, IOStreamParam dst, bool closeio=false)
	Save an Surface into ICO 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...

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::SaveTGA (SurfaceParam surface, StringParam file)
	Save an Surface into a TGA image file. More...

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

void	SDL::SaveWEBP (SurfaceParam surface, StringParam file, float quality)
	Save an Surface into a WEBP image file. More...

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

int	SDL::GetAnimationWidth (AnimationConstParam anim)
	Get the width in pixels.

int	SDL::GetAnimationHeight (AnimationConstParam anim)
	Get the height in pixels.

Point	SDL::GetAnimationSize (AnimationConstParam anim)
	Get the size in pixels.

int	SDL::GetAnimationCount (AnimationConstParam anim)
	Return the number of frames.

Surface	SDL::GetAnimationFrame (AnimationConstParam anim, int index)
	Return the frame image under given index. More...

int	SDL::GetAnimationDelay (AnimationConstParam anim, int index)
	Return the frame delay under given index. 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 IOStream. More...

Animation	SDL::LoadANIAnimation (IOStreamParam src)
	Load an ANI animation directly from an IOStream. More...

Animation	SDL::LoadAPNGAnimation (IOStreamParam src)
	Load an APNG animation directly from an IOStream. More...

Animation	SDL::LoadAVIFAnimation (IOStreamParam src)
	Load an AVIF animation directly from an IOStream. More...

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

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

void	SDL::SaveAnimation (AnimationParam anim, StringParam file)
	Save an animation to a file. More...

void	SDL::SaveAnimationTyped (AnimationParam anim, IOStreamParam dst, StringParam type, bool closeio=false)
	Save an animation to an IOStream. More...

void	SDL::SaveANIAnimation (AnimationParam anim, IOStreamParam dst, bool closeio=false)
	Save an animation in ANI format to an IOStream. More...

void	SDL::SaveAPNGAnimation (AnimationParam anim, IOStreamParam dst, bool closeio=false)
	Save an animation in APNG format to an IOStream. More...

void	SDL::SaveAVIFAnimation (AnimationParam anim, IOStreamParam dst, int quality, bool closeio=false)
	Save an animation in AVIF format to an IOStream. More...

void	SDL::SaveGIFAnimation (AnimationParam anim, IOStreamParam dst, bool closeio=false)
	Save an animation in GIF format to an IOStream. More...

void	SDL::SaveWEBPAnimation (AnimationParam anim, IOStreamParam dst, int quality, bool closeio=false)
	Save an animation in WEBP format to an IOStream. More...

Cursor	SDL::CreateAnimatedCursor (AnimationParam anim, const PointRaw &hotspot)
	Create an animated cursor from an animation. More...

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

AnimationEncoder	SDL::CreateAnimationEncoder (StringParam file)
	Create an encoder to save a series of images to a file. More...

AnimationEncoder	SDL::CreateAnimationEncoder (IOStreamParam dst, StringParam type, bool closeio=false)
	Create an encoder to save a series of images to an IOStream. More...

AnimationEncoder	SDL::CreateAnimationEncoderWithProperties (PropertiesParam props)
	Create an animation encoder with the specified properties. More...

void	SDL::AddAnimationEncoderFrame (AnimationEncoderParam encoder, SurfaceParam surface, Uint64 duration)
	Add a frame to an animation encoder. More...

void	SDL::CloseAnimationEncoder (AnimationEncoderRaw encoder)
	Close an animation encoder, finishing any encoding. More...

AnimationDecoder	SDL::CreateAnimationDecoder (StringParam file)
	Create a decoder to read a series of images from a file. More...

AnimationDecoder	SDL::CreateAnimationDecoder (IOStreamParam src, StringParam type, bool closeio=false)
	Create a decoder to read a series of images from an IOStream. More...

AnimationDecoder	SDL::CreateAnimationDecoderWithProperties (PropertiesParam props)
	Create an animation decoder with the specified properties. More...

PropertiesRef	SDL::GetAnimationDecoderProperties (AnimationDecoderParam decoder)
	Get the properties of an animation decoder. More...

Surface	SDL::GetAnimationDecoderFrame (AnimationDecoderParam decoder, Uint64 *duration)
	Get the next frame in an animation decoder. More...

AnimationDecoderStatus	SDL::GetAnimationDecoderStatus (AnimationDecoderParam decoder)
	Get the decoder status indicating the current state of the decoder. More...

void	SDL::ResetAnimationDecoder (AnimationDecoderParam decoder)
	Reset an animation decoder. More...

void	SDL::CloseAnimationDecoder (AnimationDecoderRaw decoder)
	Close an animation decoder, finishing any decoding. 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 texture. More...

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

int	SDL::Animation::GetWidth () const
	Get the width in pixels.

int	SDL::Animation::GetHeight () const
	Get the height in pixels.

Point	SDL::Animation::GetSize () const
	Get the size in pixels.

int	SDL::Animation::GetCount () const
	Return the number of frames.

Surface	SDL::Animation::GetFrame (int index) const
	Return the frame image under given index. More...

int	SDL::Animation::GetDelay (int index) const
	Return the frame delay under given index. More...

void	SDL::Animation::Save (StringParam file)
	Save an animation to a file. More...

void	SDL::Animation::SaveTyped (IOStreamParam dst, StringParam type, bool closeio=false)
	Save an animation to an IOStream. More...

void	SDL::Animation::SaveANI (IOStreamParam dst, bool closeio=false)
	Save an animation in ANI format to an IOStream. More...

void	SDL::Animation::SaveAPNG (IOStreamParam dst, bool closeio=false)
	Save an animation in APNG format to an IOStream. More...

void	SDL::Animation::SaveAVIF (IOStreamParam dst, int quality, bool closeio=false)
	Save an animation in AVIF format to an IOStream. More...

void	SDL::Animation::SaveGIF (IOStreamParam dst, bool closeio=false)
	Save an animation in GIF format to an IOStream. More...

void	SDL::Animation::SaveWEBP (IOStreamParam dst, int quality, bool closeio=false)
	Save an animation in WEBP format to an IOStream. More...

Cursor	SDL::Animation::CreateCursor (const PointRaw &hotspot)
	Create an animated cursor from an animation. More...

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

void	SDL::AnimationEncoder::AddFrame (SurfaceParam surface, Uint64 duration)
	Add a frame to an animation encoder. More...

void	SDL::AnimationEncoder::Close ()
	Close an animation encoder, finishing any encoding. More...

PropertiesRef	SDL::AnimationDecoder::GetProperties ()
	Get the properties of an animation decoder. More...

Surface	SDL::AnimationDecoder::GetFrame (Uint64 *duration)
	Get the next frame in an animation decoder. More...

AnimationDecoderStatus	SDL::AnimationDecoder::GetStatus ()
	Get the decoder status indicating the current state of the decoder. More...

void	SDL::AnimationDecoder::Reset ()
	Reset an animation decoder. More...

void	SDL::AnimationDecoder::Close ()
	Close an animation decoder, finishing any decoding. More...

Variables
constexpr AnimationDecoderStatus	SDL::DECODER_STATUS_INVALID
	The decoder is invalid. More...

constexpr AnimationDecoderStatus	SDL::DECODER_STATUS_OK
	The decoder is ready to decode the next frame. More...

constexpr AnimationDecoderStatus	SDL::DECODER_STATUS_FAILED
	The decoder failed to decode a frame, call GetError() for more information. More...

constexpr AnimationDecoderStatus	SDL::DECODER_STATUS_COMPLETE
	No more frames available. 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))

Typedef Documentation

◆ AnimationDecoderStatus

using SDL::AnimationDecoderStatus = typedef IMG_AnimationDecoderStatus

Since: This enum is available since SDL_image 3.4.0.

Function Documentation

◆ AddAnimationEncoderFrame()

void SDL::AddAnimationEncoderFrame	(	AnimationEncoderParam	encoder,
		SurfaceParam	surface,
		Uint64	duration
	)

inline

Parameters

encoder	the receiving images.
surface	the surface to add as the next frame in the animation.
duration	the duration of the frame, usually in milliseconds but can be other units if the `prop::AnimationEncoder.CREATE_TIMEBASE_DENOMINATOR_NUMBER` property is set when creating the encoder.

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.4.0.

See also: AnimationEncoder.AnimationEncoder; AnimationEncoder.AnimationEncoder; AnimationEncoder.AnimationEncoder; AnimationEncoder.Close

◆ AddFrame()

void SDL::AnimationEncoder::AddFrame	(	SurfaceParam	surface,
		Uint64	duration
	)

inline

Parameters

surface	the surface to add as the next frame in the animation.
duration	the duration of the frame, usually in milliseconds but can be other units if the `prop::AnimationEncoder.CREATE_TIMEBASE_DENOMINATOR_NUMBER` property is set when creating the encoder.

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.4.0.

See also: AnimationEncoder.AnimationEncoder; AnimationEncoder.AnimationEncoder; AnimationEncoder.AnimationEncoder; AnimationEncoder.Close

◆ Close() [1/2]

void SDL::AnimationEncoder::Close ( )

inline

Calling this function frees the animation encoder, and returns the final status of the encoding process.

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.4.0.

See also: AnimationEncoder.AnimationEncoder; AnimationEncoder.AnimationEncoder; AnimationEncoder.AnimationEncoder

◆ Close() [2/2]

void SDL::AnimationDecoder::Close ( )

inline

Calling this function frees the animation decoder, and returns the final status of the decoding process.

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.4.0.

See also: AnimationDecoder.AnimationDecoder; AnimationDecoder.AnimationDecoder; AnimationDecoder.AnimationDecoder

◆ CloseAnimationDecoder()

void SDL::CloseAnimationDecoder ( AnimationDecoderRaw decoder )

inline

Calling this function frees the animation decoder, and returns the final status of the decoding process.

Parameters

decoder the decoder to close.

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.4.0.

See also: AnimationDecoder.AnimationDecoder; AnimationDecoder.AnimationDecoder; AnimationDecoder.AnimationDecoder

◆ CloseAnimationEncoder()

void SDL::CloseAnimationEncoder ( AnimationEncoderRaw encoder )

inline

Calling this function frees the animation encoder, and returns the final status of the encoding process.

Parameters

encoder the encoder to close.

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.4.0.

See also: AnimationEncoder.AnimationEncoder; AnimationEncoder.AnimationEncoder; AnimationEncoder.AnimationEncoder

◆ CreateAnimatedCursor()

Cursor SDL::CreateAnimatedCursor	(	AnimationParam	anim,
		const PointRaw &	hotspot
	)

inline

Parameters

anim	an animation to use to create an animated cursor.
hotspot	the x, y position of the cursor hot spot.

Returns: the new cursor on success.

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.4.0.

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

◆ CreateAnimationDecoder() [1/2]

AnimationDecoder SDL::CreateAnimationDecoder	(	IOStreamParam	src,
		StringParam	type,
		bool	closeio = `false`
	)

inline

These animation types are currently supported:

ANI
APNG
AVIFS
GIF
WEBP

If closeio is true, src will be closed before returning if this function fails, or when the animation decoder is closed if this function succeeds.

Parameters

src	an IOStream containing a series of images.
closeio	true to close the IOStream when done, false to leave it open.
type	a filename extension that represent this data ("WEBP", etc).

Returns: a new AnimationDecoder, or nullptr on failure; call GetError() for more information.

Since: This function is available since SDL_image 3.4.0.

See also: AnimationDecoder.AnimationDecoder; AnimationDecoder.AnimationDecoder; AnimationDecoder.GetFrame; AnimationDecoder.Reset; AnimationDecoder.Close

◆ CreateAnimationDecoder() [2/2]

AnimationDecoder SDL::CreateAnimationDecoder ( StringParam file )

inline

These animation types are currently supported:

ANI
APNG
AVIFS
GIF
WEBP

The file type is determined from the file extension, e.g. "file.webp" will be decoded using WEBP.

Parameters

file	the file containing a series of images.

Returns: a new AnimationDecoder, or nullptr on failure; call GetError() for more information.

Since: This function is available since SDL_image 3.4.0.

See also: AnimationDecoder.AnimationDecoder; AnimationDecoder.AnimationDecoder; AnimationDecoder.GetFrame; AnimationDecoder.Reset; AnimationDecoder.Close

◆ CreateAnimationDecoderWithProperties()

AnimationDecoder SDL::CreateAnimationDecoderWithProperties ( PropertiesParam props )

inline

These animation types are currently supported:

ANI
APNG
AVIFS
GIF
WEBP

These are the supported properties:

prop::AnimationDecoder.CREATE_FILENAME_STRING: the file to load, if an IOStream isn't being used. This is required if prop::AnimationDecoder.CREATE_IOSTREAM_POINTER isn't set.
prop::AnimationDecoder.CREATE_IOSTREAM_POINTER: an IOStream containing a series of images. This should not be closed until the animation decoder is closed. This is required if prop::AnimationDecoder.CREATE_FILENAME_STRING isn't set.
prop::AnimationDecoder.CREATE_IOSTREAM_AUTOCLOSE_BOOLEAN: true if closing the animation decoder should also close the associated IOStream.
prop::AnimationDecoder.CREATE_TYPE_STRING: the input file type, e.g. "webp", defaults to the file extension if prop::AnimationDecoder.CREATE_FILENAME_STRING is set.

Parameters

props the properties of the animation decoder.

Returns: a new AnimationDecoder, or nullptr on failure; call GetError() for more information.

Since: This function is available since SDL_image 3.4.0.

See also: AnimationDecoder.AnimationDecoder; AnimationDecoder.AnimationDecoder; AnimationDecoder.GetFrame; AnimationDecoder.Reset; AnimationDecoder.Close

◆ CreateAnimationEncoder() [1/2]

AnimationEncoder SDL::CreateAnimationEncoder	(	IOStreamParam	dst,
		StringParam	type,
		bool	closeio = `false`
	)

inline

These animation types are currently supported:

ANI
APNG
AVIFS
GIF
WEBP

If closeio is true, dst will be closed before returning if this function fails, or when the animation encoder is closed if this function succeeds.

Parameters

dst	an IOStream that will be used to save the stream.
type	a filename extension that represent this data ("WEBP", etc).
closeio	true to close the IOStream when done, false to leave it open.

Returns: a new AnimationEncoder, or nullptr on failure; call GetError() for more information.

Since: This function is available since SDL_image 3.4.0.

See also: AnimationEncoder.AnimationEncoder; AnimationEncoder.AnimationEncoder; AnimationEncoder.AddFrame; AnimationEncoder.Close

◆ CreateAnimationEncoder() [2/2]

AnimationEncoder SDL::CreateAnimationEncoder ( StringParam file )

inline

These animation types are currently supported:

ANI
APNG
AVIFS
GIF
WEBP

The file type is determined from the file extension, e.g. "file.webp" will be encoded using WEBP.

Parameters

file	the file where the animation will be saved.

Returns: a new AnimationEncoder, or nullptr on failure; call GetError() for more information.

Since: This function is available since SDL_image 3.4.0.

See also: AnimationEncoder.AnimationEncoder; AnimationEncoder.AnimationEncoder; AnimationEncoder.AddFrame; AnimationEncoder.Close

◆ CreateAnimationEncoderWithProperties()

AnimationEncoder SDL::CreateAnimationEncoderWithProperties ( PropertiesParam props )

inline

These animation types are currently supported:

ANI
APNG
AVIFS
GIF
WEBP

These are the supported properties:

prop::AnimationEncoder.CREATE_FILENAME_STRING: the file to save, if an IOStream isn't being used. This is required if prop::AnimationEncoder.CREATE_IOSTREAM_POINTER isn't set.
prop::AnimationEncoder.CREATE_IOSTREAM_POINTER: an IOStream that will be used to save the stream. This should not be closed until the animation encoder is closed. This is required if prop::AnimationEncoder.CREATE_FILENAME_STRING isn't set.
prop::AnimationEncoder.CREATE_IOSTREAM_AUTOCLOSE_BOOLEAN: true if closing the animation encoder should also close the associated IOStream.
prop::AnimationEncoder.CREATE_TYPE_STRING: the output file type, e.g. "webp", defaults to the file extension if prop::AnimationEncoder.CREATE_FILENAME_STRING is set.
prop::AnimationEncoder.CREATE_QUALITY_NUMBER: the compression quality, in the range of 0 to 100. The higher the number, the higher the quality and file size. This defaults to a balanced value for compression and quality.
prop::AnimationEncoder.CREATE_TIMEBASE_NUMERATOR_NUMBER: the numerator of the fraction used to multiply the pts to convert it to seconds. This defaults to 1.
prop::AnimationEncoder.CREATE_TIMEBASE_DENOMINATOR_NUMBER: the denominator of the fraction used to multiply the pts to convert it to seconds. This defaults to 1000.

Parameters

props the properties of the animation encoder.

Returns: a new AnimationEncoder, or nullptr on failure; call GetError() for more information.

Since: This function is available since SDL_image 3.4.0.

See also: AnimationEncoder.AnimationEncoder; AnimationEncoder.AnimationEncoder; AnimationEncoder.AddFrame; AnimationEncoder.Close

◆ CreateCursor()

Cursor SDL::Animation::CreateCursor ( const PointRaw & hotspot )

inline

Parameters

hotspot the x, y position of the cursor hot spot.

Returns: the new cursor on success.

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.4.0.

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

◆ 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; Animation.Animation; LoadAnimationTyped; LoadANIAnimation; LoadAPNGAnimation; LoadAVIFAnimation; LoadGIFAnimation; LoadWEBPAnimation

◆ 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; LoadANIAnimation; LoadAPNGAnimation; LoadAVIFAnimation; LoadGIFAnimation; LoadWEBPAnimation

◆ GetAnimationDecoderFrame()

Surface SDL::GetAnimationDecoderFrame	(	AnimationDecoderParam	decoder,
		Uint64 *	duration
	)

inline

This function decodes the next frame in the animation decoder, returning it as an Surface.

Parameters

decoder	the animation decoder.
duration	the duration of the frame, usually in milliseconds but can be other units if the `prop::AnimationDecoder.CREATE_TIMEBASE_DENOMINATOR_NUMBER` property is set when creating the decoder.

Returns: the Surface for the next frame in the animation.

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.4.0.

See also: AnimationDecoder.AnimationDecoder; AnimationDecoder.AnimationDecoder; AnimationDecoder.AnimationDecoder; AnimationDecoder.GetStatus; AnimationDecoder.Reset; AnimationDecoder.Close

◆ GetAnimationDecoderProperties()

PropertiesRef SDL::GetAnimationDecoderProperties ( AnimationDecoderParam decoder )

inline

This function returns the properties of the animation decoder, which holds information about the underlying image such as description, copyright text and loop count.

Parameters

decoder the animation decoder.

Returns: the properties ID of the animation decoder, or 0 if there are no properties; call GetError() for more information.

Since: This function is available since SDL_image 3.4.0.

See also: AnimationDecoder.AnimationDecoder; AnimationDecoder.AnimationDecoder; AnimationDecoder.AnimationDecoder

◆ GetAnimationDecoderStatus()

AnimationDecoderStatus SDL::GetAnimationDecoderStatus ( AnimationDecoderParam decoder )

inline

Parameters

decoder the decoder to get the status of.

Returns: the status of the underlying decoder, or DECODER_STATUS_INVALID if the given decoder is invalid.

Since: This function is available since SDL_image 3.4.0.

See also: AnimationDecoder.GetFrame

◆ GetAnimationDelay()

int SDL::GetAnimationDelay	(	AnimationConstParam	anim,
		int	index
	)

inline

Parameters

anim	Animation to dispose of.
index	the index to get frame, within [0, GetCount() - 1]

◆ GetAnimationFrame()

Surface SDL::GetAnimationFrame	(	AnimationConstParam	anim,
		int	index
	)

inline

Parameters

anim	Animation to dispose of.
index	the index to get frame, within [0, GetCount() - 1]

◆ GetClipboardImage()

Surface SDL::GetClipboardImage ( )

inline

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

Returns: a new SDL surface, or nullptr if no supported image is available.

Since: This function is available since SDL_image 3.4.0.

◆ GetDelay()

int SDL::Animation::GetDelay ( int index ) const

inline

Parameters

index the index to get frame, within [0, GetCount() - 1]

◆ GetFrame() [1/2]

Surface SDL::Animation::GetFrame ( int index ) const

inline

Parameters

index the index to get frame, within [0, GetCount() - 1]

◆ GetFrame() [2/2]

Surface SDL::AnimationDecoder::GetFrame ( Uint64 * duration )

inline

This function decodes the next frame in the animation decoder, returning it as an Surface. The returned surface should be freed with SDL_FreeSurface() when no longer needed.

Parameters

duration the duration of the frame, usually in milliseconds but can be other units if the prop::AnimationDecoder.CREATE_TIMEBASE_DENOMINATOR_NUMBER property is set when creating the decoder.

Returns: the Surface for the next frame in the animation.

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.4.0.

See also: AnimationDecoder.AnimationDecoder; AnimationDecoder.AnimationDecoder; AnimationDecoder.AnimationDecoder; AnimationDecoder.GetStatus; AnimationDecoder.Reset; AnimationDecoder.Close

◆ GetProperties()

PropertiesRef SDL::AnimationDecoder::GetProperties ( )

inline

This function returns the properties of the animation decoder, which holds information about the underlying image such as description, copyright text and loop count.

Returns: the properties ID of the animation decoder, or 0 if there are no properties; call GetError() for more information.

Since: This function is available since SDL_image 3.4.0.

See also: AnimationDecoder.AnimationDecoder; AnimationDecoder.AnimationDecoder; AnimationDecoder.AnimationDecoder

◆ GetStatus()

AnimationDecoderStatus SDL::AnimationDecoder::GetStatus ( )

inline

Returns: the status of the underlying decoder, or DECODER_STATUS_INVALID if the given decoder is invalid.

Since: This function is available since SDL_image 3.4.0.

See also: AnimationDecoder.GetFrame

◆ isANI()

bool SDL::isANI ( 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: true if this is ANI animated cursor data, false otherwise.

Since: This function is available since SDL_image 3.4.0.

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

◆ 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: true if this is AVIF data, false otherwise.

Since: This function is available since SDL_image 3.0.0.

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

◆ 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: true if this is BMP data, false otherwise.

Since: This function is available since SDL_image 3.0.0.

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

◆ 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: true if this is CUR data, false otherwise.

Since: This function is available since SDL_image 3.0.0.

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

◆ 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: true if this is GIF data, false otherwise.

Since: This function is available since SDL_image 3.0.0.

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

◆ 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: true if this is ICO data, false otherwise.

Since: This function is available since SDL_image 3.0.0.

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

◆ 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: true if this is JPG data, false otherwise.

Since: This function is available since SDL_image 3.0.0.

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

◆ 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: true if this is JXL data, false otherwise.

Since: This function is available since SDL_image 3.0.0.

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

◆ 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: true if this is LBM data, false otherwise.

Since: This function is available since SDL_image 3.0.0.

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

◆ 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: true if this is PCX data, false otherwise.

Since: This function is available since SDL_image 3.0.0.

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

◆ 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: true if this is PNG data, false otherwise.

Since: This function is available since SDL_image 3.0.0.

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

◆ 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: true if this is PNM data, false otherwise.

Since: This function is available since SDL_image 3.0.0.

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

◆ 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: true if this is QOI data, false otherwise.

Since: This function is available since SDL_image 3.0.0.

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

◆ 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: true if this is SVG data, false otherwise.

Since: This function is available since SDL_image 3.0.0.

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

◆ 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: true if this is TIFF data, false otherwise.

Since: This function is available since SDL_image 3.0.0.

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

◆ 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: true if this is WEBP data, false otherwise.

Since: This function is available since SDL_image 3.0.0.

See also: isANI; isAVIF; isBMP; isCUR; isGIF; isICO; isJPG; isJXL; isLBM; isPCX; isPNG; isPNM; isQOI; isSVG; 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: true if this is XCF data, false otherwise.

Since: This function is available since SDL_image 3.0.0.

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

◆ 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: true if this is XPM data, false otherwise.

Since: This function is available since SDL_image 3.0.0.

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

◆ 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: true if this is XV data, false otherwise.

Since: This function is available since SDL_image 3.0.0.

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

◆ LoadANIAnimation()

Animation SDL::LoadANIAnimation ( IOStreamParam src )

inline

If you know you definitely have an ANI 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.

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

Parameters

src	an IOStream from which data will be read.

Returns: a new Animation, or nullptr on error.

Since: This function is available since SDL_image 3.4.0.

See also: isANI; Animation.Animation; Animation.Animation; LoadAnimationTyped; LoadAPNGAnimation; LoadAVIFAnimation; LoadGIFAnimation; LoadWEBPAnimation; Animation.Free

◆ 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.CreateCursor; Animation.Animation; LoadAnimationTyped; LoadANIAnimation; LoadAPNGAnimation; LoadAVIFAnimation; LoadGIFAnimation; LoadWEBPAnimation; 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.CreateCursor; Animation.Animation; LoadAnimationTyped; LoadANIAnimation; LoadAPNGAnimation; LoadAVIFAnimation; LoadGIFAnimation; LoadWEBPAnimation; 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.CreateCursor; Animation.Animation; Animation.Animation; LoadANIAnimation; LoadAPNGAnimation; LoadAVIFAnimation; LoadGIFAnimation; LoadWEBPAnimation; Animation.Free

◆ LoadAPNGAnimation()

Animation SDL::LoadAPNGAnimation ( IOStreamParam src )

inline

If you know you definitely have an APNG 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.

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

Parameters

src	an IOStream from which data will be read.

Returns: a new Animation, or nullptr on error.

Since: This function is available since SDL_image 3.4.0.

See also: isPNG; Animation.Animation; Animation.Animation; LoadAnimationTyped; LoadANIAnimation; LoadAVIFAnimation; LoadGIFAnimation; LoadWEBPAnimation; 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: LoadBMP; LoadCUR; LoadGIF; LoadICO; LoadJPG; LoadJXL; LoadLBM; LoadPCX; LoadPNG; LoadPNM; LoadQOI; LoadSVG; LoadTGA; LoadTIF; LoadWEBP; LoadXCF; LoadXPM; LoadXV

◆ LoadAVIFAnimation()

Animation SDL::LoadAVIFAnimation ( IOStreamParam src )

inline

If you know you definitely have an AVIF animation, 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.

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.

Returns: a new Animation, or nullptr on error.

Since: This function is available since SDL_image 3.4.0.

See also: isAVIF; Animation.Animation; Animation.Animation; LoadAnimationTyped; LoadANIAnimation; LoadAPNGAnimation; LoadGIFAnimation; LoadWEBPAnimation; Animation.Free

◆ 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; LoadCUR; LoadGIF; LoadICO; LoadJPG; LoadJXL; LoadLBM; LoadPCX; LoadPNG; LoadPNM; LoadQOI; LoadSVG; LoadTGA; LoadTIF; LoadWEBP; LoadXCF; LoadXPM; LoadXV

◆ 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; LoadBMP; LoadGIF; LoadICO; LoadJPG; LoadJXL; LoadLBM; LoadPCX; LoadPNG; LoadPNM; LoadQOI; LoadSVG; LoadTGA; LoadTIF; LoadWEBP; LoadXCF; LoadXPM; LoadXV

◆ 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; LoadBMP; LoadCUR; LoadICO; LoadJPG; LoadJXL; LoadLBM; LoadPCX; LoadPNG; LoadPNM; LoadQOI; LoadSVG; LoadTGA; LoadTIF; LoadWEBP; LoadXCF; LoadXPM; LoadXV

◆ 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: isGIF; Animation.Animation; Animation.Animation; LoadAnimationTyped; LoadANIAnimation; LoadAPNGAnimation; LoadAVIFAnimation; LoadWEBPAnimation; Animation.Free

◆ LoadGPUTexture() [1/2]

GPUTexture SDL::LoadGPUTexture	(	GPUDeviceParam	device,
		GPUCopyPass	copy_pass,
		IOStreamParam	src,
		bool	closeio = `false`,
		int *	width = `nullptr`,
		int *	height = `nullptr`
	)

inline

An GPUTexture represents an image in GPU memory, usable by SDL's GPU API. Regardless of the source format of the image, this function will create a GPU texture with the format GPU_TEXTUREFORMAT_R8G8B8A8_UNORM with no mip levels. It can be bound as a sampled texture from a graphics or compute pipeline and as a a readonly storage texture in a compute pipeline.

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: `LoadGPUTexture(device, copy_pass, "filename.jpg", width, height) will call this function and manage those details for you, determining the file type from the filename's extension.

There is also LoadGPUTextureTyped(), 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.

When done with the returned texture, the app should dispose of it with a call to GPUDevice.ReleaseTexture().

Parameters

device	the GPUDevice to use to create the GPU texture.
copy_pass	the GPUCopyPass to use to upload the loaded image to 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.
width	a pointer filled in with the width of the GPU texture. may be nullptr.
height	a pointer filled in with the width of the GPU texture. may be nullptr.

Returns: a new GPU texture, or nullptr on error.

Since: This function is available since SDL_image 3.4.0.

See also: LoadGPUTexture; LoadGPUTextureTyped

◆ LoadGPUTexture() [2/2]

GPUTexture SDL::LoadGPUTexture	(	GPUDeviceParam	device,
		GPUCopyPass	copy_pass,
		StringParam	file,
		int *	width = `nullptr`,
		int *	height = `nullptr`
	)

inline

An GPUTexture represents an image in GPU memory, usable by SDL's GPU API. Regardless of the source format of the image, this function will create a GPU texture with the format GPU_TEXTUREFORMAT_R8G8B8A8_UNORM with no mip levels. It can be bound as a sampled texture from a graphics or compute pipeline and as a a readonly storage texture in a compute pipeline.

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

When done with the returned texture, the app should dispose of it with a call to GPUDevice.ReleaseTexture().

Parameters

device	the GPUDevice to use to create the GPU texture.
copy_pass	the GPUCopyPass to use to upload the loaded image to the GPU texture.
file	a path on the filesystem to load an image from.
width	a pointer filled in with the width of the GPU texture. may be nullptr.
height	a pointer filled in with the width of the GPU texture. may be nullptr.

Returns: a new GPU texture, or nullptr on error.

Since: This function is available since SDL_image 3.4.0.

See also: LoadGPUTextureTyped; LoadGPUTexture

◆ LoadGPUTextureTyped()

GPUTexture SDL::LoadGPUTextureTyped	(	GPUDeviceParam	device,
		GPUCopyPass	copy_pass,
		IOStreamParam	src,
		StringParam	type,
		bool	closeio = `false`,
		int *	width = `nullptr`,
		int *	height = `nullptr`
	)

inline

An GPUTexture represents an image in GPU memory, usable by SDL's GPU API. Regardless of the source format of the image, this function will create a GPU texture with the format GPU_TEXTUREFORMAT_R8G8B8A8_UNORM with no mip levels. It can be bound as a sampled texture from a graphics or compute pipeline and as a a readonly storage texture in a compute pipeline.

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: `LoadGPUTexture(device, copy_pass, "filename.jpg", width, height) will call this function and manage those details for you, determining the file type from the filename's extension.

There is also LoadGPUTexture(), 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.

When done with the returned texture, the app should dispose of it with a call to GPUDevice.ReleaseTexture().

Parameters

device	the GPUDevice to use to create the GPU texture.
copy_pass	the GPUCopyPass to use to upload the loaded image to 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.
width	a pointer filled in with the width of the GPU texture. may be nullptr.
height	a pointer filled in with the width of the GPU texture. may be nullptr.

Returns: a new GPU texture, or nullptr on error.

Since: This function is available since SDL_image 3.4.0.

See also: LoadGPUTexture; LoadGPUTexture

◆ 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; LoadBMP; LoadCUR; LoadGIF; LoadJPG; LoadJXL; LoadLBM; LoadPCX; LoadPNG; LoadPNM; LoadQOI; LoadSVG; LoadTGA; LoadTIF; LoadWEBP; LoadXCF; LoadXPM; LoadXV

◆ 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; LoadBMP; LoadCUR; LoadGIF; LoadICO; LoadJXL; LoadLBM; LoadPCX; LoadPNG; LoadPNM; LoadQOI; LoadSVG; LoadTGA; LoadTIF; LoadWEBP; LoadXCF; LoadXPM; LoadXV

◆ 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; LoadBMP; LoadCUR; LoadGIF; LoadICO; LoadJPG; LoadLBM; LoadPCX; LoadPNG; LoadPNM; LoadQOI; LoadSVG; LoadTGA; LoadTIF; LoadWEBP; LoadXCF; LoadXPM; LoadXV

◆ 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; LoadBMP; LoadCUR; LoadGIF; LoadICO; LoadJPG; LoadJXL; LoadPCX; LoadPNG; LoadPNM; LoadQOI; LoadSVG; LoadTGA; LoadTIF; LoadWEBP; LoadXCF; LoadXPM; LoadXV

◆ 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; LoadBMP; LoadCUR; LoadGIF; LoadICO; LoadJPG; LoadJXL; LoadLBM; LoadPNG; LoadPNM; LoadQOI; LoadSVG; LoadTGA; LoadTIF; LoadWEBP; LoadXCF; LoadXPM; LoadXV

◆ 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; LoadBMP; LoadCUR; LoadGIF; LoadICO; LoadJPG; LoadJXL; LoadLBM; LoadPCX; LoadPNM; LoadQOI; LoadSVG; LoadTGA; LoadTIF; LoadWEBP; LoadXCF; LoadXPM; LoadXV

◆ 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; LoadBMP; LoadCUR; LoadGIF; LoadICO; LoadJPG; LoadJXL; LoadLBM; LoadPCX; LoadPNG; LoadQOI; LoadSVG; LoadTGA; LoadTIF; LoadWEBP; LoadXCF; LoadXPM; LoadXV

◆ 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; LoadBMP; LoadCUR; LoadGIF; LoadICO; LoadJPG; LoadJXL; LoadLBM; LoadPCX; LoadPNG; LoadPNM; LoadSVG; LoadTGA; LoadTIF; LoadWEBP; LoadXCF; LoadXPM; LoadXV

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

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

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.

See also: LoadSVG

◆ LoadSurface() [1/2]

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

inline

Load a BMP or PNG image from a seekable SDL data stream.

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: LoadSurface("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 LoadSurface() 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

The new surface should be freed with Surface.Destroy(). Not doing so will result in a memory leak.

Parameters

src	the data stream for the surface.
closeio	if true, calls IOStream.Close() on `src` before returning, even in the case of an error.

Returns: a pointer to a new Surface structure or nullptr on failure; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.4.0.

See also: Surface.Destroy; LoadSurface

◆ LoadSurface() [2/2]

Surface SDL::LoadSurface ( StringParam file )

inline

Load a BMP or PNG image from a file.

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

The new surface should be freed with Surface.Destroy(). Not doing so will result in a memory leak.

Parameters

file	the file to load.

Returns: a pointer to a new Surface structure or nullptr on failure; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.4.0.

See also: Surface.Destroy; LoadSurface

◆ 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: LoadSurface("filename.jpg") will call this function and manage those details for you, determining the file type from the filename's extension.

There is also LoadSurface(), 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

◆ 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; LoadBMP; LoadCUR; LoadGIF; LoadICO; LoadJPG; LoadJXL; LoadLBM; LoadPCX; LoadPNG; LoadPNM; LoadQOI; LoadSizedSVG; LoadTGA; LoadTIF; LoadWEBP; LoadXCF; LoadXPM; LoadXV

◆ 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 LoadSurface() instead.

Parameters

renderer	the Renderer to use to create the 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

◆ 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 LoadSurface() instead.

Parameters

renderer	the Renderer to use to create the 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 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; LoadBMP; LoadCUR; LoadGIF; LoadICO; LoadJPG; LoadJXL; LoadLBM; LoadPCX; LoadPNG; LoadPNM; LoadQOI; LoadSVG; LoadTIF; LoadWEBP; LoadXCF; LoadXPM; LoadXV

◆ 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; LoadBMP; LoadCUR; LoadGIF; LoadICO; LoadJPG; LoadJXL; LoadLBM; LoadPCX; LoadPNG; LoadPNM; LoadQOI; LoadSVG; LoadTGA; LoadWEBP; LoadXCF; LoadXPM; LoadXV

◆ 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; LoadBMP; LoadCUR; LoadGIF; LoadICO; LoadJPG; LoadJXL; LoadLBM; LoadPCX; LoadPNG; LoadPNM; LoadQOI; LoadSVG; 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: isWEBP; Animation.Animation; Animation.Animation; LoadAnimationTyped; LoadANIAnimation; LoadAPNGAnimation; LoadAVIFAnimation; LoadGIFAnimation; 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; LoadBMP; LoadCUR; LoadGIF; LoadICO; LoadJPG; LoadJXL; LoadLBM; LoadPCX; LoadPNG; LoadPNM; LoadQOI; LoadSVG; LoadTGA; LoadTIF; LoadWEBP; LoadXPM; LoadXV

◆ 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; LoadBMP; LoadCUR; LoadGIF; LoadICO; LoadJPG; LoadJXL; LoadLBM; LoadPCX; LoadPNG; LoadPNM; LoadQOI; LoadSVG; LoadTGA; LoadTIF; LoadWEBP; LoadXCF; LoadXV

◆ 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; LoadBMP; LoadCUR; LoadGIF; LoadICO; LoadJPG; LoadJXL; LoadLBM; LoadPCX; LoadPNG; LoadPNM; LoadQOI; LoadSVG; LoadTGA; LoadTIF; LoadWEBP; LoadXCF; LoadXPM

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

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

◆ Reset()

void SDL::AnimationDecoder::Reset ( )

inline

Calling this function resets the animation decoder, allowing it to start from the beginning again. This is useful if you want to decode the frame sequence again without creating a new decoder.

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.4.0.

See also: AnimationDecoder.AnimationDecoder; AnimationDecoder.AnimationDecoder; AnimationDecoder.AnimationDecoder; AnimationDecoder.GetFrame; AnimationDecoder.Close

◆ ResetAnimationDecoder()

void SDL::ResetAnimationDecoder ( AnimationDecoderParam decoder )

inline

Calling this function resets the animation decoder, allowing it to start from the beginning again. This is useful if you want to decode the frame sequence again without creating a new decoder.

Parameters

decoder the decoder to reset.

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.4.0.

See also: AnimationDecoder.AnimationDecoder; AnimationDecoder.AnimationDecoder; AnimationDecoder.AnimationDecoder; AnimationDecoder.GetFrame; AnimationDecoder.Close

◆ Save() [1/2]

void SDL::Animation::Save ( StringParam file )

inline

For formats that accept a quality, a default quality of 90 will be used.

Parameters

file	path on the filesystem containing an animated image.

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.4.0.

See also: Animation.SaveTyped; Animation.SaveANI; Animation.SaveAPNG; Animation.SaveAVIF; Animation.SaveGIF; Animation.SaveWEBP

◆ Save() [2/2]

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

inline

If the file already exists, it will be overwritten.

For formats that accept a quality, a default quality of 90 will be used.

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

See also: SaveTyped; SaveAVIF; SaveBMP; SaveCUR; SaveGIF; SaveICO; SaveJPG; SavePNG; SaveTGA; SaveWEBP

◆ SaveANI()

void SDL::Animation::SaveANI	(	IOStreamParam	dst,
		bool	closeio = `false`
	)

inline

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

Parameters

dst	an IOStream from which data will be written 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.4.0.

See also: Animation.Save; Animation.SaveTyped; Animation.SaveAPNG; Animation.SaveAVIF; Animation.SaveGIF; Animation.SaveWEBP

◆ SaveANIAnimation()

void SDL::SaveANIAnimation	(	AnimationParam	anim,
		IOStreamParam	dst,
		bool	closeio = `false`
	)

inline

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

Parameters

anim	the animation to save.
dst	an IOStream from which data will be written 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.4.0.

See also: Animation.Save; Animation.SaveTyped; Animation.SaveAPNG; Animation.SaveAVIF; Animation.SaveGIF; Animation.SaveWEBP

◆ SaveAnimation()

void SDL::SaveAnimation	(	AnimationParam	anim,
		StringParam	file
	)

inline

For formats that accept a quality, a default quality of 90 will be used.

Parameters

anim	the animation to save.
file	path on the filesystem containing an animated image.

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.4.0.

See also: Animation.SaveTyped; Animation.SaveANI; Animation.SaveAPNG; Animation.SaveAVIF; Animation.SaveGIF; Animation.SaveWEBP

◆ SaveAnimationTyped()

void SDL::SaveAnimationTyped	(	AnimationParam	anim,
		IOStreamParam	dst,
		StringParam	type,
		bool	closeio = `false`
	)

inline

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

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

For formats that accept a quality, a default quality of 90 will be used.

Parameters

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

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.4.0.

See also: Animation.Save; Animation.SaveANI; Animation.SaveAPNG; Animation.SaveAVIF; Animation.SaveGIF; Animation.SaveWEBP

◆ SaveAPNG()

void SDL::Animation::SaveAPNG	(	IOStreamParam	dst,
		bool	closeio = `false`
	)

inline

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

Parameters

dst	an IOStream from which data will be written 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.4.0.

See also: Animation.Save; Animation.SaveTyped; Animation.SaveANI; Animation.SaveAVIF; Animation.SaveGIF; Animation.SaveWEBP

◆ SaveAPNGAnimation()

void SDL::SaveAPNGAnimation	(	AnimationParam	anim,
		IOStreamParam	dst,
		bool	closeio = `false`
	)

inline

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

Parameters

anim	the animation to save.
dst	an IOStream from which data will be written 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.4.0.

See also: Animation.Save; Animation.SaveTyped; Animation.SaveANI; Animation.SaveAVIF; Animation.SaveGIF; Animation.SaveWEBP

◆ SaveAVIF() [1/3]

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

inline

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

Parameters

dst	an IOStream from which data will be written 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.4.0.

See also: Animation.Save; Animation.SaveTyped; Animation.SaveANI; Animation.SaveAPNG; Animation.SaveGIF; Animation.SaveWEBP

◆ SaveAVIF() [2/3]

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.

See also: SaveAVIF

◆ SaveAVIF() [3/3]

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.

See also: SaveAVIF

◆ SaveAVIFAnimation()

void SDL::SaveAVIFAnimation	(	AnimationParam	anim,
		IOStreamParam	dst,
		int	quality,
		bool	closeio = `false`
	)

inline

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

Parameters

anim	the animation to save.
dst	an IOStream from which data will be written 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.4.0.

See also: Animation.Save; Animation.SaveTyped; Animation.SaveANI; Animation.SaveAPNG; Animation.SaveGIF; Animation.SaveWEBP

◆ SaveBMP() [1/2]

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

inline

If you just want to save to a filename, you can use SaveBMP() 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.4.0.

See also: SaveBMP

◆ SaveBMP() [2/2]

void SDL::SaveBMP	(	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.4.0.

See also: SaveBMP

◆ SaveCUR() [1/2]

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

inline

If you just want to save to a filename, you can use SaveCUR() 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.4.0.

See also: SaveCUR

◆ SaveCUR() [2/2]

void SDL::SaveCUR	(	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.4.0.

See also: SaveCUR

◆ SaveGIF() [1/3]

void SDL::Animation::SaveGIF	(	IOStreamParam	dst,
		bool	closeio = `false`
	)

inline

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

Parameters

dst	an IOStream from which data will be written 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.4.0.

See also: Animation.Save; Animation.SaveTyped; Animation.SaveANI; Animation.SaveAPNG; Animation.SaveAVIF; Animation.SaveWEBP

◆ SaveGIF() [2/3]

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

inline

If you just want to save to a filename, you can use SaveGIF() 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.4.0.

See also: SaveGIF

◆ SaveGIF() [3/3]

void SDL::SaveGIF	(	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.4.0.

See also: SaveGIF

◆ SaveGIFAnimation()

void SDL::SaveGIFAnimation	(	AnimationParam	anim,
		IOStreamParam	dst,
		bool	closeio = `false`
	)

inline

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

Parameters

anim	the animation to save.
dst	an IOStream from which data will be written 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.4.0.

See also: Animation.Save; Animation.SaveTyped; Animation.SaveANI; Animation.SaveAPNG; Animation.SaveAVIF; Animation.SaveWEBP

◆ SaveICO() [1/2]

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

inline

If you just want to save to a filename, you can use SaveICO() 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.4.0.

See also: SaveICO

◆ SaveICO() [2/2]

void SDL::SaveICO	(	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.4.0.

See also: SaveICO

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

See also: SaveJPG

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

See also: SaveJPG

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

See also: SavePNG

◆ 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

◆ SaveTGA() [1/2]

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

inline

If you just want to save to a filename, you can use SaveTGA() 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.4.0.

See also: SaveTGA

◆ SaveTGA() [2/2]

void SDL::SaveTGA	(	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.4.0.

See also: SaveTGA

◆ SaveTyped() [1/2]

void SDL::Animation::SaveTyped	(	IOStreamParam	dst,
		StringParam	type,
		bool	closeio = `false`
	)

inline

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

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

For formats that accept a quality, a default quality of 90 will be used.

Parameters

dst	an IOStream that data will be written to.
type	a filename extension that represent this data ("GIF", etc).
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.4.0.

See also: Animation.Save; Animation.SaveANI; Animation.SaveAPNG; Animation.SaveAVIF; Animation.SaveGIF; Animation.SaveWEBP

◆ SaveTyped() [2/2]

void SDL::SaveTyped	(	SurfaceParam	surface,
		IOStreamParam	dst,
		StringParam	type,
		bool	closeio = `false`
	)

inline

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

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

For formats that accept a quality, a default quality of 90 will be used.

Parameters

surface	the SDL surface to save.
dst	the IOStream to save the image data to.
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.

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.4.0.

See also: Save; SaveAVIF; SaveBMP; SaveCUR; SaveGIF; SaveICO; SaveJPG; SavePNG; SaveTGA; SaveWEBP

◆ SaveWEBP() [1/3]

void SDL::Animation::SaveWEBP	(	IOStreamParam	dst,
		int	quality,
		bool	closeio = `false`
	)

inline

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

Parameters

dst	an IOStream from which data will be written to.
quality	between 0 and 100. For lossy, 0 gives the smallest size and 100 the largest. For lossless, this parameter is the amount of effort put into the compression: 0 is the fastest but gives larger files compared to the slowest, but best, 100.
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.4.0.

See also: Animation.Save; Animation.SaveTyped; Animation.SaveANI; Animation.SaveAPNG; Animation.SaveAVIF; Animation.SaveGIF

◆ SaveWEBP() [2/3]

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

inline

If you just want to save to a filename, you can use SaveWEBP() 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	between 0 and 100. For lossy, 0 gives the smallest size and 100 the largest. For lossless, this parameter is the amount of effort put into the compression: 0 is the fastest but gives larger files compared to the slowest, but best, 100.
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.4.0.

See also: SaveWEBP

◆ SaveWEBP() [3/3]

void SDL::SaveWEBP	(	SurfaceParam	surface,
		StringParam	file,
		float	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 the new file to.
quality	between 0 and 100. For lossy, 0 gives the smallest size and 100 the largest. For lossless, this parameter is the amount of effort put into the compression: 0 is the fastest but gives larger files compared to the slowest, but best, 100.

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.4.0.

See also: SaveWEBP

◆ SaveWEBPAnimation()

void SDL::SaveWEBPAnimation	(	AnimationParam	anim,
		IOStreamParam	dst,
		int	quality,
		bool	closeio = `false`
	)

inline

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

Parameters

anim	the animation to save.
dst	an IOStream from which data will be written to.
quality	between 0 and 100. For lossy, 0 gives the smallest size and 100 the largest. For lossless, this parameter is the amount of effort put into the compression: 0 is the fastest but gives larger files compared to the slowest, but best, 100.
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.4.0.

See also: Animation.Save; Animation.SaveTyped; Animation.SaveANI; Animation.SaveAPNG; Animation.SaveAVIF; Animation.SaveGIF

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

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

Variable Documentation

◆ DECODER_STATUS_COMPLETE

constexpr AnimationDecoderStatus SDL::DECODER_STATUS_COMPLETE

constexpr

Initial value:

=

IMG_DECODER_STATUS_COMPLETE

◆ DECODER_STATUS_FAILED

constexpr AnimationDecoderStatus SDL::DECODER_STATUS_FAILED

constexpr

Initial value:

=

IMG_DECODER_STATUS_FAILED

◆ DECODER_STATUS_INVALID

constexpr AnimationDecoderStatus SDL::DECODER_STATUS_INVALID

constexpr

Initial value:

=

IMG_DECODER_STATUS_INVALID

◆ DECODER_STATUS_OK

constexpr AnimationDecoderStatus SDL::DECODER_STATUS_OK

constexpr

Initial value:

=

IMG_DECODER_STATUS_OK

Classes

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ SDL_IMAGE_VERSION

◆ SDL_IMAGE_VERSION_ATLEAST

Typedef Documentation

◆ AnimationDecoderStatus

Function Documentation

◆ AddAnimationEncoderFrame()

◆ AddFrame()

◆ Close() [1/2]

◆ Close() [2/2]

◆ CloseAnimationDecoder()

◆ CloseAnimationEncoder()

◆ CreateAnimatedCursor()

◆ CreateAnimationDecoder() [1/2]

◆ CreateAnimationDecoder() [2/2]

◆ CreateAnimationDecoderWithProperties()

◆ CreateAnimationEncoder() [1/2]

◆ CreateAnimationEncoder() [2/2]

◆ CreateAnimationEncoderWithProperties()

◆ CreateCursor()

◆ Free()

◆ FreeAnimation()

◆ GetAnimationDecoderFrame()

◆ GetAnimationDecoderProperties()

◆ GetAnimationDecoderStatus()

◆ GetAnimationDelay()

◆ GetAnimationFrame()

◆ GetClipboardImage()

◆ GetDelay()

◆ GetFrame() [1/2]

◆ GetFrame() [2/2]

◆ GetProperties()

◆ GetStatus()

◆ isANI()

◆ isAVIF()

◆ isBMP()

◆ isCUR()

◆ isGIF()

◆ isICO()

◆ isJPG()

◆ isJXL()

◆ isLBM()

◆ isPCX()

◆ isPNG()

◆ isPNM()

◆ isQOI()

◆ isSVG()

◆ isTIF()

◆ isWEBP()

◆ isXCF()

◆ isXPM()

◆ isXV()

◆ LoadANIAnimation()

◆ LoadAnimation() [1/2]

◆ LoadAnimation() [2/2]

◆ LoadAnimationTyped()

◆ LoadAPNGAnimation()

◆ LoadAVIF()

◆ LoadAVIFAnimation()

◆ LoadBMP()

◆ LoadCUR()

◆ LoadGIF()

◆ LoadGIFAnimation()

◆ LoadGPUTexture() [1/2]

◆ LoadGPUTexture() [2/2]

◆ LoadGPUTextureTyped()

◆ LoadICO()

◆ LoadJPG()

◆ LoadJXL()

◆ LoadLBM()

◆ LoadPCX()

◆ LoadPNG()

◆ LoadPNM()

◆ LoadQOI()