ra8_rabook_comic.h File Reference

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

#include <stddef.h>
#include <stdint.h>
#include "ra8_err.h"
#include "ra8_rabook_raster.h"
#include "rabook_compile.h"

Include dependency graph for ra8_rabook_comic.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_comic_metadata_t
	Header metadata interned when the comic is finalized. More...
struct	ra8_rabook_comic_workspace_t
	Caller-owned arenas retained for one streaming comic build. More...
struct	ra8_rabook_comic_t
	Mutable state for one image-sequence-to-RABOOK build. More...

Typedefs
typedef ra8_err_t(*	ra8_rabook_comic_write_at_fn) (void *ctx, uint32_t offset, const uint8_t *source, uint32_t requested, uint32_t *out_written)
	Write normalized image bytes at one logical spool offset.

Enumerations
enum	ra8_rabook_comic_limit_t : uint16_t { k_ra8_rabook_comic_string_max = 512U }
	Bounded string dimensions accepted by the comic facade. More...

Functions
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.

Converts one encoded page at a time into a canonical RABOOK1 book. JPEG, PNG, GIF, BMP, and WebP pages pass through the shared caller-arena raster normalizer. Normalized image bytes are written to an external spool, while only bounded chapter, DOM, image, and string tables remain resident. The completed flat book is emitted through a caller append callback and can then be wrapped by ra8_rabook_container_write into the RBKC .rabook artifact. No filesystem, transport, heap, or global workspace is owned here.

[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_comic.h.

Typedef Documentation

ra8_rabook_comic_write_at_fn

typedef ra8_err_t(* ra8_rabook_comic_write_at_fn) (void *ctx, uint32_t offset, const uint8_t *source, uint32_t requested, uint32_t *out_written)

Write normalized image bytes at one logical spool offset.

Parameters

[in,out]	ctx	Caller-owned spool context.
[in]	offset	Logical image-pool byte offset.
[in]	source	Source bytes to write.
[in]	requested	Exact requested byte count.
[out]	out_written	Actual bytes accepted.

Returns

Backend status; callback-specific failures propagate unchanged.

Precondition

Pointers are non-NULL and source spans requested readable bytes.

The destination supports bounded writes at arbitrary uint32 offsets.

Postcondition

The comic builder rejects a successful short write.

No byte before offset is modified by a conforming callback.

Note

Not thread-safe unless the callback context is synchronized.

Since

0.1.0

Definition at line 53 of file ra8_rabook_comic.h.

Enumeration Type Documentation

ra8_rabook_comic_limit_t

enum ra8_rabook_comic_limit_t : uint16_t

Bounded string dimensions accepted by the comic facade.

Enumerator
k_ra8_rabook_comic_string_max	Bytes including the terminating NUL.

Definition at line 34 of file ra8_rabook_comic.h.

Function Documentation

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