Caller-arena raster normalizer for RABOOK image records. More...

#include "ra8_rabook_raster.h"
#include <limits.h>
#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include "ra8_attributes.h"
#include "ra8_img_arena.h"
#include "ra8_rabook_gray4.h"
#include "ra8_webp.h"
#include "stb_image.h"

Include dependency graph for ra8_rabook_raster.c:

Data Structures
struct	internal_decoded_raster_t
	One decoded source view and the ownership needed to release it. More...

Typedefs
typedef struct internal_decoded_raster_t	internal_decoded_raster_t
	One decoded source view and the ownership needed to release it.

Enumerations
enum	ra8_rabook_raster_consts_t : uint16_t { k_raster_webp_signature_size = 12U , k_raster_webp_form_offset = 8U , k_raster_webp_bytes_per_px = 4U , k_raster_luma_r = 77U , k_raster_luma_g = 150U , k_raster_luma_b = 29U , k_raster_luma_shift = 8U }
	Raster signature and color-conversion constants. More...

Functions
static bool	internal_is_webp (const uint8_t *source, size_t source_size)
	Return true only for a complete RIFF/WEBP signature.
static void	internal_rgba_to_gray (uint8_t *rgba, uint32_t pixels)
	Convert an in-place RGBA frame to a packed grayscale prefix.
static void	internal_output_dims (uint16_t source_width, uint16_t source_height, uint16_t max_edge, uint16_t out_width, uint16_t out_height)
	Compute output geometry, preserving dimensions when unclamped.
static ra8_err_t	internal_scale (const uint8_t source_gray, uint16_t source_width, uint16_t source_height, uint16_t out_width, uint16_t out_height, ra8_rabook_raster_workspace_t workspace, const uint8_t **out_gray)
	Select the source or caller downscale buffer for final encoding.
static ra8_err_t	internal_encode (const uint8_t gray, uint16_t width, uint16_t height, uint8_t pixel_format, uint8_t encoded, size_t encoded_cap, uint32_t *out_size)
	Encode scaled grayscale pixels at the requested device depth.
static ra8_err_t	internal_decode_webp (const uint8_t source, size_t source_size, ra8_rabook_raster_workspace_t workspace, const uint8_t *out_gray, uint16_t out_width, uint16_t *out_height)
	Decode WebP into caller RGBA storage and expose its gray prefix.
static ra8_err_t	internal_decode_stb (const uint8_t source, size_t source_size, ra8_rabook_raster_workspace_t workspace, uint8_t *out_gray, uint16_t out_width, uint16_t *out_height)
	Decode an stb-supported raster and expose arena-owned gray pixels.
static ra8_err_t	internal_decode_source (const uint8_t source, size_t source_size, ra8_rabook_raster_workspace_t workspace, internal_decoded_raster_t *decoded)
	Decode one supported source into a normalized grayscale view.
static ra8_err_t	internal_encode_source (const uint8_t source, size_t source_size, uint16_t max_edge, uint8_t pixel_format, ra8_rabook_raster_workspace_t workspace, uint8_t encoded, size_t encoded_cap, ra8_rabook_raster_result_t result)
	Scale, encode, and release one successfully validated source.
ra8_err_t	ra8_rabook_raster_encode (const uint8_t source, size_t source_size, uint16_t max_edge, uint8_t pixel_format, ra8_rabook_raster_workspace_t workspace, uint8_t encoded, size_t encoded_cap, ra8_rabook_raster_result_t result)
	Decode and normalize one encoded raster into a RABOOK image payload.

Detailed Description

Caller-arena raster normalizer for RABOOK image records.

Decodes JPEG, PNG, GIF, BMP, or WebP bytes through caller-supplied codec arenas, optionally bounds the longer edge, and emits deterministic gray4 or gray8 payloads. Codec bindings are released on every path, and no filesystem service or heap allocation is required by the normalization pipeline.

Since: 0.1.0

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

Definition in file ra8_rabook_raster.c.

Typedef Documentation

◆ internal_decoded_raster_t

typedef struct internal_decoded_raster_t internal_decoded_raster_t

One decoded source view and the ownership needed to release it.

Enumeration Type Documentation

◆ ra8_rabook_raster_consts_t

enum ra8_rabook_raster_consts_t : uint16_t

Raster signature and color-conversion constants.

