zoom.c

Go to the documentation of this file.

 
#include "zoom.h"
 
#include <stdint.h>
 
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_ui.h"
#include "zoom_internal.h"

static const char* const s_tag = "zoom";

typedef enum : uint8_t {
  k_zoom_overlap_div = 8U, 
  k_zoom_scale_dbl   = 2U, 
} zoom_step_t;
 
RA8_PRIV void
priv_zoom_axis(int32_t anchor, int32_t extent, int32_t scale, int32_t src_dim, zoom_axis_t* out)
{
  const int32_t plane = src_dim * scale;
  int32_t       d0    = -anchor;
  if (d0 < 0) {
    d0 = 0;
  }
  int32_t d1 = plane - anchor;
  if (d1 > extent) {
    d1 = extent;
  }
  if (d1 < d0) {
    d1 = d0;
  }
  out->d0 = d0;
  out->d1 = d1;
  out->s0 = 0U;
  /* Beyond this point `anchor + d0 >= 0` by construction, so the source-index
   * divisions never touch a negative numerator. */
  if (d1 <= d0) {
    out->count = 0U;
    return;
  }
  const int32_t s0 = (anchor + d0) / scale;
  const int32_t s1 = (anchor + d1 - 1) / scale;
  /* `span` is a named object rather than the composite `(s1 - s0) + 1` inline,
   * so the widening cast below converts a simple expression: casting the
   * composite would change essential type mid-expression (MISRA 10.8). It is
   * positive by construction -- s1 >= s0 whenever d1 > d0. */
  const int32_t span = (s1 - s0) + 1;
  out->s0            = (uint32_t)s0;
  out->count         = (uint32_t)span;
}

RA8_INTERNAL
static bool internal_dim_ok(uint32_t dim)
{
  return (dim != 0U) && (dim <= (uint32_t)k_zoom_dim_max);
}

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_INTERNAL
static int32_t internal_clamp_anchor(int32_t anchor, int32_t plane, int32_t extent)
{
  if (plane <= extent) {
    /* Image smaller than the viewport at this zoom: centre it, letting the
     * anchor go negative. The render reads that as a letterbox. */
    return -((extent - plane) / 2);
  }
  if (anchor < 0) {
    return 0;
  }
  if (anchor > (plane - extent)) {
    return plane - extent;
  }
  return anchor;
}

RA8_INTERNAL
static void internal_reclamp(zoom_view_t* v)
{
  const int32_t scale = (int32_t)v->scale;
  v->anchor_x         = internal_clamp_anchor(v->anchor_x, (int32_t)v->src.width * scale, v->dst.w);
  v->anchor_y = internal_clamp_anchor(v->anchor_y, (int32_t)v->src.height * scale, v->dst.h);
}

RA8_INTERNAL
static void internal_touch(zoom_view_t* v, uint32_t now_ms)
{
  const bool responsive = (v->policy == k_zoom_policy_responsive);
  v->last_input_ms      = now_ms;
  v->pending            = true;
  v->pending_kind       = responsive ? k_zoom_refresh_fast : k_zoom_refresh_quality;
  v->settle_armed       = responsive;
}

