Lock a portion of the texture for write-only pixel access, and expose it as a SDL surface. More...

Inheritance diagram for SDL::TextureSurfaceLock:

Public Member Functions
	TextureSurfaceLock (TextureRef resource, OptionalRef< const RectRaw > rect=std::nullopt)
	Lock a portion of the texture for write-only pixel access, and expose it as a SDL surface.
	TextureSurfaceLock (const TextureSurfaceLock &other)=delete
	Copy constructor.
	TextureSurfaceLock (TextureSurfaceLock &&other) noexcept
	Move constructor.
	~TextureSurfaceLock ()
	Unlock a texture, uploading the changes to video memory, if needed.
TextureSurfaceLock &	operator= (const TextureSurfaceLock &other)=delete
TextureSurfaceLock &	operator= (TextureSurfaceLock &&other) noexcept
	Assignment operator.
void	reset ()
	Unlock a texture, uploading the changes to video memory, if needed.
TextureRef	resource () const
	Get the reference to locked resource.
Public Member Functions inherited from SDL::Surface
constexpr	Surface (SurfaceRaw resource) noexcept
	Constructs from raw Surface.
constexpr	Surface (const Surface &other)
	Copy constructor.
constexpr	Surface (Surface &&other) noexcept
	Move constructor.
	Surface (const PointRaw &size, PixelFormat format)
	Allocate a new surface with a specific pixel format.
	Surface (const PointRaw &size, PixelFormat format, void *pixels, int pitch)
	Allocate a new surface with a specific pixel format and existing pixel data.
	Surface (StringParam file)
	Load an image from a filesystem path into a software surface.
	Surface (IOStreamRef src, bool closeio=false)
	Load an image from an SDL data source into a software surface.
constexpr	operator SurfaceConstRef () const noexcept
	Converts to SurfaceConstRef.
	~Surface ()
	Destructor.
constexpr Surface &	operator= (Surface &&other) noexcept
	Assignment operator.
Surface &	operator= (const Surface &other)
	Assignment operator.
void	Destroy ()
	Free this surface.
constexpr bool	MustLock () const
	Evaluates to true if the surface needs to be locked before access.
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.
Palette	CreatePalette ()
	Create a palette and associate it with a surface.
void	SetPalette (PaletteRef palette)
	Set the palette used by a surface.
Palette	GetPalette () const
	Get the palette used by a surface.
void	AddAlternateImage (SurfaceRef image)
	Add an alternate version of a surface.
bool	HasAlternateImages () const
	Return whether a surface has alternate versions available.
OwnArray< SurfaceRaw >	GetImages () const
	Get an array including all versions of a surface.
void	RemoveAlternateImages ()
	Remove all alternate versions of a surface.
SurfaceLock	Lock ()
	Set up a surface for directly accessing the pixels.
void	Unlock (SurfaceLock &&lock)
	Release a surface after directly accessing the pixels.
void	SaveBMP_IO (IOStreamRef dst, bool closeio=false) const
	Save a surface to a seekable SDL data stream in BMP format.
void	SaveBMP (StringParam file) const
	Save a surface to a file in BMP format.
void	SavePNG_IO (IOStreamRef dst, bool closeio=false) const
	Save a surface to a seekable SDL data stream in PNG format.
void	SavePNG (StringParam file) const
	Save a surface to a file in PNG format.
void	SetRLE (bool enabled)
	Set the RLE acceleration hint for a surface.
bool	HasRLE () const
	Returns whether the surface is RLE enabled.
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.
std::optional< Uint32 >	GetColorKey () 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 RectRaw > 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	Rotate (float angle)
	Return a copy of a surface rotated clockwise a number of degrees.
Surface	Duplicate () const
	Creates a new surface identical to the existing surface.
