jof_produce.c

Go to the documentation of this file.

 
#include "jof_produce.h"
 
#include <stddef.h>
#include <stdint.h>
#include <string.h>
 
#include "jof.h"
#include "jof_internal.h"
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_compress.h"
#include "ra8_err.h"
#include "ra8_jpeg_sw.h"
#include "ra8_log.h"
#include "ra8_webp.h"

static const char* const s_tag = "jof_prod";

typedef enum : uint32_t {
  k_jof_sniff_bytes     = 12U,    
  k_jof_png_sig_len     = 8U,     
  k_jof_jpeg_soi_first  = 0xFFU,  
  k_jof_jpeg_soi_second = 0xD8U,  
  k_jof_webp_fourcc_ofs = 8U,     
  k_jof_png_ring        = 65536U, 
  k_jof_png_inbuf       = 4096U,  
  k_jof_byte_mask       = 0xFFU,  
  k_jof_le_sh8          = 8U,     
  k_jof_le_sh16         = 16U,    
  k_jof_le_sh24         = 24U,    
  k_jof_png_ihdr_w      = 16U,    
  k_jof_png_ihdr_h      = 20U,    
  k_jof_png_ihdr_end    = 24U,    
} jof_prod_const_t;

typedef enum : uint8_t {
  k_jof_png_sig_high = 0x89U, 
  k_jof_png_sig_cr   = 0x0DU, 
  k_jof_png_sig_lf   = 0x0AU, 
  k_jof_png_sig_sub  = 0x1AU, 
} jof_png_signature_t;

static const uint8_t s_prod_png_sig[k_jof_png_sig_len] = {k_jof_png_sig_high,
                                                          'P',
                                                          'N',
                                                          'G',
                                                          k_jof_png_sig_cr,
                                                          k_jof_png_sig_lf,
                                                          k_jof_png_sig_sub,
                                                          k_jof_png_sig_lf};

static const uint8_t s_prod_webp_riff[k_jof_magic_len] = {'R', 'I', 'F', 'F'};

static const uint8_t s_prod_webp_webp[k_jof_magic_len] = {'W', 'E', 'B', 'P'};

RA8_PRIV void* priv_jof_bump_take(jof_bump_t* bump, size_t len)
{
  if ((bump == nullptr) || (len == 0U)) {
    return nullptr;
  }
  const size_t mask    = (size_t)k_jof_bump_align - 1U;
  const size_t aligned = (bump->off + mask) & ~mask;
  if ((aligned > bump->cap) || (len > (bump->cap - aligned))) {
    return nullptr;
  }
  bump->off = aligned + len;
  return &bump->base[aligned];
}
 
/* ---------------------------------------------------------------------------
 * Little-endian field writers + sink accounting.
 * ---------------------------------------------------------------------------
 */

RA8_INTERNAL
RA8_INTERNAL static void internal_wr_u16(uint8_t* buf, uint16_t v)
{
  buf[0] = (uint8_t)(v & (uint16_t)k_jof_byte_mask);
  buf[1] = (uint8_t)((uint32_t)v >> k_jof_le_sh8);
}

RA8_INTERNAL
RA8_INTERNAL static void internal_wr_u32(uint8_t* buf, uint32_t v)
{
  buf[0] = (uint8_t)(v & (uint32_t)k_jof_byte_mask);
  buf[1] = (uint8_t)((v >> k_jof_le_sh8) & (uint32_t)k_jof_byte_mask);
  buf[2] = (uint8_t)((v >> k_jof_le_sh16) & (uint32_t)k_jof_byte_mask);
  buf[3] = (uint8_t)((v >> k_jof_le_sh24) & (uint32_t)k_jof_byte_mask);
}

RA8_INTERNAL
RA8_INTERNAL static ra8_err_t internal_sink(jof_prod_state_t* st, const uint8_t* buf, size_t len)
{
  if ((uint64_t)len > ((uint64_t)UINT32_MAX - (uint64_t)st->written)) {
    return k_ra8_err_invalid_size;
  }
  const ra8_err_t err = st->cfg->sink(st->cfg->sink_ctx, buf, len);
  if (err != k_ra8_ok) {
    return err;
  }
  st->written += (uint32_t)len;
  return k_ra8_ok;
}
 
