Single-image to JOF transcode behind jof_worker.h. More...

#include "jof_worker.h"
#include <errno.h>
#include <fcntl.h>
#include <stdlib.h>
#include <string.h>
#include <sys/stat.h>
#include <unistd.h>
#include "jof_produce.h"
#include "ra8_attributes.h"

Include dependency graph for jof_worker.c:

Data Structures
struct	worker_pull_t
	Pull cursor over the in-RAM encoded source. More...
struct	worker_sink_t
	Sink state over the raw output descriptor. More...

Enumerations
enum	worker_limit_t : uint64_t { k_worker_max_input = 256U * 1024U * 1024U , k_worker_tile_h = 256U , k_worker_out_mode = 0644U }
	Named resource limits for the worker. More...
enum	worker_webp_t : uint8_t { k_worker_webp_riff_ofs = 0U , k_worker_webp_form_ofs = 8U , k_worker_webp_head_len = 12U , k_worker_webp_tag_len = 4U }
	WebP container-head offsets for the whole-frame-arena decision. More...

Functions
static bool	worker_read_all (int fd, uint8_t *buf, size_t len)
	Read exactly len bytes unless the descriptor fails or ends early.
static ra8_err_t	worker_sink (void ctx, const uint8_t buf, size_t len)
	Append producer output bytes to the output descriptor.
static ra8_err_t	worker_pull (void ctx, uint8_t buf, size_t cap, size_t *got)
	Copy the next encoded source span into a producer buffer.
static bool	worker_is_webp (const uint8_t *data, size_t len)
	Test whether source bytes carry the WebP RIFF container head.
static jof_worker_result_t	worker_map_producer (ra8_err_t err)
	Map a producer return code to the worker result contract.
static jof_worker_result_t	worker_read_source (const char in_path, uint8_t out_src, size_t out_len)
	Read encoded source file into an allocated RAM buffer.
static jof_worker_result_t	worker_alloc_webp (const uint8_t src, size_t src_len, uint16_t w, uint16_t h, uint8_t out_webp_work, size_t out_webp_cap)
	Allocate the WebP frame arena if the source format requires one.
static jof_worker_result_t	worker_produce_to_file (const char out_path, const uint8_t src, size_t src_len, uint16_t w, uint16_t h, uint16_t tile_h, uint8_t work, size_t work_cap, uint8_t webp_work, size_t webp_work_cap)
	Stream JOF producer output into the destination atlas file.
jof_worker_result_t	jof_worker_convert (const char in_path, const char out_path)
	Transcode one encoded image file into one JOF atlas file.

Variables
static const uint8_t	s_worker_riff [k_worker_webp_tag_len] = {'R', 'I', 'F', 'F'}
	WebP RIFF container tag (source head bytes 0..3).
static const uint8_t	s_worker_webp [k_worker_webp_tag_len] = {'W', 'E', 'B', 'P'}
	WebP form-type fourCC (source head bytes 8..11).

Detailed Description

Single-image to JOF transcode behind jof_worker.h.

Reads one encoded source file whole (bounded), probes its geometry with jof_probe_dims(), sizes the exact producer arenas for that geometry, and streams jof_produce() into the output file through a raw-descriptor sink. All I/O uses bounded read/write loops with partial-transfer and EINTR handling; no FILE * appears.

[Ring 4 / Domain] {World: NS}

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

Since: 0.1.0

Definition in file jof_worker.c.

Enumeration Type Documentation

◆ worker_limit_t

enum worker_limit_t : uint64_t

Named resource limits for the worker.

Enumerator
k_worker_max_input	Largest accepted input, bytes.
k_worker_tile_h	Band-tile height cap, pixels.
k_worker_out_mode	File mode: rw-r–r–.

Definition at line 30 of file jof_worker.c.

◆ worker_webp_t

enum worker_webp_t : uint8_t

WebP container-head offsets for the whole-frame-arena decision.

Enumerator
k_worker_webp_riff_ofs	Offset of the "RIFF" fourCC.
k_worker_webp_form_ofs	Offset of the "WEBP" fourCC.
k_worker_webp_head_len	Bytes needed to sniff both tags.
k_worker_webp_tag_len	Length of one fourCC tag.

Definition at line 37 of file jof_worker.c.

Function Documentation

◆ jof_worker_convert()

jof_worker_result_t jof_worker_convert	(	const char *	in_path,
		const char *	out_path )

nodiscard

Transcode one encoded image file into one JOF atlas file.

