ra8_jpeg_sw_decode.c

Go to the documentation of this file.

 
#include <stdint.h> // ra8-keep-include: `uint8_t` used directly
#include <string.h>
 
#include "ra8_attributes.h" // ra8-keep-include: `RA8_INTERNAL` and `RA8_PRIV` used directly
#include "ra8_check.h"
#include "ra8_err.h" // ra8-keep-include: `ra8_err_t` used directly
#include "ra8_jpeg_sw.h"
#include "ra8_jpeg_sw_internal.h"

static const char* s_tag = "JPEG_SW";
 
/* ------------------------------------------------------------------ */
/* Decoder */
/* ------------------------------------------------------------------ */
 
/* The decoder context (`ra8_jpeg_dec_ctx_t`) and the marker/scan
 * primitives below are declared in `ra8_jpeg_sw_internal.h` so the
 * streaming driver (`ra8_jpeg_sw_stream.c`) can reuse them over its
 * sliding window; this unit keeps their definitions plus the
 * whole-buffer `ra8_jpeg_sw_decode()` driver. */

RA8_PRIV ra8_err_t priv_jpeg_sw_skip_segment(ra8_jpeg_dec_ctx_t* d)
{
  if (d->cursor + 2U > d->src_len) {
    return k_ra8_err_protocol_error;
  }
  uint16_t len = internal_read_be16(&d->src[d->cursor]);
  if (len < 2U || (uint32_t)len > d->src_len - d->cursor) {
    return k_ra8_err_protocol_error;
  }
  d->cursor += len;
  return k_ra8_ok;
}

RA8_PRIV ra8_err_t priv_jpeg_sw_parse_dqt(ra8_jpeg_dec_ctx_t* d)
{
  if (d->cursor + 2U > d->src_len) {
    return k_ra8_err_protocol_error;
  }
  uint16_t len = internal_read_be16(&d->src[d->cursor]);
  if (len < 2U || (uint32_t)len > d->src_len - d->cursor) {
    return k_ra8_err_protocol_error;
  }
  uint32_t end = d->cursor + len;
  d->cursor += 2U;
  while (d->cursor < end) {
    uint8_t pq_tq = d->src[d->cursor];
    d->cursor++;
    uint8_t pq = (uint8_t)(pq_tq >> k_ra8_jpeg_nibble_shift);
    uint8_t tq = (uint8_t)(pq_tq & k_ra8_jpeg_nibble_mask);
    if (tq >= (uint8_t)k_ra8_jpeg_quant_tabs || pq != 0U) {
      return k_ra8_err_not_supported; /* 16-bit precision not supported. */
    }
    if (d->cursor + (uint32_t)k_ra8_jpeg_block_size > end) {
      return k_ra8_err_protocol_error;
    }
    for (uint8_t i = 0U; i < (uint8_t)k_ra8_jpeg_block_size; i++) {
      d->qtab[tq][s_zigzag[i]] = d->src[d->cursor];
      d->cursor++;
    }
  }
  return k_ra8_ok;
}

RA8_INTERNAL static ra8_err_t internal_dec_parse_dht_one(ra8_jpeg_dec_ctx_t* d, uint32_t end)
{
  uint8_t tc_th = d->src[d->cursor];
  d->cursor++;
  uint8_t tc = (uint8_t)(tc_th >> k_ra8_jpeg_nibble_shift);
  uint8_t th = (uint8_t)(tc_th & k_ra8_jpeg_nibble_mask);
  if (tc >= (uint8_t)k_ra8_jpeg_huff_classes || th >= (uint8_t)k_ra8_jpeg_huff_ids) {
    return k_ra8_err_not_supported;
  }
  if (d->cursor + (uint32_t)k_ra8_jpeg_huff_lengths > end) {
    return k_ra8_err_protocol_error;
  }
  ra8_jpeg_htab_t* h     = (tc == 0U) ? &d->hdc[th] : &d->hac[th];
  uint16_t         total = 0U;
  for (uint8_t i = 0U; i < (uint8_t)k_ra8_jpeg_huff_lengths; i++) {
    h->bits[i] = d->src[d->cursor];
    d->cursor++;
    total = (uint16_t)(total + h->bits[i]);
  }
  if (total > (uint16_t)k_ra8_jpeg_huff_max) {
    return k_ra8_err_protocol_error;
  }
  if (d->cursor + total > end) {
    return k_ra8_err_protocol_error;
  }
  for (uint16_t i = 0U; i < total; i++) {
    h->vals[i] = d->src[d->cursor];
    d->cursor++;
  }
  priv_jpeg_sw_htab_build(h);
  return k_ra8_ok;
}

