Shared contract for the ereader_shelf multi-screen e-reader. More...

#include <stddef.h>
#include <stdint.h>
#include "book.h"
#include "book_paged.h"
#include "library.h"
#include "ra8_panel.h"
#include "ra8_ui.h"
#include "ra8_vsource.h"
#include "sh_classify.h"

Include dependency graph for sh_app.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	sh_line_t
	One wrapped reader line: a byte slice of sh_state_t::text. More...
struct	sh_entry_t
	One shelf book, sourced from MRAM (baked) or the SD card, in either the .rabook or .epub format. More...
struct	sh_state_t
	Whole-app UI + reader state (single instance g_sh). More...
struct	sh_comic_probe_t
	One container's headless self-check result (page 0 decode digest). More...

Enumerations
enum	sh_const_t : uint32_t { k_sh_fb_w = 1024U , k_sh_fb_h = 600U , k_sh_glyph_w = 8U , k_sh_glyph_h = 16U , k_sh_line_h = 22U , k_sh_bar_h = 56U , k_sh_pad = 24U , k_sh_gap = 24U , k_sh_card_pad = 14U , k_sh_thumb_w = 130U , k_sh_thumb_h = 195U , k_sh_grid_cols = 4U , k_sh_toc_row_h = 40U , k_sh_linebuf = 160U , k_sh_text_cap = 48U * 1024U , k_sh_max_lines = 6144U , k_sh_max_books = 12U , k_sh_thumb_bytes = 150U * 225U , k_sh_name_cap = 128U , k_sh_title_cap = 72U , k_sh_author_cap = 56U , k_sh_uart_chan = 8U , k_sh_uart_baud = 115200U , k_sh_poll_pts = 5U , k_sh_poll_ms = 30U , k_sh_dec_base = 10U }
	Panel geometry, layout, font, and reader sizing constants. More...