/* ---------------------------------------------------------------------------
 * Prefix-replay pull adapter.
 * ---------------------------------------------------------------------------
 */
 
RA8_PRIV ra8_err_t priv_jof_prefix_pull(void* ctx, uint8_t* buf, size_t cap, size_t* got)
{
  jof_prefix_pull_t* pfx = (jof_prefix_pull_t*)ctx;
  if (pfx->pos < pfx->head_len) {
    const size_t left = pfx->head_len - pfx->pos;
    const size_t take = (cap < left) ? cap : left;
    (void)memcpy(buf, &pfx->head[pfx->pos], take);
    pfx->pos += take;
    *got = take;
    return k_ra8_ok;
  }
  return pfx->inner(pfx->inner_ctx, buf, cap, got);
}
 
/* ---------------------------------------------------------------------------
 * Geometry + band accumulation + tile flush.
 * ---------------------------------------------------------------------------
 */

RA8_INTERNAL
RA8_INTERNAL static ra8_err_t internal_emit_header(jof_prod_state_t* st)
{
  uint8_t hdr[k_jof_hdr_bytes] = {};
  hdr[0]                       = 'J';
  hdr[1]                       = 'O';
  hdr[2]                       = 'F';
  hdr[3]                       = '1';
  internal_wr_u16(&hdr[k_jof_ofs_width], st->w);
  internal_wr_u16(&hdr[k_jof_ofs_height], st->h);
  internal_wr_u16(&hdr[k_jof_ofs_tile_w], st->cfg->tile_w);
  internal_wr_u16(&hdr[k_jof_ofs_tile_h], st->cfg->tile_h);
  hdr[k_jof_ofs_bpp]   = st->bpp;
  hdr[k_jof_ofs_codec] = st->cfg->codec;
  internal_wr_u32(&hdr[k_jof_ofs_tile_count], st->tile_count);
  return internal_sink(st, hdr, sizeof(hdr));
}

RA8_INTERNAL
RA8_INTERNAL static ra8_err_t internal_carve_pixel_path(jof_prod_state_t* st)
{
  const uint16_t tw          = st->cfg->tile_w;
  const uint16_t th          = st->cfg->tile_h;
  const uint64_t band_bytes  = (uint64_t)st->w * (uint64_t)th * (uint64_t)st->bpp;
  const uint32_t tw_eff      = (tw < st->w) ? tw : st->w;
  const uint32_t th_eff      = (th < st->h) ? th : st->h;
  const uint64_t stage_bytes = (uint64_t)tw_eff * (uint64_t)th_eff * (uint64_t)st->bpp;
  // mcdc-deactivated: stage_bytes = tw_eff*th_eff*bpp with tw_eff <= w and th_eff <= tile_h, so stage_bytes <= w*tile_h*bpp = band_bytes always; the stage-overflow arm cannot flip independently of the band arm (which apps/shared_libs/jof/tests/src/test_jof_produce_guards.c drives true via a 32768-wide RGBA source and a 65535-tall tile).
  if ((band_bytes > (uint64_t)UINT32_MAX) || (stage_bytes > (uint64_t)UINT32_MAX)) {
    return k_ra8_err_invalid_size;
  }
  st->band  = priv_jof_bump_take(st->bump, (size_t)band_bytes);
  st->stage = priv_jof_bump_take(st->bump, (size_t)stage_bytes);
  st->idx   = priv_jof_bump_take(st->bump, (size_t)st->tile_count * (size_t)k_jof_index_entry);
  if ((st->band == nullptr) || (st->stage == nullptr) || (st->idx == nullptr)) {
    return k_ra8_err_invalid_size;
  }
  if (st->cfg->codec == (uint8_t)k_jof_codec_deflate) {
    st->cmp_cap = jof_stored_bound((uint32_t)stage_bytes);
    st->cmp     = priv_jof_bump_take(st->bump, (size_t)st->cmp_cap);
    if (st->cmp == nullptr) {
      return k_ra8_err_invalid_size;
    }
  }
  return k_ra8_ok;
}

