Chapter / metadata / cover / glyph accessors for the EPUB reader. More...

#include <stddef.h>
#include <stdint.h>
#include <stdlib.h>
#include <string.h>
#include "miniz.h"
#include "epub.h"
#include "epub_internal.h"
#include "ra8_attributes.h"
#include "ra8_err.h"
#include "ra8_stbtt_guard.h"
#include "stb_truetype.h"

Include dependency graph for epub_chapter.c:

Enumerations
enum	epub_chapter_internal_t : uint16_t { k_epub_min_font_bytes = 16 }
	Implementation-only sizing constants. More...

Functions
bool	priv_epub_glyph_dim_invalid (int w, int h)
	Pure glyph-dim-invalid predicate.
bool	priv_epub_book_not_ready (uint8_t in_use, uint8_t zip_archive_active)
	Pure book-not-ready predicate.
void	priv_epub_join_path (const char dir, const char name, char *dst, size_t cap)
	Concatenate dir + name into dst, NUL-terminated.
static ra8_err_t	internal_locate_extract (mz_zip_archive zip, const char prefixed_path, const char bare_path, uint8_t out_buf, size_t max_len, size_t *got_len)
	Locate-then-extract a file from the open zip into a caller buffer.
static ra8_err_t	internal_font_init (const epub_book_t book, stbtt_fontinfo out_font)
	Initialise an stbtt_fontinfo from the book's font blob.
static ra8_err_t	internal_render_into (const stbtt_fontinfo font, int32_t codepoint, float font_size, uint8_t out_bitmap, size_t max_pixels, uint32_t out_w, uint32_t out_h)
	Rasterise the code point and copy into the caller buffer.
ra8_err_t	epub_get_chapter_count (const epub_book_t book, uint16_t out_count)
	Report how many chapters the spine contains.
ra8_err_t	epub_load_chapter (epub_book_t book, uint16_t idx, uint8_t out_xhtml, size_t max_len, size_t *got_len)
	Extract the raw XHTML bytes of one chapter into the caller's buffer.
ra8_err_t	epub_get_toc_kind (const epub_book_t book, uint8_t out_kind)
	Report which navigation document the TOC was parsed from.
ra8_err_t	epub_get_toc_count (const epub_book_t book, uint16_t out_count)
	Report how many table-of-contents entries the book exposes.
ra8_err_t	epub_get_toc_entry (const epub_book_t book, uint16_t idx, epub_toc_entry_t out_entry)
	Copy one table-of-contents entry into the caller's struct.
ra8_err_t	epub_toc_entry_to_chapter (const epub_book_t book, uint16_t toc_idx, uint16_t out_chapter_idx)
	Resolve a TOC entry to the spine chapter index it points into.
ra8_err_t	epub_get_metadata (const epub_book_t book, epub_metadata_t out_meta)
	Return Dublin Core metadata strings.
ra8_err_t	epub_get_cover_image (epub_book_t book, uint8_t out_buf, size_t max_len, size_t *got_len)
	Copy the raw bytes of the cover image into the caller's buffer.
ra8_err_t	epub_get_resource (epub_book_t book, const char path, uint8_t out_buf, size_t max_len, size_t got_len)
	Copy the raw bytes of an arbitrary archive resource into the caller's buffer (#140 external stylesheets, and any href-referenced resource).
