Viewable manga reader: pan/zoom a page larger than the panel (Demo B). More...

#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include "jof.h"
#include "jof_produce.h"
#include "mg_page_fixture.h"
#include "mg_reader.h"
#include "ra8_board_ek_ra8d2.h"
#include "ra8_board_ek_ra8d2_touch.h"
#include "ra8_boot_entry.h"
#include "ra8_cgc.h"
#include "ra8_display_pal.h"
#include "ra8_display_pal_lcd.h"
#include "ra8_err.h"
#include "ra8_gfx.h"
#include "ra8_isr.h"
#include "ra8_mstp.h"
#include "ra8_panel.h"
#include "ra8_panel_timing.h"
#include "ra8_sdramc.h"
#include "ra8_tile_cache.h"
#include "ra8_time.h"
#include "ra8_touch.h"

Include dependency graph for main.c:

Data Structures
struct	mg_png_cursor_t
	Forward cursor over the baked PNG for the produce pull seam. More...

Enumerations
enum	mg_boot_t : uint32_t { k_mg_uart_baud = 115200U , k_mg_settle_ms = 500U , k_mg_frame_ms = 25U , k_mg_led_every = 16U , k_mg_touch_max_points = 1U }
	Boot / console / touch knobs. More...
enum	mg_atlas_t : uint32_t { k_mg_tile_edge = 256U , k_mg_cap_edge = 2048U , k_mg_cell_bytes = 256U * 256U , k_mg_view_cols , k_mg_view_rows , k_mg_cells = (k_mg_view_cols + 1U) * (k_mg_view_rows + 1U) , k_mg_buckets = 64U , k_mg_cell_budget_bytes = 4U * 1024U * 1024U , k_mg_scratch = 96U * 1024U , k_mg_work_bytes = 3203832U , k_mg_store_bytes = 4U * 1024U * 1024U , k_mg_image_id = 1U , k_mg_hex_nibbles = 8U , k_mg_nibble_bits = 4U , k_mg_nibble_mask = 0x0FU , k_mg_dec_ten = 10U }
	JOF produce + cache budget (page geometry rides in the fixture). More...
enum	mg_fb_t : uint16_t { k_mg_fb_w = k_panel_width_px , k_mg_fb_h = k_panel_height_px }
	Framebuffer geometry (mirrors the EK-RA8D2 panel). More...

Functions
	RA8_BOARD_PANEL_FRAMEBUFFER (s_framebuffer)
static void	mg_print (const uint8_t *msg, uint32_t len)
	Emit a byte run on the console.
static void	mg_panic_halt (const uint8_t *msg, uint32_t len)
	Print a fail banner, then trap (ra8_emulator halts on the BKPT).
static void	mg_print_hex (uint32_t value)
	Print a 32-bit value as 8 upper-case hex digits.
static void	mg_print_uint (uint32_t value)
	Print a small unsigned integer in decimal.
static void	mg_bringup_clocks (void)
	Bring up clocks, MSTP, system tick, LEDs and the SCI console.
static void	mg_bringup_panel (void)
	Bring up SDRAM + the GLCDC panel, then bind ra8_gfx to the FB.
static void	mg_bringup_touch (void)
	Open the GT911 touch controller (best-effort, polled).
static ra8_err_t	mg_png_pull (void ctx, uint8_t buf, size_t cap, size_t *got)
	produce pull seam: stream the baked PNG bytes to the transcoder.
static bool	mg_build_atlas (void)
	Transcode the baked page into a JOF atlas + parse its geometry.
static bool	mg_setup_cache (void)
	Wire the tile cache (decode-on-miss = read_tile) over the atlas.
static void	mg_present (void)
	Present the framebuffer (clean full update).
static void	mg_print_banner (void)
	Print the deterministic boot banner (geometry + render hash).
static void	mg_poll_touch (bool *was_touching)
	Poll the GT911 once; on a fresh tap, mutate + redraw the viewport.
