Module-private seams shared by the producer translation units. More...

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

Include dependency graph for jof_internal.h:

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

Go to the source code of this file.

Data Structures
struct	jof_bump_t
	Linear (bump) allocator over the caller's work arena. More...
struct	jof_prefix_pull_t
	Pull adapter that replays the sniffed head bytes, then delegates. More...
struct	jof_prod_state_t
	Whole transcode state (module-static instance in the producer TU). More...

Typedefs
typedef ra8_err_t(*	jof_geom_fn) (void *ctx, uint16_t width, uint16_t height, uint8_t channels)
	Producer geometry hook: fires once when the source dimensions and output channel count are known, before any pixel row is emitted.
typedef ra8_err_t(*	jof_rows_fn) (void ctx, const uint8_t px, uint16_t width, uint16_t y0, uint16_t nrows, uint8_t channels)
	Producer row sink: receives decoded pixel rows strictly in order.

Enumerations
enum	jof_bump_const_t : uint8_t { k_jof_bump_align = 8U }
	Bump-allocator alignment constants. More...
enum	jof_carve_const_t : uint32_t { k_jof_carve_slack = 128U }
	Carve-sizing constant shared by both work-arena calculators. More...

Functions
void *	priv_jof_bump_take (jof_bump_t *bump, size_t len)
	Carve `len` 8-byte-aligned bytes from the bump arena.
ra8_err_t	priv_jof_png_rows (jof_pull_fn pull, void pull_ctx, jof_bump_t bump, uint16_t max_w, uint16_t max_h, jof_geom_fn on_geom, jof_rows_fn on_rows, void *cb_ctx)
	Streaming PNG scanline decode: pull bytes in, emit rows in order.
ra8_err_t	priv_jof_prefix_pull (void ctx, uint8_t buf, size_t cap, size_t *got)
	Pull adapter: replay the sniffed head, then delegate to the source.
ra8_err_t	priv_jof_on_geom (void *ctx, uint16_t width, uint16_t height, uint8_t channels)
	Bind the source geometry: validate caps, carve buffers, emit header.
ra8_err_t	priv_jof_on_rows (void ctx, const uint8_t px, uint16_t width, uint16_t y0, uint16_t nrows, uint8_t channels)
	Row sink shared by every decoder arm: accumulate, flush full bands.