Enumerator
k_raster_webp_signature_size	RIFF size plus WEBP form tag.
k_raster_webp_form_offset	WEBP form tag byte offset.
k_raster_webp_bytes_per_px	Decoded RGBA bytes per pixel.
k_raster_luma_r	stb-compatible red weight.
k_raster_luma_g	stb-compatible green weight.
k_raster_luma_b	stb-compatible blue weight.
k_raster_luma_shift	Luminance normalization shift.

Definition at line 30 of file ra8_rabook_raster.c.

Function Documentation

◆ internal_decode_source()

ra8_err_t internal_decode_source	(	const uint8_t *	source,
		size_t	source_size,
		ra8_rabook_raster_workspace_t *	workspace,
		internal_decoded_raster_t *	decoded )

static

Decode one supported source into a normalized grayscale view.

Detects WebP by signature and selects the bounded WebP or stb arena decoder, then normalizes ownership and sample access in decoded.

Parameters

[in]	source	Encoded raster bytes.
[in]	source_size	Accessible source length in bytes.
[in,out]	workspace	Caller-owned decoder arenas.
[out]	decoded	Receives normalized pixels, dimensions, and ownership.

Returns: Decoder status.

Return values

k_ra8_ok	The source decoded to a grayscale view.
k_ra8_err_validation_failed	The encoded source is malformed.
k_ra8_err_invalid_size	Source or decoded dimensions are unsupported.
k_ra8_err_no_mem	A selected bounded arena is unavailable or too small.

Precondition: All pointer arguments are non-NULL and capacities describe accessible spans.; decoded does not alias source bytes or decoder arenas.

Postcondition: Success initializes every field of decoded.; Failure does not publish a successful normalized view.

Note: Not thread-safe; decoder arena binding is process-global.

Since: Version 0.1.0

Definition at line 392 of file ra8_rabook_raster.c.

References internal_decoded_raster_t::gray, internal_decoded_raster_t::height, internal_decode_stb(), internal_decode_webp(), internal_is_webp(), internal_decoded_raster_t::stb_pixels, internal_decoded_raster_t::webp, and internal_decoded_raster_t::width.

Referenced by internal_encode_source().

◆ internal_decode_stb()

ra8_err_t internal_decode_stb	(	const uint8_t *	source,
		size_t	source_size,
		ra8_rabook_raster_workspace_t *	workspace,
		uint8_t **	out_gray,
		uint16_t *	out_width,
		uint16_t *	out_height )

static

Decode an stb-supported raster and expose arena-owned gray pixels.

Binds the caller arena, asks stb_image for one gray channel, and validates positive dimensions against the RABOOK uint16 fields. The successful allocation deliberately remains live for the caller to scale/encode before it frees and unbinds it.

Parameters

[in]	source	Encoded JPEG/PNG/GIF/BMP bytes.
[in]	source_size	Readable source length.
[in,out]	workspace	Caller stb arena descriptor.
[out]	out_gray	Receives arena-owned gray pixels.
[out]	out_width	Receives source width.
[out]	out_height	Receives source height.

Returns: Decode status.

Return values

k_ra8_ok	Gray pixels remain live in the bound arena.
k_ra8_err_invalid_size	Source length or dimensions exceed an API bound.
k_ra8_err_no_mem	No stb arena was supplied.
k_ra8_err_validation_failed	stb rejected or could not decode the source.

Precondition: All pointer arguments are non-NULL.; workspace's stb arena backing spans its declared capacity.

Postcondition: On success the image arena remains bound until the public caller frees it.; On failure the image arena is unbound before return.

Note: Not thread-safe because the stb allocator binding is global.

Since: 0.1.0

Definition at line 314 of file ra8_rabook_raster.c.

References k_ra8_err_invalid_size, k_ra8_err_no_mem, k_ra8_err_validation_failed, k_ra8_ok, ra8_img_arena_bind(), ra8_img_arena_unbind(), RA8_INTERNAL, and ra8_rabook_raster_workspace_t::stb_arena.

Referenced by internal_decode_source().

◆ internal_decode_webp()

ra8_err_t internal_decode_webp	(	const uint8_t *	source,
		size_t	source_size,
		ra8_rabook_raster_workspace_t *	workspace,
		const uint8_t **	out_gray,
		uint16_t *	out_width,
		uint16_t *	out_height )

static

Decode WebP into caller RGBA storage and expose its gray prefix.

Validates bounded dimensions, proves the full RGBA frame fits, runs the arena-backed WebP facade, then converts the frame prefix in place to deterministic grayscale.

