ez_scene.c

Go to the documentation of this file.

 
#include "ez_scene.h"
 
#include <stddef.h>
#include <stdint.h>
 
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_gfx.h"
#include "ra8_tile_cache.h"
#include "ra8_ui.h"
#include "zoom.h"
#include "zoom_tiles.h"

static const char* const s_tag = "ereader_zoom";
 
/*
 * ::k_ez_cells is DERIVED from the panel and tile geometry, never hand-picked
 * (#338). At 1:1 the 1024x552 content window over 256x256 tiles straddles at
 * most ceil(1024/256)+1 = 5 columns and ceil(552/256)+1 = 4 rows; the enum
 * carries one more column than that so a horizontal pan step (which is nearly a
 * whole viewport) still finds the union of before/after resident. Sizing the
 * cache to that frame plus one tile of margin on each axis means a pan
 * re-decodes only the newly exposed row or column, never a tile still on screen.
 * The first assert fails the build if the derivation is ever undercut; the
 * second bounds the resident arena so it cannot silently balloon.
 */
static_assert((uint64_t)k_ez_cells >= ((uint64_t)k_ez_view_cols * (uint64_t)k_ez_view_rows),
              "tile cache is smaller than the 1:1 viewport tile demand: re-derive k_ez_cells "
              "from the panel + tile geometry so a single-step pan cannot thrash (#338)");
static_assert((uint64_t)k_ez_cells * (uint64_t)k_ez_cell_bytes <= (uint64_t)k_ez_cell_budget_bytes,
              "resident tile arena exceeds its SDRAM budget");
static_assert((k_ez_page_w % k_ez_tile_edge) == 0U,
              "page width must tile exactly: the demo asserts a full-tile geometry");
static_assert((k_ez_page_h % k_ez_tile_edge) == 0U,
              "page height must tile exactly: the demo asserts a full-tile geometry");
/*
 * The composite scratch is sized for the WIDEST viewport and shared by both
 * views, which is only sound while the packed buffer can hold a full strip of
 * that width. 1024 x 16 rows packed at 2 px/byte is exactly k_ez_packed_bytes.
 */
static_assert((uint64_t)k_ez_packed_bytes >= (((uint64_t)k_ez_strip_bytes + 1U) / 2U),
              "packed scratch cannot hold one dithered strip of the widest viewport");
static_assert((uint64_t)k_ez_lens_edge < (uint64_t)k_ez_row_bytes,
              "the loupe must be narrower than the shared composite row buffer");

typedef enum : uint32_t {
  k_ez_bg_lo      = 140U, 
  k_ez_grad_shift = 4U,   
  k_ez_grad_mask  = 63U,  
  k_ez_grad_wrap  = 127U, 
  k_ez_ink        = 24U,  
  k_ez_rule_mask  = 31U,  
  k_ez_rule_thick = 3U,   
  k_ez_word_shift = 5U,   
  k_ez_word_mask  = 7U,   
  k_ez_word_blank = 7U,   
} ez_tone_t;

typedef enum : uint32_t {
  k_ez_col_bar  = 0x00222222U, 
  k_ez_col_ind  = 0x00DDDDDDU, 
  k_ez_col_dim  = 0x00555555U, 
  k_ez_col_lens = 0x00000000U, 
} ez_chrome_t;

typedef enum : uint32_t {
  k_ez_fnv_offset = 2166136261U, 
  k_ez_fnv_prime  = 16777619U,   
} ez_fnv_t;

typedef enum : uint16_t {
  k_ez_st_focus_x = 700U, 
  k_ez_st_focus_y = 400U, 
  k_ez_st_scale   = 2U,   
  k_ez_st_t0      = 0U,   
} ez_selftest_step_t;
 
