Locks a Texture for access to its pixels.

Inheritance diagram for SDL::TextureLock:

[legend]

Public Member Functions
constexpr	TextureLock ()=default
	default ctor

	TextureLock (const TextureLock &other)=delete

	TextureLock (TextureLock &&other)
	Move ctor.

	~TextureLock ()
	destructor

TextureLock &	operator= (TextureLock other)
	Assignment operator.

void	Unlock ()
	Unlock a texture, uploading the changes to video memory, if needed.

void *	GetPixels () const
	Get the pixels.

int	GetPitch () const
	Get pitch (the number of bytes between the start of one row the next)

void	reset ()

Public Member Functions inherited from SDL::SurfaceBase
	SurfaceBase (StringParam file)
	Load an image from a filesystem path into a software surface.

	SurfaceBase (IOStreamBase &src)
	Load an image from a IOStreamBase into a software surface.

	SurfaceBase (const SDL_Point &size, PixelFormat format)
	Allocate a new surface with a specific pixel format.

	SurfaceBase (const SDL_Point &size, PixelFormat format, void *pixels, int pitch)
	Allocate a new surface with a specific pixel format and existing pixel data.

PropertiesRef	GetProperties () const
	Get the properties associated with a surface.

void	SetColorspace (Colorspace colorspace)
	Set the colorspace used by a surface.

Colorspace	GetColorspace () const
	Get the colorspace used by a surface.

PaletteRef	CreatePalette ()
	Create a palette and associate it with a surface.

void	SetPalette (PaletteBase &palette)
	Set the palette used by a surface.

PaletteRef	GetPalette () const
	Get the palette used by a surface.

void	AddAlternateImage (SurfaceBase &image)
	Add an alternate version of a surface.

bool	HasAlternateImages () const
	Return whether a surface has alternate versions available.

OwnArray< SurfaceRef >	GetImages () const
	Get an array including all versions of a surface.

void	RemoveAlternateImages ()
	Remove all alternate versions of a surface.

constexpr bool	MustLock () const
	Evaluates to true if the surface needs to be locked before access.

SurfaceLock	Lock () &
	Set up a surface for directly accessing the pixels.

void	SetRLE (bool enabled)
	Set the RLE acceleration hint for a surface.

bool	HasRLE () const
	Returns whether the surface is RLE enabled.

void	SetColorKey (Color key)
	Set the color key (transparent pixel) in a surface.

void	SetColorKey (std::optional< Uint32 > key)
	Set the color key (transparent pixel) in a surface.

void	ClearColorKey ()
	Unset the color key (transparent pixel) in a surface.

bool	HasColorKey () const
	Returns whether the surface has a color key.

Color	GetColorKey () const
	Get the color key (transparent pixel) for a surface.

void	GetColorKey (Color *key) const
	Get the color key (transparent pixel) for a surface.

void	GetColorKey (Uint32 *key) const
	Get the color key (transparent pixel) for a surface.

void	SetColorMod (Uint8 r, Uint8 g, Uint8 b)
	Set an additional color value multiplied into blit operations.

void	GetColorMod (Uint8 r, Uint8 g, Uint8 *b) const
	Get the additional color value multiplied into blit operations.

void	SetAlphaMod (Uint8 alpha)
	Set an additional alpha value used in blit operations.

Uint8	GetAlphaMod () const
	Get the additional alpha value used in blit operations.

void	SetMod (Color color)
	Set an additional color and alpha value multiplied into blit operations.

Color	GetMod () const
	Get the additional color and alpha value multiplied into blit operations.

void	SetBlendMode (BlendMode blendMode)
	Set the blend mode used for blit operations.

BlendMode	GetBlendMode () const
	Get the blend mode used for blit operations.

bool	SetClipRect (OptionalRef< const SDL_Rect > rect)
	Set the clipping rectangle for a surface.

void	ResetClipRect ()
	Disable the clipping rectangle for a surface.