RA8_PRIV ra8_err_t priv_jpeg_sw_parse_dht(ra8_jpeg_dec_ctx_t* d)
{
  if (d->cursor + 2U > d->src_len) {
    return k_ra8_err_protocol_error;
  }
  uint16_t len = internal_read_be16(&d->src[d->cursor]);
  if (len < 2U || (uint32_t)len > d->src_len - d->cursor) {
    return k_ra8_err_protocol_error;
  }
  uint32_t end = d->cursor + len;
  d->cursor += 2U;
  while (d->cursor < end) {
    ra8_err_t e = internal_dec_parse_dht_one(d, end);
    if (e != k_ra8_ok) {
      return e;
    }
  }
  return k_ra8_ok;
}

RA8_INTERNAL static void internal_dec_parse_sof0_components(ra8_jpeg_dec_ctx_t* d, uint32_t* s)
{
  d->hmax = 0U;
  d->vmax = 0U;
  for (uint8_t i = 0U; i < d->ncomp; i++) {
    d->comp_id[i] = d->src[*s];
    (*s)++;
    uint8_t hv = d->src[*s];
    (*s)++;
    d->comp_h[i]   = (uint8_t)(hv >> k_ra8_jpeg_nibble_shift);
    d->comp_v[i]   = (uint8_t)(hv & k_ra8_jpeg_nibble_mask);
    d->comp_qid[i] = d->src[*s];
    (*s)++;
    if (d->comp_h[i] > d->hmax) {
      d->hmax = d->comp_h[i];
    }
    if (d->comp_v[i] > d->vmax) {
      d->vmax = d->comp_v[i];
    }
  }
}

RA8_INTERNAL static ra8_err_t internal_dec_check_chroma_layout(const ra8_jpeg_dec_ctx_t* d)
{
  /* Only 4:4:4 (1,1,1) and 4:2:0 (2,1,1) accepted. */
  if (d->ncomp == 3U) {
    bool is_444 = (d->hmax == 1U && d->vmax == 1U);
    bool is_420 = (d->hmax == 2U && d->vmax == 2U && d->comp_h[1] == 1U && d->comp_v[1] == 1U &&
                   d->comp_h[2] == 1U && d->comp_v[2] == 1U);
    if (!is_444 && !is_420) {
      return k_ra8_err_not_supported;
    }
  }
  return k_ra8_ok;
}

RA8_PRIV ra8_err_t priv_jpeg_sw_parse_sof0(ra8_jpeg_dec_ctx_t* d)
{
  if (d->cursor + 2U > d->src_len) {
    return k_ra8_err_protocol_error;
  }
  uint16_t len = internal_read_be16(&d->src[d->cursor]);
  if (len < 8U || (uint32_t)len > d->src_len - d->cursor) {
    return k_ra8_err_protocol_error;
  }
  uint32_t s         = d->cursor + 2U;
  uint8_t  precision = d->src[s];
  s++;
  if (precision != 8U) {
    return k_ra8_err_not_supported;
  }
  d->height = internal_read_be16(&d->src[s]);
  s += 2U;
  d->width = internal_read_be16(&d->src[s]);
  s += 2U;
  d->ncomp = d->src[s];
  s++;
  if (d->ncomp != 1U && d->ncomp != 3U) {
    return k_ra8_err_not_supported;
  }
  if (((uint32_t)d->ncomp * 3U) + (s - d->cursor) > (uint32_t)len) {
    return k_ra8_err_protocol_error;
  }
  internal_dec_parse_sof0_components(d, &s);
  d->cursor += len;
  return internal_dec_check_chroma_layout(d);
}

