ra8_rabook_comic.c File Reference

Streaming image-sequence builder for reader-native RABOOK comics. More...

#include "ra8_rabook_comic.h"
#include <stddef.h>
#include <stdint.h>
#include "book.h"
#include "ra8_attributes.h"

Include dependency graph for ra8_rabook_comic.c:

Go to the source code of this file.

Functions
static bool	internal_string_is_bounded (const char *text)
	Return whether one bounded string has a NUL terminator.
static ra8_err_t	internal_intern (ra8_rabook_ctx_t *builder, const char *text, uint32_t *out_off)
	Intern one string or classify the builder failure.
static ra8_err_t	internal_append_chapter (ra8_rabook_comic_t *comic, uint32_t page_id_off)
	Append the minimal body/img DOM and one chapter row.
static ra8_err_t	internal_store_image (ra8_rabook_comic_t *comic, uint32_t page_id_off, const ra8_rabook_raster_result_t *raster)
	Store one normalized raster and append its image descriptor.
static ra8_err_t	internal_set_metadata (ra8_rabook_comic_t *comic, const ra8_rabook_comic_metadata_t *metadata)
	Validate and intern all final metadata fields.
ra8_err_t	ra8_rabook_comic_init (ra8_rabook_comic_t *comic, const ra8_rabook_comic_workspace_t *workspace, ra8_rabook_image_read_fn image_read, ra8_rabook_comic_write_at_fn image_write, void *image_ctx, uint16_t max_image_edge, uint8_t pixel_format)
	Initialize one bounded streaming comic builder.
ra8_err_t	ra8_rabook_comic_add_page (ra8_rabook_comic_t *comic, const char *page_id, const uint8_t *source, size_t source_size)
	Normalize and append one source image as one comic chapter.
ra8_err_t	ra8_rabook_comic_finish (ra8_rabook_comic_t *comic, const ra8_rabook_comic_metadata_t *metadata, ra8_rabook_write_fn write, void *write_ctx, uint32_t *out_len)
	Finalize the completed comic as one canonical flat RABOOK1 stream.

Detailed Description

Streaming image-sequence builder for reader-native RABOOK comics.

Normalizes one encoded page at a time, stores its gray payload in a caller spool, constructs a minimal body/img DOM chapter, and streams the canonical flat RABOOK1 layout without resident image or output pools.

Copyright

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

Since

0.1.0

Definition in file ra8_rabook_comic.c.

Function Documentation

internal_append_chapter()

ra8_err_t internal_append_chapter ( ra8_rabook_comic_t * comic, uint32_t page_id_off )

static

Append the minimal body/img DOM and one chapter row.

Interns the required XML names, creates a body with one img child, binds its src to the page identifier, and publishes the matching chapter only after every preceding builder step succeeds.

Parameters

[in,out]	comic	Active comic build.
[in]	page_id_off	Interned page identifier and image href.

Returns

Builder/link status.

Return values

k_ra8_ok	One chapter rooted at a body/img tree was appended.
k_ra8_err_no_mem	A string, node, attribute, or chapter arena filled.

Returns

Link validation failures propagate unchanged.

Precondition

The page image descriptor was appended successfully.

page_id_off addresses the image id in the builder string pool.

Postcondition

Success adds exactly two nodes, one attribute, and one chapter.

Failure leaves the builder sticky failure latched when capacity caused it.

Note

Not thread-safe through comic.

Since

0.1.0

Definition at line 95 of file ra8_rabook_comic.c.

References ra8_rabook_comic_t::builder, internal_intern(), k_book_nil, k_ra8_err_no_mem, k_ra8_ok, RA8_INTERNAL, ra8_rabook_add_chapter(), ra8_rabook_add_element(), and ra8_rabook_link_child().

Referenced by ra8_rabook_comic_add_page().

internal_intern()

ra8_err_t internal_intern ( ra8_rabook_ctx_t * builder, const char * text, uint32_t * out_off )

