zoom_tiles.c

Go to the documentation of this file.

 
#ifdef __has_include
#if __has_include("ra8_tile_cache.h")
#define ZOOM_HAVE_TILES
#endif
#endif
 
#ifdef ZOOM_HAVE_TILES
 
#include "zoom_tiles.h"
 
#include <stdint.h>
#include <string.h>
 
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_tile_cache.h"
#include "ra8_ui.h"
#include "zoom.h"

static const char* const s_tag = "zoom_tiles";
 
/* zoom_tiles_prefetch forwards a zoom_pan_t straight into the cache's
 * ra8_tile_pan_dir_t rather than switching over it. That is only sound while the
 * two enumerations agree value for value, so the agreement is pinned here rather
 * than asserted in prose -- a renumbering of either enum fails the build instead
 * of quietly warming the wrong edge. */
static_assert((uint8_t)k_zoom_pan_none == (uint8_t)k_ra8_tile_pan_none,
              "zoom_pan_t and ra8_tile_pan_dir_t must agree: none");
static_assert((uint8_t)k_zoom_pan_left == (uint8_t)k_ra8_tile_pan_left,
              "zoom_pan_t and ra8_tile_pan_dir_t must agree: left");
static_assert((uint8_t)k_zoom_pan_right == (uint8_t)k_ra8_tile_pan_right,
              "zoom_pan_t and ra8_tile_pan_dir_t must agree: right");
static_assert((uint8_t)k_zoom_pan_up == (uint8_t)k_ra8_tile_pan_up,
              "zoom_pan_t and ra8_tile_pan_dir_t must agree: up");
static_assert((uint8_t)k_zoom_pan_down == (uint8_t)k_ra8_tile_pan_down,
              "zoom_pan_t and ra8_tile_pan_dir_t must agree: down");

typedef enum : uint16_t {
  k_zoom_tiles_native_level = 0U, 
} zoom_tiles_key_t;

typedef struct {
  uint32_t x; 
  uint32_t y; 
  uint32_t w; 
  uint32_t h; 
} zoom_tile_span_t;

RA8_INTERNAL
static void internal_tile_copy(const ra8_tile_t*       tile,
                               uint32_t                org_x,
                               uint32_t                org_y,
                               const zoom_tile_span_t* span,
                               uint8_t*                out,
                               uint32_t                stride)
{
  const uint32_t x0     = (span->x > org_x) ? span->x : org_x;
  const uint32_t y0     = (span->y > org_y) ? span->y : org_y;
  const uint32_t tx_end = org_x + (uint32_t)tile->width;
  const uint32_t ty_end = org_y + (uint32_t)tile->height;
  const uint32_t x1     = ((span->x + span->w) < tx_end) ? (span->x + span->w) : tx_end;
  const uint32_t y1     = ((span->y + span->h) < ty_end) ? (span->y + span->h) : ty_end;
  for (uint32_t sy = y0; sy < y1; ++sy) {
    const uint8_t* srow = &tile->pixels[((sy - org_y) * (uint32_t)tile->width) + (x0 - org_x)];
    uint8_t*       drow = &out[((sy - span->y) * stride) + (x0 - span->x)];
    (void)memcpy(drow, srow, (size_t)(x1 - x0));
  }
}

