DsSurface is a class that represents a drawing surface. More...

#include <ds_surface.h>

Public Member Functions
	DsSurface (int32_t width, int32_t height, const DsRotation &rotation, DsColorMode cmode, bool palette_has_alpha, size_t palette_size, ds_malloc_t fb_malloc, ds_free_t fb_free, uint32_t alignment=32, size_t extra_data=0)
	Creates a surface, allocates the framebuffer and the pallete table (if required)

	DsSurface (uint32_t *stream, size_t size)
	Creates a surface, allocates the framebuffer and the pallete table (if required) using a stream of bytes as the input.

	DsSurface (const DsSurface &src)
	Copy constructor - creates a copy of a surface. This will share the same framebuffer as the original surface.

	~DsSurface ()
	Destructor - frees the frame buffer and the palette table.

DsSize	getSize (void) const
	Return the logical size of the surface in pixels.

DsRect	getRegion (void) const
	Return the rectangular region of the surface (logical).

void	setUser (void *user)
	Sets the user pointer attached to the surface.

void *	getUser (void)
	Gets the user pointer attached to the surface.

DsRotation	getRotation (void) const
	Gets the surface rotation.

int32_t	getPhysicalWidth (void) const
	Gets the physical width of the framebuffer.

int32_t	getPhysicalHeight (void) const
	Gets the physical height of the framebuffer.

uint32_t	getBpp (void) const
	Gets the number of bytes per pixel of the surface. This value depends on the color mode of the framebuffer.

uint32_t	getPitch (void) const
	Gets the pitch of the surface (number of bytes to add to a pixel to advance exactly one line).

uint32_t	getPitchPx (void) const
	Gets the pitch of the surface (number of pixels to add to a pixel to advance exactly one line).

DsColorMode	getColorMode (void) const
	Gets the color mode of the surface.

uint8_t *	getPixels (void)
	Gets the address of the framebuffer.

size_t	getFrameBufferSize (void) const
	Gets the total size in bytes of the framebuffer (allocated size)

uint16_t	getPaletteSize (void) const
	Gets the total size in bytes of the pallete (allocated size)

bool	doesPaletteHaveAlpha (void) const
	Does the palette have the alpha channel?

uint8_t *	getPalette (void)
	Gets the address of the palette.

DsSurface	getSubSurface (const DsRect &rect) const
	Returns a subsurface of the existing surface. The same framebuffer is used.

void	clear (DsColor color)
	Fills the surface with a specified color respecting the clip region.

void	putPixel (int32_t x, int32_t y, DsColor color)
	Sets the color of a pixel within the surface.

void	copy (int32_t x, int32_t y, const DsSurface &src, DsAlphaMode alpha_mode, DsColor color)
	Copies an entire surface to the current surface object respecting the clipping region.

void	copy (int32_t x, int32_t y, const DsSurface &src, const DsRect &src_area, DsAlphaMode alpha_mode, DsColor color)
	Copies a region of a surface to the current surface object respecting the clipping region.

void	blend (int32_t x, int32_t y, const DsSurface &src, DsAlphaMode alpha_mode, DsColor color)
	Blends an entire surface to the current surface object respecting the clipping region.

void	blend (int32_t x, int32_t y, const DsSurface &src, const DsRect &src_area, DsAlphaMode alpha_mode, DsColor color)
	Blends a region of a surface to the current surface object respecting the clipping region.

void	blendAligned (const DsSurface &src, DsAlphaMode alpha_mode, DsColor color, const DsRect &boundary, const DsAlignment &alignment, const DsPoint &offset=DsPoint(0, 0))
	Blends an entire surface to the current surface object respecting the clipping region.

void	invert (void)
	Inverts all the pixel values in a surface at a byte level.

void	replaceColor (DsColor match_color, bool match_mask_a, bool match_mask_r, bool match_mask_g, bool match_mask_b, DsColor new_color, bool new_mask_a, bool new_mask_r, bool new_mask_g, bool new_mask_b)
	Replaces a the color component of each pixel in the surface with a new value.

void	replaceColor (const DsSurface &src, bool replace_a, bool replace_r, bool replace_g, bool replace_b)
	Replaces the color components of each pixel in the surface with the components of the corresponding pixel in the source surface.

void	replaceAlpha (const DsSurface &alpha_only_src)
	Replaces the alpha channel of each pixel in the surface with the alpha of the corresponding pixel in the source surface.

void	rotateFrameBuffer (DsRotation rotation)
	Rotates the entire framebuffer counter-clockwise.

size_t	saveStream (uint32_t *stream)
	Saves the DsSurface object in the specified stream.

void	rotateXY (int32_t &x, int32_t &y) const
	Rotates the coordinate system to match the screen framebuffer rotation.

