A drawing view bundling a pixel surface with the drawing primitives. More...

Public Types
using	pixel_type = typename Surface::pixel_type
	The pixel value type of the underlying surface.

Public Member Functions
	canvas (Surface &surface) noexcept
	Creates a canvas drawing on the given surface.

	canvas (Surface &surface, size_t x, size_t y) noexcept
	Creates a canvas whose surface sits at (`x`, `y`) in the canvas's coordinates.

Surface &	surface () const noexcept
	Returns the underlying surface.

size_t	width () const noexcept
	Returns the width of the canvas's coordinate space, in pixels.

size_t	height () const noexcept
	Returns the height of the canvas's coordinate space, in pixels.

canvas	window (size_t x, size_t y, size_t width, size_t height) const noexcept
	Returns a canvas for a sub-region of this one.

void	set_pixel (size_t x, size_t y, pixel_type ink) noexcept
	Sets a single pixel to the given ink.

void	fill (pixel_type ink) noexcept
	Sets every drawable pixel to the given ink.

void	clear () noexcept
	Sets every drawable pixel to the default value (equivalent to `fill(pixel_type{})`).

template<typename... Args> requires requires(Surface& s) { s.flush(std::declval<Args>()...); }
decltype(auto)	flush (Args &&... args) const
	Pushes the surface's content onward, on surfaces that support it.

template<typename... Args> requires requires(Surface& s) { s.try_flush(std::declval<Args>()...); }
decltype(auto)	try_flush (Args &&... args) const
	Pushes the surface's content onward, on surfaces that support it.

void	fill_rect (size_t x, size_t y, size_t width, size_t height, pixel_type ink) noexcept
	Fills a rectangle with the given ink.

void	draw_hline (size_t x, size_t y, size_t length, pixel_type ink) noexcept
	Draws a horizontal line with the given ink.

void	draw_vline (size_t x, size_t y, size_t length, pixel_type ink) noexcept
	Draws a vertical line with the given ink.

void	draw_rect (size_t x, size_t y, size_t width, size_t height, pixel_type ink) noexcept
	Outlines a rectangle with the given ink.

void	draw_line (size_t x0, size_t y0, size_t x1, size_t y1, pixel_type ink) noexcept
	Draws a straight line between two points with the given ink.

void	draw_text (const font::mono_font &font, size_t x, size_t y, std::string_view text, pixel_type ink, unsigned scale=1) noexcept
	Draws text with the given ink.

void	draw_text (const font::mono_font &font, size_t x, size_t y, std::string_view text) noexcept
	Draws text on a monochrome surface, setting glyph ink pixels.

Detailed Description

template<pixel_surface Surface>
class idfxx::gfx::canvas< Surface >

A drawing view bundling a pixel surface with the drawing primitives.

A canvas holds a reference to a surface and exposes the drawing primitives as members, so a sequence of drawing calls reads as operations on one object rather than free functions each taking the surface:

idfxx::lcd::rgb565_framebuffer band(240, 40);
idfxx::gfx::canvas canvas(band);
 
canvas.clear();
canvas.fill_rect(8, 8, 60, 24, red);
canvas.draw_rect(6, 6, 64, 28, white);
canvas.draw_text(idfxx::font::spleen_8x16, 84, 12, "red", red);
canvas.flush(panel, 0, 40);

Each drawing member is equivalent to the free function of the same name applied to the underlying surface, with the same ink-only rendering and clipping contract. fill and clear use the surface's own fill/clear when it provides them (framebuffers fill their backing store directly), falling back to per-pixel writes otherwise. When the surface can push its content onward (the framebuffers' flush / try_flush to a panel), flush and try_flush forward to it, so the full draw-then-transfer cycle reads off the one object.

A canvas may also place its surface within a larger drawing-coordinate space. Constructing with an origin — canvas(band, 0, y) — declares that the surface's top-left corner sits at (0, y) in the canvas's coordinates, so a frame taller than the surface can be authored once in full-screen coordinates and rendered band by band, with everything outside the band clipped (on all four sides — glyphs and lines straddling a band edge render exactly their visible part):

idfxx::lcd::rgb565_framebuffer band(DISPLAY_W, BAND_H);
for (size_t y = 0; y < DISPLAY_H; y += BAND_H) {
    idfxx::gfx::canvas canvas(band, 0, y);
    canvas.clear();
    draw_frame(canvas); // draws in full-screen coordinates
    canvas.flush(panel, 0, y);
}

render_banded packages this loop — prefer it over writing the loop by hand.

The inverse mapping is window, which returns a canvas for a sub-region of this one with its own local coordinates and clipping — e.g. handing a widget a canvas where (0, 0) is the widget's corner.