uint8_t ez_page_sample(uint32_t x, uint32_t y)
{
  /* A TRIANGLE wave, not a sawtooth: a sawtooth's wrap is a real tone
   * discontinuity in the source, and it would read on the panel as exactly the
   * banding artefact this demo exists to show the dither removing. */
  const uint32_t phase = ((x >> (uint32_t)k_ez_grad_shift) + (y >> (uint32_t)k_ez_grad_shift)) &
                         (uint32_t)k_ez_grad_wrap;
  const uint32_t band =
    (phase <= (uint32_t)k_ez_grad_mask) ? phase : ((uint32_t)k_ez_grad_wrap - phase);
  const bool on_rule = ((y & (uint32_t)k_ez_rule_mask) < (uint32_t)k_ez_rule_thick);
  const bool inked =
    (((x >> (uint32_t)k_ez_word_shift) & (uint32_t)k_ez_word_mask) != (uint32_t)k_ez_word_blank);
  if (on_rule && inked) {
    return (uint8_t)k_ez_ink;
  }
  return (uint8_t)((uint32_t)k_ez_bg_lo + band);
}

static void ez_fill_tile(uint8_t* cell, uint32_t org_x, uint32_t org_y)
{
  for (uint32_t r = 0U; r < (uint32_t)k_ez_tile_edge; ++r) {
    uint8_t* row = &cell[(size_t)r * (size_t)k_ez_tile_edge];
    for (uint32_t c = 0U; c < (uint32_t)k_ez_tile_edge; ++c) {
      row[c] = ez_page_sample(org_x + c, org_y + r);
    }
  }
}
 
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)
{
  (void)ctx;
  RA8_CHECK_NULL_PTR(key, s_tag, "tile key must not be nullptr");
  RA8_CHECK_NULL_PTR(cell, s_tag, "tile cell must not be nullptr");
  RA8_CHECK_NULL_PTR(out_w, s_tag, "out_w must not be nullptr");
  RA8_CHECK_NULL_PTR(out_h, s_tag, "out_h must not be nullptr");
  if (cell_bytes < (uint32_t)k_ez_cell_bytes) {
    ra8_log_error(s_tag, "tile cell is smaller than one page tile");
    return k_ra8_err_no_mem;
  }
  const uint32_t org_x = (uint32_t)key->tile_x * (uint32_t)k_ez_tile_edge;
  const uint32_t org_y = (uint32_t)key->tile_y * (uint32_t)k_ez_tile_edge;
  if ((org_x >= (uint32_t)k_ez_page_w) || (org_y >= (uint32_t)k_ez_page_h)) {
    ra8_log_error(s_tag, "tile key names a tile outside the page");
    return k_ra8_err_out_of_range;
  }
  ez_fill_tile(cell, org_x, org_y);
  *out_w = (uint16_t)k_ez_tile_edge;
  *out_h = (uint16_t)k_ez_tile_edge;
  return k_ra8_ok;
}
 
ra8_ui_rect_t ez_content_rect(int32_t fb_w, int32_t fb_h)
{
  const ra8_ui_rect_t r = {
    .x = 0,
    .y = (int32_t)k_ez_status_h,
    .w = fb_w,
    .h = fb_h - (int32_t)k_ez_status_h,
  };
  return r;
}

static ra8_ui_rect_t ez_lens_rect(ra8_ui_rect_t content)
{
  const ra8_ui_rect_t r = {
    .x = content.x + ((content.w - (int32_t)k_ez_lens_edge) / 2),
    .y = content.y + ((content.h - (int32_t)k_ez_lens_edge) / 2),
    .w = (int32_t)k_ez_lens_edge,
    .h = (int32_t)k_ez_lens_edge,
  };
  return r;
}

static zoom_scratch_t ez_scratch_of(const ez_scene_cfg_t* cfg)
{
  const zoom_scratch_t sc = {
    .row        = cfg->row,
    .row_cap    = (uint32_t)k_ez_row_bytes,
    .strip      = cfg->strip,
    .strip_cap  = (uint32_t)k_ez_strip_bytes,
    .packed     = cfg->packed,
    .packed_cap = (uint32_t)k_ez_packed_bytes,
  };
  return sc;
}

static ra8_err_t ez_cfg_scratch_ok(const ez_scene_cfg_t* cfg)
{
  RA8_CHECK_NULL_PTR(cfg->row, s_tag, "row scratch must not be nullptr");
  RA8_CHECK_NULL_PTR(cfg->strip, s_tag, "strip scratch must not be nullptr");
  RA8_CHECK_NULL_PTR(cfg->packed, s_tag, "packed scratch must not be nullptr");
  return k_ra8_ok;
}

