zoom_tiles.h File Reference

Bind a tiled gray8 atlas behind an ra8_tile_cache as a zoom source (#478). More...

#include <stdint.h>
#include "ra8_err.h"
#include "ra8_tile_cache.h"
#include "zoom.h"

Include dependency graph for zoom_tiles.h:

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

Go to the source code of this file.

Data Structures
struct	zoom_tile_src_t
	A tiled gray8 image, its grid, and the cache that pages it. More...

Functions
ra8_err_t	zoom_tile_src_init (zoom_tile_src_t *ts, ra8_tile_cache_t *cache, uint32_t image_id, uint32_t width, uint32_t height, uint16_t tile_w, uint16_t tile_h)
	Bind a tiled image and its cache, deriving the tile grid.
ra8_err_t	zoom_tile_src_bind (zoom_tile_src_t *ts, zoom_source_t *out)
	Present a bound tiled image to the zoom engine as a zoom_source_t.
ra8_err_t	zoom_tile_read (void *ctx, uint32_t x, uint32_t y, uint32_t w, uint32_t h, uint8_t *out, uint32_t out_stride)
	zoom_read_fn over a tiled atlas paged by an ra8_tile_cache.
ra8_err_t	zoom_tiles_prefetch (zoom_tile_src_t *ts, const zoom_view_t *v, zoom_pan_t dir, uint16_t max_tiles, uint16_t *out_warmed)
	Warm the tiles one pan step beyond what a view currently shows.

Detailed Description

Bind a tiled gray8 atlas behind an ra8_tile_cache as a zoom source (#478).

The manga / comic half of the tap-to-zoom viewer, and the half that answers the residency question. A full-resolution comic page does not fit in RAM, so it lives as a tiled atlas (JOF, #231) paged through an ::ra8_tile_cache. This adapter turns "give me source rectangle (x,y,w,h)" into "get exactly the tiles that rectangle intersects, copy the overlap, release them" – so the resident set at any instant is the tiles under the viewport and never the page.

Each tile is acquired and released around a single copy, so at most one cell is pinned at a time and a cache smaller than the frame degrades to re-decoding rather than to k_ra8_err_no_mem. Sizing the cache to the frame is the caller's job and is what stops thrash (#338); zoom_tiles_prefetch warms the lead edge of a pan out of whatever spare capacity the caller declares.

Fail-closed on geometry

The tile cache carries no pixel format, so a colour atlas would otherwise be read as gray8 and silently misrender (#339). Every fetched tile has its decoded extent checked against the geometry declared at init, which is exactly the mismatch a wrong bpp produces, and a mismatch is k_ra8_err_invalid_size rather than a wrong picture.

The TU compiles to nothing when ra8_tile_cache.h is not on the include path, so an app that only magnifies .rabook figures does not drag ra8_mem in.

Note

Not thread-safe; inherits the single-threaded contract of ra8_tile_cache.

See also

zoom.h The viewport engine this feeds.

zoom_book.h The .rabook figure source, for EPUB.

Copyright

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

Since

0.1.0

Definition in file zoom_tiles.h.

Function Documentation

zoom_tile_read()

ra8_err_t zoom_tile_read ( void * ctx, uint32_t x, uint32_t y, uint32_t w, uint32_t h, uint8_t * out, uint32_t out_stride )

nodiscard

zoom_read_fn over a tiled atlas paged by an ra8_tile_cache.

Bound by zoom_tile_src_bind; not normally called directly. Walks only the tiles the rectangle intersects, copying each overlap and releasing the cell before moving on, so the pin count never exceeds one and the resident set is bounded by the cache, not by the rectangle.

Parameters

[in]	ctx	The zoom_tile_src_t binding.
[in]	x	Rectangle left edge, source pixels.
[in]	y	Rectangle top edge, source pixels.
[in]	w	Rectangle width, source pixels (> 0).
[in]	h	Rectangle height, source pixels (> 0).
[out]	out	gray8 destination of at least out_stride * h bytes.
[in]	out_stride	Bytes between successive output rows (>= w).

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	The rectangle was assembled from its tiles.
k_ra8_err_null_ptr	ctx or out is NULL.
k_ra8_err_invalid_arg	Zero extent, or out_stride < w.
k_ra8_err_out_of_range	The rectangle leaves the image.
k_ra8_err_invalid_size	A fetched tile is not the declared geometry.
k_ra8_err_*	Propagated verbatim from the tile cache.

Precondition

ctx is a bound zoom_tile_src_t.

The rectangle lies inside the bound image.

Postcondition

On k_ra8_ok every output pixel is the gray8 value of its source pixel.

No cell is left pinned on any return path.

Note

Not thread-safe.

See also

ra8_tile_cache_get

Since

0.1.0

zoom_tile_src_bind()

ra8_err_t zoom_tile_src_bind ( zoom_tile_src_t * ts, zoom_source_t * out )

nodiscard

Present a bound tiled image to the zoom engine as a zoom_source_t.

Parameters

[in]	ts	Binding populated by zoom_tile_src_init.
[out]	out	Source descriptor to fill.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	out is ready to hand to zoom_view_open.
k_ra8_err_null_ptr	ts, out, or ts->cache is NULL.
k_ra8_err_invalid_arg	The bound extent is unusable (zero or too large).

Precondition

ts was populated by zoom_tile_src_init.

ts outlives every view bound to out.

Postcondition

On k_ra8_ok out->ctx == ts and the extent equals the image's.

ts is not modified.

Note

Not thread-safe.

See also

zoom_view_open

Since

0.1.0

Referenced by ez_bind_page().

zoom_tile_src_init()

ra8_err_t zoom_tile_src_init ( zoom_tile_src_t * ts, ra8_tile_cache_t * cache, uint32_t image_id, uint32_t width, uint32_t height, uint16_t tile_w, uint16_t tile_h )

nodiscard

Bind a tiled image and its cache, deriving the tile grid.

Derives tile_cols / tile_rows rather than accepting them, so the grid can never disagree with the extent it is supposed to cover – the disagreement that turns into an out-of-range tile fetch three layers down. Validates that the derived grid fits the 16-bit tile indices the cache key uses.

Parameters

[out]	ts	Binding to populate.
[in]	cache	Initialised tile cache whose decoder serves this image.
[in]	image_id	Tile-cache key image id (distinguishes co-resident images).
[in]	width	Full-resolution image width, pixels (> 0).
[in]	height	Full-resolution image height, pixels (> 0).
[in]	tile_w	Tile width, pixels (> 0).
[in]	tile_h	Tile height, pixels (> 0).

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	ts is bound and its grid derived.
k_ra8_err_null_ptr	ts or cache is NULL.
k_ra8_err_invalid_arg	An extent or a tile dimension is zero.
k_ra8_err_invalid_size	The derived grid exceeds 65535 tiles on an axis.

Precondition

cache was initialised by ra8_tile_cache_init.

The cache's decoder produces gray8 tiles of tile_w x tile_h.

Postcondition

On k_ra8_ok the grid invariants of zoom_tile_src_t hold.

On any error ts is not left partially bound.

Note

Not thread-safe.

See also

zoom_tile_src_bind

Since

0.1.0

Referenced by ez_bind_page().

zoom_tiles_prefetch()

ra8_err_t zoom_tiles_prefetch ( zoom_tile_src_t * ts, const zoom_view_t * v, zoom_pan_t dir, uint16_t max_tiles, uint16_t * out_warmed )

nodiscard

Warm the tiles one pan step beyond what a view currently shows.

Joins the two halves this library exists to keep in agreement: the view reports the source pixels it will read (zoom_view_window), ra8_tile_rect_of_pixels turns that into the tile rectangle, and the cache warms the lead edge of dir out of max_tiles of spare capacity. Best-effort by construction – read-ahead that could not complete never fails a pan.

Parameters

[in,out]	ts	Bound tiled source.
[in]	v	The open view whose visible window drives the warm.
[in]	dir	Direction of travel; k_zoom_pan_none warms nothing.
[in]	max_tiles	Residency budget: warm at most this many tiles.
[out]	out_warmed	Tiles warmed (may be NULL).

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	The sweep ran (possibly warming nothing).
k_ra8_err_null_ptr	ts, v, or ts->cache is NULL.
k_ra8_err_*	Propagated from zoom_view_window or the cache.

Precondition

v is open and bound to the same image as ts.

max_tiles is the caller's spare capacity, not the cache size.

Postcondition

No on-screen tile is evicted by this call when max_tiles respects the cache's spare capacity.

*out_warmed (when given) is at most max_tiles.

Note

Not thread-safe. Single-threaded read-ahead only.

Example:

uint16_t warmed = 0U;
(void)zoom_tiles_prefetch(&ts, &view, k_zoom_pan_right, spare, &warmed);

See also

ra8_tile_cache_prefetch_pan

Since

0.1.0

Referenced by ez_scene_prefetch().