RA8_INTERNAL
static ra8_err_t internal_tile_fetch(zoom_tile_src_t*        ts,
                                     uint16_t                tx,
                                     uint16_t                ty,
                                     const zoom_tile_span_t* span,
                                     uint8_t*                out,
                                     uint32_t                stride)
{
  const ra8_tile_key_t key = {
    .image_id = ts->image_id,
    .tile_x   = tx,
    .tile_y   = ty,
    .zoom     = (uint16_t)k_zoom_tiles_native_level,
    .reserved = 0U,
  };
  ra8_tile_t tile = {};
  RA8_RETURN_ON_ERROR(ra8_tile_cache_get(ts->cache, &key, &tile), s_tag, "tile fetch");
 
  const uint32_t org_x = (uint32_t)tx * (uint32_t)ts->tile_w;
  const uint32_t org_y = (uint32_t)ty * (uint32_t)ts->tile_h;
  const uint32_t exp_w =
    ((org_x + (uint32_t)ts->tile_w) > ts->width) ? (ts->width - org_x) : (uint32_t)ts->tile_w;
  const uint32_t exp_h =
    ((org_y + (uint32_t)ts->tile_h) > ts->height) ? (ts->height - org_y) : (uint32_t)ts->tile_h;
  /* Decision: a tile that did not decode to the declared gray8 geometry is a
   * format mismatch, not a picture (2 conditions). */
  if (((uint32_t)tile.width != exp_w) || ((uint32_t)tile.height != exp_h)) {
    (void)ra8_tile_cache_put(ts->cache, tile.pixels);
    ra8_log_error(s_tag, "tile decoded to an unexpected extent (wrong bpp or geometry)");
    return k_ra8_err_invalid_size;
  }
  internal_tile_copy(&tile, org_x, org_y, span, out, stride);
  return ra8_tile_cache_put(ts->cache, tile.pixels);
}
 
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)
{
  RA8_CHECK_NULL_PTR(ts, s_tag, "binding must not be nullptr");
  RA8_CHECK_NULL_PTR(cache, s_tag, "tile cache must not be nullptr");
  /* Decision: every extent and tile edge must be non-zero (4 conditions). */
  if ((width == 0U) || (height == 0U) || (tile_w == 0U) || (tile_h == 0U)) {
    ra8_log_error(s_tag, "image extent and tile edges must all be non-zero");
    return k_ra8_err_invalid_arg;
  }
  const uint32_t cols = ((width + (uint32_t)tile_w) - 1U) / (uint32_t)tile_w;
  const uint32_t rows = ((height + (uint32_t)tile_h) - 1U) / (uint32_t)tile_h;
  /* Decision: the derived grid must fit the cache key's 16-bit tile indices. */
  if ((cols > (uint32_t)UINT16_MAX) || (rows > (uint32_t)UINT16_MAX)) {
    ra8_log_error(s_tag, "derived tile grid exceeds the 16-bit tile index range");
    return k_ra8_err_invalid_size;
  }
  ts->cache     = cache;
  ts->image_id  = image_id;
  ts->width     = width;
  ts->height    = height;
  ts->tile_w    = tile_w;
  ts->tile_h    = tile_h;
  ts->tile_cols = (uint16_t)cols;
  ts->tile_rows = (uint16_t)rows;
  return k_ra8_ok;
}
 
ra8_err_t zoom_tile_src_bind(zoom_tile_src_t* ts, zoom_source_t* out)
{
  RA8_CHECK_NULL_PTR(ts, s_tag, "binding must not be nullptr");
  RA8_CHECK_NULL_PTR(out, s_tag, "source out must not be nullptr");
  RA8_CHECK_NULL_PTR(ts->cache, s_tag, "binding was never initialised");
  return zoom_source_init(out, zoom_tile_read, ts, ts->width, ts->height);
}

