ra8-firmware 0.1.0
Bare-metal firmware for the Renesas RA8 family (RA8D2 / RA8P1)
Loading...
Searching...
No Matches
reflow_layout_image.c File Reference

Block-level <img> layout for the reflow engine (#106). More...

#include <stddef.h>
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_err.h"
#include "reflow.h"
#include "reflow_image.h"
#include "reflow_internal.h"
#include "reflow_layout_internal.h"
#include "stb_truetype.h"
Include dependency graph for reflow_layout_image.c:

Go to the source code of this file.

Functions

static bool internal_apply_image_placeholder (reflow_t *engine, priv_cursor_t *cur)
 Apply an <img> token without a bound loader: placeholder advance.
static bool internal_page_has_content (const reflow_t *engine, const priv_cursor_t *cur)
 True iff the page under construction already holds glyphs or images.
static void internal_image_fit (int32_t iw, int32_t ih, int32_t col_w, int32_t avail_h, int32_t *out_w, int32_t *out_h)
 Scale an intrinsic image size to fit the text column (no upscaling).
static bool internal_image_resolve_size (reflow_t *engine, const reflow_token_t *tok, int32_t *out_w, int32_t *out_h)
 Resolve an image token to a column-fitted box size via the loader.
static void internal_image_record (reflow_t *engine, priv_cursor_t *cur, const reflow_token_t *tok, int32_t bw, int32_t bh)
 Record a laid-out image box and advance the cursor below it.
static bool internal_place_image (reflow_t *engine, priv_cursor_t *cur, const reflow_token_t *tok)
 Lay out a real <img> as a block: size it, page-break, record it.
bool priv_reflow_layout_apply_image (reflow_t *engine, priv_cursor_t *cur, const reflow_token_t *tok)
 Apply an <img> token: real image when a loader is bound, else a placeholder.

Detailed Description

Block-level <img> layout for the reflow engine (#106).

Splits the image-layout sub-responsibility out of reflow_layout.c so each translation unit stays under the project file-size cap. An <img> is laid out as a block: when a loader + arena are bound and the token carries a source slice, the encoded bytes are fetched, the intrinsic size is probed (zero-alloc), the box is scaled to fit the text column without upscaling, the cursor page-breaks as needed, and the box is recorded for the render pass. If no loader is bound – or any sizing step fails – the historic fixed-size placeholder advance is used so image-free content remains byte-identical.

The driver reaches this module via priv_reflow_layout_apply_image; the core inline-flow helpers it reuses (line wrap, page flush) are shared through reflow_layout_internal.h.

[Ring 4 / Reflow] {World: NS}

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

Definition in file reflow_layout_image.c.

Function Documentation

◆ internal_apply_image_placeholder()

bool internal_apply_image_placeholder ( reflow_t * engine,
priv_cursor_t * cur )
static

Apply an <img> token without a bound loader: placeholder advance.

See implementation. Historical v1 behaviour, kept so image-free content (and content laid out before a loader is bound) is byte-identical.

Parameters
[in]engineSee implementation.
[in]curSee implementation.
Returns
Result code.
Return values
k_ra8_okOperation 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 55 of file reflow_layout_image.c.

References k_priv_image_placeholder_px, k_reflow_margin_px, priv_cursor_t::line_has_content, priv_reflow_internal_right_overflow_break(), priv_reflow_layout_newline(), reflow_t::viewport_w, and priv_cursor_t::x.

Referenced by priv_reflow_layout_apply_image().

◆ internal_image_fit()

void internal_image_fit ( int32_t iw,
int32_t ih,
int32_t col_w,
int32_t avail_h,
int32_t * out_w,
int32_t * out_h )
static

Scale an intrinsic image size to fit the text column (no upscaling).

See implementation. Caps width at the column, height at one page; preserves aspect ratio with int64 products to avoid overflow.

Parameters
[in]iwSee implementation.
[in]ihSee implementation.
[in]col_wSee implementation.
[in]avail_hSee implementation.
[out]out_wSee implementation.
[out]out_hSee implementation.
Returns
None.
Precondition
iw > 0 and ih > 0.
col_w > 0 and avail_h > 0.
Postcondition
*out_w in [1, col_w] and *out_h in [1, avail_h].
Aspect ratio preserved within integer rounding.
Note
Pure function.
Since
0.1.0

Definition at line 114 of file reflow_layout_image.c.

Referenced by internal_image_resolve_size().

◆ internal_image_record()

void internal_image_record ( reflow_t * engine,
priv_cursor_t * cur,
const reflow_token_t * tok,
int32_t bw,
int32_t bh )
static

Record a laid-out image box and advance the cursor below it.

See implementation. Stores the box at the left margin / current baseline tagged with the active page, then drops the cursor past it.

Parameters
[in]engineSee implementation.
[in]curSee implementation.
[in]tokSee implementation.
[in]bwSee implementation.
[in]bhSee implementation.
Returns
None.
Precondition
engine->image_box_count < k_reflow_max_images.
bw >= 1 and bh >= 1.
Postcondition
One image box appended; image_box_count incremented.
Cursor advanced below the image, line reset to the left margin.
Note
Not thread-safe.
Since
0.1.0

Definition at line 195 of file reflow_layout_image.c.

References reflow_image_box_t::h, reflow_t::image_box_count, reflow_t::image_boxes, priv_cursor_t::indent_px, k_reflow_margin_px, k_reflow_paragraph_gap_px, priv_cursor_t::line_has_content, priv_cursor_t::line_top, reflow_t::page_count, reflow_image_box_t::page_index, reflow_image_box_t::reserved, reflow_image_box_t::src_len, reflow_image_box_t::src_off, reflow_token_t::text_len, reflow_token_t::text_off, reflow_image_box_t::w, priv_cursor_t::x, reflow_image_box_t::x, priv_cursor_t::y, and reflow_image_box_t::y.

Referenced by internal_place_image().

◆ internal_image_resolve_size()

bool internal_image_resolve_size ( reflow_t * engine,
const reflow_token_t * tok,
int32_t * out_w,
int32_t * out_h )
static

Resolve an image token to a column-fitted box size via the loader.

See implementation. Calls the bound loader for the encoded bytes, probes the intrinsic size (zero-alloc), and fits it to the column.

Parameters
[in]engineSee implementation.
[in]tokSee implementation.
[out]out_wSee implementation.
[out]out_hSee implementation.
Returns
Boolean.
Return values
trueBox size resolved.
falseLoader failed, probe failed, or viewport too small.
Precondition
engine->img_loader != nullptr.
tok->text_len > 0.
Postcondition
On true, *out_w/*out_h are a valid column-fit box.
On false, no box is produced (caller falls back).
Note
Not thread-safe.
Since
0.1.0

Definition at line 151 of file reflow_layout_image.c.

References reflow_t::img_loader, reflow_t::img_loader_ctx, internal_image_fit(), k_ra8_ok, k_reflow_margin_px, ra8_img_probe_size(), reflow_token_t::text_len, reflow_token_t::text_off, reflow_t::text_pool, reflow_t::viewport_h, and reflow_t::viewport_w.

Referenced by internal_place_image().

◆ internal_page_has_content()

bool internal_page_has_content ( const reflow_t * engine,
const priv_cursor_t * cur )
static

True iff the page under construction already holds glyphs or images.

See implementation.

Parameters
[in]engineSee implementation.
[in]curSee implementation.
Returns
Boolean.
Return values
truePage has content.
Precondition
Module state is consistent.
Module state is consistent.
Postcondition
No state mutated.
No state mutated.
Note
Pure read.
Since
0.1.0

Definition at line 88 of file reflow_layout_image.c.

References reflow_t::glyph_count, reflow_t::image_box_count, priv_cursor_t::page_first_glyph, and priv_cursor_t::page_first_image.

Referenced by internal_place_image().

◆ internal_place_image()

bool internal_place_image ( reflow_t * engine,
priv_cursor_t * cur,
const reflow_token_t * tok )
static

Lay out a real <img> as a block: size it, page-break, record it.

See implementation. Returns false (caller falls back to the placeholder) on a full image pool, unresolved src, or a flush overflow.

Parameters
[in]engineSee implementation.
[in]curSee implementation.
[in]tokSee implementation.
Returns
Boolean.
Return values
trueImage placed and recorded.
falseCould not place; caller uses the placeholder.
Precondition
engine->img_loader != nullptr and engine->img_arena != nullptr.
tok->text_len > 0.
Postcondition
On true, one image box exists and the cursor sits below it.
On false, engine image state is unchanged.
Note
Not thread-safe.
Since
0.1.0

Definition at line 237 of file reflow_layout_image.c.

References reflow_t::image_box_count, internal_image_record(), internal_image_resolve_size(), internal_page_has_content(), k_reflow_margin_px, k_reflow_max_images, priv_cursor_t::line_has_content, priv_cursor_t::line_height_px, priv_reflow_layout_finish_page(), priv_reflow_layout_newline(), reflow_t::viewport_h, and priv_cursor_t::y.

Referenced by priv_reflow_layout_apply_image().

◆ priv_reflow_layout_apply_image()

bool priv_reflow_layout_apply_image ( reflow_t * engine,
priv_cursor_t * cur,
const reflow_token_t * tok )

Apply an <img> token: real image when a loader is bound, else a placeholder.

Defined in reflow_layout_image.c. When the engine has a bound image loader + arena and the token carries a source slice, the image is sized to the text column, page-broken as a block, and recorded as an image box; any failure (full pool, unresolved src, flush overflow) falls back to the historic fixed-size placeholder advance so image-free content stays byte-identical.

Parameters
[in]engineSee implementation.
[in]curSee implementation.
[in]tokSee implementation.
Returns
Boolean.
Return values
trueToken applied (image placed or placeholder reserved).
falsePool overflow propagated from a sub-step.
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 270 of file reflow_layout_image.c.

References reflow_t::img_arena, reflow_t::img_loader, internal_apply_image_placeholder(), internal_place_image(), and reflow_token_t::text_len.

Referenced by priv_reflow_layout_apply_token().