A canvas is a cheap, copyable view: it does not own the surface, and the caller must ensure the surface outlives it. A canvas itself satisfies pixel_surface, so it can be passed anywhere a surface is expected.

Template Parameters

Surface The surface type (satisfies pixel_surface).

Definition at line 393 of file gfx.hpp.

Member Typedef Documentation

◆ pixel_type

template<pixel_surface Surface>

using idfxx::gfx::canvas< Surface >::pixel_type = typename Surface::pixel_type

The pixel value type of the underlying surface.

Definition at line 396 of file gfx.hpp.

Constructor & Destructor Documentation

◆ canvas() [1/2]

template<pixel_surface Surface>

idfxx::gfx::canvas< Surface >::canvas ( Surface & surface )

inlineexplicitnoexcept

Creates a canvas drawing on the given surface.

The canvas's coordinates coincide with the surface's: (0, 0) is the surface's top-left corner, and width / height match the surface's dimensions (captured at construction).

Parameters

surface The surface to draw on; must outlive the canvas.

Definition at line 407 of file gfx.hpp.

◆ canvas() [2/2]

template<pixel_surface Surface>

idfxx::gfx::canvas< Surface >::canvas	(	Surface &	surface,
		size_t	x,
		size_t	y
	)

inlinenoexcept

Creates a canvas whose surface sits at (x, y) in the canvas's coordinates.

Declares that the surface holds the region of the drawing space whose top-left corner is (x, y) — the band-rendering mapping. Drawing uses the full-space coordinates; pixels landing outside the surface are clipped on all four sides. width and height report the far edges of the surface in canvas coordinates (x + the surface width, y + the surface height), so for a full-width band they match the frame dimensions.

Parameters

surface	The surface to draw on; must outlive the canvas.
x	Canvas-coordinate column of the surface's left edge.
y	Canvas-coordinate row of the surface's top edge.

Definition at line 429 of file gfx.hpp.

Member Function Documentation

◆ clear()

template<pixel_surface Surface>

void idfxx::gfx::canvas< Surface >::clear ( )

inlinenoexcept

Sets every drawable pixel to the default value (equivalent to fill(pixel_type{})).

Clears the canvas's drawable region — the part of its coordinate space backed by the surface. Uses the surface's own clear when it provides one and the region covers the whole surface (the identity and whole-band cases); otherwise fills the region with a value-initialized pixel (false on monochrome surfaces, black on RGB565 ones).

Definition at line 545 of file gfx.hpp.

References idfxx::gfx::canvas< Surface >::fill().

Referenced by idfxx::gfx::try_render_banded().

◆ draw_hline()

template<pixel_surface Surface>

void idfxx::gfx::canvas< Surface >::draw_hline	(	size_t	x,
		size_t	y,
		size_t	length,
		pixel_type	ink
	)

inlinenoexcept

Draws a horizontal line with the given ink.

The line starts at (x, y) and extends length pixels to the right. Any part falling outside the canvas is clipped.

Parameters

x	Column of the line's left end, in pixels.
y	Row of the line, in pixels.
length	Length of the line, in pixels.
ink	The pixel value to write.

Definition at line 642 of file gfx.hpp.

References idfxx::gfx::canvas< Surface >::fill_rect().

◆ draw_line()

template<pixel_surface Surface>

void idfxx::gfx::canvas< Surface >::draw_line	(	size_t	x0,
		size_t	y0,
		size_t	x1,
		size_t	y1,
		pixel_type	ink
	)

inlinenoexcept

Draws a straight line between two points with the given ink.

Both endpoints are inclusive. Any part falling outside the canvas is clipped.

Parameters

x0	Column of the first endpoint, in pixels.
y0	Row of the first endpoint, in pixels.
x1	Column of the second endpoint, in pixels.
y1	Row of the second endpoint, in pixels.
ink	The pixel value to write.

Definition at line 686 of file gfx.hpp.

References idfxx::gfx::draw_line().

◆ draw_rect()

template<pixel_surface Surface>

void idfxx::gfx::canvas< Surface >::draw_rect	(	size_t	x,
		size_t	y,
		size_t	width,
		size_t	height,
		pixel_type	ink
	)

inlinenoexcept

Outlines a rectangle with the given ink.

The rectangle's top-left corner is at (x, y) and it spans width columns and height rows; only its one-pixel border is drawn. Any part falling outside the canvas is clipped.

Parameters

x	Left edge of the rectangle, in pixels.
y	Top edge of the rectangle, in pixels.
width	Width of the rectangle, in pixels.
height	Height of the rectangle, in pixels.
ink	The pixel value to write.

Definition at line 670 of file gfx.hpp.

References idfxx::gfx::draw_rect(), idfxx::gfx::canvas< Surface >::height(), and idfxx::gfx::canvas< Surface >::width().

◆ draw_text() [1/2]

template<pixel_surface Surface>

