Callback-driven, caller-workspace image-to-JOF conversion. More...

#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include "jof_produce.h"
#include "ra8_attributes.h"
#include "ra8_fmt_stream.h"
#include "ra8_webp.h"

Include dependency graph for ra8_fmt_stream_convert.c:

Data Structures
struct	convert_pull_t
	Sequential cursor over one positioned source callback. More...

Enumerations
enum	convert_const_t : uint32_t { k_convert_band_height = 256U , k_convert_probe_bytes = 64U , k_convert_jpeg_soi = 0xD8U , k_convert_jpeg_eoi = 0xD9U , k_convert_jpeg_sos = 0xDAU , k_convert_jpeg_sof0 = 0xC0U , k_convert_jpeg_dht = 0xC4U , k_convert_jpeg_jpg = 0xC8U , k_convert_jpeg_dac = 0xCCU , k_convert_jpeg_rst_lo = 0xD0U , k_convert_jpeg_rst_hi = 0xD7U , k_convert_jpeg_tem = 0x01U , k_convert_marker = 0xFFU , k_convert_jpeg_8bit = 8U , k_convert_png_dims_end = 24U , k_convert_png_w = 16U , k_convert_png_h = 20U , k_convert_decimal_max = 20U , k_convert_decimal_base = 10U , k_convert_u32_high_shift = 24U , k_convert_jpeg_sof_last = 0xCFU , k_convert_probe_min = 12U }
	Image-probe and report constants. More...
enum	convert_png_signature_t : uint8_t { k_convert_png_sig_high = 0x89U , k_convert_png_sig_cr = 0x0DU , k_convert_png_sig_lf = 0x0AU , k_convert_png_sig_sub = 0x1AU }
	Fixed non-ASCII bytes in the PNG signature. More...
enum	convert_kind_t : uint8_t { k_convert_kind_jpeg = 0U , k_convert_kind_png = 1U , k_convert_kind_webp = 2U }
	Accepted source encoding selected by the header probe. More...

Functions
static ra8_err_t	internal_read_exact (const ra8_fmt_source_t source, uint64_t offset, uint8_t bytes, size_t len)
	Read an exact positioned source window.
static uint16_t	internal_be16 (const uint8_t bytes[2])
	Decode one big-endian uint16 field.
static uint32_t	internal_be32 (const uint8_t bytes[4])
	Decode one big-endian uint32 field.
static bool	internal_is_sof (uint8_t marker)
	Classify JPEG SOF-range markers without mistaking table markers.
static ra8_err_t	internal_jpeg_marker (const ra8_fmt_source_t source, uint64_t offset, uint8_t *marker)
	Find the next non-fill JPEG marker code.
static ra8_err_t	internal_jpeg_sof0 (const ra8_fmt_source_t source, uint64_t payload, uint16_t segment_len, uint16_t out_w, uint16_t *out_h)
	Parse and validate one baseline JPEG SOF0 segment.
static ra8_err_t	internal_jpeg_dims (const ra8_fmt_source_t source, uint16_t out_w, uint16_t *out_h)
	Walk a JPEG marker chain to its baseline SOF0 dimensions.
static ra8_err_t	internal_png_dims (const uint8_t prefix[k_convert_png_dims_end], uint16_t out_w, uint16_t out_h)
	Probe PNG dimensions from the fixed IHDR prefix.
static ra8_err_t	internal_probe (const ra8_fmt_source_t source, convert_kind_t kind, uint16_t out_w, uint16_t out_h)
	Probe the exact source kind and dimensions through positioned reads.
static ra8_err_t	internal_pull (void ctx, uint8_t bytes, size_t cap, size_t *got)
	Producer pull adapter over positioned source reads.
static ra8_err_t	internal_append (void ctx, const uint8_t bytes, size_t len)
	Producer sink adapter over the durable transaction append operation.
static void	internal_abort (ra8_fmt_transaction_t *transaction)
	Abort an active transaction after any pre-publication error.
static ra8_err_t	internal_text (const ra8_fmt_sink_t report, const char text)
	Append a NUL-terminated text fragment to a report sink.
static ra8_err_t	internal_u64 (const ra8_fmt_sink_t *report, uint64_t value)
	Append one unsigned decimal to a report sink.
static void	internal_field (const ra8_fmt_sink_t report, uint64_t value, const char suffix, ra8_err_t *status)
	Append one numeric report field and its suffix fail-fast.
