Token-stream driver + public lifecycle API for the reflow engine. More...

#include <stddef.h>
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_err.h"
#include "ra8_stbtt_guard.h"
#include "reflow.h"
#include "reflow_internal.h"
#include "reflow_layout_internal.h"
#include "stb_truetype.h"

Include dependency graph for reflow_layout_driver.c:

Functions
static ra8_err_t	internal_layout_tokens (reflow_t engine, const stbtt_fontinfo font)
	Run one pass over the token stream populating engine->glyphs[] and engine->pages[].
ra8_err_t	reflow_run_layout (reflow_t *engine)
	Run the line-break + page-break pass over engine->tokens[].
ra8_err_t	reflow_init (uint16_t viewport_w, uint16_t viewport_h, const uint8_t font_data, size_t font_len, uint16_t font_px, uint32_t body_color, uint32_t link_color, reflow_t out_engine)
	Initialise a reflow engine for a given viewport / font.
ra8_err_t	reflow_close (reflow_t *engine)
	Release a previously initialized engine.
ra8_err_t	reflow_set_image_loader (reflow_t engine, reflow_image_loader_fn loader, void ctx, ra8_img_arena_t *arena)
	Bind an <img> byte loader + decode arena to enable image rendering.
ra8_err_t	reflow_set_css_loader (reflow_t engine, reflow_css_loader_fn loader, void ctx)
	Bind the external-stylesheet loader for <link rel="stylesheet">.
ra8_err_t	reflow_layout_chapter (reflow_t engine, const uint8_t xhtml_buf, size_t xhtml_len, uint32_t *out_total_pages)
	Parse + lay out one chapter of XHTML.
ra8_err_t	reflow_get_page_count (const reflow_t engine, uint32_t out_count)
	Report the laid-out page count.
ra8_err_t	reflow_set_font_size (reflow_t *engine, uint16_t new_font_px)
	Change the body font size and re-flow the cached chapter.
ra8_err_t	reflow_bind_font (reflow_t engine, const uint8_t font_data, size_t font_len)
	Implementation of reflow_bind_font() – validate then swap.
ra8_err_t	reflow_register_face (reflow_t engine, uint8_t css_face_idx, const uint8_t blob, size_t len)
	Implementation of reflow_register_face() – validate then append.

Detailed Description

Token-stream driver + public lifecycle API for the reflow engine.

Splits the outer layout driver and the public entry points out of reflow_layout.c so each translation unit stays under the project file-size cap. The driver (internal_layout_tokens) walks the parsed token stream once, dispatching <table> ranges to priv_reflow_layout_table and every other token to priv_reflow_layout_apply_token, then flushes a final page and builds the tappable link rectangles.

The public API covers engine lifecycle (reflow_init, reflow_close), loader binding (image / CSS), chapter dispatch (reflow_layout_chapter, reflow_set_font_size), font (re)binding, and face registration.

[Ring 4 / Reflow] {World: NS}

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

Since: 0.1.0

Definition in file reflow_layout_driver.c.

Function Documentation

◆ internal_layout_tokens()

ra8_err_t internal_layout_tokens	(	reflow_t *	engine,
		const stbtt_fontinfo *	font )

static

Run one pass over the token stream populating engine->glyphs[] and engine->pages[].

See implementation.

Parameters

[in]	engine	See implementation.
[in]	font	See implementation.

Returns: Result code.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 54 of file reflow_layout_driver.c.

References reflow_t::font_px, reflow_t::glyph_count, reflow_t::image_box_count, k_ra8_err_no_mem, k_ra8_ok, k_reflow_align_left, k_reflow_margin_px, k_reflow_style_normal, k_reflow_tag_table, k_reflow_tok_block_start, reflow_token_t::kind, priv_cursor_t::page_first_glyph, priv_cursor_t::page_first_image, priv_reflow_layout_apply_token(), priv_reflow_layout_finish_page(), priv_reflow_layout_line_height(), priv_reflow_layout_table(), reflow_token_t::tag, and reflow_t::tokens.

