4bpp-grayscale cover / image decode + scaled blit for ereader_shelf. More...

#include "ra8_check.h"
#include "ra8_gfx.h"
#include "sh_app.h"

Include dependency graph for sh_image.c:

Enumerations
enum	sh_img_const_t : uint32_t { k_sh_nib_sh = 4U , k_sh_two = 2U , k_sh_img_max_w = 2048U }
	Nibble repack + scale-bound constants. More...

Functions
static bool	sh_gray4_fetch_row (const book_src_t src, const book_image_t img, uint32_t sy)
	Read source row `sy` of `img` as unpacked gray8 into s_sh_gray8_row via the library's sub-rect reader.
static void	sh_fit_box (int32_t src_w, int32_t src_h, int32_t box_w, int32_t box_h, int32_t fit_w, int32_t fit_h)
	Aspect-fit `src_w` x `src_h` into `box`; sets `fit_w` / `fit_h` (>=1).
static bool	sh_gray4_image (const book_src_t src, uint32_t img_idx, book_image_t out_img)
	Read image descriptor `img_idx` via the library and confirm it is a renderable gray4 raster that fits s_sh_gray8_row; false otherwise.
static int32_t	sh_clampi (int32_t v, int32_t lo, int32_t hi)
	Clamp `v` into [`lo`, `hi`] (assumes `hi` >= `lo`).
static void	sh_loupe_pack (int32_t j, int32_t i, int32_t w, uint8_t g8)
	Pack gray8 pixel `g8` into s_sh_loupe at flat index `j` * `w` + `i`.
static bool	sh_loupe_stage (const book_src_t src, const book_image_t img, int32_t sx, int32_t sy, int32_t w, int32_t h)
	Stage the `w` x `h` source window at (`sx`, `sy`) into s_sh_loupe.
static void	sh_loupe_chrome (int32_t dst_x, int32_t dst_y)
	Frame the lens window with a k_sh_loupe_border-thick ink border.
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).

Variables
static uint8_t	s_sh_gray8_row [k_sh_img_max_w]
	One unpacked gray8 source row read from the paged image pool.
static uint8_t	s_sh_loupe [((k_sh_loupe_w/k_sh_loupe_zoom) *(k_sh_loupe_h/k_sh_loupe_zoom))/k_sh_two]
	One magnifier-loupe source window, repacked as a compact gray4 image.
static uint8_t	s_sh_cover_row [k_sh_fb_w]
	One decoded gray8 row of the scaled cover, reused across rows.

Detailed Description

4bpp-grayscale cover / image decode + scaled blit for ereader_shelf.

book stores raster images as panel-native 4-bit grayscale (two pixels per byte) in the flat blob's image pool. The image-pool addressing contract – descriptor stride, pool base, nibble packing and odd-width parity – lives in the library that owns the format (book_src_image / book_src_image_rect, #342), not here. This module keeps only the presentation geometry: it asks the library for one unpacked gray8 source row at a time (a bounded, demand-paged read), nearest-neighbour aspect-fit scales it, and emits gray8 rows. Covers feed both the shelf thumbnail cache (gray8 buffer) and the full-screen cover page (row-wise ra8_gfx_blit_gray8); the loupe repacks the sampled gray8 window to gray4 for ra8_gfx_blit_gray4_zoom(). The pixels are byte-identical to the previous open-coded pool walk – only the addressing owner changed.

[Ring 6 / App] {World: NS}

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

Since: 0.1.0

Definition in file sh_image.c.

Enumeration Type Documentation

◆ sh_img_const_t

enum sh_img_const_t : uint32_t

Nibble repack + scale-bound constants.

Enumerator
k_sh_nib_sh	Gray8->gray4 nibble shift for the loupe repack.
k_sh_two	Centring divisor / half-extent divisor.
k_sh_img_max_w	Max accepted source width (row-buffer cap).

Definition at line 30 of file sh_image.c.

Function Documentation

◆ sh_clampi()

int32_t sh_clampi	(	int32_t	v,
		int32_t	lo,
		int32_t	hi )

static

Clamp v into [lo, hi] (assumes hi >= lo).

Definition at line 117 of file sh_image.c.

Referenced by sh_image_loupe().

◆ sh_fit_box()

void sh_fit_box	(	int32_t	src_w,
		int32_t	src_h,
		int32_t	box_w,
		int32_t	box_h,
		int32_t *	fit_w,
		int32_t *	fit_h )

static

Aspect-fit src_w x src_h into box; sets fit_w / fit_h (>=1).

Definition at line 83 of file sh_image.c.

Referenced by sh_image_blit_cover(), sh_image_decode_gray8(), and sh_image_loupe_map().

◆ sh_gray4_fetch_row()

bool sh_gray4_fetch_row	(	const book_src_t *	src,
		const book_image_t *	img,
		uint32_t	sy )

static

Read source row sy of img as unpacked gray8 into s_sh_gray8_row via the library's sub-rect reader.

False if the read/bounds fail.

Definition at line 70 of file sh_image.c.