static ra8_err_t	internal_report (const ra8_fmt_sink_t report, const jof_info_t info, const char *output_name)
	Emit the established successful-conversion report line.
ra8_err_t	ra8_fmt_jof_convert_requirements (const ra8_fmt_source_t source, ra8_fmt_jof_convert_requirements_t out)
	Derive source geometry and exact JOF conversion workspace needs.
ra8_err_t	ra8_fmt_jof_convert_stream (const ra8_fmt_source_t source, const ra8_fmt_jof_convert_requirements_t requirements, const ra8_fmt_jof_convert_workspace_t workspace, ra8_fmt_transaction_t transaction, const ra8_fmt_sink_t report, const char output_name)
	Stream one encoded image into a durably published JOF artifact.

Detailed Description

Callback-driven, caller-workspace image-to-JOF conversion.

Probes image geometry through positioned reads, derives the exact producer arenas, and streams the firmware JOF producer into an injected durable transaction. Host paths and descriptors never enter this engine.

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

Since: 0.1.0

Definition in file ra8_fmt_stream_convert.c.

Enumeration Type Documentation

◆ convert_const_t

enum convert_const_t : uint32_t

Image-probe and report constants.

Enumerator
k_convert_band_height	Established media-downloader band height.
k_convert_probe_bytes	WebP metadata prefix capacity.
k_convert_jpeg_soi	JPEG start-of-image marker.
k_convert_jpeg_eoi	JPEG end-of-image marker.
k_convert_jpeg_sos	JPEG start-of-scan marker.
k_convert_jpeg_sof0	Baseline sequential frame marker.
k_convert_jpeg_dht	Non-frame marker inside SOF number range.
k_convert_jpeg_jpg	Reserved non-frame marker.
k_convert_jpeg_dac	Arithmetic table non-frame marker.
k_convert_jpeg_rst_lo	First restart marker.
k_convert_jpeg_rst_hi	Last restart marker.
k_convert_jpeg_tem	Standalone TEM marker.
k_convert_marker	JPEG marker introducer.
k_convert_jpeg_8bit	Supported JPEG sample precision.
k_convert_png_dims_end	PNG prefix through IHDR dimensions.
k_convert_png_w	PNG IHDR width offset.
k_convert_png_h	PNG IHDR height offset.
k_convert_decimal_max	Decimal digits in uint64_t.
k_convert_decimal_base	Report integer radix.
k_convert_u32_high_shift	Shift of a big-endian uint32 high byte.
k_convert_jpeg_sof_last	Last JPEG SOF-range marker.
k_convert_probe_min	Smallest supported image prefix.

Definition at line 22 of file ra8_fmt_stream_convert.c.

◆ convert_kind_t

enum convert_kind_t : uint8_t

Accepted source encoding selected by the header probe.

Enumerator
k_convert_kind_jpeg	Baseline JPEG.
k_convert_kind_png	Non-interlaced PNG (producer validates body).
k_convert_kind_webp	WebP accepted by the firmware facade.

Definition at line 56 of file ra8_fmt_stream_convert.c.

◆ convert_png_signature_t

enum convert_png_signature_t : uint8_t

Fixed non-ASCII bytes in the PNG signature.

Enumerator
k_convert_png_sig_high	High-bit signature byte.
k_convert_png_sig_cr	Carriage return byte.
k_convert_png_sig_lf	Line feed byte.
k_convert_png_sig_sub	DOS EOF byte.

Definition at line 48 of file ra8_fmt_stream_convert.c.

Function Documentation

◆ internal_abort()

void internal_abort ( ra8_fmt_transaction_t * transaction )

static

Abort an active transaction after any pre-publication error.

Null-safe cleanup delegates only when a complete abort operation exists.

Parameters

[in,out] transaction Transaction to discard, or null.

Precondition: transaction is null or caller-owned transaction state.; No concurrent append or commit uses the same transaction.

Postcondition: A complete transaction receives exactly one abort call.; Null or partial transaction bindings are ignored safely.

Note: Cleanup has no status channel by transaction contract.

Since: 0.1.0

Definition at line 495 of file ra8_fmt_stream_convert.c.

References ra8_fmt_transaction_ops_t::abort, ra8_fmt_transaction_t::ctx, and ra8_fmt_transaction_t::ops.