enum	sh_loupe_const_t : uint32_t { k_sh_loupe_w = 320U , k_sh_loupe_h = 320U , k_sh_loupe_zoom = 2U , k_sh_loupe_border = 2U , k_sh_loupe_hold_ms = 350U }
	Press-and-hold magnifier-loupe geometry + gesture threshold (#211). More...
enum	sh_color_t : uint32_t { k_sh_col_bg = 0x201A14U , k_sh_col_bar = 0x3A2E22U , k_sh_col_card = 0xF4ECDFU , k_sh_col_card_hi = 0xFFF7E0U , k_sh_col_ink = 0x1A140EU , k_sh_col_sub = 0x6A5C4AU , k_sh_col_edge = 0xB7A789U , k_sh_col_sel = 0xC8762AU , k_sh_col_barfg = 0xF4ECDFU , k_sh_col_rowhi = 0xE7DCC6U }
	0x00RRGGBB palette shared by every screen. More...
enum	sh_screen_t : uint8_t { k_sh_screen_shelf = 0U , k_sh_screen_cover = 1U , k_sh_screen_toc = 2U , k_sh_screen_reader = 3U , k_sh_screen_comic = 4U }
	The active screen in sh_state_t. More...
enum	sh_cover_act_t : uint8_t { k_sh_cover_none = 0U , k_sh_cover_read = 1U , k_sh_cover_toc = 2U }
	Result of a tap on the cover screen. More...

Functions
ra8_err_t	sh_image_decode_gray8 (const book_src_t src, uint32_t img_idx, uint8_t out, int32_t box_w, int32_t box_h, int32_t out_w, int32_t out_h)
	Decode a 4bpp grayscale image, aspect-fit-scale it into `box`, and write the result into a gray8 buffer (host-friendly: no framebuffer).
void	sh_image_blit_gray8 (const uint8_t *src, int32_t w, int32_t h, int32_t dst_x, int32_t dst_y)
	Blit a gray8 bitmap to the bound framebuffer at `dst_x`, `dst_y`.
ra8_err_t	sh_image_blit_cover (const book_src_t src, uint32_t img_idx, int32_t dst_x, int32_t dst_y, int32_t box_w, int32_t box_h, int32_t out_w, int32_t *out_h)
	Decode + aspect-fit a 4bpp image straight into the framebuffer box.
ra8_err_t	sh_image_loupe (const book_src_t *src, uint32_t img_idx, int32_t src_cx, int32_t src_cy, int32_t dst_x, int32_t dst_y)
	Draw the magnifier loupe: a k_sh_loupe_zoom-magnified 1:1 window of a full-resolution 4bpp source image, centred on a source point (#211).
bool	sh_image_loupe_map (const book_src_t src, uint32_t img_idx, int32_t box_x, int32_t box_y, int32_t box_w, int32_t box_h, int32_t px, int32_t py, int32_t out_cx, int32_t *out_cy)
	Map a framebuffer touch point over an aspect-fit image box to full-resolution source coordinates (loupe pan target).
int32_t	sh_cells (int32_t pixels)
	Cells of the 8px bitmap font that fit in `pixels`.
void	sh_fit (char dst, size_t cap, const char src, int32_t max_chars)
	Copy `src` into `dst` (cap bytes), truncating past `max_chars` with "..".
size_t	sh_fmt_uint (char *dst, size_t pos, uint32_t v)
	Append unsigned `v` as decimal into `dst` at `pos`; returns new pos.
void	sh_border (ra8_ui_rect_t r, uint32_t colour, int32_t width)
	Draw a `width-thick` rectangle outline in `colour`.
void	sh_titlebar (const char title, const char right)
	Fill the header bar and draw `title` left + optional `right` text.
bool	sh_sd_mount (void)
	Bring up the Pmod2 microSD over ra8_sdmmc_spi and mount its FAT volume.
void	sh_sd_scan (void)
	Append every root *.RBK file on the card as an SD shelf entry.
bool	sh_sd_book_open (const char name, uint32_t out_len)
	Open SD file `name` and hold it as the paged book backing.
ra8_err_t	sh_sd_book_read (void ctx, uint64_t offset, uint8_t buf, uint32_t len)
	ra8_vsource_read_fn over the held-open SD book file (seek + read).
void	sh_sd_book_close (void)
	Close the held SD book file (idempotent).
size_t	sh_sd_comic_read (void ctx, uint64_t offset, void buf, size_t len)
	comic_read_fn over the held-open SD book file (seek + clamped read).
bool	sh_sd_open_epub (const char name, void out_book)
	Stream-open SD file `name` as an EPUB via epub_open_streamed_fs.
void	sh_sd_close_epub (void *book)
	Close a streamed EPUB opened by sh_sd_open_epub and its source file.
uint16_t *	sh_fb_pixels (void)
	The live RGB565 framebuffer ra8_gfx scans (defined in main.c).
void	sh_decode_cover (uint16_t idx, const book_src_t *src)
	Decode the open rabook source's 4bpp cover into thumbnail slot `idx`.
void	sh_shelf_build_thumbs (void)
	Copy the baked books' pre-decoded covers into sh_state_t::thumb at boot.
void	sh_shelf_render (void)
	Render the shelf grid (cover cards) into the framebuffer.
int32_t	sh_shelf_hit (int32_t x, int32_t y)
	Hit-test a shelf tap; returns the book index or -1.
void	sh_cover_render (void)
	Render the selected book's cover / title page.
sh_cover_act_t	sh_cover_action (int32_t x, int32_t y)
	Classify a cover-screen tap into a sh_cover_act_t.
bool	sh_cover_loupe_map (int32_t px, int32_t py, int32_t out_cx, int32_t out_cy)
	Map a cover-screen touch to full-res source coordinates for the loupe.
void	sh_cover_loupe_render (void)
	Draw the magnifier loupe over the cover at the current pan centre.
void	sh_toc_render (void)
	Render the open book's chapter list (TOC).
int32_t	sh_toc_hit (int32_t x, int32_t y)
	Hit-test a TOC tap; returns the chapter index or -1.
void	sh_toc_scroll (int32_t dir)
	Scroll the TOC list by `dir` pages (-1 up / +1 down), clamped.
ra8_err_t	sh_inflate (const void src, size_t src_len, void dst, size_t dst_cap, size_t *out_len)
	Heap-free zlib inflater matching book_inflate_fn (miniz; main.c).
bool	sh_paged_open (ra8_vsource_read_fn file_read, void *file_ctx, uint64_t file_len)
	Open a chunked .rabook container as the demand-paged book source.
bool	sh_paged_open_mram (const uint8_t *blob, uint32_t blob_len)
	Open a memory-mapped (baked MRAM) RBKC container as the paged source.
void	sh_paged_close (void)
	Unbind the paged book source and release its SD backing (idempotent).
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).
void	sh_book_chapter_label (uint32_t chapter, char *out, size_t cap)
	Resolve a chapter's TOC label (or "Chapter N") into `out`.
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.
void	sh_reader_load_chapter (uint32_t chapter)
	Load + wrap a chapter into the reader working set.
uint32_t	sh_reader_first_content (void)
	First chapter with substantial prose (skips title/imprint front matter).
void	sh_reader_render (void)
	Render the current reader page.
bool	sh_reader_turn (int32_t dir)
	Turn the reader page by `dir` (-1/+1) across chapters; returns changed.
void	sh_reader_prefetch_adjacent (void)
	Read-ahead warm the adjacent chapters into the page cache (#207).
bool	sh_comic_open (uint16_t idx)
	Open shelf entry `idx` as a comic archive (CBZ / CBR) for page reading.
void	sh_comic_close (void)
	Close any open comic and release its backing (idempotent).
void	sh_comic_render (void)
	Render the current comic page full-screen (title bar + fitted image).
int32_t	sh_comic_edge_dir (int32_t x)
	Map a comic-screen edge tap to a reading-order page delta (RTL-aware).
bool	sh_comic_turn (int32_t dir)
	Turn the comic page by `dir` in reading order, clamped to the ends.
bool	sh_comic_tap (int32_t x, bool header)
	Handle a comic-screen tap: header returns to the shelf, else page-turn.
void	sh_comic_toggle_rtl (void)
	Flip the comic reading direction (LTR <-> RTL); page index unchanged.
void	sh_comic_selfcheck (sh_comic_probe_t cbz, sh_comic_probe_t cbr, bool *rtl_ok)
	Headless boot self-check: decode the baked CBZ + CBR page 0, verify RTL.
void	sh_comic_append_banner (char b, size_t pos, const sh_comic_probe_t cbz, const sh_comic_probe_t cbr, bool rtl_ok)
	Append " cbz=P:WxH:CRC cbr=P:WxH:CRC rtl=OK" to the boot banner buffer.

Variables
sh_state_t	g_sh
	The single whole-app state instance (defined in main.c).

Detailed Description

Shared contract for the ereader_shelf multi-screen e-reader.

The app is split into one module per screen plus a shared image blitter, all driven by main.c's boot + input loop. This header is the contract between them: the screen enumeration, the layout/colour constants, the single global sh_state_t, and every module entry point. State lives in one g_sh instance (defined in main.c) rather than function-threaded context, mirroring the single-screen-at-a-time nature of the UI.

Screens:

k_sh_screen_shelf – grid of book cards, each with a cover thumbnail.
k_sh_screen_cover – one book's full cover + title/author + actions.
k_sh_screen_toc – scrollable chapter list; tap a chapter to open it.
k_sh_screen_reader – full-book pagination across every chapter.
k_sh_screen_comic – full-page image reader for a CBZ / CBR comic.

[Ring 6 / App] {World: NS}

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

Since: 0.1.0

Definition in file sh_app.h.

Enumeration Type Documentation

◆ sh_color_t

enum sh_color_t : uint32_t

0x00RRGGBB palette shared by every screen.

Since: 0.1.0

Enumerator
k_sh_col_bg	App background (dark wood).
k_sh_col_bar	Header / title-bar fill.
k_sh_col_card	Card / page fill (paper).
k_sh_col_card_hi	Selected card fill.
k_sh_col_ink	Body ink.
k_sh_col_sub	Secondary ink (author / hints).
k_sh_col_edge	Card / image border.
k_sh_col_sel	Selection accent (amber).
k_sh_col_barfg	Text on the bar.
k_sh_col_rowhi	TOC selected-row fill.

Definition at line 97 of file sh_app.h.

◆ sh_const_t

enum sh_const_t : uint32_t

Panel geometry, layout, font, and reader sizing constants.

Since: 0.1.0

Enumerator
k_sh_fb_w	Panel width in pixels.
k_sh_fb_h	Panel height in pixels.
k_sh_glyph_w	Bitmap font cell width.
k_sh_glyph_h	Bitmap font cell height.
k_sh_line_h	Reader text line height.
k_sh_bar_h	Header / title-bar height.
k_sh_pad	Outer margin / content inset.
k_sh_gap	Gap between shelf cards.
k_sh_card_pad	Inner card inset.
k_sh_thumb_w	Shelf cover-thumbnail box width.
k_sh_thumb_h	Shelf cover-thumbnail box height.
k_sh_grid_cols	Shelf grid columns.
k_sh_toc_row_h	TOC list row height.
k_sh_linebuf	Per-line draw buffer bytes.
k_sh_text_cap	Per-chapter plain-text buffer bytes.
k_sh_max_lines	Max wrapped reader lines per chapter.
k_sh_max_books	Shelf / thumbnail-cache capacity.
k_sh_thumb_bytes	gray8 bytes per cached thumbnail.
k_sh_name_cap	SD file-name buffer bytes (VFAT long).
k_sh_title_cap	Entry title buffer bytes.
k_sh_author_cap	Entry author buffer bytes.
k_sh_uart_chan	SCI8 J-Link OB console channel.
k_sh_uart_baud	Console baud.
k_sh_poll_pts	Touch points polled per read.
k_sh_poll_ms	Input poll period in ms.
k_sh_dec_base	Decimal formatting base.

Definition at line 45 of file sh_app.h.

◆ sh_cover_act_t

enum sh_cover_act_t : uint8_t

Result of a tap on the cover screen.

Since: 0.1.0

Enumerator
k_sh_cover_none	Tap hit nothing actionable.
k_sh_cover_read	Open the reader at chapter 0.
k_sh_cover_toc	Open the table of contents.

Definition at line 446 of file sh_app.h.

◆ sh_loupe_const_t

enum sh_loupe_const_t : uint32_t

Press-and-hold magnifier-loupe geometry + gesture threshold (#211).

The lens is a fixed square window centred on the panel. While a press is held over a full-resolution cover/page image, a k_sh_loupe_w / k_sh_loupe_zoom by k_sh_loupe_h / k_sh_loupe_zoom window of the source is sampled at k_sh_loupe_zoom magnification and drawn 1:1 (no scale-to-fit decimation) via ra8_gfx_blit_gray4_zoom().

Since: 0.1.0

Enumerator
k_sh_loupe_w	Lens window width in framebuffer pixels.
k_sh_loupe_h	Lens window height in framebuffer pixels.
k_sh_loupe_zoom	Integer magnification of the sampled window.
k_sh_loupe_border	Lens chrome (frame) thickness in pixels.
k_sh_loupe_hold_ms	Press-hold duration that opens the lens (ms).

Definition at line 84 of file sh_app.h.

◆ sh_screen_t

enum sh_screen_t : uint8_t

The active screen in sh_state_t.

Since: 0.1.0

Enumerator
k_sh_screen_shelf	Book grid with cover thumbnails.
k_sh_screen_cover	One book's cover / title page.
k_sh_screen_toc	Chapter list.
k_sh_screen_reader	Reading a book.
k_sh_screen_comic	Full-page image reader (CBZ / CBR).

Definition at line 115 of file sh_app.h.

Function Documentation

◆ 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_border()

void sh_border	(	ra8_ui_rect_t	r,
		uint32_t	colour,
		int32_t	width )

Draw a width-thick rectangle outline in colour.

Definition at line 69 of file sh_util.c.

References ra8_ui_rect_t::h, ra8_gfx_rect(), ra8_ui_rect_t::w, ra8_ui_rect_t::x, and ra8_ui_rect_t::y.

Referenced by sh_draw_card(), and sh_loupe_chrome().

◆ sh_cells()

int32_t sh_cells ( int32_t pixels )

Cells of the 8px bitmap font that fit in pixels.

Definition at line 28 of file sh_util.c.

References k_sh_glyph_w.

Referenced by sh_cover_render(), sh_draw_card(), sh_reader_load_chapter(), and sh_toc_label().

◆ sh_comic_append_banner()

void sh_comic_append_banner	(	char *	b,
		size_t *	pos,
		const sh_comic_probe_t *	cbz,
		const sh_comic_probe_t *	cbr,
		bool	rtl_ok )

Append " cbz=P:WxH:CRC cbr=P:WxH:CRC rtl=OK" to the boot banner buffer.

Formats the two sh_comic_selfcheck digests + the RTL verdict onto b at *pos, advancing *pos past what it wrote. The comic golden the shelf hil.conf pins lives entirely in these fields, so the shelf's own fb= hash stays byte-identical (this appends after).

Parameters

[in,out]	b	Banner buffer with room for the appended fields.
[in,out]	pos	Current write offset into `b`; advanced on return.
[in]	cbz	CBZ page-0 self-check result (non-NULL).
[in]	cbr	CBR page-0 self-check result (non-NULL).
[in]	rtl_ok	RTL edge-mapping verdict from sh_comic_selfcheck.

Precondition: b holds at least *pos + 64 writable bytes.; pos, cbz, cbr are non-NULL.

Postcondition: *pos advanced past the appended text; b is not NUL-terminated here.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 359 of file sh_comic.c.

References sh_comic_probe_t::crc, k_sh_dec_base, k_shc_hex_digits, k_shc_nib_bits, k_shc_nib_mask, and sh_fmt_uint().

Referenced by sh_print_banner().

◆ sh_comic_close()

void sh_comic_close ( void )

Close any open comic and release its backing (idempotent).

Definition at line 205 of file sh_comic.c.

References comic_close(), g_sh, s_comic, s_from_sd, and sh_sd_book_close().

Referenced by sh_book_open(), sh_comic_open(), and sh_comic_probe_blob().

◆ sh_comic_edge_dir()

int32_t sh_comic_edge_dir ( int32_t x )

Map a comic-screen edge tap to a reading-order page delta (RTL-aware).

The left third yields one edge and the right third the other; the centre third is neutral. In left-to-right order the right edge is "next" (+1); in right-to-left (manga) order the mapping is mirrored, so the LEFT edge advances. The centre band returns 0.

Parameters

[in] x Touch X in framebuffer pixels (0 .. k_sh_fb_w - 1).

Returns: +1 to advance a page, -1 to go back, 0 for a neutral centre tap.

Return values

+1	Tap maps to the next page in reading order.
-1	Tap maps to the previous page in reading order.
0	Tap fell in the neutral centre band.

Precondition: g_sh.comic_rtl reflects the active reading direction.

Postcondition: No state is modified (pure mapping).

Note: Thread-safe: pure function of x and the RTL flag.

Since: 0.1.0

Definition at line 255 of file sh_comic.c.

References g_sh, k_sh_fb_w, and k_shc_thirds.

Referenced by sh_comic_selfcheck(), and sh_comic_tap().

◆ sh_comic_open()

bool sh_comic_open ( uint16_t idx )

Open shelf entry idx as a comic archive (CBZ / CBR) for page reading.

Binds ::comic over the entry's backing – a baked MRAM blob, or the held-open SD file (sh_sd_book_open + sh_sd_comic_read) – and builds the sorted page index. On success g_sh.comic_count is the page count and g_sh.comic_page is reset to 0. The reading direction (g_sh.comic_rtl) is preserved across opens (an app-level toggle, since raw CBZ/CBR carry no direction metadata).

Parameters

[in] idx Shelf entry index (< g_sh.book_count) whose fmt is a comic.

Returns: true if the comic opened with >= 1 page; false leaves none open.

Return values

true	Comic bound; g_sh.comic_count >= 1, g_sh.comic_page == 0.
false	Bad index/format, backing open failed, or no decodable pages.

Precondition: The entry at idx has sh_fmt_is_comic() true.; Any previously open book/comic was torn down by the caller (sh_book_open).

Postcondition: On true a comic is bound and page 0 is the current page.; On false no comic is bound (g_sh.comic_count == 0).

Note: Not thread-safe; single-threaded UI loop only.

Since: 0.1.0

Definition at line 174 of file sh_comic.c.

References sh_entry_t::blob, sh_entry_t::blob_len, sh_entry_t::fmt, sh_entry_t::from_sd, g_sh, s_blob, s_from_sd, sh_entry_t::sd_name, sh_comic_bind(), sh_comic_blob_read(), sh_comic_close(), sh_fmt_is_comic(), sh_sd_book_close(), sh_sd_book_open(), and sh_sd_comic_read().

Referenced by sh_book_open().

◆ sh_comic_render()

void sh_comic_render ( void )

Render the current comic page full-screen (title bar + fitted image).

Definition at line 222 of file sh_comic.c.

References g_sh, k_ra8_ok, k_sh_bar_h, k_sh_col_sub, k_sh_fb_h, k_sh_fb_w, k_sh_linebuf, k_shc_live_bg, ra8_gfx_clear(), ra8_gfx_font_8x16, ra8_gfx_text_out(), sh_comic_blit_page(), sh_comic_center_x(), sh_fmt_uint(), and sh_titlebar().

Referenced by sh_present().

◆ sh_comic_selfcheck()

void sh_comic_selfcheck	(	sh_comic_probe_t *	cbz,
		sh_comic_probe_t *	cbr,
		bool *	rtl_ok )

Headless boot self-check: decode the baked CBZ + CBR page 0, verify RTL.

Opens each baked fixture through the SAME ::comic path the live screen uses, decodes page 0 into an off-screen RGB565 scratch via the integer ra8_img_decode_blit pipeline, and FNV-hashes the scratch – a deterministic digest identical on host, ra8_emulator, and silicon. It also exercises sh_comic_edge_dir in both reading directions. The live display framebuffer binding is restored on return, so the shelf render (and its pinned fb= hash) is untouched.

Parameters

[out]	cbz	Receives the CBZ page-0 decode result (non-NULL).
[out]	cbr	Receives the CBR page-0 decode result (non-NULL).
[out]	rtl_ok	Receives true if the RTL edge mapping mirrors LTR (non-NULL).

Precondition: ra8_gfx is bound to the live framebuffer on entry.; cbz, cbr, and rtl_ok are non-NULL.

Postcondition: ra8_gfx is rebound to the live framebuffer (sh_fb_pixels) on return.; No comic is left open.

Note: Not thread-safe; single-threaded boot only.

Since: 0.1.0

Definition at line 335 of file sh_comic.c.

References g_sh, k_comic_cbr, k_comic_cbr_len, k_comic_cbz, k_comic_cbz_len, k_ra8_gfx_format_rgb565, k_sh_fb_h, k_sh_fb_w, ra8_gfx_init(), sh_comic_edge_dir(), sh_comic_probe_blob(), and sh_fb_pixels().

Referenced by main().

◆ sh_comic_tap()

bool sh_comic_tap	(	int32_t	x,
		bool	header )

Handle a comic-screen tap: header returns to the shelf, else page-turn.

Parameters

[in]	x	Touch X in framebuffer pixels.
[in]	header	true if the tap landed in the header bar (y < k_sh_bar_h).

Returns: true if the screen must be repainted.

Return values

true	Navigated to the shelf, or a page turned.
false	Neutral tap with no state change.

Precondition: The comic screen is active.

Postcondition: On a header tap g_sh.screen == k_sh_screen_shelf.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 285 of file sh_comic.c.

References g_sh, k_sh_fb_w, k_sh_screen_shelf, sh_comic_edge_dir(), sh_comic_toggle_rtl(), and sh_comic_turn().

Referenced by sh_handle_tap().

◆ sh_comic_toggle_rtl()

void sh_comic_toggle_rtl ( void )

Flip the comic reading direction (LTR <-> RTL); page index unchanged.

Definition at line 301 of file sh_comic.c.

References g_sh.

Referenced by sh_comic_tap().

◆ sh_comic_turn()

bool sh_comic_turn ( int32_t dir )

Turn the comic page by dir in reading order, clamped to the ends.

Parameters

[in] dir +1 for the next page, -1 for the previous; 0 is a no-op.

Returns: true if the page index changed (a repaint is needed).

Return values

true	g_sh.comic_page advanced/retreated by one.
false	At an end, no comic open, or `dir` == 0.

Precondition: A comic is open (or the call is a no-op).

Postcondition: g_sh.comic_page stays within [0, g_sh.comic_count).; On false no state changed.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 268 of file sh_comic.c.

References g_sh.

Referenced by sh_comic_tap(), and sh_handle_button().

◆ sh_cover_action()

sh_cover_act_t sh_cover_action	(	int32_t	x,
		int32_t	y )

Classify a cover-screen tap into a sh_cover_act_t.

Definition at line 91 of file sh_cover.c.

References k_sh_cover_none, k_sh_cover_read, k_sh_cover_toc, k_sh_cv_box_h, k_sh_cv_box_w, k_sh_cv_box_x, k_sh_cv_box_y, k_sh_cv_btn_h, k_sh_cv_btn_w, k_sh_cv_panel_x, k_sh_cv_read_y, k_sh_cv_toc_y, and sh_in_rect().

Referenced by sh_tap_cover().

◆ sh_cover_loupe_map()

bool sh_cover_loupe_map	(	int32_t	px,
		int32_t	py,
		int32_t *	out_cx,
		int32_t *	out_cy )

Map a cover-screen touch to full-res source coordinates for the loupe.

Only rabook covers with a real 4bpp cover image are magnifiable; EPUB covers (decoded JPEG/PNG) and cover-less books return false.

Parameters

[in]	px	Touch X in framebuffer pixels.
[in]	py	Touch Y in framebuffer pixels.
[out]	out_cx	Receives the source-image X the point maps to.
[out]	out_cy	Receives the source-image Y the point maps to.

Returns: true if the point is over a magnifiable cover image.

Since: 0.1.0

Definition at line 103 of file sh_cover.c.

References g_sh, k_book_nil, k_sh_cv_box_h, k_sh_cv_box_w, k_sh_cv_box_x, k_sh_cv_box_y, k_sh_fmt_rabook, and sh_image_loupe_map().

Referenced by sh_loupe_held().

◆ sh_cover_loupe_render()

void sh_cover_loupe_render ( void )

Draw the magnifier loupe over the cover at the current pan centre.

Definition at line 124 of file sh_cover.c.

References g_sh, k_book_nil, k_sh_fb_h, k_sh_fb_w, k_sh_fmt_rabook, k_sh_loupe_h, k_sh_loupe_w, and sh_image_loupe().

Referenced by sh_present(), and sh_present_loupe().

◆ sh_cover_render()

void sh_cover_render ( void )

Render the selected book's cover / title page.

Definition at line 51 of file sh_cover.c.

References sh_entry_t::author, sh_entry_t::from_sd, g_sh, k_sh_col_bg, k_sh_col_card, k_sh_col_sub, k_sh_cv_auth_y, k_sh_cv_box_h, k_sh_cv_box_w, k_sh_cv_box_x, k_sh_cv_box_y, k_sh_cv_panel_x, k_sh_cv_read_y, k_sh_cv_title_y, k_sh_cv_toc_y, k_sh_fb_w, k_sh_glyph_h, k_sh_linebuf, k_sh_pad, ra8_gfx_clear(), ra8_gfx_font_8x16, ra8_gfx_text_out(), sh_book_cover_fullscreen(), sh_cells(), sh_cover_button(), sh_fit(), sh_titlebar(), and sh_entry_t::title.

Referenced by sh_present().

◆ sh_decode_cover()

void sh_decode_cover	(	uint16_t	idx,
		const book_src_t *	src )

Decode the open rabook source's 4bpp cover into thumbnail slot idx.

Definition at line 37 of file sh_shelf.c.

References book_header_t::cover_image_index, g_sh, book_src_t::hdr, k_book_nil, k_ra8_ok, k_sh_thumb_h, k_sh_thumb_w, and sh_image_decode_gray8().

Referenced by sh_book_decode_thumb().

◆ sh_fb_pixels()

uint16_t * sh_fb_pixels ( void )

The live RGB565 framebuffer ra8_gfx scans (defined in main.c).

Definition at line 180 of file main.c.

References s_framebuffer.

Referenced by sh_comic_selfcheck(), and sh_epub_thumb().

◆ sh_fit()

void sh_fit	(	char *	dst,
		size_t	cap,
		const char *	src,
		int32_t	max_chars )

Copy src into dst (cap bytes), truncating past max_chars with "..".

Definition at line 33 of file sh_util.c.

References k_sh_ellipsis_min, memcpy(), and strlen().

Referenced by sh_cover_render(), sh_draw_card(), and sh_toc_label().

◆ sh_fmt_uint()

size_t sh_fmt_uint	(	char *	dst,
		size_t	pos,
		uint32_t	v )

Append unsigned v as decimal into dst at pos; returns new pos.

Definition at line 52 of file sh_util.c.

References k_sh_dec_base.

Referenced by sh_book_chapter_label(), sh_comic_append_banner(), sh_comic_render(), sh_print_banner(), sh_reader_render(), and sh_toc_render().

◆ sh_image_blit_cover()

ra8_err_t sh_image_blit_cover	(	const book_src_t *	src,
		uint32_t	img_idx,
		int32_t	dst_x,
		int32_t	dst_y,
		int32_t	box_w,
		int32_t	box_h,
		int32_t *	out_w,
		int32_t *	out_h )

Decode + aspect-fit a 4bpp image straight into the framebuffer box.

Parameters

[in]	src	Bound book source (image bytes read on demand).
[in]	img_idx	Image-table index.
[in]	dst_x	Box left edge.
[in]	dst_y	Box top edge.
[in]	box_w	Box width (> 0).
[in]	box_h	Box height (> 0).
[out]	out_w	Receives drawn width (may be NULL).
[out]	out_h	Receives drawn height (may be NULL).

Returns: k_ra8_ok on success.

Precondition: src bound; ra8_gfx bound.

Postcondition: The scaled image is centred in the box.

Since: 0.1.0

Definition at line 228 of file sh_image.c.

References book_image_t::height, k_ra8_err_invalid_arg, k_ra8_ok, k_sh_fb_w, k_sh_two, RA8_CHECK_NULL_PTR, ra8_gfx_blit_gray8(), s_sh_cover_row, s_sh_gray8_row, sh_fit_box(), sh_gray4_fetch_row(), sh_gray4_image(), and book_image_t::width.

Referenced by sh_book_cover_fullscreen().

◆ sh_image_blit_gray8()

void sh_image_blit_gray8	(	const uint8_t *	src,
		int32_t	w,
		int32_t	h,
		int32_t	dst_x,
		int32_t	dst_y )

Blit a gray8 bitmap to the bound framebuffer at dst_x, dst_y.

Parameters

[in]	src	gray8 pixels (row-major, w*h bytes), non-NULL.
[in]	w	Width in pixels (> 0).
[in]	h	Height in pixels (> 0).
[in]	dst_x	Left edge in framebuffer pixels.
[in]	dst_y	Top edge in framebuffer pixels.

Precondition: ra8_gfx is bound to the framebuffer.

Postcondition: Pixels in range are written; out-of-range pixels are clipped.

Since: 0.1.0

Definition at line 208 of file sh_image.c.

References ra8_gfx_blit_gray8().

Referenced by sh_draw_card().

◆ sh_image_decode_gray8()

ra8_err_t sh_image_decode_gray8	(	const book_src_t *	src,
		uint32_t	img_idx,
		uint8_t *	out,
		int32_t	box_w,
		int32_t	box_h,
		int32_t *	out_w,
		int32_t *	out_h )

Decode a 4bpp grayscale image, aspect-fit-scale it into box, and write the result into a gray8 buffer (host-friendly: no framebuffer).

Parameters

[in]	src	Bound book source (image bytes read on demand).
[in]	img_idx	Image-table index (< header image_count).
[out]	out	Destination gray8 buffer (>= box_w*box_h bytes).
[in]	box_w	Bounding-box width in pixels (> 0).
[in]	box_h	Bounding-box height in pixels (> 0).
[out]	out_w	Receives the actual scaled width.
[out]	out_h	Receives the actual scaled height.

Returns: k_ra8_ok on success; k_ra8_err_invalid_arg on bad index/format.

Precondition: src was bound by book_src_paged() / book_src_resident().

Postcondition: On success out holds out_w*out_h gray bytes (row-major).

Since: 0.1.0

Definition at line 174 of file sh_image.c.

References book_image_t::height, k_ra8_err_invalid_arg, k_ra8_ok, RA8_CHECK_NULL_PTR, s_sh_gray8_row, sh_fit_box(), sh_gray4_fetch_row(), sh_gray4_image(), and book_image_t::width.

Referenced by sh_decode_cover().

◆ sh_image_loupe()

ra8_err_t sh_image_loupe	(	const book_src_t *	src,
		uint32_t	img_idx,
		int32_t	src_cx,
		int32_t	src_cy,
		int32_t	dst_x,
		int32_t	dst_y )

Draw the magnifier loupe: a k_sh_loupe_zoom-magnified 1:1 window of a full-resolution 4bpp source image, centred on a source point (#211).

Samples a k_sh_loupe_w / k_sh_loupe_zoom by k_sh_loupe_h / k_sh_loupe_zoom window of the FULL-RESOLUTION source (read through the demand-paged book, one bounded window per call – never scale-to-fit decimated), integer-zooms it into the lens box, and frames it. The clip is confined to the lens window so nothing spills.

Parameters

[in]	src	Bound book source (image bytes read on demand).
[in]	img_idx	Image-table index of the source to magnify.
[in]	src_cx	Pan-centre X in full-resolution source pixels.
[in]	src_cy	Pan-centre Y in full-resolution source pixels.
[in]	dst_x	Lens-window left edge in framebuffer pixels.
[in]	dst_y	Lens-window top edge in framebuffer pixels.

Returns: k_ra8_ok on success; k_ra8_err_invalid_arg on a bad index/format/read.

Precondition: src was bound by book_src_paged() / book_src_resident().; ra8_gfx is bound to the framebuffer.

Postcondition: On success the lens window holds the magnified source window + a frame.

Since: 0.1.0

Definition at line 273 of file sh_image.c.

References book_image_t::height, k_ra8_err_invalid_arg, k_ra8_ok, k_sh_loupe_h, k_sh_loupe_w, k_sh_loupe_zoom, k_sh_two, RA8_CHECK_NULL_PTR, ra8_gfx_blit_gray4_zoom(), ra8_gfx_reset_clip(), ra8_gfx_set_clip(), s_sh_loupe, sh_clampi(), sh_gray4_image(), sh_loupe_chrome(), sh_loupe_stage(), and book_image_t::width.

Referenced by sh_cover_loupe_render().

◆ sh_image_loupe_map()

bool sh_image_loupe_map	(	const book_src_t *	src,
		uint32_t	img_idx,
		int32_t	box_x,
		int32_t	box_y,
		int32_t	box_w,
		int32_t	box_h,
		int32_t	px,
		int32_t	py,
		int32_t *	out_cx,
		int32_t *	out_cy )

Map a framebuffer touch point over an aspect-fit image box to full-resolution source coordinates (loupe pan target).

Parameters

[in]	src	Bound book source.
[in]	img_idx	Image-table index (the displayed image).
[in]	box_x	Display box left in framebuffer pixels.
[in]	box_y	Display box top in framebuffer pixels.
[in]	box_w	Display box width (> 0).
[in]	box_h	Display box height (> 0).
[in]	px	Touch X in framebuffer pixels.
[in]	py	Touch Y in framebuffer pixels.
[out]	out_cx	Receives the source X the point maps to.
[out]	out_cy	Receives the source Y the point maps to.

Returns: true if the point is over the displayed (aspect-fit) image; false otherwise (bad index/format, or point outside the fitted image).

Precondition: src, out_cx and out_cy are non-NULL.

Postcondition: On true, (out_cx, out_cy) is inside the source image bounds.

Since: 0.1.0

Definition at line 305 of file sh_image.c.

References book_image_t::height, k_sh_two, sh_fit_box(), sh_gray4_image(), and book_image_t::width.

Referenced by sh_cover_loupe_map().

◆ sh_inflate()

ra8_err_t sh_inflate	(	const void *	src,
		size_t	src_len,
		void *	dst,
		size_t	dst_cap,
		size_t *	out_len )

Heap-free zlib inflater matching book_inflate_fn (miniz; main.c).

The chunked reader hands one chunk's zlib stream plus a destination sized to the recorded inflated length, so a single non-wrapping tinfl_decompress() call suffices – no dictionary window, no allocation. tinfl also verifies the stream's Adler-32, which is the per-chunk integrity check the paged open path relies on.

Parameters

[in]	src	Start of the zlib stream.
[in]	src_len	Stream length in bytes.
[out]	dst	Destination buffer to inflate into.
[in]	dst_cap	Capacity of `dst` in bytes.
[out]	out_len	Receives the number of bytes written to `dst`.

Returns: k_ra8_ok, or k_ra8_err_invalid_size on a malformed/mismatched stream.

Precondition: src holds one complete zlib (RFC 1950) stream.

Postcondition: On k_ra8_ok the stream's Adler-32 checksum was verified.

Since: 0.1.0

Definition at line 160 of file main.c.

References k_ra8_err_invalid_size, k_ra8_ok, and s_tinfl.

Referenced by sh_paged_open().

◆ sh_paged_close()

void sh_paged_close ( void )

Unbind the paged book source and release its SD backing (idempotent).

Definition at line 279 of file sh_paged.c.

References g_sh, s_shp_mram, s_shp_rd, and sh_sd_book_close().

Referenced by sh_book_open(), and sh_paged_open().

◆ sh_paged_open()

bool sh_paged_open	(	ra8_vsource_read_fn	file_read,
		void *	file_ctx,
		uint64_t	file_len )

Open a chunked .rabook container as the demand-paged book source.

Binds the RBKC chunk reader over file_read, registers it as a paged ::ra8_vsource object, (re)initialises the ra8_vmem frame cache, and binds g_sh.book_src in paged mode. Always paged – there is deliberately no resident/paged size threshold (#205).

Parameters

[in]	file_read	Byte reader over the container file bytes.
[in]	file_ctx	Context for `file_read`.
[in]	file_len	Container file length in bytes.

Returns: true on success; false leaves no book bound (and the SD backing, if any, closed).

Precondition: Any previously open book was torn down via sh_paged_close (the backing file_read reads from must be live when this is called).

Since: 0.1.0

Definition at line 223 of file sh_paged.c.

References book_chunked_open(), g_sh, k_ra8_ok, k_shp_frame_bytes, k_shp_staging_bytes, k_shp_table_entries, s_shp_rd, s_shp_staging, s_shp_table, sh_inflate(), sh_paged_bind(), and sh_paged_close().

Referenced by sh_book_open_rabook(), and sh_paged_open_mram().

◆ sh_paged_open_mram()

bool sh_paged_open_mram	(	const uint8_t *	blob,
		uint32_t	blob_len )

Open a memory-mapped (baked MRAM) RBKC container as the paged source.

The file-read callback is a bounds-checked memcpy from blob; the container bytes are already addressable, but chunks still inflate on demand into cache frames – same path as SD books.

Parameters

[in]	blob	First container byte (MRAM).
[in]	blob_len	Container length in bytes.

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

Since: 0.1.0

Definition at line 267 of file sh_paged.c.

References s_shp_mram, sh_paged_mram_read(), and sh_paged_open().

Referenced by sh_book_open_rabook().

◆ sh_reader_first_content()

uint32_t sh_reader_first_content ( void )

First chapter with substantial prose (skips title/imprint front matter).

Definition at line 198 of file sh_reader.c.

References g_sh, k_ra8_ok, k_sh_content_min, and sh_book_chapter_text().

Referenced by sh_start_reading().

◆ sh_reader_load_chapter()

void sh_reader_load_chapter ( uint32_t chapter )

Load + wrap a chapter into the reader working set.

Definition at line 177 of file sh_reader.c.

References g_sh, k_ra8_ok, k_sh_fb_w, k_sh_pad, sh_ascii_fold(), sh_book_chapter_text(), sh_cells(), sh_lines_per_page(), and sh_reader_wrap().

Referenced by sh_reader_turn(), sh_start_reading(), and sh_tap_toc().

◆ sh_reader_prefetch_adjacent()

void sh_reader_prefetch_adjacent ( void )

Read-ahead warm the adjacent chapters into the page cache (#207).

Called in the reader's flush-idle window (after the panel flush, before the next input poll): a within-chapter page turn reads no new cache bytes (the chapter text is pre-extracted into sh_state_t::text), so the only demand faults happen when a turn crosses a chapter boundary. This warms chapter N+1 (forward reading) and N-1 (a back-flip) via book_src_prefetch_chapter() so that crossing finds them resident. Best-effort and transparent (warming never changes rendered output); a no-op unless a demand-paged .rabook is open.

Precondition: The reader screen is active (g_sh.screen == k_sh_screen_reader).; A book is open (or the call is a no-op).

Postcondition: No cache frame is left pinned by this call.; Rendered output and g_sh reader state are unchanged.

Since: 0.1.0

Definition at line 282 of file sh_reader.c.

References book_src_prefetch_chapter(), g_sh, and k_sh_fmt_rabook.

Referenced by sh_present().

◆ sh_reader_render()

void sh_reader_render ( void )

Render the current reader page.

Definition at line 210 of file sh_reader.c.

References g_sh, k_sh_bar_h, k_sh_card_pad, k_sh_col_card, k_sh_col_ink, k_sh_line_h, k_sh_linebuf, k_sh_pad, memcpy(), ra8_gfx_clear(), ra8_gfx_font_8x16, ra8_gfx_text_out(), sh_fmt_uint(), sh_lines_per_page(), and sh_titlebar().

Referenced by sh_present().

◆ sh_reader_turn()

bool sh_reader_turn ( int32_t dir )

Turn the reader page by dir (-1/+1) across chapters; returns changed.

Definition at line 254 of file sh_reader.c.

References g_sh, and sh_reader_load_chapter().

Referenced by sh_demo_step(), sh_handle_button(), and sh_tap_reader().

◆ sh_sd_book_close()

void sh_sd_book_close ( void )

Close the held SD book file (idempotent).

Definition at line 225 of file sh_sd.c.

References ra8_fs_close(), and s_book.

Referenced by sh_comic_close(), sh_comic_open(), sh_paged_close(), and sh_sd_book_open().

◆ sh_sd_book_open()

bool sh_sd_book_open	(	const char *	name,
		uint32_t *	out_len )

Open SD file name and hold it as the paged book backing.

Closes any previously held book file first. The handle stays open until sh_sd_book_close (or the next open), so sh_sd_book_read can serve chunk reads on demand – the file is never slurped whole.

Parameters

[in]	name	Root file name (e.g. "Meditations.rabook").
[out]	out_len	Receives the file size in bytes.

Returns: true if the file is open and non-empty.

Since: 0.1.0

Definition at line 150 of file sh_sd.c.

References k_ra8_fs_mode_read, k_ra8_ok, ra8_fs_open(), ra8_fs_size(), s_book, s_mount, and sh_sd_book_close().

Referenced by sh_book_open_rabook(), and sh_comic_open().

◆ sh_sd_book_read()

ra8_err_t sh_sd_book_read	(	void *	ctx,
		uint64_t	offset,
		uint8_t *	buf,
		uint32_t	len )

ra8_vsource_read_fn over the held-open SD book file (seek + read).

Parameters

[in]	ctx	Unused (the held file handle is module state).
[in]	offset	Absolute byte offset within the file.
[out]	buf	Destination for exactly `len` bytes.
[in]	len	Bytes to read; a read past EOF is rejected.

Returns: k_ra8_ok, or the ra8_fs error / k_ra8_err_out_of_range on a short read.

Precondition: A book file is held open via sh_sd_book_open.

Postcondition: On k_ra8_ok exactly len bytes were copied to buf.

Since: 0.1.0

Definition at line 176 of file sh_sd.c.

References k_ra8_err_invalid_state, k_ra8_err_out_of_range, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_fs_read(), ra8_fs_seek(), s_book, and s_sd_tag.

Referenced by sh_book_open_rabook().

◆ sh_sd_close_epub()

void sh_sd_close_epub ( void * book )

Close a streamed EPUB opened by sh_sd_open_epub and its source file.

Parameters

[in,out] book The epub_book_t* passed to sh_sd_open_epub.

Since: 0.1.0

Definition at line 244 of file sh_sd.c.

References epub_close_streamed_fs(), and s_epub_io.

Referenced by sh_book_open().

◆ sh_sd_comic_read()

size_t sh_sd_comic_read	(	void *	ctx,
		uint64_t	offset,
		void *	buf,
		size_t	len )

comic_read_fn over the held-open SD book file (seek + clamped read).

Shares the held file handle with sh_sd_book_read but matches the comic reader's seam shape (returns the byte count, not an error) and serves a short read at EOF instead of rejecting it – comic's miniz/RAR backends probe the archive tail and treat a short read as end-of-file.

Parameters

[in]	ctx	Unused (the held file handle is module state).
[in]	offset	Absolute byte offset within the file.
[out]	buf	Destination buffer (`len` writable bytes).
[in]	len	Bytes requested.

Returns: Bytes actually copied (0 at/after EOF or on any error).

Precondition: A comic file is held open via sh_sd_book_open.; buf holds len writable bytes.

Postcondition: At most len bytes were copied to buf; the return is that count.

Since: 0.1.0

Definition at line 203 of file sh_sd.c.

References k_ra8_ok, ra8_fs_read(), ra8_fs_seek(), and s_book.

Referenced by sh_comic_open().

◆ sh_sd_mount()

bool sh_sd_mount ( void )

Bring up the Pmod2 microSD over ra8_sdmmc_spi and mount its FAT volume.

Returns: true if a card mounted; false (the common no-card case) leaves the shelf baked-only.

Precondition: Clocks (ra8_cgc) are initialised.

Postcondition: On true, ::sh_sd_read / sh_sd_scan are usable.

Since: 0.1.0

Definition at line 97 of file sh_sd.c.

References k_ra8_clock_id_pclka, k_ra8_ok, ra8_cgc_get_clock_hz(), ra8_fs_mount(), ra8_sdmmc_spi_bind_fs_backend(), ra8_sdmmc_spi_init(), s_backend, s_mount, s_pclka_hz, sh_sd_bus_init(), sh_sd_cs(), sh_sd_set_clock(), and sh_sd_xfer().

Referenced by main().

◆ sh_sd_open_epub()

bool sh_sd_open_epub	(	const char *	name,
		void *	out_book )

Stream-open SD file name as an EPUB via epub_open_streamed_fs.

No whole-file residency (#230): the source file stays held open by this module and every ZIP entry (chapter, cover, resource) is seek+read on demand, so there is no book-size ceiling below the ra8_fs 4 GiB offset limit. Release with sh_sd_close_epub.

Parameters

[in]	name	Root file name (e.g. "Pride and Prejudice.epub").
[out]	out_book	epub_book_t* (void* to keep epub out of this header).

Returns: true if the EPUB opened (the source file is now held open).

Since: 0.1.0

Definition at line 233 of file sh_sd.c.

References epub_open_streamed_fs(), k_ra8_ok, s_epub_io, and s_mount.

Referenced by sh_book_open().

◆ sh_sd_scan()

void sh_sd_scan ( void )

Append every root *.RBK file on the card as an SD shelf entry.

Definition at line 143 of file sh_sd.c.

References ra8_fs_listdir(), s_mount, and sh_sd_listdir_cb().

Referenced by main().

◆ sh_shelf_build_thumbs()

void sh_shelf_build_thumbs ( void )

Copy the baked books' pre-decoded covers into sh_state_t::thumb at boot.

Definition at line 62 of file sh_shelf.c.

References sh_entry_t::from_sd, g_sh, memcpy(), sh_entry_t::thumb, sh_entry_t::thumb_h, and sh_entry_t::thumb_w.

Referenced by main().

◆ sh_shelf_hit()

int32_t sh_shelf_hit	(	int32_t	x,
		int32_t	y )

Hit-test a shelf tap; returns the book index or -1.

Definition at line 170 of file sh_shelf.c.

References g_sh, ra8_ui_rect_t::h, ra8_ui_rect_t::w, ra8_ui_rect_t::x, and ra8_ui_rect_t::y.

Referenced by sh_handle_tap().

◆ sh_shelf_render()

void sh_shelf_render ( void )

Render the shelf grid (cover cards) into the framebuffer.

Definition at line 160 of file sh_shelf.c.

References g_sh, k_sh_col_bg, ra8_gfx_clear(), sh_draw_card(), sh_layout_cards(), and sh_titlebar().

Referenced by sh_present().

◆ sh_titlebar()

void sh_titlebar	(	const char *	title,
		const char *	right )

Fill the header bar and draw title left + optional right text.

Definition at line 76 of file sh_util.c.

References k_sh_bar_h, k_sh_col_bar, k_sh_col_barfg, k_sh_fb_w, k_sh_glyph_h, k_sh_glyph_w, k_sh_pad, ra8_gfx_font_8x16, ra8_gfx_rect(), ra8_gfx_text_out(), and strlen().

Referenced by sh_comic_render(), sh_cover_render(), sh_reader_render(), sh_shelf_render(), and sh_toc_render().

◆ sh_toc_hit()

int32_t sh_toc_hit	(	int32_t	x,
		int32_t	y )

Hit-test a TOC tap; returns the chapter index or -1.

Definition at line 79 of file sh_toc.c.

References g_sh, k_sh_bar_h, and k_sh_toc_row_h.

Referenced by sh_tap_toc().

◆ sh_toc_render()

void sh_toc_render ( void )

Render the open book's chapter list (TOC).

Definition at line 42 of file sh_toc.c.

References g_sh, k_sh_bar_h, k_sh_col_card, k_sh_col_edge, k_sh_col_ink, k_sh_col_rowhi, k_sh_col_sub, k_sh_dec_base, k_sh_fb_w, k_sh_glyph_h, k_sh_linebuf, k_sh_toc_num_w, k_sh_toc_row_h, k_sh_toc_text_pad, ra8_gfx_clear(), ra8_gfx_font_8x16, ra8_gfx_rect(), ra8_gfx_text_out(), sh_fmt_uint(), sh_titlebar(), sh_toc_label(), and sh_toc_visible_rows().

Referenced by sh_present().

◆ sh_toc_scroll()

void sh_toc_scroll ( int32_t dir )

Scroll the TOC list by dir pages (-1 up / +1 down), clamped.

Definition at line 90 of file sh_toc.c.

References g_sh, and sh_toc_visible_rows().

Referenced by sh_handle_button().

Variable Documentation

◆ g_sh

sh_state_t g_sh

extern

The single whole-app state instance (defined in main.c).

Definition at line 64 of file main.c.

Referenced by main(), sh_ascii_fold(), sh_book_capture_meta(), sh_book_chapter_label(), sh_book_chapter_text(), sh_book_cover_fullscreen(), sh_book_decode_thumb(), sh_book_open(), sh_comic_bind(), sh_comic_blit_page(), sh_comic_close(), sh_comic_edge_dir(), sh_comic_open(), sh_comic_probe_blob(), sh_comic_render(), sh_comic_selfcheck(), sh_comic_tap(), sh_comic_toggle_rtl(), sh_comic_turn(), sh_cover_gesture(), sh_cover_loupe_map(), sh_cover_loupe_render(), sh_cover_render(), sh_decode_cover(), sh_demo_step(), sh_draw_card(), sh_epub_thumb(), sh_handle_button(), sh_handle_tap(), sh_layout_cards(), sh_loupe_held(), sh_paged_bind(), sh_paged_close(), sh_paged_open(), sh_present(), sh_print_banner(), sh_pump_input(), sh_rabook_label(), sh_reader_first_content(), sh_reader_load_chapter(), sh_reader_prefetch_adjacent(), sh_reader_render(), sh_reader_turn(), sh_reader_wrap(), sh_sd_listdir_cb(), sh_seed_baked(), sh_select_book(), sh_shelf_build_thumbs(), sh_shelf_hit(), sh_shelf_render(), sh_skip_word(), sh_start_reading(), sh_tap_cover(), sh_tap_reader(), sh_tap_toc(), sh_toc_hit(), sh_toc_render(), sh_toc_scroll(), and sh_wrap_line().

Data Structures

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ sh_color_t

◆ sh_const_t

◆ sh_cover_act_t

◆ sh_loupe_const_t

◆ sh_screen_t

Function Documentation

◆ sh_book_chapter_label()

◆ sh_book_chapter_text()

◆ sh_book_cover_fullscreen()

◆ sh_book_decode_thumb()

◆ sh_book_open()

◆ sh_border()

◆ sh_cells()

◆ sh_comic_append_banner()

◆ sh_comic_close()

◆ sh_comic_edge_dir()

◆ sh_comic_open()

◆ sh_comic_render()

◆ sh_comic_selfcheck()

◆ sh_comic_tap()

◆ sh_comic_toggle_rtl()

◆ sh_comic_turn()

◆ sh_cover_action()

◆ sh_cover_loupe_map()

◆ sh_cover_loupe_render()

◆ sh_cover_render()

◆ sh_decode_cover()

◆ sh_fb_pixels()

◆ sh_fit()

◆ sh_fmt_uint()

◆ sh_image_blit_cover()

◆ sh_image_blit_gray8()

◆ sh_image_decode_gray8()

◆ sh_image_loupe()

◆ sh_image_loupe_map()

◆ sh_inflate()

◆ sh_paged_close()

◆ sh_paged_open()

◆ sh_paged_open_mram()

◆ sh_reader_first_content()

◆ sh_reader_load_chapter()

◆ sh_reader_prefetch_adjacent()

◆ sh_reader_render()

◆ sh_reader_turn()

◆ sh_sd_book_close()

◆ sh_sd_book_open()

◆ sh_sd_book_read()

◆ sh_sd_close_epub()

◆ sh_sd_comic_read()

◆ sh_sd_mount()

◆ sh_sd_open_epub()

◆ sh_sd_scan()

◆ sh_shelf_build_thumbs()

◆ sh_shelf_hit()

◆ sh_shelf_render()

◆ sh_titlebar()

◆ sh_toc_hit()

◆ sh_toc_render()

◆ sh_toc_scroll()

Variable Documentation

◆ g_sh