RA8_PRIV ra8_err_t priv_jpeg_sw_parse_sos(ra8_jpeg_dec_ctx_t* d)
{
  if (d->cursor + 2U > d->src_len) {
    return k_ra8_err_protocol_error;
  }
  uint16_t len = internal_read_be16(&d->src[d->cursor]);
  if (len < 6U || (uint32_t)len > d->src_len - d->cursor) {
    return k_ra8_err_protocol_error;
  }
  uint32_t s  = d->cursor + 2U;
  uint8_t  ns = d->src[s];
  s++;
  if (ns != d->ncomp) {
    return k_ra8_err_not_supported;
  }
  for (uint8_t i = 0U; i < ns; i++) {
    uint8_t cs = d->src[s];
    s++;
    uint8_t tdta = d->src[s];
    s++;
    uint8_t idx = i;
    for (uint8_t j = 0U; j < d->ncomp; j++) {
      if (d->comp_id[j] == cs) {
        idx = j;
        break;
      }
    }
    d->comp_dc_id[idx] = (uint8_t)(tdta >> k_ra8_jpeg_nibble_shift);
    d->comp_ac_id[idx] = (uint8_t)(tdta & k_ra8_jpeg_nibble_mask);
    if (d->comp_dc_id[idx] >= (uint8_t)k_ra8_jpeg_huff_ids ||
        d->comp_ac_id[idx] >= (uint8_t)k_ra8_jpeg_huff_ids) {
      return k_ra8_err_not_supported;
    }
  }
  /* Skip Ss/Se/AhAl (3 bytes). */
  d->cursor += len;
  return k_ra8_ok;
}

RA8_INTERNAL static ra8_err_t
internal_dec_block_ac(ra8_jpeg_dec_ctx_t* d, ra8_jpeg_bitreader_t* br, uint8_t ci, int32_t* outblk)
{
  uint8_t k = 1U;
  while (k < (uint8_t)k_ra8_jpeg_block_size) {
    int32_t rs = priv_jpeg_sw_htab_decode(br, &d->hac[d->comp_ac_id[ci]]);
    if (rs < 0) {
      return k_ra8_err_protocol_error;
    }
    uint8_t rrrr = (uint8_t)(rs >> k_ra8_jpeg_nibble_shift);
    uint8_t ssss = (uint8_t)(rs & k_ra8_jpeg_nibble_mask);
    if (ssss == 0U) {
      if (rrrr == k_jpeg_nibble_mask) {
        k = (uint8_t)(k + 16U); /* ZRL: 16 zero coeffs. */
        continue;
      }
      break; /* EOB. */
    }
    k = (uint8_t)(k + rrrr);
    if (k >= (uint8_t)k_ra8_jpeg_block_size) {
      return k_ra8_err_protocol_error;
    }
    int32_t v = priv_jpeg_sw_br_get_bits(br, ssss);
    if (v < 0) {
      return k_ra8_err_protocol_error;
    }
    v                   = priv_jpeg_sw_huff_extend(v, ssss);
    outblk[s_zigzag[k]] = v * (int32_t)d->qtab[d->comp_qid[ci]][s_zigzag[k]];
    k++;
  }
  return k_ra8_ok;
}

