Header file for SDL_image library. More...

Namespaces
namespace	SDL::prop
	Constants for Properties keys.
namespace	SDL::prop::AnimationEncoder
	Supported properties for creating an animation encoder.
namespace	SDL::prop::AnimationDecoder
	Supported properties for creating an animation decoder.
namespace	SDL::prop::Metadata
	Animation metadata properties.

Classes
struct	SDL::Animation
	Animated image support. More...
struct	SDL::AnimationEncoder
	An object representing the encoder context. More...
struct	SDL::AnimationDecoder
	An object representing animation decoder. More...

Macros
#define	SDL_IMAGE_VERSION
	This is the version number macro for the current SDL_image version.
#define	SDL_IMAGE_VERSION_ATLEAST(X, Y, Z)
	This macro will evaluate to true if compiled with SDL_image at least X.Y.Z.

Typedefs
using	SDL::AnimationRaw = IMG_Animation*
	Alias to raw representation for Animation.
using	SDL::AnimationRawConst = const IMG_Animation*
	Alias to const raw representation for Animation.
using	SDL::AnimationRef = ResourceRef<Animation>
	Reference for Animation.
using	SDL::AnimationConstRef = ResourceConstRef<AnimationRaw, AnimationRawConst>
	Safely wrap Animation for non owning const parameters.
using	SDL::AnimationEncoderRaw = IMG_AnimationEncoder*
	Alias to raw representation for AnimationEncoder.
using	SDL::AnimationEncoderRef = ResourceRef<AnimationEncoder>
	Reference for AnimationEncoder.
using	SDL::AnimationDecoderRaw = IMG_AnimationDecoder*
	Alias to raw representation for AnimationDecoder.
using	SDL::AnimationDecoderRef = ResourceRef<AnimationDecoder>
	Reference for AnimationDecoder.
using	SDL::AnimationDecoderStatus = IMG_AnimationDecoderStatus
	An enum representing the status of an animation decoder.

Functions
Surface	SDL::LoadSurface (StringParam file)
	Load an image from a filesystem path into a software surface.
Surface	SDL::LoadSurface_IO (IOStreamRef src, bool closeio=false)
	Load an image from an SDL data source into a software surface.
Surface	SDL::LoadSurfaceTyped_IO (IOStreamRef src, StringParam type, bool closeio=false)
	Load an image from an SDL data source into a software surface.
Texture	SDL::LoadTexture (RendererRef renderer, StringParam file)
	Load an image from a filesystem path into a texture.
Texture	SDL::LoadTexture_IO (RendererRef renderer, IOStreamRef src, bool closeio=false)
	Load an image from an SDL data source into a texture.
Texture	SDL::LoadTextureTyped_IO (RendererRef renderer, IOStreamRef src, StringParam type, bool closeio=false)
	Load an image from an SDL data source into a texture.
GPUTexture	SDL::LoadGPUTexture (GPUDeviceRef device, GPUCopyPass copy_pass, StringParam file, int width=nullptr, int height=nullptr)
	Load an image from a filesystem path into a GPU texture.
Surface	SDL::GetClipboardImage ()
	Load an image from an SDL data source into a GPU texture.
bool	SDL::isANI (IOStreamRef src)
	Detect ANI animated cursor data on a readable/seekable IOStream.
bool	SDL::isAVIF (IOStreamRef src)
	Detect AVIF image data on a readable/seekable IOStream.
bool	SDL::isCUR (IOStreamRef src)
	Detect CUR image data on a readable/seekable IOStream.
bool	SDL::isBMP (IOStreamRef src)
	Detect BMP image data on a readable/seekable IOStream.
bool	SDL::isGIF (IOStreamRef src)
	Detect GIF image data on a readable/seekable IOStream.
bool	SDL::isICO (IOStreamRef src)
	Detect ICO image data on a readable/seekable IOStream.
bool	SDL::isJPG (IOStreamRef src)
	Detect JPG image data on a readable/seekable IOStream.
bool	SDL::isJXL (IOStreamRef src)
	Detect JXL image data on a readable/seekable IOStream.
bool	SDL::isLBM (IOStreamRef src)
	Detect LBM image data on a readable/seekable IOStream.
bool	SDL::isPCX (IOStreamRef src)
	Detect PCX image data on a readable/seekable IOStream.
bool	SDL::isPNG (IOStreamRef src)
	Detect PNG image data on a readable/seekable IOStream.
bool	SDL::isPNM (IOStreamRef src)
	Detect PNM image data on a readable/seekable IOStream.
bool	SDL::isQOI (IOStreamRef src)
	Detect QOI image data on a readable/seekable IOStream.
bool	SDL::isSVG (IOStreamRef src)
	Detect SVG image data on a readable/seekable IOStream.
bool	SDL::isTIF (IOStreamRef src)
	Detect TIFF image data on a readable/seekable IOStream.
bool	SDL::isWEBP (IOStreamRef src)
	Detect WEBP image data on a readable/seekable IOStream.
bool	SDL::isXCF (IOStreamRef src)
	Detect XCF image data on a readable/seekable IOStream.
bool	SDL::isXPM (IOStreamRef src)
	Detect XPM image data on a readable/seekable IOStream.
bool	SDL::isXV (IOStreamRef src)
	Detect XV image data on a readable/seekable IOStream.
Surface	SDL::LoadAVIF_IO (IOStreamRef src)
	Load a AVIF image directly.
Surface	SDL::LoadCUR_IO (IOStreamRef src)
	Load a CUR image directly.
Surface	SDL::LoadGIF_IO (IOStreamRef src)
	Load a GIF image directly.
Surface	SDL::LoadICO_IO (IOStreamRef src)
	Load a ICO image directly.
Surface	SDL::LoadJPG_IO (IOStreamRef src)
	Load a JPG image directly.
Surface	SDL::LoadJXL_IO (IOStreamRef src)
	Load a JXL image directly.
Surface	SDL::LoadLBM_IO (IOStreamRef src)
	Load a LBM image directly.
Surface	SDL::LoadPCX_IO (IOStreamRef src)
	Load a PCX image directly.
Surface	SDL::LoadPNG_IO (IOStreamRef src)
	Load a PNG image directly.
Surface	SDL::LoadPNG_IO (IOStreamRef src, bool closeio)
	Load a PNG image directly.
Surface	SDL::LoadPNG (StringParam file)
	Load a PNG image from a file.
Surface	SDL::LoadPNM_IO (IOStreamRef src)
	Load a PNM image directly.
Surface	SDL::LoadSVG_IO (IOStreamRef src)
	Load a SVG image directly.
Surface	SDL::LoadSizedSVG_IO (IOStreamRef src, const PointRaw &size)
	Load an SVG image, scaled to a specific size.
Surface	SDL::LoadQOI_IO (IOStreamRef src)
	Load a QOI image directly.
Surface	SDL::LoadTGA_IO (IOStreamRef src)
	Load a TGA image directly.
Surface	SDL::LoadTIF_IO (IOStreamRef src)
	Load a TIFF image directly.
Surface	SDL::LoadWEBP_IO (IOStreamRef src)
	Load a WEBP image directly.
Surface	SDL::LoadXCF_IO (IOStreamRef src)
	Load a XCF image directly.
Surface	SDL::LoadXPM_IO (IOStreamRef src)
	Load a XPM image directly.
Surface	SDL::LoadXV_IO (IOStreamRef src)
	Load a XV image directly.
Surface	SDL::ReadXPMFromArray (char **xpm)
	Load an XPM image from a memory array.
Surface	SDL::ReadXPMFromArrayToRGB888 (char **xpm)
	Load an XPM image from a memory array.
void	SDL::Save (SurfaceConstRef surface, StringParam file)
	Save an Surface into an image file.
void	SDL::SaveTyped_IO (SurfaceConstRef surface, IOStreamRef dst, StringParam type, bool closeio=false)
	Save an Surface into formatted image data, via an IOStream.