RA8_PRIV ra8_err_t priv_jof_on_geom(void* ctx, uint16_t width, uint16_t height, uint8_t channels)
{
  jof_prod_state_t* st = (jof_prod_state_t*)ctx;
  if (st->geom_done != 0U) {
    return k_ra8_err_invalid_state;
  }
  if ((width == 0U) || (width > st->cap_w) || (height == 0U) || (height > st->cap_h)) {
    return k_ra8_err_invalid_size;
  }
  const uint32_t cols = ((uint32_t)width + st->cfg->tile_w - 1U) / st->cfg->tile_w;
  const uint32_t rows = ((uint32_t)height + st->cfg->tile_h - 1U) / st->cfg->tile_h;
  if ((cols * rows) > (uint32_t)k_jof_max_tiles) {
    return k_ra8_err_invalid_size;
  }
  st->w          = width;
  st->h          = height;
  st->bpp        = channels;
  st->tile_cols  = (uint16_t)cols;
  st->tile_rows  = (uint16_t)rows;
  st->tile_count = cols * rows;
  ra8_err_t err  = internal_carve_pixel_path(st);
  if (err != k_ra8_ok) {
    return err;
  }
  err = internal_emit_header(st);
  if (err != k_ra8_ok) {
    return err;
  }
  st->geom_done = 1U;
  return k_ra8_ok;
}

RA8_INTERNAL
RA8_INTERNAL static ra8_err_t internal_encode_tile(jof_prod_state_t* st, uint32_t payload)
{
  const uint8_t* out_bytes = st->stage;
  uint32_t       out_len   = payload;
  if (st->cfg->codec == (uint8_t)k_jof_codec_deflate) {
    uint32_t clen = 0U;
    if (ra8_compress(st->stage, payload, st->cmp, st->cmp_cap, st->dfl, st->dfl_len, &clen) !=
        k_ra8_ok) {
      return k_ra8_err_validation_failed;
    }
    out_bytes = st->cmp;
    out_len   = clen;
  }
  uint8_t* entry = &st->idx[(size_t)st->tiles_done * (size_t)k_jof_index_entry];
  internal_wr_u32(&entry[k_jof_idx_ofs_offset], st->written);
  internal_wr_u32(&entry[k_jof_idx_ofs_length], out_len);
  const ra8_err_t err = internal_sink(st, out_bytes, (size_t)out_len);
  if (err != k_ra8_ok) {
    return err;
  }
  st->tiles_done++;
  return k_ra8_ok;
}

RA8_INTERNAL
RA8_INTERNAL static ra8_err_t internal_flush_band(jof_prod_state_t* st, uint32_t th)
{
  const uint32_t stride = (uint32_t)st->w * (uint32_t)st->bpp;
  for (uint32_t tx = 0U; tx < (uint32_t)st->tile_cols; tx++) {
    const uint32_t x0        = tx * (uint32_t)st->cfg->tile_w;
    const uint32_t tw        = (((uint32_t)st->w - x0) < (uint32_t)st->cfg->tile_w)
                                 ? ((uint32_t)st->w - x0)
                                 : (uint32_t)st->cfg->tile_w;
    const uint32_t row_bytes = tw * (uint32_t)st->bpp;
    for (uint32_t r = 0U; r < th; r++) {
      (void)memcpy(&st->stage[(size_t)r * (size_t)row_bytes],
                   &st->band[((size_t)r * (size_t)stride) + ((size_t)x0 * (size_t)st->bpp)],
                   (size_t)row_bytes);
    }
    const ra8_err_t err = internal_encode_tile(st, row_bytes * th);
    if (err != k_ra8_ok) {
      return err;
    }
  }
  return k_ra8_ok;
}
 
