oxideav-h261 0.0.7

//! H.261 macroblock-layer decoding — §4.2.3 of ITU-T Rec. H.261.
//!
//! Per-MB decode sequence:
//! 1. **MBA** (VLC, Table 1) — absolute MB address for the first MB of a
//!    GOB; otherwise an address *difference* from the previous coded MB.
//!    MBA stuffing is discarded; GBSC is not a normal MBA entry (detected
//!    by the start-code scanner in `decoder.rs`).
//! 2. **MTYPE** (VLC, Table 2) — selects INTRA / INTER / INTER+MC /
//!    INTER+MC+FIL and tells us whether MQUANT, MVD, CBP, TCOEFF are present.
//! 3. **MQUANT** (5-bit FLC) — new quantiser if flagged.
//! 4. **MVD** — two VLCs (x then y); each decoded with the paired
//!    representative + the previous-MB predictor per §4.2.3.4. Only present
//!    for INTER+MC / INTER+MC+FIL.
//! 5. **CBP** (VLC, Table 4) — 6-bit CBP packed as `32*P1 + 16*P2 + 8*P3 +
//!    4*P4 + 2*P5 + P6`, where `Pn` is the luma block n=1..=4 or chroma
//!    n=5..=6 (Figure 10). Present when MTYPE says so.
//! 6. **Block layer** — 6 blocks transmitted in order Y0, Y1, Y2, Y3, Cb, Cr.
//!    INTRA always transmits all six. INTER transmits only the CBP-flagged
//!    ones; the rest come from the motion-compensated predictor (or zero
//!    residual when MC is not signalled).
//!
//! # Motion compensation
//!
//! H.261 MC is **integer-pel only**, with each luma component in `-15..=15`.
//! Chroma MVs are `floor(abs(luma)/2) * sign(luma)` (spec: halved, truncated
//! toward zero; see `luma_to_chroma_mv`).
//!
//! MVD is signalled as a paired differential (Table 3) — for each code the
//! decoder picks whichever paired representative brings the reconstructed MV
//! into `-15..=15`. The predictor is the previous coded MB's vector, reset
//! to zero at the start of every GOB, at MBA discontinuity (non-consecutive
//! MB address), and whenever the previous MB was not MC-coded (§4.2.3.4).
//!
//! # Loop filter (§3.2.3)
//!
//! When MTYPE carries the FIL flag, a separable 1/4-1/2-1/4 filter is
//! applied to each predicted 8x8 block before the residual is added. The
//! filter taps at block edges are replaced with `0, 1, 0` (no change).

use oxideav_core::bits::BitReader;
use oxideav_core::{Error, Result};

use crate::block::decode_inter_block;
use crate::tables::{
    decode_vlc, MbaSym, MtypeInfo, MvdSym, Prediction, CBP_TABLE, MBA_TABLE, MTYPE_TABLE, MVD_TABLE,
};

/// Reconstructed H.261 picture: three pel planes (Y, Cb, Cr), stride = MB-aligned width.
#[derive(Clone)]
pub struct Picture {
    pub width: usize,
    pub height: usize,
    pub mb_width: usize,
    pub mb_height: usize,
    pub y: Vec<u8>,
    pub cb: Vec<u8>,
    pub cr: Vec<u8>,
    pub y_stride: usize,
    pub c_stride: usize,
}

impl Picture {
    pub fn new(width: usize, height: usize) -> Self {
        let mb_w = width.div_ceil(16);
        let mb_h = height.div_ceil(16);
        let y_stride = mb_w * 16;
        let c_stride = mb_w * 8;
        Self {
            width,
            height,
            mb_width: mb_w,
            mb_height: mb_h,
            y_stride,
            c_stride,
            y: vec![0u8; y_stride * mb_h * 16],
            cb: vec![0u8; c_stride * mb_h * 8],
            cr: vec![0u8; c_stride * mb_h * 8],
        }
    }
}

