AxlGfxDisplayList — Retained Display List

See AxlGfx — Graphics for an overview of the graphics substrate. An AxlGfxDisplayList is a retained, replayable command buffer: record a sequence of draw operations, then replay them against the active draw target as many times as you like — or walk them for trace / debug.

Header: <axl/axl-gfx-display-list.h>

The recorder is explicit: every immediate-mode axl_gfx_* primitive has an axl_gfx_dl_* analogue that appends an op instead of drawing. axl_gfx_display_list_replay then invokes the real primitive for each recorded op, in order — byte-identical to immediate mode.

Ownership. The list copies the transient data it is handed — polyline point arrays, blit pixel buffers, text strings, and stroke dash arrays — so the caller’s originals may be freed immediately after recording. It does not copy the handle-typed objects, which have their own lifecycles and must outlive the list: AxlGfxPath (filled / stroked by reference), AxlFont, and AxlTtf.

This is the Phase G9 “AGT-consumer” op slice — the primitives an AgtDrawContext forwards. Gradient fills and the transform-stack ops are a tracked follow-up.

API Reference

AxlGfx display list (Phase G9): a retained, replayable command buffer. Record a sequence of draw operations into an AxlGfxDisplayList, then replay them against the active draw target as many times as you like, or walk them for trace / debug.

A display list decouples what to draw from when to draw it. The classic uses are double-buffered retained rendering (record a widget tree once, replay every frame), draw-call tracing (assert that a widget emitted exactly the expected primitives — superseding a hand-rolled recording fixture), and deferred / reordered rendering.

The recorder is explicit: every immediate-mode axl_gfx_* draw primitive has an axl_gfx_dl_* analogue that appends an op instead of drawing. axl_gfx_display_list_replay then invokes the real primitive for each recorded op, in order.

AxlGfxDisplayList *dl = axl_gfx_display_list_new();
axl_gfx_dl_clear(dl, AXL_GFX_BLACK);
axl_gfx_dl_fill_rect(dl, 0, 0, 100, 40, AXL_GFX_BLUE);
axl_gfx_dl_fill_path(dl, glyph_path, AXL_GFX_WHITE);

// Replay every frame:
axl_gfx_display_list_replay(dl);

// Or introspect (e.g. in a test):
const AxlGfxOp *op = axl_gfx_display_list_op_at(dl, 1);
// op->kind == AXL_GFX_OP_FILL_RECT, op->u.rect_u.w == 100, ...

axl_gfx_display_list_free(dl);

Ownership.** The display list copies by-value op data and the transient arrays it is handed — polyline point arrays, blit pixel buffers, text strings, and stroke dash arrays — so the caller’s originals may be freed immediately after recording. It does NOT copy the handle-typed objects, which have their own lifecycles and are expected to outlive the list: AxlGfxPath (filled / stroked by reference, matching axl_gfx_path_free ownership), AxlFont, and AxlTtf. Those must stay valid until the last replay / free.

Covers the immediate-mode primitives an AgtDrawContext forwards, plus gradient fills and the full transform stack (translate / scale / rotate / skew / push / pop / reset). A textual dump serialization is the one tracked follow-up.

Typedefs

typedef struct AxlStream AxlStream: Forward declaration — axl_gfx_display_list_dump writes to an AxlStream without this header pulling in the whole stream API. Callers using the dump include <axl/axl-stream.h> themselves.

typedef struct AxlGfxDisplayList AxlGfxDisplayList: Opaque, growable, replayable list of recorded draw operations. Created with axl_gfx_display_list_new; freed with axl_gfx_display_list_free.

Enums

enum AxlGfxOpKind

Discriminant for AxlGfxOp — which immediate-mode primitive the op records. Stable enough to switch on for replay / trace.

Values:

enumerator AXL_GFX_OP_FILL_RECT: axl_gfx_fill_rect (u.rect_u)

enumerator AXL_GFX_OP_FILL_RECT_I: axl_gfx_fill_rect_i (u.rect_i)

enumerator AXL_GFX_OP_DRAW_LINE: axl_gfx_draw_line (u.line)

enumerator AXL_GFX_OP_DRAW_RECT: axl_gfx_draw_rect (u.rect_u)

enumerator AXL_GFX_OP_DRAW_POLYLINE: axl_gfx_draw_polyline (u.polyline)

enumerator AXL_GFX_OP_BLIT: axl_gfx_blit (u.blit)

enumerator AXL_GFX_OP_CLEAR: clear active target (u.clear)

enumerator AXL_GFX_OP_PUSH_CLIP: axl_gfx_push_clip (u.push_clip)

enumerator AXL_GFX_OP_POP_CLIP: axl_gfx_pop_clip (no payload)

enumerator AXL_GFX_OP_FILL_PATH: axl_gfx_fill_path (u.fill_path)