Referenced by reflow_run_layout().

◆ reflow_bind_font()

ra8_err_t reflow_bind_font	(	reflow_t *	engine,
		const uint8_t *	font_data,
		size_t	font_len )

nodiscard

Implementation of reflow_bind_font() – validate then swap.

Bind an EPUB-embedded typeface as the engine's active face (#109).

Definition at line 301 of file reflow_layout_driver.c.

References reflow_t::font_data, reflow_t::font_len, reflow_t::in_use, k_ra8_err_invalid_size, k_ra8_err_not_initialized, k_ra8_err_not_supported, k_ra8_err_null_ptr, k_ra8_ok, k_reflow_min_font_bytes, priv_reflow_internal_xhtml_invalid(), ra8_stbtt_sfnt_dir_in_bounds(), reflow_layout_chapter(), reflow_t::xhtml_buf, and reflow_t::xhtml_len.

◆ reflow_close()

ra8_err_t reflow_close ( reflow_t * engine )

nodiscard

Release a previously initialized engine.

Parameters

[in,out] engine Engine returned by reflow_init().

Returns: ra8_err_t

Return values

k_ra8_ok	Closed.
k_ra8_err_null_ptr	engine is NULL.
k_ra8_err_not_initialized	engine->in_use == 0.

Precondition: engine non-NULL.; engine->in_use == 1.

Postcondition: engine->in_use == 0.; engine->page_count == 0.

Since: 0.1.0

Definition at line 184 of file reflow_layout_driver.c.

◆ reflow_get_page_count()

ra8_err_t reflow_get_page_count	(	const reflow_t *	engine,
		uint32_t *	out_count )

nodiscard

Report the laid-out page count.

Parameters

[in]	engine	Laid-out engine.
[out]	out_count	Page count (0 if no chapter laid out yet).

Returns: ra8_err_t

Return values

k_ra8_ok	Reported.
k_ra8_err_null_ptr	Any pointer is NULL.
k_ra8_err_not_initialized	engine->in_use == 0.

Since: 0.1.0

Definition at line 267 of file reflow_layout_driver.c.

◆ reflow_init()

ra8_err_t reflow_init	(	uint16_t	viewport_w,
		uint16_t	viewport_h,
		const uint8_t *	font_data,
		size_t	font_len,
		uint16_t	font_px,
		uint32_t	body_color,
		uint32_t	link_color,
		reflow_t *	out_engine )

nodiscard

Initialise a reflow engine for a given viewport / font.

Records the viewport size, font handle and colour palette into the engine handle and clears the cached chapter / glyph / page state.

Parameters

[in]	viewport_w	Viewport width, pixels (1..4096).
[in]	viewport_h	Viewport height, pixels (1..4096).
[in]	font_data	TTF blob; must outlive the engine.
[in]	font_len	Length of font_data, bytes (>= 16).
[in]	font_px	Initial font size, pixels (k_reflow_min_font_px .. k_reflow_max_font_px).
[in]	body_color	Body text colour (0xRRGGBB).
[in]	link_color	Anchor colour (0xRRGGBB).
[out]	out_engine	Engine handle to populate.

Returns: ra8_err_t

Return values

k_ra8_ok	Initialized.
k_ra8_err_null_ptr	font_data or out_engine is NULL.
k_ra8_err_invalid_arg	Viewport or font size out of range.
k_ra8_err_invalid_size	font_len too small.

Precondition: font_data non-NULL, out_engine non-NULL.; Viewport and font size in their documented ranges.

Postcondition: On success, out_engine->in_use == 1 and out_engine->page_count == 0.; On failure, *out_engine is zero-initialized.

Note: Not thread-safe. Single-threaded init context.

See also: reflow_close()

Since: 0.1.0

Definition at line 149 of file reflow_layout_driver.c.

◆ reflow_layout_chapter()

ra8_err_t reflow_layout_chapter	(	reflow_t *	engine,
		const uint8_t *	xhtml_buf,
		size_t	xhtml_len,
		uint32_t *	out_total_pages )

