Graphics Component

Rectangles, lines, and text drawing on any pixel surface. More...

Namespaces
namespace	idfxx
namespace	idfxx::gfx
	Drawing primitives and the pixel surface concept.

Concepts
concept	idfxx::gfx::pixel_surface
	A drawable two-dimensional pixel surface.

Classes
class	idfxx::gfx::canvas< Surface >
	A drawing view bundling a pixel surface with the drawing primitives. More...

Functions
template<pixel_surface Surface>
void	idfxx::gfx::fill_rect (Surface &surface, size_t x, size_t y, size_t width, size_t height, typename Surface::pixel_type ink) noexcept
	Fills a rectangle with the given ink.
template<pixel_surface Surface>
void	idfxx::gfx::draw_hline (Surface &surface, size_t x, size_t y, size_t length, typename Surface::pixel_type ink) noexcept
	Draws a horizontal line with the given ink.
template<pixel_surface Surface>
void	idfxx::gfx::draw_vline (Surface &surface, size_t x, size_t y, size_t length, typename Surface::pixel_type ink) noexcept
	Draws a vertical line with the given ink.
template<pixel_surface Surface>
void	idfxx::gfx::draw_rect (Surface &surface, size_t x, size_t y, size_t width, size_t height, typename Surface::pixel_type ink) noexcept
	Outlines a rectangle with the given ink.
template<pixel_surface Surface>
void	idfxx::gfx::draw_line (Surface &surface, size_t x0, size_t y0, size_t x1, size_t y1, typename Surface::pixel_type ink) noexcept
	Draws a straight line between two points with the given ink.
template<pixel_surface Surface>
void	idfxx::gfx::draw_text (Surface &surface, const font::mono_font &font, size_t x, size_t y, std::string_view text, typename Surface::pixel_type ink, unsigned scale=1) noexcept
	Draws text with the given ink.
