Format-agnostic book backend: book (.rabook) + epub (.epub). More...

#include <string.h>
#include "epub.h"
#include "ra8_gfx.h"
#include "reflow_image.h"
#include "sh_app.h"

Include dependency graph for sh_book.c:

Data Structures
struct	sh_strip_t
	Mutable state threaded through the XHTML strip. More...

Enumerations
enum	sh_book_const_t : uint32_t { k_sh_xhtml_cap = 256U * 1024U , k_sh_cover_cap = 512U * 1024U , k_sh_arena_cap = 64U * 1024U , k_sh_col_white = 0xFFFFFFU , k_sh_luma_r = 77U , k_sh_luma_g = 150U , k_sh_luma_b = 29U , k_sh_luma_sh = 8U , k_sh_r5_sh = 11U , k_sh_g6_sh = 5U , k_sh_r5_mask = 0x1FU , k_sh_g6_mask = 0x3FU , k_sh_5to8 = 3U , k_sh_6to8 = 2U }
	Backend buffer + format constants. More...
enum	sh_u8enc_t : uint32_t { k_u8_1max = 0x80U , k_u8_2max = 0x800U , k_u8_cont = 0x80U , k_u8_2lead = 0xC0U , k_u8_3lead = 0xE0U , k_u8_data = 0x3FU , k_u8_sh6 = 6U , k_u8_sh12 = 12U , k_ent_dec = 10U , k_ent_hex = 16U , k_ent_a10 = 10U }
	UTF-8 encode boundaries / lead-byte prefixes. More...

Functions
static bool	sh_xhtml_is_block (const char *tag, size_t n)
	Is `tag` (length `n`) a block element that should break the line?
static bool	sh_xhtml_is_suppress (const char *tag, size_t n)
	Is `tag` an element whose text content must be suppressed entirely?
static void	sh_emit_cp (char out, size_t cap, size_t pos, uint32_t cp)
	Append code point `cp` to `out` as UTF-8 (the reader folds to ASCII).
static uint32_t	sh_digit (char c, uint32_t base)
	Value of hex/decimal digit `c` in base `base`, or UINT32_MAX if invalid.
static bool	sh_parse_numeric (const char s, size_t n, size_t consumed, uint32_t *cp)
	Parse a numeric entity body #[x]NNN; at `s`; sets `cp` + `consumed`.
static bool	sh_decode_entity (const char s, size_t n, size_t consumed, uint32_t *cp)
	Decode the &..; entity at `s`; sets `cp` + `consumed`; false if invalid.
static void	sh_strip_break (char out, sh_strip_t st)
	Emit a paragraph break: trim trailing spaces, collapse runs of ' '.
static void	sh_strip_text (char out, size_t cap, sh_strip_t st, uint32_t cp)
	Emit one decoded code point as collapsed body text.
static size_t	sh_strip_tag (const uint8_t x, size_t n, size_t i, char out, sh_strip_t *st)
	Handle one <...> tag: break/suppress bookkeeping; returns index past >.
static size_t	sh_strip_xhtml (const uint8_t x, size_t n, char out, size_t cap)
	Strip XHTML `x`[0,n) to collapsed plain text in `out`; returns length.
static uint8_t	sh_luma565 (uint16_t px)
	Rec.601 luma of an RGB565 pixel (0..255).
static bool	sh_epub_thumb (uint16_t idx)
	Decode the open EPUB's cover into gray8 thumbnail slot `idx`.
bool	sh_book_decode_thumb (uint16_t idx)
	Decode the open book's cover into thumbnail slot `idx`; returns ok.
void	sh_book_cover_fullscreen (int32_t x, int32_t y, int32_t w, int32_t h)
	Draw the open book's cover full-size, aspect-fit into the box.
static void	sh_copy_str (char dst, size_t cap, const char src)
	Copy `src` into `dst` (cap bytes) NUL-terminated.
static void	sh_src_string (const book_src_t src, uint32_t off, char out, size_t cap)
	Copy the string-pool entry at pool offset `off` out of the paged source into `out` (cap bytes, always NUL-terminated).
static void	sh_book_capture_meta (uint16_t idx)
	Populate SD entry `idx` title/author/cover from the just-opened book.
static bool	sh_book_open_rabook (const sh_entry_t *e)
	Bind shelf entry `e's` RBKC container as the demand-paged source.