nodiscard

Parse + lay out one chapter of XHTML.

Walks the XHTML once with the no-heap streaming tokenizer, emits a token stream, then runs the greedy line-break + page-break engine to produce a flat list of positioned glyphs grouped by page. The engine caches the input buffer so reflow_set_font_size() can re-flow without the caller re-supplying it.

Algorithm summary:

Tokenize the XHTML in a single no-heap forward pass, emitting tokens (block_start / text / break / ...).
For each token, if it is a text run, walk word-by-word.
Measure word_width = sum(stbtt advance per glyph).
If cursor_x + word_width > viewport_w - margins then break to a new line.
If cursor_y + line_height > viewport_h - margins then start a new page.
After all tokens, record page_count.

Parameters

[in,out]	engine	Initialized engine handle.
[in]	xhtml_buf	UTF-8 / ASCII XHTML source bytes.
[in]	xhtml_len	Length of xhtml_buf, bytes (>0).
[out]	out_total_pages	Total page count (>= 1 on success).

Returns: ra8_err_t

Return values

k_ra8_ok	Laid out.
k_ra8_err_null_ptr	Any required pointer is NULL.
k_ra8_err_not_initialized	engine->in_use == 0.
k_ra8_err_invalid_size	xhtml_len == 0.
k_ra8_err_validation_failed	XHTML did not parse.
k_ra8_err_no_mem	Token / glyph / page pool full.

Precondition: engine, xhtml_buf, out_total_pages non-NULL.; engine->in_use == 1.

Postcondition: On success, *out_total_pages == engine->page_count >= 1.

Since: 0.1.0

Definition at line 233 of file reflow_layout_driver.c.

Referenced by reflow_bind_font(), and reflow_set_font_size().

◆ reflow_register_face()

ra8_err_t reflow_register_face	(	reflow_t *	engine,
		uint8_t	css_face_idx,
		const uint8_t *	blob,
		size_t	len )

nodiscard

Implementation of reflow_register_face() – validate then append.