RA8_PRIV ra8_err_t priv_jof_on_rows(void*          ctx,
                                    const uint8_t* px,
                                    uint16_t       width,
                                    uint16_t       y0,
                                    uint16_t       nrows,
                                    uint8_t        channels)
{
  jof_prod_state_t* st = (jof_prod_state_t*)ctx;
  RA8_CHECK_NULL_PTR(px, s_tag, "px must not be nullptr");
  if ((st->geom_done == 0U) || (width != st->w) || (channels != st->bpp)) {
    return k_ra8_err_validation_failed;
  }
  // mcdc-deactivated: row-ordering contract guard; the PNG scanline assembler emits exactly one row per call at y0 == rows_done and the JPEG stripe walker emits edge-clamped nrows >= 1 at strictly increasing MCU-row origins, so zero/duplicated/overshooting deliveries are not constructible from a public-API source.
  if ((nrows == 0U) || ((uint32_t)y0 != st->rows_seen) ||
      (((uint32_t)y0 + (uint32_t)nrows) > (uint32_t)st->h)) {
    return k_ra8_err_validation_failed;
  }
  const uint32_t stride = (uint32_t)st->w * (uint32_t)st->bpp;
  const uint8_t* src    = px;
  uint32_t       left   = nrows;
  while (left > 0U) {
    const uint32_t room = (uint32_t)st->cfg->tile_h - st->band_fill;
    const uint32_t take = (left < room) ? left : room;
    (void)memcpy(&st->band[(size_t)st->band_fill * (size_t)stride],
                 src,
                 (size_t)take * (size_t)stride);
    st->band_fill += take;
    st->rows_seen += take;
    src = &src[(size_t)take * (size_t)stride];
    left -= take;
    if (st->band_fill == (uint32_t)st->cfg->tile_h) {
      const ra8_err_t err = internal_flush_band(st, st->band_fill);
      if (err != k_ra8_ok) {
        return err;
      }
      st->band_fill = 0U;
    }
  }
  return k_ra8_ok;
}

RA8_INTERNAL
RA8_INTERNAL static ra8_err_t internal_jpeg_geom(void*     ctx,
                                                 uint16_t  width,
                                                 uint16_t  height,
                                                 uint8_t   channels,
                                                 uint16_t  stripe_rows,
                                                 uint8_t** out_stripe,
                                                 uint32_t* out_stripe_cap)
{
  jof_prod_state_t* st  = (jof_prod_state_t*)ctx;
  const ra8_err_t   err = priv_jof_on_geom(ctx, width, height, channels);
  if (err != k_ra8_ok) {
    return err;
  }
  const uint32_t cap = (uint32_t)width * (uint32_t)stripe_rows * (uint32_t)channels;
  uint8_t*       buf = priv_jof_bump_take(st->bump, (size_t)cap);
  if (buf == nullptr) {
    return k_ra8_err_invalid_size;
  }
  *out_stripe     = buf;
  *out_stripe_cap = cap;
  return k_ra8_ok;
}
 
/* ---------------------------------------------------------------------------
 * Trailer emission + entry point.
 * ---------------------------------------------------------------------------
 */

RA8_INTERNAL
RA8_INTERNAL static ra8_err_t internal_finish(jof_prod_state_t* st, jof_info_t* out_info)
{
  if (st->tiles_done != st->tile_count) {
    return k_ra8_err_validation_failed;
  }
  const uint32_t index_off = st->written;
  ra8_err_t err = internal_sink(st, st->idx, (size_t)st->tile_count * (size_t)k_jof_index_entry);
  if (err != k_ra8_ok) {
    return err;
  }
  uint8_t ftr[k_jof_footer_bytes] = {};
  internal_wr_u32(&ftr[k_jof_ftr_index_off], index_off);
  internal_wr_u32(&ftr[k_jof_ftr_tile_count], st->tile_count);
  internal_wr_u32(&ftr[k_jof_ftr_total_size], st->written + (uint32_t)k_jof_footer_bytes);
  ftr[k_jof_ftr_magic]      = 'J';
  ftr[k_jof_ftr_magic + 1U] = 'O';
  ftr[k_jof_ftr_magic + 2U] = 'F';
  ftr[k_jof_ftr_magic + 3U] = 'E';
  err                       = internal_sink(st, ftr, sizeof(ftr));
  if (err != k_ra8_ok) {
    return err;
  }
  out_info->width      = st->w;
  out_info->height     = st->h;
  out_info->tile_w     = st->cfg->tile_w;
  out_info->tile_h     = st->cfg->tile_h;
  out_info->tile_cols  = st->tile_cols;
  out_info->tile_rows  = st->tile_rows;
  out_info->bpp        = st->bpp;
  out_info->codec      = st->cfg->codec;
  out_info->tile_count = st->tile_count;
  out_info->index_off  = index_off;
  out_info->total_size = st->written;
  return k_ra8_ok;
}