static

Intern one string or classify the builder failure.

Translates the builder's nil-offset sentinel into the public no-memory status while preserving valid offset zero for empty text.

Parameters

[in,out]	builder	Active RABOOK table builder.
[in]	text	Bounded NUL-terminated string.
[out]	out_off	Resulting string-pool offset.

Returns

Intern status.

Return values

k_ra8_ok	The string was interned or deduplicated.
k_ra8_err_no_mem	The string pool could not hold the value.

Precondition

Pointers are non-NULL and text passed the bounded-string check.

builder was initialized and remains active.

Postcondition

Success initializes out_off to a non-nil offset or zero for empty.

Failure leaves the builder's sticky failure latched.

Note

Not thread-safe through builder.

Since

0.1.0

Definition at line 67 of file ra8_rabook_comic.c.

References k_book_nil, k_ra8_err_no_mem, k_ra8_ok, and ra8_rabook_intern().

Referenced by internal_append_chapter(), internal_set_metadata(), and ra8_rabook_comic_add_page().

internal_set_metadata()

ra8_err_t internal_set_metadata ( ra8_rabook_comic_t * comic, const ra8_rabook_comic_metadata_t * metadata )

static

Validate and intern all final metadata fields.

Bounded-validates the four public strings before mutating the header, interns them in declared order, and selects the first page as the cover image.

Parameters

[in,out]	comic	Active populated comic build.
[in]	metadata	Caller metadata strings.

Returns

Metadata validation and builder status.

Return values

k_ra8_ok	Header offsets and first-page cover were recorded.
k_ra8_err_null_ptr	metadata is NULL.
k_ra8_err_invalid_size	A string lacks a bounded terminator.
k_ra8_err_no_mem	The string arena filled.

Precondition

The comic contains at least one image descriptor.

Metadata strings remain immutable for the call.

Postcondition

Success binds every header string and cover image index zero.

Failure does not invoke the streaming finalizer.

Note

Not thread-safe through comic.

Since

0.1.0

Definition at line 201 of file ra8_rabook_comic.c.

References ra8_rabook_comic_metadata_t::author, ra8_rabook_comic_t::builder, ra8_rabook_comic_metadata_t::identifier, internal_intern(), internal_string_is_bounded(), k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, ra8_rabook_comic_metadata_t::language, RA8_INTERNAL, ra8_rabook_set_metadata(), and ra8_rabook_comic_metadata_t::title.

Referenced by ra8_rabook_comic_finish().

internal_store_image()

ra8_err_t internal_store_image ( ra8_rabook_comic_t * comic, uint32_t page_id_off, const ra8_rabook_raster_result_t * raster )

static

Store one normalized raster and append its image descriptor.

Writes at the builder's current logical image-pool end, requires an exact write, then records an external descriptor whose returned offset must agree with the write offset.

Parameters

[in,out]	comic	Active comic build.
[in]	page_id_off	Interned image identifier.
[in]	raster	Normalized raster geometry and extent.

Returns

Spool and builder status.

Return values

k_ra8_ok	Exact bytes were spooled and one descriptor was appended.
k_ra8_err_invalid_size	The spool callback reported a short write.
k_ra8_err_no_mem	The descriptor or logical image pool overflowed.

Returns

Backend failures propagate unchanged.

Precondition

comic->normalized holds raster->encoded_size readable bytes.

The image spool is private and supports this logical offset.

Postcondition

Success advances the logical image pool by exactly the encoded size.

Failure must be followed by discarding the entire private spool.

Note

Not thread-safe through comic or its spool.

Since

0.1.0

Definition at line 149 of file ra8_rabook_comic.c.