ra8_err_t	priv_jof_webp_transcode (jof_prod_state_t st, jof_prefix_pull_t pfx)
	Transcode a WebP source into the JOF tile path (whole-frame, #290).

Detailed Description

Module-private seams shared by the producer translation units.

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

The producer is split across translation units to keep each under the maintainability line cap:

jof_produce.c – sniff/dispatch, band accumulator, tile cut + encode + sink, index/footer emission, JPEG/PNG arms.
jof_produce_webp.c – the whole-frame WebP arm (#290): jof_webp_work_bytes() and priv_jof_webp_transcode().
jof_png.c – the streaming PNG scanline decoder.

This header carries the bump allocator over the caller's work arena, the geometry/rows callback contracts the PNG decoder reports through (the JPEG path reports through ra8_jpeg_sw_decode_stripes()'s own public seams instead), and the producer-state / prefix-pull seams the WebP arm shares with the dispatcher.

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

Since: 0.1.0

Definition in file jof_internal.h.

Typedef Documentation

◆ jof_geom_fn

typedef ra8_err_t(* jof_geom_fn) (void *ctx, uint16_t width, uint16_t height, uint8_t channels)

Producer geometry hook: fires once when the source dimensions and output channel count are known, before any pixel row is emitted.

Parameters

[in]	ctx	Producer context.
[in]	width	Source width, pixels (>= 1).
[in]	height	Source height, pixels (>= 1).
[in]	channels	Output bytes per pixel (1, 3 or 4).

Returns: k_ra8_ok to continue; any error aborts the decode with that code.

Since: 0.1.0

Definition at line 96 of file jof_internal.h.

◆ jof_rows_fn

typedef ra8_err_t(* jof_rows_fn) (void *ctx, const uint8_t *px, uint16_t width, uint16_t y0, uint16_t nrows, uint8_t channels)

Producer row sink: receives decoded pixel rows strictly in order.

Parameters

[in]	ctx	Producer context.
[in]	px	Row pixels (nrows * width * channels bytes, packed).
[in]	width	Row width, pixels.
[in]	y0	Image row of the first delivered row.
[in]	nrows	Rows delivered this call (>= 1).
[in]	channels	Bytes per pixel (matches the geometry hook).

Returns: k_ra8_ok to continue; any error aborts the decode with that code.

Since: 0.1.0

Definition at line 111 of file jof_internal.h.

Enumeration Type Documentation

◆ jof_bump_const_t

enum jof_bump_const_t : uint8_t

Bump-allocator alignment constants.

Enumerator
k_jof_bump_align	Every carve is 8-byte aligned.

Definition at line 43 of file jof_internal.h.

◆ jof_carve_const_t

enum jof_carve_const_t : uint32_t

Carve-sizing constant shared by both work-arena calculators.

Enumerator
k_jof_carve_slack	Alignment slack folded into every arena sizing.

Definition at line 175 of file jof_internal.h.

Function Documentation

◆ priv_jof_bump_take()

void * priv_jof_bump_take	(	jof_bump_t *	bump,
		size_t	len )

Carve len 8-byte-aligned bytes from the bump arena.

Parameters

[in,out]	bump	Arena state (offset advances).
[in]	len	Bytes requested.

Returns: Pointer to the carved region, or NULL on exhaustion.

Return values

NULL	The arena cannot fit `len` more aligned bytes.
non-NULL	8-byte-aligned region of `len` bytes (assignable to any object pointer whose alignment is at most 8).

Precondition: bump is non-NULL with base covering cap bytes.; len is a real buffer size (> 0).

Postcondition: On success bump->off advanced past the carve.; On NULL the arena is unchanged.

Note: Not thread-safe.

Since: 0.1.0

Carve len 8-byte-aligned bytes from the bump arena.

Definition at line 89 of file jof_produce.c.

References jof_bump_t::base, jof_bump_t::cap, k_jof_bump_align, jof_bump_t::off, and RA8_PRIV.

Referenced by internal_carve_pixel_path(), internal_dispatch(), internal_init_state(), internal_jpeg_geom(), and internal_png_bind_geometry().

◆ priv_jof_on_geom()

ra8_err_t priv_jof_on_geom	(	void *	ctx,
		uint16_t	width,
		uint16_t	height,
		uint8_t	channels )

Bind the source geometry: validate caps, carve buffers, emit header.

Fires once per transcode (from any decoder arm). Rejects, fail closed: dimensions above the caps, a tile grid above the format cap, and any carve the arena cannot fit. On success the 32-byte JOF header has been sunk. Matches jof_geom_fn.

Parameters

[in]	ctx	The producer state (jof_prod_state_t).
[in]	width	Source width, pixels.
[in]	height	Source height, pixels.
[in]	channels	Output bytes per pixel (1, 3 or 4).

Returns: Result code.

Return values

k_ra8_ok	Geometry bound; header written.
k_ra8_err_invalid_size	Over the caps / grid cap / arena exhausted.
k_ra8_err_invalid_state	The geometry hook fired twice.
other	Propagated from the sink.

Precondition: The decoder validated width/height non-zero.; st->cfg and st->bump are bound.

Postcondition: On success the pixel-path buffers are carved and the header sunk.; On error the transcode aborts.

Note: Not thread-safe.

Since: 0.1.0

Fires once per transcode (from either decoder). Rejects, fail closed: dimensions above the caps, a tile grid above the format cap, and any carve the arena cannot fit. On success the 32-byte JOF header has been sunk.

Parameters

[in]	ctx	The producer state.
[in]	width	Source width, pixels.
[in]	height	Source height, pixels.
[in]	channels	Output bytes per pixel (1, 3 or 4).

Returns: Result code.

Return values

k_ra8_ok	Geometry bound; header written.
k_ra8_err_invalid_size	Over the caps / grid cap / arena exhausted.
k_ra8_err_invalid_state	The geometry hook fired twice.
other	Propagated from the sink.

Precondition: The decoder validated width/height non-zero.; st->cfg and st->bump are bound.

Postcondition: On success band/stage/cmp/idx are carved and header sunk.; On error the transcode aborts.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 301 of file jof_produce.c.

References jof_prod_state_t::bpp, jof_prod_state_t::cap_h, jof_prod_state_t::cap_w, jof_prod_state_t::cfg, jof_prod_state_t::geom_done, jof_prod_state_t::h, internal_carve_pixel_path(), internal_emit_header(), k_jof_max_tiles, k_ra8_err_invalid_size, k_ra8_err_invalid_state, k_ra8_ok, RA8_PRIV, jof_prod_state_t::tile_cols, jof_prod_state_t::tile_count, jof_produce_cfg_t::tile_h, jof_prod_state_t::tile_rows, jof_produce_cfg_t::tile_w, and jof_prod_state_t::w.

Referenced by internal_dispatch(), internal_jpeg_geom(), and priv_jof_webp_transcode().

◆ priv_jof_on_rows()

ra8_err_t priv_jof_on_rows	(	void *	ctx,
		const uint8_t *	px,
		uint16_t	width,
		uint16_t	y0,
		uint16_t	nrows,
		uint8_t	channels )

Row sink shared by every decoder arm: accumulate, flush full bands.

Enforces the strict in-order row contract (y0 == rows_seen), then copies the delivered rows into the band, flushing a tile row every time the band fills. A row group may span a band boundary; the copy loop splits it. Matches jof_rows_fn.

Parameters

[in]	ctx	The producer state (jof_prod_state_t).
[in]	px	Decoded row pixels.
[in]	width	Row width, pixels.
[in]	y0	Image row of the first delivered row.
[in]	nrows	Rows delivered.
[in]	channels	Bytes per pixel.

Returns: Result code.

Return values

k_ra8_ok	Rows accumulated (bands maybe flushed).
k_ra8_err_validation_failed	Contract violation (order, geometry).
other	Propagated from the flush stage.

Precondition: The geometry hook has fired (geom_done == 1).; px holds nrows * width * channels bytes.

Postcondition: rows_seen advanced by nrows on success.; On error the transcode aborts.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 418 of file jof_produce.c.

References jof_prod_state_t::band, jof_prod_state_t::band_fill, jof_prod_state_t::bpp, jof_prod_state_t::cfg, jof_prod_state_t::geom_done, jof_prod_state_t::h, internal_flush_band(), k_ra8_err_validation_failed, k_ra8_ok, memcpy(), RA8_CHECK_NULL_PTR, RA8_PRIV, jof_prod_state_t::rows_seen, s_tag, jof_produce_cfg_t::tile_h, and jof_prod_state_t::w.

Referenced by internal_dispatch(), and internal_webp_feed().

◆ priv_jof_png_rows()

ra8_err_t priv_jof_png_rows	(	jof_pull_fn	pull,
		void *	pull_ctx,
		jof_bump_t *	bump,
		uint16_t	max_w,
		uint16_t	max_h,
		jof_geom_fn	on_geom,
		jof_rows_fn	on_rows,
		void *	cb_ctx )

Streaming PNG scanline decode: pull bytes in, emit rows in order.

Bounded-RAM PNG decoder for the transcode producer: 8-bit depth, colour types 0/2/3/4/6, non-interlaced. IDAT inflates through miniz tinfl into a 64 KiB ring, scanlines are unfiltered against one previous row and translated to the output layout (gray -> 1, RGB / opaque palette -> 3, gray+alpha / RGBA / palette+tRNS -> 4), then handed to on_rows one row at a time. All working buffers are carved from bump. Interlaced, 16-bit, and out-of-spec structures are rejected fail-closed. Chunk CRCs are not verified (the ZIP layer above already integrity-checks the entry; the zlib Adler32 inside IDAT is verified).

Parameters

[in]	pull	Sequential byte source positioned at byte 0 of the PNG stream (the producer replays sniffed bytes).
[in]	pull_ctx	Context for `pull`.
[in,out]	bump	Work-arena allocator for the decoder's buffers.
[in]	max_w	Fail-closed width cap, pixels.
[in]	max_h	Fail-closed height cap, pixels.
[in]	on_geom	Geometry hook (fires once, before rows).
[in]	on_rows	Row sink (fires height times, in order).
[in]	cb_ctx	Context for both hooks.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Every row emitted.
k_ra8_err_invalid_size	Dimensions exceed the caps or the arena is exhausted.
k_ra8_err_not_supported	Interlaced / 16-bit / unknown colour type / non-zero compression or filter method.
k_ra8_err_protocol_error	Malformed chunk structure or a corrupt / truncated deflate stream.
k_ra8_err_validation_failed	Pixel-stream inconsistency (filter byte, palette index, row count).
other	Propagated from pull / the hooks.

Precondition: pull delivers the PNG from its first signature byte.; bump has capacity per jof_work_bytes().

Postcondition: On success exactly height rows were emitted, in order.; On any error emission stops; the transcode aborts.

Note: Not thread-safe (module-static inflate context).

Since: 0.1.0

Definition at line 579 of file jof_png.c.

References ra8_png_state_t::cb_ctx, internal_png_walk_chunks(), memset(), ra8_png_state_t::on_geom, ra8_png_state_t::on_rows, ra8_png_state_t::pull, ra8_png_state_t::pull_ctx, RA8_CHECK_NULL_PTR, RA8_PRIV, and s_tag.

Referenced by internal_dispatch().

◆ priv_jof_prefix_pull()

ra8_err_t priv_jof_prefix_pull	(	void *	ctx,
		uint8_t *	buf,
		size_t	cap,
		size_t *	got )

Pull adapter: replay the sniffed head, then delegate to the source.

Serves the replay bytes first, then transparently delegates to the inner source. Matches jof_pull_fn so it can be passed as the pull seam to any decoder.

Parameters

[in]	ctx	A jof_prefix_pull_t.
[out]	buf	Destination buffer.
[in]	cap	Capacity of `buf`.
[out]	got	Bytes delivered.

Returns: Result code.

Return values

k_ra8_ok	Delivered replay or source bytes.
other	Propagated from the inner source.

Precondition: ctx points at an initialised adapter.; buf holds cap writable bytes.

Postcondition: *got <= cap bytes were written to buf.; The replay cursor never exceeds the head length.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 184 of file jof_produce.c.

References jof_prefix_pull_t::head, jof_prefix_pull_t::head_len, jof_prefix_pull_t::inner, jof_prefix_pull_t::inner_ctx, k_ra8_ok, memcpy(), jof_prefix_pull_t::pos, and RA8_PRIV.

Referenced by internal_dispatch(), and internal_webp_pull_all().

◆ priv_jof_webp_transcode()

ra8_err_t priv_jof_webp_transcode	(	jof_prod_state_t *	st,
		jof_prefix_pull_t *	pfx )

Transcode a WebP source into the JOF tile path (whole-frame, #290).

Pulls the whole compressed source into cfg->webp_work, reads its geometry, binds it as a 4-bpp source through priv_jof_on_geom, carves the decoded RGBA frame and libwebp scratch after the source bytes, decodes heap-free through the ra8_webp facade, and bands the frame out through priv_jof_on_rows. Every carve is bounds-checked; any shortfall fails closed. WebP is not stripe-decodable (its lossless mode back-references the whole frame), so it carries an honest whole-frame memory cost isolated in webp_work; the emitted atlas bytes are identical to the streaming arms for the same pixels.

Parameters

[in,out]	st	Producer state (priv_init_state() succeeded).
[in,out]	pfx	Prefix-replay pull adapter over the source.

Returns: Result code.

Return values

k_ra8_ok	Whole WebP decoded and accumulated.
k_ra8_err_not_supported	No webp_work arena, or an axis over cap.
k_ra8_err_invalid_size	The arena cannot fit source + frame + scratch.
k_ra8_err_validation_failed	Corrupt WebP or the scratch exhausted.
other	Propagated from the pull / facade / rows.

Precondition: priv_jof_prefix_pull replays the sniffed head before the source.; The dispatcher confirmed the RIFF+WEBP head.

Postcondition: On success every source row reached the band accumulator.; On error the transcode aborts.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 158 of file jof_produce_webp.c.

References jof_prod_state_t::cfg, internal_webp_feed(), internal_webp_pull_all(), k_jof_bump_align, k_jof_webp_bpp, k_ra8_err_invalid_size, k_ra8_err_not_supported, k_ra8_ok, priv_jof_on_geom(), RA8_PRIV, ra8_webp_decode_rgba(), ra8_webp_get_info(), jof_produce_cfg_t::webp_work, and jof_produce_cfg_t::webp_work_cap.

Referenced by internal_dispatch().

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ jof_geom_fn

◆ jof_rows_fn

Enumeration Type Documentation

◆ jof_bump_const_t

◆ jof_carve_const_t

Function Documentation

◆ priv_jof_bump_take()

◆ priv_jof_on_geom()

◆ priv_jof_on_rows()

◆ priv_jof_png_rows()

◆ priv_jof_prefix_pull()

◆ priv_jof_webp_transcode()