ra8_stbtt_alloc.h File Reference

Heap-free scratch allocator for stb_truetype (glyph rasterise). More...

#include <stddef.h>
#include <stdint.h>

Include dependency graph for ra8_stbtt_alloc.h:

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

Go to the source code of this file.

Functions
void *	ra8_stbtt_malloc (size_t n)
	Allocate n bytes of glyph scratch from the static arena.
void	ra8_stbtt_free (void *p)
	Release a block previously returned by ra8_stbtt_malloc().
size_t	ra8_stbtt_alloc_high_water (void)
	Worst-case arena high-water mark observed since boot, in bytes.

Detailed Description

Heap-free scratch allocator for stb_truetype (glyph rasterise).

stb_truetype allocates short-lived scratch (glyph vertices, rasteriser edge/point lists) through STBTT_malloc / STBTT_free for every glyph – on both the one-shot stbtt_GetCodepointBitmap() path and the two-step stbtt_GetCodepointBitmapBox() + stbtt_MakeCodepointBitmap() path. The firmware has no heap (_sbrk traps after init), so the build redirects those macros to the functions below (see the CMake STBTT_malloc / STBTT_free compile definitions on the stb_truetype_impl.c source).

The allocator is a fixed-capacity bump arena with reference-counted auto-reset: each successful ra8_stbtt_malloc() bumps an offset and a live-block count; each ra8_stbtt_free() decrements the count and, when it reaches zero, rewinds the offset to the base. Every top-level stb_truetype call frees all of its scratch before returning, so the arena fully drains after each glyph – no caller cooperation, robust to any free order (stb frees composite-glyph buffers out of LIFO order), and immune to fragmentation. On exhaustion ra8_stbtt_malloc() returns NULL; stb_truetype tolerates this and the offending glyph is skipped rather than corrupting memory.

NASA Power-of-10 Rule 3 (no dynamic allocation after init): the backing store is a single file-scope array.

[Ring 4 / Reflow] {World: NS}

Copyright

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

Since

0.1.0

Definition in file ra8_stbtt_alloc.h.

Function Documentation

ra8_stbtt_alloc_high_water()

size_t ra8_stbtt_alloc_high_water

(

void

)

Worst-case arena high-water mark observed since boot, in bytes.

Diagnostic hook for sizing/regression: lets a host test or an on-target probe confirm the configured capacity has headroom.

Returns

Peak number of simultaneously-bumped bytes since boot.

Return values

0	No allocation has been made yet.

Precondition

None beyond a consistent arena state.

Called single-threaded from the rasteriser.

Postcondition

The arena state is left unchanged (pure read).

The returned value never decreases across calls.

Note

Not thread-safe: rasterisation is single-threaded.

Since

0.1.0

Definition at line 83 of file ra8_stbtt_alloc.c.

References s_high_water.

ra8_stbtt_free()

void ra8_stbtt_free

(

void *

p

)

Release a block previously returned by ra8_stbtt_malloc().

Decrements the live-block count; the bump offset is not tracked per block. When the count reaches zero the arena is fully drained, so the offset rewinds to the base. A nullptr argument is ignored.

Parameters

[in]

p

Pointer to release; nullptr is ignored.

Returns

None.

Precondition

p was returned by ra8_stbtt_malloc(), or is nullptr.

Called single-threaded from the rasteriser.

Postcondition

The live-block count is decremented (never below zero).

When the live-block count reaches zero the arena offset rewinds to the base (full auto-reset).

Note

Not thread-safe: rasterisation is single-threaded.

Since

0.1.0

Definition at line 70 of file ra8_stbtt_alloc.c.

References s_live, and s_offset.

ra8_stbtt_malloc()

void * ra8_stbtt_malloc

(

size_t

n

)

Allocate n bytes of glyph scratch from the static arena.

Bumps the arena offset by n rounded up to the 16-byte alignment and increments the live-block count. Requests larger than the arena, or that do not fit the remaining capacity, fail with nullptr.

Parameters

[in]

n

Byte count requested by stb_truetype.

Returns

16-byte-aligned pointer into the arena, or nullptr if the request does not fit the remaining capacity.

Return values

nullptr

The request exceeds the arena or remaining capacity.

Precondition

The arena is in a consistent state (statically zero-initialised).

Called single-threaded from the rasteriser.

Postcondition

On success the live-block count is incremented and the offset advances by the aligned size.

On failure the arena state is unchanged.

Note

Not thread-safe: rasterisation is single-threaded.

Since

0.1.0

Definition at line 50 of file ra8_stbtt_alloc.c.

References k_ra8_stbtt_align_mask, k_ra8_stbtt_arena_bytes, s_arena, s_high_water, s_live, and s_offset.