enumerator AXL_GFX_OP_STROKE_PATH: axl_gfx_stroke_path_ex (u.stroke_path)

enumerator AXL_GFX_OP_FILL_ROUNDED_RECT: axl_gfx_fill_rounded_rect (u.rounded_rect)

enumerator AXL_GFX_OP_DRAW_TEXT: axl_gfx_draw_text (u.text)

enumerator AXL_GFX_OP_DRAW_TEXT_TTF: axl_ttf_draw (u.text_ttf)

enumerator AXL_GFX_OP_FILL_RECT_GRADIENT: axl_gfx_fill_rect_gradient (u.rect_gradient)

enumerator AXL_GFX_OP_FILL_PATH_GRADIENT: axl_gfx_fill_path_gradient (u.path_gradient)

enumerator AXL_GFX_OP_FILL_ROUNDED_RECT_GRADIENT: axl_gfx_fill_rounded_rect_gradient (u.rounded_rect_gradient)

enumerator AXL_GFX_OP_TRANSLATE: axl_gfx_translate (u.translate)

enumerator AXL_GFX_OP_SCALE: axl_gfx_scale (u.scale)

enumerator AXL_GFX_OP_ROTATE: axl_gfx_rotate (u.rotate)

enumerator AXL_GFX_OP_SKEW: axl_gfx_skew (u.skew)

enumerator AXL_GFX_OP_PUSH_TRANSFORM: axl_gfx_push_transform (no payload)

enumerator AXL_GFX_OP_POP_TRANSFORM: axl_gfx_pop_transform (no payload)

enumerator AXL_GFX_OP_RESET_TRANSFORM: axl_gfx_reset_transform (no payload)

Functions

AxlGfxDisplayList *axl_gfx_display_list_new(void)

Allocate an empty display list.

Returns:: new list (caller frees with axl_gfx_display_list_free), or NULL on allocation failure.

void axl_gfx_display_list_free(AxlGfxDisplayList *dl)

Free a display list and every op it owns (point arrays, blit pixels, text strings, dash arrays). Borrowed handles (paths / fonts / ttf) are NOT freed. Safe to call with NULL.

Parameters:

dl – list to free, or NULL

void axl_gfx_display_list_clear(AxlGfxDisplayList *dl)

Remove all recorded ops, freeing their owned data, while retaining the list’s allocation for reuse. Cheaper than free + new for a list rebuilt every frame. Safe to call with NULL.

Parameters:

dl – list to reset, or NULL

size_t axl_gfx_display_list_count(const AxlGfxDisplayList *dl)

Number of ops recorded in dl.

Parameters:

dl – [in] list

Returns:

op count, or 0 if dl is NULL.

const AxlGfxOp *axl_gfx_display_list_op_at(const AxlGfxDisplayList *dl, size_t index)

Borrow a read-only pointer to the op at index.

The pointer is valid until the next mutation of dl (axl_gfx_dl_*, _clear, _free) — recording may reallocate the backing store. Do not free or mutate the returned op.

Parameters:

dl – [in] list
index – 0-based op index

Returns:

pointer to the op, or NULL if dl is NULL or index is out of range.

int axl_gfx_dl_fill_rect(AxlGfxDisplayList *dl, uint32_t x, uint32_t y, uint32_t w, uint32_t h, AxlGfxPixel color): Record axl_gfx_fill_rect.

int axl_gfx_dl_fill_rect_i(AxlGfxDisplayList *dl, int32_t x, int32_t y, int32_t w, int32_t h, AxlGfxPixel color): Record axl_gfx_fill_rect_i (signed coordinates).

int axl_gfx_dl_draw_line(AxlGfxDisplayList *dl, int32_t x0, int32_t y0, int32_t x1, int32_t y1, AxlGfxPixel color): Record axl_gfx_draw_line.

int axl_gfx_dl_draw_rect(AxlGfxDisplayList *dl, uint32_t x, uint32_t y, uint32_t w, uint32_t h, AxlGfxPixel color): Record axl_gfx_draw_rect.

int axl_gfx_dl_draw_polyline(AxlGfxDisplayList *dl, const AxlGfxPoint *points, size_t count, AxlGfxPixel color)

Record axl_gfx_draw_polyline. Copies count points.

AXL_ERR if points is NULL or count < 2 (matching axl_gfx_draw_polyline).

Parameters:

dl – target display list
points – [in] copied into the list
count – number of points (>= 2)
color – line color

int axl_gfx_dl_blit(AxlGfxDisplayList *dl, const AxlGfxPixel *buffer, uint32_t x, uint32_t y, uint32_t w, uint32_t h)

Record axl_gfx_blit. Copies w * h pixels from buffer.

AXL_ERR if buffer is NULL or w / h is 0.

Parameters:

dl – target display list
buffer – [in] copied into the list
x – destination x (top-left)
y – destination y (top-left)
w – source width in pixels
h – source height in pixels