void	main (void)
	App entry: panel bring-up -> atlas -> tile cache -> pan/zoom loop.

Variables
static uint8_t	s_work [k_mg_work_bytes]
	Producer work arena (SDRAM: the transcode working set).
static uint8_t	s_store_buf [k_mg_store_bytes]
	Atlas memstore backing (SDRAM: the produced JOF atlas).
static uint8_t	s_cell_mem [(size_t) k_mg_cells *(size_t) k_mg_cell_bytes]
	Tile-cache cell storage (k_mg_cells gray8 256x256 tiles, SDRAM).
static uint8_t	s_scratch [k_mg_scratch]
	read_tile deflate stored-stream staging (SDRAM).
static const display_cfg_t	k_mg_display_cfg
	Display PAL config – LCD/GLCDC backend over the SDRAM framebuffer.
static display_handle_t *	s_display = nullptr
	PAL handle returned by display_init.
static display_fb_t	s_fb
	Mutable copy of the FB descriptor; populated at boot.
static jof_memstore_t	s_store
	The atlas memstore (sink + pread pair over s_store_buf).
static jof_info_t	s_info
	Parsed atlas geometry after produce.
static ra8_tile_cache_t	s_cache
	Tile-cache state paging the atlas.
static mg_tile_src_t	s_tile_src
	Decode-on-miss context bound into the cache.
static mg_reader_t	s_reader
	The pan/zoom viewer over the tiled page.
static ra8_tile_key_t	s_keys [k_mg_cells]
	Tile-cache key storage (one per cell).
static ra8_tile_dims_t	s_dims [k_mg_cells]
	Tile-cache dim descriptors (one per cell).
static ra8_keycache_cell_t	s_meta [k_mg_cells]
	Tile-cache link metadata (one per cell).
static int32_t	s_buckets [k_mg_buckets]
	Tile-cache hash buckets.
static mg_png_cursor_t	s_png_cursor
	PNG pull cursor for the produce source.
static const uint8_t	k_msg_boot [] = "ereader-manga: boot\r\n"
	Bound I2C bus handle the touch driver's injected seam points at.
static const uint8_t	k_msg_fail [] = "ereader-manga: FAIL init\r\n"
static const uint8_t	k_msg_atl [] = "ereader-manga: FAIL atlas\r\n"
static const uint8_t	k_msg_rend [] = "ereader-manga: FAIL render\r\n"
static const uint8_t	k_msg_pre [] = "ereader-manga: page "
static const uint8_t	k_msg_x [] = "x"
static const uint8_t	k_msg_tiles [] = " tiles="
static const uint8_t	k_msg_atlas [] = " atlas="
static const uint8_t	k_msg_view [] = " view=0,0 zoom=1:1 crc="
static const uint8_t	k_msg_ok [] = " ok\r\n"

Detailed Description

Viewable manga reader: pan/zoom a page larger than the panel (Demo B).

Tag: [Ring 7 / App] {World: NS}

The viewable counterpart of the #231 tile pipeline. Where the old headless gate rendered a 160x120 crop into an internal buffer, this app brings up the real 1024x600 GLCDC panel and lets the user pan and zoom a page far bigger than the screen:

