marfrit/daedalus-decoder
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Stage 2 PR-a: predicted samples plumbing — caller-supplied per-MB pixels

Browse Source 
First concrete deliverable on the daedalus-decoder Stage 2 path post
the 2026-05-25 architecture re-pin (memory: dejavu / frame-major UMA).

Q2 decision: CPU intra prediction.  libavcodec's existing NEON intra
prediction kernels generate predicted samples per MB; daedalus-decoder
accepts those samples through the API and uses them as the IDCT-add
starting state.  FFmpeg's `idct_add` semantics — dst += idct(coeffs);
clip255 — fold DESIGN.md's Stage 3 reconstruction into the existing
Stage 1 IDCT dispatch for free.  No new GPU work.

API change
----------

`daedalus_decoder_mb_input` gains a `const uint8_t *predicted` field:

    predicted [  0 .. 256) — 16×16 luma, row-major raster
    predicted [256 .. 320) — 8×8  Cb,   row-major raster
    predicted [320 .. 384) — 8×8  Cr,   row-major raster

NULL is legal and equivalent to all-zero predicted samples — preserves
the existing IDCT-isolation test contract.

Internal changes
----------------

  - `daedalus_decoder` gains predicted_y (W×H) and predicted_uv (planar
    Cb||Cr, W×H/2) buffers allocated at create, zeroed at end of every
    flush_frame so NULL `mb->predicted` is indistinguishable from
    explicit zeros from one frame to the next.
  - `append_mb` splats mb->predicted into predicted_y/_uv at raster
    (mb_y*16, mb_x*16) for luma and (mb_y*8, mb_x*8) for each chroma
    component.
  - `flush_frame` replaces `calloc(scratch_y)` and `calloc(scratch_uv)`
    with `malloc + memcpy from predicted_y/_uv` — the IDCT dispatch
    then writes residual on top, clip-adding to the predicted samples
    in place.

Test
----

`test_idct_bitexact` extended:

  - Generates random predicted samples (uint8_t) per MB alongside the
    existing random coeffs.
  - Pre-fills the reference ref_y / ref_cb / ref_cr planes with those
    same predicted samples at the corresponding raster positions
    BEFORE applying ref_idct4_add / ref_idct8_add per block.
  - Compares GPU output to reference byte-for-byte.

Result on hertz (Pi 5 V3D 7.1), all three substrates:

  test_idct_bitexact 320 240 0xfeedface5a5a5a5a {cpu, qpu, auto}
    Y bytes diff:  0/76800 (0.0000%)
    Cb bytes diff: 0/19200 (0.0000%)
    Cr bytes diff: 0/19200 (0.0000%)
  BIT-EXACT PASS on all three substrates

Catches any silent drift between substrates and any predicted-samples
plumbing mistake on either the API or the dispatch side.

Followups
---------

  - Stage 2 PR-b: deblock dispatch in flush_frame.
  - Stage 2 daemon refactor (parallel, daedalus-v4l2 daemon): replace
    avcodec_send_packet/receive_frame with a libavcodec-parser-only
    path that drives daedalus_decoder_append_mb in raster order +
    flush_frame at slice boundary.
