Caller-bound bump arena with refcount auto-reset for stb_image. More...

#include "ra8_img_arena.h"
#include <stddef.h>
#include <stdint.h>
#include <string.h>

Include dependency graph for ra8_img_arena.c:

Enumerations
enum	ra8_img_arena_consts_t : uint32_t { k_ra8_img_align = 16U , k_ra8_img_align_mask = 15U }
	Arena alignment knobs (no magic numbers). More...

Functions
void	ra8_img_arena_bind (ra8_img_arena_t *arena)
	Bind `arena` as the active scratch for subsequent decode allocations.
void	ra8_img_arena_unbind (void)
	Unbind the active arena; subsequent allocation hooks fail with nullptr.
void *	ra8_img_arena_malloc (size_t n)
	stb_image STBI_MALLOC hook: bump `n` bytes from the bound arena.
void	ra8_img_arena_free (void *p)
	stb_image STBI_FREE hook: release a block; auto-reset when none live.
void *	ra8_img_arena_realloc_sized (void *p, size_t oldsz, size_t newsz)
	stb_image STBI_REALLOC_SIZED hook: fresh-allocate, copy, free old.

Variables
static ra8_img_arena_t *	s_arena = nullptr
	Currently-bound arena, or nullptr when no decode is in flight.

Detailed Description

Caller-bound bump arena with refcount auto-reset for stb_image.

See ra8_img_arena.h for the rationale. Unlike the stb_truetype arena, the backing store is not a file-scope array: the consumer binds a buffer sized for the image at hand (SRAM for thumbnails, SDRAM for full covers) via ra8_img_arena_bind(), and these hooks bump-allocate out of it. The reference count drives an auto-reset so the arena fully drains after each decode.

[Ring 4 / Reflow] {World: NS}

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

Since: 0.1.0

Definition in file ra8_img_arena.c.

Enumeration Type Documentation

◆ ra8_img_arena_consts_t

enum ra8_img_arena_consts_t : uint32_t

Arena alignment knobs (no magic numbers).

Enumerator
k_ra8_img_align	Allocation alignment, bytes.
k_ra8_img_align_mask	k_ra8_img_align - 1 (round-up mask).

Definition at line 30 of file ra8_img_arena.c.

Function Documentation

◆ ra8_img_arena_bind()

void ra8_img_arena_bind ( ra8_img_arena_t * arena )

Bind arena as the active scratch for subsequent decode allocations.

Records arena in a file-static slot and resets it to empty (offset = 0, live = 0). Every ra8_img_arena_malloc() / _free() / _realloc until the next ra8_img_arena_bind() or ra8_img_arena_unbind() operates on it.

Parameters

[in,out] arena Arena to make active; reset to empty on entry. NULL unbinds (equivalent to ra8_img_arena_unbind()).

Returns: None.

Precondition: arena, if non-NULL, has base pointing at cap writable bytes.; Called single-threaded around one decode (decoding is not re-entrant).

Postcondition: The active arena is arena and, if non-NULL, it is empty.; A subsequent ra8_img_arena_malloc() draws from arena.

Note: Not thread-safe: image decoding is single-threaded.

Since: 0.1.0

Definition at line 38 of file ra8_img_arena.c.

References ra8_img_arena_t::live, ra8_img_arena_t::offset, and s_arena.

Referenced by internal_decode_stb(), internal_probe_page(), internal_transcode_image(), and ra8_img_decode_blit().

◆ ra8_img_arena_free()

void ra8_img_arena_free ( void * p )

stb_image STBI_FREE hook: release a block; auto-reset when none live.

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

Parameters

[in] p Pointer to release; nullptr is ignored.

Returns: None.

Precondition: p was returned by ra8_img_arena_malloc()/_realloc_sized(), or is nullptr.; Called single-threaded from the decoder.

Postcondition: The live-block count is decremented (never below zero).; When the live-block count reaches zero the arena offset rewinds to base.

Note: Not thread-safe: image decoding is single-threaded.

Since: 0.1.0

