End-to-end EPUB -> RABOOK1 compile pipeline (#149). More...

#include <stddef.h>
#include <stdint.h>
#include "epub.h"
#include "ra8_err.h"
#include "ra8_fs.h"
#include "ra8_rabook_xml_shim.h"
#include "rabook_compile.h"
#include "reflow_image.h"

Include dependency graph for ra8_rabook_pipeline.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_pipeline_scratch_t
	Caller-owned temporary buffers the pipeline stage needs. More...

Functions
ra8_err_t	rabook_compile_from_epub (epub_book_t epub, const ra8_rabook_buffers_t buffers, const ra8_rabook_pipeline_scratch_t scratch, ra8_fs_mount_t mount, const char *out_path)
	Compile an open EPUB into a RABOOK1 blob written to `out_path` on the SD filesystem.
ra8_err_t	rabook_compile_from_epub_to_buffer (epub_book_t epub, const ra8_rabook_buffers_t bufs, const ra8_rabook_pipeline_scratch_t scr, const void out_blob, uint32_t out_len)
	Compile an open EPUB into a RABOOK1 blob left in `bufs->out`, with no filesystem write.

Detailed Description

End-to-end EPUB -> RABOOK1 compile pipeline (#149).

Wires the back-end stages into a single call, in the desktop epub_compile.py emit order so the RABOOK1 blob is byte-identical:

Stylesheets – every text/css manifest item, loaded via epub_get_resource and interned, in OPF order.
Images – every image manifest item in OPF order: image/svg+xml stored verbatim, other image/ types decoded to 8-bit grayscale via stb_image, downscaled + quantised to 4-bpp (ra8_rabook_gray4_downscale / ra8_rabook_gray4_encode), and stored via ra8_rabook_add_image. The cover index is resolved from the cover manifest item.
Spine chapters – raw XHTML extracted by epub_load_chapter, parsed and DOM-built by ra8_rabook_xml_parse_chapter.
Metadata – Dublin Core from the open epub_book_t, interned LAST and recorded via ra8_rabook_set_metadata.

All working storage is caller-supplied (ra8_rabook_pipeline_scratch_t); no heap is touched (the stb_image arena is backed by the caller's img_arena). The caller is responsible for opening and closing the epub_book_t and for providing correctly-sized arenas.

NASA Rule 3 (no heap): stb_image is the sole allocation source; it is redirected to ra8_img_arena_t – a caller-owned bump arena. XML parsing uses the explicit caller-owned ra8_rabook_xml_workspace_t.

Note: Not thread-safe.

See also: rabook_compile.h Builder API (emitter).; ra8_rabook_gray4.h Image transcode stage.; ra8_rabook_xml_shim.h XHTML -> DOM stage.; epub.h EPUB reader the pipeline drives.

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

Since: Version 0.1.0

[Ring 4 / EPUB Compiler] {World: NS}

Definition in file ra8_rabook_pipeline.h.

Function Documentation

◆ rabook_compile_from_epub()

ra8_err_t rabook_compile_from_epub	(	epub_book_t *	epub,
		const ra8_rabook_buffers_t *	buffers,
		const ra8_rabook_pipeline_scratch_t *	scratch,
		ra8_fs_mount_t *	mount,
		const char *	out_path )

Compile an open EPUB into a RABOOK1 blob written to out_path on the SD filesystem.

Full pipeline, in order:

The stage order mirrors the desktop epub_compile.py so the emitted blob is byte-identical: stylesheets, then images (cover), then chapters, then metadata is interned last.

Initialise the builder context via rabook_compile_init.
For each text/css manifest item (OPF order): load it into scratch->css and add it via ra8_rabook_add_stylesheet.
If a cover image is present: extract raw bytes, decode to 8-bit grey with stb_image (using scratch->img_arena), downscale to at most the caller's opt-in max_image_edge clamp (source resolution when the field is 0, the default) on the longer edge, encode to 4-bpp, and add via ra8_rabook_add_image.
For each spine chapter (0..chapter_count): extract the raw XHTML into scratch->xhtml, look up the matching TOC entry for a title, and call ra8_rabook_xml_parse_chapter.
Read Dublin Core metadata from epub and call ra8_rabook_set_metadata (interned after the chapters).
Finalise the blob via ra8_rabook_finalize.
Write the blob to out_path via ra8_fs_write_file.

Parameters

[in,out]	epub	Open book (in_use == 1); chapters are extracted in-place from the ZIP.
[in]	buffers	Builder arenas (all non-NULL, sized for the book).
[in]	scratch	Scratch buffers for XHTML load + image decode + gray.
[in,out]	mount	Mounted filesystem volume to write `out_path` onto.
[in]	out_path	Filesystem path of the output .rabook file.

Returns: Error code.

Return values

k_ra8_ok	Book compiled and written to `out_path`.
k_ra8_err_null_ptr	Any required pointer is NULL.
k_ra8_err_no_mem	An arena overflowed, a scratch buffer was too small, or a present cover failed to transcode.
k_ra8_err_not_found	A chapter ZIP entry referenced by the spine is missing.
k_ra8_err_invalid_size	The laid-out blob exceeds the output arena (propagated from ra8_rabook_finalize).

Returns: Any other error code is propagated unchanged from the EPUB reader (epub_get_metadata / epub_load_chapter / ...) or from the filesystem write (ra8_fs_write_file).

Precondition: epub->in_use == 1.; All arenas and scratch buffers are non-NULL with valid capacities.

Postcondition: On k_ra8_ok, out_path contains a valid RABOOK1 blob.; On failure, partial output may exist at out_path.

Note: Not thread-safe.

Since: Version 0.1.0

Definition at line 21 of file ra8_rabook_pipeline_fs.c.

References k_ra8_ok, priv_rabook_pipeline_check_common(), RA8_CHECK_NULL_PTR, ra8_fs_write_file(), and rabook_compile_from_epub_to_buffer().

Referenced by rabook_import_compile_adapter().

◆ rabook_compile_from_epub_to_buffer()

ra8_err_t rabook_compile_from_epub_to_buffer	(	epub_book_t *	epub,
		const ra8_rabook_buffers_t *	bufs,
		const ra8_rabook_pipeline_scratch_t *	scr,
		const void **	out_blob,
		uint32_t *	out_len )

Compile an open EPUB into a RABOOK1 blob left in bufs->out, with no filesystem write.

Identical compile to rabook_compile_from_epub – same stages, same byte-identical desktop emit order – but it stops at ra8_rabook_finalize and returns the blob in place instead of calling ra8_fs_write_file. This is the entry point for callers with no filesystem: notably the Cortex-M33 offload (#149), which finalises into a shared SDRAM buffer and lets the M85 own the SD write. The returned *out_blob aliases bufs->out and is valid only while that arena is. A build defining RA8_RABOOK_NO_RASTER (the M33 text/CSS/SVG image) links no stb_image: raster manifest images are skipped, SVG verbatim and text/CSS are unaffected.

Parameters

[in,out]	epub	Open book (in_use == 1); chapters extracted in-place.
[in]	bufs	Builder arenas (all non-NULL, sized for the book).
[in]	scr	Scratch buffers for XHTML load + image decode + gray.
[out]	out_blob	Receives a pointer to the blob inside `bufs->out`.
[out]	out_len	Receives the blob length in bytes.

Returns: Error code.

Return values

k_ra8_ok	Book compiled; `out_blob` / `out_len` set.
k_ra8_err_null_ptr	Any required pointer is NULL.

Returns: Any other code is propagated from a compile stage or ra8_rabook_finalize (see rabook_compile_from_epub).

Precondition: epub->in_use == 1.; All arenas and scratch buffers are non-NULL with valid capacities.

Postcondition: On k_ra8_ok *out_blob addresses a valid RABOOK1 blob in bufs->out.; No filesystem state is touched.

Note: Not thread-safe.

See also: rabook_compile_from_epub The filesystem-writing variant.

Since: Version 0.1.0

Definition at line 644 of file ra8_rabook_pipeline.c.

References internal_compile_to_blob(), k_ra8_ok, priv_rabook_pipeline_check_common(), RA8_CHECK_NULL_PTR, and s_tag.

Referenced by compile_fixture(), internal_compile_temp(), and rabook_compile_from_epub().

Data Structures

Functions

Detailed Description

Function Documentation

◆ rabook_compile_from_epub()

◆ rabook_compile_from_epub_to_buffer()