void idfxx::gfx::canvas< Surface >::draw_text	(	const font::mono_font &	font,
		size_t	x,
		size_t	y,
		std::string_view	text
	)

inlinenoexcept

Draws text on a monochrome surface, setting glyph ink pixels.

Equivalent to draw_text with ink = true; see there for the full rendering contract.

Parameters

font	Font to render with.
x	Left edge of the first glyph cell, in pixels.
y	Top edge of the glyph cells, in pixels.
text	The text to draw.

Definition at line 731 of file gfx.hpp.

References idfxx::gfx::draw_text().

◆ draw_text() [2/2]

template<pixel_surface Surface>

void idfxx::gfx::canvas< Surface >::draw_text	(	const font::mono_font &	font,
		size_t	x,
		size_t	y,
		std::string_view	text,
		pixel_type	ink,
		unsigned	scale = `1`
	)

inlinenoexcept

Draws text with the given ink.

Renders text left-to-right starting with its top-left corner at (x, y). Only glyph "ink" pixels are written — background pixels within the cell are left untouched, so text composes over existing content (on a monochrome surface, pass ink = false to erase ink pixels instead, e.g. for inverse text on a filled banner). Characters outside the font's range advance the cursor without drawing. Pixels falling outside the canvas are clipped.

Parameters

font	Font to render with.
x	Left edge of the first glyph cell, in pixels.
y	Top edge of the glyph cells, in pixels.
text	The text to draw.
ink	The pixel value to write for glyph ink.
scale	Integer magnification factor (>= 1; 0 is treated as 1); each font pixel becomes a scale x scale block.

Definition at line 709 of file gfx.hpp.

References idfxx::gfx::draw_text().

◆ draw_vline()

template<pixel_surface Surface>

void idfxx::gfx::canvas< Surface >::draw_vline	(	size_t	x,
		size_t	y,
		size_t	length,
		pixel_type	ink
	)

inlinenoexcept

Draws a vertical line with the given ink.

The line starts at (x, y) and extends length pixels downward. Any part falling outside the canvas is clipped.

Parameters

x	Column of the line, in pixels.
y	Row of the line's top end, in pixels.
length	Length of the line, in pixels.
ink	The pixel value to write.

Definition at line 655 of file gfx.hpp.

References idfxx::gfx::canvas< Surface >::fill_rect().

◆ fill()

template<pixel_surface Surface>

void idfxx::gfx::canvas< Surface >::fill ( pixel_type ink )

inlinenoexcept

Sets every drawable pixel to the given ink.

Fills the canvas's drawable region — the part of its coordinate space backed by the surface. Uses the surface's own fill when it provides one and the region covers the whole surface (the identity and whole-band cases); otherwise fills the region rectangle.

Parameters

ink	The pixel value to fill with.

Definition at line 523 of file gfx.hpp.

References idfxx::gfx::canvas< Surface >::fill_rect().

Referenced by idfxx::gfx::canvas< Surface >::clear().

◆ fill_rect()

template<pixel_surface Surface>

void idfxx::gfx::canvas< Surface >::fill_rect	(	size_t	x,
		size_t	y,
		size_t	width,
		size_t	height,
		pixel_type	ink
	)

inlinenoexcept

Fills a rectangle with the given ink.

The rectangle's top-left corner is at (x, y) and it spans width columns and height rows. Any part falling outside the canvas is clipped.

Parameters

x	Left edge of the rectangle, in pixels.
y	Top edge of the rectangle, in pixels.
width	Width of the rectangle, in pixels.
height	Height of the rectangle, in pixels.
ink	The pixel value to write.

Definition at line 612 of file gfx.hpp.

References idfxx::gfx::fill_rect(), idfxx::gfx::canvas< Surface >::height(), and idfxx::gfx::canvas< Surface >::width().

Referenced by idfxx::gfx::canvas< Surface >::draw_hline(), idfxx::gfx::canvas< Surface >::draw_vline(), and idfxx::gfx::canvas< Surface >::fill().

◆ flush()

template<pixel_surface Surface>

template<typename... Args>
requires requires(Surface& s) { s.flush(std::declval<Args>()...); }

decltype(auto) idfxx::gfx::canvas< Surface >::flush ( Args &&... args ) const

inline

Pushes the surface's content onward, on surfaces that support it.

Forwards to the underlying surface's flush, so a canvas over a framebuffer completes the draw-then-transfer cycle without reaching for the surface: canvas.flush(panel, x, y).

Template Parameters

Args	Argument types accepted by the surface's `flush`.

Parameters

args	Arguments forwarded to the surface's `flush`.

Returns: Whatever the surface's flush returns.

Note: Only declared when the surface provides a matching flush overload (for the idfxx framebuffers, only when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig).

Exceptions