bool	sh_book_open (uint16_t idx)
	Open shelf entry `idx` by its format; sets g_sh.open_fmt + chapter count, and (for SD books on first open) the entry title/author/cover.
ra8_err_t	sh_book_chapter_text (uint32_t chapter, char out, size_t cap, size_t out_len)
	Extract one chapter's plain text from the open book (either backend).
static bool	sh_epub_label (uint32_t chapter, char *out, size_t cap)
	Reverse-lookup the EPUB TOC label that targets spine `chapter`.
static bool	sh_rabook_label (uint32_t chapter, char *out, size_t cap)
	Paged rabook TOC label: read the chapter record, then its string.
void	sh_book_chapter_label (uint32_t chapter, char *out, size_t cap)
	Resolve a chapter's TOC label (or "Chapter N") into `out`.

Variables
static epub_book_t	s_epub
	The open EPUB (in_use when active).
static uint8_t	s_xhtml [k_sh_xhtml_cap]
static uint8_t	s_cover [k_sh_cover_cap]
static uint8_t	s_arena [k_sh_arena_cap]
static uint16_t	s_thumb_rgb [k_sh_thumb_w *k_sh_thumb_h]

Detailed Description

Format-agnostic book backend: book (.rabook) + epub (.epub).

The shelf/cover/TOC/reader screens never touch a parser directly – they go through this backend, which dispatches on the open book's sh_book_fmt_t:

.rabook: the pre-parsed book blob, demand-paged through the chunked RBKC reader bound by sh_paged.c (#204/#205 – always paged, never a whole-book inflate). Chapter text, TOC labels, metadata strings and the 4bpp cover are all copied out of the page cache via book_src_read / book_chapter_text_src.
.epub: parsed on-device by epub (SD only), STREAMED straight off the card (#230 – the source file stays held open in sh_sd.c and every ZIP entry is seek+read on demand; no whole-file buffer, no book-size ceiling). Chapters arrive as XHTML, which this module strips to the same plain text the reader word-wraps; the cover is a compressed JPEG/PNG decoded via ra8_img_decode_blit.

[Ring 6 / App] {World: NS}

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

Since: 0.1.0

Definition in file sh_book.c.

Enumeration Type Documentation

◆ sh_book_const_t

enum sh_book_const_t : uint32_t

Backend buffer + format constants.

Enumerator
k_sh_xhtml_cap	One chapter's XHTML scratch.
k_sh_cover_cap	Compressed cover image bytes.
k_sh_arena_cap	stb_image decode bump arena.
k_sh_col_white	Thumbnail letterbox fill.
k_sh_luma_r	Rec.601 red weight (/256).
k_sh_luma_g	Rec.601 green weight.
k_sh_luma_b	Rec.601 blue weight.
k_sh_luma_sh	Rec.601 divide shift (/256).
k_sh_r5_sh	RGB565 red shift.
k_sh_g6_sh	RGB565 green shift.
k_sh_r5_mask	5-bit channel mask.
k_sh_g6_mask	6-bit channel mask.
k_sh_5to8	5-bit -> 8-bit shift.
k_sh_6to8	6-bit -> 8-bit shift.

Definition at line 36 of file sh_book.c.

◆ sh_u8enc_t

enum sh_u8enc_t : uint32_t

UTF-8 encode boundaries / lead-byte prefixes.

Enumerator
k_u8_1max	Code points below: 1 byte.
k_u8_2max	Below: 2 bytes.
k_u8_cont	Continuation prefix.
k_u8_2lead	2-byte lead prefix.
k_u8_3lead	3-byte lead prefix.
k_u8_data	Continuation payload mask.
k_u8_sh6	One continuation shift.
k_u8_sh12	Two continuation shift.
k_ent_dec	Decimal numeric-entity base.
k_ent_hex	Hex numeric-entity base.
k_ent_a10	Hex 'a'/'A' digit value.

Definition at line 91 of file sh_book.c.

Function Documentation

◆ sh_book_capture_meta()

void sh_book_capture_meta ( uint16_t idx )

static

Populate SD entry idx title/author/cover from the just-opened book.

Definition at line 402 of file sh_book.c.

References epub_metadata_t::author, sh_entry_t::author, epub_get_metadata(), g_sh, k_ra8_ok, k_sh_fmt_epub, s_epub, sh_book_decode_thumb(), sh_copy_str(), sh_src_string(), epub_metadata_t::title, and sh_entry_t::title.

Referenced by sh_book_open().

◆ sh_book_chapter_label()

void sh_book_chapter_label	(	uint32_t	chapter,
		char *	out,
		size_t	cap )

Resolve a chapter's TOC label (or "Chapter N") into out.

Definition at line 536 of file sh_book.c.

References g_sh, k_sh_fmt_rabook, sh_epub_label(), sh_fmt_uint(), and sh_rabook_label().

Referenced by sh_toc_label().

◆ sh_book_chapter_text()

ra8_err_t sh_book_chapter_text	(	uint32_t	chapter,
		char *	out,
		size_t	cap,
		size_t *	out_len )

Extract one chapter's plain text from the open book (either backend).

Parameters

[in]	chapter	Chapter index (< g_sh.chapter_count).
[out]	out	Plain-text destination.
[in]	cap	Capacity of `out`.
[out]	out_len	Receives the text length.

Returns: k_ra8_ok on success.

Since: 0.1.0

Definition at line 480 of file sh_book.c.

References book_chapter_text_src(), epub_load_chapter(), g_sh, k_ra8_ok, k_sh_fmt_epub, s_epub, s_xhtml, and sh_strip_xhtml().

Referenced by sh_reader_first_content(), and sh_reader_load_chapter().

◆ sh_book_cover_fullscreen()

void sh_book_cover_fullscreen	(	int32_t	x,
		int32_t	y,
		int32_t	w,
		int32_t	h )

Draw the open book's cover full-size, aspect-fit into the box.

Definition at line 341 of file sh_book.c.

References epub_get_cover_image(), g_sh, k_book_nil, k_ra8_ok, k_sh_fmt_epub, ra8_img_decode_blit(), s_arena, s_cover, s_epub, and sh_image_blit_cover().

Referenced by sh_cover_render().

◆ sh_book_decode_thumb()

bool sh_book_decode_thumb ( uint16_t idx )

Decode the open book's cover into thumbnail slot idx; returns ok.

Definition at line 328 of file sh_book.c.

References g_sh, k_sh_fmt_epub, sh_decode_cover(), and sh_epub_thumb().

Referenced by sh_book_capture_meta().

◆ sh_book_open()

bool sh_book_open ( uint16_t idx )

Open shelf entry idx by its format; sets g_sh.open_fmt + chapter count, and (for SD books on first open) the entry title/author/cover.

.rabook entries (baked or SD) bind the demand-paged source via sh_paged.c; .epub entries open through epub.

Parameters

[in] idx Shelf entry index (< g_sh.book_count).

Returns: true on success; false leaves no book open.

Since: 0.1.0

Definition at line 431 of file sh_book.c.

References epub_get_chapter_count(), sh_entry_t::fmt, sh_entry_t::from_sd, g_sh, k_ra8_ok, k_sh_fmt_epub, k_sh_fmt_rabook, s_epub, sh_entry_t::sd_name, sh_book_capture_meta(), sh_book_open_rabook(), sh_comic_close(), sh_comic_open(), sh_fmt_is_comic(), sh_paged_close(), sh_sd_close_epub(), and sh_sd_open_epub().

Referenced by sh_select_book().

◆ sh_book_open_rabook()

bool sh_book_open_rabook ( const sh_entry_t * e )

static

Bind shelf entry e's RBKC container as the demand-paged source.

Definition at line 419 of file sh_book.c.

References sh_entry_t::blob, sh_entry_t::blob_len, sh_entry_t::from_sd, sh_entry_t::sd_name, sh_paged_open(), sh_paged_open_mram(), sh_sd_book_open(), and sh_sd_book_read().

Referenced by sh_book_open().

◆ sh_copy_str()

void sh_copy_str	(	char *	dst,
		size_t	cap,
		const char *	src )

static

Copy src into dst (cap bytes) NUL-terminated.

Definition at line 365 of file sh_book.c.

References strncpy().

Referenced by sh_book_capture_meta(), and sh_epub_label().

◆ sh_decode_entity()

bool sh_decode_entity	(	const char *	s,
		size_t	n,
		size_t *	consumed,
		uint32_t *	cp )

static

Decode the &..; entity at s; sets cp + consumed; false if invalid.

< Name.

< Cp.

Definition at line 164 of file sh_book.c.

References sh_parse_numeric(), strlen(), and strncmp().

Referenced by sh_strip_xhtml().

◆ sh_digit()

uint32_t sh_digit	(	char	c,
		uint32_t	base )

static

Value of hex/decimal digit c in base base, or UINT32_MAX if invalid.

Definition at line 121 of file sh_book.c.

References k_ent_a10, and k_ent_hex.

Referenced by sh_parse_numeric().

◆ sh_emit_cp()

void sh_emit_cp	(	char *	out,
		size_t	cap,
		size_t *	pos,
		uint32_t	cp )

static

Append code point cp to out as UTF-8 (the reader folds to ASCII).

Definition at line 106 of file sh_book.c.

References k_u8_1max, k_u8_2lead, k_u8_2max, k_u8_3lead, k_u8_cont, k_u8_data, k_u8_sh12, and k_u8_sh6.

Referenced by sh_strip_text().

◆ sh_epub_label()

bool sh_epub_label	(	uint32_t	chapter,
		char *	out,
		size_t	cap )

static

Reverse-lookup the EPUB TOC label that targets spine chapter.

Definition at line 496 of file sh_book.c.

References epub_get_toc_count(), epub_get_toc_entry(), epub_toc_entry_to_chapter(), k_ra8_ok, s_epub, sh_copy_str(), and epub_toc_entry_t::title.

Referenced by sh_book_chapter_label().

◆ sh_epub_thumb()

bool sh_epub_thumb ( uint16_t idx )

static

Decode the open EPUB's cover into gray8 thumbnail slot idx.

Definition at line 289 of file sh_book.c.

References epub_get_cover_image(), g_sh, k_ra8_gfx_format_rgb565, k_ra8_ok, k_sh_col_white, k_sh_fb_h, k_sh_fb_w, k_sh_thumb_h, k_sh_thumb_w, ra8_gfx_clear(), ra8_gfx_init(), ra8_img_decode_blit(), s_arena, s_cover, s_epub, s_thumb_rgb, sh_fb_pixels(), and sh_luma565().

Referenced by sh_book_decode_thumb().

◆ sh_luma565()

uint8_t sh_luma565 ( uint16_t px )

static

Rec.601 luma of an RGB565 pixel (0..255).

Definition at line 280 of file sh_book.c.

References k_sh_5to8, k_sh_6to8, k_sh_g6_mask, k_sh_g6_sh, k_sh_luma_b, k_sh_luma_g, k_sh_luma_r, k_sh_luma_sh, k_sh_r5_mask, and k_sh_r5_sh.

Referenced by sh_epub_thumb().

◆ sh_parse_numeric()

bool sh_parse_numeric	(	const char *	s,
		size_t	n,
		size_t *	consumed,
		uint32_t *	cp )

static

Parse a numeric entity body #[x]NNN; at s; sets cp + consumed.

Definition at line 136 of file sh_book.c.

References k_ent_dec, k_ent_hex, and sh_digit().

Referenced by sh_decode_entity().

◆ sh_rabook_label()

bool sh_rabook_label	(	uint32_t	chapter,
		char *	out,
		size_t	cap )

static

Paged rabook TOC label: read the chapter record, then its string.

Definition at line 517 of file sh_book.c.

References book_src_read(), book_header_t::chapter_count, book_header_t::chapter_off, g_sh, book_src_t::hdr, k_ra8_ok, sh_src_string(), book_chapter_t::title_off, and book_src_t::vm.

Referenced by sh_book_chapter_label().

◆ sh_src_string()

void sh_src_string	(	const book_src_t *	src,
		uint32_t	off,
		char *	out,
		size_t	cap )

static

Copy the string-pool entry at pool offset off out of the paged source into out (cap bytes, always NUL-terminated).

Reads at most cap - 1 bytes (clamped to the pool end) through book_src_read, then terminates. Pool strings are themselves NUL-terminated, so a shorter string keeps its own terminator and a longer one truncates. On any fault out is the empty string.

Definition at line 379 of file sh_book.c.

References abs(), book_src_read(), book_src_t::hdr, k_ra8_ok, book_header_t::string_off, and book_header_t::string_size.

Referenced by sh_book_capture_meta(), and sh_rabook_label().

◆ sh_strip_break()

void sh_strip_break	(	char *	out,
		sh_strip_t *	st )

static

Emit a paragraph break: trim trailing spaces, collapse runs of '
'.

Definition at line 192 of file sh_book.c.

References sh_strip_t::at_break, and sh_strip_t::pos.

Referenced by sh_strip_tag().

◆ sh_strip_tag()

size_t sh_strip_tag	(	const uint8_t *	x,
		size_t	n,
		size_t	i,
		char *	out,
		sh_strip_t *	st )

static

Handle one <...> tag: break/suppress bookkeeping; returns index past >.

Definition at line 219 of file sh_book.c.

References sh_strip_break(), sh_xhtml_is_block(), sh_xhtml_is_suppress(), and sh_strip_t::suppress.

Referenced by sh_strip_xhtml().

◆ sh_strip_text()

void sh_strip_text	(	char *	out,
		size_t	cap,
		sh_strip_t *	st,
		uint32_t	cp )

static

Emit one decoded code point as collapsed body text.

Definition at line 204 of file sh_book.c.

References sh_strip_t::at_break, sh_strip_t::pos, and sh_emit_cp().

Referenced by sh_strip_xhtml().

◆ sh_strip_xhtml()

size_t sh_strip_xhtml	(	const uint8_t *	x,
		size_t	n,
		char *	out,
		size_t	cap )

static

Strip XHTML x[0,n) to collapsed plain text in out; returns length.

Definition at line 247 of file sh_book.c.

References k_sh_xhtml_cap, sh_strip_t::pos, sh_decode_entity(), sh_strip_tag(), sh_strip_text(), and sh_strip_t::suppress.

Referenced by sh_book_chapter_text().

◆ sh_xhtml_is_block()

bool sh_xhtml_is_block	(	const char *	tag,
		size_t	n )

static

Is tag (length n) a block element that should break the line?

Definition at line 64 of file sh_book.c.

References strlen(), and strncmp().

Referenced by sh_strip_tag().

◆ sh_xhtml_is_suppress()

bool sh_xhtml_is_suppress	(	const char *	tag,
		size_t	n )

static

Is tag an element whose text content must be suppressed entirely?

Definition at line 79 of file sh_book.c.

References strlen(), and strncmp().

Referenced by sh_strip_tag().

Variable Documentation

◆ s_arena

uint8_t s_arena[k_sh_arena_cap]

static

Definition at line 57 of file sh_book.c.

◆ s_cover

uint8_t s_cover[k_sh_cover_cap]

static

Definition at line 56 of file sh_book.c.

Referenced by ec_render_cover_or_halt(), sh_book_cover_fullscreen(), and sh_epub_thumb().

◆ s_epub

epub_book_t s_epub

static

The open EPUB (in_use when active).

Definition at line 53 of file sh_book.c.

Referenced by sh_book_capture_meta(), sh_book_chapter_text(), sh_book_cover_fullscreen(), sh_book_open(), sh_epub_label(), and sh_epub_thumb().

◆ s_thumb_rgb

uint16_t s_thumb_rgb[k_sh_thumb_w *k_sh_thumb_h]

static

Definition at line 59 of file sh_book.c.

Referenced by sh_epub_thumb().

◆ s_xhtml

uint8_t s_xhtml[k_sh_xhtml_cap]

static

Definition at line 55 of file sh_book.c.

Referenced by bind_compile(), erb_render_chapter(), and sh_book_chapter_text().

Data Structures

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ sh_book_const_t

◆ sh_u8enc_t

Function Documentation

◆ sh_book_capture_meta()

◆ sh_book_chapter_label()

◆ sh_book_chapter_text()

◆ sh_book_cover_fullscreen()

◆ sh_book_decode_thumb()

◆ sh_book_open()

◆ sh_book_open_rabook()

◆ sh_copy_str()

◆ sh_decode_entity()

◆ sh_digit()

◆ sh_emit_cp()

◆ sh_epub_label()

◆ sh_epub_thumb()

◆ sh_luma565()

◆ sh_parse_numeric()

◆ sh_rabook_label()

◆ sh_src_string()

◆ sh_strip_break()

◆ sh_strip_tag()

◆ sh_strip_text()

◆ sh_strip_xhtml()

◆ sh_xhtml_is_block()

◆ sh_xhtml_is_suppress()

Variable Documentation

◆ s_arena

◆ s_cover

◆ s_epub

◆ s_thumb_rgb

◆ s_xhtml