Zero-heap raster image decode + scale + blit for reflow (#106). More...

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

Include dependency graph for reflow_image.h:

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

Data Structures
struct	ra8_img_arena_t
	Caller-owned bump arena backing a single image decode. More...

Functions
ra8_err_t	ra8_img_decode_blit (ra8_img_arena_t arena, const uint8_t bytes, size_t len, int32_t dst_x, int32_t dst_y, int32_t box_w, int32_t box_h, int32_t out_w, int32_t out_h)
	Decode `bytes` and blit it, scaled to fit, into the bound framebuffer.
ra8_err_t	ra8_img_probe_size (const uint8_t bytes, size_t len, int32_t out_w, int32_t *out_h)
	Probe an image's intrinsic dimensions without a full decode.

Detailed Description

Zero-heap raster image decode + scale + blit for reflow (#106).

Decodes an in-memory JPEG/PNG/GIF/BMP (the formats EPUB covers + figures use) through stb_image and blits it – nearest-neighbour scaled to fit a layout box – into the ra8_gfx framebuffer. The cover path (#106 Phase 1) and the in-chapter <img> path (Phase 2) both call ra8_img_decode_blit.

Zero heap (NASA P10 Rule 3). stb_image normally mallocs; here it is redirected (at build time in stb_image_impl.c) to a caller-owned bump arena (ra8_img_arena_t). The caller sizes the scratch for the largest image it decodes (a few KiB in SRAM for thumbnails, a few MiB in SDRAM for a full cover) – the module allocates nothing static and reaches no malloc.

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

Since: 0.1.0

Definition in file reflow_image.h.

Function Documentation

◆ ra8_img_decode_blit()

ra8_err_t ra8_img_decode_blit	(	ra8_img_arena_t *	arena,
		const uint8_t *	bytes,
		size_t	len,
		int32_t	dst_x,
		int32_t	dst_y,
		int32_t	box_w,
		int32_t	box_h,
		int32_t *	out_w,
		int32_t *	out_h )

nodiscard

Decode bytes and blit it, scaled to fit, into the bound framebuffer.

Decodes the image to RGB through stb_image (allocating only from arena), computes a fit rectangle inside box_w x box_h that preserves the source aspect ratio, then nearest-neighbour blits the scaled image at (dst_x, dst_y) via ra8_gfx. The arena is fully reset on return (success or failure). The caller must have bound a framebuffer with ra8_gfx_init().

Parameters

[in,out]	arena	Bump arena (reset on entry); scratch for the decode.
[in]	bytes	Encoded image bytes (JPEG/PNG/GIF/BMP).
[in]	len	Length of `bytes`.
[in]	dst_x	Destination left edge, framebuffer pixels.
[in]	dst_y	Destination top edge, framebuffer pixels.
[in]	box_w	Available box width to scale into (>= 1).
[in]	box_h	Available box height to scale into (>= 1).
[out]	out_w	Receives the blitted (scaled) width (NULL ok).
[out]	out_h	Receives the blitted (scaled) height (NULL ok).

Returns: ra8_err_t

Return values

k_ra8_ok	Image decoded, scaled, and blitted.
k_ra8_err_null_ptr	`arena` or `bytes` is NULL.
k_ra8_err_invalid_arg	`len` is 0, or `box_w` / `box_h` is < 1.
k_ra8_err_not_supported	stb_image could not decode the bytes.
k_ra8_err_no_mem	The arena is too small for this image.

Precondition: ra8_gfx_init() bound a framebuffer.; arena->base holds arena->cap writable bytes.

Postcondition: On success the scaled image is drawn; arena is reset to empty.; On any return arena->offset == 0 and arena->live == 0.

Note: Not thread-safe (uses a file-static "current arena" for the stb hooks).

Since: 0.1.0

Decode bytes and blit it, scaled to fit, into the bound framebuffer.

Definition at line 277 of file reflow_image.c.

References internal_arena_release(), internal_blit_scaled(), internal_decode_fail(), internal_fit_box(), k_ra8_err_invalid_arg, k_ra8_img_min_edge, k_ra8_img_req_rgb, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_img_arena_bind(), ra8_log_error, and s_tag_img.

Referenced by cm_draw_page(), ec_render_cover_or_halt(), ef_decode_and_hash(), internal_decode(), internal_render_one_image(), internal_render_svg(), main(), sh_book_cover_fullscreen(), sh_comic_blit_page(), and sh_epub_thumb().

◆ ra8_img_probe_size()

ra8_err_t ra8_img_probe_size	(	const uint8_t *	bytes,
		size_t	len,
		int32_t *	out_w,
		int32_t *	out_h )

nodiscard

Probe an image's intrinsic dimensions without a full decode.

Wraps stbi_info_from_memory – lets the layout pass size an <img> box from the source dimensions before deciding to decode + blit. Allocates nothing.

Parameters

[in]	bytes	Encoded image bytes.
[in]	len	Length of `bytes`.
[out]	out_w	Receives intrinsic width.
[out]	out_h	Receives intrinsic height.

Returns: ra8_err_t

Return values

k_ra8_ok	Dimensions read.
k_ra8_err_null_ptr	Any pointer argument is NULL.
k_ra8_err_not_supported	stb_image could not parse the header.

Precondition: bytes holds len bytes; out_w / out_h are writable.

Postcondition: On success *out_w / *out_h are the source pixel dimensions.

Note: Pure read of bytes; thread-safe.

Since: 0.1.0

Definition at line 59 of file reflow_image.c.

References k_ra8_err_not_supported, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_log_error, ra8_svg_is_svg(), ra8_svg_size(), and s_tag_img.

Referenced by internal_image_resolve_size(), and internal_probe_page().

Data Structures

Functions

Detailed Description

Function Documentation

◆ ra8_img_decode_blit()

◆ ra8_img_probe_size()