RA8_PRIV ra8_err_t priv_jpeg_sw_block(ra8_jpeg_dec_ctx_t*   d,
                                      ra8_jpeg_bitreader_t* br,
                                      uint8_t               ci,
                                      int32_t*              outblk)
{
  for (uint8_t i = 0U; i < (uint8_t)k_ra8_jpeg_block_size; i++) {
    outblk[i] = 0;
  }
  /* DC. */
  int32_t t = priv_jpeg_sw_htab_decode(br, &d->hdc[d->comp_dc_id[ci]]);
  if (t < 0) {
    return k_ra8_err_protocol_error;
  }
  int32_t r = priv_jpeg_sw_br_get_bits(br, (uint8_t)t);
  /* A zero-width Huffman value requests no bits, so the bit reader cannot
   * return its exhausted sentinel when t == 0. */
  // mcdc-deactivated: t == 0 requests no bits, so r < 0 requires t != 0; the operands cannot independently vary.
  if (r < 0 && t != 0) {
    return k_ra8_err_protocol_error;
  }
  int32_t diff = priv_jpeg_sw_huff_extend(r, (uint8_t)t);
  d->comp_dc_pred[ci] += diff;
  outblk[0] = d->comp_dc_pred[ci] * (int32_t)d->qtab[d->comp_qid[ci]][0];
 
  /* AC. */
  return internal_dec_block_ac(d, br, ci, outblk);
}
 
/* ------------------------------------------------------------------ */
/* Public API: decode */
/* ------------------------------------------------------------------ */

RA8_PRIV void priv_jpeg_sw_idct_into(int32_t* coeffs, uint8_t* tile)
{
  priv_jpeg_sw_idct8x8(coeffs);
  for (uint8_t i = 0U; i < (uint8_t)k_ra8_jpeg_block_size; i++) {
    int32_t v = coeffs[i] + (int32_t)k_ra8_jpeg_level_offset;
    tile[i]   = internal_clamp_u8(v);
  }
}

RA8_INTERNAL static void internal_dec_copy_block_to_tile(const uint8_t* blk,
                                                         uint8_t*       y_tile,
                                                         uint8_t        bx,
                                                         uint8_t        by,
                                                         uint16_t       mcu_w_px)
{
  for (uint8_t r = 0U; r < (uint8_t)k_ra8_jpeg_block_dim; r++) {
    for (uint8_t c = 0U; c < (uint8_t)k_ra8_jpeg_block_dim; c++) {
      uint16_t ty                  = (uint16_t)((by * (uint16_t)k_ra8_jpeg_block_dim) + r);
      uint16_t tx                  = (uint16_t)((bx * (uint16_t)k_ra8_jpeg_block_dim) + c);
      y_tile[(ty * mcu_w_px) + tx] = blk[(r * (uint8_t)k_ra8_jpeg_block_dim) + c];
    }
  }
}

RA8_PRIV ra8_err_t priv_jpeg_sw_mcu_y(ra8_jpeg_dec_ctx_t*   d,
                                      ra8_jpeg_bitreader_t* br,
                                      uint8_t*              y_tile,
                                      uint16_t              mcu_w_px)
{
  int32_t coeffs[(uint32_t)k_ra8_jpeg_block_size];
  for (uint8_t by = 0U; by < d->vmax; by++) {
    for (uint8_t bx = 0U; bx < d->hmax; bx++) {
      ra8_err_t e = priv_jpeg_sw_block(d, br, 0U, coeffs);
      if (e != k_ra8_ok) {
        return e;
      }
      uint8_t blk[(uint32_t)k_ra8_jpeg_block_size];
      priv_jpeg_sw_idct_into(coeffs, blk);
      internal_dec_copy_block_to_tile(blk, y_tile, bx, by, mcu_w_px);
    }
  }
  return k_ra8_ok;
}

RA8_PRIV ra8_err_t priv_jpeg_sw_mcu_chroma(ra8_jpeg_dec_ctx_t*   d,
                                           ra8_jpeg_bitreader_t* br,
                                           uint8_t*              cb_tile,
                                           uint8_t*              cr_tile)
{
  int32_t   coeffs[(uint32_t)k_ra8_jpeg_block_size];
  ra8_err_t e = priv_jpeg_sw_block(d, br, 1U, coeffs);
  if (e != k_ra8_ok) {
    return e;
  }
  priv_jpeg_sw_idct_into(coeffs, cb_tile);
  e = priv_jpeg_sw_block(d, br, 2U, coeffs);
  if (e != k_ra8_ok) {
    return e;
  }
  priv_jpeg_sw_idct_into(coeffs, cr_tile);
  return k_ra8_ok;
}

