LiteHTML-backed reflow engine – reflow public API adapter. More...

#include <cstddef>
#include <cstdint>
#include <cstdio>
#include <cstring>
#include <memory>
#include <string>
#include "ra8_attributes.h"
#include "ra8_err.h"
#include "reflow.h"
#include "litehtml.h"

Include dependency graph for reflow_v2.cpp:

Functions
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_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_render_page (const reflow_t engine, uint32_t page_idx, void framebuffer)
	Render one page into the active ra8_gfx framebuffer.
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_parse_xhtml (reflow_t engine, const uint8_t xhtml_buf, size_t xhtml_len)
	Parse the XHTML buffer into the engine's token stream.
ra8_err_t	reflow_run_layout (reflow_t *engine)
	Run the line-break + page-break pass over engine->tokens[].

Detailed Description

LiteHTML-backed reflow engine – reflow public API adapter.

Tag: [Ring 4 / Reflow] {World: NS}

Drop-in replacement for apps/shared_libs/reflow/src/reflow_*.c. Built only when the consumer selects -DREFLOW_USE_LITEHTML=ON; the default OFF path keeps the v1 hand-rolled engine in place.

Hands the chapter buffer to litehtml::document::createFromString, runs render(viewport_w), then paginates by viewport height.

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

Since: 0.1.0

Definition in file reflow_v2.cpp.

Function Documentation

◆ 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 470 of file reflow_v2.cpp.

References reflow_t::glyph_count, reflow_t::image_box_count, reflow_t::in_use, k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_ok, reflow_t::page_count, reflow_t::text_pool_used, reflow_t::token_count, reflow_t::xhtml_buf, and reflow_t::xhtml_len.

Referenced by er_reflow_relayout().

◆ 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 518 of file reflow_v2.cpp.

References reflow_t::in_use, k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_ok, and reflow_t::page_count.

Referenced by erb_render_all(), and internal_rc_render_all().

◆ 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 437 of file reflow_v2.cpp.

References reflow_t::body_color, reflow_t::font_data, reflow_t::font_len, reflow_t::font_px, reflow_t::in_use, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, k_reflow_max_font_px, k_reflow_min_font_px, reflow_t::link_color, priv_reflow_layout_byte_zero(), reflow_t::viewport_h, and reflow_t::viewport_w.

Referenced by er_reflow_relayout(), internal_pc_engine_init(), main(), and sfr_render_or_halt().

◆ 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 484 of file reflow_v2.cpp.

References reflow_t::in_use, k_ra8_err_invalid_size, k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_ok, reflow_t::page_count, reflow_parse_xhtml(), reflow_run_layout(), reflow_t::xhtml_buf, and reflow_t::xhtml_len.

Referenced by er_reflow_relayout(), erb_render_chapter(), internal_pc_live_layout_or_halt(), main(), and sfr_render_or_halt().

◆ reflow_parse_xhtml()

ra8_err_t reflow_parse_xhtml	(	reflow_t *	engine,
		const uint8_t *	xhtml_buf,
		size_t	xhtml_len )

nodiscard

Parse the XHTML buffer into the engine's token stream.

Internal helper used by reflow_layout_chapter(). Implemented by the no-heap streaming tokenizer in reflow_tokenize.c. Declared here so reflow_layout.c can call it without a forward declaration.

Parameters

[in,out]	engine	Engine whose token / text pools will be populated.
[in]	xhtml_buf	XHTML source bytes.
[in]	xhtml_len	Length of xhtml_buf.

Returns: ra8_err_t

Return values

k_ra8_ok	Tokens emitted.
k_ra8_err_validation_failed	XHTML did not parse.
k_ra8_err_no_mem	Token or text pool full.

Since: 0.1.0

Definition at line 550 of file reflow_v2.cpp.

References reflow_t::in_use, k_ra8_err_invalid_size, k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_ok, reflow_t::link_target_count, priv_reflow_xml_walk(), reflow_t::text_pool_used, reflow_t::token_count, reflow_t::xhtml_buf, and reflow_t::xhtml_len.

Referenced by reflow_layout_chapter().

◆ reflow_render_page()

ra8_err_t reflow_render_page	(	const reflow_t *	engine,
		uint32_t	page_idx,
		void *	framebuffer )

nodiscard

Render one page into the active ra8_gfx framebuffer.

Walks the slice of engine->glyphs[] that belongs to page_idx, rasterises each code point through the two-step stbtt_GetCodepointBitmapBox() + stbtt_MakeCodepointBitmap() path (glyph bitmap into a fixed buffer; stb scratch via the no-heap arena in ra8_stbtt_alloc.c), and blits the alpha-8 mask into the framebuffer with ra8_gfx_pixel().

The framebuffer must already be bound by ra8_gfx_init(). The background is NOT cleared; the caller chooses the background colour with a prior ra8_gfx_clear().

Parameters

[in]	engine	Laid-out engine.
[in]	page_idx	Page to render ([0, page_count)).
[in,out]	framebuffer	Reserved for future use; pass NULL while ra8_gfx is bound. (Forward-compat hook so future builds can blit straight into a non-active buffer without re-binding ra8_gfx.)

Returns: ra8_err_t

Return values

k_ra8_ok	Rendered.
k_ra8_err_null_ptr	engine is NULL.
k_ra8_err_not_initialized	engine->in_use == 0.
k_ra8_err_out_of_range	page_idx >= page_count.
k_ra8_err_validation_failed	Font blob malformed.

Precondition: ra8_gfx_init() has been called.; A chapter has been laid out.

Postcondition: Glyph pixels of the requested page are blitted into the bound framebuffer.

Since: 0.1.0

Definition at line 505 of file reflow_v2.cpp.

References internal_render_page(), k_ra8_err_out_of_range, k_ra8_ok, and reflow_t::page_count.

Referenced by erb_render_all(), internal_rc_render_all(), and sfr_render_or_halt().

◆ 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 560 of file reflow_v2.cpp.

References reflow_t::anchor_count, reflow_page_t::glyph_count, reflow_t::glyph_count, reflow_page_t::glyph_first, reflow_t::image_box_count, reflow_t::in_use, internal_layout_tokens(), k_priv_min_chapter_pages, k_ra8_err_no_mem, k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_ok, k_reflow_max_pages, reflow_t::link_rect_count, reflow_t::page_count, reflow_t::pages, priv_reflow_internal_final_page_needed(), priv_reflow_layout_build_link_rects(), priv_reflow_layout_init_font(), and reflow_t::token_count.

◆ 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 531 of file reflow_v2.cpp.

References reflow_t::font_px, reflow_t::in_use, k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_ok, k_reflow_max_font_px, k_reflow_min_font_px, priv_reflow_internal_xhtml_invalid(), reflow_layout_chapter(), reflow_t::xhtml_buf, and reflow_t::xhtml_len.

Referenced by main().

Functions

Detailed Description

Function Documentation

◆ reflow_close()

◆ reflow_get_page_count()

◆ reflow_init()

◆ reflow_layout_chapter()

◆ reflow_parse_xhtml()

◆ reflow_render_page()

◆ reflow_run_layout()

◆ reflow_set_font_size()