void	SDL::SaveAVIF (SurfaceRef surface, StringParam file, int quality)
	Save an Surface into a AVIF image file.
void	SDL::SaveAVIF_IO (SurfaceRef surface, IOStreamRef dst, int quality, bool closeio=false)
	Save an Surface into AVIF image data, via an IOStream.
void	SDL::SaveCUR (SurfaceRef surface, StringParam file)
	Save an Surface into a CUR image file.
void	SDL::SaveCUR_IO (SurfaceRef surface, IOStreamRef dst, bool closeio=false)
	Save an Surface into CUR image data, via an IOStream.
void	SDL::SaveGIF (SurfaceRef surface, StringParam file)
	Save an Surface into a GIF image file.
void	SDL::SaveGIF_IO (SurfaceRef surface, IOStreamRef dst, bool closeio=false)
	Save an Surface into GIF image data, via an IOStream.
void	SDL::SaveICO (SurfaceRef surface, StringParam file)
	Save an Surface into a ICO image file.
void	SDL::SaveICO_IO (SurfaceRef surface, IOStreamRef dst, bool closeio=false)
	Save an Surface into ICO image data, via an IOStream.
void	SDL::SaveJPG (SurfaceRef surface, StringParam file, int quality)
	Save an Surface into a JPEG image file.
void	SDL::SaveJPG_IO (SurfaceRef surface, IOStreamRef dst, int quality, bool closeio=false)
	Save an Surface into JPEG image data, via an IOStream.
void	SDL::SavePNG (SurfaceRef surface, StringParam file)
	Save an Surface into a PNG image file.
void	SDL::SavePNG_IO (SurfaceRef surface, IOStreamRef dst, bool closeio=false)
	Save an Surface into PNG image data, via an IOStream.
void	SDL::SaveTGA (SurfaceRef surface, StringParam file)
	Save an Surface into a TGA image file.
void	SDL::SaveTGA_IO (SurfaceRef surface, IOStreamRef dst, bool closeio=false)
	Save an Surface into TGA image data, via an IOStream.
void	SDL::SaveWEBP (SurfaceRef surface, StringParam file, float quality)
	Save an Surface into a WEBP image file.
void	SDL::SaveWEBP_IO (SurfaceRef surface, IOStreamRef dst, float quality, bool closeio=false)
	Save an Surface into WEBP image data, via an IOStream.
int	SDL::GetAnimationWidth (AnimationConstRef anim)
	Get the width in pixels.
int	SDL::GetAnimationHeight (AnimationConstRef anim)
	Get the height in pixels.
Point	SDL::GetAnimationSize (AnimationConstRef anim)
	Get the size in pixels.
int	SDL::GetAnimationCount (AnimationConstRef anim)
	Return the number of frames.
Surface	SDL::GetAnimationFrame (AnimationConstRef anim, int index)
	Return the frame image under given index.
int	SDL::GetAnimationDelay (AnimationConstRef anim, int index)
	Return the frame delay under given index.
Animation	SDL::LoadAnimation (StringParam file)
	Load an animation from a file.
Animation	SDL::LoadAnimation_IO (IOStreamRef src, bool closeio=false)
	Load an animation from an IOStream.
Animation	SDL::LoadAnimationTyped_IO (IOStreamRef src, StringParam type, bool closeio=false)
	Load an animation from an IOStream.
Animation	SDL::LoadANIAnimation_IO (IOStreamRef src)
	Load an ANI animation directly from an IOStream.
Animation	SDL::LoadAPNGAnimation_IO (IOStreamRef src)
	Load an APNG animation directly from an IOStream.
Animation	SDL::LoadAVIFAnimation_IO (IOStreamRef src)
	Load an AVIF animation directly from an IOStream.
Animation	SDL::LoadGIFAnimation_IO (IOStreamRef src)
	Load a GIF animation directly.
Animation	SDL::LoadWEBPAnimation_IO (IOStreamRef src)
	Load a WEBP animation directly.
void	SDL::SaveAnimation (AnimationRef anim, StringParam file)
	Save an animation to a file.
void	SDL::SaveAnimationTyped_IO (AnimationRef anim, IOStreamRef dst, StringParam type, bool closeio=false)
	Save an animation to an IOStream.
void	SDL::SaveANIAnimation_IO (AnimationRef anim, IOStreamRef dst, bool closeio=false)
	Save an animation in ANI format to an IOStream.
void	SDL::SaveAPNGAnimation_IO (AnimationRef anim, IOStreamRef dst, bool closeio=false)
	Save an animation in APNG format to an IOStream.
void	SDL::SaveAVIFAnimation_IO (AnimationRef anim, IOStreamRef dst, int quality, bool closeio=false)
	Save an animation in AVIF format to an IOStream.
void	SDL::SaveGIFAnimation_IO (AnimationRef anim, IOStreamRef dst, bool closeio=false)
	Save an animation in GIF format to an IOStream.
void	SDL::SaveWEBPAnimation_IO (AnimationRef anim, IOStreamRef dst, int quality, bool closeio=false)
	Save an animation in WEBP format to an IOStream.
Cursor	SDL::CreateAnimatedCursor (AnimationRef anim, const PointRaw &hotspot)
	Create an animated cursor from an animation.
void	SDL::FreeAnimation (AnimationRaw anim)
	Dispose of an Animation and free its resources.
AnimationEncoder	SDL::CreateAnimationEncoder (StringParam file)
	Create an encoder to save a series of images to a file.
AnimationEncoder	SDL::CreateAnimationEncoder_IO (IOStreamRef dst, StringParam type, bool closeio=false)
	Create an encoder to save a series of images to an IOStream.
AnimationEncoder	SDL::CreateAnimationEncoderWithProperties (PropertiesRef props)
	Create an animation encoder with the specified properties.
void	SDL::AddAnimationEncoderFrame (AnimationEncoderRef encoder, SurfaceRef surface, Uint64 duration)
	Add a frame to an animation encoder.
void	SDL::CloseAnimationEncoder (AnimationEncoderRaw encoder)
	Close an animation encoder, finishing any encoding.
AnimationDecoder	SDL::CreateAnimationDecoder (StringParam file)
	Create a decoder to read a series of images from a file.
AnimationDecoder	SDL::CreateAnimationDecoder_IO (IOStreamRef src, StringParam type, bool closeio=false)
	Create a decoder to read a series of images from an IOStream.
AnimationDecoder	SDL::CreateAnimationDecoderWithProperties (PropertiesRef props)
	Create an animation decoder with the specified properties.
PropertiesRef	SDL::GetAnimationDecoderProperties (AnimationDecoderRef decoder)
	Get the properties of an animation decoder.
Surface	SDL::GetAnimationDecoderFrame (AnimationDecoderRef decoder, Uint64 *duration)
	Get the next frame in an animation decoder.
AnimationDecoderStatus	SDL::GetAnimationDecoderStatus (AnimationDecoderRef decoder)
	Get the decoder status indicating the current state of the decoder.
void	SDL::ResetAnimationDecoder (AnimationDecoderRef decoder)
	Reset an animation decoder.
void	SDL::CloseAnimationDecoder (AnimationDecoderRaw decoder)
	Close an animation decoder, finishing any decoding.
	SDL::Surface::Surface (StringParam file)
	Load an image from a filesystem path into a software surface.
	SDL::Surface::Surface (IOStreamRef src, bool closeio=false)
	Load an image from an SDL data source into a software surface.
	SDL::Texture::Texture (RendererRef renderer, StringParam file)
	Load an image from a filesystem path into a texture.
	SDL::Texture::Texture (RendererRef renderer, IOStreamRef src, bool closeio=false)
	Load an image from an SDL data source into a texture.
void	SDL::Surface::Save (StringParam filename) const
	Save an Surface into an image file.
void	SDL::Surface::SaveTyped_IO (IOStreamRef dst, StringParam type, bool closeio=false) const
	Save an Surface into formatted image data, via an IOStream.