Parameters

[in]	source	Encoded WebP bytes.
[in]	source_size	Readable source length.
[in,out]	workspace	Caller WebP arena and RGBA frame storage.
[out]	out_gray	Receives the grayscale frame prefix.
[out]	out_width	Receives source width.
[out]	out_height	Receives source height.

Returns: Decode status.

Return values

k_ra8_ok	A complete gray frame is available.
k_ra8_err_invalid_size	Dimensions exceed the RABOOK wire fields.
k_ra8_err_no_mem	Required caller storage is absent or undersized.

Returns: Other WebP validation/decode errors propagate unchanged.

Precondition: All pointer arguments are non-NULL.; Non-NULL arena/buffer members span their declared capacities.

Postcondition: On success the WebP arena is drained and outputs are initialized.; On error the output pointer/dimensions remain untouched.

Note: Not thread-safe because the WebP allocator binding is global.

Since: 0.1.0

Definition at line 241 of file ra8_rabook_raster.c.

References internal_rgba_to_gray(), k_ra8_err_invalid_size, k_ra8_err_no_mem, k_ra8_ok, k_raster_webp_bytes_per_px, RA8_INTERNAL, ra8_webp_decode_rgba(), ra8_webp_get_info(), ra8_rabook_raster_workspace_t::rgba, ra8_rabook_raster_workspace_t::rgba_cap, and ra8_rabook_raster_workspace_t::webp_arena.

Referenced by internal_decode_source().

◆ internal_encode()

ra8_err_t internal_encode	(	const uint8_t *	gray,
		uint16_t	width,
		uint16_t	height,
		uint8_t	pixel_format,
		uint8_t *	encoded,
		size_t	encoded_cap,
		uint32_t *	out_size )

static

Encode scaled grayscale pixels at the requested device depth.

Saturates a host-sized capacity to the uint32 firmware API and dispatches to gray8 copy or gray4 nibble packing.

Parameters

[in]	gray	Scaled grayscale pixels.
[in]	width	Pixel width.
[in]	height	Pixel height.
[in]	pixel_format	Valid RABOOK gray depth.
[out]	encoded	Encoded destination bytes.
[in]	encoded_cap	Writable destination capacity.
[out]	out_size	Receives the exact encoded byte count.

Returns: Encoder status.

Return values

k_ra8_ok	Payload encoded.
k_ra8_err_no_mem	Destination is too small.

Returns: Other encoder argument errors propagate unchanged.

Precondition: Pointers are non-NULL and gray spans width * height bytes.; pixel_format is gray4 or gray8.

Postcondition: On success encoded contains exactly *out_size payload bytes.; The input grayscale buffer is not modified.

Note: Thread-safe for distinct buffers.

Since: 0.1.0

Definition at line 203 of file ra8_rabook_raster.c.

References k_book_pixfmt_gray8, RA8_INTERNAL, ra8_rabook_gray4_encode(), and ra8_rabook_gray8_encode().

Referenced by internal_encode_source().

◆ internal_encode_source()

ra8_err_t internal_encode_source	(	const uint8_t *	source,
		size_t	source_size,
		uint16_t	max_edge,
		uint8_t	pixel_format,
		ra8_rabook_raster_workspace_t *	workspace,
		uint8_t *	encoded,
		size_t	encoded_cap,
		ra8_rabook_raster_result_t *	result )

static

Scale, encode, and release one successfully validated source.

Decodes to gray, derives aspect-preserving bounded dimensions, scales when required, packs the requested depth, and releases stb arena ownership on every post-decode path.

Parameters

[in]	source	Encoded raster bytes.
[in]	source_size	Accessible source length in bytes.
[in]	max_edge	Maximum output width or height in pixels.
[in]	pixel_format	Requested gray4 or gray8 output format.
[in,out]	workspace	Caller-owned decode and scale arenas.
[out]	encoded	Destination for packed output bytes.
[in]	encoded_cap	Writable bytes at `encoded`.
[out]	result	Receives dimensions, format, and encoded length on success.

Returns: Complete raster pipeline status.

Return values

k_ra8_ok	The raster was decoded, scaled, and encoded.
k_ra8_err_validation_failed	Source decoding failed.
k_ra8_err_invalid_size	Geometry or destination capacity is invalid.
k_ra8_err_no_mem	A caller-owned arena cannot satisfy the operation.