Whatever the surface's flush throws (std::system_error for the idfxx framebuffers).

Definition at line 575 of file gfx.hpp.

◆ height()

template<pixel_surface Surface>

size_t idfxx::gfx::canvas< Surface >::height ( ) const

inlinenoexcept

Returns the height of the canvas's coordinate space, in pixels.

Coordinates at or beyond this bound clip. For a canvas covering its whole surface this is the surface height; for a translated canvas it is the surface's far row edge in canvas coordinates; for a window it is the window height.

Definition at line 457 of file gfx.hpp.

Referenced by idfxx::gfx::canvas< Surface >::draw_rect(), idfxx::gfx::canvas< Surface >::fill_rect(), and idfxx::gfx::canvas< Surface >::window().

◆ set_pixel()

template<pixel_surface Surface>

void idfxx::gfx::canvas< Surface >::set_pixel	(	size_t	x,
		size_t	y,
		pixel_type	ink
	)

inlinenoexcept

Sets a single pixel to the given ink.

Coordinates outside the canvas bounds, or landing outside the underlying surface, are ignored.

Parameters

x	Column, in `[0, width())`.
y	Row, in `[0, height())`.
ink	The pixel value to write.

Definition at line 500 of file gfx.hpp.

◆ surface()

template<pixel_surface Surface>

Surface & idfxx::gfx::canvas< Surface >::surface ( ) const

inlinenoexcept

Returns the underlying surface.

Definition at line 437 of file gfx.hpp.

◆ try_flush()

template<pixel_surface Surface>

template<typename... Args>
requires requires(Surface& s) { s.try_flush(std::declval<Args>()...); }

decltype(auto) idfxx::gfx::canvas< Surface >::try_flush ( Args &&... args ) const

inline

Pushes the surface's content onward, on surfaces that support it.

Forwards to the underlying surface's try_flush, so a canvas over a framebuffer completes the draw-then-transfer cycle without reaching for the surface: canvas.try_flush(panel, x, y).

Template Parameters

Args	Argument types accepted by the surface's `try_flush`.

Parameters

args	Arguments forwarded to the surface's `try_flush`.

Returns: Whatever the surface's try_flush returns (success or an error for the idfxx framebuffers).

Note: Only declared when the surface provides a matching try_flush overload.

Definition at line 595 of file gfx.hpp.

Referenced by idfxx::gfx::try_render_banded().

◆ width()

template<pixel_surface Surface>

size_t idfxx::gfx::canvas< Surface >::width ( ) const

inlinenoexcept

Returns the width of the canvas's coordinate space, in pixels.

Coordinates at or beyond this bound clip. For a canvas covering its whole surface this is the surface width; for a translated canvas it is the surface's far column edge in canvas coordinates; for a window it is the window width.

Definition at line 447 of file gfx.hpp.

Referenced by idfxx::gfx::canvas< Surface >::draw_rect(), idfxx::gfx::canvas< Surface >::fill_rect(), and idfxx::gfx::canvas< Surface >::window().

◆ window()

template<pixel_surface Surface>

canvas idfxx::gfx::canvas< Surface >::window	(	size_t	x,
		size_t	y,
		size_t	width,
		size_t	height
	)		const

inlinenoexcept

Returns a canvas for a sub-region of this one.

The returned canvas has its own local coordinates — (0, 0) is the sub-region's top-left corner, which sits at (x, y) on this canvas — and clips to the sub-region's bounds, so drawing cannot escape it (including fill and clear, which affect only the sub-region). The requested rectangle is clamped to this canvas's bounds; an empty result is allowed and draws nothing.

auto gauge = canvas.window(50, 60, 100, 30);
gauge.clear();
gauge.draw_text(idfxx::font::spleen_5x8, 2, 2, "RPM", white);

Parameters

x	Column of the sub-region's left edge, in this canvas's coordinates.
y	Row of the sub-region's top edge, in this canvas's coordinates.
width	Width of the sub-region, in pixels.
height	Height of the sub-region, in pixels.

Returns: A canvas over the same surface, restricted to the sub-region.

Definition at line 481 of file gfx.hpp.

References idfxx::gfx::canvas< Surface >::height(), and idfxx::gfx::canvas< Surface >::width().

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

idfxx_gfx/include/idfxx/gfx.hpp

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ pixel_type

Constructor & Destructor Documentation

◆ canvas() [1/2]

◆ canvas() [2/2]

Member Function Documentation

◆ clear()

◆ draw_hline()

◆ draw_line()

◆ draw_rect()

◆ draw_text() [1/2]

◆ draw_text() [2/2]

◆ draw_vline()

◆ fill()

◆ fill_rect()

◆ flush()

◆ height()

◆ set_pixel()

◆ surface()

◆ try_flush()

◆ width()

◆ window()