Register one embedded @font-face typeface for per-run selection (#109).

Definition at line 346 of file reflow_layout_driver.c.

References reflow_face_t::blob, reflow_face_t::css_face_idx, reflow_t::face_count, reflow_t::faces, reflow_t::in_use, k_ra8_err_invalid_size, k_ra8_err_no_mem, k_ra8_err_not_initialized, k_ra8_err_not_supported, k_ra8_err_null_ptr, k_ra8_ok, k_reflow_max_faces, k_reflow_min_font_bytes, reflow_face_t::len, and ra8_stbtt_sfnt_dir_in_bounds().

◆ reflow_run_layout()

ra8_err_t reflow_run_layout ( reflow_t * engine )

nodiscard

Run the line-break + page-break pass over engine->tokens[].

Internal helper. Consumes the token stream populated by reflow_parse_xhtml() and writes positioned glyphs into engine->glyphs[] plus page index ranges into engine->pages[].

Parameters

[in,out] engine Engine in in_use == 1 state with a populated token stream.

Returns: ra8_err_t

Return values

k_ra8_ok	Layout complete.
k_ra8_err_no_mem	Glyph or page pool full.

Since: 0.1.0

Definition at line 105 of file reflow_layout_driver.c.

Referenced by reflow_layout_chapter().

◆ reflow_set_css_loader()

ra8_err_t reflow_set_css_loader	(	reflow_t *	engine,
		reflow_css_loader_fn	loader,
		void *	ctx )

nodiscard

Bind the external-stylesheet loader for <link rel="stylesheet">.

Mirrors reflow_set_image_loader(). When bound, reflow_layout_chapter() resolves each <link rel="stylesheet" href> in the chapter via loader and parses the returned CSS into the chapter sheet in document order (so a later inline <style> / style= overrides it). NULL loader disables the feature (chapters parse only their inline CSS, exactly as before).

Parameters

[in,out]	engine	Engine to bind.
[in]	loader	Stylesheet byte loader, or NULL to disable.
[in]	ctx	Opaque context handed back to `loader`.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Binding recorded.
k_ra8_err_null_ptr	`engine` is NULL.
k_ra8_err_not_initialized	engine->in_use == 0.

Precondition: engine is non-NULL and initialized.

Postcondition: On success the engine uses (loader, ctx) for <link> stylesheets.; Binding takes effect on the next reflow_layout_chapter().

Note: Not thread-safe; bind before laying out.

Since: 0.1.0

Definition at line 220 of file reflow_layout_driver.c.

References reflow_t::css_loader, reflow_t::css_loader_ctx, reflow_t::in_use, k_ra8_err_not_initialized, k_ra8_err_null_ptr, and k_ra8_ok.

◆ reflow_set_font_size()

ra8_err_t reflow_set_font_size	(	reflow_t *	engine,
		uint16_t	new_font_px )

nodiscard

Change the body font size and re-flow the cached chapter.

Re-runs the line-break + page-break engine against the most recent chapter handed to reflow_layout_chapter(). Glyph and page state are rebuilt from scratch; the previous page count and page-glyph ranges are invalidated.

Parameters

[in,out]	engine	Initialized + laid-out engine.
[in]	new_font_px	New body font size, pixels (k_reflow_min_font_px .. k_reflow_max_font_px).

Returns: ra8_err_t

Return values

k_ra8_ok	Re-flowed.
k_ra8_err_null_ptr	engine is NULL.
k_ra8_err_not_initialized	engine->in_use == 0.
k_ra8_err_invalid_state	No chapter cached yet.
k_ra8_err_invalid_arg	new_font_px out of range.

Since: 0.1.0

Definition at line 279 of file reflow_layout_driver.c.

◆ reflow_set_image_loader()

ra8_err_t reflow_set_image_loader	(	reflow_t *	engine,
		reflow_image_loader_fn	loader,
		void *	ctx,
		ra8_img_arena_t *	arena )

nodiscard

Bind an <img> byte loader + decode arena to enable image rendering.

Without this binding (the default), <img> elements reserve a small placeholder advance and draw nothing – the historical v1 behaviour, kept so image-free content lays out byte-identically. Once a loader + arena are bound, the layout pass resolves each <img src> to its intrinsic size, reserves a scaled block (text flows below), and the render pass decodes + blits the image on demand. Pass loader == NULL or arena == NULL to disable again.

Parameters

[in,out]	engine	Initialized engine handle.
[in]	loader	Resolves an href to encoded image bytes (NULL = off).
[in]	ctx	Opaque context handed back to `loader`.
[in]	arena	Caller-owned decode scratch (NULL = off); sized for the largest image (a few KiB SRAM .. a few MiB SDRAM).

Returns: ra8_err_t

Return values

k_ra8_ok	Binding recorded.
k_ra8_err_null_ptr	`engine` is NULL.
k_ra8_err_not_initialized	engine->in_use == 0.

Precondition: engine is non-NULL and initialized.; If non-NULL, arena->base addresses arena->cap writable bytes.

Postcondition: On success the engine uses (loader, ctx, arena) for <img>.; Binding takes effect on the next reflow_layout_chapter() / re-flow.

Note: Not thread-safe; bind before laying out.

Since: 0.1.0

Definition at line 203 of file reflow_layout_driver.c.

References reflow_t::img_arena, reflow_t::img_loader, reflow_t::img_loader_ctx, reflow_t::in_use, k_ra8_err_not_initialized, k_ra8_err_null_ptr, and k_ra8_ok.

Referenced by er_reflow_relayout().

Functions

Detailed Description

Function Documentation

◆ internal_layout_tokens()

◆ reflow_bind_font()

◆ reflow_close()

◆ reflow_get_page_count()

◆ reflow_init()

◆ reflow_layout_chapter()

◆ reflow_register_face()

◆ reflow_run_layout()

◆ reflow_set_css_loader()

◆ reflow_set_font_size()

◆ reflow_set_image_loader()