Opens and bounds-checks the input, probes its dimensions, sizes the exact jof_work_bytes() / jof_webp_work_bytes() arenas for them, runs jof_produce() with a full-width band tile (tile_w == width, tile_h == min(height, 256)), and closes the output. On any failure the output path is closed and removed, so no torn atlas is left behind; cleanup failure never masks the primary error.

Parameters

[in]	in_path	Encoded source image (JPEG, PNG, or WebP).
[in]	out_path	Destination JOF atlas (created/truncated).

Returns: One jof_worker_result_t member.

Return values

k_jof_worker_ok	Atlas fully written to the output path.
k_jof_worker_usage	Wrong argument count or null path.
k_jof_worker_input	Input open/stat/read failed or was refused.
k_jof_worker_output	Output open/write/close failed.
k_jof_worker_geometry	Source dimensions unusable or unproduceable.
k_jof_worker_decode	Source is hostile or an unsupported variant.
k_jof_worker_memory	A bounded work arena could not be allocated.

Precondition: in_path and out_path are non-NULL NUL-terminated paths.; in_path points to an existing readable file.

Postcondition: On k_jof_worker_ok out_path holds one complete JOF atlas.; On any other result out_path does not exist.

Note: Not thread-safe (module-static decoder contexts in the producer).

Since: 0.1.0

Definition at line 410 of file jof_worker.c.

References jof_probe_dims(), jof_work_bytes(), jof_worker_convert(), k_jof_worker_geometry, k_jof_worker_memory, k_jof_worker_ok, k_jof_worker_usage, k_ra8_ok, k_worker_tile_h, worker_alloc_webp(), worker_produce_to_file(), and worker_read_source().

Referenced by jof_worker_convert(), and main().

◆ worker_alloc_webp()

jof_worker_result_t worker_alloc_webp	(	const uint8_t *	src,
		size_t	src_len,
		uint16_t	w,
		uint16_t	h,
		uint8_t **	out_webp_work,
		size_t *	out_webp_cap )

static

Allocate the WebP frame arena if the source format requires one.

Checks if the source bytes match the WebP container header. If so, computes the required whole-frame arena byte size using jof_webp_work_bytes() and allocates the arena via malloc. For non-WebP sources, returns success with a NULL arena.

Parameters

[in]	src	Source image bytes.
[in]	src_len	Byte length of source image bytes.
[in]	w	Source image width, pixels.
[in]	h	Source image height, pixels.
[out]	out_webp_work	Destination pointer receiving the arena.
[out]	out_webp_cap	Destination pointer receiving the arena capacity.

Returns: One jof_worker_result_t member.

Return values

k_jof_worker_ok	Arena allocated or not needed for non-WebP image.
k_jof_worker_geometry	WebP source dimensions exceed allowable sizing.
k_jof_worker_memory	Heap allocation for WebP scratch arena failed.

Precondition: src points to src_len readable bytes.; out_webp_work and out_webp_cap are non-NULL destination pointers.

Postcondition: On success with WebP, *out_webp_work holds the allocated buffer.; On non-WebP source, *out_webp_work is set to NULL and capacity to 0.

Note: Reentrant and thread-safe.

Since: 0.1.0

Definition at line 306 of file jof_worker.c.

References jof_webp_work_bytes(), k_jof_worker_geometry, k_jof_worker_memory, k_jof_worker_ok, and worker_is_webp().

Referenced by jof_worker_convert().

◆ worker_is_webp()

bool worker_is_webp	(	const uint8_t *	data,
		size_t	len )

static

Test whether source bytes carry the WebP RIFF container head.

Mirrors the producer's own dispatch sniff: both fourCCs must match, so a non-WebP RIFF (WAVE, AVI) is not mistaken for WebP and charged the whole-frame arena.

Parameters

[in]	data	Source bytes.
[in]	len	Readable byte count at data.

Returns: Whether data begins with a WebP container head.

Return values

true	Source begins with RIFF and WEBP fourCC identifiers.
false	Source is shorter than header length or tags do not match.

Precondition: data points to at least len readable bytes.; len is a valid non-negative byte length.

Postcondition: No memory or descriptor state is modified.; Return value depends strictly on first 12 bytes of data.

Note: Reentrant and thread-safe.

Since: 0.1.0

Definition at line 189 of file jof_worker.c.

References k_worker_webp_form_ofs, k_worker_webp_head_len, k_worker_webp_riff_ofs, memcmp(), s_worker_riff, and s_worker_webp.

Referenced by worker_alloc_webp().