Referenced by mdl_storage_vfs_init(), and ra8_fmt_jof_convert_stream().

◆ internal_append()

ra8_err_t internal_append	(	void *	ctx,
		const uint8_t *	bytes,
		size_t	len )

static

Producer sink adapter over the durable transaction append operation.

Delegates one exact producer byte span to the unpublished stage.

Parameters

[in,out]	ctx	Active ra8_fmt_transaction_t.
[in]	bytes	Producer output bytes.
[in]	len	Exact append length.

Returns: Transaction append status.

Return values

k_ra8_ok	Complete span was staged.
other	Injected transaction rejected the append.

Precondition: ctx names an active transaction with an append operation.; bytes spans len readable bytes.

Postcondition: Success stages exactly len additional bytes.; No publication occurs in this adapter.

Note: Thread safety inherits the transaction backend.

Since: 0.1.0

Definition at line 477 of file ra8_fmt_stream_convert.c.

References ra8_fmt_transaction_ops_t::append, ra8_fmt_transaction_t::ctx, and ra8_fmt_transaction_t::ops.

◆ internal_be16()

uint16_t internal_be16 ( const uint8_t bytes[2] )

static

Decode one big-endian uint16 field.

Assembles exactly two network-order bytes without unaligned access.

Parameters

[in] bytes Two readable source bytes.

Returns: Decoded unsigned value.

Return values

0	Both input bytes were zero.

Precondition: bytes spans two readable bytes.; The field is encoded most-significant byte first.

Postcondition: Input bytes remain unchanged.; Result equals (bytes[0] << 8) | bytes[1].

Note: Pure and thread-safe.

Since: 0.1.0

Definition at line 122 of file ra8_fmt_stream_convert.c.

Referenced by internal_jpeg_dims(), and internal_jpeg_sof0().

◆ internal_be32()

uint32_t internal_be32 ( const uint8_t bytes[4] )

static

Decode one big-endian uint32 field.

Assembles exactly four network-order bytes without unaligned access.

Parameters

[in] bytes Four readable source bytes.

Returns: Decoded unsigned value.

Return values

0	All four input bytes were zero.

Precondition: bytes spans four readable bytes.; The field is encoded most-significant byte first.

Postcondition: Input bytes remain unchanged.; Result is the four-byte big-endian assembly.

Note: Pure and thread-safe.

Since: 0.1.0

Definition at line 141 of file ra8_fmt_stream_convert.c.

References k_convert_u32_high_shift.

Referenced by internal_png_dims().

◆ internal_field()

void internal_field	(	const ra8_fmt_sink_t *	report,
		uint64_t	value,
		const char *	suffix,
		ra8_err_t *	status )

static

Append one numeric report field and its suffix fail-fast.

Centralizes bounded report composition without local formatting macros.

Parameters

[in]	report	Bound report sink.
[in]	value	Unsigned field value.
[in]	suffix	NUL-terminated field suffix.
[in,out]	status	Current and resulting report status.

Precondition: Every pointer argument is non-null.; suffix is NUL-terminated and *status is canonical.

Postcondition: Successful status attempts number then suffix in order.; A failing status prevents all later writes.

Note: Thread safety inherits the report sink.

Since: 0.1.0

Definition at line 569 of file ra8_fmt_stream_convert.c.

References internal_text(), internal_u64(), and k_ra8_ok.

Referenced by internal_report().

◆ internal_is_sof()

bool internal_is_sof ( uint8_t marker )

static

Classify JPEG SOF-range markers without mistaking table markers.

Excludes DHT, reserved JPG, and DAC codes embedded in the numeric SOF range.

Parameters

[in] marker Marker code following the 0xFF introducer.

Returns: Whether marker is any frame-header marker.

Return values

true	The marker is a JPEG frame header.
false	The marker lies outside the range or is an excluded table marker.

Precondition: marker is the byte following a JPEG marker introducer.; No entropy-coded byte stuffing is present at this scan point.

Postcondition: No state is mutated.; The result depends only on marker.

Note: Pure and thread-safe.

Since: 0.1.0

Definition at line 162 of file ra8_fmt_stream_convert.c.

References k_convert_jpeg_dac, k_convert_jpeg_dht, k_convert_jpeg_jpg, k_convert_jpeg_sof0, and k_convert_jpeg_sof_last.