Rect	GetClipRect () const
	Get the clipping rectangle for a surface.

void	Flip (FlipMode flip)
	Flip a surface vertically or horizontally.

Surface	Duplicate () const
	Creates a new surface identical to the existing surface.

Surface	Scale (int width, int height, ScaleMode scaleMode) const
	Creates a new surface identical to the existing surface, scaled to the desired size.

Surface	Convert (PixelFormat format) const
	Copy an existing surface to a new surface of the specified format.

Surface	Convert (PixelFormat format, PaletteBase &palette, Colorspace colorspace, PropertiesBase &props) const
	Copy an existing surface to a new surface of the specified format and colorspace.

void	PremultiplyAlpha (bool linear)
	Premultiply the alpha in a surface.

void	Clear (SDL_FColor color)
	Clear a surface with a specific color, with floating point precision.

void	Fill (SDL_Color color)
	Perform a fast fill of a rectangle with a specific color.

void	Fill (Uint32 color)
	Perform a fast fill of a rectangle with a specific color.

void	FillRect (const SDL_Rect &rect, SDL_Color color)
	Perform a fast fill of a rectangle with a specific color.

void	FillRect (const SDL_Rect &rect, Uint32 color)
	Perform a fast fill of a rectangle with a specific color.

void	FillRects (SpanRef< const SDL_Rect > rects, SDL_Color color)
	Perform a fast fill of a set of rectangles with a specific color.

void	FillRects (SpanRef< const SDL_Rect > rects, Uint32 color)
	Perform a fast fill of a set of rectangles with a specific color.

void	Blit (const SurfaceBase &src, OptionalRef< const SDL_Rect > srcrect, const SDL_Point &dstpos)
	Performs a fast blit from the source surface to the destination surface with clipping.

void	Blit (const SurfaceBase &src, OptionalRef< const SDL_Rect > srcrect, OptionalRef< const SDL_Rect > dstrect)
	Performs a fast blit from the source surface to the destination surface with clipping.

void	BlitUnchecked (const SurfaceBase &src, const SDL_Rect &srcrect, const SDL_Rect &dstrect)
	Perform low-level surface blitting only.

void	BlitScaled (const SurfaceBase &src, OptionalRef< const SDL_Rect > srcrect, OptionalRef< const SDL_Rect > dstrect, ScaleMode scaleMode)
	Perform a scaled blit to a destination surface, which may be of a different format.

void	BlitUncheckedScaled (const SurfaceBase &src, const SDL_Rect &srcrect, const SDL_Rect &dstrect, ScaleMode scaleMode)
	Perform low-level surface scaled blitting only.

void	Stretch (const SurfaceBase &src, const SDL_Rect &srcrect, const SDL_Rect &dstrect, ScaleMode scaleMode)
	Perform a stretched pixel copy from one surface to another.

void	BlitTiled (const SurfaceBase &src, OptionalRef< const SDL_Rect > srcrect, OptionalRef< const SDL_Rect > dstrect)
	Perform a tiled blit to a destination surface, which may be of a different format.

void	BlitTiledWithScale (const SurfaceBase &src, OptionalRef< const SDL_Rect > srcrect, float scale, SDL_ScaleMode scaleMode, OptionalRef< const SDL_Rect > dstrect)
	Perform a scaled and tiled blit to a destination surface, which may be of a different format.

void	Blit9Grid (const SurfaceBase &src, OptionalRef< const SDL_Rect > srcrect, int left_width, int right_width, int top_height, int bottom_height, OptionalRef< const SDL_Rect > dstrect)
	Perform a scaled blit using the 9-grid algorithm to a destination surface, which may be of a different format.

void	Blit9GridWithScale (const SurfaceBase &src, OptionalRef< const SDL_Rect > srcrect, int left_width, int right_width, int top_height, int bottom_height, float scale, SDL_ScaleMode scaleMode, OptionalRef< const SDL_Rect > dstrect)
	Perform a scaled blit using the 9-grid algorithm to a destination surface, which may be of a different format.