static ra8_err_t ez_cfg_ptrs_ok(const ez_scene_cfg_t* cfg)
{
  RA8_CHECK_NULL_PTR(cfg->fb, s_tag, "framebuffer must not be nullptr");
  RA8_CHECK_NULL_PTR(cfg->cell_mem, s_tag, "cell_mem must not be nullptr");
  RA8_CHECK_NULL_PTR(cfg->meta, s_tag, "meta must not be nullptr");
  RA8_CHECK_NULL_PTR(cfg->keys, s_tag, "keys must not be nullptr");
  RA8_CHECK_NULL_PTR(cfg->dims, s_tag, "dims must not be nullptr");
  RA8_CHECK_NULL_PTR(cfg->buckets, s_tag, "buckets must not be nullptr");
  return ez_cfg_scratch_ok(cfg);
}

static ra8_err_t ez_open_views(ez_scene_t* s, const ez_scene_cfg_t* cfg)
{
  const zoom_scratch_t  scratch  = ez_scratch_of(cfg);
  const zoom_view_cfg_t page_cfg = {
    .src       = s->src,
    .scratch   = scratch,
    .dst       = s->content,
    .scale     = (uint8_t)k_zoom_scale_min,
    .scale_max = (uint8_t)k_ez_page_scale_max,
    .policy    = k_zoom_policy_responsive,
    .settle_ms = 0U,
    .focus_x   = 0,
    .focus_y   = 0,
  };
  RA8_RETURN_ON_ERROR(zoom_view_open(&s->page, &page_cfg), s_tag, "page view open");
 
  const ra8_ui_rect_t   lens     = ez_lens_rect(s->content);
  const zoom_view_cfg_t lens_cfg = {
    .src       = s->src,
    .scratch   = scratch,
    .dst       = lens,
    .scale     = (uint8_t)k_ez_lens_scale_min,
    .scale_max = (uint8_t)k_ez_lens_scale_max,
    .policy    = k_zoom_policy_responsive,
    .settle_ms = 0U,
    .focus_x   = 0,
    .focus_y   = 0,
  };
  return zoom_view_open(&s->lens, &lens_cfg);
}

static ra8_err_t ez_bind_page(ez_scene_t* s, const ez_scene_cfg_t* cfg)
{
  const ra8_tile_cache_cfg_t cache_cfg = {
    .cell_mem     = cfg->cell_mem,
    .cell_bytes   = (uint32_t)k_ez_cell_bytes,
    .cell_count   = (uint32_t)k_ez_cells,
    .meta         = cfg->meta,
    .keys         = cfg->keys,
    .dims         = cfg->dims,
    .buckets      = cfg->buckets,
    .bucket_count = (uint32_t)k_ez_buckets,
    .decode       = ez_tile_decode,
    .decode_ctx   = nullptr,
  };
  RA8_RETURN_ON_ERROR(ra8_tile_cache_init(&s->cache, &cache_cfg), s_tag, "tile cache init");
  RA8_RETURN_ON_ERROR(zoom_tile_src_init(&s->tiles,
                                         &s->cache,
                                         (uint32_t)k_ez_image_id,
                                         (uint32_t)k_ez_page_w,
                                         (uint32_t)k_ez_page_h,
                                         (uint16_t)k_ez_tile_edge,
                                         (uint16_t)k_ez_tile_edge),
                      s_tag,
                      "tiled source init");
  return zoom_tile_src_bind(&s->tiles, &s->src);
}
 
ra8_err_t ez_scene_init(ez_scene_t* s, const ez_scene_cfg_t* cfg)
{
  RA8_CHECK_NULL_PTR(s, s_tag, "scene must not be nullptr");
  RA8_CHECK_NULL_PTR(cfg, s_tag, "cfg must not be nullptr");
  s->lens_on = false;
  RA8_RETURN_ON_ERROR(ez_cfg_ptrs_ok(cfg), s_tag, "cfg pointer check");
  if ((cfg->fb_w <= (int32_t)k_ez_lens_edge) ||
      (cfg->fb_h <= ((int32_t)k_ez_status_h + (int32_t)k_ez_lens_edge))) {
    ra8_log_error(s_tag, "framebuffer is too small for the demo layout");
    return k_ra8_err_invalid_arg;
  }
  s->fb       = cfg->fb;
  s->fb_bytes = cfg->fb_bytes;
  s->fb_w     = cfg->fb_w;
  s->fb_h     = cfg->fb_h;
  s->content  = ez_content_rect(cfg->fb_w, cfg->fb_h);
 
  RA8_RETURN_ON_ERROR(ez_bind_page(s, cfg), s_tag, "page binding");
  return ez_open_views(s, cfg);
}
 