ra8_err_t	epub_get_embedded_font_count (const epub_book_t book, uint16_t out_count)
	Count the fonts the EPUB ships in its OPF manifest (#109).
uint16_t	epub_manifest_count (const epub_book_t *book)
	Number of <manifest> <item> entries retained (#151).
const epub_manifest_item_t *	epub_manifest_item (const epub_book_t *book, uint16_t index)
	Borrow the manifest item at `index` (OPF document order, #151).
ra8_err_t	epub_get_embedded_font (epub_book_t book, uint16_t idx, uint8_t out_buf, size_t max_len, size_t *got_len)
	Extract one EPUB-shipped font's bytes into a caller buffer (#109).
ra8_err_t	epub_set_font (epub_book_t book, const uint8_t font_data, size_t font_size)
	Attach a TTF font blob to be used by epub_render_glyph().
ra8_err_t	epub_render_glyph (const epub_book_t book, int32_t codepoint, float font_size, uint8_t out_bitmap, size_t max_pixels, uint32_t out_w, uint32_t out_h)
	Rasterise a single Unicode code point into an alpha-8 bitmap.

Detailed Description

Chapter / metadata / cover / glyph accessors for the EPUB reader.

The functions in this TU all read against an already-open epub_book_t:

epub_get_chapter_count() – size of the spine.
epub_load_chapter() – extract one XHTML body via miniz.
epub_get_metadata() – title / author / language strings.
epub_get_cover_image() – raw bytes of the cover, decoded by the caller via stb_image.
epub_set_font() – attach a TTF blob.
epub_render_glyph() – rasterise a code point via stb_truetype into an alpha-8 buffer.

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

[Ring 4 / EPUB] {World: NS}

Definition in file epub_chapter.c.

Enumeration Type Documentation

◆ epub_chapter_internal_t

enum epub_chapter_internal_t : uint16_t

Implementation-only sizing constants.

Enumerator
k_epub_min_font_bytes	Smallest TTF blob we'll accept.

Definition at line 53 of file epub_chapter.c.

Function Documentation

◆ epub_get_chapter_count()

ra8_err_t epub_get_chapter_count	(	const epub_book_t *	book,
		uint16_t *	out_count )

nodiscard

Report how many chapters the spine contains.

Parameters

[in]	book	Open book.
[out]	out_count	Chapter count.

Return values

k_ra8_ok	Reported.
k_ra8_err_null_ptr	Any pointer NULL.
k_ra8_err_not_initialized	book->in_use == 0.

Precondition: book non-NULL, out_count non-NULL.

Postcondition: *out_count <= k_epub_max_chapters.

Since: 0.1.0

Definition at line 310 of file epub_chapter.c.

References epub_book_t::chapter_count, epub_book_t::in_use, k_ra8_err_not_initialized, k_ra8_err_null_ptr, and k_ra8_ok.

Referenced by eoh_parse_or_halt(), ep_parse_or_halt(), est_open_or_halt(), etoc_check_bad(), internal_compile_chapters(), and sh_book_open().

◆ epub_get_cover_image()

ra8_err_t epub_get_cover_image	(	epub_book_t *	book,
		uint8_t *	out_buf,
		size_t	max_len,
		size_t *	got_len )

nodiscard

Copy the raw bytes of the cover image into the caller's buffer.

The image is returned in its on-disk encoding (PNG / JPEG / GIF). The caller decodes it with stb_image (see apps/shared_libs/third_party/stb) or any other decoder.

Parameters

[in]	book	Open book.
[out]	out_buf	Destination buffer.
[in]	max_len	Capacity of out_buf, bytes.
[out]	got_len	Bytes actually written.

Return values

k_ra8_ok	Cover copied.
k_ra8_err_null_ptr	Any pointer NULL.
k_ra8_err_not_initialized	book->in_use == 0.
k_ra8_err_invalid_size	max_len == 0.
k_ra8_err_not_found	No cover image declared.
k_ra8_err_no_mem	Cover does not fit in max_len.

Since: 0.1.0

Definition at line 444 of file epub_chapter.c.

References epub_book_t::cover_path, epub_book_t::in_use, internal_locate_extract(), k_epub_max_path_len, k_ra8_err_invalid_size, k_ra8_err_not_found, k_ra8_err_not_initialized, k_ra8_err_null_ptr, epub_book_t::opf_dir, priv_epub_book_not_ready(), priv_epub_join_path(), epub_book_t::zip_archive_active, and epub_book_t::zip_archive_storage.

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

◆ epub_get_embedded_font()

ra8_err_t epub_get_embedded_font	(	epub_book_t *	book,
		uint16_t	idx,
		uint8_t *	out_buf,
		size_t	max_len,
		size_t *	got_len )

nodiscard

Extract one EPUB-shipped font's bytes into a caller buffer (#109).

Joins the recorded font href onto the OPF directory and extracts the resource from the open ZIP (same path as epub_get_cover_image()). The returned bytes can be validated + bound into the reflow engine via reflow_bind_font(), or attached with epub_set_font().

Parameters

[in,out]	book	Open book.
[in]	idx	Font index, 0 .. epub_get_embedded_font_count()-1.
[out]	out_buf	Destination buffer for the raw font bytes.
[in]	max_len	Capacity of `out_buf`, bytes.
[out]	got_len	Bytes actually written.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Font copied; *got_len > 0.
k_ra8_err_null_ptr	`book`, `out_buf`, or `got_len` is NULL.
k_ra8_err_not_initialized	book->in_use == 0.
k_ra8_err_invalid_size	max_len == 0.
k_ra8_err_out_of_range	idx >= embedded_font_count.
k_ra8_err_no_mem	Font does not fit in `max_len`.
k_ra8_err_not_found	Recorded font href missing from the archive.

Precondition: book->in_use == 1 and idx < epub_get_embedded_font_count().; out_buf and got_len are non-NULL, max_len > 0.

Postcondition: On success *got_len holds the font length; on failure *got_len == 0.

Note: Not thread-safe; single-threaded init-context use.

See also: epub_get_embedded_font_count(), reflow_bind_font()

Since: 0.1.0

Definition at line 527 of file epub_chapter.c.

References epub_book_t::embedded_font_count, epub_book_t::embedded_font_paths, epub_book_t::in_use, internal_locate_extract(), k_epub_max_path_len, k_ra8_err_invalid_size, k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_err_out_of_range, epub_book_t::opf_dir, priv_epub_book_not_ready(), priv_epub_join_path(), epub_book_t::zip_archive_active, and epub_book_t::zip_archive_storage.

◆ epub_get_embedded_font_count()

ra8_err_t epub_get_embedded_font_count	(	const epub_book_t *	book,
		uint16_t *	out_count )

nodiscard

Count the fonts the EPUB ships in its OPF manifest (#109).

During epub_open() the manifest is scanned for <item> entries whose media-type is a known font type (application/font-sfnt, application/vnd.ms-opentype, font/ttf, font/otf, application/x-font-ttf); their hrefs are recorded (up to k_epub_max_fonts). This returns how many were found so the caller can iterate epub_get_embedded_font(). Zero is normal – many books rely on the reading-system font.

Parameters

[in]	book	Open book.
[out]	out_count	Receives the embedded font count (0 .. k_epub_max_fonts).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Count written.
k_ra8_err_null_ptr	`book` or `out_count` is NULL.
k_ra8_err_not_initialized	book->in_use == 0.

Precondition: book->in_use == 1.; out_count is non-NULL.

Postcondition: *out_count <= k_epub_max_fonts.; book is unmodified.

Note: Not thread-safe; single-threaded init-context use.

See also: epub_get_embedded_font()

Since: 0.1.0

Definition at line 493 of file epub_chapter.c.

References epub_book_t::embedded_font_count, epub_book_t::in_use, k_ra8_err_not_initialized, k_ra8_err_null_ptr, and k_ra8_ok.

◆ epub_get_metadata()

ra8_err_t epub_get_metadata	(	const epub_book_t *	book,
		epub_metadata_t *	out_meta )

nodiscard

Return Dublin Core metadata strings.

The returned const char* pointers alias book storage and are valid until epub_close() is called. Missing fields point at the empty string "", never NULL.

Parameters

[in]	book	Open book.
[out]	out_meta	Populated metadata struct on success.

Return values

k_ra8_ok	Reported.
k_ra8_err_null_ptr	Any pointer NULL.
k_ra8_err_not_initialized	book->in_use == 0.

Since: 0.1.0

Definition at line 429 of file epub_chapter.c.

References epub_book_t::author, epub_metadata_t::author, epub_book_t::identifier, epub_metadata_t::identifier, epub_book_t::in_use, k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_ok, epub_book_t::language, epub_metadata_t::language, epub_book_t::title, and epub_metadata_t::title.

Referenced by eoh_parse_or_halt(), ep_parse_or_halt(), internal_compile_metadata(), and sh_book_capture_meta().

◆ epub_get_resource()

ra8_err_t epub_get_resource	(	epub_book_t *	book,
		const char *	path,
		uint8_t *	out_buf,
		size_t	max_len,
		size_t *	got_len )

nodiscard

Copy the raw bytes of an arbitrary archive resource into the caller's buffer (#140 external stylesheets, and any href-referenced resource).

Generic by-path extraction from the open ZIP – the same path the cover, embedded fonts, and chapters use. path is resolved relative to the OPF directory (book->opf_dir), with a fall-back to path taken as an archive-rooted path; so "style.css", "css/main.css", and a bare "OEBPS/style.css" all resolve. The bytes are returned exactly as stored (decompressed); the caller owns out_buf and interprets them (e.g. CSS text fed to ra8_css_parse() via a reflow css-loader).

Parameters

[in]	book	Open book (in_use == 1, archive active).
[in]	path	Resource path, OPF-dir-relative or archive-rooted, NUL-terminated.
[out]	out_buf	Destination buffer.
[in]	max_len	Capacity of `out_buf`, bytes.
[out]	got_len	Bytes actually written.

Return values

k_ra8_ok	Resource copied.
k_ra8_err_null_ptr	Any pointer NULL.
k_ra8_err_not_initialized	Book not open / archive inactive.
k_ra8_err_invalid_size	max_len == 0.
k_ra8_err_not_found	No entry at `path` (prefixed or bare).
k_ra8_err_no_mem	Resource does not fit in `max_len`.

Precondition: book->in_use == 1 and the archive is active.; path, out_buf, got_len are non-NULL; max_len > 0.

Postcondition: On success *got_len bytes are written to out_buf.; On any error *got_len == 0.

Note: Not thread-safe; single-threaded reader context.

See also: epub_get_cover_image(), epub_get_embedded_font()

Since: 0.1.0

Definition at line 468 of file epub_chapter.c.

References epub_book_t::in_use, internal_locate_extract(), k_epub_max_path_len, k_ra8_err_invalid_size, k_ra8_err_not_initialized, k_ra8_err_null_ptr, epub_book_t::opf_dir, priv_epub_book_not_ready(), priv_epub_join_path(), epub_book_t::zip_archive_active, and epub_book_t::zip_archive_storage.

Referenced by internal_add_manifest_image(), and internal_compile_stylesheets().

◆ epub_get_toc_count()

ra8_err_t epub_get_toc_count	(	const epub_book_t *	book,
		uint16_t *	out_count )

nodiscard

Report how many table-of-contents entries the book exposes.

The count is the flattened (depth-first) entry total parsed from the book's NCX or nav document; 0 means no usable TOC was found. Use epub_get_toc_entry() to read each entry's title, href, and depth.

Parameters

[in]	book	Open book.
[out]	out_count	Entry count.

Returns: ra8_err_t

Return values

k_ra8_ok	Reported.
k_ra8_err_null_ptr	Any pointer NULL.
k_ra8_err_not_initialized	book->in_use == 0.

Precondition: book non-NULL, out_count non-NULL.; book->in_use == 1.

Postcondition: *out_count <= k_epub_max_toc.

Since: 0.1.0

Definition at line 367 of file epub_chapter.c.

References epub_book_t::in_use, k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_ok, and epub_book_t::toc_count.

Referenced by est_open_or_halt(), etoc_read_toc(), internal_compile_chapters(), and sh_epub_label().

◆ epub_get_toc_entry()

ra8_err_t epub_get_toc_entry	(	const epub_book_t *	book,
		uint16_t	idx,
		epub_toc_entry_t *	out_entry )

nodiscard

Copy one table-of-contents entry into the caller's struct.

Parameters

[in]	book	Open book.
[in]	idx	Entry index, [0, toc_count).
[out]	out_entry	Destination entry (title, href, depth) on success.

Returns: ra8_err_t

Return values

k_ra8_ok	Entry copied.
k_ra8_err_null_ptr	Any pointer NULL.
k_ra8_err_not_initialized	book->in_use == 0.
k_ra8_err_out_of_range	idx >= toc_count.

Precondition: book non-NULL, out_entry non-NULL.; book->in_use == 1.

Postcondition: On success, *out_entry is a NUL-terminated, bounded copy.; On failure, *out_entry is left unmodified.

Since: 0.1.0

Definition at line 379 of file epub_chapter.c.

References epub_book_t::in_use, k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_err_out_of_range, k_ra8_ok, epub_book_t::toc, and epub_book_t::toc_count.

Referenced by etoc_read_toc(), internal_chapter_title(), and sh_epub_label().

◆ epub_get_toc_kind()

ra8_err_t epub_get_toc_kind	(	const epub_book_t *	book,
		uint8_t *	out_kind )

nodiscard

Report which navigation document the TOC was parsed from.

Parameters

[in]	book	Open book.
[out]	out_kind	Receives a epub_toc_kind_t value.

Returns: ra8_err_t

Return values

k_ra8_ok	Reported.
k_ra8_err_null_ptr	Any pointer NULL.
k_ra8_err_not_initialized	book->in_use == 0.

Precondition: book non-NULL, out_kind non-NULL.; book->in_use == 1.

Postcondition: *out_kind is one of the epub_toc_kind_t enumerators.; *out_kind == k_epub_toc_none iff toc_count == 0.

Since: 0.1.0

Definition at line 355 of file epub_chapter.c.

References epub_book_t::in_use, k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_ok, and epub_book_t::toc_kind.

Referenced by etoc_check_bad(), and etoc_read_toc().

◆ epub_load_chapter()

ra8_err_t epub_load_chapter	(	epub_book_t *	book,
		uint16_t	idx,
		uint8_t *	out_xhtml,
		size_t	max_len,
		size_t *	got_len )

nodiscard

Extract the raw XHTML bytes of one chapter into the caller's buffer.

Parameters

[in]	book	Open book.
[in]	idx	Chapter index, [0, chapter_count).
[out]	out_xhtml	Destination buffer (caller-owned).
[in]	max_len	Capacity of out_xhtml, bytes.
[out]	got_len	Bytes actually written (0 on failure).

Return values

k_ra8_ok	Chapter copied (got_len <= max_len).
k_ra8_err_null_ptr	Any pointer NULL.
k_ra8_err_not_initialized	book->in_use == 0.
k_ra8_err_out_of_range	idx >= chapter_count.
k_ra8_err_invalid_size	max_len == 0.
k_ra8_err_no_mem	Chapter does not fit in max_len.
k_ra8_err_not_found	Manifest references a missing zip entry.

Precondition: book non-NULL, book->in_use == 1.

Postcondition: On success, *got_len > 0. On failure, *got_len == 0.

Since: 0.1.0

Definition at line 322 of file epub_chapter.c.

References epub_book_t::chapter_count, epub_book_t::chapter_paths, epub_book_t::in_use, internal_locate_extract(), k_epub_max_path_len, k_ra8_err_invalid_size, k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_err_out_of_range, epub_book_t::opf_dir, priv_epub_book_not_ready(), priv_epub_join_path(), epub_book_t::zip_archive_active, and epub_book_t::zip_archive_storage.

Referenced by eoh_parse_or_halt(), ep_parse_or_halt(), internal_compile_chapters(), and sh_book_chapter_text().

◆ epub_manifest_count()

uint16_t epub_manifest_count ( const epub_book_t * book )

nodiscard

Number of <manifest> <item> entries retained (#151).

epub_open() records every manifest item – id, href, media-type – in OPF document order, up to k_epub_max_manifest. The on-device compiler walks them in that order to emit the stylesheet and image tables, matching the desktop epub_compile.py (manifest.items()), which keeps the blob byte-identical.

Parameters

[in] book Open book (in_use == 1).

Returns: Item count (0 .. k_epub_max_manifest), or 0 if book is NULL.

Return values

0	No items, a closed book, or a NULL handle.

Precondition: book was populated by epub_open().; The caller treats the count as a read-only snapshot.

Postcondition: No state is mutated.

Note: Not thread-safe; single-threaded reader context.

See also: epub_manifest_item()

Since: 0.1.0

Definition at line 505 of file epub_chapter.c.

References epub_book_t::in_use, and epub_book_t::manifest_count.

Referenced by internal_compile_images(), and internal_compile_stylesheets().

◆ epub_manifest_item()

const epub_manifest_item_t * epub_manifest_item	(	const epub_book_t *	book,
		uint16_t	index )

nodiscard

Borrow the manifest item at index (OPF document order, #151).

Returns a const pointer into the book's retained manifest array; the storage lives in book and stays valid until epub_close(). The caller must not write through the pointer.

Parameters

[in]	book	Open book (in_use == 1).
[in]	index	Zero-based item index, < epub_manifest_count(book).

Returns: Pointer to the item, or NULL if book is NULL or index is out of range.

Return values

NULL	`book` is NULL or `index` >= the retained count.

Precondition: book was populated by epub_open().; index is less than epub_manifest_count for book.

Postcondition: No state is mutated; the returned storage is owned by book.

Note: Not thread-safe; single-threaded reader context.

See also: epub_manifest_count()

Since: 0.1.0

Definition at line 516 of file epub_chapter.c.

References epub_book_t::in_use, epub_book_t::manifest, and epub_book_t::manifest_count.

Referenced by internal_compile_images(), and internal_compile_stylesheets().

◆ epub_render_glyph()

ra8_err_t epub_render_glyph	(	const epub_book_t *	book,
		int32_t	codepoint,
		float	font_size,
		uint8_t *	out_bitmap,
		size_t	max_pixels,
		uint32_t *	out_w,
		uint32_t *	out_h )

nodiscard

Rasterise a single Unicode code point into an alpha-8 bitmap.

Wraps stbtt_GetCodepointBitmap() against the font installed via epub_set_font(). The resulting bitmap is 8 bits per pixel, grayscale, with the glyph's advance and side-bearing dropped (the caller positions glyphs on the page).

Parameters

[in]	book	Open book with a font installed.
[in]	codepoint	Unicode code point (e.g. 'A').
[in]	font_size	Pixel size for the rasteriser.
[out]	out_bitmap	Destination buffer (caller-owned).
[in]	max_pixels	Capacity of out_bitmap, in bytes.
[out]	out_w	Glyph width in pixels.
[out]	out_h	Glyph height in pixels.

Return values

k_ra8_ok	Glyph rasterised.
k_ra8_err_null_ptr	Any pointer NULL.
k_ra8_err_not_initialized	book->in_use == 0 or no font set.
k_ra8_err_invalid_arg	font_size <= 0.
k_ra8_err_no_mem	Glyph does not fit in max_pixels.
k_ra8_err_validation_failed	Font blob malformed.

Since: 0.1.0

Definition at line 576 of file epub_chapter.c.

References epub_book_t::font_data, epub_book_t::in_use, internal_font_init(), internal_render_into(), k_ra8_err_invalid_arg, k_ra8_err_not_initialized, k_ra8_err_null_ptr, and k_ra8_ok.

◆ epub_set_font()

ra8_err_t epub_set_font	(	epub_book_t *	book,
		const uint8_t *	font_data,
		size_t	font_size )

nodiscard

Attach a TTF font blob to be used by epub_render_glyph().

epub does not embed a default font; the caller (or the host application) must point the book at a TTF blob that lives for the lifetime of the book. Typical sources are:

A font baked into the firmware image as a static const.
A font/-prefixed manifest entry inside the EPUB, extracted via epub_load_chapter() style code into a caller buffer.

Parameters

[in,out]	book	Open book.
[in]	font_data	TTF buffer; must outlive book.
[in]	font_size	Length of font_data, bytes.

Return values

k_ra8_ok	Font installed.
k_ra8_err_null_ptr	Any pointer NULL.
k_ra8_err_not_initialized	book->in_use == 0.
k_ra8_err_invalid_size	font_size < 16.

Since: 0.1.0

Definition at line 560 of file epub_chapter.c.

References epub_book_t::font_data, epub_book_t::font_size, epub_book_t::in_use, k_epub_min_font_bytes, k_ra8_err_invalid_size, k_ra8_err_not_initialized, k_ra8_err_null_ptr, and k_ra8_ok.

◆ epub_toc_entry_to_chapter()

ra8_err_t epub_toc_entry_to_chapter	(	const epub_book_t *	book,
		uint16_t	toc_idx,
		uint16_t *	out_chapter_idx )

nodiscard

Resolve a TOC entry to the spine chapter index it points into.

Makes the parsed TOC navigable: a TOC entry's href is an OPF-relative path with an optional #fragment (e.g. ch3.xhtml#sec2), whereas epub_load_chapter() is indexed by spine position. This strips any fragment from the entry href and returns the index of the first spine chapter (chapter_paths) whose path matches, suitable to hand to epub_load_chapter().

Parameters

[in]	book	Open book.
[in]	toc_idx	TOC entry index, [0, toc_count).
[out]	out_chapter_idx	Spine chapter index on success.

Returns: ra8_err_t

Return values

k_ra8_ok	Resolved; *out_chapter_idx < chapter_count.
k_ra8_err_null_ptr	Any pointer NULL.
k_ra8_err_not_initialized	book->in_use == 0.
k_ra8_err_out_of_range	toc_idx >= toc_count.
k_ra8_err_not_found	The entry points outside the spine.

Precondition: book non-NULL, out_chapter_idx non-NULL.; book->in_use == 1.

Postcondition: On success, *out_chapter_idx indexes a valid spine chapter.; On failure, *out_chapter_idx is left unmodified.

Since: 0.1.0

Definition at line 395 of file epub_chapter.c.

References epub_book_t::chapter_count, epub_book_t::chapter_paths, epub_toc_entry_t::href, epub_book_t::in_use, k_ra8_err_not_found, k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_err_out_of_range, k_ra8_ok, strlen(), strncmp(), epub_book_t::toc, and epub_book_t::toc_count.

Referenced by etoc_read_toc(), internal_chapter_title(), and sh_epub_label().

◆ internal_font_init()

ra8_err_t internal_font_init	(	const epub_book_t *	book,
		stbtt_fontinfo *	out_font )

static

Initialise an stbtt_fontinfo from the book's font blob.

Returns: k_ra8_ok on success; k_ra8_err_validation_failed on a malformed / non-TTF blob.

See implementation.

Parameters

[in]	book	See implementation.
[in]	out_font	See implementation.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 219 of file epub_chapter.c.

References epub_book_t::font_data, epub_book_t::font_size, k_ra8_err_validation_failed, k_ra8_ok, and ra8_stbtt_sfnt_dir_in_bounds().

Referenced by epub_render_glyph().

◆ internal_locate_extract()

ra8_err_t internal_locate_extract	(	mz_zip_archive *	zip,
		const char *	prefixed_path,
		const char *	bare_path,
		uint8_t *	out_buf,
		size_t	max_len,
		size_t *	got_len )

static

Locate-then-extract a file from the open zip into a caller buffer.

Looks up prefixed_path first; on miss falls back to bare_path (some EPUBs store hrefs without the OPF directory prefix).

See implementation.

Parameters

[in]	zip	See implementation.
[in]	prefixed_path	See implementation.
[in]	bare_path	See implementation.
[in]	out_buf	See implementation.
[in]	max_len	See implementation.
[in]	got_len	See implementation.

Returns: Result code.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 165 of file epub_chapter.c.

References k_ra8_err_no_mem, k_ra8_err_not_found, k_ra8_err_validation_failed, k_ra8_ok, and priv_epub_zip_guard_entry().

Referenced by epub_get_cover_image(), epub_get_embedded_font(), epub_get_resource(), and epub_load_chapter().

◆ internal_render_into()

ra8_err_t internal_render_into	(	const stbtt_fontinfo *	font,
		int32_t	codepoint,
		float	font_size,
		uint8_t *	out_bitmap,
		size_t	max_pixels,
		uint32_t *	out_w,
		uint32_t *	out_h )

static

Rasterise the code point and copy into the caller buffer.

Splits the second half of epub_render_glyph out so that function stays under the NASA-Rule-4 statement budget enforced by clang-tidy (readability-function-size).

See implementation.

Parameters

[in]	font	See implementation.
[in]	codepoint	See implementation.
[in]	font_size	See implementation.
[in]	out_bitmap	See implementation.
[in]	max_pixels	See implementation.
[in]	out_w	See implementation.
[in]	out_h	See implementation.

Returns: Result code.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 265 of file epub_chapter.c.

References k_ra8_err_no_mem, k_ra8_err_validation_failed, k_ra8_ok, and priv_epub_glyph_dim_invalid().

Referenced by epub_render_glyph().

◆ priv_epub_book_not_ready()

bool priv_epub_book_not_ready	(	uint8_t	in_use,
		uint8_t	zip_archive_active )

Pure book-not-ready predicate.

Pure predicate: book unused OR zip archive inactive.

Promoted helper so the line-300/369 OR can be driven under MC/DC.

Parameters

[in]	in_use	Book "in_use" byte.
[in]	zip_archive_active	Book "zip_archive_active" byte.

Returns: Boolean reject predicate.

Return values

true	Caller returns not-initialized.
false	Book is ready.

Precondition: None.; None.

Postcondition: No state mutated.; Return depends solely on inputs.

Note: Pure; thread-safe.

Since: 0.1.0

Definition at line 97 of file epub_chapter.c.

References RA8_PRIV.

Referenced by epub_entry_open(), epub_entry_pread(), epub_get_cover_image(), epub_get_embedded_font(), epub_get_resource(), and epub_load_chapter().

◆ priv_epub_glyph_dim_invalid()

bool priv_epub_glyph_dim_invalid	(	int	w,
		int	h )

Pure glyph-dim-invalid predicate.

Pure predicate: width OR height is negative.

Promoted helper so the line-225 OR can be driven under MC/DC.

Parameters

[in]	w	Glyph bbox width.
[in]	h	Glyph bbox height.

Returns: Boolean reject predicate.

Return values

true	Caller returns validation-failed.
false	Both dimensions OK.

Precondition: None.; None.

Postcondition: No state mutated.; Return depends solely on inputs.

Note: Pure; thread-safe.

Since: 0.1.0

Definition at line 77 of file epub_chapter.c.

References RA8_PRIV.

Referenced by internal_render_into().

◆ priv_epub_join_path()

void priv_epub_join_path	(	const char *	dir,
		const char *	name,
		char *	dst,
		size_t	cap )

Concatenate dir + name into dst, NUL-terminated.

Concatenate dir and name into dst, NUL-terminated.

Joins two NUL-terminated path components into the caller-supplied buffer with bounded length.

Parameters

[in]	dir	Directory prefix (may be NULL).
[in]	name	Name suffix (may be NULL).
[out]	dst	Destination buffer.
[in]	cap	Capacity of `dst` in bytes.

Precondition: cap == 0 implies dst may be NULL.; cap > 0 implies dst is non-NULL and writeable.

Postcondition: dst is NUL-terminated when cap > 0.; No more than (cap - 1) bytes written from inputs.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 118 of file epub_chapter.c.

References RA8_PRIV.

Referenced by epub_get_cover_image(), epub_get_embedded_font(), epub_get_resource(), epub_load_chapter(), internal_load_toc(), and internal_locate().

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ epub_chapter_internal_t

Function Documentation

◆ epub_get_chapter_count()

◆ epub_get_cover_image()

◆ epub_get_embedded_font()

◆ epub_get_embedded_font_count()

◆ epub_get_metadata()

◆ epub_get_resource()

◆ epub_get_toc_count()

◆ epub_get_toc_entry()

◆ epub_get_toc_kind()

◆ epub_load_chapter()

◆ epub_manifest_count()

◆ epub_manifest_item()

◆ epub_render_glyph()

◆ epub_set_font()

◆ epub_toc_entry_to_chapter()

◆ internal_font_init()

◆ internal_locate_extract()

◆ internal_render_into()

◆ priv_epub_book_not_ready()

◆ priv_epub_glyph_dim_invalid()

◆ priv_epub_join_path()