Uint32	MapColor (SDL_Color color) const
	Map an RGBA quadruple to a pixel value for a surface.

Uint32	MapColor (Uint8 r, Uint8 g, Uint8 b) const
	Map an RGB triple to an opaque pixel value for a surface.

Uint32	MapColor (Uint8 r, Uint8 g, Uint8 b, Uint8 a) const
	Map an RGBA quadruple to a pixel value for a surface.

Color	ReadPixel (const SDL_Point &p) const
	This function prioritizes correctness over speed: it is suitable for unit tests, but is not intended for use in a game engine.

void	ReadPixel (const SDL_Point &p, SDL_Color *c) const
	This function prioritizes correctness over speed: it is suitable for unit tests, but is not intended for use in a game engine.

void	ReadPixel (const SDL_Point &p, SDL_FColor *c) const
	Retrieves a single pixel from a surface.

void	ReadPixel (const SDL_Point &p, Uint8 r, Uint8 g, Uint8 b, Uint8 a) const
	Retrieves a single pixel from a surface.

void	ReadPixel (const SDL_Point &p, float r, float g, float b, float a) const
	Retrieves a single pixel from a surface.

void	WritePixel (const SDL_Point &p, SDL_Color c)
	Writes a single pixel to a surface.

void	WritePixel (const SDL_Point &p, SDL_FColor c)
	Writes a single pixel to a surface.

int	GetWidth () const
	Get the width in pixels.

int	GetHeight () const
	Get the height in pixels.

Point	GetSize () const
	Get the size in pixels.

PixelFormat	GetFormat () const
	Get the pixel format.

constexpr	Resource (T resource={})
	Constructs the underlying resource.

constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.

constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.

	Resource (const Resource &other)=delete

	Resource (Resource &&other)=delete

Public Member Functions inherited from SDL::Resource< SDL_Surface * >
constexpr	Resource (SDL_Surface * resource={})
	Constructs the underlying resource.

constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.

constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.

	Resource (const Resource &other)=delete

	Resource (Resource &&other)=delete

Resource &	operator= (const Resource &other)=delete

Resource &	operator= (Resource &&other)=delete

constexpr	operator bool () const
	True if contains a valid resource.

constexpr bool	operator== (const Resource &other) const=default
	Comparison.

constexpr bool	operator== (std::nullopt_t) const
	Comparison.

constexpr bool	operator== (std::nullptr_t) const
	Comparison.

constexpr SDL_Surface *	get () const
	Return contained resource;.

constexpr SDL_Surface *	release (SDL_Surface * newResource={})
	Return contained resource and empties or replace value.

constexpr const SDL_Surface *	operator-> () const
	Access to fields.

constexpr SDL_Surface *	operator-> ()
	Access to fields.

Friends
class	TextureBase

Constructor & Destructor Documentation

◆ ~TextureLock()

SDL::TextureLock::~TextureLock ( )

inline

See also: Unlock()

Member Function Documentation

◆ reset()

void SDL::TextureLock::reset ( )

inline

See also: Unlock()

◆ Unlock()

void SDL::TextureLock::Unlock ( )

inline

Warning: Please note that TextureBase.Lock() is intended to be write-only; it will not guarantee the previous contents of the texture will be provided. You must fully initialize any area of a texture that you lock before unlocking it, as the pixels might otherwise be uninitialized memory.

Which is to say: locking and immediately unlocking a texture can result in corrupted textures, depending on the renderer in use.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: TextureBase.Lock

The documentation for this class was generated from the following file:

SDL3pp/SDL3pp_render.h

Public Member Functions

Friends

Constructor & Destructor Documentation

◆ ~TextureLock()

Member Function Documentation

◆ reset()

◆ Unlock()