ez_zone_t ez_zone_hit(const ez_scene_t* s, int32_t x, int32_t y)
{
  if (s == nullptr) {
    return k_ez_zone_none;
  }
  if (y < (int32_t)k_ez_status_h) {
    return k_ez_zone_toggle;
  }
  if (!ra8_ui_rect_contains(&s->content, x, y)) {
    return k_ez_zone_none;
  }
  const ra8_ui_rect_t lens = ez_lens_rect(s->content);
  if (s->lens_on && ra8_ui_rect_contains(&lens, x, y)) {
    return k_ez_zone_lens;
  }
  if (x < (s->content.x + (int32_t)k_ez_edge_band)) {
    return k_ez_zone_pan_left;
  }
  if (x >= ((s->content.x + s->content.w) - (int32_t)k_ez_edge_band)) {
    return k_ez_zone_pan_right;
  }
  if (y < (s->content.y + (int32_t)k_ez_edge_band)) {
    return k_ez_zone_pan_up;
  }
  if (y >= ((s->content.y + s->content.h) - (int32_t)k_ez_edge_band)) {
    return k_ez_zone_pan_down;
  }
  return k_ez_zone_zoom;
}

static bool ez_apply_pan(ez_scene_t* s, ez_zone_t zone, uint32_t now_ms)
{
  zoom_pan_t dir = k_zoom_pan_none;
  switch (zone) {
    case k_ez_zone_pan_left:
      dir = k_zoom_pan_left;
      break;
    case k_ez_zone_pan_right:
      dir = k_zoom_pan_right;
      break;
    case k_ez_zone_pan_up:
      dir = k_zoom_pan_up;
      break;
    case k_ez_zone_pan_down:
      dir = k_zoom_pan_down;
      break;
    default:
      return false;
  }
  ra8_ui_rect_t before = {};
  ra8_ui_rect_t after  = {};
  (void)zoom_view_window(&s->page, &before);
  if (zoom_view_pan_dir(&s->page, dir, now_ms) != k_ra8_ok) {
    return false;
  }
  (void)zoom_view_window(&s->page, &after);
  if ((after.x == before.x) && (after.y == before.y)) {
    return false;
  }
  /* Idle-window read-ahead: warm the tiles the next step in this direction
   * will expose, out of the cache's spare margin (#341). */
  (void)ez_scene_prefetch(s, dir, nullptr);
  return true;
}
 
bool ez_scene_tap(ez_scene_t* s, int32_t x, int32_t y, uint32_t now_ms)
{
  if (s == nullptr) {
    return false;
  }
  const ez_zone_t zone = ez_zone_hit(s, x, y);
  if (zone == k_ez_zone_toggle) {
    s->lens_on = !s->lens_on;
    /* The loupe covers page pixels, so opening or closing it damages the whole
     * content rectangle -- damage the engine cannot see, because neither the
     * anchor nor the scale moved. Say so explicitly: a pan of (0, 0) would
     * correctly report "nothing moved" and the lens would never be flushed to
     * an e-ink panel (a continuously-scanned LCD would hide the bug entirely). */
    return zoom_view_invalidate(&s->page, now_ms) == k_ra8_ok;
  }
  if (zone == k_ez_zone_lens) {
    const uint8_t next =
      zoom_scale_cycle(s->lens.scale, (uint8_t)k_ez_lens_scale_min, (uint8_t)k_ez_lens_scale_max);
    return zoom_view_set_scale(&s->lens, next, x, y, now_ms) == k_ra8_ok;
  }
  if (zone == k_ez_zone_zoom) {
    const uint8_t next =
      zoom_scale_cycle(s->page.scale, (uint8_t)k_zoom_scale_min, (uint8_t)k_ez_page_scale_max);
    return zoom_view_set_scale(&s->page, next, x, y, now_ms) == k_ra8_ok;
  }
  return ez_apply_pan(s, zone, now_ms);
}

