mediaway-sw 0.1.6

//! CAVLC variable-length code tables (ITU-T H.264 Tables 9-5, 9-7, 9-8, 9-9, 9-10).
//!
//! Codewords are kept as bit-string literals (`"0"`/`"1"` characters) copied verbatim from
//! the spec tables rather than hand-converted to numeric `(code, length)` pairs — that
//! keeps the only "transcription step" a straight character-for-character copy, with the
//! bit-string -> `(u32, u8)` conversion done once by [`super::cavlc::parse_bits`] instead of
//! by hand. Data only; decode logic lives in [`super::cavlc`].
//!
//! `4:2:2`/`4:4:4`-only tables (`nC == -2`, the FLC-adjacent "for others" column of Table
//! 9-5) are out of scope — this crate decodes 4:2:0 only.
//!
//! **Provenance / verification (see `adr/0003-cavlc-i-slice-first-decode.md`):** these
//! codewords were transcribed from the spec via a permissively-licensed reference (an
//! MIT/BSD-style H.264 CAVLC encoder's literal `coeff_token`/`total_zeros`/`run_before`
//! table source, fetched and read for its numeric constants only — no code copied from
//! it), then spot-checked against independently-recalled known values (e.g. the FLC
//! formula for `nC >= 8`, and several `total_zeros`/`run_before` rows) before being typed
//! in here. [`ZIGZAG_4X4`] was cross-checked the same way.

#![forbid(unsafe_code)]

/// `coeff_token` VLC0 (Table 9-5, `0 <= nC < 2`): `(TotalCoeff, TrailingOnes, codeword)`.
pub(super) const COEFF_TOKEN_VLC0: &[(u8, u8, &str)] = &[
    (0, 0, "1"),
    (1, 0, "000101"),
    (1, 1, "01"),
    (2, 0, "00000111"),
    (2, 1, "000100"),
    (2, 2, "001"),
    (3, 0, "000000111"),
    (3, 1, "00000110"),
    (3, 2, "0000101"),
    (3, 3, "00011"),
    (4, 0, "0000000111"),
    (4, 1, "000000110"),
    (4, 2, "00000101"),
    (4, 3, "000011"),
    (5, 0, "00000000111"),
    (5, 1, "0000000110"),
    (5, 2, "000000101"),
    (5, 3, "0000100"),
    (6, 0, "0000000001111"),
    (6, 1, "00000000110"),
    (6, 2, "0000000101"),
    (6, 3, "00000100"),
    (7, 0, "0000000001011"),
    (7, 1, "0000000001110"),
    (7, 2, "00000000101"),
    (7, 3, "000000100"),
    (8, 0, "0000000001000"),
    (8, 1, "0000000001010"),
    (8, 2, "0000000001101"),
    (8, 3, "0000000100"),
    (9, 0, "00000000001111"),
    (9, 1, "00000000001110"),
    (9, 2, "0000000001001"),
    (9, 3, "00000000100"),
    (10, 0, "00000000001011"),
    (10, 1, "00000000001010"),
    (10, 2, "00000000001101"),
    (10, 3, "0000000001100"),
    (11, 0, "000000000001111"),
    (11, 1, "000000000001110"),
    (11, 2, "00000000001001"),
    (11, 3, "00000000001100"),
    (12, 0, "000000000001011"),
    (12, 1, "000000000001010"),
    (12, 2, "000000000001101"),
    (12, 3, "00000000001000"),
    (13, 0, "0000000000001111"),
    (13, 1, "000000000000001"),
    (13, 2, "000000000001001"),
    (13, 3, "000000000001100"),
    (14, 0, "0000000000001011"),
    (14, 1, "0000000000001110"),
    (14, 2, "0000000000001101"),
    (14, 3, "000000000001000"),
    (15, 0, "0000000000000111"),
    (15, 1, "0000000000001010"),
    (15, 2, "0000000000001001"),
    (15, 3, "0000000000001100"),
    (16, 0, "0000000000000100"),
    (16, 1, "0000000000000110"),
    (16, 2, "0000000000000101"),
    (16, 3, "0000000000001000"),
];