◆ worker_map_producer()

jof_worker_result_t worker_map_producer ( ra8_err_t err )

static

Map a producer return code to the worker result contract.

Geometry-shaped codes (bad tile math, over-budget source, short arena) become geometry; hostile-or-unsupported sources become decode; arena exhaustion becomes memory. Sink/pull failures never reach here: the caller applies the output-close, sink, pull, producer-error precedence before consulting this map.

Parameters

[in] err Producer return code.

Returns: Mapped worker result (never ok: success is decided by the caller).

Return values

k_jof_worker_geometry	Input dimensions or tile sizing cannot be produced.
k_jof_worker_memory	Arena memory limit was exceeded during transcode.
k_jof_worker_decode	Corrupted, hostile, or unsupported image encoding.

Precondition: err is a valid ra8_err_t failure status.; err is not k_ra8_ok.

Postcondition: No system or worker state is modified.; Output is uniquely mapped according to error category.

Note: Pure function; reentrant and thread-safe.

Since: 0.1.0

Definition at line 217 of file jof_worker.c.

References k_jof_worker_decode, k_jof_worker_geometry, k_jof_worker_memory, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, and k_ra8_err_no_mem.

Referenced by worker_produce_to_file().

◆ worker_produce_to_file()

jof_worker_result_t worker_produce_to_file	(	const char *	out_path,
		const uint8_t *	src,
		size_t	src_len,
		uint16_t	w,
		uint16_t	h,
		uint16_t	tile_h,
		uint8_t *	work,
		size_t	work_cap,
		uint8_t *	webp_work,
		size_t	webp_work_cap )

static

Stream JOF producer output into the destination atlas file.

Opens the output file descriptor with creation and truncation flags, initializes pull cursor and sink descriptors, constructs the producer configuration structure, and invokes jof_produce(). Closes the output descriptor upon completion and evaluates sink status.

Parameters

[in]	out_path	Destination JOF atlas path.
[in]	src	Source image bytes.
[in]	src_len	Source image byte count.
[in]	w	Image width, pixels.
[in]	h	Image height, pixels.
[in]	tile_h	Tile height, pixels.
[in]	work	Producer work arena.
[in]	work_cap	Capacity of work arena, bytes.
[in]	webp_work	Optional WebP frame arena.
[in]	webp_work_cap	Capacity of WebP arena, bytes.

Returns: One jof_worker_result_t member.

Return values

k_jof_worker_ok	Atlas produced and written successfully.
k_jof_worker_output	Output file creation, write, or close failed.
k_jof_worker_geometry	Dimension or tile geometry rejected by producer.
k_jof_worker_decode	Image decode failed due to corrupted data.
k_jof_worker_memory	Internal producer arena was exhausted.

Precondition: out_path is non-NULL and points to a valid destination path.; work points to at least work_cap writable bytes.

Postcondition: On success, the complete JOF atlas is written to out_path.; The output file descriptor is always closed before return.

Note: Not thread-safe due to producer module-static decoder contexts.

Since: 0.1.0

Definition at line 364 of file jof_worker.c.

References worker_sink_t::failed, jof_produce(), k_jof_codec_deflate, k_jof_worker_ok, k_jof_worker_output, k_ra8_ok, k_worker_out_mode, worker_map_producer(), worker_pull(), and worker_sink().

Referenced by jof_worker_convert().

◆ worker_pull()

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

static

Copy the next encoded source span into a producer buffer.

Reads up to cap bytes from the in-memory cursor and advances the read position. When the cursor reaches the end of the source buffer, reports zero bytes read to indicate end-of-input.

Parameters

[in,out]	ctx	Pull cursor (a worker_pull_t *).
[out]	buf	Destination holding cap writable bytes.
[in]	cap	Writable capacity of buf.
[out]	got	Bytes copied (0 at end of input).

Returns: Status code (always k_ra8_ok).

Return values

k_ra8_ok The memory span was copied successfully.

Precondition: ctx is non-NULL and points to valid source data.; buf points to at least cap writable bytes.

Postcondition: *got holds the count of transferred bytes (up to cap).; ctx->pos advances by *got bytes.

Note: Reentrant across distinct pull cursor instances.

Since: 0.1.0

Definition at line 159 of file jof_worker.c.

References worker_pull_t::data, k_ra8_ok, worker_pull_t::len, memcpy(), and worker_pull_t::pos.

Referenced by worker_produce_to_file().

◆ worker_read_all()

bool worker_read_all	(	int	fd,
		uint8_t *	buf,
		size_t	len )

