longstrip.c

Go to the documentation of this file.

 
#include "longstrip.h"
 
#include <stdint.h>
 
#include "jof.h"
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_tile_cache.h"

static const char* const s_tag = "longstrip";

typedef enum : uint8_t {
  k_wt_fling_num = 7U, 
  k_wt_fling_den = 8U, 
  k_wt_tile_x    = 0U, 
  k_wt_zoom      = 0U, 
} wt_consts_t;
 
ra8_err_t longstrip_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_CHECK_NULL_PTR(ctx, s_tag, "decode ctx must not be nullptr");
  RA8_CHECK_NULL_PTR(key, s_tag, "key must not be nullptr");
  RA8_CHECK_NULL_PTR(cell, s_tag, "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");
  longstrip_decode_ctx_t* dc = (longstrip_decode_ctx_t*)ctx;
  return jof_read_tile(dc->pread,
                       dc->pread_ctx,
                       &dc->info,
                       key->tile_x,
                       key->tile_y,
                       dc->scratch,
                       dc->scratch_cap,
                       cell,
                       cell_bytes,
                       out_w,
                       out_h);
}

RA8_INTERNAL
static void internal_bind(longstrip_t* wt, const longstrip_cfg_t* cfg, const jof_info_t* info)
{
  wt->info       = *info;
  wt->canvas_w   = info->width;
  wt->canvas_h   = info->height;
  wt->band_h     = info->tile_h;
  wt->band_count = info->tile_rows;
  wt->viewport_w = cfg->viewport_w;
  wt->viewport_h = cfg->viewport_h;
  wt->scroll_y   = 0;
  wt->max_scroll = (info->height > cfg->viewport_h)
                     ? (int32_t)((uint32_t)info->height - (uint32_t)cfg->viewport_h)
                     : 0;
  wt->velocity   = 0;
  wt->cache      = cfg->cache;
  wt->image_id   = cfg->image_id;
  wt->blit       = cfg->blit;
  wt->blit_ctx   = cfg->blit_ctx;
}

RA8_INTERNAL
static ra8_err_t internal_check_ptrs(const longstrip_t* wt, const longstrip_cfg_t* cfg)
{
  RA8_CHECK_NULL_PTR(wt, s_tag, "wt must not be nullptr");
  RA8_CHECK_NULL_PTR(cfg, s_tag, "cfg must not be nullptr");
  RA8_CHECK_NULL_PTR(cfg->pread, s_tag, "cfg->pread must not be nullptr");
  RA8_CHECK_NULL_PTR(cfg->cache, s_tag, "cfg->cache must not be nullptr");
  RA8_CHECK_NULL_PTR(cfg->blit, s_tag, "cfg->blit must not be nullptr");
  return k_ra8_ok;
}
 
ra8_err_t longstrip_open(longstrip_t* wt, const longstrip_cfg_t* cfg)
{
  const ra8_err_t ptr_err = internal_check_ptrs(wt, cfg);
  if (ptr_err != k_ra8_ok) {
    return ptr_err;
  }
  /* Decision: reject a zero-area viewport (2 conditions -- MC/DC in tests). */
  if ((cfg->viewport_w == 0U) || (cfg->viewport_h == 0U)) {
    return k_ra8_err_invalid_arg;
  }
  jof_info_t      info = {};
  const ra8_err_t err  = jof_parse(cfg->pread, cfg->pread_ctx, cfg->atlas_size, &info);
  if (err != k_ra8_ok) {
    return err;
  }
  /* A longstrip strip is one full-width band column; anything else is not a
   * scrollable strip. `jof_parse` derives tile_cols as
   * ceil(width / tile_w), so `tile_w == width` already implies tile_cols == 1
   * -- the full-width test alone is necessary and sufficient. */
  if (info.tile_w != info.width) {
    return k_ra8_err_not_supported;
  }
  internal_bind(wt, cfg, &info);
  return k_ra8_ok;
}
 
ra8_err_t longstrip_set_viewport(longstrip_t* wt, uint16_t viewport_w, uint16_t viewport_h)
{
  RA8_CHECK_NULL_PTR(wt, s_tag, "wt must not be nullptr");
  /* Decision: reject a zero-area viewport (2 conditions -- MC/DC in tests). */
  if ((viewport_w == 0U) || (viewport_h == 0U)) {
    return k_ra8_err_invalid_arg;
  }
  wt->viewport_w = viewport_w;
  wt->viewport_h = viewport_h;
  wt->max_scroll =
    (wt->canvas_h > (uint32_t)viewport_h) ? (int32_t)(wt->canvas_h - (uint32_t)viewport_h) : 0;
  wt->scroll_y = longstrip_clamp_scroll(wt, wt->scroll_y);
  return k_ra8_ok;
}
 