void	SDL::Surface::SavePNG (StringParam file) const
	Save a surface to a file in PNG format.
void	SDL::Surface::SavePNG_IO (IOStreamRef dst, bool closeio=false) const
	Save a surface to a seekable SDL data stream in PNG format.
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.
int	SDL::Animation::GetDelay (int index) const
	Return the frame delay under given index.
	SDL::Animation::Animation (StringParam file)
	Load an animation from a file.
	SDL::Animation::Animation (IOStreamRef src, bool closeio=false)
	Load an animation from an IOStream.
void	SDL::Animation::Save (StringParam file)
	Save an animation to a file.
void	SDL::Animation::SaveTyped_IO (IOStreamRef dst, StringParam type, bool closeio=false)
	Save an animation to an IOStream.
void	SDL::Animation::SaveANI_IO (IOStreamRef dst, bool closeio=false)
	Save an animation in ANI format to an IOStream.
void	SDL::Animation::SaveAPNG_IO (IOStreamRef dst, bool closeio=false)
	Save an animation in APNG format to an IOStream.
void	SDL::Animation::SaveAVIF_IO (IOStreamRef dst, int quality, bool closeio=false)
	Save an animation in AVIF format to an IOStream.
void	SDL::Animation::SaveGIF_IO (IOStreamRef dst, bool closeio=false)
	Save an animation in GIF format to an IOStream.
void	SDL::Animation::SaveWEBP_IO (IOStreamRef dst, int quality, bool closeio=false)
	Save an animation in WEBP format to an IOStream.
Cursor	SDL::Animation::CreateCursor (const PointRaw &hotspot)
	Create an animated cursor from an animation.
void	SDL::Animation::Free ()
	Dispose of an Animation and free its resources.
	SDL::AnimationEncoder::AnimationEncoder (StringParam file)
	Create an encoder to save a series of images to a file.
	SDL::AnimationEncoder::AnimationEncoder (IOStreamRef dst, StringParam type, bool closeio=false)
	Create an encoder to save a series of images to an IOStream.
	SDL::AnimationEncoder::AnimationEncoder (PropertiesRef props)
	Create an animation encoder with the specified properties.
void	SDL::AnimationEncoder::AddFrame (SurfaceRef surface, Uint64 duration)
	Add a frame to an animation encoder.
void	SDL::AnimationEncoder::Close ()
	Close an animation encoder, finishing any encoding.
	SDL::AnimationDecoder::AnimationDecoder (StringParam file)
	Create a decoder to read a series of images from a file.
	SDL::AnimationDecoder::AnimationDecoder (IOStreamRef src, StringParam type, bool closeio=false)
	Create a decoder to read a series of images from an IOStream.
	SDL::AnimationDecoder::AnimationDecoder (PropertiesRef props)
	Create an animation decoder with the specified properties.
PropertiesRef	SDL::AnimationDecoder::GetProperties ()
	Get the properties of an animation decoder.
Surface	SDL::AnimationDecoder::GetFrame (Uint64 *duration)
	Get the next frame in an animation decoder.
AnimationDecoderStatus	SDL::AnimationDecoder::GetStatus ()
	Get the decoder status indicating the current state of the decoder.
void	SDL::AnimationDecoder::Reset ()
	Reset an animation decoder.
void	SDL::AnimationDecoder::Close ()
	Close an animation decoder, finishing any decoding.

Variables
constexpr AnimationDecoderStatus	SDL::DECODER_STATUS_INVALID
	The decoder is invalid.
constexpr AnimationDecoderStatus	SDL::DECODER_STATUS_OK
	The decoder is ready to decode the next frame.
constexpr AnimationDecoderStatus	SDL::DECODER_STATUS_FAILED
	The decoder failed to decode a frame, call GetError() for more information.
constexpr AnimationDecoderStatus	SDL::DECODER_STATUS_COMPLETE
	No more frames available.

Detailed Description

Header file for SDL_image library.

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

This is the version number macro for the current SDL_image version.

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

This macro will evaluate to true if compiled with SDL_image at least X.Y.Z.

Typedef Documentation

◆ AnimationDecoderRef

using SDL::AnimationDecoderRef = ResourceRef<AnimationDecoder>

Reference for AnimationDecoder.

This does not take ownership!

◆ AnimationDecoderStatus

using SDL::AnimationDecoderStatus = IMG_AnimationDecoderStatus

An enum representing the status of an animation decoder.

Since: This enum is available since SDL_image 3.4.0.

◆ AnimationEncoderRef

using SDL::AnimationEncoderRef = ResourceRef<AnimationEncoder>

Reference for AnimationEncoder.

This does not take ownership!

◆ AnimationRef

using SDL::AnimationRef = ResourceRef<Animation>

Reference for Animation.

This does not take ownership!

Function Documentation

◆ AddAnimationEncoderFrame()

void SDL::AddAnimationEncoderFrame	(	AnimationEncoderRef	encoder,
		SurfaceRef	surface,
		Uint64	duration )

inline

Add a frame to an animation encoder.

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: CreateAnimationEncoder; CreateAnimationEncoder_IO; CreateAnimationEncoderWithProperties; AnimationEncoder.Close

◆ AddFrame()

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

inline

Add a frame to an animation encoder.

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: CreateAnimationEncoder; CreateAnimationEncoder_IO; CreateAnimationEncoderWithProperties; AnimationEncoder.Close

◆ Animation() [1/2]

SDL::Animation::Animation	(	IOStreamRef	src,
		bool	closeio = false )

inline

Load an animation from an IOStream.

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.

Postcondition: a new Animation, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: Animation.CreateCursor; LoadAnimation; LoadAnimationTyped_IO; LoadANIAnimation_IO; LoadAPNGAnimation_IO; LoadAVIFAnimation_IO; LoadGIFAnimation_IO; LoadWEBPAnimation_IO; Animation.Free

◆ Animation() [2/2]

SDL::Animation::Animation ( StringParam file )

inline

Load an animation from a file.

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.

Postcondition: a new Animation, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: Animation.CreateCursor; LoadAnimation_IO; LoadAnimationTyped_IO; LoadANIAnimation_IO; LoadAPNGAnimation_IO; LoadAVIFAnimation_IO; LoadGIFAnimation_IO; LoadWEBPAnimation_IO; Animation.Free

◆ AnimationDecoder() [1/3]

SDL::AnimationDecoder::AnimationDecoder	(	IOStreamRef	src,
		StringParam	type,
		bool	closeio = false )

inline

Create a decoder to read a series of images from an IOStream.

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

Postcondition: a new AnimationDecoder on success.

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.4.0.

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

◆ AnimationDecoder() [2/3]

SDL::AnimationDecoder::AnimationDecoder ( PropertiesRef props )

inline

Create an animation decoder with the specified properties.

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.

Postcondition: a new AnimationDecoder on success.

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.4.0.

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

◆ AnimationDecoder() [3/3]

SDL::AnimationDecoder::AnimationDecoder ( StringParam file )

inline

Create a decoder to read a series of images from a file.

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.

Postcondition: a new AnimationDecoder on success.

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.4.0.

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

◆ AnimationEncoder() [1/3]

SDL::AnimationEncoder::AnimationEncoder	(	IOStreamRef	dst,
		StringParam	type,
		bool	closeio = false )

inline

Create an encoder to save a series of images to an IOStream.

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.

Postcondition: a new AnimationEncoder on success.

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.4.0.

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

◆ AnimationEncoder() [2/3]

SDL::AnimationEncoder::AnimationEncoder ( PropertiesRef props )

inline

Create an animation encoder with the specified properties.

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.

Postcondition: a new AnimationEncoder on success.

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.4.0.

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

◆ AnimationEncoder() [3/3]

SDL::AnimationEncoder::AnimationEncoder ( StringParam file )

inline

Create an encoder to save a series of images to a file.

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.

Postcondition: a new AnimationEncoder on success.

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.4.0.

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