RA8_INTERNAL
RA8_INTERNAL static ra8_err_t internal_check_cfg(const jof_produce_cfg_t* cfg)
{
  if ((cfg->tile_w == 0U) || (cfg->tile_h == 0U)) {
    return k_ra8_err_invalid_arg;
  }
  if (cfg->codec > (uint8_t)k_jof_codec_deflate) {
    return k_ra8_err_invalid_arg;
  }
  return k_ra8_ok;
}
 
uint32_t jof_work_bytes(uint16_t max_width, uint16_t max_height, uint16_t tile_w, uint16_t tile_h)
{
  if ((max_width == 0U) || ((uint32_t)max_width > (uint32_t)k_jof_max_dim) || (max_height == 0U) ||
      ((uint32_t)max_height > (uint32_t)k_jof_max_dim)) {
    return 0U;
  }
  if ((tile_w == 0U) || (tile_h == 0U)) {
    return 0U;
  }
  const uint64_t cols = ((uint64_t)max_width + tile_w - 1U) / tile_w;
  const uint64_t rows = ((uint64_t)max_height + tile_h - 1U) / tile_h;
  if ((cols * rows) > (uint64_t)k_jof_max_tiles) {
    return 0U;
  }
  const uint64_t bpp = (uint64_t)k_jof_bpp_max;
  const uint64_t jpeg_set =
    (uint64_t)k_ra8_jpeg_sw_stream_min_window +
    ((uint64_t)max_width * (uint64_t)k_ra8_jpeg_sw_stream_mcu_rows_max * 3U);
  const uint64_t png_set = (uint64_t)sizeof(tinfl_decompressor) + (uint64_t)k_jof_png_ring +
                           (uint64_t)k_jof_png_inbuf + (3U * ((uint64_t)max_width * bpp)) + 2U;
  const uint64_t dec_set = (jpeg_set > png_set) ? jpeg_set : png_set;
  const uint64_t band    = (uint64_t)max_width * (uint64_t)tile_h * bpp;
  const uint64_t tw_eff =
    ((uint64_t)tile_w < (uint64_t)max_width) ? (uint64_t)tile_w : (uint64_t)max_width;
  const uint64_t th_eff =
    ((uint64_t)tile_h < (uint64_t)max_height) ? (uint64_t)tile_h : (uint64_t)max_height;
  const uint64_t stage       = tw_eff * th_eff * bpp;
  const uint64_t cmp         = (uint64_t)jof_stored_bound((uint32_t)stage);
  const uint64_t index_bytes = cols * rows * (uint64_t)k_jof_index_entry;
  const uint64_t dfl         = (uint64_t)k_ra8_compress_scratch_bytes;
  const uint64_t total =
    dec_set + band + stage + cmp + index_bytes + dfl + (uint64_t)k_jof_carve_slack;
  if ((stage > (uint64_t)UINT32_MAX) || (total > (uint64_t)UINT32_MAX)) {
    return 0U;
  }
  return (uint32_t)total;
}

RA8_INTERNAL
RA8_INTERNAL static ra8_err_t internal_init_state(jof_prod_state_t*        st,
                                                  const jof_produce_cfg_t* cfg)
{
  (void)memset(st, 0, sizeof(*st));
  st->cfg        = cfg;
  st->bump_store = (jof_bump_t){.base = cfg->work, .cap = cfg->work_cap, .off = 0U};
  st->bump       = &st->bump_store;
  st->cap_w      = ((cfg->max_width != 0U) && ((uint32_t)cfg->max_width < (uint32_t)k_jof_max_dim))
                     ? cfg->max_width
                     : (uint16_t)k_jof_max_dim;
  st->cap_h = ((cfg->max_height != 0U) && ((uint32_t)cfg->max_height < (uint32_t)k_jof_max_dim))
                ? cfg->max_height
                : (uint16_t)k_jof_max_dim;
  if (cfg->codec == (uint8_t)k_jof_codec_deflate) {
    st->dfl_len = (uint32_t)k_ra8_compress_scratch_bytes;
    st->dfl     = priv_jof_bump_take(st->bump, (size_t)st->dfl_len);
    if (st->dfl == nullptr) {
      return k_ra8_err_invalid_size;
    }
  }
  return k_ra8_ok;
}