/// `coeff_token` VLC1 (Table 9-5, `2 <= nC < 4`).
pub(super) const COEFF_TOKEN_VLC1: &[(u8, u8, &str)] = &[
    (0, 0, "11"),
    (1, 0, "001011"),
    (1, 1, "10"),
    (2, 0, "000111"),
    (2, 1, "00111"),
    (2, 2, "011"),
    (3, 0, "0000111"),
    (3, 1, "001010"),
    (3, 2, "001001"),
    (3, 3, "0101"),
    (4, 0, "00000111"),
    (4, 1, "000110"),
    (4, 2, "000101"),
    (4, 3, "0100"),
    (5, 0, "00000100"),
    (5, 1, "0000110"),
    (5, 2, "0000101"),
    (5, 3, "00110"),
    (6, 0, "000000111"),
    (6, 1, "00000110"),
    (6, 2, "00000101"),
    (6, 3, "001000"),
    (7, 0, "00000001111"),
    (7, 1, "000000110"),
    (7, 2, "000000101"),
    (7, 3, "000100"),
    (8, 0, "00000001011"),
    (8, 1, "00000001110"),
    (8, 2, "00000001101"),
    (8, 3, "0000100"),
    (9, 0, "000000001111"),
    (9, 1, "00000001010"),
    (9, 2, "00000001001"),
    (9, 3, "000000100"),
    (10, 0, "000000001011"),
    (10, 1, "000000001110"),
    (10, 2, "000000001101"),
    (10, 3, "00000001100"),
    (11, 0, "000000001000"),
    (11, 1, "000000001010"),
    (11, 2, "000000001001"),
    (11, 3, "00000001000"),
    (12, 0, "0000000001111"),
    (12, 1, "0000000001110"),
    (12, 2, "0000000001101"),
    (12, 3, "000000001100"),
    (13, 0, "0000000001011"),
    (13, 1, "0000000001010"),
    (13, 2, "0000000001001"),
    (13, 3, "0000000001100"),
    (14, 0, "0000000000111"),
    (14, 1, "00000000001011"),
    (14, 2, "0000000000110"),
    (14, 3, "0000000001000"),
    (15, 0, "00000000001001"),
    (15, 1, "00000000001000"),
    (15, 2, "00000000001010"),
    (15, 3, "00000000000001"),
    (16, 0, "00000000000111"),
    (16, 1, "00000000000110"),
    (16, 2, "00000000000101"),
    (16, 3, "00000000000100"),
];

/// `coeff_token` VLC2 (Table 9-5, `4 <= nC < 8`).
pub(super) const COEFF_TOKEN_VLC2: &[(u8, u8, &str)] = &[
    (0, 0, "1111"),
    (1, 0, "001111"),
    (1, 1, "1110"),
    (2, 0, "001011"),
    (2, 1, "01111"),
    (2, 2, "1101"),
    (3, 0, "001000"),
    (3, 1, "01100"),
    (3, 2, "01110"),
    (3, 3, "1100"),
    (4, 0, "0001111"),
    (4, 1, "01010"),
    (4, 2, "01011"),
    (4, 3, "1011"),
    (5, 0, "0001011"),
    (5, 1, "01000"),
    (5, 2, "01001"),
    (5, 3, "1010"),
    (6, 0, "0001001"),
    (6, 1, "001110"),
    (6, 2, "001101"),
    (6, 3, "1001"),
    (7, 0, "0001000"),
    (7, 1, "001010"),
    (7, 2, "001001"),
    (7, 3, "1000"),
    (8, 0, "00001111"),
    (8, 1, "0001110"),
    (8, 2, "0001101"),
    (8, 3, "01101"),
    (9, 0, "00001011"),
    (9, 1, "00001110"),
    (9, 2, "0001010"),
    (9, 3, "001100"),
    (10, 0, "000001111"),
    (10, 1, "00001010"),
    (10, 2, "00001101"),
    (10, 3, "0001100"),
    (11, 0, "000001011"),
    (11, 1, "000001110"),
    (11, 2, "00001001"),
    (11, 3, "00001100"),
    (12, 0, "000001000"),
    (12, 1, "000001010"),
    (12, 2, "000001101"),
    (12, 3, "00001000"),
    (13, 0, "0000001101"),
    (13, 1, "000000111"),
    (13, 2, "000001001"),
    (13, 3, "000001100"),
    (14, 0, "0000001001"),
    (14, 1, "0000001100"),
    (14, 2, "0000001011"),
    (14, 3, "0000001010"),
    (15, 0, "0000000101"),
    (15, 1, "0000001000"),
    (15, 2, "0000000111"),
    (15, 3, "0000000110"),
    (16, 0, "0000000001"),
    (16, 1, "0000000100"),
    (16, 2, "0000000011"),
    (16, 3, "0000000010"),
];