◆ Close() [1/2]

void SDL::AnimationDecoder::Close ( )

inline

Close an animation decoder, finishing any decoding.

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: CreateAnimationDecoder; CreateAnimationDecoder_IO; CreateAnimationDecoderWithProperties

◆ Close() [2/2]

void SDL::AnimationEncoder::Close ( )

inline

Close an animation encoder, finishing any encoding.

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: CreateAnimationEncoder; CreateAnimationEncoder_IO; CreateAnimationEncoderWithProperties

◆ CloseAnimationDecoder()

void SDL::CloseAnimationDecoder ( AnimationDecoderRaw decoder )

inline

Close an animation decoder, finishing any decoding.

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: CreateAnimationDecoder; CreateAnimationDecoder_IO; CreateAnimationDecoderWithProperties

◆ CloseAnimationEncoder()

void SDL::CloseAnimationEncoder ( AnimationEncoderRaw encoder )

inline

Close an animation encoder, finishing any encoding.

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: CreateAnimationEncoder; CreateAnimationEncoder_IO; CreateAnimationEncoderWithProperties

◆ CreateAnimatedCursor()

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

inline

Create an animated cursor from an animation.

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: LoadAnimation; LoadAnimation_IO; LoadAnimationTyped_IO

◆ CreateAnimationDecoder()

AnimationDecoder SDL::CreateAnimationDecoder ( StringParam file )

inline

Create a decoder to read a series of images from a file.

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

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.4.0.

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

◆ CreateAnimationDecoder_IO()

AnimationDecoder SDL::CreateAnimationDecoder_IO	(	IOStreamRef	src,
		StringParam	type,
		bool	closeio = false )

inline

Create a decoder to read a series of images from an IOStream.

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

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.4.0.

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

◆ CreateAnimationDecoderWithProperties()

AnimationDecoder SDL::CreateAnimationDecoderWithProperties ( PropertiesRef props )

inline

Create an animation decoder with the specified properties.

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

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.4.0.

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

◆ CreateAnimationEncoder()

AnimationEncoder SDL::CreateAnimationEncoder ( StringParam file )

inline

Create an encoder to save a series of images to a file.

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

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.4.0.

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

◆ CreateAnimationEncoder_IO()

AnimationEncoder SDL::CreateAnimationEncoder_IO	(	IOStreamRef	dst,
		StringParam	type,
		bool	closeio = false )

inline

Create an encoder to save a series of images to an IOStream.

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

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.4.0.

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

◆ CreateAnimationEncoderWithProperties()

AnimationEncoder SDL::CreateAnimationEncoderWithProperties ( PropertiesRef props )

inline

Create an animation encoder with the specified properties.

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

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.4.0.

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

◆ CreateCursor()

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

inline

Create an animated cursor from an animation.

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: LoadAnimation; LoadAnimation_IO; LoadAnimationTyped_IO

◆ Free()

void SDL::Animation::Free ( )

inline

Dispose of an Animation and free its resources.

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

Since: This function is available since SDL_image 3.0.0.

See also: LoadAnimation; LoadAnimation_IO; LoadAnimationTyped_IO; LoadANIAnimation_IO; LoadAPNGAnimation_IO; LoadAVIFAnimation_IO; LoadGIFAnimation_IO; LoadWEBPAnimation_IO

◆ FreeAnimation()

void SDL::FreeAnimation ( AnimationRaw anim )

inline

Dispose of an Animation and free its resources.

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: LoadAnimation; LoadAnimation_IO; LoadAnimationTyped_IO; LoadANIAnimation_IO; LoadAPNGAnimation_IO; LoadAVIFAnimation_IO; LoadGIFAnimation_IO; LoadWEBPAnimation_IO

◆ GetAnimationDecoderFrame()

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

inline

Get the next frame in an animation decoder.

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: CreateAnimationDecoder; CreateAnimationDecoder_IO; CreateAnimationDecoderWithProperties; AnimationDecoder.GetStatus; AnimationDecoder.Reset; AnimationDecoder.Close

◆ GetAnimationDecoderProperties()

PropertiesRef SDL::GetAnimationDecoderProperties ( AnimationDecoderRef decoder )

inline

Get the properties of an animation decoder.

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: CreateAnimationDecoder; CreateAnimationDecoder_IO; CreateAnimationDecoderWithProperties

◆ GetAnimationDecoderStatus()

AnimationDecoderStatus SDL::GetAnimationDecoderStatus ( AnimationDecoderRef decoder )

inline

Get the decoder status indicating the current state of the decoder.

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	(	AnimationConstRef	anim,
		int	index )

inline

Return the frame delay under given index.

Parameters

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

◆ GetAnimationFrame()

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

inline

Return the frame image under given index.

Parameters

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

◆ GetClipboardImage()

Surface SDL::GetClipboardImage ( )

inline

Load an image from an SDL data source into a GPU texture.

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_IO(), 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_IO */ inline GPUTexture LoadGPUTexture_IO(GPUDeviceRef device, GPUCopyPass copy_pass, IOStreamRef src, bool closeio = false, int* width = nullptr, int* height = nullptr) { return IMG_LoadGPUTexture_IO(device, copy_pass, src, closeio, width, height); }

/** Load an image from an SDL data source into a GPU texture.

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_IO(), 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_IO */ inline GPUTexture LoadGPUTextureTyped_IO(GPUDeviceRef device, GPUCopyPass copy_pass, IOStreamRef src, StringParam type, bool closeio = false, int* width = nullptr, int* height = nullptr) { return IMG_LoadGPUTextureTyped_IO( device, copy_pass, src, closeio, type, width, height); }

