ra8_tile_cache.c

Go to the documentation of this file.

 
#include "ra8_tile_cache.h"
 
#include <stddef.h>
#include <stdint.h>
#include <string.h>
 
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_keycache.h"

static const char* const s_tag = "ra8_tile_cache";

RA8_INTERNAL
RA8_INTERNAL static ra8_err_t
internal_tile_decode(void* ctx, const void* key, uint8_t* cell, uint32_t cell_bytes, void* user)
{
  const ra8_tile_cache_t* tc   = (const ra8_tile_cache_t*)ctx;
  const ra8_tile_key_t*   tk   = (const ra8_tile_key_t*)key;
  ra8_tile_dims_t*        dims = (ra8_tile_dims_t*)user;
  uint16_t                w    = 0;
  uint16_t                h    = 0;
  const ra8_err_t         rerr = tc->decode(tc->decode_ctx, tk, cell, cell_bytes, &w, &h);
  if (rerr != k_ra8_ok) {
    return rerr;
  }
  dims->w = w;
  dims->h = h;
  return k_ra8_ok;
}

RA8_INTERNAL
RA8_INTERNAL static uint16_t internal_clamp_tile(uint32_t index, uint16_t count)
{
  const uint32_t last = (uint32_t)count - 1U;
  return (uint16_t)((index > last) ? last : index);
}
 
ra8_err_t ra8_tile_rect_of_pixels(uint32_t         px,
                                  uint32_t         py,
                                  uint32_t         pw,
                                  uint32_t         ph,
                                  uint16_t         tile_w,
                                  uint16_t         tile_h,
                                  uint16_t         tile_cols,
                                  uint16_t         tile_rows,
                                  ra8_tile_rect_t* out)
{
  RA8_CHECK_NULL_PTR(out, s_tag, "out rect must not be nullptr");
  /* Decision: an empty pixel rectangle names no tiles (2 conditions). */
  if ((pw == 0U) || (ph == 0U)) {
    ra8_log_error(s_tag, "pixel rect must have a positive extent");
    return k_ra8_err_invalid_arg;
  }
  /* Decision: the tile geometry must describe a real grid (4 conditions). */
  if ((tile_w == 0U) || (tile_h == 0U) || (tile_cols == 0U) || (tile_rows == 0U)) {
    ra8_log_error(s_tag, "tile geometry must be non-zero on every axis");
    return k_ra8_err_invalid_arg;
  }
  out->tx0 = internal_clamp_tile(px / (uint32_t)tile_w, tile_cols);
  out->ty0 = internal_clamp_tile(py / (uint32_t)tile_h, tile_rows);
  out->tx1 = internal_clamp_tile(((px + pw) - 1U) / (uint32_t)tile_w, tile_cols);
  out->ty1 = internal_clamp_tile(((py + ph) - 1U) / (uint32_t)tile_h, tile_rows);
  return k_ra8_ok;
}
 
ra8_err_t ra8_tile_cache_init(ra8_tile_cache_t* tc, const ra8_tile_cache_cfg_t* cfg)
{
  RA8_CHECK_NULL_PTR(tc, s_tag, "tc must not be nullptr");
  RA8_CHECK_NULL_PTR(cfg, s_tag, "cfg must not be nullptr");
  RA8_CHECK_NULL_PTR(cfg->decode, s_tag, "decode must not be nullptr");
  (void)memset(tc, 0, sizeof(*tc));
  tc->decode              = cfg->decode;
  tc->decode_ctx          = cfg->decode_ctx;
  ra8_keycache_cfg_t kcfg = {};
  kcfg.cell_mem           = cfg->cell_mem;
  kcfg.cell_bytes         = cfg->cell_bytes;
  kcfg.cell_count         = cfg->cell_count;
  kcfg.key_mem            = (uint8_t*)cfg->keys;
  kcfg.key_bytes          = (uint32_t)sizeof(ra8_tile_key_t);
  kcfg.user_mem           = (uint8_t*)cfg->dims;
  kcfg.user_bytes         = (uint32_t)sizeof(ra8_tile_dims_t);
  kcfg.meta               = cfg->meta;
  kcfg.buckets            = cfg->buckets;
  kcfg.bucket_count       = cfg->bucket_count;
  kcfg.render             = internal_tile_decode;
  kcfg.render_ctx         = tc;
  return ra8_keycache_init(&tc->kc, &kcfg);
}
 
ra8_err_t ra8_tile_cache_get(ra8_tile_cache_t* tc, const ra8_tile_key_t* key, ra8_tile_t* out_tile)
{
  RA8_CHECK_NULL_PTR(tc, s_tag, "tc must not be nullptr");
  RA8_CHECK_NULL_PTR(key, s_tag, "key must not be nullptr");
  RA8_CHECK_NULL_PTR(out_tile, s_tag, "out_tile must not be nullptr");
  ra8_keycache_view_t v   = {};
  const ra8_err_t     err = ra8_keycache_get(&tc->kc, key, &v);
  if (err != k_ra8_ok) {
    return err;
  }
  const ra8_tile_dims_t* dims = (const ra8_tile_dims_t*)v.user;
  *out_tile                   = (ra8_tile_t){.pixels = v.data, .width = dims->w, .height = dims->h};
  return k_ra8_ok;
}
 
ra8_err_t ra8_tile_cache_put(ra8_tile_cache_t* tc, const uint8_t* pixels)
{
  RA8_CHECK_NULL_PTR(tc, s_tag, "tc must not be nullptr");
  RA8_CHECK_NULL_PTR(pixels, s_tag, "pixels must not be nullptr");
  return ra8_keycache_put(&tc->kc, pixels);
}
 