References ra8_rabook_comic_t::builder, ra8_rabook_raster_result_t::encoded_size, ra8_rabook_ctx_t::failed, ra8_rabook_raster_result_t::height, ra8_rabook_comic_t::image_ctx, ra8_rabook_ctx_t::image_pool_size, ra8_rabook_comic_t::image_write, k_book_image_gray4, k_book_nil, k_ra8_err_invalid_size, k_ra8_err_no_mem, k_ra8_err_validation_failed, k_ra8_ok, ra8_rabook_comic_t::normalized, ra8_rabook_raster_result_t::pixel_format, RA8_INTERNAL, ra8_rabook_add_image_external(), and ra8_rabook_raster_result_t::width.

Referenced by ra8_rabook_comic_add_page().

internal_string_is_bounded()

bool internal_string_is_bounded ( const char * text )

static

Return whether one bounded string has a NUL terminator.

Scans at most the public comic string limit so untrusted metadata cannot cause an unbounded read before interning.

Parameters

[in]

text

Candidate string.

Returns

Whether a terminator occurs within the comic string capacity.

Return values

true	The complete bounded string is safe for builder interning.
false	The pointer is NULL or the bounded window lacks a terminator.

Precondition

Non-NULL text spans k_ra8_rabook_comic_string_max readable bytes.

The string remains immutable for this call.

Postcondition

No input byte or builder state is modified.

At most the fixed bounded window is inspected.

Note

Pure and thread-safe.

Since

0.1.0

Definition at line 36 of file ra8_rabook_comic.c.

References k_ra8_rabook_comic_string_max, and RA8_INTERNAL.

Referenced by internal_set_metadata(), and ra8_rabook_comic_add_page().

ra8_rabook_comic_add_page()

ra8_err_t ra8_rabook_comic_add_page ( ra8_rabook_comic_t * comic, const char * page_id, const uint8_t * source, size_t source_size )

nodiscard

Normalize and append one source image as one comic chapter.

Parameters

[in,out]	comic	Active comic build.
[in]	page_id	Stable NUL-terminated page href/title.
[in]	source	Complete encoded JPEG, PNG, GIF, BMP, or WebP bytes.
[in]	source_size	Readable source byte count.

Returns

Page conversion and append status.

Return values

k_ra8_ok	One image, DOM chapter, and spool span were appended.
k_ra8_err_invalid_state	The build is inactive.
k_ra8_err_invalid_arg	An input is empty or invalid.
k_ra8_err_invalid_size	page_id lacks a bounded terminator.
k_ra8_err_no_mem	A builder, codec, or normalized arena is too small.

Returns

Raster, spool, or builder errors otherwise propagate unchanged.

Precondition

source remains readable and disjoint from comic scratch for the call.

Page identifiers are unique within one comic.

Postcondition

Success increments page, chapter, and image counts exactly once.

Failure makes the build inactive; the caller discards its private spools.

Note

The first successfully appended page becomes the cover at finish.

Since

0.1.0

Definition at line 270 of file ra8_rabook_comic.c.

References ra8_rabook_comic_t::active, ra8_rabook_comic_t::builder, internal_append_chapter(), internal_intern(), internal_store_image(), internal_string_is_bounded(), k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_ok, ra8_rabook_comic_t::max_image_edge, ra8_rabook_comic_t::normalized, ra8_rabook_comic_t::normalized_cap, ra8_rabook_comic_t::page_count, ra8_rabook_comic_t::pixel_format, ra8_rabook_raster_encode(), and ra8_rabook_comic_t::raster.

Referenced by priv_media_download_format_rabook().

ra8_rabook_comic_finish()

ra8_err_t ra8_rabook_comic_finish ( ra8_rabook_comic_t * comic, const ra8_rabook_comic_metadata_t * metadata, ra8_rabook_write_fn write, void * write_ctx, uint32_t * out_len )

nodiscard

Finalize the completed comic as one canonical flat RABOOK1 stream.

Parameters

[in,out]	comic	Active comic containing at least one page.
[in]	metadata	Complete bounded header metadata.
[in]	write	Exact append callback for the flat output.
[in,out]	write_ctx	Context passed to write.
[out]	out_len	Exact flat RABOOK1 byte length.