static ra8_err_t ez_draw_status(const ez_scene_t* s)
{
  RA8_RETURN_ON_ERROR(
    ra8_gfx_rect(0, 0, s->fb_w, (int32_t)k_ez_status_h, (uint32_t)k_ez_col_bar, true),
    s_tag,
    "status bar fill");
  const int32_t top   = ((int32_t)k_ez_status_h - (int32_t)k_ez_ind_block) / 2;
  const int32_t pitch = (int32_t)k_ez_ind_block + (int32_t)k_ez_ind_gap;
  for (int32_t i = 0; i < (int32_t)k_ez_page_scale_max; ++i) {
    const uint32_t colour =
      (i < (int32_t)s->page.scale) ? (uint32_t)k_ez_col_ind : (uint32_t)k_ez_col_dim;
    RA8_RETURN_ON_ERROR(ra8_gfx_rect(top + (i * pitch),
                                     top,
                                     (int32_t)k_ez_ind_block,
                                     (int32_t)k_ez_ind_block,
                                     colour,
                                     true),
                        s_tag,
                        "zoom indicator block");
  }
  return k_ra8_ok;
}

static ra8_err_t ez_draw_lens_chrome(ra8_ui_rect_t lens)
{
  for (int32_t i = 0; i < (int32_t)k_ez_lens_border; ++i) {
    RA8_RETURN_ON_ERROR(ra8_gfx_rect(lens.x + i,
                                     lens.y + i,
                                     lens.w - (2 * i),
                                     lens.h - (2 * i),
                                     (uint32_t)k_ez_col_lens,
                                     false),
                        s_tag,
                        "lens border");
  }
  return k_ra8_ok;
}
 
ra8_err_t ez_scene_render(ez_scene_t* s)
{
  RA8_CHECK_NULL_PTR(s, s_tag, "scene must not be nullptr");
  RA8_CHECK_NULL_PTR(s->src.read, s_tag, "scene source must not be nullptr");
  RA8_RETURN_ON_ERROR(zoom_view_render(&s->page), s_tag, "page render");
  if (s->lens_on) {
    RA8_RETURN_ON_ERROR(zoom_view_render(&s->lens), s_tag, "lens render");
    RA8_RETURN_ON_ERROR(ez_draw_lens_chrome(ez_lens_rect(s->content)), s_tag, "lens chrome");
  }
  return ez_draw_status(s);
}

static void ez_choose_plan(const ez_scene_t*     s,
                           const zoom_present_t* page_plan,
                           const zoom_present_t* lens_plan,
                           ez_present_t*         out)
{
  if (page_plan->present) {
    out->rect    = s->content;
    out->quality = (page_plan->refresh == k_zoom_refresh_quality);
    out->present = true;
    return;
  }
  if (lens_plan->present && s->lens_on) {
    /* The partial-update case: only the lens box changed, so only the lens box
     * is flushed -- 102400 pixels instead of the content area's 565248. */
    out->rect    = ez_lens_rect(s->content);
    out->quality = (lens_plan->refresh == k_zoom_refresh_quality);
    out->present = true;
    return;
  }
  out->present = false;
}
 
ra8_err_t ez_scene_present(ez_scene_t* s, ez_present_t* out)
{
  RA8_CHECK_NULL_PTR(s, s_tag, "scene must not be nullptr");
  RA8_CHECK_NULL_PTR(out, s_tag, "present out must not be nullptr");
  zoom_present_t page_plan = {};
  zoom_present_t lens_plan = {};
  RA8_RETURN_ON_ERROR(zoom_view_present(&s->page, &page_plan), s_tag, "page present");
  RA8_RETURN_ON_ERROR(zoom_view_present(&s->lens, &lens_plan), s_tag, "lens present");
  ez_choose_plan(s, &page_plan, &lens_plan, out);
  return k_ra8_ok;
}
 
bool ez_scene_tick(ez_scene_t* s, uint32_t now_ms)
{
  if (s == nullptr) {
    return false;
  }
  const bool page_due = zoom_view_tick(&s->page, now_ms);
  const bool lens_due = zoom_view_tick(&s->lens, now_ms);
  if (page_due) {
    return true;
  }
  if (lens_due) {
    return s->lens_on;
  }
  return false;
}
 