template<pixel_surface Surface> requires std::same_as<typename Surface::pixel_type, bool>
void	idfxx::gfx::draw_text (Surface &surface, 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.
template<pixel_surface Surface, typename Dest , typename DrawFn > requires banded_renderable<Surface, Dest, DrawFn>
void	idfxx::gfx::render_banded (Surface &band, Dest &dest, size_t frame_height, DrawFn &&draw)
	Renders a frame taller than its framebuffer, band by band.
template<pixel_surface Surface, typename Dest , typename DrawFn > requires banded_renderable<Surface, Dest, DrawFn>
result< void >	idfxx::gfx::try_render_banded (Surface &band, Dest &dest, size_t frame_height, DrawFn &&draw)
	Renders a frame taller than its framebuffer, band by band.

Detailed Description

Rectangles, lines, and text drawing on any pixel surface.

Provides integer drawing primitives over the idfxx::gfx::pixel_surface concept: any type with set_pixel(x, y, pixel) and reported dimensions can be drawn on, with the ink value matching the surface's pixel type — bool for monochrome framebuffers, idfxx::lcd::rgb565 for color ones. All functions render "ink only": they write the requested pixels and leave everything else untouched, so drawing composes over existing content.

The primitives are available two ways: as members of idfxx::gfx::canvas, a lightweight view bundling a surface with the drawing operations, and as free functions taking the surface as their first argument.

idfxx::lcd::mono_framebuffer fb(display.width(), display.height());
idfxx::gfx::canvas canvas(fb);
 
canvas.fill_rect(0, 0, canvas.width(), 10, true);
canvas.draw_text(idfxx::font::spleen_5x8, 2, 1, "status", false);
canvas.draw_text(idfxx::font::spleen_8x16, 4, 16, "23.7", true, 2);
canvas.flush(display);

Function Documentation

draw_hline()

template<pixel_surface Surface>

void idfxx::gfx::draw_hline ( Surface &  surface, size_t  x, size_t  y, size_t  length, typename Surface::pixel_type  ink  )

noexcept

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 surface is clipped.

Template Parameters

Surface

The surface type (satisfies pixel_surface).

Parameters

surface	The surface to draw on.
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 130 of file gfx.hpp.

References idfxx::gfx::fill_rect().

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

draw_line()

template<pixel_surface Surface>

void idfxx::gfx::draw_line ( Surface &  surface, size_t  x0, size_t  y0, size_t  x1, size_t  y1, typename Surface::pixel_type  ink  )

noexcept

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

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

Template Parameters

Surface

The surface type (satisfies pixel_surface).

Parameters

surface	The surface to draw on.
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 204 of file gfx.hpp.

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

draw_rect()

template<pixel_surface Surface>

void idfxx::gfx::draw_rect ( Surface &  surface, size_t  x, size_t  y, size_t  width, size_t  height, typename Surface::pixel_type  ink  )

noexcept

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 surface is clipped.

Template Parameters

Surface

The surface type (satisfies pixel_surface).

Parameters

surface	The surface to draw on.
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 168 of file gfx.hpp.

References idfxx::gfx::draw_hline(), idfxx::gfx::draw_vline(), and idfxx::gfx::fill_rect().

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

draw_text() [1/2]

template<pixel_surface Surface>
requires std::same_as<typename Surface::pixel_type, bool>

void idfxx::gfx::draw_text ( Surface &  surface, 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.

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

Template Parameters

Surface

The surface type (satisfies pixel_surface with a bool pixel type).

Parameters

surface	The surface to draw on.
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 329 of file gfx.hpp.

References idfxx::gfx::draw_text().

draw_text() [2/2]

template<pixel_surface Surface>

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

noexcept

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 surface are clipped.

Template Parameters

Surface

The surface type (satisfies pixel_surface).

Parameters

surface	The surface to draw on.
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 265 of file gfx.hpp.

References idfxx::font::mono_font::advance(), idfxx::font::mono_font::bytes_per_row(), idfxx::font::mono_font::contains(), idfxx::font::mono_font::glyph(), idfxx::font::mono_font::height, and idfxx::font::mono_font::width.

Referenced by idfxx::gfx::canvas< Surface >::draw_text(), idfxx::gfx::canvas< Surface >::draw_text(), and idfxx::gfx::draw_text().

draw_vline()

template<pixel_surface Surface>

void idfxx::gfx::draw_vline ( Surface &  surface, size_t  x, size_t  y, size_t  length, typename Surface::pixel_type  ink  )

noexcept

Draws a vertical line with the given ink.

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

Template Parameters

Surface

The surface type (satisfies pixel_surface).

Parameters

surface	The surface to draw on.
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 148 of file gfx.hpp.

References idfxx::gfx::fill_rect().

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

fill_rect()

template<pixel_surface Surface>

void idfxx::gfx::fill_rect ( Surface &  surface, size_t  x, size_t  y, size_t  width, size_t  height, typename Surface::pixel_type  ink  )

noexcept

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 surface is clipped.

Template Parameters

Surface

The surface type (satisfies pixel_surface).

Parameters

surface	The surface to draw on.
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 94 of file gfx.hpp.

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

render_banded()

template<pixel_surface Surface, typename Dest , typename DrawFn >
requires banded_renderable<Surface, Dest, DrawFn>

void idfxx::gfx::render_banded	(	Surface &	band,
		Dest &	dest,
		size_t	frame_height,
		DrawFn &&	draw
	)

Renders a frame taller than its framebuffer, band by band.

Renders a frame_height-row frame through band, a framebuffer covering band.width() x band.height() pixels, in frame_height / band.height() passes. Each pass clears the band, invokes draw with a canvas whose coordinates span the full frame (the band placed at its slice via canvas(band, 0, y)), and flushes the band to dest at (0, y). Content outside the pass's band clips; content straddling band edges renders exactly its visible part, so the assembled frame is identical to one drawn through a full-frame buffer.

The callback is invoked once per band and must draw the complete frame each time, as a pure function of the scene state — compute any state changes (advancing samples, reading sensors) before rendering, not inside the callback.

idfxx::lcd::rgb565_framebuffer band(240, 40);
idfxx::gfx::render_banded(band, panel, 320, [&](auto& canvas) {
    canvas.draw_text(idfxx::font::spleen_8x16, 8, 8, "title", white, 2);
    canvas.draw_line(0, 0, 239, 319, green); // crosses every band
});

Template Parameters

Surface	The band's surface type (satisfies pixel_surface).
Dest	The flush destination type (e.g. a panel).
DrawFn	The draw callback type, invocable with canvas<Surface>&.

Parameters

band	The framebuffer to render through; its width is the frame width.
dest	The destination the band flushes to after each pass.
frame_height	Height of the frame, in pixels; must be a non-zero multiple of band.height().
draw	Callback drawing the complete frame on the given canvas.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error

on error (e.g. an invalid frame_height, or a failed flush).

Definition at line 811 of file gfx.hpp.

References idfxx::gfx::try_render_banded(), and idfxx::unwrap().

try_render_banded()

template<pixel_surface Surface, typename Dest , typename DrawFn >
requires banded_renderable<Surface, Dest, DrawFn>

result< void > idfxx::gfx::try_render_banded	(	Surface &	band,
		Dest &	dest,
		size_t	frame_height,
		DrawFn &&	draw
	)

Renders a frame taller than its framebuffer, band by band.

Renders a frame_height-row frame through band, a framebuffer covering band.width() x band.height() pixels, in frame_height / band.height() passes. Each pass clears the band, invokes draw with a canvas whose coordinates span the full frame (the band placed at its slice via canvas(band, 0, y)), and flushes the band to dest at (0, y). Content outside the pass's band clips; content straddling band edges renders exactly its visible part, so the assembled frame is identical to one drawn through a full-frame buffer.

The callback is invoked once per band and must draw the complete frame each time, as a pure function of the scene state — compute any state changes (advancing samples, reading sensors) before rendering, not inside the callback.

Template Parameters

Surface	The band's surface type (satisfies pixel_surface).
Dest	The flush destination type (e.g. a panel).
DrawFn	The draw callback type, invocable with canvas<Surface>&.

Parameters

band	The framebuffer to render through; its width is the frame width.
dest	The destination the band flushes to after each pass.
frame_height	Height of the frame, in pixels; must be a non-zero multiple of band.height().
draw	Callback drawing the complete frame on the given canvas.

Returns

Success, or an error.

Return values

idfxx::errc::invalid_arg

if frame_height is zero or not a multiple of band.height(), or the band has zero height.

Definition at line 847 of file gfx.hpp.

References idfxx::gfx::canvas< Surface >::clear(), idfxx::error(), idfxx::invalid_arg, and idfxx::gfx::canvas< Surface >::try_flush().

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