Precondition: Pointer arguments and workspace arenas passed public validation.; encoded addresses encoded_cap writable bytes disjoint from source.

Postcondition: Success fully initializes result and the reported encoded prefix.; Failure zeros result and releases any temporary stb ownership.

Note: Not thread-safe; decoder arena binding is process-global.

Since: Version 0.1.0

Definition at line 442 of file ra8_rabook_raster.c.

References ra8_rabook_raster_result_t::encoded_size, internal_decoded_raster_t::gray, internal_decoded_raster_t::height, ra8_rabook_raster_result_t::height, internal_decode_source(), internal_encode(), internal_output_dims(), internal_scale(), k_ra8_ok, ra8_rabook_raster_result_t::pixel_format, ra8_img_arena_unbind(), internal_decoded_raster_t::stb_pixels, internal_decoded_raster_t::webp, internal_decoded_raster_t::width, and ra8_rabook_raster_result_t::width.

Referenced by ra8_rabook_raster_encode().

◆ internal_is_webp()

bool internal_is_webp	(	const uint8_t *	source,
		size_t	source_size )

static

Return true only for a complete RIFF/WEBP signature.

Checks both the RIFF container tag and WEBP form tag after proving the fixed header is readable; other RIFF formats remain on the stb path and fail its decoder normally.

Parameters

[in]	source	Encoded candidate bytes.
[in]	source_size	Readable byte count at `source`.

Returns: Whether the candidate carries the WebP signature.

Return values

true	Both required tags match.
false	The header is short or either tag differs.

Precondition: source is non-NULL and spans source_size bytes.; source_size is the complete candidate byte length.

Postcondition: No input or codec state is modified.; No byte beyond the twelve-byte signature window is inspected.

Note: Pure and thread-safe.

Since: 0.1.0

Definition at line 57 of file ra8_rabook_raster.c.

References k_raster_webp_form_offset, k_raster_webp_signature_size, memcmp(), and RA8_INTERNAL.

Referenced by internal_decode_source().

◆ internal_output_dims()

void internal_output_dims	(	uint16_t	source_width,
		uint16_t	source_height,
		uint16_t	max_edge,
		uint16_t *	out_width,
		uint16_t *	out_height )

static

Compute output geometry, preserving dimensions when unclamped.

A zero clamp copies the source dimensions. A nonzero clamp delegates to the shared fixed-point RABOOK dimension helper.

Parameters

[in]	source_width	Source width in pixels.
[in]	source_height	Source height in pixels.
[in]	max_edge	Optional longer-edge limit; zero disables scaling.
[out]	out_width	Receives the output width.
[out]	out_height	Receives the output height.

Precondition: Output pointers are non-NULL and source dimensions are nonzero.; max_edge is zero or a valid nonzero pixel edge.

Postcondition: Outputs preserve the source or fit within max_edge.; Both output dimensions are nonzero.

Note: Pure and thread-safe.

Since: 0.1.0

Definition at line 111 of file ra8_rabook_raster.c.

References RA8_INTERNAL, and ra8_rabook_gray4_output_dims().

Referenced by internal_encode_source().

◆ internal_rgba_to_gray()

void internal_rgba_to_gray	(	uint8_t *	rgba,
		uint32_t	pixels )

static

Convert an in-place RGBA frame to a packed grayscale prefix.

Reads each four-byte pixel before replacing the corresponding byte in the frame prefix with stb's deterministic integer luminance.

Parameters

[in,out]	rgba	Frame containing `pixels` RGBA8888 pixels.
[in]	pixels	Number of pixels to convert.

Precondition: rgba is non-NULL and spans pixels * 4 readable/writable bytes.; pixels * 4 is representable by size_t.

Postcondition: The first pixels bytes hold grayscale samples; later bytes are unspecified scratch and no byte outside the original frame is written.; The alpha channel does not influence any grayscale sample.

Note: Pure with respect to global state; thread-safe for distinct frames.

Since: 0.1.0

Definition at line 84 of file ra8_rabook_raster.c.

References k_raster_luma_b, k_raster_luma_g, k_raster_luma_r, k_raster_luma_shift, k_raster_webp_bytes_per_px, and RA8_INTERNAL.

Referenced by internal_decode_webp().

◆ internal_scale()

ra8_err_t internal_scale	(	const uint8_t *	source_gray,
		uint16_t	source_width,
		uint16_t	source_height,
		uint16_t	out_width,
		uint16_t	out_height,
		ra8_rabook_raster_workspace_t *	workspace,
		const uint8_t **	out_gray )