Referenced by internal_jpeg_dims().

◆ internal_jpeg_dims()

ra8_err_t internal_jpeg_dims	(	const ra8_fmt_source_t *	source,
		uint16_t *	out_w,
		uint16_t *	out_h )

static

Walk a JPEG marker chain to its baseline SOF0 dimensions.

Skips length-delimited metadata without buffering it and rejects non-baseline SOF.

Parameters

[in]	source	Source whose SOI was already recognized.
[out]	out_w	Receives width.
[out]	out_h	Receives height.

Returns: Geometry, unsupported-mode, or protocol status.

Return values

k_ra8_ok	Baseline SOF0 dimensions were returned.
k_ra8_err_not_supported	A different JPEG frame mode was declared.

Precondition: source begins with a recognized SOI marker.; Both output pointers are non-null and writable.

Postcondition: Success initializes both output dimensions.; Source position and bytes remain unchanged.

Note: Loop work is bounded by the immutable source byte length.

Since: 0.1.0

Definition at line 275 of file ra8_fmt_stream_convert.c.

References internal_be16(), internal_is_sof(), internal_jpeg_marker(), internal_jpeg_sof0(), internal_read_exact(), k_convert_jpeg_eoi, k_convert_jpeg_rst_hi, k_convert_jpeg_rst_lo, k_convert_jpeg_sof0, k_convert_jpeg_soi, k_convert_jpeg_sos, k_convert_jpeg_tem, k_ra8_err_not_supported, k_ra8_err_protocol_error, k_ra8_ok, and ra8_fmt_source_t::size.

Referenced by internal_probe().

◆ internal_jpeg_marker()

ra8_err_t internal_jpeg_marker	(	const ra8_fmt_source_t *	source,
		uint64_t *	offset,
		uint8_t *	marker )

static

Find the next non-fill JPEG marker code.

Skips data before an introducer plus repeated fill bytes and rejects stuffed zero.

Parameters

[in]	source	JPEG source.
[in,out]	offset	Scan cursor.
[out]	marker	Receives marker code without introducer.

Returns: Read status or protocol failure at EOF/stuffed data.

Return values

k_ra8_ok	A complete non-zero marker code was returned.
k_ra8_err_protocol_error	Source ended or contained stuffed data before SOF.

Precondition: offset starts after SOI and before entropy-coded data.; source, offset, and marker are non-null and writable as applicable.

Postcondition: Success advances beyond one complete marker prefix/code.; Success initializes marker; failure never claims a marker.

Note: Loop work is bounded by the immutable source length.

Since: 0.1.0

Definition at line 188 of file ra8_fmt_stream_convert.c.

References internal_read_exact(), k_convert_marker, k_ra8_err_protocol_error, and k_ra8_ok.

Referenced by internal_jpeg_dims().

◆ internal_jpeg_sof0()

ra8_err_t internal_jpeg_sof0	(	const ra8_fmt_source_t *	source,
		uint64_t	payload,
		uint16_t	segment_len,
		uint16_t *	out_w,
		uint16_t *	out_h )

static

Parse and validate one baseline JPEG SOF0 segment.

Reads precision and geometry fields, enforcing the producer's axis cap.

Parameters

[in]	source	JPEG source.
[in]	payload	Offset of SOF payload after its length field.
[in]	segment_len	Declared segment length including its length field.
[out]	out_w	Receives width.
[out]	out_h	Receives height.

Returns: Geometry status.

Return values

k_ra8_ok	Valid dimensions were stored.
k_ra8_err_not_supported	Sample precision is not eight bits.

Precondition: source and both output pointers are non-null.; payload follows the two-byte length of the selected SOF0 marker.

Postcondition: Success initializes both non-zero output dimensions.; Failure performs no filesystem or transaction I/O.

Note: Thread safety inherits the positioned source callback.

Since: 0.1.0

Definition at line 229 of file ra8_fmt_stream_convert.c.

References internal_be16(), internal_read_exact(), k_convert_jpeg_8bit, k_jof_max_dim, k_ra8_err_invalid_size, k_ra8_err_not_supported, k_ra8_err_protocol_error, and k_ra8_ok.

Referenced by internal_jpeg_dims().

◆ internal_png_dims()

ra8_err_t internal_png_dims	(	const uint8_t	prefix[k_convert_png_dims_end],
		uint16_t *	out_w,
		uint16_t *	out_h )