RA8_INTERNAL
static ra8_err_t internal_cfg_ptrs_ok(const zoom_view_cfg_t* cfg)
{
  RA8_CHECK_NULL_PTR(cfg->src.read, s_tag, "source read seam must not be nullptr");
  RA8_CHECK_NULL_PTR(cfg->scratch.row, s_tag, "scratch.row must not be nullptr");
  RA8_CHECK_NULL_PTR(cfg->scratch.strip, s_tag, "scratch.strip must not be nullptr");
  RA8_CHECK_NULL_PTR(cfg->scratch.packed, s_tag, "scratch.packed must not be nullptr");
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_cfg_extent_ok(const zoom_view_cfg_t* cfg)
{
  if ((cfg->dst.w <= 0) || (cfg->dst.h <= 0)) {
    ra8_log_error(s_tag, "viewport must have positive width and height");
    return k_ra8_err_invalid_arg;
  }
  if (!internal_dim_ok(cfg->src.width) || !internal_dim_ok(cfg->src.height)) {
    ra8_log_error(s_tag, "source extent is zero or exceeds k_zoom_dim_max");
    return k_ra8_err_invalid_arg;
  }
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_cfg_scratch_ok(const zoom_view_cfg_t* cfg, uint16_t* out_strip_rows)
{
  const uint32_t width = (uint32_t)cfg->dst.w;
  if ((cfg->scratch.row_cap < width) || (cfg->scratch.strip_cap < width)) {
    ra8_log_error(s_tag, "scratch row/strip buffer is narrower than the viewport");
    return k_ra8_err_no_mem;
  }
  uint32_t rows = cfg->scratch.strip_cap / width;
  if (rows > (uint32_t)k_zoom_strip_rows_max) {
    rows = (uint32_t)k_zoom_strip_rows_max;
  }
  if (rows > (uint32_t)cfg->dst.h) {
    rows = (uint32_t)cfg->dst.h;
  }
  if (cfg->scratch.packed_cap < (((width * rows) + 1U) / 2U)) {
    ra8_log_error(s_tag, "scratch packed buffer cannot hold one dithered strip");
    return k_ra8_err_no_mem;
  }
  *out_strip_rows = (uint16_t)rows;
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t
internal_cfg_ladder_ok(const zoom_view_cfg_t* cfg, uint8_t* out_scale, uint8_t* out_ceiling)
{
  /* The "0 means default" rewrite happens first and lifts both values to at
   * least k_zoom_scale_min, so a `< min` half in either check below could
   * never be true. Testing it anyway would be a condition that cannot vary --
   * unreachable by construction, and dead weight in an MC/DC argument. Each
   * check is therefore the one bound that can actually fail. */
  const uint8_t ceiling = (cfg->scale_max == 0U) ? (uint8_t)k_zoom_scale_max : cfg->scale_max;
  const uint8_t opening = (cfg->scale == 0U) ? (uint8_t)k_zoom_scale_min : cfg->scale;
  if (ceiling > (uint8_t)k_zoom_scale_max) {
    ra8_log_error(s_tag, "scale_max is outside the engine ladder");
    return k_ra8_err_invalid_arg;
  }
  if (opening > ceiling) {
    ra8_log_error(s_tag, "opening scale is outside the configured ladder");
    return k_ra8_err_invalid_arg;
  }
  *out_scale   = opening;
  *out_ceiling = ceiling;
  return k_ra8_ok;
}
 
ra8_err_t
zoom_source_init(zoom_source_t* out, zoom_read_fn read, void* ctx, uint32_t width, uint32_t height)
{
  RA8_CHECK_NULL_PTR(out, s_tag, "source out must not be nullptr");
  RA8_CHECK_NULL_PTR(read, s_tag, "source read seam must not be nullptr");
  if (!internal_dim_ok(width) || !internal_dim_ok(height)) {
    ra8_log_error(s_tag, "source extent is zero or exceeds k_zoom_dim_max");
    return k_ra8_err_invalid_arg;
  }
  out->read   = read;
  out->ctx    = ctx;
  out->width  = width;
  out->height = height;
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_cfg_ok(const zoom_view_cfg_t* cfg,
                                 uint16_t*              out_strip_rows,
                                 uint8_t*               out_scale,
                                 uint8_t*               out_ceiling)
{
  RA8_RETURN_ON_ERROR(internal_cfg_ptrs_ok(cfg), s_tag, "cfg pointer check");
  RA8_RETURN_ON_ERROR(internal_cfg_extent_ok(cfg), s_tag, "cfg extent check");
  RA8_RETURN_ON_ERROR(internal_cfg_scratch_ok(cfg, out_strip_rows), s_tag, "cfg scratch check");
  return internal_cfg_ladder_ok(cfg, out_scale, out_ceiling);
}

RA8_INTERNAL
static void internal_view_adopt(zoom_view_t*           v,
                                const zoom_view_cfg_t* cfg,
                                uint8_t                opening,
                                uint8_t                ceiling,
                                uint16_t               strip_rows)
{
  v->src           = cfg->src;
  v->scratch       = cfg->scratch;
  v->dst           = cfg->dst;
  v->scale         = opening;
  v->scale_max     = ceiling;
  v->policy        = cfg->policy;
  v->settle_ms     = (cfg->settle_ms == 0U) ? (uint16_t)k_zoom_settle_ms_default : cfg->settle_ms;
  v->strip_rows    = strip_rows;
  v->anchor_x      = (cfg->focus_x * (int32_t)opening) - (cfg->dst.w / 2);
  v->anchor_y      = (cfg->focus_y * (int32_t)opening) - (cfg->dst.h / 2);
  v->last_input_ms = 0U;
  v->settle_armed  = false;
  v->pending       = true;
  v->pending_kind  = k_zoom_refresh_quality;
  v->active        = true;
  internal_reclamp(v);
}
 
ra8_err_t zoom_view_open(zoom_view_t* v, const zoom_view_cfg_t* cfg)
{
  RA8_CHECK_NULL_PTR(v, s_tag, "view must not be nullptr");
  RA8_CHECK_NULL_PTR(cfg, s_tag, "cfg must not be nullptr");
  v->active           = false;
  uint16_t strip_rows = 0U;
  uint8_t  opening    = 0U;
  uint8_t  ceiling    = 0U;
  RA8_RETURN_ON_ERROR(internal_cfg_ok(cfg, &strip_rows, &opening, &ceiling), s_tag, "cfg check");
  internal_view_adopt(v, cfg, opening, ceiling, strip_rows);
  return k_ra8_ok;
}
 
ra8_err_t zoom_view_rebind(zoom_view_t* v, const zoom_source_t* src, uint32_t now_ms)
{
  RA8_CHECK_NULL_PTR(v, s_tag, "view must not be nullptr");
  RA8_CHECK_NULL_PTR(src, s_tag, "src must not be nullptr");
  RA8_CHECK_NULL_PTR(src->read, s_tag, "source read seam must not be nullptr");
  if (!v->active) {
    ra8_log_error(s_tag, "rebind on a closed view");
    return k_ra8_err_invalid_state;
  }
  if (!internal_dim_ok(src->width) || !internal_dim_ok(src->height)) {
    ra8_log_error(s_tag, "source extent is zero or exceeds k_zoom_dim_max");
    return k_ra8_err_invalid_arg;
  }
  v->src = *src;
  internal_reclamp(v);
  internal_touch(v, now_ms);
  return k_ra8_ok;
}
 
ra8_err_t zoom_view_invalidate(zoom_view_t* v, uint32_t now_ms)
{
  RA8_CHECK_NULL_PTR(v, s_tag, "view must not be nullptr");
  if (!v->active) {
    ra8_log_error(s_tag, "invalidate on a closed view");
    return k_ra8_err_invalid_state;
  }
  internal_touch(v, now_ms);
  return k_ra8_ok;
}
 
ra8_err_t zoom_view_close(zoom_view_t* v)
{
  RA8_CHECK_NULL_PTR(v, s_tag, "view must not be nullptr");
  v->active       = false;
  v->pending      = false;
  v->settle_armed = false;
  return k_ra8_ok;
}
 
bool zoom_view_active(const zoom_view_t* v)
{
  return (v != nullptr) && v->active;
}
 
uint8_t zoom_scale_cycle(uint8_t scale, uint8_t min, uint8_t max)
{
  const uint8_t floor_v   = (min == 0U) ? (uint8_t)k_zoom_scale_min : min;
  const uint8_t ceiling_v = (max < floor_v) ? floor_v : max;
  if (scale >= ceiling_v) {
    return floor_v;
  }
  const uint16_t doubled = (uint16_t)((uint16_t)scale * (uint16_t)k_zoom_scale_dbl);
  if (doubled >= (uint16_t)ceiling_v) {
    return ceiling_v;
  }
  if (doubled < (uint16_t)floor_v) {
    return floor_v;
  }
  return (uint8_t)doubled;
}
 
ra8_err_t zoom_view_set_scale(zoom_view_t* v,
                              uint8_t      scale,
                              int32_t      focus_x,
                              int32_t      focus_y,
                              uint32_t     now_ms)
{
  RA8_CHECK_NULL_PTR(v, s_tag, "view must not be nullptr");
  if (!v->active) {
    ra8_log_error(s_tag, "set_scale on a closed view");
    return k_ra8_err_invalid_state;
  }
  if ((scale < (uint8_t)k_zoom_scale_min) || (scale > v->scale_max)) {
    ra8_log_error(s_tag, "requested scale is off the ladder");
    return k_ra8_err_out_of_range;
  }
  if (scale == v->scale) {
    return k_ra8_ok;
  }
  /* Keep the plane point under (focus_x, focus_y) fixed: rescale that plane
   * coordinate by new/old, then re-derive the anchor from it. The intermediate
   * product is 64-bit (a plane coordinate times the new scale can exceed int32
   * before the divide brings it back), and each narrowing cast takes a NAMED
   * 64-bit object rather than a composite expression -- casting the quotient
   * in place would change essential type mid-expression (MISRA 10.8). */
  const int32_t off_x    = focus_x - v->dst.x;
  const int32_t off_y    = focus_y - v->dst.y;
  const int64_t old      = (int64_t)v->scale;
  const int64_t plane_x  = (int64_t)(v->anchor_x + off_x) * (int64_t)scale;
  const int64_t plane_y  = (int64_t)(v->anchor_y + off_y) * (int64_t)scale;
  const int64_t scaled_x = plane_x / old;
  const int64_t scaled_y = plane_y / old;
  v->anchor_x            = (int32_t)scaled_x - off_x;
  v->anchor_y            = (int32_t)scaled_y - off_y;
  v->scale               = scale;
  internal_reclamp(v);
  internal_touch(v, now_ms);
  return k_ra8_ok;
}
 
ra8_err_t zoom_view_pan(zoom_view_t* v, int32_t dx, int32_t dy, uint32_t now_ms)
{
  RA8_CHECK_NULL_PTR(v, s_tag, "view must not be nullptr");
  if (!v->active) {
    ra8_log_error(s_tag, "pan on a closed view");
    return k_ra8_err_invalid_state;
  }
  const int32_t was_x = v->anchor_x;
  const int32_t was_y = v->anchor_y;
  v->anchor_x         = internal_sat_add(v->anchor_x, dx);
  v->anchor_y         = internal_sat_add(v->anchor_y, dy);
  internal_reclamp(v);
  /* Decision: a pan that clamped to no movement owes the panel nothing. */
  if ((v->anchor_x != was_x) || (v->anchor_y != was_y)) {
    internal_touch(v, now_ms);
  }
  return k_ra8_ok;
}
 
ra8_err_t zoom_view_pan_dir(zoom_view_t* v, zoom_pan_t dir, uint32_t now_ms)
{
  RA8_CHECK_NULL_PTR(v, s_tag, "view must not be nullptr");
  if (!v->active) {
    ra8_log_error(s_tag, "pan_dir on a closed view");
    return k_ra8_err_invalid_state;
  }
  const int32_t step_x = v->dst.w - (v->dst.w / (int32_t)k_zoom_overlap_div);
  const int32_t step_y = v->dst.h - (v->dst.h / (int32_t)k_zoom_overlap_div);
  int32_t       dx     = 0;
  int32_t       dy     = 0;
  switch (dir) {
    case k_zoom_pan_left:
      dx = -step_x;
      break;
    case k_zoom_pan_right:
      dx = step_x;
      break;
    case k_zoom_pan_up:
      dy = -step_y;
      break;
    case k_zoom_pan_down:
      dy = step_y;
      break;
    case k_zoom_pan_none:
    default:
      break;
  }
  return zoom_view_pan(v, dx, dy, now_ms);
}
 
ra8_err_t zoom_view_window(const zoom_view_t* v, ra8_ui_rect_t* out)
{
  RA8_CHECK_NULL_PTR(v, s_tag, "view must not be nullptr");
  RA8_CHECK_NULL_PTR(out, s_tag, "out rect must not be nullptr");
  if (!v->active) {
    ra8_log_error(s_tag, "window query on a closed view");
    return k_ra8_err_invalid_state;
  }
  zoom_axis_t ax = {};
  zoom_axis_t ay = {};
  priv_zoom_axis(v->anchor_x, v->dst.w, (int32_t)v->scale, (int32_t)v->src.width, &ax);
  priv_zoom_axis(v->anchor_y, v->dst.h, (int32_t)v->scale, (int32_t)v->src.height, &ay);
  out->x = (int32_t)ax.s0;
  out->w = (int32_t)ax.count;
  out->y = (int32_t)ay.s0;
  out->h = (int32_t)ay.count;
  return k_ra8_ok;
}
 
bool zoom_view_tick(zoom_view_t* v, uint32_t now_ms)
{
  if (v == nullptr) {
    return false;
  }
  /* Decision: only an open view with an armed settle can promote to quality. */
  if (!v->active || !v->settle_armed) {
    return false;
  }
  /* Unsigned difference, so a wrapping millisecond counter settles early
   * rather than never. */
  if ((now_ms - v->last_input_ms) < (uint32_t)v->settle_ms) {
    return false;
  }
  v->settle_armed = false;
  v->pending      = true;
  v->pending_kind = k_zoom_refresh_quality;
  return true;
}
 
ra8_err_t zoom_view_present(zoom_view_t* v, zoom_present_t* out)
{
  RA8_CHECK_NULL_PTR(v, s_tag, "view must not be nullptr");
  RA8_CHECK_NULL_PTR(out, s_tag, "present out must not be nullptr");
  if (!v->active) {
    ra8_log_error(s_tag, "present on a closed view");
    return k_ra8_err_invalid_state;
  }
  out->rect    = v->dst;
  out->refresh = v->pending_kind;
  out->present = v->pending;
  v->pending   = false;
  return k_ra8_ok;
}