diff --git a/include/daedalus_decoder.h b/include/daedalus_decoder.h index 639aefe..917fde2 100644 --- a/include/daedalus_decoder.h +++ b/include/daedalus_decoder.h @@ -89,6 +89,26 @@ struct daedalus_decoder_mb_input { * column-major within each 4x4 or 8x8 block (matches FFmpeg * convention). Caller-owned; copied during append. */ const int16_t *coeffs; /* points at exactly 384 int16_t */ + + /* Reconstructed predicted samples for this MB, planar order: + * [ 0 .. 256) — 16×16 luma, ROW-MAJOR raster (row 0 cols 0..15, + * row 1 cols 0..15, ..., row 15 cols 0..15) + * [256 .. 320) — 8×8 Cb, ROW-MAJOR raster + * [320 .. 384) — 8×8 Cr, ROW-MAJOR raster + * + * The caller (libavcodec's CPU intra-prediction kernels for Phase 1 + * I-frames; MC fallback for Phase 2 P-frames before GPU MC lands) + * populates this from neighbour samples per H.264 §8.3 / §8.4. + * `flush_frame()`'s reconstruction step is `clip255(predicted + + * idct(coeffs))` — the IDCT shader reads dst, adds the inverse + * transform, writes clipped — so a non-zero `predicted` here makes + * the output pixel a valid H.264 reconstruction; zero means + * residual-only (used by IDCT-isolation tests). + * + * NULL is legal and means "all-zero predicted samples" for this MB + * (the per-frame predicted buffer is zeroed at flush time so a NULL + * is indistinguishable from explicit zeros). */ + const uint8_t *predicted; /* NULL or exactly 384 uint8_t */ }; /* ------------------------------------------------------------------- diff --git a/src/daedalus_decoder.c b/src/daedalus_decoder.c index a48c0b2..80e3d25 100644 --- a/src/daedalus_decoder.c +++ b/src/daedalus_decoder.c @@ -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; } diff --git a/src/internal.h b/src/internal.h index 87845c7..4f96c42 100644 --- a/src/internal.h +++ b/src/internal.h @@ -62,6 +62,20 @@ struct daedalus_decoder { int16_t *coeffs; /* n_mbs * 384 */ int mbs_appended; /* per-frame count */ + /* Per-frame predicted samples, accumulated by append_mb(), consumed + * by flush_frame() as the initial dst content for the IDCT-add + * dispatch (predicted + idct → clip → final pixel). Zeroed at end + * of each flush_frame so NULL `mb->predicted` is indistinguishable + * from explicit zeros. + * + * predicted_y: width × height, row-major (stride = width) + * predicted_uv: PLANAR Cb||Cr, each (width/2) × (height/2), so + * size = width × height / 2, with Cb plane at + * offset 0 and Cr at offset (width/2)*(height/2). + * Matches scratch_uv layout in flush_frame. */ + uint8_t *predicted_y; + uint8_t *predicted_uv; + /* Output format. */ daedalus_decoder_output_format output_fmt;