/// State kept between consecutive MBs inside a GOB — the MV predictor and
/// the last MBA seen (to detect non-consecutive addresses per §4.2.3.4).
#[derive(Clone, Copy, Debug)]
pub struct MbContext {
    pub mv: (i32, i32),
    /// True iff the previous MB was MC-coded (InterMc / InterMcFil). Reset at
    /// GOB start.
    pub prev_was_mc: bool,
    /// Previous MBA within the GOB. `0` means "no previous MB yet".
    pub prev_mba: u8,
}

impl MbContext {
    pub fn reset() -> Self {
        Self {
            mv: (0, 0),
            prev_was_mc: false,
            prev_mba: 0,
        }
    }
}

/// Build a neutral-grey reference picture (Y=128, Cb=Cr=128) of the given
/// dimensions. Used as the first-picture fallback when an encoder emits
/// INTER MBs before any I-frame establishes a reference.
fn grey_reference(width: usize, height: usize) -> Picture {
    let mut p = Picture::new(width, height);
    p.y.fill(128);
    p.cb.fill(128);
    p.cr.fill(128);
    p
}

/// Chroma MV per §3.2.2: halve + truncate toward zero.
pub fn luma_to_chroma_mv(v: i32) -> i32 {
    // `/ 2` in Rust truncates toward zero for signed.
    v / 2
}

/// Fold MVD paired representative into `[-15, 15]` given the predictor.
/// Returns the chosen signed reconstructed MV.
///
/// §4.2.3.4: exactly one of `predictor + a` and `predictor + b` is in the
/// range `[-15, 15]`; we pick that one. If both are in-range (impossible
/// when `|predictor| <= 15` and `|a-b| == 32` with `a != 0`), we pick `a`.
/// Also used by the RTP MB-level fragmenter's Huffman-layer walker
/// (RFC 4587 §4.2) to track the reference MVD across packet boundaries.
pub(crate) fn reconstruct_mv(predictor: i32, sym: MvdSym) -> i32 {
    let a = predictor + sym.a as i32;
    let b = predictor + sym.b as i32;
    let in_range = |v: i32| (-15..=15).contains(&v);
    match (in_range(a), in_range(b)) {
        (true, _) => a,
        (false, true) => b,
        (false, false) => a, // shouldn't happen on well-formed streams
    }
}

/// §4.2.3.4 motion-vector predictor for the current MB's MVD.
///
/// The predictor is the previous MB's reconstructed vector `prev_mv`, except
/// that it "is regarded as zero in the following three situations":
///
/// 1. **Row start** — the MB is the first of an MB row in the GOB, i.e. its
///    MBA is 1, 12 or 23. A GOB is 11 MBs wide × 3 rows, so the rows begin at
///    MBA 1, 12 and 23; the spec lists exactly these three. MBA 1 is also
///    covered by the per-GOB context reset (`prev_mba == 0`), but MBA 12 and
///    23 must reset even when the immediately preceding MB was a *consecutive*
///    MC macroblock — which is why the absolute MBA, not just the MBA
///    difference, has to be inspected.
/// 2. **MBA discontinuity** — the MBA does not represent a difference of 1
///    (one or more skipped MBs lie between this MB and the previous one).
/// 3. **Previous MB not MC** — the previous macroblock's MTYPE was not
///    motion-compensated (tracked by `prev_was_mc`).
///
/// `prev_mba == 0` marks "no previous MB yet in this GOB"; in that state the
/// MBA-difference condition (2) already forces the zero predictor.
pub(crate) fn mvd_predictor(
    mba: u8,
    prev_mba: u8,
    prev_was_mc: bool,
    prev_mv: (i32, i32),
) -> (i32, i32) {
    let row_start = matches!(mba, 1 | 12 | 23);
    let consecutive = prev_mba != 0 && mba == prev_mba + 1;
    if !row_start && consecutive && prev_was_mc {
        prev_mv
    } else {
        (0, 0)
    }
}