Surface	Scale (const PointRaw &size, 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, PaletteRef palette, Colorspace colorspace, PropertiesRef 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 (const FColorRaw &c)
	Clear a surface with a specific color, with floating point precision.
void	FillRect (OptionalRef< const RectRaw > rect, Uint32 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	FillRects (SpanRef< const RectRaw > rects, Uint32 color)
	Perform a fast fill of a set of rectangles with a specific color.
void	Blit (SurfaceRef src, OptionalRef< const RectRaw > srcrect, OptionalRef< const RectRaw > dstrect)
	Performs a fast blit from the source surface to the destination surface with clipping.
void	BlitAt (SurfaceRef src, OptionalRef< const RectRaw > srcrect, const PointRaw &dstpos)
	Performs a fast blit from the source surface to the destination surface with clipping.
void	BlitUnchecked (SurfaceRef src, const RectRaw &srcrect, const RectRaw &dstrect)
	Perform low-level surface blitting only.
void	BlitScaled (SurfaceRef src, OptionalRef< const RectRaw > srcrect, OptionalRef< const RectRaw > dstrect, ScaleMode scaleMode)
	Perform a scaled blit to a destination surface, which may be of a different format.
void	BlitUncheckedScaled (SurfaceRef src, const RectRaw &srcrect, const RectRaw &dstrect, ScaleMode scaleMode)
	Perform low-level surface scaled blitting only.
void	Stretch (SurfaceRef src, OptionalRef< RectRaw > srcrect, OptionalRef< RectRaw > dstrect, ScaleMode scaleMode)
	Perform a stretched pixel copy from one surface to another.
void	BlitTiled (SurfaceRef src, OptionalRef< const RectRaw > srcrect, OptionalRef< const RectRaw > dstrect)
	Perform a tiled blit to a destination surface, which may be of a different format.
void	BlitTiledWithScale (SurfaceRef src, OptionalRef< const RectRaw > srcrect, float scale, ScaleMode scaleMode, OptionalRef< const RectRaw > dstrect)
	Perform a scaled and tiled blit to a destination surface, which may be of a different format.
void	Blit9Grid (SurfaceRef src, OptionalRef< const RectRaw > srcrect, int left_width, int right_width, int top_height, int bottom_height, OptionalRef< const RectRaw > dstrect, float scale=1, ScaleMode scaleMode=SCALEMODE_NEAREST)
	Perform a scaled blit using the 9-grid algorithm to a destination surface, which may be of a different format.
Uint32	MapRGB (Uint8 r, Uint8 g, Uint8 b) const
	Map an RGB triple to an opaque pixel value for a surface.
Uint32	MapRGBA (ColorRaw c) const
	Map an RGBA quadruple to a pixel value for a surface.
void	ReadPixel (const PointRaw &p, Uint8 r, Uint8 g, Uint8 b, Uint8 a) const
	Retrieves a single pixel from a surface.
Color	ReadPixel (const PointRaw &p) const
	Retrieves a single pixel from a surface.
void	ReadPixelFloat (const PointRaw &p, float r, float g, float b, float a) const
	Retrieves a single pixel from a surface.
FColor	ReadPixelFloat (const PointRaw &p) const
	Retrieves a single pixel from a surface.
void	WritePixel (const PointRaw &p, ColorRaw c)
	Writes a single pixel to a surface.
void	WritePixelFloat (const PointRaw &p, const FColorRaw &c)
	Writes a single pixel to a surface.
constexpr int	GetWidth () const
	Get the width in pixels.
constexpr int	GetHeight () const
	Get the height in pixels.
constexpr Point	GetSize () const
	Get the size in pixels.
constexpr int	GetPitch () const
	Get pitch in bytes.
constexpr PixelFormat	GetFormat () const
	Get the pixel format.
constexpr void *	GetPixels () const
	Get the pixels.
void	Save (StringParam filename) const
	Save an Surface into an image file.
void	SaveTyped_IO (IOStreamRef dst, StringParam type, bool closeio=false) const
	Save an Surface into formatted image data, via an IOStream.
constexpr	ResourceBase (RawPointer resource)
	Constructs from resource pointer.
constexpr	ResourceBase (std::nullptr_t=nullptr)
	Constructs null/invalid.
Public Member Functions inherited from SDL::ResourceBase< SurfaceRaw, SurfaceRawConst >
constexpr	ResourceBase (RawPointer resource)
	Constructs from resource pointer.
constexpr	operator bool () const
	Converts to bool.
constexpr auto	operator<=> (const ResourceBase &other) const=default
	Comparison.
constexpr RawConstPointer	operator-> () const noexcept
	member access to underlying resource pointer.
constexpr RawPointer	get () const noexcept
	Retrieves underlying resource pointer.
constexpr RawPointer	release () noexcept
	Retrieves underlying resource pointer and clear this.

Additional Inherited Members
Public Types inherited from SDL::ResourceBase< SurfaceRaw, SurfaceRawConst >
using	RawPointer
	The underlying raw pointer type.
using	RawConstPointer
	The underlying const raw pointer type.
Static Public Member Functions inherited from SDL::Surface
static Surface	Borrow (SurfaceRaw resource)
	Safely borrows the from SurfaceRaw.

Detailed Description

Lock a portion of the texture for write-only pixel access, and expose it as a SDL surface.

Besides providing an Surface instead of raw pixel data, this function operates like Texture.Lock.

As an optimization, the pixels made available for editing don't necessarily contain the old texture data. This is a write-only operation, and if you need to keep a copy of the texture data you should do that at the application level.

You must use Texture.Unlock() to unlock the pixels and apply any changes.

The returned surface is freed internally after calling Texture.Unlock() or Texture.Destroy(). The caller should not free it.

Since: This class is available since SDL 3.2.0.

See also: Texture.Lock; Texture.Unlock

Constructor & Destructor Documentation

◆ ~TextureSurfaceLock()

SDL::TextureSurfaceLock::~TextureSurfaceLock ( )

inline

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

Warning: Please note that Texture.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: Texture.Lock

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

SDL3pp/SDL3pp_render.h

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ ~TextureSurfaceLock()