RA8_INTERNAL
RA8_INTERNAL static ra8_err_t internal_sniff_head(const jof_produce_cfg_t* cfg, uint8_t* head)
{
  size_t head_len = 0U;
  while (head_len < (size_t)k_jof_sniff_bytes) {
    size_t          got = 0U;
    const ra8_err_t err =
      cfg->pull(cfg->pull_ctx, &head[head_len], (size_t)k_jof_sniff_bytes - head_len, &got);
    if (err != k_ra8_ok) {
      return err;
    }
    if (got == 0U) {
      return k_ra8_err_protocol_error; /* too short to be a JPEG/PNG */
    }
    head_len += got;
  }
  return k_ra8_ok;
}

RA8_INTERNAL
RA8_INTERNAL static ra8_err_t
internal_dispatch(jof_prod_state_t* st, const uint8_t* head, jof_prefix_pull_t* pfx)
{
  if ((head[0] == (uint8_t)k_jof_jpeg_soi_first) && (head[1] == (uint8_t)k_jof_jpeg_soi_second)) {
    uint8_t* window = priv_jof_bump_take(st->bump, (size_t)k_ra8_jpeg_sw_stream_min_window);
    if (window == nullptr) {
      return k_ra8_err_invalid_size;
    }
    return ra8_jpeg_sw_decode_stripes(priv_jof_prefix_pull,
                                      pfx,
                                      window,
                                      (uint32_t)k_ra8_jpeg_sw_stream_min_window,
                                      internal_jpeg_geom,
                                      priv_jof_on_rows,
                                      st);
  }
  if (memcmp(head, s_prod_png_sig, sizeof(s_prod_png_sig)) == 0) {
    return priv_jof_png_rows(priv_jof_prefix_pull,
                             pfx,
                             st->bump,
                             st->cap_w,
                             st->cap_h,
                             priv_jof_on_geom,
                             priv_jof_on_rows,
                             st);
  }
  if ((memcmp(head, s_prod_webp_riff, sizeof(s_prod_webp_riff)) == 0) &&
      (memcmp(&head[k_jof_webp_fourcc_ofs], s_prod_webp_webp, sizeof(s_prod_webp_webp)) == 0)) {
    return priv_jof_webp_transcode(st, pfx);
  }
  return k_ra8_err_not_supported; /* not a JPEG/PNG/WebP source */
}

RA8_INTERNAL
RA8_INTERNAL static uint32_t internal_rd_be32(const uint8_t* buf)
{
  return ((uint32_t)buf[0] << k_jof_le_sh24) | ((uint32_t)buf[1] << k_jof_le_sh16) |
         ((uint32_t)buf[2] << k_jof_le_sh8) | (uint32_t)buf[3];
}

RA8_INTERNAL
RA8_INTERNAL static bool internal_is_webp(const uint8_t* data)
{
  return (memcmp(data, s_prod_webp_riff, sizeof(s_prod_webp_riff)) == 0) &&
         (memcmp(&data[k_jof_webp_fourcc_ofs], s_prod_webp_webp, sizeof(s_prod_webp_webp)) == 0);
}

RA8_INTERNAL
RA8_INTERNAL static ra8_err_t
internal_png_dims(const uint8_t* data, size_t len, uint32_t* out_w, uint32_t* out_h)
{
  if (len < (size_t)k_jof_png_ihdr_end) {
    return k_ra8_err_not_supported; /* IHDR truncated */
  }
  *out_w = internal_rd_be32(&data[k_jof_png_ihdr_w]);
  *out_h = internal_rd_be32(&data[k_jof_png_ihdr_h]);
  return k_ra8_ok;
}