int axl_gfx_dl_clear(AxlGfxDisplayList *dl, AxlGfxPixel color)

Record a clear of the active draw target to color.

On replay this clears whatever target is active: an off-screen buffer via axl_gfx_buffer_clear, or the full screen extent when rendering to the screen.

int axl_gfx_dl_push_clip(AxlGfxDisplayList *dl, AxlGfxClip rect): Record axl_gfx_push_clip.

int axl_gfx_dl_pop_clip(AxlGfxDisplayList *dl): Record axl_gfx_pop_clip.

int axl_gfx_dl_fill_path(AxlGfxDisplayList *dl, const AxlGfxPath *path, AxlGfxPixel color)

Record axl_gfx_fill_path. Borrows path (caller keeps it alive until the last replay / free).

AXL_ERR if path is NULL.

Parameters:

dl – target display list
path – borrowed (caller-owned)
color – fill color

int axl_gfx_dl_stroke_path(AxlGfxDisplayList *dl, const AxlGfxPath *path, AxlGfxPixel color, const AxlGfxStrokeStyle *style)

Record axl_gfx_stroke_path_ex. Borrows path; copies style by value plus an owned copy of its dash array (if any).

AXL_ERR if path or style is NULL, or on allocation failure.

Parameters:

dl – target display list
path – borrowed (caller-owned)
color – stroke color
style – [in] copied (dashes deep-copied)

int axl_gfx_dl_fill_rounded_rect(AxlGfxDisplayList *dl, int32_t x, int32_t y, int32_t w, int32_t h, float radius, AxlGfxPixel color): Record axl_gfx_fill_rounded_rect.

int axl_gfx_dl_draw_text(AxlGfxDisplayList *dl, const AxlFont *font, uint32_t x, uint32_t y, const char *text, AxlGfxPixel color, uint32_t scale)

Record axl_gfx_draw_text (bitmap font). Borrows font; copies text.

AXL_ERR if font or text is NULL.

Parameters:

dl – target display list
font – borrowed (caller-owned)
x – pen x (top-left of the text)
y – pen y (top-left of the text)
text – [in] copied into the list
color – text color
scale – integer pixel scale (1 = native)

int axl_gfx_dl_draw_text_ttf(AxlGfxDisplayList *dl, AxlTtf *ttf, int32_t x, int32_t y, const char *text, float px_size, AxlGfxPixel color)

Record axl_ttf_draw (vector text). Borrows ttf; copies text. (x, y) is the baseline origin, as in axl_ttf_draw.

AXL_ERR if ttf or text is NULL.

Parameters:

dl – target display list
ttf – borrowed (caller-owned)
x – baseline origin x
y – baseline origin y
text – [in] copied into the list
px_size – text size in pixels (em height)
color – text color

int axl_gfx_dl_fill_rect_gradient(AxlGfxDisplayList *dl, int32_t x, int32_t y, int32_t w, int32_t h, const AxlGfxGradient *g)

Record axl_gfx_fill_rect_gradient. Borrows g.

AXL_ERR if dl or g is NULL.

Parameters:

dl – target display list
x – rect x (top-left)
y – rect y (top-left)
w – rect width
h – rect height
g – borrowed (caller-owned)

int axl_gfx_dl_fill_path_gradient(AxlGfxDisplayList *dl, const AxlGfxPath *path, const AxlGfxGradient *g)

Record axl_gfx_fill_path_gradient. Borrows path and g.

AXL_ERR if dl, path, or g is NULL.

Parameters:

dl – target display list
path – borrowed (caller-owned)
g – borrowed (caller-owned)

int axl_gfx_dl_fill_rounded_rect_gradient(AxlGfxDisplayList *dl, int32_t x, int32_t y, int32_t w, int32_t h, float radius, const AxlGfxGradient *g)

Record axl_gfx_fill_rounded_rect_gradient. Borrows g.

AXL_ERR if dl or g is NULL.

Parameters:

dl – target display list
x – rect x (top-left)
y – rect y (top-left)
w – rect width
h – rect height
radius – corner radius in pixels
g – borrowed (caller-owned)

int axl_gfx_dl_translate(AxlGfxDisplayList *dl, double tx, double ty): Record axl_gfx_translate.

int axl_gfx_dl_scale(AxlGfxDisplayList *dl, double sx, double sy): Record axl_gfx_scale.

int axl_gfx_dl_rotate(AxlGfxDisplayList *dl, double radians): Record axl_gfx_rotate (radians).

int axl_gfx_dl_skew(AxlGfxDisplayList *dl, double sx, double sy): Record axl_gfx_skew.

int axl_gfx_dl_push_transform(AxlGfxDisplayList *dl): Record axl_gfx_push_transform.

int axl_gfx_dl_pop_transform(AxlGfxDisplayList *dl): Record axl_gfx_pop_transform.