RA8_INTERNAL static void internal_dec_emit_mcu_rgb(const ra8_jpeg_dec_ctx_t* d,
                                                   const uint8_t*            y_tile,
                                                   const uint8_t*            cb_tile,
                                                   const uint8_t*            cr_tile,
                                                   uint16_t                  mx,
                                                   uint16_t                  my,
                                                   uint16_t                  mcu_w_px,
                                                   uint16_t                  mcu_h_px,
                                                   uint8_t*                  out_buf)
{
  for (uint16_t r = 0U; r < mcu_h_px; r++) {
    uint16_t py = (uint16_t)((my * mcu_h_px) + r);
    if (py >= d->height) {
      break;
    }
    for (uint16_t c = 0U; c < mcu_w_px; c++) {
      uint16_t px = (uint16_t)((mx * mcu_w_px) + c);
      if (px >= d->width) {
        break;
      }
      int32_t y = (int32_t)y_tile[(r * mcu_w_px) + c];
      int32_t cb;
      int32_t cr;
      if (d->ncomp == 3U) {
        uint16_t cr_x = (uint16_t)(c / d->hmax);
        uint16_t cr_y = (uint16_t)(r / d->vmax);
        cb            = (int32_t)cb_tile[(cr_y * (uint16_t)k_ra8_jpeg_block_dim) + cr_x];
        cr            = (int32_t)cr_tile[(cr_y * (uint16_t)k_ra8_jpeg_block_dim) + cr_x];
      } else {
        cb = (int32_t)k_ra8_jpeg_level_offset;
        cr = (int32_t)k_ra8_jpeg_level_offset;
      }
      uint32_t idx =
        (((uint32_t)py * (uint32_t)d->width) + (uint32_t)px) * (uint32_t)k_ra8_jpeg_rgb_components;
      priv_jpeg_sw_ycc_to_rgb(y, cb, cr, &out_buf[idx], &out_buf[idx + 1U], &out_buf[idx + 2U]);
    }
  }
}

RA8_INTERNAL static ra8_err_t internal_dec_decode_mcu(ra8_jpeg_dec_ctx_t*   d,
                                                      ra8_jpeg_bitreader_t* br,
                                                      uint8_t*              y_tile,
                                                      uint8_t*              cb_tile,
                                                      uint8_t*              cr_tile,
                                                      uint16_t              mx,
                                                      uint16_t              my,
                                                      uint16_t              mcu_w_px,
                                                      uint16_t              mcu_h_px,
                                                      uint8_t*              out_buf)
{
  ra8_err_t e = priv_jpeg_sw_mcu_y(d, br, y_tile, mcu_w_px);
  if (e != k_ra8_ok) {
    return e;
  }
  if (d->ncomp == 3U) {
    e = priv_jpeg_sw_mcu_chroma(d, br, cb_tile, cr_tile);
    if (e != k_ra8_ok) {
      return e;
    }
  }
  internal_dec_emit_mcu_rgb(d, y_tile, cb_tile, cr_tile, mx, my, mcu_w_px, mcu_h_px, out_buf);
  return k_ra8_ok;
}

RA8_INTERNAL static void internal_dec_scan_begin(ra8_jpeg_dec_ctx_t* d, ra8_jpeg_bitreader_t* br)
{
  br->buf     = d->src;
  br->len     = d->src_len;
  br->pos     = d->cursor;
  br->acc     = 0U;
  br->nbits   = 0U;
  br->had_eoi = 0U;
  for (uint8_t i = 0U; i < (uint8_t)k_ra8_jpeg_max_comps; i++) {
    d->comp_dc_pred[i] = 0;
  }
}