static

Probe PNG dimensions from the fixed IHDR prefix.

Decodes both big-endian fields and enforces the JOF per-axis cap.

Parameters

[in]	prefix	Prefix through both IHDR dimension fields.
[out]	out_w	Receives width.
[out]	out_h	Receives height.

Returns: Validated geometry status.

Return values

k_ra8_ok	Both dimensions were accepted and stored.
k_ra8_err_invalid_size	A dimension was zero or over the cap.

Precondition: prefix spans through byte k_convert_png_dims_end.; Both output pointers are non-null and writable.

Postcondition: Success initializes both narrowed dimensions.; Prefix bytes remain unchanged.

Note: Pure and thread-safe.

Since: 0.1.0

Definition at line 333 of file ra8_fmt_stream_convert.c.

References internal_be32(), k_convert_png_dims_end, k_convert_png_h, k_convert_png_w, k_jof_max_dim, k_ra8_err_invalid_size, and k_ra8_ok.

Referenced by internal_probe().

◆ internal_probe()

ra8_err_t internal_probe	(	const ra8_fmt_source_t *	source,
		convert_kind_t *	kind,
		uint16_t *	out_w,
		uint16_t *	out_h )

static

Probe the exact source kind and dimensions through positioned reads.

Mirrors firmware dispatch across JPEG, PNG, and RIFF/WebP headers.

Parameters

[in]	source	Immutable image source.
[out]	kind	Receives accepted encoding kind.
[out]	out_w	Receives width.
[out]	out_h	Receives height.

Returns: Probe status.

Return values

k_ra8_ok	Encoding and dimensions were returned.
k_ra8_err_not_supported	The prefix matched no supported source.

Precondition: source and its positioned callback are non-null.; Every output pointer is non-null and writable.

Postcondition: Success initializes kind, width, and height together.; No backend cursor, source byte, or filesystem object changed.

Note: Reads at most one fixed prefix plus the JPEG marker chain.

Since: 0.1.0

Definition at line 364 of file ra8_fmt_stream_convert.c.

References internal_jpeg_dims(), internal_png_dims(), internal_read_exact(), k_convert_jpeg_soi, k_convert_kind_jpeg, k_convert_kind_png, k_convert_kind_webp, k_convert_marker, k_convert_png_dims_end, k_convert_png_sig_cr, k_convert_png_sig_high, k_convert_png_sig_lf, k_convert_png_sig_sub, k_convert_probe_bytes, k_convert_probe_min, k_jof_max_dim, k_ra8_err_invalid_size, k_ra8_err_not_supported, k_ra8_ok, memcmp(), ra8_webp_get_info(), and ra8_fmt_source_t::size.

Referenced by ra8_fmt_jof_convert_requirements().

◆ internal_pull()

ra8_err_t internal_pull	(	void *	ctx,
		uint8_t *	bytes,
		size_t	cap,
		size_t *	got )

static

Producer pull adapter over positioned source reads.

Converts a sequential producer request into a bounded absolute read.

Parameters

[in,out]	ctx	Bound convert_pull_t cursor.
[out]	bytes	Destination for up to `cap` bytes.
[in]	cap	Requested byte capacity.
[out]	got	Receives bytes supplied, including zero at EOF.

Returns: Positioned source status.

Return values

k_ra8_ok	A legal span or EOF was returned.
k_ra8_err_protocol_error	Callback claimed more than `cap` bytes.

Precondition: ctx and got are non-null.; bytes spans cap bytes when cap is non-zero.

Postcondition: Success advances the cursor by exactly *got.; The cursor never advances beyond declared source size.

Note: Not thread-safe through one shared cursor.

Since: 0.1.0

Definition at line 437 of file ra8_fmt_stream_convert.c.

References ra8_fmt_source_t::ctx, k_ra8_err_null_ptr, k_ra8_err_protocol_error, k_ra8_ok, convert_pull_t::offset, ra8_fmt_source_t::read_at, ra8_fmt_source_t::size, and convert_pull_t::source.

Referenced by internal_produce(), and ra8_fmt_jof_convert_stream().

◆ internal_read_exact()

ra8_err_t internal_read_exact	(	const ra8_fmt_source_t *	source,
		uint64_t	offset,
		uint8_t *	bytes,
		size_t	len )

static

Read an exact positioned source window.