int axl_gfx_dl_reset_transform(AxlGfxDisplayList *dl): Record axl_gfx_reset_transform.

int axl_gfx_display_list_replay(const AxlGfxDisplayList *dl)

Replay every recorded op against the active draw target, in order, by invoking the corresponding immediate-mode primitive.

Replays the whole list even if an individual op fails (e.g. GOP unavailable on a screen target).

Parameters:

dl – [in] list to replay

Returns:

AXL_OK if dl is non-NULL and every op succeeded; AXL_ERR if dl is NULL or any op’s primitive reported failure.

int axl_gfx_display_list_dump(const AxlGfxDisplayList *dl, AxlStream *out)

Write a human-readable, line-per-op textual trace of dl to out.

Each recorded op produces exactly one \n-terminated line of the form <index>: <op-name> <field>=<value> ..., in record order. The format is for debugging / golden-trace tests, not a round-trippable serialization (there is no loader) — it does not emit borrowed-handle contents (a path’s vertices, a gradient’s stops, a font’s glyphs), only that the op references one.

Conventions:

colors print as #RRGGBBAA (8 hex digits, upper-case);
floats (width, radius, px, transform args) print with 3 decimal places;
text strings print double-quoted with \\, \", \n, \r, and \t backslash-escaped so each op stays on one line.

An empty list writes nothing and returns AXL_OK.

Parameters:

dl – [in] list to dump
out – [in] destination stream

Returns:

AXL_OK on success. AXL_ERR if dl or out is NULL, or a write to out fails.

struct AxlGfxOp

#include <axl-gfx-display-list.h>

One recorded draw operation. kind selects the active union member. All pointers reachable from an op are owned by the display list and stay valid until axl_gfx_display_list_clear / _free — EXCEPT the borrowed handle fields (fill_path.path, stroke_path.path, text.font, text_ttf.ttf), which the caller owns and must keep alive. Returned by axl_gfx_display_list_op_at for read-only introspection; do not mutate or free its fields.

Public Members

AxlGfxOpKind kind: which primitive this op records

uint32_t x

uint32_t y

uint32_t w

uint32_t h

AxlGfxPixel color

struct AxlGfxOp rect_u: FILL_RECT / DRAW_RECT — unsigned-coordinate rectangle.

int32_t x

int32_t y: baseline origin

int32_t w

int32_t h

struct AxlGfxOp rect_i: FILL_RECT_I — signed-coordinate rectangle.

int32_t x0

int32_t y0

int32_t x1

int32_t y1

struct AxlGfxOp line: DRAW_LINE — segment endpoints (inclusive).

AxlGfxPoint *points: owned (freed with the list)

size_t count

struct AxlGfxOp polyline: DRAW_POLYLINE — owned copy of the point array.

AxlGfxPixel *pixels: owned (freed with the list), w*h pixels

struct AxlGfxOp blit: BLIT — owned copy of the source pixels.

struct AxlGfxOp clear: CLEAR — fill the active target with this color.

AxlGfxClip rect

struct AxlGfxOp push_clip: PUSH_CLIP — clip rectangle to intersect onto the stack.

const AxlGfxPath *path: borrowed (caller-owned)

struct AxlGfxOp fill_path: FILL_PATH — borrowed path + fill color.

AxlGfxStrokeStyle style: style.dashes is owned by the list

struct AxlGfxOp stroke_path: STROKE_PATH — borrowed path + color + style (with an owned copy of the style’s dash array, if any).

float radius

struct AxlGfxOp rounded_rect: FILL_ROUNDED_RECT — signed rect + corner radius.

const AxlFont *font: borrowed (caller-owned)

char *text: owned NUL-terminated copy

uint32_t scale

struct AxlGfxOp text: DRAW_TEXT — bitmap-font text (owned string, borrowed font).

AxlTtf *ttf: borrowed (caller-owned)

float px_size

struct AxlGfxOp text_ttf: DRAW_TEXT_TTF — vector text (owned string, borrowed font).

const AxlGfxGradient *g: borrowed (caller-owned)

struct AxlGfxOp rect_gradient: FILL_RECT_GRADIENT — signed rect filled with a gradient.

struct AxlGfxOp path_gradient: FILL_PATH_GRADIENT — borrowed path filled with a gradient.

struct AxlGfxOp rounded_rect_gradient: FILL_ROUNDED_RECT_GRADIENT — signed rounded rect + gradient.

double tx

double ty

struct AxlGfxOp translate: TRANSLATE — append a translation to the active transform.

double sx

double sy

struct AxlGfxOp scale: SCALE — append a non-uniform scale.

double radians

struct AxlGfxOp rotate: ROTATE — append a rotation (radians).

struct AxlGfxOp skew: SKEW — append a 2D shear.

union AxlGfxOp u