/// `coeff_token` chroma DC table (Table 9-5, `nC == -1`, 4:2:0: `maxNumCoeff == 4`).
pub(super) const COEFF_TOKEN_CHROMA_DC: &[(u8, u8, &str)] = &[
    (0, 0, "01"),
    (1, 0, "000111"),
    (1, 1, "1"),
    (2, 0, "000100"),
    (2, 1, "000110"),
    (2, 2, "001"),
    (3, 0, "000011"),
    (3, 1, "0000011"),
    (3, 2, "0000010"),
    (3, 3, "000101"),
    (4, 0, "000010"),
    (4, 1, "00000011"),
    (4, 2, "00000010"),
    (4, 3, "0000000"),
];

/// `total_zeros` for 4x4 blocks (Tables 9-7/9-8, `maxNumCoeff` 15 or 16):
/// `(TotalZeros, TotalCoeff, codeword)`. `TotalCoeff == 16` is never looked up here (per
/// § 7.3.5.3.1, `total_zeros` is only present when `TotalCoeff < maxNumCoeff`).
pub(super) const TOTAL_ZEROS_4X4: &[(u8, u8, &str)] = &[
    (0, 1, "1"),
    (0, 2, "111"),
    (0, 3, "0101"),
    (0, 4, "00011"),
    (0, 5, "0101"),
    (0, 6, "000001"),
    (0, 7, "000001"),
    (0, 8, "000001"),
    (0, 9, "000001"),
    (0, 10, "00001"),
    (0, 11, "0000"),
    (0, 12, "0000"),
    (0, 13, "000"),
    (0, 14, "00"),
    (0, 15, "0"),
    (1, 1, "011"),
    (1, 2, "110"),
    (1, 3, "111"),
    (1, 4, "111"),
    (1, 5, "0100"),
    (1, 6, "00001"),
    (1, 7, "00001"),
    (1, 8, "0001"),
    (1, 9, "000000"),
    (1, 10, "00000"),
    (1, 11, "0001"),
    (1, 12, "0001"),
    (1, 13, "001"),
    (1, 14, "01"),
    (1, 15, "1"),
    (2, 1, "010"),
    (2, 2, "101"),
    (2, 3, "110"),
    (2, 4, "0101"),
    (2, 5, "0011"),
    (2, 6, "111"),
    (2, 7, "101"),
    (2, 8, "00001"),
    (2, 9, "0001"),
    (2, 10, "001"),
    (2, 11, "001"),
    (2, 12, "01"),
    (2, 13, "1"),
    (2, 14, "1"),
    (3, 1, "0011"),
    (3, 2, "100"),
    (3, 3, "101"),
    (3, 4, "0100"),
    (3, 5, "111"),
    (3, 6, "110"),
    (3, 7, "100"),
    (3, 8, "011"),
    (3, 9, "11"),
    (3, 10, "11"),
    (3, 11, "010"),
    (3, 12, "1"),
    (3, 13, "01"),
    (4, 1, "0010"),
    (4, 2, "011"),
    (4, 3, "0100"),
    (4, 4, "110"),
    (4, 5, "110"),
    (4, 6, "101"),
    (4, 7, "011"),
    (4, 8, "11"),
    (4, 9, "10"),
    (4, 10, "10"),
    (4, 11, "1"),
    (4, 12, "001"),
    (5, 1, "00011"),
    (5, 2, "0101"),
    (5, 3, "0011"),
    (5, 4, "101"),
    (5, 5, "101"),
    (5, 6, "100"),
    (5, 7, "11"),
    (5, 8, "10"),
    (5, 9, "001"),
    (5, 10, "01"),
    (5, 11, "011"),
    (6, 1, "00010"),
    (6, 2, "0100"),
    (6, 3, "100"),
    (6, 4, "100"),
    (6, 5, "100"),
    (6, 6, "011"),
    (6, 7, "010"),
    (6, 8, "010"),
    (6, 9, "01"),
    (6, 10, "0001"),
    (7, 1, "000011"),
    (7, 2, "0011"),
    (7, 3, "011"),
    (7, 4, "0011"),
    (7, 5, "011"),
    (7, 6, "010"),
    (7, 7, "0001"),
    (7, 8, "001"),
    (7, 9, "00001"),
    (8, 1, "000010"),
    (8, 2, "0010"),
    (8, 3, "0010"),
    (8, 4, "011"),
    (8, 5, "0010"),
    (8, 6, "0001"),
    (8, 7, "001"),
    (8, 8, "000000"),
    (9, 1, "0000011"),
    (9, 2, "00011"),
    (9, 3, "00011"),
    (9, 4, "0010"),
    (9, 5, "00001"),
    (9, 6, "001"),
    (9, 7, "000000"),
    (10, 1, "0000010"),
    (10, 2, "00010"),
    (10, 3, "00010"),
    (10, 4, "00010"),
    (10, 5, "0001"),
    (10, 6, "000000"),
    (11, 1, "00000011"),
    (11, 2, "000011"),
    (11, 3, "000001"),
    (11, 4, "00001"),
    (11, 5, "00000"),
    (12, 1, "00000010"),
    (12, 2, "000010"),
    (12, 3, "00001"),
    (12, 4, "00000"),
    (13, 1, "000000011"),
    (13, 2, "000001"),
    (13, 3, "000000"),
    (14, 1, "000000010"),
    (14, 2, "000000"),
    (15, 1, "000000001"),
];