/// Decode a single macroblock at MB position `(mb_col, mb_row)` within the
/// current GOB's top-left origin `(gob_x, gob_y)` (in luma pels). Updates
/// `ctx` for the next MB, and writes into `pic`.
///
/// `reference` is optional — it's `None` for the very first I-picture (in
/// which case an INTER MB is a decode error) and `Some(&prev_picture)` for
/// every subsequent picture.
#[allow(clippy::too_many_arguments)]
pub fn decode_macroblock(
    br: &mut BitReader<'_>,
    mba: u8,
    gob_x: usize,
    gob_y: usize,
    quant: &mut u32,
    ctx: &mut MbContext,
    pic: &mut Picture,
    reference: Option<&Picture>,
) -> Result<()> {
    // Figure out where this MB is in luma pels.
    let idx = (mba - 1) as usize;
    let mb_col = idx % 11;
    let mb_row = idx / 11;
    let luma_x = gob_x + mb_col * 16;
    let luma_y = gob_y + mb_row * 16;

    // MTYPE.
    let mtype: MtypeInfo = decode_vlc(br, MTYPE_TABLE)?;

    // MQUANT (if present).
    if mtype.mquant {
        let q = br.read_u32(5)?;
        if q == 0 {
            return Err(Error::invalid("h261 MB: MQUANT == 0"));
        }
        *quant = q;
    }

    // MVD (if present).
    let mut mv = (0i32, 0i32);
    if mtype.mvd {
        let pred = mvd_predictor(mba, ctx.prev_mba, ctx.prev_was_mc, ctx.mv);
        let sym_x: MvdSym = decode_vlc(br, MVD_TABLE)?;
        let sym_y: MvdSym = decode_vlc(br, MVD_TABLE)?;
        let mx = reconstruct_mv(pred.0, sym_x);
        let my = reconstruct_mv(pred.1, sym_y);
        mv = (mx, my);
    }

    // CBP — if absent, either:
    //   * INTRA: all 6 blocks coded.
    //   * INTER+MC without CBP (InterMc variant with tcoeff=false): no blocks coded.
    let cbp: u8 = if mtype.cbp {
        decode_vlc(br, CBP_TABLE)?
    } else if mtype.prediction == Prediction::Intra {
        0b111111
    } else {
        // Inter+MC with tcoeff=false: no blocks coded, just prediction.
        0
    };

    // Block order is Y1, Y2, Y3, Y4, Cb, Cr (Figure 10).
    // Per CBP formula: CBP = 32*P1 + 16*P2 + 8*P3 + 4*P4 + 2*P5 + P6.
    let block_coded = [
        (cbp >> 5) & 1 != 0, // Y1 - top-left
        (cbp >> 4) & 1 != 0, // Y2 - top-right
        (cbp >> 3) & 1 != 0, // Y3 - bottom-left
        (cbp >> 2) & 1 != 0, // Y4 - bottom-right
        (cbp >> 1) & 1 != 0, // Cb
        cbp & 1 != 0,        // Cr
    ];

    // INTRA path: each block is self-contained (INTRA DC + AC + IDCT, pel-domain).
    if mtype.prediction == Prediction::Intra {
        for i in 0..6 {
            // INTRA always codes every block irrespective of CBP flagging.
            let _ = block_coded[i];
            let mut out = [0u8; 64];
            crate::block::decode_intra_block(br, *quant, &mut out)?;
            write_block(pic, i, luma_x, luma_y, &out);
        }
        ctx.mv = (0, 0);
        ctx.prev_was_mc = false;
        ctx.prev_mba = mba;
        return Ok(());
    }

    // INTER path: build predictor, add residual. When there's no prior
    // reference we fall back to a mid-grey reference — H.261 doesn't
    // explicitly tag I vs P pictures, and some encoders emit inter MBs even
    // in the very first picture (their internal reference is initialised to
    // 128).
    let fallback_ref;
    let reference_ref: &Picture = match reference {
        Some(r) => r,
        None => {
            fallback_ref = grey_reference(pic.width, pic.height);
            &fallback_ref
        }
    };
    let reference = reference_ref;

    // Per-block MV: luma MV for Y1..Y4; chroma MV for Cb/Cr.
    let (mvx, mvy) = mv;
    let cmvx = luma_to_chroma_mv(mvx);
    let cmvy = luma_to_chroma_mv(mvy);

    for i in 0..4usize {
        // Luma block top-left (in luma pels).
        let (sub_x, sub_y) = match i {
            0 => (0, 0),
            1 => (8, 0),
            2 => (0, 8),
            3 => (8, 8),
            _ => unreachable!(),
        };
        let bx = (luma_x + sub_x) as i32;
        let by = (luma_y + sub_y) as i32;
        let mut pred = [0u8; 64];
        copy_block_integer(
            &reference.y,
            reference.y_stride,
            reference.y_stride as i32,
            (reference.y.len() / reference.y_stride) as i32,
            bx,
            by,
            mvx,
            mvy,
            &mut pred,
        );
        if mtype.filter {
            pred = apply_loop_filter(&pred);
        }
        if block_coded[i] && mtype.tcoeff {
            let mut resid = [0i32; 64];
            decode_inter_block(br, *quant, &mut resid)?;
            let mut out = [0u8; 64];
            for j in 0..64 {
                out[j] = (pred[j] as i32 + resid[j]).clamp(0, 255) as u8;
            }
            write_block(pic, i, luma_x, luma_y, &out);
        } else {
            write_block(pic, i, luma_x, luma_y, &pred);
        }
    }

    // Chroma blocks.
    for ci in 0..2usize {
        let (ref_plane, ref_stride) = if ci == 0 {
            (&reference.cb, reference.c_stride)
        } else {
            (&reference.cr, reference.c_stride)
        };
        let ref_h = (ref_plane.len() / ref_stride) as i32;
        let cx = (luma_x / 2) as i32;
        let cy = (luma_y / 2) as i32;
        let mut pred = [0u8; 64];
        copy_block_integer(
            ref_plane,
            ref_stride,
            ref_stride as i32,
            ref_h,
            cx,
            cy,
            cmvx,
            cmvy,
            &mut pred,
        );
        if mtype.filter {
            pred = apply_loop_filter(&pred);
        }
        let block_i = 4 + ci;
        if block_coded[block_i] && mtype.tcoeff {
            let mut resid = [0i32; 64];
            decode_inter_block(br, *quant, &mut resid)?;
            let mut out = [0u8; 64];
            for j in 0..64 {
                out[j] = (pred[j] as i32 + resid[j]).clamp(0, 255) as u8;
            }
            write_block(pic, block_i, luma_x, luma_y, &out);
        } else {
            write_block(pic, block_i, luma_x, luma_y, &pred);
        }
    }

    ctx.mv = mv;
    ctx.prev_was_mc = matches!(
        mtype.prediction,
        Prediction::InterMc | Prediction::InterMcFil
    );
    ctx.prev_mba = mba;
    Ok(())
}

