ra8_rabook_raster.h File Reference

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

#include <stddef.h>
#include <stdint.h>
#include "book.h"
#include "ra8_err.h"
#include "ra8_img_arena.h"
#include "ra8_webp_arena.h"

Include dependency graph for ra8_rabook_raster.h:

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

Go to the source code of this file.

Data Structures
struct	ra8_rabook_raster_workspace_t
	Exclusive caller-owned scratch used by one raster conversion. More...
struct	ra8_rabook_raster_result_t
	Geometry and byte count of a normalized RABOOK raster payload. More...

Functions
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, and WebP source bytes, optionally downscales them, and emits the exact gray4 or gray8 payload consumed by book_image_t. Every byte of working storage is supplied by the caller; the codec adapters use ra8_img_arena_t and ra8_webp_arena_t rather than the C heap. The API has no filesystem dependency, so host tools and firmware composition roots can share the same normalization path.

[Ring 3 / RABOOK Compiler] {World: NS}

Copyright

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

Since

0.1.0

Definition in file ra8_rabook_raster.h.

Function Documentation

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().