RA8_INTERNAL static ra8_err_t
internal_dec_decode_scan(ra8_jpeg_dec_ctx_t* d, uint8_t* out_buf, uint32_t out_buf_len)
{
  uint32_t need = (uint32_t)d->width * (uint32_t)d->height * (uint32_t)k_ra8_jpeg_rgb_components;
  if (out_buf_len < need) {
    return k_ra8_err_invalid_size;
  }
 
  ra8_jpeg_bitreader_t br;
  internal_dec_scan_begin(d, &br);
 
  /*
   * Cross-function invariant: priv_jpeg_sw_parse_sof0() only returns
   * success for the 4:4:4 and 4:2:0 chroma layouts (and grayscale), all
   * of which set hmax and vmax to a non-zero value.
   * The clang static analyzer (scan-build, core.DivideZero) cannot follow
   * the cross-function invariant, so re-state it here as an assertion to
   * make the property locally provable to the analyzer and to NASA Power-
   * of-10 Rule 5 readers.
   */
  RA8_ASSERT(d->hmax > 0U, "JPEG decoder hmax must be positive");
  RA8_ASSERT(d->vmax > 0U, "JPEG decoder vmax must be positive");
 
  uint16_t mcu_w_px = (uint16_t)((uint16_t)k_ra8_jpeg_block_dim * d->hmax);
  uint16_t mcu_h_px = (uint16_t)((uint16_t)k_ra8_jpeg_block_dim * d->vmax);
  uint16_t mcus_x   = (uint16_t)(((d->width + mcu_w_px) - 1U) / mcu_w_px);
  uint16_t mcus_y   = (uint16_t)(((d->height + mcu_h_px) - 1U) / mcu_h_px);
 
  uint8_t y_tile[(uint32_t)k_ra8_jpeg_mcu_max_dim * (uint32_t)k_ra8_jpeg_mcu_max_dim];
  uint8_t cb_tile[(uint32_t)k_ra8_jpeg_block_size];
  uint8_t cr_tile[(uint32_t)k_ra8_jpeg_block_size];
 
  for (uint16_t my = 0U; my < mcus_y; my++) {
    for (uint16_t mx = 0U; mx < mcus_x; mx++) {
      ra8_err_t e = internal_dec_decode_mcu(d,
                                            &br,
                                            y_tile,
                                            cb_tile,
                                            cr_tile,
                                            mx,
                                            my,
                                            mcu_w_px,
                                            mcu_h_px,
                                            out_buf);
      if (e != k_ra8_ok) {
        return e;
      }
    }
  }
  d->cursor = br.pos;
  return k_ra8_ok;
}

RA8_INTERNAL static ra8_err_t internal_dec_dispatch_tail(ra8_jpeg_dec_ctx_t*           d,
                                                         uint16_t                      mk,
                                                         bool                          got_sof,
                                                         ra8_jpeg_dec_marker_action_t* action)
{
  if (mk == (uint16_t)k_ra8_jpeg_marker_dqt) {
    return priv_jpeg_sw_parse_dqt(d);
  }
  if (mk == (uint16_t)k_ra8_jpeg_marker_dht) {
    return priv_jpeg_sw_parse_dht(d);
  }
  if (mk == (uint16_t)k_ra8_jpeg_marker_sos) {
    if (!got_sof) {
      return k_ra8_err_protocol_error;
    }
    ra8_err_t e = priv_jpeg_sw_parse_sos(d);
    if (e != k_ra8_ok) {
      return e;
    }
    *action = k_ra8_jpeg_dec_scan;
    return k_ra8_ok;
  }
  if (mk == (uint16_t)k_ra8_jpeg_marker_eoi) {
    *action = k_ra8_jpeg_dec_eoi;
    return k_ra8_ok;
  }
  if (mk >= (uint16_t)k_ra8_jpeg_marker_rst0 && mk <= (uint16_t)k_ra8_jpeg_marker_rst7) {
    /* Standalone marker, no length. */
    return k_ra8_ok;
  }
  return priv_jpeg_sw_skip_segment(d);
}