void	rotateXY (float &x, float &y) const
	Rotates the coordinate system to match the screen framebuffer rotation.

void	rotateWH (int32_t &w, int32_t &h) const
	Rotates the size (W, H) to match the screen framebuffer rotation.

void	rotateWH (float &w, float &h) const
	Rotates the size (W, H) to match the screen framebuffer rotation.

void	rotateRect (DsRect &rect) const
	Rotates a rectangle to match the screen framebuffer rotation.

void	rotateRect (DsFRect &rect) const
	Rotates a rectangle to match the screen framebuffer rotation.

void	unrotateRect (DsRect &rect) const
	Rotates a rectangle to match the screen framebuffer rotation.

void	unrotateRect (DsFRect &rect) const
	Rotates a rectangle to match the screen framebuffer rotation.

Friends
class	DsRenderer

class	DsScreen

class	DsView

Detailed Description

DsSurface is a class that represents a drawing surface.

This class contains all the information about the geometry of the framebuffer (width, height, pitch, rotation, color mode, bits per pixel, bytes per pixel, ...) The framebuffer is allocated using the supplied allocator / deallocator functions while observing the alignment requirements. Every line in the framebuffer is aligned according to the specified alignment. This is done to improve performance of certain DMAs, SDRAM controllers or LCD controllers. If the color mode is such that it requires a palette table, it will be allocated as well.

Constructor & Destructor Documentation

◆ DsSurface() [1/3]

DsSurface::DsSurface	(	int32_t	width,
		int32_t	height,
		const DsRotation &	rotation,
		DsColorMode	cmode,
		bool	palette_has_alpha,
		size_t	palette_size,
		ds_malloc_t	fb_malloc,
		ds_free_t	fb_free,
		uint32_t	alignment = `32`,
		size_t	extra_data = `0`
	)

Creates a surface, allocates the framebuffer and the pallete table (if required)

Parameters

width	Width of the surface in pixels
height	Height of the surface in pixels
rotation	Surface rotation (0°, 90°, 180°, 270°)
cmode	Color mode (ARGB888, RGB888, RGB565, ...)
palette_has_alpha	Does the palette contain the alpha channel?
palette_size	Number of entries in the color palette (if palette is not used the value does not matter)
fb_malloc	Pointer to a malloc style allocator used to allocate the framebuffer
fb_free	Pointer to a malloc style free function used to free the framebuffer
alignment	Alignment used for allocating the framebuffer. Every line in the framebuffer will be aligned to this value.
extra_data	Extra size to allocate. The framebuffer will contain "extra_data" number bytes on top of the required size. This is internally rounded up to a multiple of 4.

◆ DsSurface() [2/3]

DsSurface::DsSurface	(	uint32_t *	stream,
		size_t	size
	)

Creates a surface, allocates the framebuffer and the pallete table (if required) using a stream of bytes as the input.

This is used when an entire surface is stored in non-volatile memory. A use case is when a splash image is needed quickly on startup. Instead of decoding a PNG image which may be time consuming, the already decoded surface can be stored in FLASH and loaded in a DsSurface object using this constructor.

Parameters

stream	Pointer in memory where the DsSurface stream is located
size	Size of the stream in bytes

◆ DsSurface() [3/3]

DsSurface::DsSurface ( const DsSurface & src )

Copy constructor - creates a copy of a surface. This will share the same framebuffer as the original surface.

Only when the original surface is destructed the framebuffer is freed.

Parameters

src	Source DsSurface object

Member Function Documentation

◆ blend() [1/2]

void DsSurface::blend	(	int32_t	x,
		int32_t	y,
		const DsSurface &	src,
		const DsRect &	src_area,
		DsAlphaMode	alpha_mode,
		DsColor	color
	)

inline

Blends a region of a surface to the current surface object respecting the clipping region.

Parameters

x	X position inside the destination surface where the blending will take place
y	Y position inside the destination surface where the blending will take place
src	Source surface
src_area	Rectangle defining the source surface area to copy
alpha_mode	Alpha mode to use for the operation
color	Contains the alpha and the color for the operation. Alpha is only used if the alpha_mode is either COPY or MULTIPLY. The RGB components are only used if the source surface is alpha only.

◆ blend() [2/2]

void DsSurface::blend	(	int32_t	x,
		int32_t	y,
		const DsSurface &	src,
		DsAlphaMode	alpha_mode,
		DsColor	color
	)

Blends an entire surface to the current surface object respecting the clipping region.

Parameters

x	X position inside the destination surface where the blending will take place
y	Y position inside the destination surface where the blending will take place
src	Source surface
alpha_mode	Alpha mode to use for the operation
color	Contains the alpha and the color for the operation. Alpha is only used if the alpha_mode is either COPY or MULTIPLY. The RGB components are only used if the source surface is alpha only.