Rejects an out-of-range request and turns a short successful read into protocol failure.

Parameters

[in]	source	Immutable source.
[in]	offset	Absolute byte offset.
[out]	bytes	Exact destination span.
[in]	len	Required byte count.

Returns: Callback status or validation failure on a short success.

Return values

k_ra8_ok	Exactly `len` bytes were read.
k_ra8_err_protocol_error	Range or returned byte count was inconsistent.

Precondition: Requested half-open range lies within the declared source size.; source, its callback, and bytes are non-null.

Postcondition: Success initializes all len bytes.; Source position and binding remain unchanged.

Note: Thread safety inherits the positioned source callback.

Since: 0.1.0

Definition at line 87 of file ra8_fmt_stream_convert.c.

References ra8_fmt_source_t::ctx, k_ra8_err_protocol_error, k_ra8_ok, ra8_fmt_source_t::read_at, and ra8_fmt_source_t::size.

Referenced by internal_jpeg_dims(), internal_jpeg_marker(), internal_jpeg_sof0(), and internal_probe().

◆ internal_report()

ra8_err_t internal_report	(	const ra8_fmt_sink_t *	report,
		const jof_info_t *	info,
		const char *	output_name )

static

Emit the established successful-conversion report line.

Reproduces legacy field order and punctuation through bounded fragments.

Parameters

[in]	report	Injected report sink.
[in]	info	Produced JOF geometry.
[in]	output_name	Destination spelling.

Returns: First sink failure or success.

Return values

k_ra8_ok	The complete report line was accepted.
other	The injected sink rejected a fragment.

Precondition: report, info, and output_name are non-null.; output_name is NUL-terminated and info describes committed bytes.

Postcondition: Success emits one newline-terminated conversion summary.; Produced geometry and destination spelling remain unchanged.

Note: Report work is independent of artifact length.

Since: 0.1.0

Definition at line 597 of file ra8_fmt_stream_convert.c.

References jof_info_t::bpp, jof_info_t::height, internal_field(), internal_text(), k_ra8_ok, jof_info_t::tile_count, jof_info_t::tile_h, jof_info_t::total_size, and jof_info_t::width.

Referenced by ra8_fmt_jof_convert_stream().

◆ internal_text()

ra8_err_t internal_text	(	const ra8_fmt_sink_t *	report,
		const char *	text )

static

Append a NUL-terminated text fragment to a report sink.

Measures the fragment and delegates one exact byte span.

Parameters

[in]	report	Bound report sink.
[in]	text	NUL-terminated text.

Returns: Injected sink status.

Return values

k_ra8_ok Complete text was accepted.

Precondition: report and its callback are non-null.; text is non-null and NUL-terminated.

Postcondition: Exactly the bytes before NUL were offered once.; Neither report binding nor source text changed.

Note: Thread safety inherits the report sink.

Since: 0.1.0

Definition at line 518 of file ra8_fmt_stream_convert.c.

References strlen().

Referenced by internal_field(), and internal_report().

◆ internal_u64()

ra8_err_t internal_u64	(	const ra8_fmt_sink_t *	report,
		uint64_t	value )

static

Append one unsigned decimal to a report sink.

Converts through fixed local buffers without locale-sensitive formatting.

Parameters

[in]	report	Bound report sink.
[in]	value	Unsigned value to render.

Returns: Injected sink status.

Return values

k_ra8_ok Complete decimal spelling was accepted.

Precondition: report and its callback are non-null.; Fixed digit storage covers every uint64_t value.

Postcondition: One non-empty base-ten spelling was offered.; No global or filesystem state changed.

Note: Thread safety inherits the report sink.

Since: 0.1.0

Definition at line 538 of file ra8_fmt_stream_convert.c.

References k_convert_decimal_base, and k_convert_decimal_max.

Referenced by internal_field().

◆ ra8_fmt_jof_convert_requirements()

ra8_err_t ra8_fmt_jof_convert_requirements	(	const ra8_fmt_source_t *	source,
		ra8_fmt_jof_convert_requirements_t *	out )

nodiscard

Derive source geometry and exact JOF conversion workspace needs.

Parameters

[in]	source	Immutable JPEG, PNG, or WebP input.
[out]	out	Receives exact arena requirements and chosen band geometry.

Returns: Probe or sizing status.

Return values