int32_t longstrip_clamp_scroll(const longstrip_t* wt, int32_t y)
{
  if (wt == nullptr) {
    return 0;
  }
  const int32_t max = wt->max_scroll;
  if (y < 0) {
    y = 0;
  } else if (y > max) {
    y = max;
  }
  return y;
}
 
ra8_err_t longstrip_band_at_y(const longstrip_t* wt, uint32_t y, uint16_t* out_band)
{
  RA8_CHECK_NULL_PTR(wt, s_tag, "wt must not be nullptr");
  RA8_CHECK_NULL_PTR(out_band, s_tag, "out_band must not be nullptr");
  if (y >= wt->canvas_h) {
    return k_ra8_err_out_of_range;
  }
  *out_band = (uint16_t)(y / (uint32_t)wt->band_h);
  return k_ra8_ok;
}
 
ra8_err_t longstrip_visible_bands(const longstrip_t* wt,
                                  int32_t            scroll_y,
                                  uint16_t*          out_first,
                                  uint16_t*          out_last)
{
  RA8_CHECK_NULL_PTR(wt, s_tag, "wt must not be nullptr");
  RA8_CHECK_NULL_PTR(out_first, s_tag, "out_first must not be nullptr");
  RA8_CHECK_NULL_PTR(out_last, s_tag, "out_last must not be nullptr");
  const int32_t  top    = longstrip_clamp_scroll(wt, scroll_y);
  const uint32_t bh     = (uint32_t)wt->band_h;
  const uint32_t first  = (uint32_t)top / bh;
  uint32_t       bottom = (uint32_t)top + (uint32_t)wt->viewport_h - 1U;
  if (bottom >= wt->canvas_h) {
    bottom = wt->canvas_h - 1U;
  }
  uint32_t last = bottom / bh;
  if (last >= (uint32_t)wt->band_count) {
    last = (uint32_t)wt->band_count - 1U;
  }
  *out_first = (uint16_t)first;
  *out_last  = (uint16_t)last;
  return k_ra8_ok;
}

RA8_INTERNAL
static int32_t internal_sat_add(int32_t a, int32_t b)
{
  const int64_t sum = (int64_t)a + (int64_t)b;
  if (sum > (int64_t)INT32_MAX) {
    return INT32_MAX;
  }
  if (sum < (int64_t)INT32_MIN) {
    return INT32_MIN;
  }
  return (int32_t)sum;
}
 
ra8_err_t longstrip_scroll_by(longstrip_t* wt, int32_t delta)
{
  RA8_CHECK_NULL_PTR(wt, s_tag, "wt must not be nullptr");
  wt->scroll_y = longstrip_clamp_scroll(wt, internal_sat_add(wt->scroll_y, delta));
  /* Decision: pinned at either end stops a running fling (2 conditions). */
  if ((wt->scroll_y == 0) || (wt->scroll_y == wt->max_scroll)) {
    wt->velocity = 0;
  }
  return k_ra8_ok;
}
 
ra8_err_t longstrip_fling(longstrip_t* wt, int32_t v0)
{
  RA8_CHECK_NULL_PTR(wt, s_tag, "wt must not be nullptr");
  wt->velocity = v0;
  return k_ra8_ok;
}

RA8_INTERNAL
static int32_t internal_apply_friction(int32_t v)
{
  return (int32_t)((v * (int32_t)k_wt_fling_num) / (int32_t)k_wt_fling_den);
}

RA8_INTERNAL
static bool internal_at_top(const longstrip_t* wt)
{
  return wt->scroll_y <= 0;
}

RA8_INTERNAL
static bool internal_at_bottom(const longstrip_t* wt)
{
  return wt->scroll_y >= wt->max_scroll;
}

RA8_INTERNAL
static bool internal_fling_should_stop(const longstrip_t* wt)
{
  return (wt->velocity < 0) ? internal_at_top(wt) : internal_at_bottom(wt);
}
 
bool longstrip_tick(longstrip_t* wt)
{
  if (wt == nullptr) {
    return false;
  }
  if (wt->velocity == 0) {
    return false;
  }
  wt->scroll_y = longstrip_clamp_scroll(wt, internal_sat_add(wt->scroll_y, wt->velocity));
  wt->velocity = internal_apply_friction(wt->velocity);
  /* Decision: come to rest when the speed hits zero or a boundary is reached. */
  if ((wt->velocity == 0) || internal_fling_should_stop(wt)) {
    wt->velocity = 0;
    return false;
  }
  return true;
}