/// Copy an 8x8 integer-pel block from `ref_plane` at luma position `(bx,by)`
/// plus `(mvx, mvy)`. Samples outside the plane are clamped to the nearest edge.
///
/// This is the §3.2.2 integer-pel motion-compensation primitive — the inner
/// loop run once per coded block of every P-macroblock. It is `pub` (like the
/// [`fdct`](crate::fdct) / [`idct`](crate::idct) primitives) so an
/// optimisation pass has a benchable baseline; the decoder calls it internally.
#[allow(clippy::too_many_arguments)]
pub fn copy_block_integer(
    ref_plane: &[u8],
    ref_stride: usize,
    ref_w: i32,
    ref_h: i32,
    bx: i32,
    by: i32,
    mvx: i32,
    mvy: i32,
    out: &mut [u8; 64],
) {
    let sx = bx + mvx;
    let sy = by + mvy;
    for j in 0..8 {
        for i in 0..8 {
            let x = (sx + i).clamp(0, ref_w - 1) as usize;
            let y = (sy + j).clamp(0, ref_h - 1) as usize;
            out[(j as usize) * 8 + i as usize] = ref_plane[y * ref_stride + x];
        }
    }
}

/// Apply the H.261 loop filter (§3.2.3) to an 8x8 block. Separable 1/4-1/2-1/4
/// filter with edge taps replaced by 0-1-0. Rounds to nearest, half-up.
///
/// This is the §3.2.3 loop-filter primitive applied to the motion-compensated
/// prediction of every filtered P-block. It is `pub` (like the
/// [`fdct`](crate::fdct) / [`idct`](crate::idct) primitives) so an optimisation
/// pass has a benchable baseline; the decoder calls it internally.
pub fn apply_loop_filter(src: &[u8; 64]) -> [u8; 64] {
    // Horizontal pass.
    let mut h = [0i32; 64];
    for j in 0..8 {
        for i in 0..8 {
            let v = if i == 0 || i == 7 {
                src[j * 8 + i] as i32
            } else {
                let a = src[j * 8 + i - 1] as i32;
                let b = src[j * 8 + i] as i32;
                let c = src[j * 8 + i + 1] as i32;
                // 1/4 a + 1/2 b + 1/4 c = (a + 2b + c) / 4; round half-up.
                (a + 2 * b + c + 2) >> 2
            };
            h[j * 8 + i] = v;
        }
    }
    // Vertical pass.
    let mut out = [0u8; 64];
    for i in 0..8 {
        for j in 0..8 {
            let v = if j == 0 || j == 7 {
                h[j * 8 + i]
            } else {
                let a = h[(j - 1) * 8 + i];
                let b = h[j * 8 + i];
                let c = h[(j + 1) * 8 + i];
                (a + 2 * b + c + 2) >> 2
            };
            out[j * 8 + i] = v.clamp(0, 255) as u8;
        }
    }
    out
}

