ra8_tile_cache.h

Go to the documentation of this file.

 
#pragma once
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include <stdint.h>
 
#include "ra8_err.h"
#include "ra8_keycache.h"

typedef struct {
  uint32_t image_id; 
  uint16_t tile_x;   
  uint16_t tile_y;   
  uint16_t zoom;     
  uint16_t reserved; 
} ra8_tile_key_t;
 
/* The key is compared/hashed byte-wise over sizeof(ra8_tile_key_t); guard the
 * padding-free layout at compile time so an accidental field change cannot
 * introduce indeterminate padding bytes into the comparison. */
static_assert(sizeof(ra8_tile_key_t) == sizeof(uint32_t) + sizeof(uint16_t) + sizeof(uint16_t) +
                                          sizeof(uint16_t) + sizeof(uint16_t),
              "ra8_tile_key_t must be padding-free for byte-wise key comparison");

typedef struct {
  uint16_t w; 
  uint16_t h; 
} ra8_tile_dims_t;

typedef struct {
  const uint8_t* pixels; 
  uint16_t       width;  
  uint16_t       height; 
} ra8_tile_t;

typedef ra8_err_t (*ra8_tile_decode_fn)(void*                 ctx,
                                        const ra8_tile_key_t* key,
                                        uint8_t*              cell,
                                        uint32_t              cell_bytes,
                                        uint16_t*             out_w,
                                        uint16_t*             out_h);

typedef struct {
  uint8_t*             cell_mem;     
  uint32_t             cell_bytes;   
  uint32_t             cell_count;   
  ra8_keycache_cell_t* meta;         
  ra8_tile_key_t*      keys;         
  ra8_tile_dims_t*     dims;         
  int32_t*             buckets;      
  uint32_t             bucket_count; 
  ra8_tile_decode_fn   decode;       
  void*                decode_ctx;   
} ra8_tile_cache_cfg_t;

typedef struct {
  ra8_keycache_t     kc;         
  ra8_tile_decode_fn decode;     
  void*              decode_ctx; 
} ra8_tile_cache_t;

typedef enum : uint8_t {
  k_ra8_tile_pan_none  = 0U, 
  k_ra8_tile_pan_left  = 1U, 
  k_ra8_tile_pan_right = 2U, 
  k_ra8_tile_pan_up    = 3U, 
  k_ra8_tile_pan_down  = 4U, 
} ra8_tile_pan_dir_t;

typedef struct {
  uint16_t tx0; 
  uint16_t ty0; 
  uint16_t tx1; 
  uint16_t ty1; 
} ra8_tile_rect_t;

typedef struct {
  uint32_t           image_id;  
  ra8_tile_rect_t    view;      
  uint16_t           tile_cols; 
  uint16_t           tile_rows; 
  uint16_t           zoom;      
  uint16_t           max_tiles; 
  ra8_tile_pan_dir_t dir;       
} ra8_tile_prefetch_req_t;

[[nodiscard]] 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);

[[nodiscard]] ra8_err_t ra8_tile_cache_init(ra8_tile_cache_t* tc, const ra8_tile_cache_cfg_t* cfg);

[[nodiscard]] ra8_err_t
ra8_tile_cache_get(ra8_tile_cache_t* tc, const ra8_tile_key_t* key, ra8_tile_t* out_tile);

[[nodiscard]] ra8_err_t ra8_tile_cache_put(ra8_tile_cache_t* tc, const uint8_t* pixels);

[[nodiscard]] uint32_t ra8_tile_cache_capacity(const ra8_tile_cache_t* tc);

[[nodiscard]] ra8_err_t ra8_tile_cache_prefetch(ra8_tile_cache_t* tc, const ra8_tile_key_t* key);

[[nodiscard]] ra8_err_t ra8_tile_cache_prefetch_pan(ra8_tile_cache_t*              tc,
                                                    const ra8_tile_prefetch_req_t* req,
                                                    uint16_t*                      out_warmed);

[[nodiscard]] 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);
 
#ifdef __cplusplus
}
#endif