Set up a surface for directly accessing the pixels. More...

Public Member Functions
	SurfaceLock (SurfaceRef resource)
	Set up a surface for directly accessing the pixels.
	SurfaceLock (const SurfaceLock &other)=delete
	Copy constructor.
	SurfaceLock (SurfaceLock &&other) noexcept
	Move constructor.
	~SurfaceLock ()
	Release a surface after directly accessing the pixels.
SurfaceLock &	operator= (const SurfaceLock &other)=delete
SurfaceLock &	operator= (SurfaceLock &&other) noexcept
	Assignment operator.
constexpr	operator bool () const
	True if not locked.
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	reset ()
	Release a surface after directly accessing the pixels.
SurfaceRef	resource () const
	Get the reference to locked resource.
void	release ()
	Releases the lock without unlocking.

Detailed Description

Set up a surface for directly accessing the pixels.

Between calls to Surface.Lock() / Surface.Unlock(), you can write to and read from surface->pixels, using the pixel format stored in surface->format. Once you are done accessing the surface, you should use Surface.Unlock() to release it.

Not all surfaces require locking. If Surface.MustLock(surface) evaluates to 0, then you can read and write to the surface at any time, and the pixel format of the surface will not change.

Since: This function is available since SDL 3.2.0.

See also: Surface.MustLock; Surface.Unlock

Constructor & Destructor Documentation

◆ ~SurfaceLock()

SDL::SurfaceLock::~SurfaceLock ( )

inline

Release a surface after directly accessing the pixels.

Thread safety:: This function is not thread safe. The locking referred to by this function is making the pixels available for direct access, not thread-safe locking.

Since: This function is available since SDL 3.2.0.

See also: Surface.Lock

Member Function Documentation

◆ ReadPixel() [1/2]

Color SDL::SurfaceLock::ReadPixel ( const PointRaw & p ) const

inline

Retrieves a single pixel from a surface.

This function prioritizes correctness over speed: it is suitable for unit tests, but is not intended for use in a game engine.

Like GetRGBA, this uses the entire 0..255 range when converting color components from pixel formats with less than 8 bits per RGB component.

Parameters

p	the coordinates, 0 <= x < width and 0 <= y < height.

Returns: color on success.

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

◆ ReadPixel() [2/2]

void SDL::SurfaceLock::ReadPixel	(	const PointRaw &	p,
		Uint8 *	r,
		Uint8 *	g,
		Uint8 *	b,
		Uint8 *	a ) const

inline

Retrieves a single pixel from a surface.

This function prioritizes correctness over speed: it is suitable for unit tests, but is not intended for use in a game engine.

Like GetRGBA, this uses the entire 0..255 range when converting color components from pixel formats with less than 8 bits per RGB component.

Parameters

p	the coordinates, 0 <= x < width and 0 <= y < height.
r	a pointer filled in with the red channel, 0-255, or nullptr to ignore this channel.
g	a pointer filled in with the green channel, 0-255, or nullptr to ignore this channel.
b	a pointer filled in with the blue channel, 0-255, or nullptr to ignore this channel.
a	a pointer filled in with the alpha channel, 0-255, or nullptr to ignore this channel.

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

◆ ReadPixelFloat() [1/2]

FColor SDL::SurfaceLock::ReadPixelFloat ( const PointRaw & p ) const

inline

Retrieves a single pixel from a surface.

This function prioritizes correctness over speed: it is suitable for unit tests, but is not intended for use in a game engine.

Parameters

p	the coordinates, 0 <= x < width and 0 <= y < height.

Returns: color on success.

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

◆ ReadPixelFloat() [2/2]

void SDL::SurfaceLock::ReadPixelFloat	(	const PointRaw &	p,
		float *	r,
		float *	g,
		float *	b,
		float *	a ) const

inline

Retrieves a single pixel from a surface.

This function prioritizes correctness over speed: it is suitable for unit tests, but is not intended for use in a game engine.

Parameters

p	the coordinates, 0 <= x < width and 0 <= y < height.
r	a pointer filled in with the red channel, normally in the range 0-1, or nullptr to ignore this channel.
g	a pointer filled in with the green channel, normally in the range 0-1, or nullptr to ignore this channel.
b	a pointer filled in with the blue channel, normally in the range 0-1, or nullptr to ignore this channel.
a	a pointer filled in with the alpha channel, normally in the range 0-1, or nullptr to ignore this channel.

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

◆ WritePixel()

void SDL::SurfaceLock::WritePixel	(	const PointRaw &	p,
		ColorRaw	c )

inline

Writes a single pixel to a surface.

This function prioritizes correctness over speed: it is suitable for unit tests, but is not intended for use in a game engine.

Like MapColor, this uses the entire 0..255 range when converting color components from pixel formats with less than 8 bits per RGB component.

Parameters

p	the coordinates, 0 <= x < width, 0 <= y < height.
c	the color channels value, 0-255.

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

◆ WritePixelFloat()

void SDL::SurfaceLock::WritePixelFloat	(	const PointRaw &	p,
		const FColorRaw &	c )

inline

Writes a single pixel to a surface.

This function prioritizes correctness over speed: it is suitable for unit tests, but is not intended for use in a game engine.

Parameters

p	the coordinates, 0 <= x < width, 0 <= y < height.
c	the color channels values, normally in the range 0-1.

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

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

SDL3pp/SDL3pp_surface.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~SurfaceLock()

Member Function Documentation

◆ ReadPixel() [1/2]

◆ ReadPixel() [2/2]

◆ ReadPixelFloat() [1/2]

◆ ReadPixelFloat() [2/2]

◆ WritePixel()

◆ WritePixelFloat()