Returns

Metadata, finalization, or callback status.

Return values

k_ra8_ok	A complete canonical flat book was appended.
k_ra8_err_invalid_state	The build is inactive.
k_ra8_err_empty	No page was appended.
k_ra8_err_invalid_size	A metadata string lacks a bounded terminator.

Returns

Builder and callback failures otherwise propagate unchanged.

Precondition

The image spool exposes every normalized byte written by add-page calls.

write appends to a private destination that may be discarded on error.

Postcondition

The build is inactive on every return.

Success sets out_len to the exact emitted byte count.

Note

Wrap the flat result with ra8_rabook_container_write for .rabook.

Since

0.1.0

Definition at line 316 of file ra8_rabook_comic.c.

References ra8_rabook_comic_t::active, ra8_rabook_comic_t::builder, ra8_rabook_comic_t::image_ctx, ra8_rabook_comic_t::image_read, internal_set_metadata(), k_ra8_err_empty, k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_ok, ra8_rabook_comic_t::page_count, ra8_rabook_finalize_stream(), ra8_rabook_comic_t::stream_scratch, and ra8_rabook_comic_t::stream_scratch_cap.

Referenced by priv_media_download_format_rabook().

ra8_rabook_comic_init()

ra8_err_t ra8_rabook_comic_init ( ra8_rabook_comic_t * comic, const ra8_rabook_comic_workspace_t * workspace, ra8_rabook_image_read_fn image_read, ra8_rabook_comic_write_at_fn image_write, void * image_ctx, uint16_t max_image_edge, uint8_t pixel_format )

nodiscard

Initialize one bounded streaming comic builder.

Parameters

[out]	comic	Caller-owned builder state.
[in]	workspace	Complete caller-owned arenas and scratch.
[in]	image_read	Repeatable reader for the normalized image spool.
[in]	image_write	Random writer for the normalized image spool.
[in,out]	image_ctx	Context shared by the two spool callbacks.
[in]	max_image_edge	Optional longer-edge clamp; zero preserves size.
[in]	pixel_format	k_book_pixfmt_gray4 or gray8.

Returns

Initialization status.

Return values

k_ra8_ok	The empty comic is ready for pages.
k_ra8_err_null_ptr	A required pointer, callback, or arena is NULL.
k_ra8_err_invalid_arg	The requested pixel format is unsupported.
k_ra8_err_invalid_size	A required scratch capacity is zero.

Returns

Builder initialization failures propagate unchanged.

Precondition

Workspace spans are disjoint and exclusively owned for this build.

Callback context remains live until finish returns.

Postcondition

Success sets active and records zero pages.

Failure leaves comic zeroed and inactive.

Note

Not thread-safe because raster codec arena bindings are global.

Since

0.1.0

Definition at line 227 of file ra8_rabook_comic.c.

References ra8_rabook_comic_t::active, ra8_rabook_comic_t::builder, ra8_rabook_comic_workspace_t::builder, ra8_rabook_comic_t::image_ctx, ra8_rabook_comic_t::image_read, ra8_rabook_comic_t::image_write, k_book_pixfmt_gray4, k_book_pixfmt_gray8, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, ra8_rabook_comic_t::max_image_edge, ra8_rabook_comic_t::normalized, ra8_rabook_comic_workspace_t::normalized, ra8_rabook_comic_t::normalized_cap, ra8_rabook_comic_workspace_t::normalized_cap, ra8_rabook_comic_t::pixel_format, rabook_compile_init(), ra8_rabook_comic_t::raster, ra8_rabook_comic_workspace_t::raster, ra8_rabook_comic_t::stream_scratch, ra8_rabook_comic_workspace_t::stream_scratch, ra8_rabook_comic_t::stream_scratch_cap, and ra8_rabook_comic_workspace_t::stream_scratch_cap.

Referenced by priv_media_download_format_rabook().