Skip to main content

threers_codec/h264/
compress.rs

1//! Compressed intra H.264: `I_NxN` macroblocks with CAVLC residuals.
2//!
3//! This is the replacement for the `I_PCM` path in [`super::slice`], which codes
4//! raw samples and so produces files the size of the source. Here every 4×4 luma
5//! block picks one of nine intra modes, the residual goes through the core
6//! transform and quantizer, and the coefficients are CAVLC-coded.
7//!
8//! Prediction is per 4×4 block from already-reconstructed neighbours, so the
9//! reconstruction has to happen *during* coding, in decoding order — the same
10//! constraint the HEVC path has, for the same reason.
11
12use crate::bitstream::{rbsp_trailing_bits, BitWriter};
13use crate::captions::CaptionTrack;
14use crate::h264::avcc::build_avcc;
15use crate::h264::cabac::{self, Cabac};
16use crate::h264::cavlc::{self, BlockKind, ZIGZAG4};
17use crate::h264::encoder::H264Encoder;
18use crate::h264::intra;
19use crate::h264::nal::{nal_unit_base, push_annexb, NalUnitType};
20use crate::h264::params::write_sps;
21use crate::h264::params::EntropyMode;
22use crate::h264::params::{H264Config, MB_SIZE};
23use crate::h264::pps::write_pps_deblock_control;
24use crate::h264::transform::{
25    chroma_dc_forward, chroma_dc_inverse, dequant4, fit_luma_dc_levels, forward4, inverse4,
26    luma_dc_hadamard, luma_dc_inverse, quant4,
27};
28use crate::hevc::encoder::{pad_plane, Yuv420Frame};
29use crate::mp4::H264Mp4Params;
30use crate::rate::{Quality, RateControl, Reach, PROBE_QP};
31
32/// `mb_type` for `I_NxN` in an I slice (Table 7-11).
33const MB_TYPE_I_NXN: u32 = 0;
34
35/// Position of each 4×4 luma block within the macroblock, in 4-sample units,
36/// in the order the bitstream visits them (Table 6-3): z-order over the four
37/// 8×8 quadrants, and z-order again inside each.
38const BLK_POS: [(usize, usize); 16] = [
39    (0, 0),
40    (1, 0),
41    (0, 1),
42    (1, 1),
43    (2, 0),
44    (3, 0),
45    (2, 1),
46    (3, 1),
47    (0, 2),
48    (1, 2),
49    (0, 3),
50    (1, 3),
51    (2, 2),
52    (3, 2),
53    (2, 3),
54    (3, 3),
55];
56
57/// Inverse of [`BLK_POS`]: `(x4, y4)` within a macroblock → block index.
58fn blk_index(x4: usize, y4: usize) -> usize {
59    BLK_POS
60        .iter()
61        .position(|&p| p == (x4, y4))
62        .expect("in-range")
63}
64
65/// `coded_block_pattern` code numbers for intra macroblocks (Table 9-4).
66/// Index is the CBP value; the entry is the `me(v)` code number.
67const CBP_INTRA_CODE: [u32; 48] = {
68    // Table 9-4 lists codeNum → CBP; invert it once at compile time.
69    const FROM_CODE: [usize; 48] = [
70        47, 31, 15, 0, 23, 27, 29, 30, 7, 11, 13, 14, 39, 43, 45, 46, 16, 3, 5, 10, 12, 19, 21, 26,
71        28, 35, 37, 42, 44, 1, 2, 4, 8, 17, 18, 20, 24, 6, 9, 22, 25, 32, 33, 34, 36, 40, 38, 41,
72    ];
73    let mut out = [0u32; 48];
74    let mut i = 0;
75    while i < 48 {
76        out[FROM_CODE[i]] = i as u32;
77        i += 1;
78    }
79    out
80};
81
82/// Chroma QP from luma QP (Table 8-15) with `chroma_qp_index_offset = 0`.
83fn chroma_qp(qp: i32) -> i32 {
84    const T: [i32; 22] = [
85        29, 30, 31, 32, 32, 33, 34, 34, 35, 35, 36, 36, 37, 37, 37, 38, 38, 38, 39, 39, 39, 39,
86    ];
87    let qpi = qp.clamp(0, 51);
88    if qpi < 30 {
89        qpi
90    } else {
91        T[(qpi - 30) as usize]
92    }
93}
94
95/// A reconstructed picture the decoder must reproduce.
96pub struct Reconstruction {
97    /// Luma, `coded_width * coded_height`.
98    pub y: Vec<u8>,
99    /// Cb, at half the coded size each way.
100    pub u: Vec<u8>,
101    /// Cr, laid out like `u`.
102    pub v: Vec<u8>,
103    /// Width padded up to whole macroblocks.
104    pub coded_width: u32,
105    /// Height padded up to whole macroblocks.
106    pub coded_height: u32,
107}
108
109/// Per-picture state the neighbour derivations read.
110struct Ctx {
111    /// Reconstructed planes at coded (MB-aligned) size.
112    ry: Vec<u8>,
113    ru: Vec<u8>,
114    rv: Vec<u8>,
115    cw: u32,
116    ch: u32,
117    cwc: u32,
118    chc: u32,
119    mbw: usize,
120    /// Non-zero coefficient counts per 4×4 luma block, indexed by picture 4×4
121    /// grid — this is what `nC` is derived from.
122    nnz_y: Vec<usize>,
123    /// Same for the two chroma planes, on the half-resolution 4×4 grid.
124    nnz_c: [Vec<usize>; 2],
125    /// Intra 4×4 prediction mode per luma block, for the MPM derivation.
126    /// `None` where no intra block has been coded.
127    modes: Vec<Option<u8>>,
128    /// Per-macroblock summary the CABAC context derivations read. Unused by the
129    /// CAVLC path, which needs only coefficient counts.
130    mb: Vec<MbNeighbor>,
131    /// Whether the previous macroblock in decoding order sent a non-zero
132    /// `mb_qp_delta` — the only thing that element's first bin's context asks.
133    prev_qp_delta_nonzero: bool,
134}
135
136impl Ctx {
137    /// Whether the sample at `(px, py)` is already reconstructed when coding the
138    /// block at `(bx, by)`.
139    ///
140    /// Macroblocks go in raster order and 4×4 blocks in z-order inside them, so
141    /// comparing `(macroblock index, block index)` lexicographically *is*
142    /// decoding order. This is what makes the above-right neighbour come out
143    /// right: available from the macroblock above-right, unavailable from a
144    /// later block in this one.
145    fn avail_luma(&self, px: i32, py: i32, bx: u32, by: u32) -> bool {
146        if px < 0 || py < 0 || px >= self.cw as i32 || py >= self.ch as i32 {
147            return false;
148        }
149        self.order_luma(px as u32, py as u32) < self.order_luma(bx, by)
150    }
151
152    fn order_luma(&self, px: u32, py: u32) -> (usize, usize) {
153        let (mbx, mby) = ((px / MB_SIZE) as usize, (py / MB_SIZE) as usize);
154        let (x4, y4) = (((px % MB_SIZE) / 4) as usize, ((py % MB_SIZE) / 4) as usize);
155        (mby * self.mbw + mbx, blk_index(x4, y4))
156    }
157
158    /// Chroma availability is macroblock-granular: the whole 8×8 is predicted at
159    /// once, so only whole neighbouring macroblocks matter.
160    fn avail_chroma(&self, px: i32, py: i32, mbx: usize, mby: usize) -> bool {
161        if px < 0 || py < 0 || px >= self.cwc as i32 || py >= self.chc as i32 {
162            return false;
163        }
164        let (nx, ny) = ((px as u32 / 8) as usize, (py as u32 / 8) as usize);
165        ny * self.mbw + nx < mby * self.mbw + mbx
166    }
167}
168
169/// Encode one picture as an IDR I-slice of `I_NxN` macroblocks.
170pub fn compressed_slice_rbsp(
171    cfg: &H264Config,
172    y: &[u8],
173    u: &[u8],
174    v: &[u8],
175    qp: i32,
176) -> (Vec<u8>, Reconstruction) {
177    let (cw, ch) = (cfg.coded_width, cfg.coded_height);
178    let (cwc, chc) = (cw / 2, ch / 2);
179    let mbw = (cw / MB_SIZE) as usize;
180    let mbh = (ch / MB_SIZE) as usize;
181    let mb_qp = adaptive_qp(y, cw, mbw, mbh, qp, cfg.aq_strength);
182
183    let mut w = BitWriter::new();
184    let mut header: Vec<u8> = Vec::new();
185    // ---- slice_header ----
186    w.write_ue(0); // first_mb_in_slice
187    w.write_ue(7); // slice_type 7 → I (all slices in the picture are I)
188    w.write_ue(0); // pic_parameter_set_id
189    w.write_bits(0, 4); // frame_num
190    w.write_ue(0); // idr_pic_id
191    w.flag(false); // no_output_of_prior_pics_flag
192    w.flag(false); // long_term_reference_flag
193    w.write_se(qp - 26); // slice_qp_delta (pic_init_qp_minus26 = 0)
194    if cfg.deblock {
195        w.write_ue(0); // disable_deblocking_filter_idc — filter on
196        w.write_se(0); // slice_alpha_c0_offset_div2
197        w.write_se(0); // slice_beta_offset_div2
198    } else {
199        w.write_ue(1); // disable_deblocking_filter_idc — filter off
200    }
201
202    // CABAC starts byte-aligned, and the padding is ones so a decoder that has
203    // mis-parsed the header runs into a syntax error rather than silently
204    // decoding noise (§7.3.4).
205    let mut entropy = match cfg.entropy {
206        EntropyMode::Cavlc => Entropy::Cavlc(w),
207        EntropyMode::Cabac => {
208            while !w.is_byte_aligned() {
209                w.write_bit(1); // cabac_alignment_one_bit
210            }
211            header = w.finish();
212            Entropy::Cabac(Box::new(Cabac::new(qp)))
213        }
214    };
215
216    let mut ctx = Ctx {
217        ry: vec![128; (cw * ch) as usize],
218        ru: vec![128; (cwc * chc) as usize],
219        rv: vec![128; (cwc * chc) as usize],
220        cw,
221        ch,
222        cwc,
223        chc,
224        mbw,
225        nnz_y: vec![0; (cw / 4 * (ch / 4)) as usize],
226        nnz_c: [
227            vec![0; (cwc / 4 * (chc / 4)) as usize],
228            vec![0; (cwc / 4 * (chc / 4)) as usize],
229        ],
230        modes: vec![None; (cw / 4 * (ch / 4)) as usize],
231        mb: vec![MbNeighbor::default(); mbw * mbh],
232        prev_qp_delta_nonzero: false,
233    };
234
235    let last = mbw * mbh - 1;
236    // `QP_Y,PRED` — the QP of the previous macroblock in decoding order, which
237    // is what `mb_qp_delta` is relative to (§7.4.5). It only moves when a
238    // macroblock actually sends a delta.
239    let mut qp_prev = qp;
240    // The QP a decoder ends up with per macroblock, which is what the
241    // deblocking thresholds are derived from — not the QP the encoder
242    // quantized with, since a macroblock that codes nothing sends no delta.
243    let mut decoded_qp = vec![qp; mbw * mbh];
244    for mby in 0..mbh {
245        for mbx in 0..mbw {
246            let qp_mb = mb_qp[mby * mbw + mbx];
247            let sent = encode_macroblock(
248                &mut entropy,
249                &mut ctx,
250                y,
251                u,
252                v,
253                mbx,
254                mby,
255                qp_mb,
256                chroma_qp(qp_mb),
257                qp_mb - qp_prev,
258            );
259            if sent {
260                qp_prev = qp_mb;
261            }
262            decoded_qp[mby * mbw + mbx] = qp_prev;
263            if let Entropy::Cabac(c) = &mut entropy {
264                c.terminate(u32::from(mby * mbw + mbx == last));
265            }
266        }
267    }
268
269    let rbsp = match entropy {
270        Entropy::Cavlc(mut w) => {
271            rbsp_trailing_bits(&mut w);
272            w.finish()
273        }
274        // The flush's final bit is the `rbsp_stop_one_bit`, so the slice needs
275        // no trailing bits of its own (§9.3.4.3.5).
276        Entropy::Cabac(c) => {
277            let mut out = header;
278            out.extend_from_slice(&c.finish());
279            out
280        }
281    };
282    // Intra prediction reads unfiltered samples, so the filter runs once over
283    // the finished picture rather than inside the reconstruction loop.
284    let (mut ry, mut ru, mut rv) = (ctx.ry, ctx.ru, ctx.rv);
285    if cfg.deblock {
286        crate::h264::deblock::deblock(&mut ry, &mut ru, &mut rv, cw, ch, &decoded_qp, chroma_qp);
287    }
288    (
289        rbsp,
290        Reconstruction {
291            y: ry,
292            u: ru,
293            v: rv,
294            coded_width: cw,
295            coded_height: ch,
296        },
297    )
298}
299
300/// The two intra macroblock shapes this encoder can emit.
301///
302/// `I_NxN` predicts each 4×4 block from its immediate neighbours, which suits
303/// detail. `I_16x16` predicts the whole macroblock at once and sends the sixteen
304/// block DCs through a second Hadamard, which suits flat areas and gradients:
305/// there it costs a couple of dozen bits where `I_NxN` pays sixteen mode
306/// signals plus sixteen `coeff_token`s just to say "nothing here".
307enum LumaCoding {
308    NxN(NxNLuma),
309    I16(I16Luma),
310}
311
312struct NxNLuma {
313    modes: [u8; 16],
314    /// Zig-zag scanned levels per 4×4 block, in coding order.
315    levels: [[i32; 16]; 16],
316    cbp_luma: u32,
317}
318
319struct I16Luma {
320    pred_mode: u8,
321    /// Zig-zag scanned Hadamard DC levels (`Intra16x16DCLevel`), always coded.
322    dc: [i32; 16],
323    /// The 15 AC levels of each 4×4 block, in coding order.
324    ac: [[i32; 15]; 16],
325    /// 0 or 15 — `I_16x16` codes every 8×8 or none of them.
326    cbp_luma: u32,
327}
328
329/// Chroma is predicted and coded the same way whichever luma shape wins, so it
330/// is built once and shared between the candidates.
331struct ChromaData {
332    mode: u8,
333    /// Quantized 2×2 chroma DC per plane, in the raster order the block uses.
334    dc: [[i32; 4]; 2],
335    /// 15 AC levels per 4×4 chroma block, per plane.
336    ac: [[[i32; 15]; 4]; 2],
337    cbp: u32,
338}
339
340/// A luma candidate, with the distortion it would leave behind.
341struct Candidate {
342    coding: LumaCoding,
343    ssd: u64,
344}
345
346/// The macroblock's share of the state the *next* macroblock reads, so a
347/// candidate can be built into `ctx`, measured, and then undone.
348struct LumaState {
349    rec: [u8; 256],
350    nnz: [usize; 16],
351    modes: [Option<u8>; 16],
352}
353
354#[allow(clippy::too_many_arguments)]
355fn encode_macroblock(
356    w: &mut Entropy,
357    ctx: &mut Ctx,
358    y: &[u8],
359    u: &[u8],
360    v: &[u8],
361    mbx: usize,
362    mby: usize,
363    qp: i32,
364    qp_c: i32,
365    qp_delta: i32,
366) -> bool {
367    // Chroma first: it depends only on neighbouring macroblocks, never on this
368    // one's luma, so both candidates can be scored against the same chroma.
369    let chroma = encode_chroma(ctx, u, v, mbx, mby, qp_c);
370
371    let nxn = build_nxn(ctx, y, mbx, mby, qp);
372    let nxn_state = save_luma(ctx, mbx, mby);
373    let nxn_cost = rd_cost(
374        nxn.ssd,
375        trial_bits(w, ctx, &nxn.coding, &chroma, mbx, mby, qp_delta),
376        qp,
377    );
378
379    // `I_16x16` predicts from outside the macroblock only, so it does not care
380    // that `build_nxn` has already overwritten the inside.
381    let i16 = build_i16(ctx, y, mbx, mby, qp);
382    let i16_cost = rd_cost(
383        i16.ssd,
384        trial_bits(w, ctx, &i16.coding, &chroma, mbx, mby, qp_delta),
385        qp,
386    );
387
388    let winner = if i16_cost < nxn_cost {
389        &i16.coding
390    } else {
391        restore_luma(ctx, mbx, mby, &nxn_state);
392        &nxn.coding
393    };
394    w.write_mb(ctx, winner, &chroma, mbx, mby, qp_delta);
395
396    // Record what the next macroblocks' CABAC contexts will ask about this one.
397    ctx.mb[mby * ctx.mbw + mbx] = MbNeighbor {
398        avail: true,
399        i16: matches!(winner, LumaCoding::I16(_)),
400        cbp_luma: match winner {
401            LumaCoding::NxN(l) => l.cbp_luma,
402            LumaCoding::I16(l) => l.cbp_luma,
403        },
404        cbp_chroma: chroma.cbp,
405        chroma_mode: chroma.mode,
406        dc_cbf: match winner {
407            LumaCoding::I16(l) => l.dc.iter().any(|&v| v != 0),
408            LumaCoding::NxN(_) => false,
409        },
410        chroma_dc_cbf: [
411            chroma.dc[0].iter().any(|&v| v != 0),
412            chroma.dc[1].iter().any(|&v| v != 0),
413        ],
414    };
415
416    // A macroblock with nothing to code carries no `mb_qp_delta`, so the
417    // predictor does not move past it — and neither does the reconstruction,
418    // since there is nothing to dequantize.
419    let sent = sends_qp_delta(winner, &chroma);
420    ctx.prev_qp_delta_nonzero = sent && qp_delta != 0;
421    sent
422}
423
424/// Whether this macroblock carries `mb_qp_delta` (§7.3.5).
425fn sends_qp_delta(luma: &LumaCoding, chroma: &ChromaData) -> bool {
426    match luma {
427        LumaCoding::I16(_) => true,
428        LumaCoding::NxN(l) => l.cbp_luma != 0 || chroma.cbp != 0,
429    }
430}
431
432/// Lagrangian cost. λ is the usual `0.85 · 2^((QP−12)/3)` for an SSD metric —
433/// it doubles every three QP steps, which is how fast the quantizer's own
434/// distortion grows.
435fn rd_cost(ssd: u64, bits: usize, qp: i32) -> f64 {
436    let lambda = 0.85 * (f64::from(qp - 12) / 3.0).exp2();
437    ssd as f64 + lambda * bits as f64
438}
439
440/// Exact size of the macroblock as it would be written, in bits.
441///
442/// CAVLC carries no adaptive state between macroblocks — `nC` comes from
443/// neighbour coefficient counts, which `ctx` already holds — so a trial encode
444/// is not an estimate. It is the number of bits this choice actually costs.
445#[allow(clippy::too_many_arguments)]
446fn trial_bits(
447    w: &Entropy,
448    ctx: &Ctx,
449    luma: &LumaCoding,
450    chroma: &ChromaData,
451    mbx: usize,
452    mby: usize,
453    qp_delta: i32,
454) -> usize {
455    let mut t = w.probe();
456    t.write_mb(ctx, luma, chroma, mbx, mby, qp_delta);
457    t.bit_len()
458}
459
460fn save_luma(ctx: &Ctx, mbx: usize, mby: usize) -> LumaState {
461    let (ox, oy) = (
462        (mbx * MB_SIZE as usize) as u32,
463        (mby * MB_SIZE as usize) as u32,
464    );
465    let mut rec = [0u8; 256];
466    for j in 0..16u32 {
467        let row = ((oy + j) * ctx.cw + ox) as usize;
468        let dst = (j * 16) as usize;
469        rec[dst..dst + 16].copy_from_slice(&ctx.ry[row..row + 16]);
470    }
471    let mut nnz = [0usize; 16];
472    let mut modes = [None; 16];
473    for (blk, &(bx4, by4)) in BLK_POS.iter().enumerate() {
474        let gi = grid_index(ctx.cw, ox + bx4 as u32 * 4, oy + by4 as u32 * 4);
475        nnz[blk] = ctx.nnz_y[gi];
476        modes[blk] = ctx.modes[gi];
477    }
478    LumaState { rec, nnz, modes }
479}
480
481fn restore_luma(ctx: &mut Ctx, mbx: usize, mby: usize, s: &LumaState) {
482    let (ox, oy) = (
483        (mbx * MB_SIZE as usize) as u32,
484        (mby * MB_SIZE as usize) as u32,
485    );
486    for j in 0..16u32 {
487        let row = ((oy + j) * ctx.cw + ox) as usize;
488        let src = (j * 16) as usize;
489        ctx.ry[row..row + 16].copy_from_slice(&s.rec[src..src + 16]);
490    }
491    for (blk, &(bx4, by4)) in BLK_POS.iter().enumerate() {
492        let gi = grid_index(ctx.cw, ox + bx4 as u32 * 4, oy + by4 as u32 * 4);
493        ctx.nnz_y[gi] = s.nnz[blk];
494        ctx.modes[gi] = s.modes[blk];
495    }
496}
497
498/// Build the `I_NxN` candidate, reconstructing into `ctx` as it goes — each
499/// block predicts from the one before it, so there is no other order to do it in.
500fn build_nxn(ctx: &mut Ctx, y: &[u8], mbx: usize, mby: usize, qp: i32) -> Candidate {
501    let mut l = NxNLuma {
502        modes: [intra::DC; 16],
503        levels: [[0; 16]; 16],
504        cbp_luma: 0,
505    };
506    let mut ssd = 0u64;
507
508    for (blk, &(bx4, by4)) in BLK_POS.iter().enumerate() {
509        let px = (mbx * MB_SIZE as usize + bx4 * 4) as u32;
510        let py = (mby * MB_SIZE as usize + by4 * 4) as u32;
511
512        let n = luma_neighbors(ctx, px, py);
513        let orig = gather(y, ctx.cw, px, py, 4);
514        let mode = best_luma_mode(&orig, &n);
515        let pred = intra::predict4(mode, &n);
516
517        let mut resid = [0i32; 16];
518        for i in 0..16 {
519            resid[i] = orig[i] - pred[i];
520        }
521        let levels = quant4(&forward4(&resid), qp, true);
522
523        // Reconstruct with exactly what the decoder will see.
524        let res = inverse4(&dequant4(&levels, qp));
525        let mut rec = [0i32; 16];
526        for i in 0..16 {
527            rec[i] = (pred[i] + res[i]).clamp(0, 255);
528            ssd += ((orig[i] - rec[i]) * (orig[i] - rec[i])) as u64;
529        }
530        store(&mut ctx.ry, ctx.cw, px, py, 4, &rec);
531
532        // Coefficients travel in zig-zag scan order.
533        let mut scan = [0i32; 16];
534        for (s, &r) in ZIGZAG4.iter().enumerate() {
535            scan[s] = levels[r];
536        }
537        let nnz = scan.iter().filter(|&&c| c != 0).count();
538        l.modes[blk] = mode;
539        l.levels[blk] = scan;
540        if nnz > 0 {
541            l.cbp_luma |= 1 << (blk / 4);
542        }
543
544        let gi = grid_index(ctx.cw, px, py);
545        ctx.nnz_y[gi] = nnz;
546        ctx.modes[gi] = Some(mode);
547    }
548
549    Candidate {
550        coding: LumaCoding::NxN(l),
551        ssd,
552    }
553}
554
555/// Build the `I_16x16` candidate: one prediction for all 256 samples, the
556/// sixteen block DCs through a 4×4 Hadamard, and the AC left in place.
557fn build_i16(ctx: &mut Ctx, y: &[u8], mbx: usize, mby: usize, qp: i32) -> Candidate {
558    let (ox, oy) = (
559        (mbx * MB_SIZE as usize) as u32,
560        (mby * MB_SIZE as usize) as u32,
561    );
562    let n = luma16_neighbors(ctx, mbx, mby);
563    let orig = gather(y, ctx.cw, ox, oy, 16);
564    let pred_mode = best_luma16_mode(&orig, &n);
565    let pred = intra::predict16(pred_mode, &n);
566
567    // Forward transform every 4×4 block, then lift the DCs out into a raster
568    // 4×4 of their own — block `blk` sits at row `by4`, column `bx4`.
569    let mut coeff = [[0i32; 16]; 16];
570    let mut dc = [0i32; 16];
571    for (blk, &(bx4, by4)) in BLK_POS.iter().enumerate() {
572        let mut r = [0i32; 16];
573        for j in 0..4 {
574            for i in 0..4 {
575                let k = (by4 * 4 + j) * 16 + bx4 * 4 + i;
576                r[j * 4 + i] = orig[k] - pred[k];
577            }
578        }
579        coeff[blk] = forward4(&r);
580        dc[by4 * 4 + bx4] = coeff[blk][0];
581    }
582
583    // The Hadamard scales by 4 in each direction and the decoder's inverse
584    // undoes only a quarter of that (§8.5.10 shifts by 6, not 4), so the
585    // encoder's quantizer runs two bits coarser than for AC.
586    let hdc = luma_dc_hadamard(&dc);
587    let mf = quant_mf0((qp % 6) as usize) as i64;
588    let qbits = 15 + qp / 6 + 2;
589    let f = (1i64 << qbits) / 3;
590    let mut dc_levels = [0i32; 16];
591    for k in 0..16 {
592        let l = ((hdc[k].abs() as i64) * mf + f) >> qbits;
593        dc_levels[k] = if hdc[k] < 0 { -(l as i32) } else { l as i32 };
594    }
595    fit_luma_dc_levels(&mut dc_levels, qp);
596    let dc_rec = luma_dc_inverse(&dc_levels, qp);
597
598    let mut l = I16Luma {
599        pred_mode,
600        dc: [0; 16],
601        ac: [[0; 15]; 16],
602        cbp_luma: 0,
603    };
604    for (s, &r) in ZIGZAG4.iter().enumerate() {
605        l.dc[s] = dc_levels[r];
606    }
607
608    let mut ssd = 0u64;
609    for (blk, &(bx4, by4)) in BLK_POS.iter().enumerate() {
610        let q = quant4(&coeff[blk], qp, true);
611        let mut scan = [0i32; 15];
612        for s in 1..16 {
613            scan[s - 1] = q[ZIGZAG4[s]];
614        }
615        let nnz = scan.iter().filter(|&&c| c != 0).count();
616        l.ac[blk] = scan;
617        if nnz > 0 {
618            l.cbp_luma = 15;
619        }
620
621        // Dequantized AC with the Hadamard's DC dropped in at position 0 — the
622        // DC never goes through the ordinary dequantizer.
623        let mut deq = dequant4(&q, qp);
624        deq[0] = dc_rec[by4 * 4 + bx4];
625        let res = inverse4(&deq);
626        let mut rec = [0i32; 16];
627        for j in 0..4 {
628            for i in 0..4 {
629                let k = (by4 * 4 + j) * 16 + bx4 * 4 + i;
630                rec[j * 4 + i] = (pred[k] + res[j * 4 + i]).clamp(0, 255);
631                let e = orig[k] - rec[j * 4 + i];
632                ssd += (e * e) as u64;
633            }
634        }
635        let (px, py) = (ox + bx4 as u32 * 4, oy + by4 as u32 * 4);
636        store(&mut ctx.ry, ctx.cw, px, py, 4, &rec);
637
638        let gi = grid_index(ctx.cw, px, py);
639        ctx.nnz_y[gi] = nnz;
640        // Not an `Intra_4x4` block: neighbours predicting against it must treat
641        // its mode as DC (§8.3.1.1), which is what `None` means here.
642        ctx.modes[gi] = None;
643    }
644
645    Candidate {
646        coding: LumaCoding::I16(l),
647        ssd,
648    }
649}
650
651/// Predict, transform, quantize and reconstruct both chroma planes.
652fn encode_chroma(
653    ctx: &mut Ctx,
654    u: &[u8],
655    v: &[u8],
656    mbx: usize,
657    mby: usize,
658    qp_c: i32,
659) -> ChromaData {
660    let cnb = chroma_neighbors(ctx, mbx, mby);
661    let mut d = ChromaData {
662        mode: best_chroma_mode(ctx, u, v, mbx, mby, &cnb),
663        dc: [[0; 4]; 2],
664        ac: [[[0; 15]; 4]; 2],
665        cbp: 0,
666    };
667
668    for (plane, src) in [(0usize, u), (1usize, v)] {
669        let cn = chroma_neighbors_plane(ctx, mbx, mby, plane);
670        let pred = intra::predict_chroma(d.mode, &cn);
671        let (cx, cy) = ((mbx * 8) as u32, (mby * 8) as u32);
672        let orig = gather(src, ctx.cwc, cx, cy, 8);
673
674        // Transform each 4×4, split DC from AC.
675        let mut dc = [0i32; 4];
676        let mut ac_coeff = [[0i32; 16]; 4];
677        for b in 0..4 {
678            let (sx, sy) = ((b % 2) * 4, (b / 2) * 4);
679            let mut r = [0i32; 16];
680            for j in 0..4 {
681                for i in 0..4 {
682                    let k = (sy + j) * 8 + sx + i;
683                    r[j * 4 + i] = orig[k] - pred[k];
684                }
685            }
686            let c = forward4(&r);
687            dc[b] = c[0];
688            ac_coeff[b] = c;
689        }
690
691        // DC goes through the 2×2 Hadamard; its quantizer runs one bit coarser
692        // because the Hadamard doubles the scale in each dimension.
693        let hdc = chroma_dc_forward(&dc);
694        let m = (qp_c % 6) as usize;
695        let qbits = 15 + qp_c / 6 + 1;
696        let f = (1i64 << qbits) / 3;
697        let mut dc_levels = [0i32; 4];
698        for b in 0..4 {
699            let mf = quant_mf0(m) as i64;
700            let l = ((hdc[b].abs() as i64) * mf + f) >> qbits;
701            dc_levels[b] = if hdc[b] < 0 { -(l as i32) } else { l as i32 };
702        }
703        crate::h264::transform::fit_chroma_dc_levels(&mut dc_levels, qp_c);
704        let dc_rec = chroma_dc_inverse(&dc_levels, qp_c);
705
706        let mut any_ac = false;
707        for b in 0..4 {
708            let q = quant4(&ac_coeff[b], qp_c, true);
709            let mut scan = [0i32; 15];
710            for s in 1..16 {
711                scan[s - 1] = q[ZIGZAG4[s]];
712            }
713            let nnz = scan.iter().filter(|&&c| c != 0).count();
714            d.ac[plane][b] = scan;
715            any_ac |= nnz > 0;
716
717            // Reconstruct: dequantized AC with the Hadamard DC dropped in at
718            // position 0, which is why the DC is not dequantized twice.
719            let mut deq = dequant4(&q, qp_c);
720            deq[0] = dc_rec[b];
721            let res = inverse4(&deq);
722            let (sx, sy) = ((b % 2) * 4, (b / 2) * 4);
723            let mut rec = [0i32; 16];
724            for j in 0..4 {
725                for i in 0..4 {
726                    let k = (sy + j) * 8 + sx + i;
727                    rec[j * 4 + i] = (pred[k] + res[j * 4 + i]).clamp(0, 255);
728                }
729            }
730            let rp = if plane == 0 { &mut ctx.ru } else { &mut ctx.rv };
731            store(rp, ctx.cwc, cx + sx as u32, cy + sy as u32, 4, &rec);
732
733            let gi = grid_index(ctx.cwc, cx + sx as u32, cy + sy as u32);
734            ctx.nnz_c[plane][gi] = nnz;
735        }
736
737        d.dc[plane] = dc_levels;
738        if any_ac {
739            d.cbp = 2;
740        } else if dc_levels.iter().any(|&c| c != 0) && d.cbp < 1 {
741            d.cbp = 1;
742        }
743    }
744    d
745}
746
747/// Per-macroblock quantizer offsets from local variance (adaptive quantization).
748///
749/// A flat macroblock and a busy one at the same QP do not look equally good:
750/// quantization error is far more visible against a smooth background than
751/// against texture, which masks it. Adaptive quantization spends the bits where
752/// the eye can see them — lower QP on flat areas, higher on detail.
753///
754/// The offsets are centred on the picture's own mean log-variance, so the
755/// average QP is unchanged and the file size stays roughly where it was. This
756/// redistributes bits rather than adding them, which is also what makes the
757/// change measurable: compare at matched size, on a perceptual metric.
758///
759/// `strength` is in QP steps per octave of variance. Zero disables it.
760fn adaptive_qp(y: &[u8], cw: u32, mbw: usize, mbh: usize, base: i32, strength: f32) -> Vec<i32> {
761    if strength == 0.0 {
762        return vec![base; mbw * mbh];
763    }
764    let mut energy = Vec::with_capacity(mbw * mbh);
765    for mby in 0..mbh {
766        for mbx in 0..mbw {
767            let (ox, oy) = (
768                (mbx * MB_SIZE as usize) as u32,
769                (mby * MB_SIZE as usize) as u32,
770            );
771            let (mut sum, mut sq) = (0i64, 0i64);
772            for j in 0..MB_SIZE {
773                let row = ((oy + j) * cw + ox) as usize;
774                for &p in &y[row..row + MB_SIZE as usize] {
775                    sum += i64::from(p);
776                    sq += i64::from(p) * i64::from(p);
777                }
778            }
779            let n = i64::from(MB_SIZE * MB_SIZE);
780            let var = (sq - sum * sum / n).max(0) as f32 / n as f32;
781            energy.push((var + 1.0).log2());
782        }
783    }
784    let mean = energy.iter().sum::<f32>() / energy.len() as f32;
785    energy
786        .iter()
787        .map(|e| {
788            // Clamp the swing: beyond a few QP steps the flat blocks stop
789            // improving and the busy ones start visibly falling apart.
790            let adj = (strength * (e - mean)).round().clamp(-5.0, 5.0) as i32;
791            (base + adj).clamp(0, 51)
792        })
793        .collect()
794}
795
796/// The quantizer multiplier for position (0,0) — the only one a DC block needs.
797fn quant_mf0(m: usize) -> i32 {
798    const MF0: [i32; 6] = [13107, 11916, 10082, 9362, 8192, 7282];
799    MF0[m]
800}
801
802#[allow(clippy::too_many_arguments)]
803fn write_macroblock(
804    w: &mut BitWriter,
805    ctx: &Ctx,
806    luma: &LumaCoding,
807    chroma: &ChromaData,
808    mbx: usize,
809    mby: usize,
810    qp_delta: i32,
811) {
812    match luma {
813        LumaCoding::NxN(l) => {
814            w.write_ue(MB_TYPE_I_NXN);
815            // Per-block prediction modes, each against the smaller of its two
816            // neighbours' modes (§8.3.1.1).
817            for (blk, &(bx4, by4)) in BLK_POS.iter().enumerate() {
818                let px = (mbx * MB_SIZE as usize + bx4 * 4) as u32;
819                let py = (mby * MB_SIZE as usize + by4 * 4) as u32;
820                let pred = mpm(ctx, px, py);
821                let mode = l.modes[blk];
822                if mode == pred {
823                    w.write_bit(1);
824                } else {
825                    w.write_bit(0);
826                    let rem = if mode > pred { mode - 1 } else { mode };
827                    w.write_bits(rem as u32, 3);
828                }
829            }
830            w.write_ue(chroma.mode as u32);
831            let cbp = l.cbp_luma | (chroma.cbp << 4);
832            w.write_ue(CBP_INTRA_CODE[cbp as usize]);
833            if cbp > 0 {
834                w.write_se(qp_delta);
835            }
836        }
837        LumaCoding::I16(l) => {
838            // Table 7-11 packs the prediction mode and both halves of the coded
839            // block pattern into `mb_type` itself, so no `coded_block_pattern`
840            // is sent — and `mb_qp_delta` is unconditional.
841            let mb_type =
842                1 + u32::from(l.pred_mode) + 4 * chroma.cbp + 12 * u32::from(l.cbp_luma != 0);
843            w.write_ue(mb_type);
844            w.write_ue(chroma.mode as u32);
845            w.write_se(qp_delta);
846        }
847    }
848
849    // ---- residual (§7.3.5.3) ----
850    match luma {
851        LumaCoding::NxN(l) => {
852            for i8 in 0..4usize {
853                if l.cbp_luma & (1 << i8) == 0 {
854                    continue;
855                }
856                for i4 in 0..4usize {
857                    let blk = i8 * 4 + i4;
858                    let (px, py) = blk_origin(mbx, mby, blk);
859                    let nc = luma_nc(ctx, px, py);
860                    cavlc::encode_block(w, &l.levels[blk], BlockKind::Luma4x4, nc);
861                }
862            }
863        }
864        LumaCoding::I16(l) => {
865            // The DC block is always present, and takes its `nC` from the
866            // neighbours of luma block 0 — both of which lie outside this
867            // macroblock, so this is well defined before anything else is coded.
868            let (px0, py0) = blk_origin(mbx, mby, 0);
869            cavlc::encode_block(w, &l.dc, BlockKind::Luma16x16Dc, luma_nc(ctx, px0, py0));
870            if l.cbp_luma != 0 {
871                for blk in 0..16usize {
872                    let (px, py) = blk_origin(mbx, mby, blk);
873                    let nc = luma_nc(ctx, px, py);
874                    cavlc::encode_block(w, &l.ac[blk], BlockKind::Luma16x16Ac, nc);
875                }
876            }
877        }
878    }
879    if chroma.cbp & 3 != 0 {
880        for plane in 0..2 {
881            cavlc::encode_block(w, &chroma.dc[plane], BlockKind::ChromaDc, -1);
882        }
883    }
884    if chroma.cbp & 2 != 0 {
885        for plane in 0..2 {
886            for b in 0..4usize {
887                let cx = (mbx * 8 + (b % 2) * 4) as u32;
888                let cy = (mby * 8 + (b / 2) * 4) as u32;
889                let nc = chroma_nc(ctx, plane, cx, cy);
890                cavlc::encode_block(w, &chroma.ac[plane][b], BlockKind::ChromaAc, nc);
891            }
892        }
893    }
894}
895
896/// Which entropy coder the slice is using.
897///
898/// The macroblock *decisions* — modes, transform levels, `I_NxN` versus
899/// `I_16x16` — do not depend on the entropy coder, only their cost does. So the
900/// build path is shared and only the emitter differs, and the rate-distortion
901/// comparison asks whichever one is in use what a candidate would cost.
902enum Entropy {
903    Cavlc(BitWriter),
904    Cabac(Box<Cabac>),
905}
906
907impl Entropy {
908    fn bit_len(&self) -> usize {
909        match self {
910            Entropy::Cavlc(w) => w.bit_len(),
911            Entropy::Cabac(c) => c.bit_len(),
912        }
913    }
914
915    /// A copy that starts with an empty buffer, for costing a candidate.
916    fn probe(&self) -> Entropy {
917        match self {
918            Entropy::Cavlc(_) => Entropy::Cavlc(BitWriter::new()),
919            Entropy::Cabac(c) => Entropy::Cabac(Box::new(c.probe())),
920        }
921    }
922
923    #[allow(clippy::too_many_arguments)]
924    fn write_mb(
925        &mut self,
926        ctx: &Ctx,
927        luma: &LumaCoding,
928        chroma: &ChromaData,
929        mbx: usize,
930        mby: usize,
931        qp_delta: i32,
932    ) {
933        match self {
934            Entropy::Cavlc(w) => write_macroblock(w, ctx, luma, chroma, mbx, mby, qp_delta),
935            Entropy::Cabac(c) => write_macroblock_cabac(c, ctx, luma, chroma, mbx, mby, qp_delta),
936        }
937    }
938}
939
940/// Everything the CABAC context derivations need to know about a neighbouring
941/// macroblock, gathered once (§9.3.3.1.1).
942#[derive(Clone, Copy, Default)]
943struct MbNeighbor {
944    avail: bool,
945    i16: bool,
946    cbp_luma: u32,
947    cbp_chroma: u32,
948    chroma_mode: u8,
949    /// `coded_block_flag` of the `Intra16x16DCLevel` block, if this macroblock
950    /// had one.
951    dc_cbf: bool,
952    /// `coded_block_flag` of each chroma DC block. Distinct from
953    /// `cbp_chroma != 0`, which only says the block was *present*.
954    chroma_dc_cbf: [bool; 2],
955}
956
957impl Ctx {
958    fn neighbor(&self, mbx: usize, mby: usize, dx: isize, dy: isize) -> MbNeighbor {
959        let (x, y) = (mbx as isize + dx, mby as isize + dy);
960        if x < 0 || y < 0 || x >= self.mbw as isize {
961            return MbNeighbor::default();
962        }
963        let i = y as usize * self.mbw + x as usize;
964        if i >= self.mb.len() {
965            return MbNeighbor::default();
966        }
967        self.mb[i]
968    }
969}
970
971#[allow(clippy::too_many_arguments)]
972fn write_macroblock_cabac(
973    c: &mut Cabac,
974    ctx: &Ctx,
975    luma: &LumaCoding,
976    chroma: &ChromaData,
977    mbx: usize,
978    mby: usize,
979    qp_delta: i32,
980) {
981    let a = ctx.neighbor(mbx, mby, -1, 0);
982    let b = ctx.neighbor(mbx, mby, 0, -1);
983
984    // ---- mb_type ----
985    // The bin-0 context counts neighbours that are *not* I_NxN, which on intra
986    // pictures means "neighbours that were flat enough for I_16x16".
987    let (a_not_nxn, b_not_nxn) = (a.avail && a.i16, b.avail && b.i16);
988    let cbp_luma = match luma {
989        LumaCoding::NxN(l) => l.cbp_luma,
990        LumaCoding::I16(l) => l.cbp_luma,
991    };
992    match luma {
993        LumaCoding::NxN(l) => {
994            c.mb_type_nxn(a_not_nxn, b_not_nxn);
995            for (blk, &(bx4, by4)) in BLK_POS.iter().enumerate() {
996                let px = (mbx * MB_SIZE as usize + bx4 * 4) as u32;
997                let py = (mby * MB_SIZE as usize + by4 * 4) as u32;
998                c.intra4x4_mode(l.modes[blk], mpm(ctx, px, py));
999            }
1000        }
1001        LumaCoding::I16(l) => {
1002            c.mb_type_i16(
1003                l.pred_mode,
1004                chroma.cbp,
1005                l.cbp_luma != 0,
1006                a_not_nxn,
1007                b_not_nxn,
1008            );
1009        }
1010    }
1011
1012    // ---- intra_chroma_pred_mode ----
1013    c.chroma_pred_mode(
1014        chroma.mode,
1015        a.avail && a.chroma_mode != 0,
1016        b.avail && b.chroma_mode != 0,
1017    );
1018
1019    // ---- coded_block_pattern (I_NxN only; I_16x16 packs it into mb_type) ----
1020    if matches!(luma, LumaCoding::NxN(_)) {
1021        let luma_inc = std::array::from_fn(|b8| cbp_luma_ctx_inc(ctx, mbx, mby, b8, cbp_luma));
1022        let cin0 = usize::from(a.avail && a.cbp_chroma != 0)
1023            + 2 * usize::from(b.avail && b.cbp_chroma != 0);
1024        let cin1 = usize::from(a.avail && a.cbp_chroma == 2)
1025            + 2 * usize::from(b.avail && b.cbp_chroma == 2);
1026        c.coded_block_pattern(cbp_luma, chroma.cbp, luma_inc, cin0, cin1);
1027    }
1028    if cbp_luma != 0 || chroma.cbp != 0 || matches!(luma, LumaCoding::I16(_)) {
1029        c.mb_qp_delta(qp_delta, ctx.prev_qp_delta_nonzero);
1030    }
1031
1032    // ---- residual ----
1033    match luma {
1034        LumaCoding::I16(l) => {
1035            let (px0, py0) = blk_origin(mbx, mby, 0);
1036            let dc_cbf = l.dc.iter().any(|&v| v != 0);
1037            let inc = dc_cbf_inc(ctx, mbx, mby);
1038            c.coded_block_flag(cabac::CAT_LUMA_DC, inc, dc_cbf);
1039            if dc_cbf {
1040                c.residual_block(&l.dc, cabac::CAT_LUMA_DC);
1041            }
1042            let _ = (px0, py0);
1043            if l.cbp_luma != 0 {
1044                for blk in 0..16usize {
1045                    let (px, py) = blk_origin(mbx, mby, blk);
1046                    let cbf = l.ac[blk].iter().any(|&v| v != 0);
1047                    let inc = luma_cbf_inc(ctx, px, py);
1048                    c.coded_block_flag(cabac::CAT_LUMA_AC, inc, cbf);
1049                    if cbf {
1050                        c.residual_block(&l.ac[blk], cabac::CAT_LUMA_AC);
1051                    }
1052                }
1053            }
1054        }
1055        LumaCoding::NxN(l) => {
1056            for i8 in 0..4usize {
1057                if l.cbp_luma & (1 << i8) == 0 {
1058                    continue;
1059                }
1060                for i4 in 0..4usize {
1061                    let blk = i8 * 4 + i4;
1062                    let (px, py) = blk_origin(mbx, mby, blk);
1063                    let cbf = l.levels[blk].iter().any(|&v| v != 0);
1064                    let inc = luma_cbf_inc(ctx, px, py);
1065                    c.coded_block_flag(cabac::CAT_LUMA_4X4, inc, cbf);
1066                    if cbf {
1067                        c.residual_block(&l.levels[blk], cabac::CAT_LUMA_4X4);
1068                    }
1069                }
1070            }
1071        }
1072    }
1073    if chroma.cbp & 3 != 0 {
1074        for plane in 0..2 {
1075            let cbf = chroma.dc[plane].iter().any(|&v| v != 0);
1076            let inc = chroma_dc_cbf_inc(ctx, mbx, mby, plane);
1077            c.coded_block_flag(cabac::CAT_CHROMA_DC, inc, cbf);
1078            if cbf {
1079                c.residual_block(&chroma.dc[plane], cabac::CAT_CHROMA_DC);
1080            }
1081        }
1082    }
1083    if chroma.cbp & 2 != 0 {
1084        for plane in 0..2 {
1085            for blk in 0..4usize {
1086                let cx = (mbx * 8 + (blk % 2) * 4) as u32;
1087                let cy = (mby * 8 + (blk / 2) * 4) as u32;
1088                let cbf = chroma.ac[plane][blk].iter().any(|&v| v != 0);
1089                let inc = chroma_ac_cbf_inc(ctx, plane, cx, cy, mbx, mby, chroma.cbp);
1090                c.coded_block_flag(cabac::CAT_CHROMA_AC, inc, cbf);
1091                if cbf {
1092                    c.residual_block(&chroma.ac[plane][blk], cabac::CAT_CHROMA_AC);
1093                }
1094            }
1095        }
1096    }
1097}
1098
1099/// `ctxIdxInc` for `coded_block_pattern`'s luma bins (§9.3.3.1.1.4).
1100///
1101/// The sense is inverted: a neighbouring 8×8 that *has* coefficients scores
1102/// zero, and so does one that does not exist. Only a neighbour that exists and
1103/// is empty pushes the context towards "this one is probably empty too".
1104fn cbp_luma_ctx_inc(ctx: &Ctx, mbx: usize, mby: usize, b8: usize, cbp_here: u32) -> usize {
1105    // The 8×8 to the left and above, which for the odd/lower blocks lie inside
1106    // this macroblock and are therefore already decided.
1107    let left = if b8 % 2 == 1 {
1108        Some((cbp_here, b8 - 1))
1109    } else {
1110        let n = ctx.neighbor(mbx, mby, -1, 0);
1111        n.avail.then_some((n.cbp_luma, b8 + 1))
1112    };
1113    let above = if b8 >= 2 {
1114        Some((cbp_here, b8 - 2))
1115    } else {
1116        let n = ctx.neighbor(mbx, mby, 0, -1);
1117        n.avail.then_some((n.cbp_luma, b8 + 2))
1118    };
1119    let flag = |v: Option<(u32, usize)>| match v {
1120        Some((cbp, idx)) => usize::from((cbp >> idx) & 1 == 0),
1121        None => 0,
1122    };
1123    flag(left) + 2 * flag(above)
1124}
1125
1126/// `ctxIdxInc` for a luma 4×4 block's `coded_block_flag` (§9.3.3.1.1.9).
1127///
1128/// An unavailable neighbour scores 1 here, not 0 — for an intra macroblock the
1129/// absence of a neighbour is read as "expect coefficients", which is the
1130/// opposite of the coded-block-pattern rule above.
1131fn luma_cbf_inc(ctx: &Ctx, px: u32, py: u32) -> usize {
1132    let f = |nx: i32, ny: i32| -> usize {
1133        if !ctx.avail_luma(nx, ny, px, py) {
1134            return 1;
1135        }
1136        usize::from(ctx.nnz_y[grid_index(ctx.cw, nx as u32, ny as u32)] > 0)
1137    };
1138    f(px as i32 - 1, py as i32) + 2 * f(px as i32, py as i32 - 1)
1139}
1140
1141/// `ctxIdxInc` for the `I_16x16` luma DC block.
1142///
1143/// The neighbouring block only exists if that macroblock was itself `I_16x16`;
1144/// against an `I_NxN` neighbour there is no DC block to consult, which scores
1145/// zero rather than the "missing neighbour" one.
1146fn dc_cbf_inc(ctx: &Ctx, mbx: usize, mby: usize) -> usize {
1147    let f = |n: MbNeighbor| -> usize {
1148        if !n.avail {
1149            return 1;
1150        }
1151        usize::from(n.i16 && n.dc_cbf)
1152    };
1153    f(ctx.neighbor(mbx, mby, -1, 0)) + 2 * f(ctx.neighbor(mbx, mby, 0, -1))
1154}
1155
1156/// `ctxIdxInc` for a chroma DC block's `coded_block_flag`.
1157///
1158/// `cbp_chroma != 0` only says the neighbour *had* a DC block; what the context
1159/// wants is whether that block actually carried coefficients. The two differ
1160/// whenever chroma AC is coded over a zero DC, which is exactly what smooth
1161/// content produces — and never what noise does, which is why a randomised
1162/// sweep passed while a gradient did not.
1163fn chroma_dc_cbf_inc(ctx: &Ctx, mbx: usize, mby: usize, plane: usize) -> usize {
1164    let f = |n: MbNeighbor| -> usize {
1165        if !n.avail {
1166            return 1;
1167        }
1168        if n.cbp_chroma == 0 {
1169            return 0; // no DC block there to consult
1170        }
1171        usize::from(n.chroma_dc_cbf[plane])
1172    };
1173    f(ctx.neighbor(mbx, mby, -1, 0)) + 2 * f(ctx.neighbor(mbx, mby, 0, -1))
1174}
1175
1176/// `ctxIdxInc` for a chroma AC block's `coded_block_flag`.
1177///
1178/// `cur_cbp_chroma` is this macroblock's own value, and it has to be passed in:
1179/// three of the four chroma blocks have a neighbour inside the *current*
1180/// macroblock, whose entry in `ctx.mb` is not written until after the whole
1181/// macroblock is emitted.
1182fn chroma_ac_cbf_inc(
1183    ctx: &Ctx,
1184    plane: usize,
1185    cx: u32,
1186    cy: u32,
1187    mbx: usize,
1188    mby: usize,
1189    cur_cbp_chroma: u32,
1190) -> usize {
1191    let f = |nx: i32, ny: i32| -> usize {
1192        if nx < 0 || ny < 0 {
1193            return 1;
1194        }
1195        let (nxu, nyu) = (nx as u32, ny as u32);
1196        if !chroma_block_done(ctx, nxu, nyu, cx, cy) {
1197            return 1;
1198        }
1199        // The block is only coded when its macroblock carries chroma AC.
1200        let (mx, my) = ((nxu / 8) as usize, (nyu / 8) as usize);
1201        let cbp = if (mx, my) == (mbx, mby) {
1202            cur_cbp_chroma
1203        } else {
1204            ctx.mb[my * ctx.mbw + mx].cbp_chroma
1205        };
1206        if cbp != 2 {
1207            return 0;
1208        }
1209        usize::from(ctx.nnz_c[plane][grid_index(ctx.cwc, nxu, nyu)] > 0)
1210    };
1211    f(cx as i32 - 1, cy as i32) + 2 * f(cx as i32, cy as i32 - 1)
1212}
1213
1214/// Picture-space origin of a macroblock's 4×4 luma block, by coding index.
1215fn blk_origin(mbx: usize, mby: usize, blk: usize) -> (u32, u32) {
1216    let (bx4, by4) = BLK_POS[blk];
1217    (
1218        (mbx * MB_SIZE as usize + bx4 * 4) as u32,
1219        (mby * MB_SIZE as usize + by4 * 4) as u32,
1220    )
1221}
1222
1223/// Reference samples along the top and left edges of a whole macroblock.
1224fn luma16_neighbors(ctx: &Ctx, mbx: usize, mby: usize) -> intra::Neighbors16 {
1225    let s = |x: i32, y: i32| ctx.ry[(y as u32 * ctx.cw + x as u32) as usize] as i32;
1226    let (xi, yi) = (
1227        (mbx * MB_SIZE as usize) as i32,
1228        (mby * MB_SIZE as usize) as i32,
1229    );
1230    let (bx, by) = (xi as u32, yi as u32);
1231    let above = (0..16)
1232        .all(|k| ctx.avail_luma(xi + k, yi - 1, bx, by))
1233        .then(|| std::array::from_fn(|k| s(xi + k as i32, yi - 1)));
1234    let left = (0..16)
1235        .all(|k| ctx.avail_luma(xi - 1, yi + k, bx, by))
1236        .then(|| std::array::from_fn(|k| s(xi - 1, yi + k as i32)));
1237    let corner = ctx
1238        .avail_luma(xi - 1, yi - 1, bx, by)
1239        .then(|| s(xi - 1, yi - 1));
1240    intra::Neighbors16 {
1241        above,
1242        left,
1243        corner,
1244    }
1245}
1246
1247/// Pick the 16×16 mode by SATD rather than SAD.
1248///
1249/// At this size the residual goes through a transform before it is coded, and
1250/// SAD cannot tell a smooth residual from a noisy one of the same magnitude —
1251/// it picks modes that cost more bits. The Hadamard is a cheap stand-in for
1252/// what the transform will actually do.
1253fn best_luma16_mode(orig: &[i32], n: &intra::Neighbors16) -> u8 {
1254    let mut best = (u64::MAX, intra::I16_DC);
1255    for mode in 0..=3u8 {
1256        if !intra::allowed16(mode, n) {
1257            continue;
1258        }
1259        let p = intra::predict16(mode, n);
1260        let mut satd = 0u64;
1261        for by in 0..4 {
1262            for bx in 0..4 {
1263                let mut blk = [0i32; 16];
1264                for j in 0..4 {
1265                    for i in 0..4 {
1266                        let k = (by * 4 + j) * 16 + bx * 4 + i;
1267                        blk[j * 4 + i] = orig[k] - p[k];
1268                    }
1269                }
1270                satd += hadamard_sad(&blk);
1271            }
1272        }
1273        if satd < best.0 {
1274            best = (satd, mode);
1275        }
1276    }
1277    best.1
1278}
1279
1280/// Sum of absolute 4×4 Hadamard coefficients, normalised back to SAD scale.
1281fn hadamard_sad(b: &[i32; 16]) -> u64 {
1282    let t = luma_dc_hadamard(b);
1283    let s: u64 = t.iter().map(|v| v.unsigned_abs() as u64).sum();
1284    s / 4
1285}
1286
1287/// Most-probable mode: the smaller of the left and above blocks' modes, DC when
1288/// either is missing (§8.3.1.1).
1289fn mpm(ctx: &Ctx, px: u32, py: u32) -> u8 {
1290    // A neighbour that exists but was coded as `I_16x16` has no 4×4 mode; the
1291    // spec substitutes DC for it, which is *not* the same as it being missing —
1292    // a missing neighbour forces the prediction to DC outright, while this one
1293    // still loses to a smaller mode on the other side.
1294    let left = ctx
1295        .avail_luma(px as i32 - 1, py as i32, px, py)
1296        .then(|| ctx.modes[grid_index(ctx.cw, px - 4, py)].unwrap_or(intra::DC));
1297    let above = ctx
1298        .avail_luma(px as i32, py as i32 - 1, px, py)
1299        .then(|| ctx.modes[grid_index(ctx.cw, px, py - 4)].unwrap_or(intra::DC));
1300    match (left, above) {
1301        (Some(a), Some(b)) => a.min(b),
1302        _ => intra::DC,
1303    }
1304}
1305
1306fn luma_nc(ctx: &Ctx, px: u32, py: u32) -> i32 {
1307    let left = ctx
1308        .avail_luma(px as i32 - 1, py as i32, px, py)
1309        .then(|| ctx.nnz_y[grid_index(ctx.cw, px - 4, py)]);
1310    let above = ctx
1311        .avail_luma(px as i32, py as i32 - 1, px, py)
1312        .then(|| ctx.nnz_y[grid_index(ctx.cw, px, py - 4)]);
1313    cavlc::derive_nc(left, above)
1314}
1315
1316fn chroma_nc(ctx: &Ctx, plane: usize, cx: u32, cy: u32) -> i32 {
1317    let inside = |x: i32, y: i32| x >= 0 && y >= 0;
1318    let left = (inside(cx as i32 - 1, cy as i32) && chroma_block_done(ctx, cx - 4, cy, cx, cy))
1319        .then(|| ctx.nnz_c[plane][grid_index(ctx.cwc, cx - 4, cy)]);
1320    let above = (inside(cx as i32, cy as i32 - 1) && chroma_block_done(ctx, cx, cy - 4, cx, cy))
1321        .then(|| ctx.nnz_c[plane][grid_index(ctx.cwc, cx, cy - 4)]);
1322    cavlc::derive_nc(left, above)
1323}
1324
1325/// Chroma 4×4 blocks are coded in raster order inside a macroblock, so ordering
1326/// is `(macroblock, raster index)`.
1327fn chroma_block_done(ctx: &Ctx, nx: u32, ny: u32, cx: u32, cy: u32) -> bool {
1328    let key = |x: u32, y: u32| {
1329        let (mx, my) = ((x / 8) as usize, (y / 8) as usize);
1330        let (bx, by) = (((x % 8) / 4) as usize, ((y % 8) / 4) as usize);
1331        (my * ctx.mbw + mx, by * 2 + bx)
1332    };
1333    key(nx, ny) < key(cx, cy)
1334}
1335
1336fn luma_neighbors(ctx: &Ctx, px: u32, py: u32) -> intra::Neighbors4 {
1337    let s = |x: i32, y: i32| ctx.ry[(y as u32 * ctx.cw + x as u32) as usize] as i32;
1338    let (xi, yi) = (px as i32, py as i32);
1339
1340    let above = (0..4)
1341        .all(|k| ctx.avail_luma(xi + k, yi - 1, px, py))
1342        .then(|| {
1343            [
1344                s(xi, yi - 1),
1345                s(xi + 1, yi - 1),
1346                s(xi + 2, yi - 1),
1347                s(xi + 3, yi - 1),
1348            ]
1349        });
1350    let above_right = (0..4)
1351        .all(|k| ctx.avail_luma(xi + 4 + k, yi - 1, px, py))
1352        .then(|| {
1353            [
1354                s(xi + 4, yi - 1),
1355                s(xi + 5, yi - 1),
1356                s(xi + 6, yi - 1),
1357                s(xi + 7, yi - 1),
1358            ]
1359        });
1360    let left = (0..4)
1361        .all(|k| ctx.avail_luma(xi - 1, yi + k, px, py))
1362        .then(|| {
1363            [
1364                s(xi - 1, yi),
1365                s(xi - 1, yi + 1),
1366                s(xi - 1, yi + 2),
1367                s(xi - 1, yi + 3),
1368            ]
1369        });
1370    let corner = ctx
1371        .avail_luma(xi - 1, yi - 1, px, py)
1372        .then(|| s(xi - 1, yi - 1));
1373    intra::Neighbors4::new(above, above_right, left, corner)
1374}
1375
1376fn chroma_neighbors_plane(ctx: &Ctx, mbx: usize, mby: usize, plane: usize) -> intra::NeighborsC {
1377    let rp: &[u8] = if plane == 0 { &ctx.ru } else { &ctx.rv };
1378    let s = |x: i32, y: i32| rp[(y as u32 * ctx.cwc + x as u32) as usize] as i32;
1379    let (xi, yi) = ((mbx * 8) as i32, (mby * 8) as i32);
1380    let above = (0..8)
1381        .all(|k| ctx.avail_chroma(xi + k, yi - 1, mbx, mby))
1382        .then(|| std::array::from_fn(|k| s(xi + k as i32, yi - 1)));
1383    let left = (0..8)
1384        .all(|k| ctx.avail_chroma(xi - 1, yi + k, mbx, mby))
1385        .then(|| std::array::from_fn(|k| s(xi - 1, yi + k as i32)));
1386    let corner = ctx
1387        .avail_chroma(xi - 1, yi - 1, mbx, mby)
1388        .then(|| s(xi - 1, yi - 1));
1389    intra::NeighborsC {
1390        above,
1391        left,
1392        corner,
1393    }
1394}
1395
1396/// A stand-in used only to choose the shared chroma mode; both planes are
1397/// scored together because the bitstream signals one mode for both.
1398fn chroma_neighbors(ctx: &Ctx, mbx: usize, mby: usize) -> intra::NeighborsC {
1399    chroma_neighbors_plane(ctx, mbx, mby, 0)
1400}
1401
1402fn best_luma_mode(orig: &[i32], n: &intra::Neighbors4) -> u8 {
1403    let mut best = (u32::MAX, intra::DC);
1404    for mode in 0..=8u8 {
1405        if !intra::allowed(mode, n) {
1406            continue;
1407        }
1408        let p = intra::predict4(mode, n);
1409        let sad: u32 = orig
1410            .iter()
1411            .zip(&p)
1412            .map(|(&o, &q)| (o - q).unsigned_abs())
1413            .sum();
1414        if sad < best.0 {
1415            best = (sad, mode);
1416        }
1417    }
1418    best.1
1419}
1420
1421fn best_chroma_mode(
1422    ctx: &Ctx,
1423    u: &[u8],
1424    v: &[u8],
1425    mbx: usize,
1426    mby: usize,
1427    _hint: &intra::NeighborsC,
1428) -> u8 {
1429    let (cx, cy) = ((mbx * 8) as u32, (mby * 8) as u32);
1430    let mut best = (u32::MAX, intra::C_DC);
1431    for mode in 0..=3u8 {
1432        let mut sad = 0u32;
1433        let mut ok = true;
1434        for (plane, src) in [(0usize, u), (1usize, v)] {
1435            let n = chroma_neighbors_plane(ctx, mbx, mby, plane);
1436            if !intra::chroma_allowed(mode, &n) {
1437                ok = false;
1438                break;
1439            }
1440            let p = intra::predict_chroma(mode, &n);
1441            let o = gather(src, ctx.cwc, cx, cy, 8);
1442            sad += o
1443                .iter()
1444                .zip(&p)
1445                .map(|(&a, &b)| (a - b).unsigned_abs())
1446                .sum::<u32>();
1447        }
1448        if ok && sad < best.0 {
1449            best = (sad, mode);
1450        }
1451    }
1452    best.1
1453}
1454
1455fn grid_index(width: u32, px: u32, py: u32) -> usize {
1456    ((py / 4) * (width / 4) + px / 4) as usize
1457}
1458
1459fn gather(plane: &[u8], w: u32, x: u32, y: u32, n: u32) -> Vec<i32> {
1460    let mut b = vec![0i32; (n * n) as usize];
1461    for yy in 0..n {
1462        for xx in 0..n {
1463            b[(yy * n + xx) as usize] = plane[((y + yy) * w + x + xx) as usize] as i32;
1464        }
1465    }
1466    b
1467}
1468
1469fn store(plane: &mut [u8], w: u32, x: u32, y: u32, n: u32, block: &[i32]) {
1470    for yy in 0..n {
1471        for xx in 0..n {
1472            plane[((y + yy) * w + x + xx) as usize] =
1473                block[(yy * n + xx) as usize].clamp(0, 255) as u8;
1474        }
1475    }
1476}
1477
1478impl CompressedEncoder {
1479    /// New encoder for `width × height` at quantization `qp` (roughly 18–40
1480    /// useful, lower is bigger and better).
1481    pub fn new(width: u32, height: u32, qp: i32) -> Self {
1482        let mut cfg = H264Config::new(width, height);
1483        cfg.qp = qp;
1484        cfg.entropy = EntropyMode::Cabac;
1485        cfg.deblock = true;
1486        cfg.aq_strength = 0.0;
1487        let sps = nal_unit_base(NalUnitType::Sps, &write_sps(&cfg));
1488        let pps = nal_unit_base(
1489            NalUnitType::Pps,
1490            &write_pps_deblock_control(cfg.entropy == EntropyMode::Cabac),
1491        );
1492        Self {
1493            cfg,
1494            qp,
1495            headers_emitted: false,
1496            sps,
1497            pps,
1498        }
1499    }
1500
1501    /// Turn the in-loop deblocking filter on or off. On by default.
1502    pub fn deblock(mut self, on: bool) -> Self {
1503        self.cfg.deblock = on;
1504        self
1505    }
1506
1507    /// Choose the entropy coder. CABAC by default; CAVLC produces a
1508    /// Baseline-profile stream, which is larger but reaches older hardware.
1509    pub fn entropy(mut self, mode: EntropyMode) -> Self {
1510        self.cfg.entropy = mode;
1511        self.sps = nal_unit_base(NalUnitType::Sps, &write_sps(&self.cfg));
1512        self.pps = nal_unit_base(
1513            NalUnitType::Pps,
1514            &write_pps_deblock_control(mode == EntropyMode::Cabac),
1515        );
1516        self
1517    }
1518
1519    /// Set the adaptive-quantization strength (see
1520    /// [`H264Config::aq_strength`]). Off by default.
1521    pub fn aq(mut self, strength: f32) -> Self {
1522        self.cfg.aq_strength = strength;
1523        self
1524    }
1525
1526    /// The configuration the parameter sets describe.
1527    pub fn config(&self) -> &H264Config {
1528        &self.cfg
1529    }
1530
1531    /// The sequence parameter set NAL unit: header included, no start code.
1532    pub fn sps(&self) -> &[u8] {
1533        &self.sps
1534    }
1535
1536    /// The picture parameter set NAL unit: header included, no start code.
1537    pub fn pps(&self) -> &[u8] {
1538        &self.pps
1539    }
1540
1541    /// Encode one 4:2:0 frame → Annex-B access unit, plus the reconstruction a
1542    /// conformant decoder must reproduce. The first call prepends SPS/PPS.
1543    pub fn encode_frame(&mut self, frame: &Yuv420Frame) -> (Vec<u8>, Reconstruction) {
1544        assert_eq!(
1545            (frame.width, frame.height),
1546            (self.cfg.width, self.cfg.height),
1547            "frame size differs from encoder size"
1548        );
1549        let (cw, ch) = (self.cfg.coded_width, self.cfg.coded_height);
1550        let y = pad_plane(&frame.y, frame.width, frame.height, cw, ch);
1551        let u = pad_plane(&frame.u, frame.width / 2, frame.height / 2, cw / 2, ch / 2);
1552        let v = pad_plane(&frame.v, frame.width / 2, frame.height / 2, cw / 2, ch / 2);
1553
1554        let (slice, recon) = compressed_slice_rbsp(&self.cfg, &y, &u, &v, self.qp);
1555        let mut au = Vec::new();
1556        if !self.headers_emitted {
1557            push_annexb(&mut au, &self.sps);
1558            push_annexb(&mut au, &self.pps);
1559            self.headers_emitted = true;
1560        }
1561        push_annexb(&mut au, &nal_unit_base(NalUnitType::Idr, &slice));
1562        (au, recon)
1563    }
1564
1565    /// One frame's slice NAL, in Annex-B form, without SPS or PPS.
1566    ///
1567    /// Takes `&self`. An all-intra stream carries nothing between frames —
1568    /// `compressed_slice_rbsp` reads the config and the pixels and nothing else
1569    /// — so frames can be encoded on separate threads and the result is
1570    /// byte-identical to encoding them in order.
1571    pub fn encode_slice_au(&self, frame: &Yuv420Frame) -> Vec<u8> {
1572        self.encode_slice_au_at(frame, self.qp)
1573    }
1574
1575    /// [`encode_slice_au`](Self::encode_slice_au) at a quantizer chosen per
1576    /// frame, which is what rate control needs.
1577    ///
1578    /// Only the slice header moves: `pic_init_qp_minus26` stays zero in the PPS
1579    /// and the frame's quantizer rides in `slice_qp_delta`, so one SPS and PPS
1580    /// serve every frame however the rate controller steers.
1581    pub fn encode_slice_au_at(&self, frame: &Yuv420Frame, qp: i32) -> Vec<u8> {
1582        let (cw, ch) = (self.cfg.coded_width, self.cfg.coded_height);
1583        let y = pad_plane(&frame.y, frame.width, frame.height, cw, ch);
1584        let u = pad_plane(&frame.u, frame.width / 2, frame.height / 2, cw / 2, ch / 2);
1585        let v = pad_plane(&frame.v, frame.width / 2, frame.height / 2, cw / 2, ch / 2);
1586        let (slice, _recon) = compressed_slice_rbsp(&self.cfg, &y, &u, &v, qp.clamp(0, 51));
1587        let mut au = Vec::new();
1588        push_annexb(&mut au, &nal_unit_base(NalUnitType::Idr, &slice));
1589        au
1590    }
1591
1592    /// The `avcC` decoder configuration for this stream, as an MP4 muxer
1593    /// (`mp4_stream::VideoConfig::avcc`) wants it.
1594    pub fn avcc(&self) -> Vec<u8> {
1595        build_avcc(&self.sps, &self.pps)
1596    }
1597
1598    /// One frame as an MP4 sample: the slice NAL, 4-byte length-prefixed,
1599    /// ready for `Mp4StreamWriter::write_video_sample` (parameter sets go in
1600    /// [`avcc`](Self::avcc), not here). Takes `&self`, like
1601    /// [`encode_slice_au`](Self::encode_slice_au), so frames can be encoded
1602    /// in parallel.
1603    pub fn encode_sample(&self, frame: &Yuv420Frame) -> Vec<u8> {
1604        self.encode_sample_at(frame, self.qp)
1605    }
1606
1607    /// [`encode_sample`](Self::encode_sample) at a quantizer chosen per frame.
1608    pub fn encode_sample_at(&self, frame: &Yuv420Frame, qp: i32) -> Vec<u8> {
1609        H264Encoder::sample_from_au(&self.encode_slice_au_at(frame, qp))
1610    }
1611}
1612
1613/// Encode `frames` as a compressed intra H.264 `.mp4` (`avc1`) at quantization
1614/// `qp`, entirely in-process — no ffmpeg, and it builds for `wasm32`.
1615///
1616/// This is the compressed counterpart to [`crate::h264::encode_mp4`],
1617/// which codes `I_PCM` and so writes raw samples at roughly 1.5 bytes per pixel
1618/// per frame. Same codec, same playback reach; two orders of magnitude smaller.
1619///
1620/// `qp` is the H.264 quantization parameter: lower is better and bigger, the
1621/// usable range is roughly 18-40, and 26 is a reasonable default.
1622pub fn encode_mp4(width: u32, height: u32, fps: u32, qp: i32, frames: &[Yuv420Frame]) -> Vec<u8> {
1623    encode_mp4_from_iter(width, height, fps, qp, None, frames.iter().cloned())
1624}
1625
1626/// [`encode_mp4`] over an iterator, so the caller can generate frames lazily and
1627/// never hold more than one — see [`crate::h264::encode_mp4_from_iter`]
1628/// for why that matters at high resolutions.
1629pub fn encode_mp4_from_iter<I>(
1630    width: u32,
1631    height: u32,
1632    fps: u32,
1633    qp: i32,
1634    captions: Option<&CaptionTrack>,
1635    frames: I,
1636) -> Vec<u8>
1637where
1638    I: IntoIterator<Item = Yuv420Frame>,
1639{
1640    let mut out = Vec::new();
1641    write_mp4_from_iter(&mut out, width, height, fps, qp, captions, frames)
1642        .expect("writing to a Vec cannot fail");
1643    out
1644}
1645
1646/// [`encode_mp4_from_iter`] written straight to a sink, so neither the clip nor
1647/// the finished file is ever held whole.
1648pub fn write_mp4_from_iter<W, I>(
1649    out: &mut W,
1650    width: u32,
1651    height: u32,
1652    fps: u32,
1653    qp: i32,
1654    captions: Option<&CaptionTrack>,
1655    frames: I,
1656) -> std::io::Result<()>
1657where
1658    W: std::io::Write,
1659    I: IntoIterator<Item = Yuv420Frame>,
1660{
1661    write_mp4_quality(
1662        out,
1663        width,
1664        height,
1665        fps,
1666        Quality::Qp(qp),
1667        captions,
1668        frames,
1669        None,
1670    )
1671}
1672
1673/// [`write_mp4_from_iter`] with a quality target rather than a fixed quantizer.
1674///
1675/// `total` is the frame count when the caller knows it, which lets average
1676/// bitrate control aim each frame at the average of what is left rather than
1677/// spreading corrections over a guessed horizon.
1678#[allow(clippy::too_many_arguments)]
1679pub fn write_mp4_quality<W, I>(
1680    out: &mut W,
1681    width: u32,
1682    height: u32,
1683    fps: u32,
1684    quality: Quality,
1685    captions: Option<&CaptionTrack>,
1686    frames: I,
1687    total: Option<u32>,
1688) -> std::io::Result<()>
1689where
1690    W: std::io::Write,
1691    I: IntoIterator<Item = Yuv420Frame>,
1692{
1693    let fps = fps.max(1);
1694    let timescale = 600u32;
1695    let base_qp = match quality {
1696        Quality::Qp(q) => q,
1697        Quality::Bitrate(_) => PROBE_QP,
1698    };
1699    let enc = CompressedEncoder::new(width, height, base_qp);
1700    let avcc = build_avcc(enc.sps(), enc.pps());
1701
1702    // Frames go out in batches so they can be encoded concurrently. Nothing
1703    // carries between them, so the batching cannot show up in the output — it
1704    // only decides how many cores are busy and how much is held at once.
1705    let mut batch = crate::frames_in_flight(width, height);
1706    let mut samples = Vec::new();
1707    let mut frames = frames.into_iter();
1708    let mut rc = match quality {
1709        Quality::Qp(_) => None,
1710        Quality::Bitrate(bps) => Some(RateControl::new(bps, fps, total)),
1711    };
1712    if let Some(r) = rc.as_ref() {
1713        // The controller only learns between groups, so a clip that fits in one
1714        // never gets to correct itself. Sized from the clip and the memory
1715        // budget alone — the cores available must not change the output.
1716        batch = r.group_size(crate::frames_by_memory(width, height));
1717    }
1718
1719    // The controller has to start somewhere. One frame coded at the probe
1720    // quantizer tells it what this content costs, which is worth far more than
1721    // any prior: content varies by orders of magnitude and quantizers do not.
1722    let mut pending: Vec<Yuv420Frame> = Vec::with_capacity(batch);
1723    // `if let (Some(r), Some(f)) = (rc.as_mut(), frames.next())` would pull a
1724    // frame whether or not there is a controller to feed it to — the tuple is
1725    // built before the pattern is tried — and a fixed-quantizer encode would
1726    // silently lose its first frame.
1727    if let Some(r) = rc.as_mut()
1728        && let Some(first) = frames.next()
1729    {
1730        let probe = enc.encode_slice_au_at(&first, PROBE_QP);
1731        r.seed(PROBE_QP, probe.len());
1732        // If the answer looks far from the probe, measure there too: one
1733        // extra frame buys a local slope instead of a chord across the
1734        // curve's bend.
1735        if let Some(q2) = r.probe_again() {
1736            let again = enc.encode_slice_au_at(&first, q2);
1737            r.seed_pair(q2, again.len());
1738        }
1739        pending.push(first);
1740    }
1741
1742    loop {
1743        while pending.len() < batch {
1744            match frames.next() {
1745                Some(f) => pending.push(f),
1746                None => break,
1747            }
1748        }
1749        if pending.is_empty() {
1750            break;
1751        }
1752        // One quantizer per batch: the controller is sequential and the encoder
1753        // is not, and a batch is small next to a clip.
1754        let qp = rc.as_ref().map_or(base_qp, |r| r.next_qp());
1755        let aus = crate::map_frames(&pending, |f| enc.encode_slice_au_at(f, qp));
1756        pending.clear();
1757        for au in &aus {
1758            if let Some(r) = rc.as_mut() {
1759                r.observe(qp, au.len());
1760            }
1761            samples.push(H264Encoder::sample_from_au(au));
1762        }
1763    }
1764    match rc.as_ref().and_then(|r| r.outcome()) {
1765        Some(Reach::TooComplex { times }) => eprintln!(
1766            "threers: this content will not fit that bitrate — even at the coarsest \
1767             quantizer it is about {times:.1}x larger. The file is as small as the \
1768             encoder can make it."
1769        ),
1770        Some(Reach::TooSimple { times }) => eprintln!(
1771            "threers: this content cannot fill that bitrate — even losslessly quantized \
1772             it is about {times:.1}x smaller, so the file is smaller than asked for. \
1773             That is the content, not a failure."
1774        ),
1775        None => {}
1776    }
1777    let params = H264Mp4Params {
1778        width,
1779        height,
1780        timescale,
1781        frame_duration: timescale / fps,
1782        avcc_payload: &avcc,
1783        samples: &samples,
1784    };
1785    crate::mp4::write_h264(out, &params, captions.filter(|t| !t.is_empty()))
1786}
1787
1788/// A compressed intra H.264 encoder: pixels in, Annex-B out.
1789///
1790/// Every frame is an IDR whose macroblocks are `I_NxN` or `I_16x16`, whichever
1791/// costs less. This is the counterpart to
1792/// [`super::encoder::H264Encoder`], which codes `I_PCM` and so does not
1793/// compress at all.
1794pub struct CompressedEncoder {
1795    cfg: H264Config,
1796    qp: i32,
1797    headers_emitted: bool,
1798    sps: Vec<u8>,
1799    pps: Vec<u8>,
1800}
1801
1802#[cfg(test)]
1803mod tests {
1804    use super::*;
1805
1806    #[test]
1807    fn encode_sample_is_the_length_prefixed_slice() {
1808        let frame = Yuv420Frame::from_rgba(32, 16, &vec![90u8; 32 * 16 * 4]);
1809        let enc = CompressedEncoder::new(32, 16, 30);
1810        assert_eq!(
1811            enc.encode_sample(&frame),
1812            H264Encoder::sample_from_au(&enc.encode_slice_au(&frame))
1813        );
1814        assert_eq!(enc.avcc(), build_avcc(enc.sps(), enc.pps()));
1815    }
1816
1817    /// Table 9-4 maps code numbers onto CBP values one-to-one; the inverse this
1818    /// module builds must therefore be a permutation of 0..48.
1819    #[test]
1820    fn cbp_table_is_a_permutation() {
1821        let mut seen = [false; 48];
1822        for &c in CBP_INTRA_CODE.iter() {
1823            assert!(c < 48, "code number {c} out of range");
1824            assert!(!seen[c as usize], "code number {c} used twice");
1825            seen[c as usize] = true;
1826        }
1827        assert!(seen.iter().all(|&s| s), "some code number is unused");
1828    }
1829
1830    #[test]
1831    fn block_positions_are_a_permutation() {
1832        let mut seen = [[false; 4]; 4];
1833        for &(x, y) in BLK_POS.iter() {
1834            assert!(!seen[y][x], "block position ({x},{y}) repeats");
1835            seen[y][x] = true;
1836        }
1837        assert!(seen.iter().flatten().all(|&s| s));
1838        // Spot-check the z-order: block 3 sits at (1,1), block 4 starts the next
1839        // 8x8 quadrant at (2,0).
1840        assert_eq!(BLK_POS[3], (1, 1));
1841        assert_eq!(BLK_POS[4], (2, 0));
1842        assert_eq!(blk_index(2, 0), 4);
1843    }
1844
1845    #[test]
1846    fn chroma_qp_follows_table_8_15() {
1847        assert_eq!(chroma_qp(0), 0);
1848        assert_eq!(chroma_qp(29), 29);
1849        assert_eq!(chroma_qp(30), 29);
1850        assert_eq!(chroma_qp(39), 35);
1851        assert_eq!(chroma_qp(51), 39);
1852        // Monotonic and never above the luma QP past the split.
1853        for q in 0..=51 {
1854            assert!(chroma_qp(q) <= q.max(0));
1855            if q > 0 {
1856                assert!(chroma_qp(q) >= chroma_qp(q - 1));
1857            }
1858        }
1859    }
1860}