◆ blendAligned()

void DsSurface::blendAligned	(	const DsSurface &	src,
		DsAlphaMode	alpha_mode,
		DsColor	color,
		const DsRect &	boundary,
		const DsAlignment &	alignment,
		const DsPoint &	offset = `DsPoint(0, 0)`
	)

Blends an entire surface to the current surface object respecting the clipping region.

The blending is done inside the boundary rectangle, according to the alignment requirements. An offset can be applied when aligning the source surface. If the alignment is DS_ALIGN_LEFT(TOP) or DS_ALIGN_CENTER the offset is applied to the left(top). If the alignment is DS_ALIGN_RIGHT(BOTTOM) the offset is applied to the right(bottom).

Parameters

src	Source surface
alpha_mode	Alpha mode to use for the operation
color	Contains the alpha and the color for the operation. Alpha is only used if the alpha_mode is either COPY or MULTIPLY. The RGB components are only used if the source surface is alpha only.
boundary	Rectangle that defines the boundary where the blending will take place
alignment	The alignment mode inside the boundary
offset	Offset to be aplied for alignment.

◆ clear()

void DsSurface::clear ( DsColor color )

Fills the surface with a specified color respecting the clip region.

Parameters

color Color to be used

◆ copy() [1/2]

void DsSurface::copy	(	int32_t	x,
		int32_t	y,
		const DsSurface &	src,
		const DsRect &	src_area,
		DsAlphaMode	alpha_mode,
		DsColor	color
	)

inline

Copies a region of a surface to the current surface object respecting the clipping region.

Parameters

x	X position inside the destination surface where the copying will take place
y	Y position inside the destination surface where the copying will take place
src	Source surface
src_area	Rectangle defining the source surface area to copy
alpha_mode	Alpha mode to use for the operation
color	Contains the alpha and the color for the operation. Alpha is only used if the alpha_mode is either COPY or MULTIPLY. The RGB components are only used if the source surface is alpha only.

◆ copy() [2/2]

void DsSurface::copy	(	int32_t	x,
		int32_t	y,
		const DsSurface &	src,
		DsAlphaMode	alpha_mode,
		DsColor	color
	)

Copies an entire surface to the current surface object respecting the clipping region.

Parameters

x	X position inside the destination surface where the copying will take place
y	Y position inside the destination surface where the copying will take place
src	Source surface
alpha_mode	Alpha mode to use for the operation
color	Contains the alpha and the color for the operation. Alpha is only used if the alpha_mode is either COPY or MULTIPLY. The RGB components are only used if the source surface is alpha only.

◆ doesPaletteHaveAlpha()

bool DsSurface::doesPaletteHaveAlpha ( void ) const

Does the palette have the alpha channel?

Returns: True if the palette has the alpha channel

◆ getBpp()

uint32_t DsSurface::getBpp ( void ) const

Gets the number of bytes per pixel of the surface. This value depends on the color mode of the framebuffer.

Returns: Number of bytes per pixel

◆ getColorMode()

DsColorMode DsSurface::getColorMode ( void ) const

Gets the color mode of the surface.

Returns: Color mode

◆ getFrameBufferSize()

size_t DsSurface::getFrameBufferSize ( void ) const

Gets the total size in bytes of the framebuffer (allocated size)

Returns: Framebuffer size in bytes

◆ getPalette()

uint8_t * DsSurface::getPalette ( void )

Gets the address of the palette.

Returns: Pointer to the palette, nullptr if the palette is not allocated

◆ getPaletteSize()

uint16_t DsSurface::getPaletteSize ( void ) const

Gets the total size in bytes of the pallete (allocated size)

Returns: Palette size in bytes. 0 if the pallete is not used and not allocated.

◆ getPhysicalHeight()

int32_t DsSurface::getPhysicalHeight ( void ) const

Gets the physical height of the framebuffer.

This may be different than the logical height if the framebuffer is rotated.

Returns: Physical height in pixels

◆ getPhysicalWidth()

int32_t DsSurface::getPhysicalWidth ( void ) const

Gets the physical width of the framebuffer.

This may be different than the logical width if the framebuffer is rotated.

Returns: Physical width in pixels

◆ getPitch()

uint32_t DsSurface::getPitch ( void ) const

Gets the pitch of the surface (number of bytes to add to a pixel to advance exactly one line).

This value depends on the color mode of the framebuffer and the alignment.

Returns: Pitch in bytes

◆ getPitchPx()

uint32_t DsSurface::getPitchPx ( void ) const

Gets the pitch of the surface (number of pixels to add to a pixel to advance exactly one line).

This value depends on the color mode of the framebuffer and the alignment.

Returns: Pitch in pixels

◆ getPixels()

uint8_t * DsSurface::getPixels ( void )

Gets the address of the framebuffer.