Definition at line 73 of file ra8_img_arena.c.

References ra8_img_arena_t::live, ra8_img_arena_t::offset, and s_arena.

Referenced by ra8_img_arena_realloc_sized().

◆ ra8_img_arena_malloc()

void * ra8_img_arena_malloc ( size_t n )

stb_image STBI_MALLOC hook: bump n bytes from the bound arena.

Rounds n up to the 16-byte alignment, bumps the bound arena's offset, and increments its live-block count. Fails with nullptr when no arena is bound, when n exceeds the capacity, or when the request does not fit the remaining capacity.

Parameters

[in] n Byte count requested by stb_image.

Returns: 16-byte-aligned pointer into the bound arena, or nullptr.

Return values

nullptr No arena bound, or the request does not fit.

Precondition: Either an arena is bound (then a decode is in progress) or the call fails.; Called single-threaded from the decoder.

Postcondition: On success the live-block count is incremented and the offset advances.; On failure the arena state is unchanged.

Note: Not thread-safe: image decoding is single-threaded.

Since: 0.1.0

Definition at line 52 of file ra8_img_arena.c.

References ra8_img_arena_t::base, ra8_img_arena_t::cap, k_ra8_img_align_mask, ra8_img_arena_t::live, ra8_img_arena_t::offset, and s_arena.

Referenced by ra8_img_arena_realloc_sized().

◆ ra8_img_arena_realloc_sized()

void * ra8_img_arena_realloc_sized	(	void *	p,
		size_t	oldsz,
		size_t	newsz )

stb_image STBI_REALLOC_SIZED hook: fresh-allocate, copy, free old.

A bump arena cannot grow a block in place, so this allocates newsz fresh, copies min(oldsz, newsz) bytes from p, and releases p. The old block's space is not reclaimed until the arena next drains – which is why the caller sizes the arena for the decode's peak, not its net, footprint.

Parameters

[in]	p	Existing block (may be nullptr -> behaves as malloc).
[in]	oldsz	Current size of `p` in bytes (0 if `p` is nullptr).
[in]	newsz	Requested new size in bytes.

Returns: Pointer to newsz bytes with the old contents copied, or nullptr.

Return values

nullptr No arena bound, or the new request does not fit.

Precondition: p was returned by a prior hook call, or is nullptr.; Called single-threaded from the decoder.

Postcondition: On success the first min(oldsz, newsz) bytes match p's old contents.; On failure p remains valid and the arena state is unchanged.

Note: Not thread-safe: image decoding is single-threaded.

Since: 0.1.0

Definition at line 87 of file ra8_img_arena.c.

References memcpy(), ra8_img_arena_free(), and ra8_img_arena_malloc().

◆ ra8_img_arena_unbind()

void ra8_img_arena_unbind ( void )

Unbind the active arena; subsequent allocation hooks fail with nullptr.

Clears the file-static active-arena slot. Used to fence the stb hooks outside a decode so a stray allocation cannot scribble on a stale buffer.

Returns: None.

Precondition: None.; Called single-threaded around one decode.

Postcondition: The active-arena slot is NULL.; A subsequent ra8_img_arena_malloc() returns nullptr until the next bind.

Note: Not thread-safe: image decoding is single-threaded.

Since: 0.1.0

Definition at line 47 of file ra8_img_arena.c.

References s_arena.

Referenced by internal_arena_release(), internal_decode_stb(), internal_encode_source(), internal_probe_page(), and internal_transcode_image().

Variable Documentation

◆ s_arena

ra8_img_arena_t* s_arena = nullptr

static

Currently-bound arena, or nullptr when no decode is in flight.

Definition at line 36 of file ra8_img_arena.c.

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ra8_img_arena_consts_t

Function Documentation

◆ ra8_img_arena_bind()

◆ ra8_img_arena_free()

◆ ra8_img_arena_malloc()

◆ ra8_img_arena_realloc_sized()

◆ ra8_img_arena_unbind()

Variable Documentation

◆ s_arena