ra8_err_t ez_scene_prefetch(ez_scene_t* s, zoom_pan_t dir, uint16_t* out_warmed)
{
  RA8_CHECK_NULL_PTR(s, s_tag, "scene must not be nullptr");
  RA8_CHECK_NULL_PTR(s->tiles.cache, s_tag, "scene tile source must be bound");
  return zoom_tiles_prefetch(&s->tiles, &s->page, dir, (uint16_t)k_ez_prefetch_max, out_warmed);
}
 
uint32_t ez_fnv1a(const void* buf, uint32_t len)
{
  uint32_t hash = (uint32_t)k_ez_fnv_offset;
  if (buf == nullptr) {
    return hash;
  }
  const uint8_t* bytes = (const uint8_t*)buf;
  for (uint32_t i = 0U; i < len; ++i) {
    hash ^= (uint32_t)bytes[i];
    hash *= (uint32_t)k_ez_fnv_prime;
  }
  return hash;
}

static ra8_err_t ez_render_and_hash(ez_scene_t* s, uint32_t* out_hash)
{
  RA8_RETURN_ON_ERROR(ez_scene_render(s), s_tag, "selftest render");
  ez_present_t plan = {};
  RA8_RETURN_ON_ERROR(ez_scene_present(s, &plan), s_tag, "selftest present");
  *out_hash = ez_fnv1a(s->fb, s->fb_bytes);
  return k_ra8_ok;
}

static ra8_err_t ez_selftest_pan(ez_scene_t* s, ez_selftest_t* out)
{
  RA8_RETURN_ON_ERROR(zoom_view_pan_dir(&s->page, k_zoom_pan_right, (uint32_t)k_ez_st_t0),
                      s_tag,
                      "selftest pan");
  RA8_RETURN_ON_ERROR(ez_scene_prefetch(s, k_zoom_pan_right, &out->warmed),
                      s_tag,
                      "selftest prefetch");
  return ez_render_and_hash(s, &out->crc_pan);
}

static ra8_err_t ez_selftest_zoom(ez_scene_t* s, ez_selftest_t* out)
{
  RA8_RETURN_ON_ERROR(zoom_view_set_scale(&s->page,
                                          (uint8_t)k_ez_st_scale,
                                          (int32_t)k_ez_st_focus_x,
                                          (int32_t)k_ez_st_focus_y,
                                          (uint32_t)k_ez_st_t0),
                      s_tag,
                      "selftest zoom");
  return ez_render_and_hash(s, &out->crc_2x);
}

static ra8_err_t ez_selftest_lens(ez_scene_t* s, ez_selftest_t* out)
{
  s->lens_on = true;
  RA8_RETURN_ON_ERROR(zoom_view_invalidate(&s->lens, (uint32_t)k_ez_st_t0),
                      s_tag,
                      "selftest lens dirty");
  RA8_RETURN_ON_ERROR(zoom_view_invalidate(&s->page, (uint32_t)k_ez_st_t0),
                      s_tag,
                      "selftest page dirty");
  return ez_render_and_hash(s, &out->crc_lens);
}

static ra8_err_t ez_selftest_stages(ez_scene_t* s, ez_selftest_t* out)
{
  RA8_RETURN_ON_ERROR(ez_render_and_hash(s, &out->crc_1x), s_tag, "selftest 1:1");
  RA8_RETURN_ON_ERROR(ez_selftest_pan(s, out), s_tag, "selftest pan stage");
  RA8_RETURN_ON_ERROR(ez_selftest_zoom(s, out), s_tag, "selftest zoom stage");
  return ez_selftest_lens(s, out);
}
 
ra8_err_t ez_scene_selftest(ez_scene_t* s, ez_selftest_t* out)
{
  RA8_CHECK_NULL_PTR(s, s_tag, "scene must not be nullptr");
  RA8_CHECK_NULL_PTR(out, s_tag, "selftest out must not be nullptr");
 
  RA8_RETURN_ON_ERROR(ez_selftest_stages(s, out), s_tag, "selftest stages");
  return ra8_tile_cache_stats(&s->cache, &out->hits, &out->misses, &out->evictions);
}