2D Drawing Engine (DRW / D/AVE 2D) display-list builder – public API More...

#include <stdint.h>
#include "ra8_drw.h"
#include "ra8_err.h"

Include dependency graph for ra8_drw_dlist.h:

This graph shows which files directly or indirectly include this file:

Functions
ra8_err_t	ra8_drw_dlist_begin (ra8_drw_dlist_t dl, uint32_t buf, uint32_t cap_words)
	Bind a display-list builder to a caller-owned word buffer.
ra8_err_t	ra8_drw_dlist_add_fill (ra8_drw_dlist_t dl, const ra8_drw_rect_t rect)
	Append one solid-rectangle fill primitive to a display list.
ra8_err_t	ra8_drw_dlist_end (ra8_drw_dlist_t *dl)
	Close a display list with its terminator word.
ra8_err_t	ra8_drw_dlist_run (const ra8_drw_dlist_t *dl)
	Trigger a built display list (writes DLISTSTART).

Detailed Description

2D Drawing Engine (DRW / D/AVE 2D) display-list builder – public API

A display list lets the DRW clear and repaint a framebuffer end to end with no CPU framebuffer writes (issue #247). This header carries the caller-side builder API that composes such a list into a caller-owned word buffer: ra8_drw_dlist_begin binds the builder, ra8_drw_dlist_add_fill appends solid-rectangle primitives, ra8_drw_dlist_end terminates the list, and ra8_drw_dlist_run triggers it. The build calls never touch MMIO; only ra8_drw_dlist_run writes DLISTSTART (via ra8_drw_run_dlist in ra8_drw.h).

The builder state type ra8_drw_dlist_t and the low-level trigger ra8_drw_run_dlist live in ra8_drw.h, which this header includes; the split is organizational (ra8_drw.h stays under the 1000-line cap) and changes no public symbol or contract.

Note: Not thread-safe; one builder per thread.

See also: ra8_drw.h

Copyright: Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Since: 0.1.0

Definition in file ra8_drw_dlist.h.

Function Documentation

◆ ra8_drw_dlist_add_fill()

ra8_err_t ra8_drw_dlist_add_fill	(	ra8_drw_dlist_t *	dl,
		const ra8_drw_rect_t *	rect )

nodiscard

Append one solid-rectangle fill primitive to a display list.

Emits the display-list entries the DRW needs to paint an axis-aligned solid rectangle – COLOR1, SIZE, CONTROL (limiters off, the bounding-box scan is the rectangle, HUM Ch 62.6.2 p 3716) and ORIGIN, the write that triggers the render – followed by a "wait for pipeline and cache" word so the primitive fully drains before the next one begins. This is the same geometry the register-mode ra8_drw_fill_rect uses; the surface format (CONTROL2, PITCH, cache) stays as ra8_drw_init programmed it. A full-surface rectangle with colour 0 is how a display list clears the framebuffer.

Parameters

[in,out]	dl	Bound builder (ra8_drw_dlist_begin succeeded).
[in]	rect	Rectangle in pixels; color_argb8888 is 0xAARRGGBB.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Primitive appended.
k_ra8_err_null_ptr	dl or rect was nullptr.
k_ra8_err_invalid_arg	Dimensions out of range or off the surface.
k_ra8_err_no_mem	The buffer cannot hold this primitive.

Precondition: dl was bound by ra8_drw_dlist_begin and not yet ended.; rect->width_px / height_px in [1..1024]; the rect lies on-surface.

Postcondition: On success dl->count grew by the primitive's word span.; On overflow dl->overflow is true and no partial entry was written.

Note: Not thread-safe; writes only the caller buffer, never MMIO.

See also: ra8_drw_dlist_end

Since: 0.1.0

Definition at line 425 of file ra8_drw_draw.c.

References ra8_drw_dlist_t::cap_words, ra8_drw_rect_t::color_argb8888, ra8_drw_dlist_t::count, ra8_drw_rect_t::height_px, internal_dlist_put_reg(), internal_dlist_put_special(), k_ra8_drw_dlist_fill_words, k_ra8_drw_dlr_arg_wait, k_ra8_drw_dlr_idx_color1, k_ra8_drw_dlr_idx_control, k_ra8_drw_dlr_idx_origin, k_ra8_drw_dlr_idx_size, k_ra8_drw_max_height_px, k_ra8_drw_max_width_px, k_ra8_drw_min_dim_px, k_ra8_drw_size_height_pos, k_ra8_err_invalid_arg, k_ra8_err_no_mem, k_ra8_ok, ra8_drw_dlist_t::overflow, priv_ra8_drw_internal_rect_above_max(), priv_ra8_drw_internal_rect_below_min(), priv_ra8_drw_internal_rect_off_surface(), priv_ra8_drw_internal_rect_origin(), RA8_CHECK_NULL_PTR, s_tag, and ra8_drw_rect_t::width_px.

Referenced by demo_build_dlist().

◆ ra8_drw_dlist_begin()

ra8_err_t ra8_drw_dlist_begin	(	ra8_drw_dlist_t *	dl,
		uint32_t *	buf,
		uint32_t	cap_words )

nodiscard

Bind a display-list builder to a caller-owned word buffer.

Resets the builder to empty and records the target buffer. The buffer must be 4-byte aligned and live in a region the DRW bus initiator can read (SRAM). No words are written yet.

Parameters

[out]	dl	Builder to initialize.
[in]	buf	4-byte-aligned word buffer in DRW-readable memory.
[in]	cap_words	Capacity of `buf` in 32-bit words (>= 1).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Builder bound and cleared.
k_ra8_err_null_ptr	dl or buf was nullptr.
k_ra8_err_invalid_arg	buf not 4-byte aligned or cap_words 0.

Precondition: dl and buf are non-null.; buf is 4-byte aligned and cap_words >= 1.

Postcondition: dl->count == 0 and dl->overflow == false.; dl->buf == buf and dl->terminated == false.

Note: Not thread-safe; one builder per thread.

See also: ra8_drw_dlist_add_fill; ra8_drw_dlist_end

Since: 0.1.0

Definition at line 407 of file ra8_drw_draw.c.

References ra8_drw_dlist_t::buf, ra8_drw_dlist_t::cap_words, ra8_drw_dlist_t::count, k_ra8_drw_internal_align_mask, k_ra8_err_invalid_arg, k_ra8_ok, ra8_drw_dlist_t::overflow, RA8_CHECK_NULL_PTR, s_tag, and ra8_drw_dlist_t::terminated.

Referenced by demo_build_dlist().

◆ ra8_drw_dlist_end()

ra8_err_t ra8_drw_dlist_end ( ra8_drw_dlist_t * dl )

nodiscard

Close a display list with its terminator word.

Appends the end-of-list marker so the DLR stops fetching after the last primitive. Must be called before ra8_drw_dlist_run.

Parameters

[in,out] dl Bound builder holding at least one primitive.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Terminator appended; the list is runnable.
k_ra8_err_null_ptr	dl was nullptr.
k_ra8_err_no_mem	The buffer cannot hold the terminator.
k_ra8_err_invalid_arg	The builder already overflowed.

Precondition: dl is non-null and was bound by ra8_drw_dlist_begin.; dl has not overflowed.

Postcondition: dl->terminated == true on success.; dl->count grew by one word.

Note: Not thread-safe.

See also: ra8_drw_dlist_run

Since: 0.1.0

Definition at line 467 of file ra8_drw_draw.c.

References ra8_drw_dlist_t::cap_words, ra8_drw_dlist_t::count, internal_dlist_put_special(), k_ra8_drw_dlist_special_words, k_ra8_drw_dlr_arg_terminate, k_ra8_err_invalid_arg, k_ra8_err_no_mem, k_ra8_ok, ra8_drw_dlist_t::overflow, RA8_CHECK_NULL_PTR, s_tag, and ra8_drw_dlist_t::terminated.

Referenced by demo_build_dlist().

◆ ra8_drw_dlist_run()

ra8_err_t ra8_drw_dlist_run ( const ra8_drw_dlist_t * dl )

nodiscard

Trigger a built display list (writes DLISTSTART).

Convenience wrapper over ra8_drw_run_dlist that first checks the builder closed cleanly. It flushes the DRW caches and writes DLISTSTART with the buffer address; the DLR then clears and repaints the framebuffer with no CPU framebuffer writes. Poll ra8_drw_wait_idle (or STATUS.DLISTACTIVE) for completion before reading the framebuffer.

Parameters

[in] dl Terminated builder (ra8_drw_dlist_end succeeded).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Display list triggered.
k_ra8_err_null_ptr	dl was nullptr.
k_ra8_err_invalid_arg	Builder overflowed, empty or not terminated.

Precondition: dl is non-null, terminated and did not overflow.; The DRW is initialized and idle.

Postcondition: DLISTSTART = dl->buf; the engine begins fetching.; On completion STATUS.DLISTIRQ is raised.

Note: Not thread-safe; writes MMIO.

See also: ra8_drw_dlist_add_fill

Since: 0.1.0

Definition at line 482 of file ra8_drw_draw.c.

References ra8_drw_dlist_t::buf, ra8_drw_dlist_t::count, k_ra8_err_invalid_arg, ra8_drw_dlist_t::overflow, RA8_CHECK_NULL_PTR, ra8_drw_run_dlist(), s_tag, and ra8_drw_dlist_t::terminated.

Referenced by main().

Functions

Detailed Description

Function Documentation

◆ ra8_drw_dlist_add_fill()

◆ ra8_drw_dlist_begin()

◆ ra8_drw_dlist_end()

◆ ra8_drw_dlist_run()