k_ra8_ok	Requirements are complete and non-zero where applicable.
k_ra8_err_not_supported	Source is not a supported baseline image.
k_ra8_err_invalid_size	Geometry, source length, or arena sizing is invalid.

Precondition: source provides a stable positioned-read callback for source->size bytes.; out is writable.

Postcondition: Success initializes every field of out.; No source byte or backend position is changed.

Note: Thread-safe for independent source contexts and caller workspaces.

Since: 0.1.0

Definition at line 615 of file ra8_fmt_stream_convert.c.

References ra8_fmt_jof_convert_requirements_t::height, internal_probe(), jof_webp_work_bytes(), jof_work_bytes(), k_convert_band_height, k_convert_kind_jpeg, k_convert_kind_webp, k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, ra8_fmt_source_t::read_at, ra8_fmt_source_t::size, ra8_fmt_jof_convert_requirements_t::tile_height, ra8_fmt_jof_convert_requirements_t::tile_width, ra8_fmt_jof_convert_requirements_t::webp_work_bytes, ra8_fmt_jof_convert_requirements_t::width, and ra8_fmt_jof_convert_requirements_t::work_bytes.

Referenced by internal_size_input(), and ra8_fmt_jof_verify_requirements().

◆ ra8_fmt_jof_convert_stream()

ra8_err_t ra8_fmt_jof_convert_stream	(	const ra8_fmt_source_t *	source,
		const ra8_fmt_jof_convert_requirements_t *	requirements,
		const ra8_fmt_jof_convert_workspace_t *	workspace,
		ra8_fmt_transaction_t *	transaction,
		const ra8_fmt_sink_t *	report,
		const char *	output_name )

nodiscard

Stream one encoded image into a durably published JOF artifact.

Parameters

[in]	source	Immutable JPEG, PNG, or WebP input.
[in]	requirements	Exact requirements derived for `source`.
[in,out]	workspace	Caller-owned exact-or-larger producer arenas.
[in,out]	transaction	Active append-only durable output transaction.
[in,out]	report	Human-readable report sink.
[in]	output_name	Stable destination spelling for the report.

Returns: Producer, transaction, or report status.

Return values

k_ra8_ok	Complete atlas was durably committed and reported.
k_ra8_err_invalid_size	A supplied arena is below its exact requirement.

Precondition: requirements came from ra8_fmt_jof_convert_requirements for source.; transaction owns an unpublished sibling stage.

Postcondition: Success commits exactly one complete JOF artifact.; Any pre-commit failure aborts the stage and preserves the prior destination.

Note: Performs no allocation and retains no caller pointer.

Since: 0.1.0

Definition at line 646 of file ra8_fmt_stream_convert.c.

References ra8_fmt_transaction_ops_t::abort, ra8_fmt_transaction_ops_t::append, ra8_fmt_transaction_ops_t::commit, ra8_fmt_transaction_t::ctx, ra8_fmt_jof_convert_requirements_t::height, internal_abort(), internal_append(), internal_pull(), internal_report(), jof_produce(), k_jof_codec_deflate, k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, ra8_fmt_transaction_t::ops, ra8_fmt_source_t::read_at, ra8_fmt_jof_convert_requirements_t::tile_height, ra8_fmt_jof_convert_requirements_t::tile_width, ra8_fmt_jof_convert_workspace_t::webp_work, ra8_fmt_jof_convert_requirements_t::webp_work_bytes, ra8_fmt_jof_convert_workspace_t::webp_work_cap, ra8_fmt_jof_convert_requirements_t::width, ra8_fmt_jof_convert_requirements_t::work_bytes, and ra8_fmt_jof_convert_workspace_t::work_cap.

Referenced by internal_run().

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ convert_const_t

◆ convert_kind_t

◆ convert_png_signature_t

Function Documentation

◆ internal_abort()

◆ internal_append()

◆ internal_be16()

◆ internal_be32()

◆ internal_field()

◆ internal_is_sof()

◆ internal_jpeg_dims()

◆ internal_jpeg_marker()

◆ internal_jpeg_sof0()

◆ internal_png_dims()

◆ internal_probe()

◆ internal_pull()

◆ internal_read_exact()

◆ internal_report()

◆ internal_text()

◆ internal_u64()

◆ ra8_fmt_jof_convert_requirements()

◆ ra8_fmt_jof_convert_stream()