RA8_INTERNAL
static void internal_warm_band(longstrip_t* wt, uint16_t band)
{
  ra8_tile_key_t key = {};
  key.image_id       = wt->image_id;
  key.tile_x         = (uint16_t)k_wt_tile_x;
  key.tile_y         = band;
  key.zoom           = (uint16_t)k_wt_zoom;
  ra8_tile_t tile    = {};
  if (ra8_tile_cache_get(wt->cache, &key, &tile) == k_ra8_ok) {
    (void)ra8_tile_cache_put(wt->cache, tile.pixels);
  }
}
 
ra8_err_t longstrip_prefetch(longstrip_t* wt, uint16_t depth)
{
  RA8_CHECK_NULL_PTR(wt, s_tag, "wt must not be nullptr");
  uint16_t        first = 0;
  uint16_t        last  = 0;
  const ra8_err_t err   = longstrip_visible_bands(wt, wt->scroll_y, &first, &last);
  if (err != k_ra8_ok) {
    return err;
  }
  if (depth > (uint16_t)k_longstrip_max_prefetch) {
    depth = (uint16_t)k_longstrip_max_prefetch;
  }
  const uint16_t visible_span = (uint16_t)((last - first) + 1U);
  /* Decision: nothing to prefetch with zero depth or a strip that fits (2). */
  if ((depth == 0U) || (wt->band_count <= visible_span)) {
    return k_ra8_ok;
  }
  const bool downward = (wt->velocity >= 0);
  for (uint16_t i = 1U; i <= depth; i++) { /* bounded by k_longstrip_max_prefetch */
    uint16_t target = 0;
    if (downward) {
      const uint32_t t = (uint32_t)last + (uint32_t)i;
      if (t >= (uint32_t)wt->band_count) {
        break;
      }
      target = (uint16_t)t;
    } else {
      if (first < i) {
        break;
      }
      target = (uint16_t)(first - i);
    }
    internal_warm_band(wt, target);
  }
  return k_ra8_ok;
}

RA8_INTERNAL
static void internal_accumulate_coverage(const longstrip_t*        wt,
                                         int32_t                   dst_y,
                                         uint16_t                  band_h,
                                         longstrip_render_stats_t* stats)
{
  int32_t       top = (dst_y > 0) ? dst_y : 0;
  int32_t       bot = dst_y + (int32_t)band_h;
  const int32_t vh  = (int32_t)wt->viewport_h;
  if (bot > vh) {
    bot = vh;
  }
  if (bot > top) {
    stats->covered_rows += (uint32_t)(bot - top);
  }
}

RA8_INTERNAL
static ra8_err_t
internal_draw_band(longstrip_t* wt, uint16_t band, int32_t dst_x, longstrip_render_stats_t* stats)
{
  ra8_tile_key_t key = {};
  key.image_id       = wt->image_id;
  key.tile_x         = (uint16_t)k_wt_tile_x;
  key.tile_y         = band;
  key.zoom           = (uint16_t)k_wt_zoom;
  ra8_tile_t tile    = {};
  if (ra8_tile_cache_get(wt->cache, &key, &tile) != k_ra8_ok) {
    stats->skipped++; /* record a gap; the frame still completes */
    return k_ra8_ok;
  }
  const int32_t   dst_y = (int32_t)((uint32_t)band * (uint32_t)wt->band_h) - wt->scroll_y;
  const ra8_err_t berr =
    wt->blit(wt->blit_ctx, tile.pixels, tile.width, tile.height, wt->info.bpp, dst_x, dst_y);
  if (berr == k_ra8_ok) {
    stats->bands_drawn++;
    internal_accumulate_coverage(wt, dst_y, tile.height, stats);
  } else {
    stats->skipped++;
  }
  const ra8_err_t perr = ra8_tile_cache_put(wt->cache, tile.pixels);
  return (berr != k_ra8_ok) ? berr : perr;
}
 
ra8_err_t longstrip_render(longstrip_t* wt, longstrip_render_stats_t* stats)
{
  RA8_CHECK_NULL_PTR(wt, s_tag, "wt must not be nullptr");
  longstrip_render_stats_t local = {};
  wt->scroll_y                   = longstrip_clamp_scroll(wt, wt->scroll_y);
  uint16_t  first                = 0;
  uint16_t  last                 = 0;
  ra8_err_t err                  = longstrip_visible_bands(wt, wt->scroll_y, &first, &last);
  if (err != k_ra8_ok) {
    return err;
  }
  const int32_t dst_x = ((int32_t)wt->viewport_w - (int32_t)wt->canvas_w) / 2;
  for (uint32_t b = (uint32_t)first; b <= (uint32_t)last; b++) { /* bounded by band_count */
    err = internal_draw_band(wt, (uint16_t)b, dst_x, &local);
    if (err != k_ra8_ok) {
      break;
    }
  }
  if (stats != nullptr) {
    *stats = local;
  }
  return err;
}