Skip to main content

threers_codec/decode/h264/
types.rs

1//! Per-macroblock state: what neighbours and later pictures read
2//! ([`MbInfo`]), and the parsed syntax of the macroblock being decoded
3//! ([`MbSyn`]).
4
5use std::sync::Arc;
6
7use crate::decode::jobs::Slot;
8use crate::decode::picture::Plane;
9
10#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
11pub enum MbKind {
12    #[default]
13    None,
14    I4x4,
15    I8x8,
16    I16x16,
17    IPcm,
18    P,
19    B,
20    PSkip,
21    BSkip,
22}
23
24impl MbKind {
25    #[inline]
26    pub fn is_intra(self) -> bool {
27        matches!(
28            self,
29            MbKind::I4x4 | MbKind::I8x8 | MbKind::I16x16 | MbKind::IPcm
30        )
31    }
32    #[inline]
33    pub fn is_skip(self) -> bool {
34        matches!(self, MbKind::PSkip | MbKind::BSkip)
35    }
36    /// `I_NxN`, whose prediction modes neighbours inherit.
37    #[inline]
38    pub fn is_nxn(self) -> bool {
39        matches!(self, MbKind::I4x4 | MbKind::I8x8)
40    }
41}
42
43/// What a decoded macroblock leaves behind for its neighbours, the
44/// deblocking filter, and pictures that use this one as a colocated
45/// reference. 4×4 blocks are indexed in raster order within the macroblock.
46#[derive(Clone, Copy, Debug)]
47pub struct MbInfo {
48    /// Slice number within the picture; `u32::MAX` until decoded.
49    pub slice: u32,
50    pub kind: MbKind,
51    /// `B_Skip` or `B_Direct_16x16` — CABAC context selection asks.
52    pub b_direct16: bool,
53    /// `QPY` (0 for `I_PCM`, as deblocking wants it).
54    pub qp: i8,
55    /// `QPC` for Cb and Cr, without the bit-depth offset.
56    pub qpc: [i8; 2],
57    /// Luma bits 0-3, chroma in bits 4-5 (`CodedBlockPattern`).
58    pub cbp: u8,
59    pub t8x8: bool,
60    pub chroma_mode: u8,
61    /// Intra 4×4/8×8 prediction mode per 4×4 block (8×8 modes replicated).
62    pub ipred: [u8; 16],
63    /// `TotalCoeff` per luma 4×4 block (CAVLC `nC`; CABAC reads `!= 0`).
64    pub nnz: [u8; 16],
65    /// `TotalCoeff` of chroma AC blocks, `[Cb, Cr][raster 2×2 or 2×4]`.
66    pub nnz_c: [[u8; 8]; 2],
67    /// `coded_block_flag` of DC blocks: bit 0 luma (Intra 16×16), 1 Cb, 2 Cr.
68    pub cbf_dc: u8,
69    /// Which 4×4 blocks have coefficients, for deblocking (spread over 8×8
70    /// when the transform is 8×8).
71    pub nz_mask: u16,
72    /// 8×8 blocks whose motion came from direct prediction.
73    pub direct8: u8,
74    pub ref_idx: [[i8; 4]; 2],
75    /// Unique id of the referenced picture per 8×8 block, `-1` for none.
76    pub ref_id: [[i32; 4]; 2],
77    pub mv: [[[i16; 2]; 16]; 2],
78    /// `|mvd|` per 4×4 block, saturated — only ever compared against 32.
79    pub mvd: [[[u8; 2]; 16]; 2],
80    /// `mb_field_decoding_flag` (MBAFF field macroblock).
81    pub field: bool,
82}
83
84impl Default for MbInfo {
85    fn default() -> Self {
86        MbInfo {
87            slice: u32::MAX,
88            kind: MbKind::None,
89            b_direct16: false,
90            qp: 0,
91            qpc: [0; 2],
92            cbp: 0,
93            t8x8: false,
94            chroma_mode: 0,
95            ipred: [2; 16],
96            nnz: [0; 16],
97            nnz_c: [[0; 8]; 2],
98            cbf_dc: 0,
99            nz_mask: 0,
100            direct8: 0,
101            ref_idx: [[-1; 4]; 2],
102            ref_id: [[-1; 4]; 2],
103            mv: [[[0; 2]; 16]; 2],
104            mvd: [[[0; 2]; 16]; 2],
105            field: false,
106        }
107    }
108}
109
110/// The parsed syntax of one macroblock, before reconstruction.
111pub struct MbSyn {
112    pub kind: MbKind,
113    /// Raw `mb_type` within its slice-type table (P 0-4, B 0-22, I 0-25).
114    pub mb_type: u32,
115    pub i16_mode: u8,
116    pub prev_flag: [bool; 16],
117    pub rem: [u8; 16],
118    pub chroma_mode: u8,
119    pub sub: [u8; 4],
120    pub ref_idx: [[i8; 4]; 2],
121    /// `[list][raster 4×4] = (x, y)`, filled over each partition's area.
122    pub mvd: [[[i32; 2]; 16]; 2],
123    pub cbp: u8,
124    pub t8x8: bool,
125    pub qp_delta: i32,
126    pub pcm: Vec<u16>,
127    /// Levels per 4×4 block by `blkIdx`, raster positions within the block.
128    pub coef: [[i32; 16]; 16],
129    /// 8×8 levels per 8×8 block, raster positions.
130    pub coef8: [[i32; 64]; 4],
131    /// Intra 16×16 DC levels, raster over the 4×4 grid of blocks.
132    pub dc_luma: [i32; 16],
133    pub dc_c: [[i32; 8]; 2],
134    /// Chroma AC levels, `[Cb, Cr][blkIdx][raster]`.
135    pub ac_c: [[[i32; 16]; 8]; 2],
136    /// Luma 4×4 blocks (by `blkIdx`) with any level.
137    pub coded: u16,
138    /// 8×8 blocks with any level.
139    pub coded8: u8,
140    pub coded_c: [u8; 2],
141}
142
143impl MbSyn {
144    pub fn new() -> Self {
145        MbSyn {
146            kind: MbKind::None,
147            mb_type: 0,
148            i16_mode: 0,
149            prev_flag: [false; 16],
150            rem: [0; 16],
151            chroma_mode: 0,
152            sub: [0; 4],
153            ref_idx: [[0; 4]; 2],
154            mvd: [[[0; 2]; 16]; 2],
155            cbp: 0,
156            t8x8: false,
157            qp_delta: 0,
158            pcm: vec![0; 512],
159            coef: [[0; 16]; 16],
160            coef8: [[0; 64]; 4],
161            dc_luma: [0; 16],
162            dc_c: [[0; 8]; 2],
163            ac_c: [[[0; 16]; 8]; 2],
164            coded: 0,
165            coded8: 0,
166            coded_c: [0; 2],
167        }
168    }
169
170    /// Clear for the next macroblock. Residual arrays are cleared lazily:
171    /// only the blocks the previous macroblock wrote.
172    pub fn reset(&mut self) {
173        for b in 0..16 {
174            if self.coded & (1 << b) != 0 {
175                self.coef[b] = [0; 16];
176            }
177        }
178        for b in 0..4 {
179            if self.coded8 & (1 << b) != 0 {
180                self.coef8[b] = [0; 64];
181            }
182        }
183        self.dc_luma = [0; 16];
184        self.dc_c = [[0; 8]; 2];
185        for c in 0..2 {
186            if self.coded_c[c] != 0 {
187                self.ac_c[c] = [[0; 16]; 8];
188            }
189        }
190        self.coded = 0;
191        self.coded8 = 0;
192        self.coded_c = [0; 2];
193        self.kind = MbKind::None;
194        self.mb_type = 0;
195        self.i16_mode = 0;
196        self.prev_flag = [false; 16];
197        self.rem = [0; 16];
198        self.chroma_mode = 0;
199        self.sub = [0; 4];
200        self.ref_idx = [[0; 4]; 2];
201        self.mvd = [[[0; 2]; 16]; 2];
202        self.cbp = 0;
203        self.t8x8 = false;
204        self.qp_delta = 0;
205    }
206}
207
208impl Default for MbSyn {
209    fn default() -> Self {
210        Self::new()
211    }
212}
213
214/// Partition shape of a non-8×8 inter macroblock.
215#[derive(Clone, Copy, Debug, PartialEq, Eq)]
216pub enum Shape {
217    S16x16,
218    S16x8,
219    S8x16,
220    S8x8,
221}
222
223impl Shape {
224    /// Partitions as `(x, y, w, h)` in 4×4 units.
225    pub fn parts(self) -> &'static [(usize, usize, usize, usize)] {
226        match self {
227            Shape::S16x16 => &[(0, 0, 4, 4)],
228            Shape::S16x8 => &[(0, 0, 4, 2), (0, 2, 4, 2)],
229            Shape::S8x16 => &[(0, 0, 2, 4), (2, 0, 2, 4)],
230            Shape::S8x8 => &[(0, 0, 2, 2), (2, 0, 2, 2), (0, 2, 2, 2), (2, 2, 2, 2)],
231        }
232    }
233}
234
235/// Prediction-list use: bit 0 L0, bit 1 L1.
236pub type PredFlags = u8;
237
238/// `(shape, [pred per partition])` for a P `mb_type` 0-4.
239pub fn p_mb_layout(t: u32) -> (Shape, [PredFlags; 2]) {
240    match t {
241        0 => (Shape::S16x16, [1, 0]),
242        1 => (Shape::S16x8, [1, 1]),
243        2 => (Shape::S8x16, [1, 1]),
244        _ => (Shape::S8x8, [1, 1]),
245    }
246}
247
248/// `(shape, [pred per partition])` for a B `mb_type` 1-22.
249pub fn b_mb_layout(t: u32) -> (Shape, [PredFlags; 2]) {
250    const T: [(Shape, [u8; 2]); 21] = [
251        (Shape::S16x16, [1, 0]),
252        (Shape::S16x16, [2, 0]),
253        (Shape::S16x16, [3, 0]),
254        (Shape::S16x8, [1, 1]),
255        (Shape::S8x16, [1, 1]),
256        (Shape::S16x8, [2, 2]),
257        (Shape::S8x16, [2, 2]),
258        (Shape::S16x8, [1, 2]),
259        (Shape::S8x16, [1, 2]),
260        (Shape::S16x8, [2, 1]),
261        (Shape::S8x16, [2, 1]),
262        (Shape::S16x8, [1, 3]),
263        (Shape::S8x16, [1, 3]),
264        (Shape::S16x8, [2, 3]),
265        (Shape::S8x16, [2, 3]),
266        (Shape::S16x8, [3, 1]),
267        (Shape::S8x16, [3, 1]),
268        (Shape::S16x8, [3, 2]),
269        (Shape::S8x16, [3, 2]),
270        (Shape::S16x8, [3, 3]),
271        (Shape::S8x16, [3, 3]),
272    ];
273    if (1..=21).contains(&t) {
274        T[t as usize - 1]
275    } else {
276        (Shape::S8x8, [0, 0])
277    }
278}
279
280/// `(pred, w, h)` in 4×4 units for a P `sub_mb_type`.
281pub fn p_sub_layout(t: u8) -> (PredFlags, usize, usize) {
282    match t {
283        0 => (1, 2, 2),
284        1 => (1, 2, 1),
285        2 => (1, 1, 2),
286        _ => (1, 1, 1),
287    }
288}
289
290/// `(pred, w, h)` for a B `sub_mb_type`; pred 0 is `B_Direct_8x8`.
291pub fn b_sub_layout(t: u8) -> (PredFlags, usize, usize) {
292    match t {
293        0 => (0, 2, 2),
294        1 => (1, 2, 2),
295        2 => (2, 2, 2),
296        3 => (3, 2, 2),
297        4 => (1, 2, 1),
298        5 => (1, 1, 2),
299        6 => (2, 2, 1),
300        7 => (2, 1, 2),
301        8 => (3, 2, 1),
302        9 => (3, 1, 2),
303        10 => (1, 1, 1),
304        11 => (2, 1, 1),
305        _ => (3, 1, 1),
306    }
307}
308
309/// A frame store: a decoded frame, a complementary field pair, or a single
310/// field, with per-field reference marking.
311#[derive(Clone)]
312pub struct RefPic {
313    pub id: u32,
314    /// The whole frame (both fields interleaved).
315    pub planes: Arc<[Plane; 3]>,
316    /// Field views of `planes` (`[top, bottom]`), built on demand.
317    pub field_planes: [Option<Arc<[Plane; 3]>>; 2],
318    /// Motion of every macroblock of a frame picture — for colocated
319    /// (direct) prediction.
320    pub mbs: Arc<Vec<MbInfo>>,
321    /// Motion of each field picture, when the frame was coded as fields.
322    pub field_mbs: [Option<Arc<Vec<MbInfo>>>; 2],
323    /// `TopFieldOrderCnt`, `BottomFieldOrderCnt` (`i32::MAX` when absent).
324    pub field_poc: [i32; 2],
325    /// `PicOrderCnt` of the frame: the smaller field POC.
326    pub poc: i32,
327    pub frame_num: u32,
328    pub frame_num_wrap: i32,
329    /// Fields marked "used for short-term reference" (bit 0 top, 1 bottom).
330    pub short: u8,
331    /// Fields marked "used for long-term reference".
332    pub long: u8,
333    pub lt_idx: u32,
334    /// With threads, where `planes` and `mbs` will come from: empty until a
335    /// job resolves it.
336    pub(crate) slot: Option<Arc<Slot<RefData>>>,
337}
338
339/// A finished frame, as later ones read it.
340pub(crate) struct RefData {
341    pub planes: Arc<[Plane; 3]>,
342    pub mbs: Arc<Vec<MbInfo>>,
343}
344
345impl RefPic {
346    pub fn is_ref(&self) -> bool {
347        self.short | self.long != 0
348    }
349
350    /// The field (`parity` 0 top, 1 bottom) as its own picture: every other
351    /// row of each plane.
352    pub fn field(&mut self, parity: usize) -> Arc<[Plane; 3]> {
353        if let Some(p) = &self.field_planes[parity] {
354            return p.clone();
355        }
356        let f = |p: &Plane| {
357            let h = p.height / 2;
358            let mut out = Plane::new(p.width, h, 0);
359            for y in 0..h {
360                let src = (2 * y + parity) * p.width;
361                out.data[y * p.width..(y + 1) * p.width]
362                    .copy_from_slice(&p.data[src..src + p.width]);
363            }
364            out
365        };
366        let a = Arc::new([f(&self.planes[0]), f(&self.planes[1]), f(&self.planes[2])]);
367        self.field_planes[parity] = Some(a.clone());
368        a
369    }
370}
371
372/// One entry of a reference picture list: a frame, or one field.
373#[derive(Clone, Debug)]
374pub struct RefEntry {
375    /// Index into the decoder's reference store.
376    pub dpb: usize,
377    /// Unique per frame or field: `store id * 4 + structure` (1 top field,
378    /// 2 bottom field, 3 frame), as ffmpeg's `ref2frm`.
379    pub id: u32,
380    pub poc: i32,
381    pub long_term: bool,
382    /// 1 top field, 2 bottom field, 3 frame.
383    pub structure: u8,
384    /// The samples to predict from (a field view for fields).
385    pub planes: Arc<[Plane; 3]>,
386}