static

Select the source or caller downscale buffer for final encoding.

Reuses source_gray when geometry is unchanged; otherwise checks the caller's gray capacity and fills it through the shared bilinear kernel before returning that buffer.

Parameters

[in]	source_gray	Source grayscale pixels.
[in]	source_width	Source width in pixels.
[in]	source_height	Source height in pixels.
[in]	out_width	Requested output width.
[in]	out_height	Requested output height.
[in,out]	workspace	Exclusive caller scratch descriptor.
[out]	out_gray	Receives the selected grayscale buffer.

Returns: Scaling status.

Return values

k_ra8_ok	Source or scaled pixels are ready.
k_ra8_err_no_mem	The gray scratch is absent or undersized.

Returns: Other downscale errors propagate unchanged.

Precondition: Pointer arguments are non-NULL and geometries are nonzero.; source_gray spans source_width * source_height readable bytes.

Postcondition: On success out_gray spans out_width * out_height readable bytes.; The source buffer is not modified.

Note: Thread-safe for distinct workspaces.

Since: 0.1.0

Definition at line 148 of file ra8_rabook_raster.c.

References ra8_rabook_raster_workspace_t::gray, ra8_rabook_raster_workspace_t::gray_cap, k_ra8_err_no_mem, k_ra8_ok, RA8_INTERNAL, and ra8_rabook_gray4_downscale().

Referenced by internal_encode_source().

◆ ra8_rabook_raster_encode()

ra8_err_t ra8_rabook_raster_encode	(	const uint8_t *	source,
		size_t	source_size,
		uint16_t	max_edge,
		uint8_t	pixel_format,
		ra8_rabook_raster_workspace_t *	workspace,
		uint8_t *	encoded,
		size_t	encoded_cap,
		ra8_rabook_raster_result_t *	result )

nodiscard

Decode and normalize one encoded raster into a RABOOK image payload.

WebP is selected only by its RIFF/WEBP signature; every other source is passed to stb_image, which validates its own JPEG/PNG/GIF/BMP structure. RGBA WebP pixels use stb_image's integer luminance rule (77R + 150G + 29B) >> 8, keeping codec results deterministic. A zero max_edge preserves source geometry; otherwise the longer edge is bounded through ra8_rabook_gray4_output_dims.

Parameters

[in]	source	Encoded image bytes.
[in]	source_size	Number of readable source bytes.
[in]	max_edge	Optional longer-edge clamp; zero preserves size.
[in]	pixel_format	k_book_pixfmt_gray4 or k_book_pixfmt_gray8.
[in,out]	workspace	Exclusive initialized scratch descriptor.
[out]	encoded	Destination for normalized gray payload bytes.
[in]	encoded_cap	Capacity of `encoded` in bytes.
[out]	result	Receives geometry, format, and encoded byte count.

Returns: Conversion status.

Return values

k_ra8_ok	Payload produced.
k_ra8_err_null_ptr	A required pointer is NULL.
k_ra8_err_invalid_arg	Source is empty or pixel format invalid.
k_ra8_err_invalid_size	A source/dimension exceeds a bounded API.
k_ra8_err_no_mem	Caller workspace/output is too small.
k_ra8_err_validation_failed	The encoded source is malformed.

Returns: Other WebP facade errors propagate unchanged.

Precondition: All workspace buffers and arena backings remain live for the call.; Source, scratch, and destination regions do not overlap.

Postcondition: On success encoded contains exactly result->encoded_size bytes.; On failure result is zeroed and neither codec arena remains bound.

Note: Not thread-safe because the underlying codec arena bindings are global.

Since: 0.1.0

Definition at line 490 of file ra8_rabook_raster.c.

References internal_encode_source(), k_book_pixfmt_gray4, k_book_pixfmt_gray8, k_ra8_err_invalid_arg, and k_ra8_err_null_ptr.

Referenced by ra8_rabook_comic_add_page().

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ internal_decoded_raster_t

Enumeration Type Documentation

◆ ra8_rabook_raster_consts_t

Function Documentation

◆ internal_decode_source()

◆ internal_decode_stb()

◆ internal_decode_webp()

◆ internal_encode()

◆ internal_encode_source()

◆ internal_is_webp()

◆ internal_output_dims()

◆ internal_rgba_to_gray()

◆ internal_scale()

◆ ra8_rabook_raster_encode()