Boot clocks / MSTP / SysTick / LEDs, then SDRAM + the GLCDC panel (ra8_display_pal with k_display_backend_lcd_ra8_glcdc), then bind ra8_gfx to the 1024x600 RGB565 framebuffer in SDRAM.
Transcode the baked 1536x2048 grayscale PNG page (mg_page_fixture.h) into a JOF tile atlas with jof_produce – one bounded band at a time, the decoded page never resident whole – into an SDRAM memstore.
Serve the atlas through an ra8_tile_cache sized (k_mg_cells) to the 1:1 viewport tile demand plus a one-tile pan margin, so panning evicts only newly exposed tiles instead of thrashing (#338).
Main loop: poll the GT911, hit-test the tap-zones (four edges pan, the centre toggles 1:1 <-> fit-page), redraw the viewport + status bar + minimap, and present.

A deterministic banner is printed once at boot over the SCI console so the headless EIL gate still asserts a fixed render:

ereader-manga: page 1536x2048 tiles=48 atlas=<N> view=0,0 zoom=1:1 crc=<8hex> ok

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

Since: 0.1.0

Definition in file main.c.

Enumeration Type Documentation

◆ mg_atlas_t

enum mg_atlas_t : uint32_t

JOF produce + cache budget (page geometry rides in the fixture).

Since: 0.1.0

Enumerator
k_mg_tile_edge	Import + cache tile edge, pixels.
k_mg_cap_edge	Produce budget cap, pixels.
k_mg_cell_bytes	One gray8 256x256 tile.
k_mg_view_cols	1:1 cols.
k_mg_view_rows	1:1 content rows.
k_mg_cells	Frame + 1-tile pan margin.
k_mg_buckets	Hash buckets (>= cells).
k_mg_cell_budget_bytes	SDRAM tile cache may claim.
k_mg_scratch	read_tile deflate staging.
k_mg_work_bytes	SDRAM producer work arena.
k_mg_store_bytes	SDRAM atlas memstore.
k_mg_image_id	Tile-cache key image id.
k_mg_hex_nibbles	Hex digits per 32-bit value.
k_mg_nibble_bits	Bits per hex nibble.
k_mg_nibble_mask	Low-nibble mask.
k_mg_dec_ten	Decimal radix / hex split.

Definition at line 82 of file main.c.

◆ mg_boot_t

enum mg_boot_t : uint32_t

Boot / console / touch knobs.

Since: 0.1.0

Enumerator
k_mg_uart_baud	Console baud.
k_mg_settle_ms	PLL / SDRAM / panel-POR settle.
k_mg_frame_ms	Input poll period, ms.
k_mg_led_every	Heartbeat LED toggle sub-cadence.
k_mg_touch_max_points	One contact = one tap.

Definition at line 69 of file main.c.

◆ mg_fb_t

enum mg_fb_t : uint16_t

Framebuffer geometry (mirrors the EK-RA8D2 panel).

Since: 0.1.0

Enumerator
k_mg_fb_w	Framebuffer width, pixels.
k_mg_fb_h	Framebuffer height, pixels.

Definition at line 178 of file main.c.

Function Documentation

◆ main()

void main ( void )

App entry: panel bring-up -> atlas -> tile cache -> pan/zoom loop.

The application entry point Reset_Handler hands control to.

Precondition: Reset_Handler copied .data and zeroed .bss.; SystemInit set VTOR / FPU / priority grouping.

Postcondition: The boot banner is emitted; the reader loop services taps forever.

Since: 0.1.0

Definition at line 498 of file main.c.

References k_mg_fb_h, k_mg_fb_w, k_mg_frame_ms, k_mg_image_id, k_mg_led_every, k_msg_atl, k_msg_boot, k_msg_rend, k_ra8_board_led_blue, k_ra8_ok, mg_bringup_clocks(), mg_bringup_panel(), mg_bringup_touch(), mg_build_atlas(), mg_panic_halt(), mg_poll_touch(), mg_present(), mg_print(), mg_print_banner(), mg_reader_init(), mg_reader_render(), mg_setup_cache(), ra8_board_led_toggle(), ra8_delay_ms(), s_cache, s_framebuffer, s_info, and s_reader.

◆ mg_bringup_clocks()

void mg_bringup_clocks ( void )

static

Bring up clocks, MSTP, system tick, LEDs and the SCI console.

Definition at line 318 of file main.c.

References k_mg_uart_baud, k_msg_fail, k_ra8_board_led_blue, k_ra8_board_led_red, k_ra8_clock_id_cpuclk0, k_ra8_ok, mg_panic_halt(), ra8_board_led_init(), ra8_board_uart_console_init(), ra8_cgc_get_clock_hz(), ra8_cgc_init(), ra8_isr_globals_enable(), ra8_mstp_init(), and ra8_time_init().

Referenced by main().

◆ mg_bringup_panel()

void mg_bringup_panel ( void )

static

Bring up SDRAM + the GLCDC panel, then bind ra8_gfx to the FB.

Definition at line 341 of file main.c.

References display_get_framebuffer(), display_init(), k_mg_display_cfg, k_mg_settle_ms, k_msg_fail, k_ra8_gfx_format_rgb565, k_ra8_ok, mg_panic_halt(), ra8_delay_ms(), ra8_gfx_init(), ra8_sdramc_init(), s_display, and s_fb.

Referenced by main().

◆ mg_bringup_touch()

void mg_bringup_touch ( void )

static

Open the GT911 touch controller (best-effort, polled).

Definition at line 360 of file main.c.

References k_mg_touch_max_points, k_ra8_touch_irq_pin_unset, and ra8_board_touch_open().

Referenced by main().

◆ mg_build_atlas()

bool mg_build_atlas ( void )

static

Transcode the baked page into a JOF atlas + parse its geometry.

Definition at line 384 of file main.c.

References jof_memstore_pread(), jof_memstore_sink(), jof_parse(), jof_produce(), jof_work_bytes(), k_jof_codec_deflate, k_mg_cap_edge, k_mg_png, k_mg_png_len, k_mg_tile_edge, k_ra8_ok, mg_png_pull(), s_info, s_png_cursor, s_store, s_store_buf, and s_work.

Referenced by main().

◆ mg_panic_halt()

void mg_panic_halt	(	const uint8_t *	msg,
		uint32_t	len )

static

Print a fail banner, then trap (ra8_emulator halts on the BKPT).

Definition at line 272 of file main.c.

References k_ra8_board_led_red, mg_print(), and ra8_board_led_on().

Referenced by main(), mg_bringup_clocks(), and mg_bringup_panel().

◆ mg_png_pull()

ra8_err_t mg_png_pull	(	void *	ctx,
		uint8_t *	buf,
		size_t	cap,
		size_t *	got )

static

produce pull seam: stream the baked PNG bytes to the transcoder.

Definition at line 372 of file main.c.

References mg_png_cursor_t::data, k_ra8_ok, mg_png_cursor_t::len, memcpy(), and mg_png_cursor_t::pos.

Referenced by mg_build_atlas().

◆ mg_poll_touch()

void mg_poll_touch ( bool * was_touching )

static

Poll the GT911 once; on a fresh tap, mutate + redraw the viewport.

Definition at line 470 of file main.c.

References k_ra8_ok, mg_present(), mg_reader_prefetch(), mg_reader_render(), mg_reader_tap(), ra8_touch_read(), s_reader, ra8_touch_point_t::x, and ra8_touch_point_t::y.

Referenced by main().

◆ mg_present()

void mg_present ( void )

static

Present the framebuffer (clean full update).

Definition at line 448 of file main.c.

References display_flush(), display_full_rect(), k_display_refresh_quality, and s_display.

Referenced by main(), and mg_poll_touch().

◆ mg_print()

void mg_print	(	const uint8_t *	msg,
		uint32_t	len )

static

Emit a byte run on the console.

Definition at line 266 of file main.c.

References ra8_board_uart_console_write().

Referenced by main(), mg_panic_halt(), mg_print_banner(), mg_print_hex(), and mg_print_uint().

◆ mg_print_banner()

void mg_print_banner ( void )

static

Print the deterministic boot banner (geometry + render hash).

Definition at line 454 of file main.c.

References k_msg_atlas, k_msg_ok, k_msg_pre, k_msg_tiles, k_msg_view, k_msg_x, mg_fnv1a(), mg_print(), mg_print_hex(), mg_print_uint(), s_framebuffer, and s_info.

Referenced by main().

◆ mg_print_hex()

void mg_print_hex ( uint32_t value )

static

Print a 32-bit value as 8 upper-case hex digits.

Definition at line 283 of file main.c.

References k_mg_dec_ten, k_mg_hex_nibbles, k_mg_nibble_bits, k_mg_nibble_mask, and mg_print().

Referenced by mg_print_banner().

◆ mg_print_uint()

void mg_print_uint ( uint32_t value )

static

Print a small unsigned integer in decimal.

Definition at line 295 of file main.c.

References k_mg_dec_ten, and mg_print().

Referenced by mg_print_banner().

◆ mg_setup_cache()

bool mg_setup_cache ( void )

static

Wire the tile cache (decode-on-miss = read_tile) over the atlas.

Definition at line 427 of file main.c.

References jof_memstore_pread(), k_mg_buckets, k_mg_cell_bytes, k_mg_cells, k_ra8_ok, mg_tile_decode(), ra8_tile_cache_init(), s_buckets, s_cache, s_cell_mem, s_dims, s_info, s_keys, s_meta, s_scratch, s_store, and s_tile_src.

Referenced by main().

◆ RA8_BOARD_PANEL_FRAMEBUFFER()

RA8_BOARD_PANEL_FRAMEBUFFER ( s_framebuffer )

References s_framebuffer.

Variable Documentation

◆ k_mg_display_cfg

const display_cfg_t k_mg_display_cfg

static

Initial value:

                                            = {
  .iface             = &k_display_backend_lcd_ra8_glcdc,
  .framebuffer       = s_framebuffer,
  .framebuffer_bytes = sizeof(s_framebuffer),
  .width_px          = (uint16_t)k_mg_fb_w,
  .height_px         = (uint16_t)k_mg_fb_h,
  .pixfmt            = k_display_pixfmt_rgb565,
  .panel_timing      = &s_ra8_panel_ek_ra8d2_timing,
}

Display PAL config – LCD/GLCDC backend over the SDRAM framebuffer.

Definition at line 203 of file main.c.

Referenced by mg_bringup_panel().

◆ k_msg_atl

const uint8_t k_msg_atl[] = "ereader-manga: FAIL atlas\r\n"

static

Definition at line 256 of file main.c.

Referenced by main().

◆ k_msg_atlas

const uint8_t k_msg_atlas[] = " atlas="

static

Definition at line 261 of file main.c.

Referenced by mg_print_banner().

◆ k_msg_boot

const uint8_t k_msg_boot[] = "ereader-manga: boot\r\n"

static

Bound I2C bus handle the touch driver's injected seam points at.

Definition at line 254 of file main.c.

◆ k_msg_fail

const uint8_t k_msg_fail[] = "ereader-manga: FAIL init\r\n"

static

Definition at line 255 of file main.c.

◆ k_msg_ok

const uint8_t k_msg_ok[] = " ok\r\n"

static

Definition at line 263 of file main.c.

◆ k_msg_pre

const uint8_t k_msg_pre[] = "ereader-manga: page "

static

Definition at line 258 of file main.c.

◆ k_msg_rend

const uint8_t k_msg_rend[] = "ereader-manga: FAIL render\r\n"

static

Definition at line 257 of file main.c.

Referenced by main().

◆ k_msg_tiles

const uint8_t k_msg_tiles[] = " tiles="

static

Definition at line 260 of file main.c.

Referenced by mg_print_banner().

◆ k_msg_view

const uint8_t k_msg_view[] = " view=0,0 zoom=1:1 crc="

static

Definition at line 262 of file main.c.

◆ k_msg_x

const uint8_t k_msg_x[] = "x"

static

Definition at line 259 of file main.c.

◆ s_buckets

int32_t s_buckets[k_mg_buckets]

static

Tile-cache hash buckets.

Definition at line 236 of file main.c.

◆ s_cache

ra8_tile_cache_t s_cache

static

Tile-cache state paging the atlas.

Definition at line 223 of file main.c.

◆ s_cell_mem

uint8_t s_cell_mem[(size_t) k_mg_cells *(size_t) k_mg_cell_bytes]

static

Tile-cache cell storage (k_mg_cells gray8 256x256 tiles, SDRAM).

Definition at line 198 of file main.c.

Referenced by ez_setup_scene(), and mg_setup_cache().

◆ s_dims

ra8_tile_dims_t s_dims[k_mg_cells]

static

Tile-cache dim descriptors (one per cell).

Definition at line 232 of file main.c.

◆ s_display

display_handle_t* s_display = nullptr

static

PAL handle returned by display_init.

Definition at line 214 of file main.c.

◆ s_fb

display_fb_t s_fb

static

Mutable copy of the FB descriptor; populated at boot.

Definition at line 216 of file main.c.

◆ s_info

jof_info_t s_info

static

Parsed atlas geometry after produce.

Definition at line 221 of file main.c.

Referenced by main(), mg_build_atlas(), mg_print_banner(), and mg_setup_cache().

◆ s_keys

ra8_tile_key_t s_keys[k_mg_cells]

static

Tile-cache key storage (one per cell).

Definition at line 230 of file main.c.

◆ s_meta

ra8_keycache_cell_t s_meta[k_mg_cells]

static

Tile-cache link metadata (one per cell).

Definition at line 234 of file main.c.

◆ s_png_cursor

mg_png_cursor_t s_png_cursor

static

PNG pull cursor for the produce source.

Definition at line 250 of file main.c.

Referenced by mg_build_atlas().

◆ s_reader

mg_reader_t s_reader

static

The pan/zoom viewer over the tiled page.

Definition at line 227 of file main.c.

Referenced by main(), mg_poll_touch(), wa_verify_or_halt(), wd_check_damage(), wd_check_touch_dispatch(), wd_register_apps(), and wd_selfcheck().

◆ s_scratch

uint8_t s_scratch[k_mg_scratch]

static

read_tile deflate stored-stream staging (SDRAM).

Definition at line 200 of file main.c.

◆ s_store

jof_memstore_t s_store

static

The atlas memstore (sink + pread pair over s_store_buf).

Definition at line 219 of file main.c.

◆ s_store_buf

uint8_t s_store_buf[k_mg_store_bytes]

static

Atlas memstore backing (SDRAM: the produced JOF atlas).

Definition at line 195 of file main.c.

Referenced by mg_build_atlas().

◆ s_tile_src

mg_tile_src_t s_tile_src

static

Decode-on-miss context bound into the cache.

Definition at line 225 of file main.c.

Referenced by mg_setup_cache().

◆ s_work

uint8_t s_work[k_mg_work_bytes]

static

Producer work arena (SDRAM: the transcode working set).

Definition at line 193 of file main.c.

Referenced by mg_build_atlas().

Data Structures

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ mg_atlas_t

◆ mg_boot_t

◆ mg_fb_t

Function Documentation

◆ main()

◆ mg_bringup_clocks()

◆ mg_bringup_panel()

◆ mg_bringup_touch()

◆ mg_build_atlas()

◆ mg_panic_halt()

◆ mg_png_pull()

◆ mg_poll_touch()

◆ mg_present()

◆ mg_print()

◆ mg_print_banner()

◆ mg_print_hex()

◆ mg_print_uint()

◆ mg_setup_cache()

◆ RA8_BOARD_PANEL_FRAMEBUFFER()

Variable Documentation

◆ k_mg_display_cfg

◆ k_msg_atl

◆ k_msg_atlas

◆ k_msg_boot

◆ k_msg_fail

◆ k_msg_ok

◆ k_msg_pre

◆ k_msg_rend

◆ k_msg_tiles

◆ k_msg_view

◆ k_msg_x

◆ s_buckets

◆ s_cache

◆ s_cell_mem

◆ s_dims

◆ s_display

◆ s_fb

◆ s_info

◆ s_keys

◆ s_meta

◆ s_png_cursor

◆ s_reader

◆ s_scratch

◆ s_store

◆ s_store_buf

◆ s_tile_src

◆ s_work