RA8_INTERNAL
RA8_INTERNAL static ra8_err_t
internal_probe_sniff(const uint8_t* data, size_t len, uint16_t* out_w, uint16_t* out_h)
{
  if (len < (size_t)k_jof_sniff_bytes) {
    return k_ra8_err_not_supported; /* too short to carry any accepted magic */
  }
  uint32_t w = 0U;
  uint32_t h = 0U;
  if ((data[0] == (uint8_t)k_jof_jpeg_soi_first) && (data[1] == (uint8_t)k_jof_jpeg_soi_second)) {
    return ra8_jpeg_sw_get_dimensions(data, (uint32_t)len, out_w, out_h);
  }
  if (memcmp(data, s_prod_png_sig, sizeof(s_prod_png_sig)) == 0) {
    const ra8_err_t rc = internal_png_dims(data, len, &w, &h);
    if (rc != k_ra8_ok) {
      return rc;
    }
  } else if (internal_is_webp(data)) {
    const ra8_err_t rc = ra8_webp_get_info(data, len, &w, &h);
    if (rc != k_ra8_ok) {
      return rc;
    }
  } else {
    return k_ra8_err_not_supported; /* not a JPEG/PNG/WebP source */
  }
  if ((w == 0U) || (h == 0U) || (w > (uint32_t)k_jof_max_dim) || (h > (uint32_t)k_jof_max_dim)) {
    return k_ra8_err_invalid_size;
  }
  *out_w = (uint16_t)w;
  *out_h = (uint16_t)h;
  return k_ra8_ok;
}
 
ra8_err_t jof_probe_dims(const uint8_t* data, size_t len, uint16_t* out_w, uint16_t* out_h)
{
  RA8_CHECK_NULL_PTR(data, s_tag, "data 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");
  return internal_probe_sniff(data, len, out_w, out_h);
}

RA8_INTERNAL
RA8_INTERNAL static ra8_err_t internal_epilogue(jof_prod_state_t* st, jof_info_t* out_info)
{
  // mcdc-deactivated: post-decode contract guard; both in-tree decoders return success only after the geometry hook fired and every declared row was delivered (short/hostile streams abort inside the decoder), so neither condition can be flipped through the public producer entry.
  if ((st->geom_done == 0U) || (st->rows_seen != (uint32_t)st->h)) {
    return k_ra8_err_validation_failed; /* decoder under-delivered */
  }
  if (st->band_fill > 0U) {
    const ra8_err_t err = internal_flush_band(st, st->band_fill);
    if (err != k_ra8_ok) {
      return err;
    }
    st->band_fill = 0U;
  }
  return internal_finish(st, out_info);
}

RA8_INTERNAL
RA8_INTERNAL static ra8_err_t internal_produce_args_ok(const jof_produce_cfg_t* cfg,
                                                       const jof_info_t*        out_info)
{
  RA8_CHECK_NULL_PTR(cfg, s_tag, "cfg must not be nullptr");
  RA8_CHECK_NULL_PTR(out_info, s_tag, "out_info must not be nullptr");
  RA8_CHECK_NULL_PTR(cfg->pull, s_tag, "cfg->pull must not be nullptr");
  RA8_CHECK_NULL_PTR(cfg->sink, s_tag, "cfg->sink must not be nullptr");
  RA8_CHECK_NULL_PTR(cfg->work, s_tag, "cfg->work must not be nullptr");
  return k_ra8_ok;
}
 
ra8_err_t jof_produce(const jof_produce_cfg_t* cfg, jof_info_t* out_info)
{
  static jof_prod_state_t s_prod;
  ra8_err_t               err = internal_produce_args_ok(cfg, out_info);
  if (err != k_ra8_ok) {
    return err;
  }
  err = internal_check_cfg(cfg);
  if (err != k_ra8_ok) {
    return err;
  }
  jof_prod_state_t* st = &s_prod;
  err                  = internal_init_state(st, cfg);
  if (err != k_ra8_ok) {
    return err;
  }
  uint8_t head[k_jof_sniff_bytes] = {};
  err                             = internal_sniff_head(cfg, head);
  if (err != k_ra8_ok) {
    return err;
  }
  jof_prefix_pull_t pfx = {
    .head      = head,
    .head_len  = sizeof(head),
    .pos       = 0U,
    .inner     = cfg->pull,
    .inner_ctx = cfg->pull_ctx,
  };
  err = internal_dispatch(st, head, &pfx);
  if (err != k_ra8_ok) {
    return err;
  }
  return internal_epilogue(st, out_info);
}