/// Write a reconstructed 8x8 block into the picture. `block_idx`:
/// 0-3 = Y1..Y4 (arrangement per Figure 10), 4 = Cb, 5 = Cr.
fn write_block(pic: &mut Picture, block_idx: usize, luma_x: usize, luma_y: usize, out: &[u8; 64]) {
    let (plane, stride, px, py): (&mut [u8], usize, usize, usize) = match block_idx {
        0 => (pic.y.as_mut_slice(), pic.y_stride, luma_x, luma_y),
        1 => (pic.y.as_mut_slice(), pic.y_stride, luma_x + 8, luma_y),
        2 => (pic.y.as_mut_slice(), pic.y_stride, luma_x, luma_y + 8),
        3 => (pic.y.as_mut_slice(), pic.y_stride, luma_x + 8, luma_y + 8),
        4 => (pic.cb.as_mut_slice(), pic.c_stride, luma_x / 2, luma_y / 2),
        5 => (pic.cr.as_mut_slice(), pic.c_stride, luma_x / 2, luma_y / 2),
        _ => unreachable!(),
    };
    for j in 0..8 {
        for i in 0..8 {
            plane[(py + j) * stride + (px + i)] = out[j * 8 + i];
        }
    }
}

/// Decode the MBA VLC plus any stuffing codewords that precede it. Returns
/// `None` if the reader hits a start-code boundary (the caller has already
/// positioned us past the 16-bit zero prefix; from the MB scanner's
/// perspective the GOB has ended) or if the bit reader has been exhausted.
///
/// Returns `Some(mba_diff)` where `mba_diff` is the value from Table 1 (1..=33).
///
/// IMPORTANT: a start code requires at least 16 zero bits followed by the
/// 1-bit sync — i.e. ≥17 bits. If fewer than 16 bits remain there cannot be
/// a start code, but the remaining bits may still encode a valid MBA VLC
/// (the shortest is just the 1-bit `Diff(1)` code). We therefore only
/// invoke the start-code peek when at least 16 bits are available; with
/// fewer bits we go straight to the VLC decoder.
pub fn decode_mba_diff(br: &mut BitReader<'_>) -> Result<Option<u8>> {
    loop {
        let remaining = br.bits_remaining();
        if remaining == 0 {
            return Ok(None);
        }
        if remaining >= 16 {
            let peek = br.peek_u32(16)?;
            if peek == 0x0001 {
                return Ok(None);
            }
        }
        // Not a start code — decode a regular MBA VLC. If the VLC table
        // can't match (e.g. we're staring at trailing padding zeros only),
        // fall through to `Ok(None)` to terminate the GOB cleanly.
        match decode_vlc(br, MBA_TABLE) {
            Ok(MbaSym::Diff(d)) => return Ok(Some(d)),
            Ok(MbaSym::Stuffing) => continue,
            // Out-of-bits or no-match at the picture-trailer padding.
            Err(_) => return Ok(None),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn chroma_mv_truncate_toward_zero() {
        assert_eq!(luma_to_chroma_mv(0), 0);
        assert_eq!(luma_to_chroma_mv(1), 0);
        assert_eq!(luma_to_chroma_mv(2), 1);
        assert_eq!(luma_to_chroma_mv(3), 1);
        assert_eq!(luma_to_chroma_mv(-1), 0);
        assert_eq!(luma_to_chroma_mv(-2), -1);
        assert_eq!(luma_to_chroma_mv(-3), -1);
        assert_eq!(luma_to_chroma_mv(15), 7);
        assert_eq!(luma_to_chroma_mv(-15), -7);
    }

    #[test]
    fn mv_paired_selection_in_range() {
        // Predictor 10, MVD "a=-2, b=30" → 10 + -2 = 8 (in range).
        let s = MvdSym { a: -2, b: 30 };
        assert_eq!(reconstruct_mv(10, s), 8);
        // Predictor 10, MVD "a=10, b=-22" → 10+10=20 out, 10-22=-12 in → -12.
        let s = MvdSym { a: 10, b: -22 };
        assert_eq!(reconstruct_mv(10, s), -12);
    }

    #[test]
    fn mvd_predictor_uses_prev_mv_mid_row() {
        // Consecutive MC MBs inside a row (e.g. MB 6 after MB 5) carry the
        // previous vector forward as the predictor (§4.2.3.4, none of the
        // three reset conditions fire).
        assert_eq!(mvd_predictor(6, 5, true, (3, -4)), (3, -4));
    }

    #[test]
    fn mvd_predictor_resets_at_row_starts() {
        // §4.2.3.4 condition (1): MBA 1, 12, 23 reset to zero even when the
        // previous MB was a *consecutive* MC macroblock. MBA 12 (after the
        // MC MB 11) and MBA 23 (after the MC MB 22) are the cases the
        // per-GOB reset alone would miss.
        assert_eq!(mvd_predictor(1, 0, false, (9, 9)), (0, 0));
        assert_eq!(mvd_predictor(12, 11, true, (9, 9)), (0, 0));
        assert_eq!(mvd_predictor(23, 22, true, (-7, 5)), (0, 0));
        // A non-row-start consecutive MC MB at the same boundary distance
        // does carry the predictor — proving it is the absolute MBA, not the
        // difference, that drives the reset.
        assert_eq!(mvd_predictor(13, 12, true, (9, 9)), (9, 9));
    }

    #[test]
    fn mvd_predictor_resets_on_discontinuity_and_non_mc() {
        // Condition (2): MBA gap > 1 (skipped MBs) → zero predictor.
        assert_eq!(mvd_predictor(7, 5, true, (2, 2)), (0, 0));
        // Condition (3): previous MB was not MC → zero predictor.
        assert_eq!(mvd_predictor(6, 5, false, (2, 2)), (0, 0));
        // No previous MB yet in the GOB (prev_mba == 0) → zero predictor.
        assert_eq!(mvd_predictor(5, 0, true, (2, 2)), (0, 0));
    }

    #[test]
    fn loop_filter_flat_block_identity() {
        let src = [128u8; 64];
        let out = apply_loop_filter(&src);
        for &v in out.iter() {
            assert_eq!(v, 128);
        }
    }
}