Skip to main content

threers_codec/decode/h264/
params.rs

1//! H.264 sequence and picture parameter sets and the slice header (§7.3.2,
2//! §7.3.3).
3
4use super::tables::{DEFAULT_4X4, DEFAULT_8X8, ZIGZAG4, ZIGZAG8};
5use crate::decode::bits::BitReader;
6
7pub type Result<T> = std::result::Result<T, String>;
8
9/// Scaling matrices in raster order: six 4×4 (Y/Cb/Cr intra, Y/Cb/Cr inter)
10/// and six 8×8 (same order; only the luma two exist outside 4:4:4).
11#[derive(Clone, Debug, PartialEq)]
12pub struct ScalingLists {
13    pub m4: [[u8; 16]; 6],
14    pub m8: [[u8; 64]; 6],
15}
16
17impl ScalingLists {
18    pub fn flat() -> Self {
19        ScalingLists {
20            m4: [[16; 16]; 6],
21            m8: [[16; 64]; 6],
22        }
23    }
24}
25
26/// Parse one `scaling_list()` (§7.3.2.1.1.1). Returns `None` when
27/// `useDefaultScalingMatrixFlag` is set; otherwise the list in raster order.
28fn scaling_list<const N: usize>(r: &mut BitReader, zigzag: &[usize; N]) -> Option<[u8; N]> {
29    let mut out = [0u8; N];
30    let mut last = 8i32;
31    let mut next = 8i32;
32    for j in 0..N {
33        if next != 0 {
34            let delta = r.se();
35            // Same as (last + delta + 256) % 256 for the legal −128..=127,
36            // without overflowing on garbage.
37            next = (last as i64 + delta as i64).rem_euclid(256) as i32;
38            if j == 0 && next == 0 {
39                return None;
40            }
41        }
42        let v = if next == 0 { last } else { next };
43        out[zigzag[j]] = v as u8;
44        last = v;
45    }
46    Some(out)
47}
48
49/// Read a full set of scaling lists, resolving each absent one by fall-back
50/// rule A (`fallback == None`, an SPS or a PPS over an SPS without lists) or
51/// B (`fallback == Some(sps lists)`) — Table 7-2.
52fn read_scaling_lists(
53    r: &mut BitReader,
54    count: usize,
55    fallback: Option<&ScalingLists>,
56) -> ScalingLists {
57    let mut s = ScalingLists::flat();
58    for i in 0..count {
59        let present = r.flag();
60        if i < 6 {
61            let parsed = if present {
62                Some(scaling_list(r, &ZIGZAG4).unwrap_or(DEFAULT_4X4[i / 3]))
63            } else {
64                None
65            };
66            s.m4[i] = match parsed {
67                Some(l) => l,
68                None if i == 0 || i == 3 => match fallback {
69                    Some(f) => f.m4[i],
70                    None => DEFAULT_4X4[i / 3],
71                },
72                None => s.m4[i - 1],
73            };
74        } else {
75            let k = i - 6;
76            let parsed = if present {
77                Some(scaling_list(r, &ZIGZAG8).unwrap_or(DEFAULT_8X8[k % 2]))
78            } else {
79                None
80            };
81            s.m8[k] = match parsed {
82                Some(l) => l,
83                None if k < 2 => match fallback {
84                    Some(f) => f.m8[k],
85                    None => DEFAULT_8X8[k],
86                },
87                None => s.m8[k - 2],
88            };
89        }
90    }
91    // Lists the syntax never reached keep the fall-back rule's answer.
92    for i in count..12 {
93        if i >= 6 {
94            let k = i - 6;
95            s.m8[k] = match fallback {
96                Some(f) => f.m8[k],
97                None if k < 2 => DEFAULT_8X8[k],
98                None => s.m8[k - 2],
99            };
100        }
101    }
102    s
103}
104
105#[derive(Clone, Debug)]
106pub struct Sps {
107    pub id: u32,
108    pub profile_idc: u32,
109    pub chroma_format_idc: u32,
110    pub bit_depth_luma: u32,
111    pub bit_depth_chroma: u32,
112    pub transform_bypass: bool,
113    pub scaling: Option<ScalingLists>,
114    pub log2_max_frame_num: u32,
115    pub poc_type: u32,
116    pub log2_max_poc_lsb: u32,
117    pub delta_pic_order_always_zero: bool,
118    pub offset_for_non_ref_pic: i32,
119    pub offset_for_top_to_bottom_field: i32,
120    pub offset_for_ref_frame: Vec<i32>,
121    pub max_num_ref_frames: u32,
122    pub gaps_allowed: bool,
123    pub width_mbs: u32,
124    pub height_mbs: u32,
125    pub frame_mbs_only: bool,
126    pub mbaff: bool,
127    pub direct_8x8_inference: bool,
128    /// Luma samples cropped off left, right, top, bottom.
129    pub crop: [u32; 4],
130    /// The VUI's colour description, when it has one.
131    pub colour_primaries: Option<u32>,
132    pub transfer_characteristics: Option<u32>,
133    pub matrix_coefficients: Option<u32>,
134    pub full_range: bool,
135}
136
137impl Sps {
138    pub fn parse(rbsp: &[u8]) -> Result<Sps> {
139        let mut r = BitReader::new(rbsp);
140        let profile_idc = r.u(8);
141        r.skip(16); // constraint flags, reserved, level_idc
142        let id = r.ue();
143        if id > 31 {
144            return Err(format!("SPS id {id} out of range"));
145        }
146        let mut chroma_format_idc = 1;
147        let mut bit_depth_luma = 8;
148        let mut bit_depth_chroma = 8;
149        let mut transform_bypass = false;
150        let mut scaling = None;
151        if matches!(
152            profile_idc,
153            100 | 110 | 122 | 244 | 44 | 83 | 86 | 118 | 128 | 138 | 139 | 134 | 135
154        ) {
155            chroma_format_idc = r.ue();
156            if chroma_format_idc == 3 && r.flag() {
157                return Err("separate colour planes are not supported".into());
158            }
159            bit_depth_luma = r.ue().saturating_add(8);
160            bit_depth_chroma = r.ue().saturating_add(8);
161            transform_bypass = r.flag();
162            if r.flag() {
163                let n = if chroma_format_idc != 3 { 8 } else { 12 };
164                scaling = Some(read_scaling_lists(&mut r, n, None));
165            }
166        }
167        if chroma_format_idc > 2 {
168            return Err(format!(
169                "H.264 chroma_format_idc {chroma_format_idc} is not supported (4:4:4)"
170            ));
171        }
172        if bit_depth_luma > 14 || bit_depth_chroma > 14 {
173            return Err("bit depth out of range".into());
174        }
175        // Range-checked against §7.4.2.1.1 before the arithmetic: a truncated
176        // or garbage SPS reads all-ones Exp-Golomb codes, which would overflow.
177        let log2_max_frame_num = r.ue().saturating_add(4);
178        if log2_max_frame_num > 16 {
179            return Err("log2_max_frame_num out of range".into());
180        }
181        let poc_type = r.ue();
182        let mut log2_max_poc_lsb = 0;
183        let mut delta_pic_order_always_zero = false;
184        let mut offset_for_non_ref_pic = 0;
185        let mut offset_for_top_to_bottom_field = 0;
186        let mut offset_for_ref_frame = Vec::new();
187        match poc_type {
188            0 => {
189                log2_max_poc_lsb = r.ue().saturating_add(4);
190                if log2_max_poc_lsb > 16 {
191                    return Err("log2_max_pic_order_cnt_lsb out of range".into());
192                }
193            }
194            1 => {
195                delta_pic_order_always_zero = r.flag();
196                offset_for_non_ref_pic = r.se();
197                offset_for_top_to_bottom_field = r.se();
198                let n = r.ue();
199                if n > 255 {
200                    return Err("too many POC cycle offsets".into());
201                }
202                for _ in 0..n {
203                    offset_for_ref_frame.push(r.se());
204                }
205            }
206            2 => {}
207            _ => return Err(format!("pic_order_cnt_type {poc_type}")),
208        }
209        let max_num_ref_frames = r.ue();
210        let gaps_allowed = r.flag();
211        let width_mbs = r.ue().saturating_add(1);
212        let height_map_units = r.ue().saturating_add(1);
213        if width_mbs > 1 << 12 || height_map_units > 1 << 12 {
214            return Err("SPS picture size out of range".into());
215        }
216        let frame_mbs_only = r.flag();
217        let mut mbaff = false;
218        if !frame_mbs_only {
219            mbaff = r.flag();
220        }
221        let height_mbs = height_map_units * if frame_mbs_only { 1 } else { 2 };
222        let direct_8x8_inference = r.flag();
223        let mut crop = [0u32; 4];
224        if r.flag() {
225            let (cx, cy) = match chroma_format_idc {
226                0 => (1, 2 - frame_mbs_only as u32),
227                // CropUnitY = SubHeightC * (2 - frame_mbs_only_flag).
228                2 => (2, 2 - frame_mbs_only as u32),
229                _ => (2, 2 * (2 - frame_mbs_only as u32)),
230            };
231            crop = [r.ue(), r.ue(), r.ue(), r.ue()];
232            crop = [
233                crop[0].saturating_mul(cx),
234                crop[1].saturating_mul(cx),
235                crop[2].saturating_mul(cy),
236                crop[3].saturating_mul(cy),
237            ];
238            // The decoder subtracts these from the coded size.
239            if crop[0].saturating_add(crop[1]) >= width_mbs * 16
240                || crop[2].saturating_add(crop[3]) >= height_mbs * 16
241            {
242                return Err("SPS cropping exceeds the picture".into());
243            }
244        }
245        let (mut colour_primaries, mut transfer_characteristics) = (None, None);
246        let mut matrix_coefficients = None;
247        let mut full_range = false;
248        if r.flag() {
249            // vui_parameters(): only as far as the colour description.
250            if r.flag() {
251                let idc = r.u(8);
252                if idc == 255 {
253                    r.skip(32);
254                }
255            }
256            if r.flag() {
257                r.skip(1);
258            }
259            if r.flag() {
260                r.skip(3);
261                full_range = r.flag();
262                if r.flag() {
263                    colour_primaries = Some(r.u(8));
264                    transfer_characteristics = Some(r.u(8));
265                    matrix_coefficients = Some(r.u(8));
266                }
267            }
268        }
269        if width_mbs > 1024 || height_mbs > 1024 {
270            return Err("picture size out of range".into());
271        }
272        crate::decode::picture::check_picture_size(width_mbs * 16, height_mbs * 16)?;
273        if crop[0] + crop[1] >= width_mbs * 16 || crop[2] + crop[3] >= height_mbs * 16 {
274            return Err("cropping removes the whole picture".into());
275        }
276        Ok(Sps {
277            id,
278            profile_idc,
279            chroma_format_idc,
280            bit_depth_luma,
281            bit_depth_chroma,
282            transform_bypass,
283            scaling,
284            log2_max_frame_num,
285            poc_type,
286            log2_max_poc_lsb,
287            delta_pic_order_always_zero,
288            offset_for_non_ref_pic,
289            offset_for_top_to_bottom_field,
290            offset_for_ref_frame,
291            max_num_ref_frames,
292            gaps_allowed,
293            width_mbs,
294            height_mbs,
295            frame_mbs_only,
296            mbaff,
297            direct_8x8_inference,
298            crop,
299            colour_primaries,
300            transfer_characteristics,
301            matrix_coefficients,
302            full_range,
303        })
304    }
305}
306
307#[derive(Clone, Debug)]
308pub struct Pps {
309    pub id: u32,
310    pub sps_id: u32,
311    pub cabac: bool,
312    pub bottom_field_pic_order_in_frame_present: bool,
313    pub num_ref_idx_default: [u32; 2],
314    pub weighted_pred: bool,
315    pub weighted_bipred_idc: u32,
316    pub pic_init_qp: i32,
317    pub chroma_qp_offset: [i32; 2],
318    pub deblocking_filter_control_present: bool,
319    pub constrained_intra_pred: bool,
320    pub redundant_pic_cnt_present: bool,
321    pub transform_8x8_mode: bool,
322    /// Present lists from the PPS, or `None` to use the SPS's.
323    pub scaling: Option<ScalingLists>,
324}
325
326impl Pps {
327    /// Parse against the SPS it names (needed for the scaling-list count and
328    /// fall-back).
329    pub fn parse(rbsp: &[u8], spss: &[Option<Sps>]) -> Result<Pps> {
330        let mut r = BitReader::new(rbsp);
331        let id = r.ue();
332        let sps_id = r.ue();
333        if id > 255 || sps_id > 31 {
334            return Err("PPS id out of range".into());
335        }
336        let sps = spss[sps_id as usize]
337            .as_ref()
338            .ok_or_else(|| format!("PPS {id} names missing SPS {sps_id}"))?;
339        let cabac = r.flag();
340        let bottom_field_pic_order_in_frame_present = r.flag();
341        let num_slice_groups = r.ue().saturating_add(1);
342        if num_slice_groups > 1 {
343            return Err("slice groups (FMO) are not supported".into());
344        }
345        let num_ref_idx_default = [r.ue().saturating_add(1), r.ue().saturating_add(1)];
346        if num_ref_idx_default[0] > 32 || num_ref_idx_default[1] > 32 {
347            return Err("num_ref_idx out of range".into());
348        }
349        let weighted_pred = r.flag();
350        let weighted_bipred_idc = r.u(2);
351        let pic_init_qp = r.se().saturating_add(26);
352        let _pic_init_qs = r.se().saturating_add(26);
353        let cb_off = r.se();
354        let deblocking_filter_control_present = r.flag();
355        let constrained_intra_pred = r.flag();
356        let redundant_pic_cnt_present = r.flag();
357        let mut transform_8x8_mode = false;
358        let mut scaling = None;
359        let mut cr_off = cb_off;
360        if r.more_rbsp_data() {
361            transform_8x8_mode = r.flag();
362            if r.flag() {
363                let n = 6 + if sps.chroma_format_idc != 3 { 2 } else { 6 }
364                    * transform_8x8_mode as usize;
365                scaling = Some(read_scaling_lists(&mut r, n, sps.scaling.as_ref()));
366            }
367            cr_off = r.se();
368        }
369        Ok(Pps {
370            id,
371            sps_id,
372            cabac,
373            bottom_field_pic_order_in_frame_present,
374            num_ref_idx_default,
375            weighted_pred,
376            weighted_bipred_idc,
377            pic_init_qp,
378            chroma_qp_offset: [cb_off, cr_off],
379            deblocking_filter_control_present,
380            constrained_intra_pred,
381            redundant_pic_cnt_present,
382            transform_8x8_mode,
383            scaling,
384        })
385    }
386}
387
388#[derive(Clone, Copy, Debug, PartialEq, Eq)]
389pub enum SliceType {
390    P,
391    B,
392    I,
393}
394
395/// One `ref_pic_list_modification` operation.
396#[derive(Clone, Copy, Debug)]
397pub struct ListMod {
398    pub idc: u32,
399    pub value: u32,
400}
401
402/// One `memory_management_control_operation`.
403#[derive(Clone, Copy, Debug)]
404pub struct Mmco {
405    pub op: u32,
406    pub diff_pic_nums_minus1: u32,
407    pub long_term_pic_num: u32,
408    pub long_term_frame_idx: u32,
409    pub max_long_term_frame_idx_plus1: u32,
410}
411
412/// Explicit weighted prediction for one list: `[ref][Y, Cb, Cr]` of
413/// `(weight, offset)`.
414#[derive(Clone, Debug, Default)]
415pub struct WeightTable {
416    pub luma_log2_denom: u32,
417    pub chroma_log2_denom: u32,
418    pub weights: [Vec<[(i32, i32); 3]>; 2],
419    /// Whether any explicit flag was set for `[list][ref]` — when none was,
420    /// the default (unweighted) formula applies.
421    pub explicit: [Vec<bool>; 2],
422}
423
424#[derive(Clone, Debug)]
425pub struct SliceHeader {
426    pub first_mb: u32,
427    pub slice_type: SliceType,
428    pub pps_id: u32,
429    pub frame_num: u32,
430    /// `field_pic_flag` / `bottom_field_flag`.
431    pub field_pic: bool,
432    pub bottom_field: bool,
433    /// `MbaffFrameFlag`: macroblock-adaptive frame/field coding of a frame.
434    pub mbaff: bool,
435    pub idr: bool,
436    pub nal_ref_idc: u32,
437    pub poc_lsb: u32,
438    pub delta_poc_bottom: i32,
439    pub delta_poc: [i32; 2],
440    pub redundant_pic_cnt: u32,
441    pub direct_spatial: bool,
442    pub num_ref_idx: [u32; 2],
443    pub list_mods: [Vec<ListMod>; 2],
444    pub weights: Option<WeightTable>,
445    pub long_term_reference: bool,
446    pub mmcos: Option<Vec<Mmco>>,
447    pub cabac_init_idc: u32,
448    pub qp: i32,
449    pub disable_deblocking: u32,
450    pub alpha_offset: i32,
451    pub beta_offset: i32,
452    /// Bit offset of `slice_data()` in the RBSP.
453    pub data_bit_offset: usize,
454}
455
456impl SliceHeader {
457    pub fn parse(
458        rbsp: &[u8],
459        nal_type: u32,
460        nal_ref_idc: u32,
461        spss: &[Option<Sps>],
462        ppss: &[Option<Pps>],
463    ) -> Result<SliceHeader> {
464        let mut r = BitReader::new(rbsp);
465        let first_mb = r.ue();
466        let slice_type = match r.ue() % 5 {
467            0 => SliceType::P,
468            1 => SliceType::B,
469            2 => SliceType::I,
470            t => return Err(format!("SP/SI slices (type {t}) are not supported")),
471        };
472        let pps_id = r.ue();
473        let pps = ppss
474            .get(pps_id as usize)
475            .and_then(|p| p.as_ref())
476            .ok_or_else(|| format!("slice names missing PPS {pps_id}"))?;
477        let sps = spss[pps.sps_id as usize]
478            .as_ref()
479            .ok_or("slice's PPS names a missing SPS")?;
480        let frame_num = r.u(sps.log2_max_frame_num);
481        let (mut field_pic, mut bottom_field) = (false, false);
482        if !sps.frame_mbs_only {
483            field_pic = r.flag();
484            if field_pic {
485                bottom_field = r.flag();
486            }
487        }
488        let idr = nal_type == 5;
489        if idr {
490            r.ue();
491        }
492        let mut poc_lsb = 0;
493        let mut delta_poc_bottom = 0;
494        let mut delta_poc = [0; 2];
495        if sps.poc_type == 0 {
496            poc_lsb = r.u(sps.log2_max_poc_lsb);
497            if pps.bottom_field_pic_order_in_frame_present && !field_pic {
498                delta_poc_bottom = r.se();
499            }
500        }
501        if sps.poc_type == 1 && !sps.delta_pic_order_always_zero {
502            delta_poc[0] = r.se();
503            if pps.bottom_field_pic_order_in_frame_present && !field_pic {
504                delta_poc[1] = r.se();
505            }
506        }
507        let mut redundant_pic_cnt = 0;
508        if pps.redundant_pic_cnt_present {
509            redundant_pic_cnt = r.ue();
510        }
511        let mut direct_spatial = false;
512        if slice_type == SliceType::B {
513            direct_spatial = r.flag();
514        }
515        let mut num_ref_idx = [0, 0];
516        if slice_type != SliceType::I {
517            num_ref_idx = pps.num_ref_idx_default;
518            if r.flag() {
519                num_ref_idx[0] = r.ue().saturating_add(1);
520                if slice_type == SliceType::B {
521                    num_ref_idx[1] = r.ue().saturating_add(1);
522                }
523            }
524            if slice_type != SliceType::B {
525                num_ref_idx[1] = 0;
526            }
527            if num_ref_idx[0] > 32 || num_ref_idx[1] > 32 {
528                return Err("num_ref_idx_active out of range".into());
529            }
530        }
531        let mut list_mods: [Vec<ListMod>; 2] = [Vec::new(), Vec::new()];
532        for list in 0..2 {
533            if ((list == 0 && slice_type != SliceType::I)
534                || (list == 1 && slice_type == SliceType::B))
535                && r.flag()
536            {
537                loop {
538                    let idc = r.ue();
539                    if idc == 3 {
540                        break;
541                    }
542                    if idc > 3 || list_mods[list].len() > 64 {
543                        return Err("bad ref_pic_list_modification".into());
544                    }
545                    let value = r.ue();
546                    list_mods[list].push(ListMod { idc, value });
547                }
548            }
549        }
550        let mut weights = None;
551        if (pps.weighted_pred && slice_type == SliceType::P)
552            || (pps.weighted_bipred_idc == 1 && slice_type == SliceType::B)
553        {
554            let mut w = WeightTable {
555                luma_log2_denom: r.ue(),
556                ..Default::default()
557            };
558            if sps.chroma_format_idc != 0 {
559                w.chroma_log2_denom = r.ue();
560            }
561            if w.luma_log2_denom > 7 || w.chroma_log2_denom > 7 {
562                return Err("weight denominator out of range".into());
563            }
564            let lists = if slice_type == SliceType::B { 2 } else { 1 };
565            for list in 0..lists {
566                for _ in 0..num_ref_idx[list] {
567                    let mut e = [
568                        (1 << w.luma_log2_denom, 0),
569                        (1 << w.chroma_log2_denom, 0),
570                        (1 << w.chroma_log2_denom, 0),
571                    ];
572                    let mut any = false;
573                    if r.flag() {
574                        e[0] = (r.se(), r.se());
575                        any = true;
576                    }
577                    if sps.chroma_format_idc != 0 && r.flag() {
578                        e[1] = (r.se(), r.se());
579                        e[2] = (r.se(), r.se());
580                        any = true;
581                    }
582                    w.weights[list].push(e);
583                    w.explicit[list].push(any);
584                }
585            }
586            weights = Some(w);
587        }
588        let mut long_term_reference = false;
589        let mut mmcos = None;
590        if nal_ref_idc != 0 {
591            if idr {
592                r.skip(1); // no_output_of_prior_pics_flag
593                long_term_reference = r.flag();
594            } else if r.flag() {
595                let mut ops = Vec::new();
596                loop {
597                    let op = r.ue();
598                    if op == 0 {
599                        break;
600                    }
601                    if op > 6 || ops.len() > 64 {
602                        return Err("bad memory_management_control_operation".into());
603                    }
604                    let mut m = Mmco {
605                        op,
606                        diff_pic_nums_minus1: 0,
607                        long_term_pic_num: 0,
608                        long_term_frame_idx: 0,
609                        max_long_term_frame_idx_plus1: 0,
610                    };
611                    if op == 1 || op == 3 {
612                        m.diff_pic_nums_minus1 = r.ue();
613                    }
614                    if op == 2 {
615                        m.long_term_pic_num = r.ue();
616                    }
617                    if op == 3 || op == 6 {
618                        m.long_term_frame_idx = r.ue();
619                    }
620                    if op == 4 {
621                        m.max_long_term_frame_idx_plus1 = r.ue();
622                    }
623                    ops.push(m);
624                }
625                mmcos = Some(ops);
626            }
627        }
628        let mut cabac_init_idc = 0;
629        if pps.cabac && slice_type != SliceType::I {
630            cabac_init_idc = r.ue();
631            if cabac_init_idc > 2 {
632                return Err("cabac_init_idc out of range".into());
633            }
634        }
635        let qp = pps.pic_init_qp.saturating_add(r.se());
636        let qp_min = -6 * (sps.bit_depth_luma as i32 - 8);
637        if qp < qp_min || qp > 51 {
638            return Err(format!("slice QP {qp} out of range"));
639        }
640        let mut disable_deblocking = 0;
641        let mut alpha_offset = 0;
642        let mut beta_offset = 0;
643        if pps.deblocking_filter_control_present {
644            disable_deblocking = r.ue();
645            if disable_deblocking > 2 {
646                return Err("disable_deblocking_filter_idc out of range".into());
647            }
648            if disable_deblocking != 1 {
649                alpha_offset = r.se().saturating_mul(2);
650                beta_offset = r.se().saturating_mul(2);
651            }
652        }
653        if r.overrun() {
654            return Err("slice header runs past the NAL".into());
655        }
656        Ok(SliceHeader {
657            first_mb,
658            slice_type,
659            pps_id,
660            frame_num,
661            field_pic,
662            mbaff: sps.mbaff && !field_pic,
663            bottom_field,
664            idr,
665            nal_ref_idc,
666            poc_lsb,
667            delta_poc_bottom,
668            delta_poc,
669            redundant_pic_cnt,
670            direct_spatial,
671            num_ref_idx,
672            list_mods,
673            weights,
674            long_term_reference,
675            mmcos,
676            cabac_init_idc,
677            qp,
678            disable_deblocking,
679            alpha_offset,
680            beta_offset,
681            data_bit_offset: r.pos(),
682        })
683    }
684}