RA8_INTERNAL
static ra8_err_t internal_walk_tile_row(zoom_tile_src_t*        ts,
                                        uint16_t                ty,
                                        uint16_t                tx0,
                                        uint16_t                tx1,
                                        const zoom_tile_span_t* span,
                                        uint8_t*                out,
                                        uint32_t                stride)
{
  for (uint16_t tx = tx0; tx <= tx1; ++tx) {
    RA8_RETURN_ON_ERROR(internal_tile_fetch(ts, tx, ty, span, out, stride), s_tag, "tile copy");
  }
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_walk_tiles(zoom_tile_src_t*        ts,
                                     const ra8_tile_rect_t*  tiles,
                                     const zoom_tile_span_t* span,
                                     uint8_t*                out,
                                     uint32_t                stride)
{
  for (uint16_t ty = tiles->ty0; ty <= tiles->ty1; ++ty) {
    RA8_RETURN_ON_ERROR(internal_walk_tile_row(ts, ty, tiles->tx0, tiles->tx1, span, out, stride),
                        s_tag,
                        "tile row");
  }
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_read_rect_ok(const zoom_tile_src_t* ts,
                                       uint32_t               x,
                                       uint32_t               y,
                                       uint32_t               w,
                                       uint32_t               h,
                                       uint32_t               out_stride)
{
  /* Decision: an empty rectangle, or one narrower than its own stride, is a
   * caller defect rather than something to clamp (3 conditions). */
  if ((w == 0U) || (h == 0U) || (out_stride < w)) {
    ra8_log_error(s_tag, "read rect must be non-empty and fit its stride");
    return k_ra8_err_invalid_arg;
  }
  /* Decision: the rectangle must lie wholly inside the bound image. */
  if (((x + w) > ts->width) || ((y + h) > ts->height)) {
    ra8_log_error(s_tag, "read rect leaves the bound image");
    return k_ra8_err_out_of_range;
  }
  return k_ra8_ok;
}
 
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)
{
  RA8_CHECK_NULL_PTR(ctx, s_tag, "read ctx must not be nullptr");
  RA8_CHECK_NULL_PTR(out, s_tag, "read destination must not be nullptr");
  zoom_tile_src_t* ts = (zoom_tile_src_t*)ctx;
  RA8_CHECK_NULL_PTR(ts->cache, s_tag, "binding was never initialised");
  RA8_RETURN_ON_ERROR(internal_read_rect_ok(ts, x, y, w, h, out_stride), s_tag, "read rect check");
 
  ra8_tile_rect_t tiles = {};
  RA8_RETURN_ON_ERROR(ra8_tile_rect_of_pixels(x,
                                              y,
                                              w,
                                              h,
                                              ts->tile_w,
                                              ts->tile_h,
                                              ts->tile_cols,
                                              ts->tile_rows,
                                              &tiles),
                      s_tag,
                      "pixel rect to tile rect");
 
  const zoom_tile_span_t span = {.x = x, .y = y, .w = w, .h = h};
  return internal_walk_tiles(ts, &tiles, &span, out, out_stride);
}
 
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)
{
  RA8_CHECK_NULL_PTR(ts, s_tag, "binding must not be nullptr");
  RA8_CHECK_NULL_PTR(v, s_tag, "view must not be nullptr");
  RA8_CHECK_NULL_PTR(ts->cache, s_tag, "binding was never initialised");
 
  ra8_ui_rect_t win = {};
  RA8_RETURN_ON_ERROR(zoom_view_window(v, &win), s_tag, "visible window");
 
  ra8_tile_rect_t tiles = {};
  RA8_RETURN_ON_ERROR(ra8_tile_rect_of_pixels((uint32_t)win.x,
                                              (uint32_t)win.y,
                                              (uint32_t)win.w,
                                              (uint32_t)win.h,
                                              ts->tile_w,
                                              ts->tile_h,
                                              ts->tile_cols,
                                              ts->tile_rows,
                                              &tiles),
                      s_tag,
                      "visible window to tile rect");
 
  const ra8_tile_prefetch_req_t req = {
    .image_id  = ts->image_id,
    .view      = tiles,
    .tile_cols = ts->tile_cols,
    .tile_rows = ts->tile_rows,
    .zoom      = (uint16_t)k_zoom_tiles_native_level,
    .max_tiles = max_tiles,
    .dir       = (ra8_tile_pan_dir_t)dir,
  };
  return ra8_tile_cache_prefetch_pan(ts->cache, &req, out_warmed);
}
 
#endif /* ZOOM_HAVE_TILES */