RA8_PRIV ra8_err_t priv_jpeg_sw_dispatch(ra8_jpeg_dec_ctx_t*           d,
                                         bool*                         got_sof,
                                         ra8_jpeg_dec_marker_action_t* action)
{
  *action = k_ra8_jpeg_dec_continue;
  if (d->src[d->cursor] != (uint8_t)k_ra8_jpeg_marker_byte) {
    return k_ra8_err_protocol_error;
  }
  while (d->cursor < d->src_len && d->src[d->cursor] == (uint8_t)k_ra8_jpeg_marker_byte) {
    d->cursor++;
  }
  if (d->cursor >= d->src_len) {
    return k_ra8_err_protocol_error;
  }
  uint8_t m = d->src[d->cursor];
  d->cursor++;
  uint16_t mk = (uint16_t)(k_jpeg_marker_ff00 | m);
 
  if (mk == (uint16_t)k_ra8_jpeg_marker_sof0) {
    ra8_err_t e = priv_jpeg_sw_parse_sof0(d);
    if (e != k_ra8_ok) {
      return e;
    }
    *got_sof = true;
    return k_ra8_ok;
  }
  if (mk >= k_jpeg_marker_sof1 && mk <= k_jpeg_marker_sof_hi &&
      mk != (uint16_t)k_ra8_jpeg_marker_dht && mk != k_jpeg_marker_jpg) {
    return k_ra8_err_not_supported;
  }
  return internal_dec_dispatch_tail(d, mk, *got_sof, action);
}

RA8_INTERNAL static ra8_err_t internal_dec_run(ra8_jpeg_dec_ctx_t* d,
                                               uint8_t*            out_buf,
                                               uint32_t            out_buf_len,
                                               uint16_t*           out_w,
                                               uint16_t*           out_h)
{
  bool got_sof = false;
  while (d->cursor < d->src_len) {
    ra8_jpeg_dec_marker_action_t action = k_ra8_jpeg_dec_continue;
    ra8_err_t                    e      = priv_jpeg_sw_dispatch(d, &got_sof, &action);
    if (e != k_ra8_ok) {
      return e;
    }
    if (action == k_ra8_jpeg_dec_scan) {
      *out_w = d->width;
      *out_h = d->height;
      return internal_dec_decode_scan(d, out_buf, out_buf_len);
    }
    if (action == k_ra8_jpeg_dec_eoi) {
      break;
    }
  }
  return k_ra8_err_protocol_error;
}
 
ra8_err_t ra8_jpeg_sw_decode(const uint8_t* jpeg_buf,
                             uint32_t       jpeg_len,
                             uint8_t*       out_buf,
                             uint32_t       out_buf_len,
                             uint16_t*      out_w,
                             uint16_t*      out_h)
{
  RA8_CHECK_NULL_PTR(jpeg_buf, s_tag, "jpeg_buf is NULL");
  RA8_CHECK_NULL_PTR(out_buf, s_tag, "out_buf is NULL");
  RA8_CHECK_NULL_PTR(out_w, s_tag, "out_w is NULL");
  RA8_CHECK_NULL_PTR(out_h, s_tag, "out_h is NULL");
  if (jpeg_len < 4U) {
    return k_ra8_err_invalid_size;
  }
 
  /* Decoder context is large (4 Huffman tables + 2 quant tables);
   * allocate as `static` so it doesn't blow the stack budget the
   * project enforces via `-Wstack-usage`. The codec is documented
   * as not thread-safe, so the static is fine. */
  static ra8_jpeg_dec_ctx_t s_d;
  ra8_jpeg_dec_ctx_t*       d = &s_d;
  memset(d, 0, sizeof(*d));
  d->src     = jpeg_buf;
  d->src_len = jpeg_len;
 
  if (internal_read_be16(jpeg_buf) != (uint16_t)k_ra8_jpeg_marker_soi) {
    return k_ra8_err_protocol_error;
  }
  d->cursor = 2U;
 
  return internal_dec_run(d, out_buf, out_buf_len, out_w, out_h);
}