ra8_glyph_atlas.c File Reference

Fixed-budget glyph cache – implementation (Layer 3, #147). More...

#include "ra8_glyph_atlas.h"
#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_keycache.h"

Include dependency graph for ra8_glyph_atlas.c:

Go to the source code of this file.

Functions
static ra8_err_t	internal_glyph_render (void *ctx, const void *key, uint8_t *cell, uint32_t cell_bytes, void *user)
	Render trampoline: adapt ra8_glyph_render_fn to the keycache seam.
ra8_err_t	ra8_glyph_atlas_init (ra8_glyph_atlas_t *atlas, const ra8_glyph_atlas_cfg_t *cfg)
	Initialise a glyph atlas over caller-supplied storage.
ra8_err_t	ra8_glyph_atlas_get (ra8_glyph_atlas_t *atlas, const ra8_glyph_key_t *key, ra8_glyph_t *out_glyph)
	Get (and pin) the rendered glyph for key.
ra8_err_t	ra8_glyph_atlas_put (ra8_glyph_atlas_t *atlas, const uint8_t *bitmap)
	Release one pin on a glyph previously returned by ra8_glyph_atlas_get.
ra8_err_t	ra8_glyph_atlas_stats (const ra8_glyph_atlas_t *atlas, uint32_t *out_hits, uint32_t *out_misses, uint32_t *out_evictions)
	Report the atlas hit / miss / eviction counters.

Variables
static const char *const	s_tag = "ra8_glyph_atlas"
	Module log tag.

Detailed Description

Fixed-budget glyph cache – implementation (Layer 3, #147).

Tag

[Ring 2 / Core] {World: NS}

A thin typed facade over ::ra8_keycache: the glyph key is the cache key, the glyph bitmap is the cell payload, and the rendered width/height ride in the per-cell ra8_glyph_dims_t user descriptor. A small render trampoline adapts the public ra8_glyph_render_fn (out_w/out_h) to the keycache's render-on-miss seam (user descriptor) so the production rasteriser and the test stubs are unchanged. All cache mechanics – the single LRU list, pinned-cell skip, hash chaining, eviction – live in ::ra8_keycache.

Copyright

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

Definition in file ra8_glyph_atlas.c.

Function Documentation

internal_glyph_render()

ra8_err_t internal_glyph_render ( void * ctx, const void * key, uint8_t * cell, uint32_t cell_bytes, void * user )

static

Render trampoline: adapt ra8_glyph_render_fn to the keycache seam.

Casts the keycache render context back to the owning atlas, calls the caller's glyph renderer for the cell, and on success records the rendered width/height into the cell's ra8_glyph_dims_t descriptor.

Parameters

[in]	ctx	The owning ra8_glyph_atlas_t (keycache render_ctx).
[in]	key	The ra8_glyph_key_t to render.
[out]	cell	Destination bitmap buffer (cell_bytes writable).
[in]	cell_bytes	Cell capacity in bytes.
[out]	user	The cell's ra8_glyph_dims_t descriptor.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	The glyph was rendered and the descriptor recorded.
k_ra8_err_*	The caller's renderer error (descriptor left untouched).

Precondition

ctx and user are non-NULL (the keycache guarantees both here).

key points at a valid ra8_glyph_key_t.

Postcondition

On success *user holds the rendered glyph dimensions.

On failure the descriptor is not written.

Note

Not thread-safe.

Since

0.1.0

Definition at line 62 of file ra8_glyph_atlas.c.

References ra8_glyph_dims_t::h, k_ra8_ok, ra8_glyph_atlas_t::render, ra8_glyph_atlas_t::render_ctx, and ra8_glyph_dims_t::w.

Referenced by ra8_glyph_atlas_init().

ra8_glyph_atlas_get()

ra8_err_t ra8_glyph_atlas_get ( ra8_glyph_atlas_t * atlas, const ra8_glyph_key_t * key, ra8_glyph_t * out_glyph )

nodiscard

Get (and pin) the rendered glyph for key.

On a hit the cell is moved to the MRU and pinned. On a miss an unpinned LRU victim is evicted, the glyph is rendered into the cell, inserted, and pinned. The returned bitmap stays valid until ra8_glyph_atlas_put.

Parameters

[in]	atlas	Initialised atlas.
[in]	key	Glyph to fetch.
[out]	out_glyph	Receives the pinned glyph view.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Glyph resident and pinned; *out_glyph set.
k_ra8_err_null_ptr	atlas, key, or out_glyph was NULL.
k_ra8_err_no_mem	Every cell is pinned (cannot evict for the miss).
k_ra8_err_*	The renderer failed (returned verbatim).

Precondition

atlas was populated by ra8_glyph_atlas_init.

The caller will ra8_glyph_atlas_put the returned glyph.

Postcondition

On success the cell's pin count increased by one.

On any non-ok return no new pin is held.

Note

Not thread-safe.

Since

0.1.0

Definition at line 103 of file ra8_glyph_atlas.c.

References ra8_keycache_view_t::data, ra8_glyph_dims_t::h, k_ra8_ok, ra8_glyph_atlas_t::kc, RA8_CHECK_NULL_PTR, ra8_keycache_get(), s_tag, ra8_keycache_view_t::user, and ra8_glyph_dims_t::w.

Referenced by internal_glyph_render_cached(), and internal_submit_access().

ra8_glyph_atlas_init()

ra8_err_t ra8_glyph_atlas_init ( ra8_glyph_atlas_t * atlas, const ra8_glyph_atlas_cfg_t * cfg )

nodiscard

Initialise a glyph atlas over caller-supplied storage.

Parameters

[out]	atlas	Atlas state to populate (zero-initialised by the caller).
[in]	cfg	Storage + renderer configuration.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Atlas ready; all cells cold.
k_ra8_err_null_ptr	atlas, cfg, or a required cfg pointer NULL.
k_ra8_err_invalid_size	cell_count, cell_bytes, or bucket_count 0.

Precondition

cfg's arrays cover their sizes and out-live the atlas.

cfg->render is non-NULL.

Postcondition

On success the atlas is empty and buckets are cleared.

On any non-ok return atlas is left unbound.

Note

Not thread-safe.

Since

0.1.0

Definition at line 78 of file ra8_glyph_atlas.c.

References ra8_glyph_atlas_cfg_t::bucket_count, ra8_keycache_cfg_t::bucket_count, ra8_glyph_atlas_cfg_t::buckets, ra8_keycache_cfg_t::buckets, ra8_glyph_atlas_cfg_t::cell_bytes, ra8_keycache_cfg_t::cell_bytes, ra8_glyph_atlas_cfg_t::cell_count, ra8_keycache_cfg_t::cell_count, ra8_glyph_atlas_cfg_t::cell_mem, ra8_keycache_cfg_t::cell_mem, ra8_glyph_atlas_cfg_t::dims, internal_glyph_render(), ra8_glyph_atlas_t::kc, ra8_keycache_cfg_t::key_bytes, ra8_keycache_cfg_t::key_mem, ra8_glyph_atlas_cfg_t::keys, memset(), ra8_glyph_atlas_cfg_t::meta, ra8_keycache_cfg_t::meta, RA8_CHECK_NULL_PTR, ra8_keycache_init(), ra8_glyph_atlas_cfg_t::render, ra8_glyph_atlas_t::render, ra8_keycache_cfg_t::render, ra8_glyph_atlas_cfg_t::render_ctx, ra8_glyph_atlas_t::render_ctx, ra8_keycache_cfg_t::render_ctx, s_tag, ra8_keycache_cfg_t::user_bytes, and ra8_keycache_cfg_t::user_mem.

Referenced by internal_run_budget(), and reflow_set_glyph_atlas().

ra8_glyph_atlas_put()

ra8_err_t ra8_glyph_atlas_put ( ra8_glyph_atlas_t * atlas, const uint8_t * bitmap )

nodiscard

Release one pin on a glyph previously returned by ra8_glyph_atlas_get.

Parameters

[in]	atlas	Initialised atlas.
[in]	bitmap	The bitmap pointer from a returned ra8_glyph_t.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Pin released.
k_ra8_err_null_ptr	atlas or bitmap was NULL.
k_ra8_err_invalid_arg	bitmap is not a cell of this atlas, or the cell was not pinned.

Precondition

bitmap came from ra8_glyph_atlas_get on this atlas and is still pinned.

atlas was populated by ra8_glyph_atlas_init.

Postcondition

On success the cell's pin count decreased by one.

On any non-ok return no state changed.

Note

Not thread-safe.

Since

0.1.0

Definition at line 118 of file ra8_glyph_atlas.c.

References ra8_glyph_atlas_t::kc, RA8_CHECK_NULL_PTR, ra8_keycache_put(), and s_tag.

Referenced by internal_glyph_render_cached(), and internal_submit_access().

ra8_glyph_atlas_stats()

ra8_err_t ra8_glyph_atlas_stats ( const ra8_glyph_atlas_t * atlas, uint32_t * out_hits, uint32_t * out_misses, uint32_t * out_evictions )

nodiscard

Report the atlas hit / miss / eviction counters.

Parameters

[in]	atlas	Initialised atlas.
[out]	out_hits	Hits so far (may be NULL).
[out]	out_misses	Misses so far (may be NULL).
[out]	out_evictions	Evictions so far (may be NULL).

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Counters reported.
k_ra8_err_null_ptr	atlas was NULL.
k_ra8_err_invalid_state	The atlas was not initialised.

Precondition

atlas was populated by ra8_glyph_atlas_init.

At least one output pointer is non-NULL to be useful.

Postcondition

On success the requested counters are written.

No atlas state is mutated.

Note

Thread-safe with respect to a quiescent atlas (pure read).

Since

0.1.0

Definition at line 125 of file ra8_glyph_atlas.c.

References ra8_keycache_cfg_t::cell_mem, ra8_keycache_t::cfg, k_ra8_err_invalid_state, ra8_glyph_atlas_t::kc, RA8_CHECK_NULL_PTR, ra8_keycache_stats(), and s_tag.

Referenced by internal_run_budget().

Variable Documentation

s_tag

const char* const s_tag = "ra8_glyph_atlas"

static

Module log tag.

Definition at line 33 of file ra8_glyph_atlas.c.