Returns: Pointer to the top left pixel (0, 0)

◆ getRegion()

DsRect DsSurface::getRegion ( void ) const

Return the rectangular region of the surface (logical).

Returns: Region

◆ getRotation()

DsRotation DsSurface::getRotation ( void ) const

Gets the surface rotation.

Returns: Rotation

◆ getSize()

DsSize DsSurface::getSize ( void ) const

Return the logical size of the surface in pixels.

Returns: Size in pixels (W, H)

◆ getSubSurface()

DsSurface DsSurface::getSubSurface ( const DsRect & rect ) const

Returns a subsurface of the existing surface. The same framebuffer is used.

Parameters

rect	The region of the surface to return as a subsurface (in the parent surface coordinate system)

Returns: Subsurface of the existing surface. The same framebuffer is used.

◆ getUser()

void * DsSurface::getUser ( void )

Gets the user pointer attached to the surface.

Returns: User pointer

◆ putPixel()

void DsSurface::putPixel	(	int32_t	x,
		int32_t	y,
		DsColor	color
	)

Sets the color of a pixel within the surface.

Parameters

x	X coordinate of the pixel
y	Y coordinate of the pixel
color	Color to be used

◆ replaceAlpha()

void DsSurface::replaceAlpha ( const DsSurface & alpha_only_src )

Replaces the alpha channel of each pixel in the surface with the alpha of the corresponding pixel in the source surface.

Parameters

alpha_only_src The source surface (must have the same size as the current surface and must have the color mode A8 - alpha only)

◆ replaceColor() [1/2]

void DsSurface::replaceColor	(	const DsSurface &	src,
		bool	replace_a,
		bool	replace_r,
		bool	replace_g,
		bool	replace_b
	)

Replaces the color components of each pixel in the surface with the components of the corresponding pixel in the source surface.

Parameters

src	The source surface (must have the same size as the current surface)
replace_a	True if the alpha channel from the source image will replace the current alpha channel
replace_r	True if the red channel from the source image will replace the current red channel
replace_g	True if the green channel from the source image will replace the current green channel
replace_b	True if the blue channel from the source image will replace the current blue channel

◆ replaceColor() [2/2]

void DsSurface::replaceColor	(	DsColor	match_color,
		bool	match_mask_a,
		bool	match_mask_r,
		bool	match_mask_g,
		bool	match_mask_b,
		DsColor	new_color,
		bool	new_mask_a,
		bool	new_mask_r,
		bool	new_mask_g,
		bool	new_mask_b
	)

Replaces a the color component of each pixel in the surface with a new value.

Parameters

match_color	The raw color value to search for
match_mask_a	True if the alpha channel from the raw color value should match
match_mask_r	True if the red channel from the raw color value should match
match_mask_g	True if the green channel from the raw color value should match
match_mask_b	True if the blue channel from the raw color value should match
new_color	The new color value to replace th matching pixels with
new_mask_a	True if the alpha channel from the new color value replaces the matched pixel alpha value
new_mask_r	True if the red channel from the new color value replaces the matched pixel red value
new_mask_g	True if the green channel from the new color value replaces the matched pixel green value
new_mask_b	True if the blue channel from the new color value replaces the matched pixel blue value

◆ rotateFrameBuffer()

void DsSurface::rotateFrameBuffer ( DsRotation rotation )

Rotates the entire framebuffer counter-clockwise.

Parameters

rotation Rotation angle

◆ saveStream()

size_t DsSurface::saveStream ( uint32_t * stream )

Saves the DsSurface object in the specified stream.

Parameters

[out] stream Address of the stream. If nullptr, only returns the required size.

Returns: Total size of the stream

◆ setUser()

void DsSurface::setUser ( void * user )

Sets the user pointer attached to the surface.

Parameters

user	User pointer

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

inc/ds_surface.h

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ DsSurface() [1/3]

◆ DsSurface() [2/3]

◆ DsSurface() [3/3]

Member Function Documentation

◆ blend() [1/2]

◆ blend() [2/2]

◆ blendAligned()

◆ clear()

◆ copy() [1/2]

◆ copy() [2/2]

◆ doesPaletteHaveAlpha()

◆ getBpp()

◆ getColorMode()

◆ getFrameBufferSize()

◆ getPalette()

◆ getPaletteSize()

◆ getPhysicalHeight()

◆ getPhysicalWidth()

◆ getPitch()

◆ getPitchPx()

◆ getPixels()

◆ getRegion()

◆ getRotation()

◆ getSize()

◆ getSubSurface()

◆ getUser()

◆ putPixel()

◆ replaceAlpha()

◆ replaceColor() [1/2]

◆ replaceColor() [2/2]

◆ rotateFrameBuffer()

◆ saveStream()

◆ setUser()