/// `total_zeros` for the chroma DC 2x2 block, 4:2:0 (Table 9-9, `ChromaArrayType == 1`):
/// `(TotalZeros, TotalCoeff, codeword)`.
pub(super) const TOTAL_ZEROS_CHROMA_DC: &[(u8, u8, &str)] = &[
    (0, 1, "1"),
    (0, 2, "1"),
    (0, 3, "1"),
    (1, 1, "01"),
    (1, 2, "01"),
    (1, 3, "0"),
    (2, 1, "001"),
    (2, 2, "00"),
    (3, 1, "000"),
];

/// `run_before` (Table 9-10): `(RunBefore, zerosLeft-index (1..=6, or 7 for ">6"), codeword)`.
pub(super) const RUN_BEFORE: &[(u8, u8, &str)] = &[
    (0, 1, "1"),
    (0, 2, "1"),
    (0, 3, "11"),
    (0, 4, "11"),
    (0, 5, "11"),
    (0, 6, "11"),
    (0, 7, "111"),
    (1, 1, "0"),
    (1, 2, "01"),
    (1, 3, "10"),
    (1, 4, "10"),
    (1, 5, "10"),
    (1, 6, "000"),
    (1, 7, "110"),
    (2, 2, "00"),
    (2, 3, "01"),
    (2, 4, "01"),
    (2, 5, "011"),
    (2, 6, "001"),
    (2, 7, "101"),
    (3, 3, "00"),
    (3, 4, "001"),
    (3, 5, "010"),
    (3, 6, "011"),
    (3, 7, "100"),
    (4, 4, "000"),
    (4, 5, "001"),
    (4, 6, "010"),
    (4, 7, "011"),
    (5, 5, "000"),
    (5, 6, "101"),
    (5, 7, "010"),
    (6, 6, "100"),
    (6, 7, "001"),
    (7, 7, "0001"),
    (8, 7, "00001"),
    (9, 7, "000001"),
    (10, 7, "0000001"),
    (11, 7, "00000001"),
    (12, 7, "000000001"),
    (13, 7, "0000000001"),
    (14, 7, "00000000001"),
];

/// Inverse zig-zag scan for a 4x4 block (ITU-T H.264 § 8.5.6, Figure 8-8 scan order):
/// `ZIGZAG_4X4[k]` is the raster index (`row * 4 + col`) of the coefficient at zig-zag scan
/// position `k`. Raster positions, in scan order, form the classic
/// `0 1 5 6 / 2 4 7 12 / 3 8 11 13 / 9 10 14 15` diagram; this is that diagram's inverse
/// permutation (scan index -> raster index) since CAVLC decode produces coefficients in
/// scan order and reconstruction needs to place them into a raster 4x4 block.
pub(super) const ZIGZAG_4X4: [u8; 16] = [0, 1, 4, 8, 5, 2, 3, 6, 9, 12, 13, 10, 7, 11, 14, 15];