uint32_t ra8_tile_cache_capacity(const ra8_tile_cache_t* tc)
{
  if (tc == nullptr) {
    return 0U;
  }
  if (tc->kc.cfg.cell_mem == nullptr) {
    return 0U; /* never initialised: report no capacity */
  }
  return tc->kc.cfg.cell_count;
}
 
ra8_err_t ra8_tile_cache_prefetch(ra8_tile_cache_t* tc, const ra8_tile_key_t* key)
{
  RA8_CHECK_NULL_PTR(tc, s_tag, "tc must not be nullptr");
  RA8_CHECK_NULL_PTR(key, s_tag, "key must not be nullptr");
  return ra8_keycache_prefetch(&tc->kc, key);
}

typedef struct {
  uint16_t x;      
  uint16_t y;      
  uint16_t step_x; 
  uint16_t step_y; 
  uint16_t count;  
} priv_pan_line_t;

RA8_INTERNAL
RA8_INTERNAL static ra8_err_t internal_validate_req(const ra8_tile_prefetch_req_t* req)
{
  const ra8_tile_rect_t v = req->view;
  if (v.tx0 > v.tx1) {
    return k_ra8_err_invalid_arg;
  }
  if (v.ty0 > v.ty1) {
    return k_ra8_err_invalid_arg;
  }
  if ((uint32_t)v.tx1 >= (uint32_t)req->tile_cols) {
    return k_ra8_err_invalid_arg;
  }
  if ((uint32_t)v.ty1 >= (uint32_t)req->tile_rows) {
    return k_ra8_err_invalid_arg;
  }
  return k_ra8_ok;
}

RA8_INTERNAL
RA8_INTERNAL static bool internal_pan_line(const ra8_tile_prefetch_req_t* req, priv_pan_line_t* out)
{
  const ra8_tile_rect_t v     = req->view;
  const uint16_t        v_run = (uint16_t)((v.ty1 - v.ty0) + 1U);
  const uint16_t        h_run = (uint16_t)((v.tx1 - v.tx0) + 1U);
  switch (req->dir) {
    case k_ra8_tile_pan_right:
      if (((uint32_t)v.tx1 + 1U) >= (uint32_t)req->tile_cols) {
        return false;
      }
      *out = (priv_pan_line_t){.x      = (uint16_t)(v.tx1 + 1U),
                               .y      = v.ty0,
                               .step_x = 0U,
                               .step_y = 1U,
                               .count  = v_run};
      return true;
    case k_ra8_tile_pan_left:
      if (v.tx0 == 0U) {
        return false;
      }
      *out = (priv_pan_line_t){.x      = (uint16_t)(v.tx0 - 1U),
                               .y      = v.ty0,
                               .step_x = 0U,
                               .step_y = 1U,
                               .count  = v_run};
      return true;
    case k_ra8_tile_pan_down:
      if (((uint32_t)v.ty1 + 1U) >= (uint32_t)req->tile_rows) {
        return false;
      }
      *out = (priv_pan_line_t){.x      = v.tx0,
                               .y      = (uint16_t)(v.ty1 + 1U),
                               .step_x = 1U,
                               .step_y = 0U,
                               .count  = h_run};
      return true;
    case k_ra8_tile_pan_up:
      if (v.ty0 == 0U) {
        return false;
      }
      *out = (priv_pan_line_t){.x      = v.tx0,
                               .y      = (uint16_t)(v.ty0 - 1U),
                               .step_x = 1U,
                               .step_y = 0U,
                               .count  = h_run};
      return true;
    case k_ra8_tile_pan_none:
    default:
      return false;
  }
}
 
ra8_err_t ra8_tile_cache_prefetch_pan(ra8_tile_cache_t*              tc,
                                      const ra8_tile_prefetch_req_t* req,
                                      uint16_t*                      out_warmed)
{
  RA8_CHECK_NULL_PTR(tc, s_tag, "tc must not be nullptr");
  RA8_CHECK_NULL_PTR(req, s_tag, "req must not be nullptr");
  if (out_warmed != nullptr) {
    *out_warmed = 0U;
  }
  const ra8_err_t verr = internal_validate_req(req);
  if (verr != k_ra8_ok) {
    return verr;
  }
  priv_pan_line_t line = {};
  if (!internal_pan_line(req, &line)) {
    return k_ra8_ok; /* at an image edge or not panning: nothing to warm */
  }
  const uint16_t cap    = (uint16_t)((line.count < req->max_tiles) ? line.count : req->max_tiles);
  uint16_t       warmed = 0U;
  for (uint16_t i = 0U; i < cap; ++i) {
    const ra8_tile_key_t key = {.image_id = req->image_id,
                                .tile_x   = (uint16_t)(line.x + (uint16_t)(line.step_x * i)),
                                .tile_y   = (uint16_t)(line.y + (uint16_t)(line.step_y * i)),
                                .zoom     = req->zoom};
    if (ra8_tile_cache_prefetch(tc, &key) != k_ra8_ok) {
      break; /* best-effort: a full/failed cache stops the sweep, not the pan */
    }
    warmed++;
  }
  if (out_warmed != nullptr) {
    *out_warmed = warmed;
  }
  return k_ra8_ok;
}
 
ra8_err_t ra8_tile_cache_stats(const ra8_tile_cache_t* tc,
                               uint32_t*               out_hits,
                               uint32_t*               out_misses,
                               uint32_t*               out_evictions)
{
  RA8_CHECK_NULL_PTR(tc, s_tag, "tc must not be nullptr");
  if (tc->kc.cfg.cell_mem == nullptr) {
    return k_ra8_err_invalid_state;
  }
  return ra8_keycache_stats(&tc->kc, out_hits, out_misses, out_evictions);
}