/** Get the image currently in the clipboard.

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

Return the frame delay under given index.

Parameters

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

◆ GetFrame() [1/2]

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

inline

Return the frame image under given index.

Parameters

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

◆ GetFrame() [2/2]

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

inline

Get the next frame in an animation decoder.

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: CreateAnimationDecoder; CreateAnimationDecoder_IO; CreateAnimationDecoderWithProperties; AnimationDecoder.GetStatus; AnimationDecoder.Reset; AnimationDecoder.Close

◆ GetProperties()

PropertiesRef SDL::AnimationDecoder::GetProperties ( )

inline

Get the properties of an animation decoder.

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: CreateAnimationDecoder; CreateAnimationDecoder_IO; CreateAnimationDecoderWithProperties

◆ GetStatus()

AnimationDecoderStatus SDL::AnimationDecoder::GetStatus ( )

inline

Get the decoder status indicating the current state of the decoder.

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

inline

Detect ANI animated cursor data on a readable/seekable IOStream.

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

inline

Detect AVIF image data on a readable/seekable IOStream.

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

inline

Detect BMP image data on a readable/seekable IOStream.

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

inline

Detect CUR image data on a readable/seekable IOStream.

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

inline

Detect GIF image data on a readable/seekable IOStream.

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

inline

Detect ICO image data on a readable/seekable IOStream.

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

inline

Detect JPG image data on a readable/seekable IOStream.

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

inline

Detect JXL image data on a readable/seekable IOStream.

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

inline

Detect LBM image data on a readable/seekable IOStream.

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

inline

Detect PCX image data on a readable/seekable IOStream.

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

inline

Detect PNG image data on a readable/seekable IOStream.

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

inline

Detect PNM image data on a readable/seekable IOStream.

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

inline

Detect QOI image data on a readable/seekable IOStream.

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

inline

Detect SVG image data on a readable/seekable IOStream.

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

inline

Detect TIFF image data on a readable/seekable IOStream.

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

inline

Detect WEBP image data on a readable/seekable IOStream.

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

inline

Detect XCF image data on a readable/seekable IOStream.

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

inline

Detect XPM image data on a readable/seekable IOStream.

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

inline

Detect XV image data on a readable/seekable IOStream.

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

Animation SDL::LoadANIAnimation_IO ( IOStreamRef src )

inline

Load an ANI animation directly from an IOStream.

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; LoadAnimation; LoadAnimation_IO; LoadAnimationTyped_IO; LoadAPNGAnimation_IO; LoadAVIFAnimation_IO; LoadGIFAnimation_IO; LoadWEBPAnimation_IO; Animation.Free

◆ LoadAnimation()

Animation SDL::LoadAnimation ( StringParam file )

inline

Load an animation from a file.

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; LoadAnimation_IO; LoadAnimationTyped_IO; LoadANIAnimation_IO; LoadAPNGAnimation_IO; LoadAVIFAnimation_IO; LoadGIFAnimation_IO; LoadWEBPAnimation_IO; Animation.Free

◆ LoadAnimation_IO()

Animation SDL::LoadAnimation_IO	(	IOStreamRef	src,
		bool	closeio = false )

inline

Load an animation from an IOStream.

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; LoadAnimation; LoadAnimationTyped_IO; LoadANIAnimation_IO; LoadAPNGAnimation_IO; LoadAVIFAnimation_IO; LoadGIFAnimation_IO; LoadWEBPAnimation_IO; Animation.Free

◆ LoadAnimationTyped_IO()

Animation SDL::LoadAnimationTyped_IO	(	IOStreamRef	src,
		StringParam	type,
		bool	closeio = false )

inline

Load an animation from an IOStream.

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; LoadAnimation; LoadAnimation_IO; LoadANIAnimation_IO; LoadAPNGAnimation_IO; LoadAVIFAnimation_IO; LoadGIFAnimation_IO; LoadWEBPAnimation_IO; Animation.Free

◆ LoadAPNGAnimation_IO()

Animation SDL::LoadAPNGAnimation_IO ( IOStreamRef src )

inline

Load an APNG animation directly from an IOStream.

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; LoadAnimation; LoadAnimation_IO; LoadAnimationTyped_IO; LoadANIAnimation_IO; LoadAVIFAnimation_IO; LoadGIFAnimation_IO; LoadWEBPAnimation_IO; Animation.Free

◆ LoadAVIF_IO()

Surface SDL::LoadAVIF_IO ( IOStreamRef src )

inline

Load a AVIF image directly.

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_IO; LoadCUR_IO; LoadGIF_IO; LoadICO_IO; LoadJPG_IO; LoadJXL_IO; LoadLBM_IO; LoadPCX_IO; LoadPNG_IO; LoadPNM_IO; LoadQOI_IO; LoadSVG_IO; LoadTGA_IO; LoadTIF_IO; LoadWEBP_IO; LoadXCF_IO; LoadXPM_IO; LoadXV_IO

◆ LoadAVIFAnimation_IO()

Animation SDL::LoadAVIFAnimation_IO ( IOStreamRef src )

inline

Load an AVIF animation directly from an IOStream.

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; LoadAnimation; LoadAnimation_IO; LoadAnimationTyped_IO; LoadANIAnimation_IO; LoadAPNGAnimation_IO; LoadGIFAnimation_IO; LoadWEBPAnimation_IO; Animation.Free

◆ LoadCUR_IO()

Surface SDL::LoadCUR_IO ( IOStreamRef src )

inline

Load a CUR image directly.

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_IO; LoadBMP_IO; LoadGIF_IO; LoadICO_IO; LoadJPG_IO; LoadJXL_IO; LoadLBM_IO; LoadPCX_IO; LoadPNG_IO; LoadPNM_IO; LoadQOI_IO; LoadSVG_IO; LoadTGA_IO; LoadTIF_IO; LoadWEBP_IO; LoadXCF_IO; LoadXPM_IO; LoadXV_IO

◆ LoadGIF_IO()

Surface SDL::LoadGIF_IO ( IOStreamRef src )

inline

Load a GIF image directly.

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_IO; LoadBMP_IO; LoadCUR_IO; LoadICO_IO; LoadJPG_IO; LoadJXL_IO; LoadLBM_IO; LoadPCX_IO; LoadPNG_IO; LoadPNM_IO; LoadQOI_IO; LoadSVG_IO; LoadTGA_IO; LoadTIF_IO; LoadWEBP_IO; LoadXCF_IO; LoadXPM_IO; LoadXV_IO

◆ LoadGIFAnimation_IO()

Animation SDL::LoadGIFAnimation_IO ( IOStreamRef src )

inline

Load a GIF animation directly.

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; LoadAnimation; LoadAnimation_IO; LoadAnimationTyped_IO; LoadANIAnimation_IO; LoadAPNGAnimation_IO; LoadAVIFAnimation_IO; LoadWEBPAnimation_IO; Animation.Free

◆ LoadGPUTexture()

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

inline

Load an image from a filesystem path into a GPU texture.

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

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_IO; LoadGPUTexture_IO

◆ LoadICO_IO()

Surface SDL::LoadICO_IO ( IOStreamRef src )

inline

Load a ICO image directly.

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_IO; LoadBMP_IO; LoadCUR_IO; LoadGIF_IO; LoadJPG_IO; LoadJXL_IO; LoadLBM_IO; LoadPCX_IO; LoadPNG_IO; LoadPNM_IO; LoadQOI_IO; LoadSVG_IO; LoadTGA_IO; LoadTIF_IO; LoadWEBP_IO; LoadXCF_IO; LoadXPM_IO; LoadXV_IO

◆ LoadJPG_IO()

Surface SDL::LoadJPG_IO ( IOStreamRef src )

inline

Load a JPG image directly.

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_IO; LoadBMP_IO; LoadCUR_IO; LoadGIF_IO; LoadICO_IO; LoadJXL_IO; LoadLBM_IO; LoadPCX_IO; LoadPNG_IO; LoadPNM_IO; LoadQOI_IO; LoadSVG_IO; LoadTGA_IO; LoadTIF_IO; LoadWEBP_IO; LoadXCF_IO; LoadXPM_IO; LoadXV_IO

◆ LoadJXL_IO()

Surface SDL::LoadJXL_IO ( IOStreamRef src )

inline

Load a JXL image directly.

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_IO; LoadBMP_IO; LoadCUR_IO; LoadGIF_IO; LoadICO_IO; LoadJPG_IO; LoadLBM_IO; LoadPCX_IO; LoadPNG_IO; LoadPNM_IO; LoadQOI_IO; LoadSVG_IO; LoadTGA_IO; LoadTIF_IO; LoadWEBP_IO; LoadXCF_IO; LoadXPM_IO; LoadXV_IO

◆ LoadLBM_IO()

Surface SDL::LoadLBM_IO ( IOStreamRef src )

inline

Load a LBM image directly.

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_IO; LoadBMP_IO; LoadCUR_IO; LoadGIF_IO; LoadICO_IO; LoadJPG_IO; LoadJXL_IO; LoadPCX_IO; LoadPNG_IO; LoadPNM_IO; LoadQOI_IO; LoadSVG_IO; LoadTGA_IO; LoadTIF_IO; LoadWEBP_IO; LoadXCF_IO; LoadXPM_IO; LoadXV_IO

◆ LoadPCX_IO()

Surface SDL::LoadPCX_IO ( IOStreamRef src )

inline

Load a PCX image directly.

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_IO; LoadBMP_IO; LoadCUR_IO; LoadGIF_IO; LoadICO_IO; LoadJPG_IO; LoadJXL_IO; LoadLBM_IO; LoadPNG_IO; LoadPNM_IO; LoadQOI_IO; LoadSVG_IO; LoadTGA_IO; LoadTIF_IO; LoadWEBP_IO; LoadXCF_IO; LoadXPM_IO; LoadXV_IO

◆ LoadPNG()

Surface SDL::LoadPNG ( StringParam file )

inline

Load a PNG image from a file.

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;

Parameters

file	the PNG file to load.

Returns: SDL surface, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: LoadAVIF_IO; LoadBMP_IO; LoadCUR_IO; LoadGIF_IO; LoadICO_IO; LoadJPG_IO; LoadJXL_IO; LoadLBM_IO; LoadPCX_IO; LoadPNM_IO; LoadQOI_IO; LoadSVG_IO; LoadTGA_IO; LoadTIF_IO; LoadWEBP_IO; LoadXCF_IO; LoadXPM_IO; LoadXV_IO

◆ LoadPNG_IO() [1/2]

Surface SDL::LoadPNG_IO ( IOStreamRef src )

inline

Load a PNG image directly.

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_IO; LoadBMP_IO; LoadCUR_IO; LoadGIF_IO; LoadICO_IO; LoadJPG_IO; LoadJXL_IO; LoadLBM_IO; LoadPCX_IO; LoadPNM_IO; LoadQOI_IO; LoadSVG_IO; LoadTGA_IO; LoadTIF_IO; LoadWEBP_IO; LoadXCF_IO; LoadXPM_IO; LoadXV_IO

◆ LoadPNG_IO() [2/2]

Surface SDL::LoadPNG_IO	(	IOStreamRef	src,
		bool	closeio )

inline

Load a PNG image directly.

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.
closeio	if true, calls IOStream.Close() on src before returning, even in the case of an error.

Returns: SDL surface, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: LoadAVIF_IO; LoadBMP_IO; LoadCUR_IO; LoadGIF_IO; LoadICO_IO; LoadJPG_IO; LoadJXL_IO; LoadLBM_IO; LoadPCX_IO; LoadPNM_IO; LoadQOI_IO; LoadSVG_IO; LoadTGA_IO; LoadTIF_IO; LoadWEBP_IO; LoadXCF_IO; LoadXPM_IO; LoadXV_IO

◆ LoadPNM_IO()

Surface SDL::LoadPNM_IO ( IOStreamRef src )

inline

Load a PNM image directly.

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_IO; LoadBMP_IO; LoadCUR_IO; LoadGIF_IO; LoadICO_IO; LoadJPG_IO; LoadJXL_IO; LoadLBM_IO; LoadPCX_IO; LoadPNG_IO; LoadQOI_IO; LoadSVG_IO; LoadTGA_IO; LoadTIF_IO; LoadWEBP_IO; LoadXCF_IO; LoadXPM_IO; LoadXV_IO

◆ LoadQOI_IO()

Surface SDL::LoadQOI_IO ( IOStreamRef src )

inline

Load a QOI image directly.

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_IO; LoadBMP_IO; LoadCUR_IO; LoadGIF_IO; LoadICO_IO; LoadJPG_IO; LoadJXL_IO; LoadLBM_IO; LoadPCX_IO; LoadPNG_IO; LoadPNM_IO; LoadSVG_IO; LoadTGA_IO; LoadTIF_IO; LoadWEBP_IO; LoadXCF_IO; LoadXPM_IO; LoadXV_IO

◆ LoadSizedSVG_IO()

Surface SDL::LoadSizedSVG_IO	(	IOStreamRef	src,
		const PointRaw &	size )

inline

Load an SVG image, scaled to a specific size.

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_IO

◆ LoadSurface()

Surface SDL::LoadSurface ( StringParam file )

inline

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

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

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_IO; LoadSurface_IO

◆ LoadSurface_IO()

Surface SDL::LoadSurface_IO	(	IOStreamRef	src,
		bool	closeio = false )

inline

Load an image from an SDL data source into a software surface.

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_IO(), 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: LoadSurface; LoadSurfaceTyped_IO

◆ LoadSurfaceTyped_IO()

Surface SDL::LoadSurfaceTyped_IO	(	IOStreamRef	src,
		StringParam	type,
		bool	closeio = false )

inline

Load an image from an SDL data source into a software surface.

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_IO(), 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_IO() 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: LoadSurface; LoadSurface_IO

◆ LoadSVG_IO()

Surface SDL::LoadSVG_IO ( IOStreamRef src )

inline

Load a SVG image directly.

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_IO; LoadBMP_IO; LoadCUR_IO; LoadGIF_IO; LoadICO_IO; LoadJPG_IO; LoadJXL_IO; LoadLBM_IO; LoadPCX_IO; LoadPNG_IO; LoadPNM_IO; LoadQOI_IO; LoadSizedSVG_IO; LoadTGA_IO; LoadTIF_IO; LoadWEBP_IO; LoadXCF_IO; LoadXPM_IO; LoadXV_IO

◆ LoadTexture()

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

inline

Load an image from a filesystem path into a texture.

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

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_IO; LoadTexture_IO

◆ LoadTexture_IO()

Texture SDL::LoadTexture_IO	(	RendererRef	renderer,
		IOStreamRef	src,
		bool	closeio = false )

inline

Load an image from an SDL data source into a texture.

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: LoadTexture(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_IO(), 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: LoadTexture; LoadTextureTyped_IO

◆ LoadTextureTyped_IO()

Texture SDL::LoadTextureTyped_IO	(	RendererRef	renderer,
		IOStreamRef	src,
		StringParam	type,
		bool	closeio = false )

inline

Load an image from an SDL data source into a texture.

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

There is also LoadTexture_IO(), 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_IO() 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: LoadTexture; LoadTexture_IO

◆ LoadTGA_IO()

Surface SDL::LoadTGA_IO ( IOStreamRef src )

inline

Load a TGA image directly.

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_IO; LoadBMP_IO; LoadCUR_IO; LoadGIF_IO; LoadICO_IO; LoadJPG_IO; LoadJXL_IO; LoadLBM_IO; LoadPCX_IO; LoadPNG_IO; LoadPNM_IO; LoadQOI_IO; LoadSVG_IO; LoadTIF_IO; LoadWEBP_IO; LoadXCF_IO; LoadXPM_IO; LoadXV_IO

◆ LoadTIF_IO()

Surface SDL::LoadTIF_IO ( IOStreamRef src )

inline

Load a TIFF image directly.

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_IO; LoadBMP_IO; LoadCUR_IO; LoadGIF_IO; LoadICO_IO; LoadJPG_IO; LoadJXL_IO; LoadLBM_IO; LoadPCX_IO; LoadPNG_IO; LoadPNM_IO; LoadQOI_IO; LoadSVG_IO; LoadTGA_IO; LoadWEBP_IO; LoadXCF_IO; LoadXPM_IO; LoadXV_IO

◆ LoadWEBP_IO()

Surface SDL::LoadWEBP_IO ( IOStreamRef src )

inline

Load a WEBP image directly.

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_IO; LoadBMP_IO; LoadCUR_IO; LoadGIF_IO; LoadICO_IO; LoadJPG_IO; LoadJXL_IO; LoadLBM_IO; LoadPCX_IO; LoadPNG_IO; LoadPNM_IO; LoadQOI_IO; LoadSVG_IO; LoadTGA_IO; LoadTIF_IO; LoadXCF_IO; LoadXPM_IO; LoadXV_IO

◆ LoadWEBPAnimation_IO()

Animation SDL::LoadWEBPAnimation_IO ( IOStreamRef src )

inline

Load a WEBP animation directly.

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; LoadAnimation; LoadAnimation_IO; LoadAnimationTyped_IO; LoadANIAnimation_IO; LoadAPNGAnimation_IO; LoadAVIFAnimation_IO; LoadGIFAnimation_IO; Animation.Free

◆ LoadXCF_IO()

Surface SDL::LoadXCF_IO ( IOStreamRef src )

inline

Load a XCF image directly.

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_IO; LoadBMP_IO; LoadCUR_IO; LoadGIF_IO; LoadICO_IO; LoadJPG_IO; LoadJXL_IO; LoadLBM_IO; LoadPCX_IO; LoadPNG_IO; LoadPNM_IO; LoadQOI_IO; LoadSVG_IO; LoadTGA_IO; LoadTIF_IO; LoadWEBP_IO; LoadXPM_IO; LoadXV_IO

◆ LoadXPM_IO()

Surface SDL::LoadXPM_IO ( IOStreamRef src )

inline

Load a XPM image directly.

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_IO; LoadBMP_IO; LoadCUR_IO; LoadGIF_IO; LoadICO_IO; LoadJPG_IO; LoadJXL_IO; LoadLBM_IO; LoadPCX_IO; LoadPNG_IO; LoadPNM_IO; LoadQOI_IO; LoadSVG_IO; LoadTGA_IO; LoadTIF_IO; LoadWEBP_IO; LoadXCF_IO; LoadXV_IO

◆ LoadXV_IO()

Surface SDL::LoadXV_IO ( IOStreamRef src )

inline

Load a XV image directly.

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_IO; LoadBMP_IO; LoadCUR_IO; LoadGIF_IO; LoadICO_IO; LoadJPG_IO; LoadJXL_IO; LoadLBM_IO; LoadPCX_IO; LoadPNG_IO; LoadPNM_IO; LoadQOI_IO; LoadSVG_IO; LoadTGA_IO; LoadTIF_IO; LoadWEBP_IO; LoadXCF_IO; LoadXPM_IO

◆ ReadXPMFromArray()

Surface SDL::ReadXPMFromArray ( char ** xpm )

inline

Load an XPM image from a memory array.

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

Load an XPM image from a memory array.

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

Reset an animation decoder.

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: CreateAnimationDecoder; CreateAnimationDecoder_IO; CreateAnimationDecoderWithProperties; AnimationDecoder.GetFrame; AnimationDecoder.Close

◆ ResetAnimationDecoder()

void SDL::ResetAnimationDecoder ( AnimationDecoderRef decoder )

inline

Reset an animation decoder.

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: CreateAnimationDecoder; CreateAnimationDecoder_IO; CreateAnimationDecoderWithProperties; AnimationDecoder.GetFrame; AnimationDecoder.Close

◆ Save() [1/3]

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

inline

Save an animation to a file.

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_IO; Animation.SaveANI_IO; Animation.SaveAPNG_IO; Animation.SaveAVIF_IO; Animation.SaveGIF_IO; Animation.SaveWEBP_IO

◆ Save() [2/3]

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

inline

Save an Surface into an image file.

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_IO; SaveAVIF; SaveBMP; SaveCUR; SaveGIF; SaveICO; SaveJPG; SavePNG; SaveTGA; SaveWEBP

◆ Save() [3/3]

void SDL::Surface::Save ( StringParam filename ) const

inline

Save an Surface into an image file.

If the file already exists, it will be overwritten.

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

Parameters

filename 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: SDL::SaveTyped_IO

◆ SaveANI_IO()

void SDL::Animation::SaveANI_IO	(	IOStreamRef	dst,
		bool	closeio = false )

inline

Save an animation in ANI format to an IOStream.

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_IO; Animation.SaveAPNG_IO; Animation.SaveAVIF_IO; Animation.SaveGIF_IO; Animation.SaveWEBP_IO

◆ SaveANIAnimation_IO()

void SDL::SaveANIAnimation_IO	(	AnimationRef	anim,
		IOStreamRef	dst,
		bool	closeio = false )

inline

Save an animation in ANI format to an IOStream.

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_IO; Animation.SaveAPNG_IO; Animation.SaveAVIF_IO; Animation.SaveGIF_IO; Animation.SaveWEBP_IO

◆ SaveAnimation()

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

inline

Save an animation to a file.

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_IO; Animation.SaveANI_IO; Animation.SaveAPNG_IO; Animation.SaveAVIF_IO; Animation.SaveGIF_IO; Animation.SaveWEBP_IO

◆ SaveAnimationTyped_IO()

void SDL::SaveAnimationTyped_IO	(	AnimationRef	anim,
		IOStreamRef	dst,
		StringParam	type,
		bool	closeio = false )

inline

Save an animation to an IOStream.

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_IO; Animation.SaveAPNG_IO; Animation.SaveAVIF_IO; Animation.SaveGIF_IO; Animation.SaveWEBP_IO

◆ SaveAPNG_IO()

void SDL::Animation::SaveAPNG_IO	(	IOStreamRef	dst,
		bool	closeio = false )

inline

Save an animation in APNG format to an IOStream.

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_IO; Animation.SaveANI_IO; Animation.SaveAVIF_IO; Animation.SaveGIF_IO; Animation.SaveWEBP_IO

◆ SaveAPNGAnimation_IO()

void SDL::SaveAPNGAnimation_IO	(	AnimationRef	anim,
		IOStreamRef	dst,
		bool	closeio = false )

inline

Save an animation in APNG format to an IOStream.

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_IO; Animation.SaveANI_IO; Animation.SaveAVIF_IO; Animation.SaveGIF_IO; Animation.SaveWEBP_IO

◆ SaveAVIF()

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

inline

Save an Surface into a AVIF image file.

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_IO

◆ SaveAVIF_IO() [1/2]

void SDL::Animation::SaveAVIF_IO	(	IOStreamRef	dst,
		int	quality,
		bool	closeio = false )

inline

Save an animation in AVIF format to an IOStream.

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_IO; Animation.SaveANI_IO; Animation.SaveAPNG_IO; Animation.SaveGIF_IO; Animation.SaveWEBP_IO

◆ SaveAVIF_IO() [2/2]

void SDL::SaveAVIF_IO	(	SurfaceRef	surface,
		IOStreamRef	dst,
		int	quality,
		bool	closeio = false )

inline

Save an Surface into AVIF image data, via an IOStream.

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

◆ SaveAVIFAnimation_IO()

void SDL::SaveAVIFAnimation_IO	(	AnimationRef	anim,
		IOStreamRef	dst,
		int	quality,
		bool	closeio = false )

inline

Save an animation in AVIF format to an IOStream.

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_IO; Animation.SaveANI_IO; Animation.SaveAPNG_IO; Animation.SaveGIF_IO; Animation.SaveWEBP_IO

◆ SaveCUR()

void SDL::SaveCUR	(	SurfaceRef	surface,
		StringParam	file )

inline

Save an Surface into a CUR image file.

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_IO

◆ SaveCUR_IO()

void SDL::SaveCUR_IO	(	SurfaceRef	surface,
		IOStreamRef	dst,
		bool	closeio = false )

inline

Save an Surface into CUR image data, via an IOStream.

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

◆ SaveGIF()

void SDL::SaveGIF	(	SurfaceRef	surface,
		StringParam	file )

inline

Save an Surface into a GIF image file.

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_IO

◆ SaveGIF_IO() [1/2]

void SDL::Animation::SaveGIF_IO	(	IOStreamRef	dst,
		bool	closeio = false )

inline

Save an animation in GIF format to an IOStream.

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_IO; Animation.SaveANI_IO; Animation.SaveAPNG_IO; Animation.SaveAVIF_IO; Animation.SaveWEBP_IO

◆ SaveGIF_IO() [2/2]

void SDL::SaveGIF_IO	(	SurfaceRef	surface,
		IOStreamRef	dst,
		bool	closeio = false )

inline

Save an Surface into GIF image data, via an IOStream.

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

◆ SaveGIFAnimation_IO()

void SDL::SaveGIFAnimation_IO	(	AnimationRef	anim,
		IOStreamRef	dst,
		bool	closeio = false )

inline

Save an animation in GIF format to an IOStream.

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_IO; Animation.SaveANI_IO; Animation.SaveAPNG_IO; Animation.SaveAVIF_IO; Animation.SaveWEBP_IO

◆ SaveICO()

void SDL::SaveICO	(	SurfaceRef	surface,
		StringParam	file )

inline

Save an Surface into a ICO image file.

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_IO

◆ SaveICO_IO()

void SDL::SaveICO_IO	(	SurfaceRef	surface,
		IOStreamRef	dst,
		bool	closeio = false )

inline

Save an Surface into ICO image data, via an IOStream.

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

◆ SaveJPG()

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

inline

Save an Surface into a JPEG image file.

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_IO

◆ SaveJPG_IO()

void SDL::SaveJPG_IO	(	SurfaceRef	surface,
		IOStreamRef	dst,
		int	quality,
		bool	closeio = false )

inline

Save an Surface into JPEG image data, via an IOStream.

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

◆ SavePNG() [1/2]

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

inline

Save an Surface into a PNG image file.

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_IO

◆ SavePNG() [2/2]

void SDL::Surface::SavePNG ( StringParam file ) const

inline

Save a surface to a file in PNG format.

If the file already exists, it will be overwritten.

Parameters

file	a file to save to.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.4.0.

See also: LoadPNG; LoadTrustedPNG; Surface.SavePNG_IO

◆ SavePNG_IO() [1/2]

void SDL::SavePNG_IO	(	SurfaceRef	surface,
		IOStreamRef	dst,
		bool	closeio = false )

inline

Save an Surface into PNG image data, via an IOStream.

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_IO() [2/2]

void SDL::Surface::SavePNG_IO	(	IOStreamRef	dst,
		bool	closeio = false ) const

inline

Save a surface to a seekable SDL data stream in PNG format.

If the file already exists, it will be overwritten.

Parameters

dst	a data stream to save to.
closeio	if true, calls IOStream.Close() on dst before returning, even in the case of an error.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.4.0.

See also: LoadPNG_IO; LoadTrustedPNG_IO; Surface.SavePNG

◆ SaveTGA()

void SDL::SaveTGA	(	SurfaceRef	surface,
		StringParam	file )

inline

Save an Surface into a TGA image file.

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_IO

◆ SaveTGA_IO()

void SDL::SaveTGA_IO	(	SurfaceRef	surface,
		IOStreamRef	dst,
		bool	closeio = false )

inline

Save an Surface into TGA image data, via an IOStream.

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

◆ SaveTyped_IO() [1/3]

void SDL::Animation::SaveTyped_IO	(	IOStreamRef	dst,
		StringParam	type,
		bool	closeio = false )

inline

Save an animation to an IOStream.

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_IO; Animation.SaveAPNG_IO; Animation.SaveAVIF_IO; Animation.SaveGIF_IO; Animation.SaveWEBP_IO

◆ SaveTyped_IO() [2/3]

void SDL::SaveTyped_IO	(	SurfaceConstRef	surface,
		IOStreamRef	dst,
		StringParam	type,
		bool	closeio = false )

inline

Save an Surface into formatted image data, via an IOStream.

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_IO; SaveBMP_IO; SaveCUR_IO; SaveGIF_IO; SaveICO_IO; SaveJPG_IO; SavePNG_IO; SaveTGA_IO; SaveWEBP_IO

◆ SaveTyped_IO() [3/3]

void SDL::Surface::SaveTyped_IO	(	IOStreamRef	dst,
		StringParam	type,
		bool	closeio = false ) const

inline

Save an Surface into formatted image data, via an IOStream.

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

dst	the IOStream to save the image data to.
closeio	true to close/free the IOStream before returning, false to leave it open.
type	a filename extension that represent this data ("BMP", "GIF", "PNG", etc).

Exceptions

Error on failure.

Since: This function is available since SDL_image 3.4.0.

See also: SDL::Save

◆ SaveWEBP()

void SDL::SaveWEBP	(	SurfaceRef	surface,
		StringParam	file,
		float	quality )

inline

Save an Surface into a WEBP image file.

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_IO

◆ SaveWEBP_IO() [1/2]

void SDL::Animation::SaveWEBP_IO	(	IOStreamRef	dst,
		int	quality,
		bool	closeio = false )

inline

Save an animation in WEBP format to an IOStream.

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_IO; Animation.SaveANI_IO; Animation.SaveAPNG_IO; Animation.SaveAVIF_IO; Animation.SaveGIF_IO

◆ SaveWEBP_IO() [2/2]

void SDL::SaveWEBP_IO	(	SurfaceRef	surface,
		IOStreamRef	dst,
		float	quality,
		bool	closeio = false )

inline

Save an Surface into WEBP image data, via an IOStream.

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

◆ SaveWEBPAnimation_IO()

void SDL::SaveWEBPAnimation_IO	(	AnimationRef	anim,
		IOStreamRef	dst,
		int	quality,
		bool	closeio = false )

inline

Save an animation in WEBP format to an IOStream.

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_IO; Animation.SaveANI_IO; Animation.SaveAPNG_IO; Animation.SaveAVIF_IO; Animation.SaveGIF_IO

◆ Surface() [1/2]

SDL::Surface::Surface	(	IOStreamRef	src,
		bool	closeio = false )

inline

Load an image from an SDL data source into a software surface.

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_IO(), 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 LoadTexture_IO() 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: LoadSurface; LoadSurfaceTyped_IO

◆ Surface() [2/2]

SDL::Surface::Surface ( StringParam file )

inline

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

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

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.

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

Since: This function is available since SDL_image 3.0.0.

See also: LoadSurfaceTyped_IO; LoadSurface_IO

◆ Texture() [1/2]

SDL::Texture::Texture	(	RendererRef	renderer,
		IOStreamRef	src,
		bool	closeio = false )

inline

Load an image from an SDL data source into a texture.

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: LoadTexture(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_IO(), 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.

Postcondition: a new texture, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: LoadTexture; LoadTextureTyped_IO

◆ Texture() [2/2]

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

inline

Load an image from a filesystem path into a texture.

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

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.

Postcondition: a new texture, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: LoadTextureTyped_IO; LoadTexture_IO

Variable Documentation

◆ DECODER_STATUS_COMPLETE

AnimationDecoderStatus SDL::DECODER_STATUS_COMPLETE

constexpr

Initial value:

=

IMG_DECODER_STATUS_COMPLETE

No more frames available.

◆ DECODER_STATUS_FAILED

AnimationDecoderStatus SDL::DECODER_STATUS_FAILED

constexpr

Initial value:

=

IMG_DECODER_STATUS_FAILED

The decoder failed to decode a frame, call GetError() for more information.

◆ DECODER_STATUS_INVALID

AnimationDecoderStatus SDL::DECODER_STATUS_INVALID

constexpr

Initial value:

=

IMG_DECODER_STATUS_INVALID

The decoder is invalid.

◆ DECODER_STATUS_OK

AnimationDecoderStatus SDL::DECODER_STATUS_OK

constexpr

Initial value:

=

IMG_DECODER_STATUS_OK

The decoder is ready to decode the next frame.

Namespaces

Classes

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ SDL_IMAGE_VERSION

◆ SDL_IMAGE_VERSION_ATLEAST

Typedef Documentation

◆ AnimationDecoderRef

◆ AnimationDecoderStatus

◆ AnimationEncoderRef

◆ AnimationRef

Function Documentation

◆ AddAnimationEncoderFrame()

◆ AddFrame()

◆ Animation() [1/2]

◆ Animation() [2/2]

◆ AnimationDecoder() [1/3]

◆ AnimationDecoder() [2/3]

◆ AnimationDecoder() [3/3]

◆ AnimationEncoder() [1/3]

◆ AnimationEncoder() [2/3]

◆ AnimationEncoder() [3/3]

◆ Close() [1/2]

◆ Close() [2/2]

◆ CloseAnimationDecoder()

◆ CloseAnimationEncoder()

◆ CreateAnimatedCursor()

◆ CreateAnimationDecoder()

◆ CreateAnimationDecoder_IO()

◆ CreateAnimationDecoderWithProperties()

◆ CreateAnimationEncoder()

◆ CreateAnimationEncoder_IO()

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

◆ LoadAnimation()

◆ LoadAnimation_IO()

◆ LoadAnimationTyped_IO()

◆ LoadAPNGAnimation_IO()

◆ LoadAVIF_IO()

◆ LoadAVIFAnimation_IO()

◆ LoadCUR_IO()

◆ LoadGIF_IO()

◆ LoadGIFAnimation_IO()