ez_scene.h File Reference

Tap-to-zoom demo scene: tiled 12 MP page, zoom viewport, loupe (#478). More...

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

Include dependency graph for ez_scene.h:

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

Go to the source code of this file.

Data Structures
struct	ez_scene_t
	The whole demo: one tiled page, one zoom viewport, one loupe. More...
struct	ez_scene_cfg_t
	Everything ez_scene_init needs: storage and framebuffer geometry. More...
struct	ez_present_t
	What the scene asks the panel to flush, and how well. More...
struct	ez_selftest_t
	Deterministic boot self-check results (the app's golden numbers). More...

Enumerations
enum	ez_page_t : uint32_t {   k_ez_page_w = 4096U ,   k_ez_page_h = 3072U ,   k_ez_tile_edge = 256U ,   k_ez_image_id = 1U }
	The procedural source page and its tiling. More...
enum	ez_layout_t : uint16_t {   k_ez_status_h = 48U ,   k_ez_lens_edge = 320U ,   k_ez_lens_border = 3U ,   k_ez_edge_band = 176U ,   k_ez_ind_block = 20U ,   k_ez_ind_gap = 8U }
	Panel layout: status bar, content viewport and the loupe box. More...
enum	ez_scale_t : uint8_t {   k_ez_page_scale_max = 4U ,   k_ez_lens_scale_min = 4U ,   k_ez_lens_scale_max = 8U }
	The magnification ladders the page view and the loupe walk. More...
enum	ez_zone_t : uint8_t {   k_ez_zone_none = 0U ,   k_ez_zone_pan_left = 1U ,   k_ez_zone_pan_right = 2U ,   k_ez_zone_pan_up = 3U ,   k_ez_zone_pan_down = 4U ,   k_ez_zone_zoom = 5U ,   k_ez_zone_lens = 6U ,   k_ez_zone_toggle = 7U }
	Tap zones of the demo's discrete touch scheme. More...
enum	ez_cache_t : uint32_t {   k_ez_cell_bytes = k_ez_tile_edge * k_ez_tile_edge ,   k_ez_view_cols = 6U ,   k_ez_view_rows = 4U ,   k_ez_cells = (k_ez_view_cols + 1U) * (k_ez_view_rows + 1U) ,   k_ez_buckets = 64U ,   k_ez_cell_budget_bytes = 4U * 1024U * 1024U ,   k_ez_prefetch_max = 6U }
	Tile-cache budget, DERIVED from the viewport and tile geometry (#338). More...
enum	ez_scratch_t : uint32_t {   k_ez_row_bytes = 1024U ,   k_ez_strip_bytes = 1024U * 16U ,   k_ez_packed_bytes = (1024U * 16U) / 2U }
	The zoom engine's entire memory footprint, in bytes. More...

Functions
uint8_t	ez_page_sample (uint32_t x, uint32_t y)
	Sample the procedural full-resolution page at one pixel.
ra8_err_t	ez_tile_decode (void *ctx, const ra8_tile_key_t *key, uint8_t *cell, uint32_t cell_bytes, uint16_t *out_w, uint16_t *out_h)
	ra8_tile_decode_fn that materialises one page tile from the sampler.
ra8_ui_rect_t	ez_content_rect (int32_t fb_w, int32_t fb_h)
	The content rectangle: the panel less the status bar.
ra8_err_t	ez_scene_init (ez_scene_t *s, const ez_scene_cfg_t *cfg)
	Wire the tile cache, the tiled source and both viewports.
ez_zone_t	ez_zone_hit (const ez_scene_t *s, int32_t x, int32_t y)
	Classify a tap by the zone it lands in.
bool	ez_scene_tap (ez_scene_t *s, int32_t x, int32_t y, uint32_t now_ms)
	Apply a tap to the scene.
ra8_err_t	ez_scene_render (ez_scene_t *s)
	Repaint the content area, the loupe (when open) and the status bar.
ra8_err_t	ez_scene_present (ez_scene_t *s, ez_present_t *out)
	Take the pending flush plan for whichever view changed.
bool	ez_scene_tick (ez_scene_t *s, uint32_t now_ms)
	Advance both views' settle timers; report whether a repaint is due.
ra8_err_t	ez_scene_prefetch (ez_scene_t *s, zoom_pan_t dir, uint16_t *out_warmed)
	Warm the tiles one pan step ahead of the page viewport.
ra8_err_t	ez_scene_selftest (ez_scene_t *s, ez_selftest_t *out)
	Drive the scene through the scripted boot self-check.
uint32_t	ez_fnv1a (const void *buf, uint32_t len)
	FNV-1a-32 over a byte range (the framebuffer hash).

Detailed Description

Tap-to-zoom demo scene: tiled 12 MP page, zoom viewport, loupe (#478).

Tag

[Ring 7 / App] {World: NS}

The presentation model of the ereader_zoom app, kept out of main.c so the host twin (apps/board/stand_alone/ereader/tests/src/test_app_ereader_zoom.c) compiles and drives the same code the board runs. Nothing here touches MMIO: it is zoom over ra8_tile_cache over a procedural page, painting through ra8_gfx.

What the demo proves

1. No downscale. The page is 4096x3072 – 12 MB of gray8, which cannot be resident on a 1.6 MB-SRAM part – and is magnified at 1:1, 2x and 4x with no resampling of the source anywhere in the path.
2. Bounded residency. The page is served through an ::ra8_tile_cache sized to the viewport tile demand plus a one-tile pan margin (k_ez_cells), so the resident set is a screenful of tiles and never the page. The banner reports the cache's own hit/miss/eviction counters, so the claim is measured rather than asserted.
3. Partial e-ink update. Cycling the loupe's magnification changes only the lens rectangle, so ez_scene_present asks for a flush of that box – 102400 of the content area's 565248 pixels – instead of a full refresh.
4. Pan-stable blue-noise tone. The whole composite is integer, and the dither phase is locked to the magnified image plane, so the framebuffer hash is reproducible on host, ra8_emulator and silicon.

Why the chrome carries no text

The status bar is filled rectangles and a block zoom indicator, not glyphs. A framebuffer hash over antialiased text is toolchain-bound – the same board prints a different value from a 13.3-built and a 14.3-built image – which makes it useless as a cross-host golden. Every pixel this scene writes comes from integer arithmetic, so the hash means the same thing everywhere.

Note

Not thread-safe; single-threaded reader loop only.

See also

zoom.h

Copyright

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

Since

0.1.0

Definition in file ez_scene.h.

Enumeration Type Documentation

ez_cache_t

enum ez_cache_t : uint32_t

Tile-cache budget, DERIVED from the viewport and tile geometry (#338).

At 1:1 the content viewport straddles at most k_ez_view_cols x k_ez_view_rows tiles; sizing the cache to that frame plus one tile of margin on each axis means a single pan step re-decodes only the newly exposed row or column and never a tile still on screen. The static_asserts in ez_scene.c fail the build if the derivation is ever undercut or grows past its SDRAM budget.

Invariant

k_ez_cells >= k_ez_view_cols * k_ez_view_rows.

Example:

static uint8_t s_cells[(size_t)k_ez_cells * (size_t)k_ez_cell_bytes];

See also

ez_scene_init

Since

0.1.0

Enumerator
k_ez_cell_bytes	One gray8 tile, bytes.
k_ez_view_cols	1:1 tile columns a frame straddles, plus one.
k_ez_view_rows	1:1 tile rows a frame straddles, plus one.
k_ez_cells	Cells.
k_ez_buckets	Cache hash buckets (>= cells).
k_ez_cell_budget_bytes	SDRAM the cache may claim.
k_ez_prefetch_max	Lead-edge tiles per pan.

Definition at line 166 of file ez_scene.h.

ez_layout_t

enum ez_layout_t : uint16_t

Panel layout: status bar, content viewport and the loupe box.

The content viewport is the panel less the status bar; the loupe is a square box centred in it. Both are compile-time constants because the tile-cache budget below is derived from them.

Invariant

k_ez_lens_edge is smaller than the content viewport on both axes.

Example:

const ra8_ui_rect_t content = ez_content_rect(fb_w, fb_h);

See also

ez_content_rect

Since

0.1.0

Enumerator
k_ez_status_h	Status bar height, pixels.
k_ez_lens_edge	Loupe box edge, pixels.
k_ez_lens_border	Loupe chrome thickness, pixels.
k_ez_edge_band	Pan tap-band depth at each edge.
k_ez_ind_block	Zoom-indicator block edge, pixels.
k_ez_ind_gap	Gap between indicator blocks, pixels.

Definition at line 94 of file ez_scene.h.

ez_page_t

enum ez_page_t : uint32_t

The procedural source page and its tiling.

4096x3072 gray8 is 12 MiB – deliberately far past what the part can hold – so "only the visible tiles are resident" is the only way the app can work at all. Every dimension is a power of two so the sampler is shifts and masks rather than divides, which matters under the instruction-accurate emulator.

Invariant

k_ez_page_w / k_ez_tile_edge and k_ez_page_h / k_ez_tile_edge are both exact, so no partial edge tile exists.

Example:

const uint8_t sample = ez_page_sample(x, y);

See also

ez_page_sample

Since

0.1.0

Enumerator
k_ez_page_w	Source page width, pixels.
k_ez_page_h	Source page height, pixels.
k_ez_tile_edge	Tile edge, pixels (gray8 => 64 KiB/tile).
k_ez_image_id	Tile-cache key image id for the page.

Definition at line 73 of file ez_scene.h.

ez_scale_t

enum ez_scale_t : uint8_t

The magnification ladders the page view and the loupe walk.

The page ladder tops out at 4x – past that a 1024-wide viewport shows fewer than 256 source pixels and the reader has lost all context. The loupe starts where the page ladder ends because that is its whole purpose: a small window magnified further than the page around it.

Invariant

k_ez_lens_scale_min >= k_ez_page_scale_max.

Example:

const uint8_t next = zoom_scale_cycle(v->scale, k_zoom_scale_min, k_ez_page_scale_max);

See also

zoom_scale_cycle

Since

0.1.0

Enumerator
k_ez_page_scale_max	Page-view ladder ceiling.
k_ez_lens_scale_min	Loupe ladder floor.
k_ez_lens_scale_max	Loupe ladder ceiling.

Definition at line 118 of file ez_scene.h.

ez_scratch_t

enum ez_scratch_t : uint32_t

The zoom engine's entire memory footprint, in bytes.

Sized for the widest viewport (the content area), and shared by both views because only one renders at a time. The strip height falls out of the division: 16384 / 1024 = 16 rows for the page view, capped at k_zoom_strip_rows_max = 32 for the narrower loupe. This is the whole cost of the viewer – 25 KiB of SRAM – because the composite never holds the visible window.

Invariant

k_ez_packed_bytes >= (k_ez_row_bytes * 16) / 2.

Example:

static uint8_t s_strip[k_ez_strip_bytes];

See also

zoom_scratch_t

Since

0.1.0

Enumerator
k_ez_row_bytes	One source row at the widest viewport.
k_ez_strip_bytes	gray8 destination strip (16 rows).
k_ez_packed_bytes	The strip packed to 4 bpp.

Definition at line 195 of file ez_scene.h.

ez_zone_t

enum ez_zone_t : uint8_t

Tap zones of the demo's discrete touch scheme.

The GT911 path reports contacts, not drags, so navigation is tap bands rather than a fling – the same scheme the sibling comic and manga demos use.

Invariant

k_ez_zone_none is the zero value and does nothing.

Example:

const ez_zone_t z = ez_zone_hit(&scene, x, y);

See also

ez_scene_tap

Since

0.1.0

Enumerator
k_ez_zone_none	Nothing under the tap.
k_ez_zone_pan_left	Left band: page travels left.
k_ez_zone_pan_right	Right band: page travels right.
k_ez_zone_pan_up	Top band: page travels up.
k_ez_zone_pan_down	Bottom band: page travels down.
k_ez_zone_zoom	Centre: cycle the page magnification.
k_ez_zone_lens	Inside the loupe: cycle its magnification.
k_ez_zone_toggle	Status bar: open / close the loupe.

Definition at line 138 of file ez_scene.h.

Function Documentation

ez_content_rect()

ra8_ui_rect_t ez_content_rect ( int32_t fb_w, int32_t fb_h )

nodiscard

The content rectangle: the panel less the status bar.

Parameters

[in]	fb_w	Framebuffer width, pixels.
[in]	fb_h	Framebuffer height, pixels.

Returns

The content rectangle in framebuffer coordinates.

Return values

{0, k_ez_status_h, fb_w, fb_h - k_ez_status_h}

Always.

Precondition

fb_h exceeds k_ez_status_h.

fb_w is positive.

Postcondition

The result's height is positive.

No state is modified (pure function).

Note

Pure; thread-safe.

See also

ez_scene_init

Since

0.1.0

Definition at line 232 of file ez_scene.c.

References k_ez_status_h.

Referenced by ez_scene_init(), and main().

ez_fnv1a()

uint32_t ez_fnv1a ( const void * buf, uint32_t len )

nodiscard

FNV-1a-32 over a byte range (the framebuffer hash).

Parameters

[in]	buf	Bytes to hash (NULL hashes nothing).
[in]	len	Byte count.

Returns

The FNV-1a-32 digest.

Return values

2166136261	buf is NULL or len is 0 (the FNV offset basis).
digest	Otherwise, the hash of the range.

Precondition

buf addresses at least len readable bytes.

The range is deterministic (integer-rendered pixels only).

Postcondition

No state is modified (pure function).

The result depends only on the bytes, not on their address.

Note

Pure; thread-safe.

See also

ez_scene_selftest

Since

0.1.0

Definition at line 712 of file ez_scene.c.

References k_ez_fnv_offset, and k_ez_fnv_prime.

Referenced by ez_render_and_hash().

ez_page_sample()

uint8_t ez_page_sample ( uint32_t x, uint32_t y )

nodiscard

Sample the procedural full-resolution page at one pixel.

A page of "text": a repeating smooth gradient (which only a dither can render on a 16-level panel without banding) overlaid with 3 px rules broken into word-like runs (which only full-resolution magnification can resolve). Every operation is a shift or a mask, so decoding a 256x256 tile is cheap enough to stay inside the emulator's boot budget.

Parameters

[in]	x	Source column, < k_ez_page_w.
[in]	y	Source row, < k_ez_page_h.

Returns

The gray8 sample.

Return values

ink	The pixel falls on an inked rule (a dark constant).
background	Otherwise, the gradient value at (x, y).

Precondition

x and y are inside the page (the caller is the tile decoder).

No global state is consulted.

Postcondition

The result is a valid gray8 value.

No state is modified (pure function).

Note

Pure; thread-safe.

See also

ez_tile_decode

Since

0.1.0

Definition at line 158 of file ez_scene.c.

References k_ez_bg_lo, k_ez_grad_mask, k_ez_grad_shift, k_ez_grad_wrap, k_ez_ink, k_ez_rule_mask, k_ez_rule_thick, k_ez_word_blank, k_ez_word_mask, and k_ez_word_shift.

Referenced by ez_fill_tile().

ez_scene_init()

ra8_err_t ez_scene_init ( ez_scene_t * s, const ez_scene_cfg_t * cfg )

nodiscard

Wire the tile cache, the tiled source and both viewports.

Parameters

[out]	s	Scene to populate.
[in]	cfg	Borrowed storage and framebuffer geometry.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	The scene is ready to render.
k_ra8_err_null_ptr	s, cfg, or a required storage pointer is NULL.
k_ra8_err_invalid_arg	The framebuffer is too small for the layout.
k_ra8_err_*	Propagated from the cache or the zoom engine.

Precondition

Every pointer in cfg outlives the scene.

ra8_gfx_init has bound the same framebuffer the scene will paint.

Postcondition

On k_ra8_ok both views are open and owe a quality flush.

On any error the scene is not left half-built (lens_on is false).

Note

Not thread-safe.

See also

ez_scene_render

Since

0.1.0

Definition at line 430 of file ez_scene.c.

References ez_scene_t::content, ez_bind_page(), ez_cfg_ptrs_ok(), ez_content_rect(), ez_open_views(), ez_scene_cfg_t::fb, ez_scene_t::fb, ez_scene_cfg_t::fb_bytes, ez_scene_t::fb_bytes, ez_scene_cfg_t::fb_h, ez_scene_t::fb_h, ez_scene_cfg_t::fb_w, ez_scene_t::fb_w, k_ez_lens_edge, k_ez_status_h, k_ra8_err_invalid_arg, ez_scene_t::lens_on, RA8_CHECK_NULL_PTR, ra8_log_error, RA8_RETURN_ON_ERROR, and s_tag.

Referenced by ez_setup_scene().

ez_scene_prefetch()

ra8_err_t ez_scene_prefetch ( ez_scene_t * s, zoom_pan_t dir, uint16_t * out_warmed )

nodiscard

Warm the tiles one pan step ahead of the page viewport.

Parameters

[in,out]	s	Initialised scene.
[in]	dir	Direction of travel.
[out]	out_warmed	Tiles warmed (may be NULL).

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	The read-ahead sweep ran.
k_ra8_err_null_ptr	s is NULL.
k_ra8_err_*	Propagated from zoom_tiles_prefetch.

Precondition

s was initialised by ez_scene_init.

The caller is in an idle window (read-ahead is not free).

Postcondition

No on-screen tile is evicted (k_ez_prefetch_max is the spare margin).

*out_warmed (when given) is at most k_ez_prefetch_max.

Note

Not thread-safe.

See also

zoom_tiles_prefetch

Since

0.1.0

Definition at line 705 of file ez_scene.c.

References zoom_tile_src_t::cache, k_ez_prefetch_max, ez_scene_t::page, RA8_CHECK_NULL_PTR, s_tag, ez_scene_t::tiles, and zoom_tiles_prefetch().

Referenced by ez_apply_pan(), and ez_selftest_pan().

ez_scene_present()

ra8_err_t ez_scene_present ( ez_scene_t * s, ez_present_t * out )

nodiscard

Take the pending flush plan for whichever view changed.

A page change dirties the whole content rectangle; a loupe-only change dirties only the lens box, which is the partial-update case this demo exists to show. A view that owes nothing contributes nothing, so an idle reader never refreshes the panel.

Parameters

[in,out]	s	Initialised scene.
[out]	out	Receives the plan; out->present is false when none is owed.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	out holds the plan.
k_ra8_err_null_ptr	s or out is NULL.
k_ra8_err_*	Propagated from zoom_view_present.

Precondition

The framebuffer already holds the pixels this plan describes.

s was initialised by ez_scene_init.

Postcondition

Neither view still owes the flush this call reported.

A second immediate call reports present == false.

Note

Not thread-safe.

See also

ez_scene_render

Since

0.1.0

Definition at line 677 of file ez_scene.c.

References ez_choose_plan(), k_ra8_ok, ez_scene_t::lens, ez_scene_t::page, RA8_CHECK_NULL_PTR, RA8_RETURN_ON_ERROR, s_tag, and zoom_view_present().

Referenced by ez_redraw(), and ez_render_and_hash().

ez_scene_render()

ra8_err_t ez_scene_render ( ez_scene_t * s )

nodiscard

Repaint the content area, the loupe (when open) and the status bar.

Parameters

[in,out]

s

Initialised scene.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	The framebuffer holds the current scene.
k_ra8_err_null_ptr	s is NULL.
k_ra8_err_*	Propagated from zoom_view_render or ra8_gfx.

Precondition

ra8_gfx_init has bound the framebuffer.

s was initialised by ez_scene_init.

Postcondition

On k_ra8_ok every pixel of the panel has been written.

The ra8_gfx clip rectangle is reset to the whole framebuffer.

Note

Not thread-safe; writes the single ra8_gfx framebuffer binding.

See also

ez_scene_present

Since

0.1.0

Definition at line 624 of file ez_scene.c.

References ez_scene_t::content, ez_draw_lens_chrome(), ez_draw_status(), ez_lens_rect(), ez_scene_t::lens, ez_scene_t::lens_on, ez_scene_t::page, RA8_CHECK_NULL_PTR, RA8_RETURN_ON_ERROR, zoom_source_t::read, s_tag, ez_scene_t::src, and zoom_view_render().

Referenced by ez_redraw(), and ez_render_and_hash().

ez_scene_selftest()

ra8_err_t ez_scene_selftest ( ez_scene_t * s, ez_selftest_t * out )

nodiscard

Drive the scene through the scripted boot self-check.

Four states – opening 1:1, one right-pan step, 2x about a fixed panel point, and the 4x loupe – each rendered and hashed. This is the app's golden: apps/board/stand_alone/ereader/tests/src/test_app_ereader_zoom.c calls this same function over a host framebuffer and asserts the identical numbers, and hil.conf pins them for the headless emulator gate.

Parameters

[in,out]	s	Initialised scene (left in the loupe state on return).
[out]	out	Receives the four hashes and the cache counters.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	The sequence ran and out is populated.
k_ra8_err_null_ptr	s or out is NULL.
k_ra8_err_*	Propagated from a render or a viewport call.

Precondition

ra8_gfx_init has bound the framebuffer the hashes cover.

s was freshly initialised (the counters start from zero).

Postcondition

On k_ra8_ok the framebuffer holds the final (loupe) state.

On k_ra8_ok every counter in out reflects the whole sequence.

Note

Not thread-safe.

See also

ez_fnv1a

Since

0.1.0

Definition at line 861 of file ez_scene.c.

References ez_scene_t::cache, ez_selftest_t::evictions, ez_selftest_stages(), ez_selftest_t::hits, ez_selftest_t::misses, RA8_CHECK_NULL_PTR, RA8_RETURN_ON_ERROR, ra8_tile_cache_stats(), and s_tag.

Referenced by main().

ez_scene_tap()

bool ez_scene_tap ( ez_scene_t * s, int32_t x, int32_t y, uint32_t now_ms )

nodiscard

Apply a tap to the scene.

Parameters

[in,out]	s	Initialised scene.
[in]	x	Framebuffer column of the tap.
[in]	y	Framebuffer row of the tap.
[in]	now_ms	Current millisecond timestamp.

Returns

Whether anything changed and a redraw is due.

Return values

true	The scene changed; re-render and present.
false	The tap hit nothing, or clamped to no movement.

Precondition

s was initialised by ez_scene_init (NULL answers false).

now_ms comes from a monotonic millisecond source.

Postcondition

A true return leaves at least one view owing a flush.

A false return leaves the scene byte-identical.

Note

Not thread-safe.

See also

ez_zone_hit

Since

0.1.0

Definition at line 531 of file ez_scene.c.

References ez_apply_pan(), ez_zone_hit(), k_ez_lens_scale_max, k_ez_lens_scale_min, k_ez_page_scale_max, k_ez_zone_lens, k_ez_zone_toggle, k_ez_zone_zoom, k_ra8_ok, k_zoom_scale_min, ez_scene_t::lens, ez_scene_t::lens_on, ez_scene_t::page, zoom_view_t::scale, zoom_scale_cycle(), zoom_view_invalidate(), and zoom_view_set_scale().

Referenced by ez_poll_touch().

ez_scene_tick()

bool ez_scene_tick	(	ez_scene_t *	s,
		uint32_t	now_ms )

Advance both views' settle timers; report whether a repaint is due.

Parameters

[in,out]	s	Initialised scene.
[in]	now_ms	Current millisecond timestamp.

Returns

Whether a full-quality repaint just became due.

Return values

true	Re-render and present.
false	Nothing to do this tick.

Precondition

s was initialised by ez_scene_init (NULL answers false).

now_ms comes from a monotonic millisecond source.

Postcondition

A true return leaves a view owing a quality flush.

A false return leaves the scene unmodified.

Note

Not thread-safe.

See also

zoom_view_tick

Since

0.1.0

Definition at line 689 of file ez_scene.c.

References ez_scene_t::lens, ez_scene_t::lens_on, ez_scene_t::page, and zoom_view_tick().

Referenced by main().

ez_tile_decode()

ra8_err_t ez_tile_decode ( void * ctx, const ra8_tile_key_t * key, uint8_t * cell, uint32_t cell_bytes, uint16_t * out_w, uint16_t * out_h )

nodiscard

ra8_tile_decode_fn that materialises one page tile from the sampler.

The decode-on-miss seam. A real reader inflates a JOF tile here; the demo computes it, which keeps the app free of a multi-megabyte baked fixture while exercising the identical cache, eviction and residency behaviour.

Parameters

[in]	ctx	Unused (the page is a pure function).
[in]	key	The tile being decoded.
[out]	cell	Destination cell, cell_bytes writable bytes.
[in]	cell_bytes	Capacity of cell.
[out]	out_w	Receives the decoded tile width.
[out]	out_h	Receives the decoded tile height.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	The tile was written.
k_ra8_err_null_ptr	key, cell, out_w or out_h is NULL.
k_ra8_err_out_of_range	The key names a tile outside the page.
k_ra8_err_no_mem	cell_bytes is smaller than one tile.

Precondition

cell addresses at least cell_bytes writable bytes.

The cache was configured with cell_bytes >= k_ez_cell_bytes.

Postcondition

On k_ra8_ok *out_w == *out_h == k_ez_tile_edge.

On any error nothing is written past the failing check.

Note

Not thread-safe (writes cell); otherwise pure.

See also

ez_page_sample

Since

0.1.0

Definition at line 204 of file ez_scene.c.

References ez_fill_tile(), k_ez_cell_bytes, k_ez_page_h, k_ez_page_w, k_ez_tile_edge, k_ra8_err_no_mem, k_ra8_err_out_of_range, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_log_error, s_tag, ra8_tile_key_t::tile_x, and ra8_tile_key_t::tile_y.

Referenced by ez_bind_page().

ez_zone_hit()

ez_zone_t ez_zone_hit ( const ez_scene_t * s, int32_t x, int32_t y )

nodiscard

Classify a tap by the zone it lands in.

Parameters

[in]	s	Initialised scene.
[in]	x	Framebuffer column of the tap.
[in]	y	Framebuffer row of the tap.

Returns

The zone under the point.

Return values

k_ez_zone_none	The point is outside every zone.
a zone	Otherwise, the zone that owns the point.

Precondition

s was initialised by ez_scene_init (NULL answers none).

The coordinates are framebuffer pixels, not page-local.

Postcondition

No state is modified (pure query).

The loupe zone is only returned while the loupe is open.

Note

Pure with respect to s; thread-safe.

See also

ez_scene_tap

Since

0.1.0

Definition at line 451 of file ez_scene.c.

References ez_scene_t::content, ez_lens_rect(), ra8_ui_rect_t::h, k_ez_edge_band, k_ez_status_h, k_ez_zone_lens, k_ez_zone_none, k_ez_zone_pan_down, k_ez_zone_pan_left, k_ez_zone_pan_right, k_ez_zone_pan_up, k_ez_zone_toggle, k_ez_zone_zoom, ez_scene_t::lens_on, ra8_ui_rect_contains(), ra8_ui_rect_t::w, ra8_ui_rect_t::x, and ra8_ui_rect_t::y.

Referenced by ez_scene_tap().