References book_src_image_rect(), k_ra8_ok, s_sh_gray8_row, and book_image_t::width.

Referenced by sh_image_blit_cover(), and sh_image_decode_gray8().

◆ sh_gray4_image()

bool sh_gray4_image	(	const book_src_t *	src,
		uint32_t	img_idx,
		book_image_t *	out_img )

static

Read image descriptor img_idx via the library and confirm it is a renderable gray4 raster that fits s_sh_gray8_row; false otherwise.

Definition at line 102 of file sh_image.c.

References book_src_image(), book_image_t::format, book_image_t::height, k_book_image_gray4, k_ra8_ok, k_sh_img_max_w, and book_image_t::width.

Referenced by sh_image_blit_cover(), sh_image_decode_gray8(), sh_image_loupe(), and sh_image_loupe_map().

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

void sh_loupe_chrome	(	int32_t	dst_x,
		int32_t	dst_y )

static

Frame the lens window with a k_sh_loupe_border-thick ink border.

Definition at line 165 of file sh_image.c.

References k_sh_col_ink, k_sh_loupe_border, k_sh_loupe_h, k_sh_loupe_w, and sh_border().

Referenced by sh_image_loupe().

◆ sh_loupe_pack()

void sh_loupe_pack	(	int32_t	j,
		int32_t	i,
		int32_t	w,
		uint8_t	g8 )

static

Pack gray8 pixel g8 into s_sh_loupe at flat index j * w + i.

Definition at line 124 of file sh_image.c.

References k_sh_nib_sh, and s_sh_loupe.

Referenced by sh_loupe_stage().

◆ sh_loupe_stage()

bool sh_loupe_stage	(	const book_src_t *	src,
		const book_image_t *	img,
		int32_t	sx,
		int32_t	sy,
		int32_t	w,
		int32_t	h )

static

Stage the w x h source window at (sx, sy) into s_sh_loupe.

Each row is read as unpacked gray8 through book_src_image_rect, then repacked to the gray4 lens buffer.

Definition at line 139 of file sh_image.c.

References book_src_image_rect(), k_ra8_ok, s_sh_gray8_row, and sh_loupe_pack().

Referenced by sh_image_loupe().

Variable Documentation

◆ s_sh_cover_row

uint8_t s_sh_cover_row[k_sh_fb_w]

static

One decoded gray8 row of the scaled cover, reused across rows.

Sized to the panel width (the largest possible fitted cover width), so sh_image_blit_cover can hand a whole row to ra8_gfx_blit_gray8 instead of plotting pixel by pixel. File-scope (not stack) to keep the frame small; the single-threaded UI never re-enters the blit.

Since: 0.1.0

Definition at line 226 of file sh_image.c.

Referenced by sh_image_blit_cover().

◆ s_sh_gray8_row

uint8_t s_sh_gray8_row[k_sh_img_max_w]

static

One unpacked gray8 source row read from the paged image pool.

Sized for a k_sh_img_max_w-wide source row: book_src_image_rect expands the packed 4bpp pool into one gray8 byte per pixel here, so the scale paths sample s_sh_gray8_row[sx] directly and the loupe packs it back to gray4. File-scope (not stack) to keep frames small; the single-threaded UI never re-enters.

Since: 0.1.0

Definition at line 46 of file sh_image.c.

Referenced by sh_gray4_fetch_row(), sh_image_blit_cover(), sh_image_decode_gray8(), and sh_loupe_stage().

◆ s_sh_loupe

uint8_t s_sh_loupe[((k_sh_loupe_w/k_sh_loupe_zoom) *(k_sh_loupe_h/k_sh_loupe_zoom))/k_sh_two]

static

One magnifier-loupe source window, repacked as a compact gray4 image.

Sized for the largest lens window (k_sh_loupe_w / k_sh_loupe_zoom by k_sh_loupe_h / k_sh_loupe_zoom pixels, two per byte). Filled one bounded gray8 window row per frame via book_src_image_rect and repacked to gray4, then handed to ra8_gfx_blit_gray4_zoom(). File-scope to keep frames small; the single-threaded UI never re-enters the render.

Warning: A paged book's loupe locality differs from sequential reading: panning samples scattered sub-rect rows that each span several inflated chunks, so the per-frame read is bounded to just this window (the #207 prefetch policy is a separate concern).

Since: 0.1.0

Definition at line 63 of file sh_image.c.

Referenced by sh_image_loupe(), and sh_loupe_pack().

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ sh_img_const_t

Function Documentation

◆ sh_clampi()

◆ sh_fit_box()

◆ sh_gray4_fetch_row()

◆ sh_gray4_image()

◆ sh_image_blit_cover()

◆ sh_image_blit_gray8()

◆ sh_image_decode_gray8()

◆ sh_image_loupe()

◆ sh_image_loupe_map()

◆ sh_loupe_chrome()

◆ sh_loupe_pack()

◆ sh_loupe_stage()

Variable Documentation

◆ s_sh_cover_row

◆ s_sh_gray8_row

◆ s_sh_loupe