This commit is contained in:
Claude (noether)
2026-05-25 22:58:00 +02:00
parent 0b6482bc8f
commit a7a0d56ecd
4 changed files with 170 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/daedalus_decoder.c
+73 -9
View File
@@ -54,7 +54,18 @@ daedalus_decoder *daedalus_decoder_create(int width, int height)
dec->mb_descs = calloc((size_t) dec->n_mbs, sizeof(*dec->mb_descs));
dec->coeffs = calloc((size_t) dec->n_mbs * 384, sizeof(int16_t));
if (!dec->mb_descs || !dec->coeffs) {
/* Predicted-samples buffers — zero-initialised so a frame where
* every append_mb gets NULL `predicted` decodes residual-only
* (the Stage 1 scaffold contract). flush_frame zeroes these at
* end-of-frame to maintain that invariant for the next frame. */
const size_t pred_y_size = (size_t) width * (size_t) height;
const size_t pred_uv_size = pred_y_size / 2;
dec->predicted_y = calloc(1, pred_y_size);
dec->predicted_uv = calloc(1, pred_uv_size);
if (!dec->mb_descs || !dec->coeffs ||
!dec->predicted_y || !dec->predicted_uv) {
daedalus_decoder_destroy(dec);
return NULL;
}
@@ -66,6 +77,8 @@ void daedalus_decoder_destroy(daedalus_decoder *dec)
{
if (!dec)
return;
free(dec->predicted_uv);
free(dec->predicted_y);
free(dec->coeffs);
free(dec->mb_descs);
if (dec->dctx)
@@ -153,6 +166,34 @@ int daedalus_decoder_append_mb(daedalus_decoder *dec,
mb->coeffs,
384 * sizeof(int16_t));
/* Splat predicted samples into frame-scoped planes at raster
* (mb_y*16, mb_x*16) for luma, (mb_y*8, mb_x*8) for each chroma
* component. NULL → leave buffers as-is (zeroed at create + at
* end of each flush_frame); that's the zero-predictor contract. */
if (mb->predicted) {
const size_t y_stride = (size_t) dec->width;
const size_t uv_stride = (size_t) dec->width / 2;
const size_t uv_plane = uv_stride * ((size_t) dec->height / 2);
const uint8_t *p_y = mb->predicted;
const uint8_t *p_cb = mb->predicted + 256;
const uint8_t *p_cr = mb->predicted + 256 + 64;
uint8_t *dst_y = &dec->predicted_y[
(size_t) mb->mb_y * 16 * y_stride + (size_t) mb->mb_x * 16];
uint8_t *dst_cb = &dec->predicted_uv[
(size_t) mb->mb_y * 8 * uv_stride + (size_t) mb->mb_x * 8];
uint8_t *dst_cr = &dec->predicted_uv[uv_plane +
(size_t) mb->mb_y * 8 * uv_stride + (size_t) mb->mb_x * 8];
for (int r = 0; r < 16; r++)
memcpy(&dst_y[(size_t) r * y_stride], &p_y[r * 16], 16);
for (int r = 0; r < 8; r++) {
memcpy(&dst_cb[(size_t) r * uv_stride], &p_cb[r * 8], 8);
memcpy(&dst_cr[(size_t) r * uv_stride], &p_cr[r * 8], 8);
}
}
dec->mbs_appended++;
return 0;
}
@@ -174,14 +215,18 @@ int daedalus_decoder_append_mb(daedalus_decoder *dec,
* int16 (64 Cb + 64 Cr); dispatch into a planar Cb||Cr scratch
* buffer (W*H/4 each, concatenated W*H/2 total); CPU-interleave
* into the caller's NV12 UV plane post-dispatch.
* - Both dispatches use predicted=0 (the scratch buffers are
* calloc'd); the shader does clip255(predicted + idct(coeffs)).
* - Both dispatches pre-fill the scratch from the per-frame
* predicted_y / predicted_uv buffers (accumulated by append_mb's
* per-MB predicted-samples splat). The IDCT shader's
* `dst += idct(coeffs)` + clip255 then folds reconstruction into
* the IDCT pass — no separate Stage 3 dispatch needed.
*
* What's NOT done yet (follow-on Phase 1 sub-PRs):
* - Intra prediction (Stage 2a wavefront): predicted is forced to 0,
* so output pixels are residual-only and not a valid frame decode.
* Sufficient for Vulkan round-trip validation, not for bit-exact
* against FFmpeg.
* - Intra prediction: caller-driven (Q2 decision 2026-05-25, CPU
* intra-pred via FFmpeg NEON kernels). Caller writes the
* intra-predicted samples into mb_input.predicted; this dispatch
* consumes them as the IDCT-add starting state. GPU wavefront
* intra-pred (DESIGN.md Stage 2a) is no longer planned.
* - Motion compensation (Stage 2b): inter MBs not handled.
* - High-profile IDCT 8x8 (Stage 1 extension).
* - Chroma DC / luma Intra16x16 DC Hadamard pre-pass (currently we
@@ -222,9 +267,17 @@ int daedalus_decoder_flush_frame(daedalus_decoder *dec,
* transform_8x8_size_flag per MB), so we allocate worst-case for
* each and track actual counts.
*/
/* Pre-fill the dispatch scratch with the per-MB predicted samples
* accumulated by append_mb. daedalus-fourier's IDCT 4x4/8x8
* shaders implement FFmpeg `idct_add` semantics — dst += idct(coeffs)
* with clip255 — so a non-zero predicted dst becomes the
* reconstruction step (residual + predicted → clip) "for free",
* collapsing DESIGN.md's Stage 3 into Stage 1's existing dispatch. */
const size_t y_stride_int = (size_t) dec->width;
const size_t y_size = y_stride_int * (size_t) dec->height;
uint8_t *scratch_y = calloc(1, y_size);
uint8_t *scratch_y = malloc(y_size);
if (scratch_y)
memcpy(scratch_y, dec->predicted_y, y_size);
const size_t worst_4x4 = (size_t) dec->n_mbs * 16;
const size_t worst_8x8 = (size_t) dec->n_mbs * 4;
@@ -349,7 +402,9 @@ int daedalus_decoder_flush_frame(daedalus_decoder *dec,
const size_t cb_plane_size = chroma_w * chroma_h;
const size_t uv_scratch_size = 2 * cb_plane_size;
scratch_uv = calloc(1, uv_scratch_size);
scratch_uv = malloc(uv_scratch_size);
if (scratch_uv)
memcpy(scratch_uv, dec->predicted_uv, uv_scratch_size);
chroma_coeffs = malloc(n_chroma_blocks * 16 * sizeof(int16_t));
chroma_meta = malloc(n_chroma_blocks *
sizeof(daedalus_h264_block_meta));
@@ -427,6 +482,15 @@ cleanup:
free(coeffs8);
free(coeffs4);
free(scratch_y);
/* Zero the predicted-samples buffers so the next frame starts from
* the all-zero-predictor baseline; MBs whose append_mb gets NULL
* for `predicted` then decode residual-only. */
if (dec->predicted_y)
memset(dec->predicted_y, 0, (size_t) dec->width * (size_t) dec->height);
if (dec->predicted_uv)
memset(dec->predicted_uv, 0, (size_t) dec->width * (size_t) dec->height / 2);
dec->mbs_appended = 0;
return rc;
}