static

Read exactly len bytes unless the descriptor fails or ends early.

Loops over read() until len bytes have been transferred. Handles transient EINTR signals without aborting. Returns false if EOF is encountered prematurely or an unrecoverable read error occurs.

Parameters

[in]	fd	Open input descriptor.
[out]	buf	Destination holding len writable bytes.
[in]	len	Byte count to read.

Returns: Whether all len bytes arrived.

Return values

true	All `len` bytes were read successfully into `buf`.
false	Reading failed or reached EOF before `len` bytes arrived.

Precondition: fd is a valid open file descriptor.; buf points to at least len writable bytes.

Postcondition: On true, buf contains len bytes read from fd.; On false, the buffer content is undefined and partial.

Note: Reentrant and thread-safe for distinct descriptors.

Since: 0.1.0

Definition at line 81 of file jof_worker.c.

Referenced by worker_read_source().

◆ worker_read_source()

jof_worker_result_t worker_read_source	(	const char *	in_path,
		uint8_t **	out_src,
		size_t *	out_len )

static

Read encoded source file into an allocated RAM buffer.

Opens the source file, inspects file status to ensure it is within accepted input limits, allocates a memory buffer of the exact file size, and reads the entire file contents. Closes the descriptor before returning.

Parameters

[in]	in_path	Path to the encoded source image.
[out]	out_src	Destination pointer receiving the allocated source bytes.
[out]	out_len	Destination pointer receiving the source byte count.

Returns: One jof_worker_result_t member.

Return values

k_jof_worker_ok	File read successfully into allocated memory.
k_jof_worker_input	File open, stat, or read operation failed.
k_jof_worker_memory	Failed to allocate heap memory for source image.

Precondition: in_path is non-NULL and points to a NUL-terminated path.; out_src and out_len are non-NULL destination pointers.

Postcondition: On success, *out_src contains allocated file bytes and *out_len is its size.; On failure, no heap memory is leaked and descriptor is closed.

Note: Reentrant for distinct input paths.

Since: 0.1.0

Definition at line 251 of file jof_worker.c.

References k_jof_worker_input, k_jof_worker_memory, k_jof_worker_ok, k_worker_max_input, and worker_read_all().

Referenced by jof_worker_convert().

◆ worker_sink()

ra8_err_t worker_sink	(	void *	ctx,
		const uint8_t *	buf,
		size_t	len )

static

Append producer output bytes to the output descriptor.

Writes atlas bytes sequentially to the underlying file descriptor. Handles partial transfers and EINTR interrupts. On write error or unexpected EOF, sets the failed flag in the sink context and returns k_ra8_fail.

Parameters

[in,out]	ctx	Sink state (a worker_sink_t *).
[in]	buf	Atlas bytes to append.
[in]	len	Readable byte count at buf.

Returns: Sink status.

Return values

k_ra8_ok	All `len` bytes were appended successfully.
k_ra8_fail	Write operation failed or descriptor was closed.

Precondition: ctx is non-NULL and points to an open worker_sink_t structure.; buf points to at least len readable bytes.

Postcondition: On success, exactly len bytes are appended to the descriptor.; On failure, ctx->failed is set to true.

Note: Reentrant across distinct sink contexts.

Since: 0.1.0

Definition at line 119 of file jof_worker.c.

References worker_sink_t::failed, worker_sink_t::fd, k_ra8_fail, and k_ra8_ok.

Referenced by worker_produce_to_file().

Variable Documentation

◆ s_worker_riff

const uint8_t s_worker_riff[k_worker_webp_tag_len] = {'R', 'I', 'F', 'F'}

static

WebP RIFF container tag (source head bytes 0..3).

Definition at line 45 of file jof_worker.c.

Referenced by worker_is_webp().

◆ s_worker_webp

const uint8_t s_worker_webp[k_worker_webp_tag_len] = {'W', 'E', 'B', 'P'}

static

WebP form-type fourCC (source head bytes 8..11).

Definition at line 48 of file jof_worker.c.

Referenced by worker_is_webp().

Data Structures

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ worker_limit_t

◆ worker_webp_t

Function Documentation

◆ jof_worker_convert()

◆ worker_alloc_webp()

◆ worker_is_webp()

◆ worker_map_producer()

◆ worker_produce_to_file()

◆ worker_pull()

◆ worker_read_all()

◆ worker_read_source()

◆ worker_sink()

Variable Documentation

◆ s_worker_riff

◆ s_worker_webp