Skip to main content

threers_codec/decode/h264/
mod.rs

1//! A from-scratch H.264 / AVC decoder.
2//!
3//! Baseline, Main and High profiles, frame, field and MBAFF coded —
4//! CAVLC and CABAC, I/P/B slices, multiple slices, 8×8 transforms, scaling
5//! matrices, weighted prediction (explicit and implicit), spatial and
6//! temporal direct, long-term references and every memory management
7//! operation, 4:2:0, 4:2:2 (High 4:2:2) or monochrome, 8 bits and up. Not
8//! supported, and refused with an error rather than decoded wrongly:
9//! 4:4:4, slice groups (FMO), data partitioning, SP/SI slices and lossless
10//! transform bypass.
11//!
12//! Feed it NAL units with [`H264Decoder::decode_nal`]; each finished picture
13//! comes out of [`H264Decoder::finish_picture`] (called for you when a new
14//! picture starts) tagged with its picture order count.
15
16#[cfg(feature = "decode")]
17pub mod cabac_init;
18#[cfg(feature = "decode")]
19pub mod cavlc;
20#[cfg(feature = "decode")]
21pub mod deblock;
22#[cfg(feature = "decode")]
23pub mod inter;
24#[cfg(feature = "decode")]
25pub mod intra;
26// Parameter sets parse without the decoder: the MP4 muxer reads them.
27#[cfg_attr(not(feature = "decode"), allow(dead_code))]
28pub mod params;
29#[cfg(feature = "decode")]
30pub mod parse_cabac;
31#[cfg(feature = "decode")]
32pub mod parse_cavlc;
33#[cfg(feature = "decode")]
34pub mod slice;
35// Parameter sets parse without the decoder: the MP4 muxer reads them.
36#[cfg_attr(not(feature = "decode"), allow(dead_code))]
37pub mod tables;
38#[cfg(feature = "decode")]
39pub mod types;
40
41#[cfg(feature = "decode")]
42use std::collections::BTreeMap;
43#[cfg(feature = "decode")]
44use std::sync::{Arc, Mutex};
45
46#[cfg(feature = "decode")]
47use self::cavlc::CavlcTables;
48#[cfg(feature = "decode")]
49use self::params::{Mmco, Pps, SliceHeader, SliceType, Sps};
50#[cfg(feature = "decode")]
51use self::slice::{CurPic, SliceDeblock, SliceDec};
52#[cfg(feature = "decode")]
53use self::types::{MbInfo, RefData, RefEntry, RefPic};
54#[cfg(feature = "decode")]
55use super::bits::unescape;
56#[cfg(feature = "decode")]
57use super::jobs::{caught, Jobs, Slot};
58#[cfg(feature = "decode")]
59use super::picture::{ChromaFormat, ColorInfo, DecodedFrame, Plane};
60
61/// Decoding errors are messages naming what was malformed or unsupported.
62#[cfg(feature = "decode")]
63pub type Result<T> = std::result::Result<T, String>;
64
65#[cfg(feature = "decode")]
66/// A decoded picture and where it goes in display order.
67#[derive(Debug, Clone)]
68pub struct H264Picture {
69    /// The picture, cropped to its display size.
70    pub frame: DecodedFrame,
71    /// `PicOrderCnt`. Resets at every IDR picture (and memory management
72    /// operation 5), so it orders pictures only within one such period.
73    pub poc: i32,
74    /// Whether this picture is an IDR picture, which starts a new POC
75    /// period.
76    pub idr: bool,
77}
78
79#[cfg(feature = "decode")]
80/// The picture (frame or field) being decoded, with what marking needs
81/// once it is done.
82struct Current {
83    pic: CurPic,
84    sps: Sps,
85    /// 1 top field, 2 bottom field, 3 frame.
86    structure: u8,
87    /// `MbaffFrameFlag`.
88    mbaff: bool,
89    /// Index of its frame store in the DPB.
90    store: usize,
91    /// Second field of a frame whose first field is in `store`.
92    second_field: bool,
93    idr: bool,
94    nal_ref_idc: u32,
95    frame_num: u32,
96    long_term_reference: bool,
97    mmcos: Option<Vec<Mmco>>,
98    /// For detecting the first slice of the next picture.
99    pps_id: u32,
100    poc_lsb: u32,
101    poc_msb: i32,
102    frame_num_offset: i32,
103    /// With threads, the slices for its job to reconstruct.
104    work: Vec<SliceWork>,
105}
106
107/// A slice whose header is read and whose data is not.
108#[cfg(feature = "decode")]
109struct SliceWork {
110    rbsp: Vec<u8>,
111    hdr: SliceHeader,
112    pps: Pps,
113    refs: [Vec<RefEntry>; 2],
114    slice_num: u32,
115}
116
117/// The state shared with picture jobs.
118#[cfg(feature = "decode")]
119struct Threads {
120    jobs: Arc<Jobs>,
121    /// Finished pictures in decode order; `None` for one that failed.
122    finished: Arc<Mutex<BTreeMap<u64, Option<H264Picture>>>>,
123    /// The first failure in decode order.
124    error: Arc<Mutex<Option<(u64, String)>>>,
125    next_take: u64,
126    next_job: u64,
127    /// Pictures still go to jobs. A field or MBAFF stream stops that: a
128    /// second field reads the first from the store they share.
129    active: bool,
130}
131
132/// A hardware back end for [`H264Decoder`].
133///
134/// The decoder keeps doing everything but reconstruction: it parses the
135/// parameter sets and slice headers, numbers and marks references, builds
136/// the reference lists and orders output. Each slice is handed over with all
137/// of that, the accelerator reconstructs the picture, and when a frame is
138/// complete the decoder asks it for the samples. This is the shape of VAAPI
139/// and the other "the driver does not parse" APIs.
140#[cfg(feature = "decode")]
141pub trait H264Accel {
142    /// Decode one slice of the current picture.
143    fn slice(&mut self, s: &AccelSlice<'_>) -> Result<()>;
144    /// The current picture (frame or field) has had all its slices.
145    fn end_picture(&mut self) -> Result<()>;
146    /// The samples of the frame in store `store_id`, cropped as `sps` says.
147    fn frame(&mut self, store_id: u32, sps: &Sps) -> Result<DecodedFrame>;
148}
149
150/// Everything an [`H264Accel`] is told about one slice.
151#[cfg(feature = "decode")]
152pub struct AccelSlice<'a> {
153    /// The NAL unit as coded: header byte included, emulation prevention in.
154    pub nal: &'a [u8],
155    /// The active sequence parameter set.
156    pub sps: &'a Sps,
157    /// The active picture parameter set.
158    pub pps: &'a Pps,
159    /// The parsed slice header (`data_bit_offset` is where slice data starts, in RBSP bits after the header byte).
160    pub hdr: &'a SliceHeader,
161    /// The first slice of a new picture.
162    pub first: bool,
163    /// The frame store the picture is decoded into (shared by both fields).
164    pub store_id: u32,
165    /// 1 top field, 2 bottom field, 3 frame.
166    pub structure: u8,
167    /// `TopFieldOrderCnt`, `BottomFieldOrderCnt` of the picture.
168    pub field_poc: [i32; 2],
169    /// The frame stores, with their reference marking.
170    pub dpb: &'a [RefPic],
171    /// `RefPicList0` and `RefPicList1`, entries indexing `dpb`.
172    pub refs: &'a [Vec<RefEntry>; 2],
173}
174
175/// An H.264 decoder fed one NAL unit at a time ([`decode_nal`](Self::decode_nal)).
176///
177/// Most callers want [`NativeDecoder`](crate::decode::NativeDecoder), which
178/// unpacks MP4 samples and orders the output; this is the layer below it.
179#[cfg(feature = "decode")]
180pub struct H264Decoder {
181    spss: Vec<Option<Sps>>,
182    ppss: Vec<Option<Pps>>,
183    tables: Arc<CavlcTables>,
184    cur: Option<Current>,
185    /// Frame stores: references, plus the frame whose first field waits for
186    /// its pair.
187    dpb: Vec<RefPic>,
188    next_id: u32,
189    max_lt_idx: Option<u32>,
190    prev_poc_msb: i32,
191    prev_poc_lsb: i32,
192    prev_frame_num_offset: i32,
193    prev_frame_num: u32,
194    prev_ref_frame_num: u32,
195    prev_had_mmco5: bool,
196    /// A decoded first field waiting for its pair: `(store id, structure,
197    /// frame_num, reference)`.
198    pending: Option<(u32, u8, u32, bool)>,
199    /// Size of the last activated SPS, to notice a resolution change.
200    active_size: Option<(u32, u32)>,
201    done: Vec<H264Picture>,
202    accel: Option<Box<dyn H264Accel>>,
203    /// The first error an accelerator reported where nothing could return it.
204    accel_error: Option<String>,
205    /// The current picture has had a slice handed to the accelerator.
206    accel_started: bool,
207    threads: Option<Threads>,
208}
209
210#[cfg(feature = "decode")]
211impl Default for H264Decoder {
212    fn default() -> Self {
213        Self::new()
214    }
215}
216
217#[cfg(feature = "decode")]
218fn empty_planes() -> [Plane; 3] {
219    [
220        Plane::new(0, 0, 0),
221        Plane::new(0, 0, 0),
222        Plane::new(0, 0, 0),
223    ]
224}
225
226#[cfg(feature = "decode")]
227impl H264Decoder {
228    /// A decoder with no parameter sets yet.
229    pub fn new() -> Self {
230        H264Decoder {
231            spss: vec![None; 32],
232            ppss: vec![None; 256],
233            tables: Arc::new(CavlcTables::new()),
234            cur: None,
235            dpb: Vec::new(),
236            next_id: 1,
237            max_lt_idx: None,
238            prev_poc_msb: 0,
239            prev_poc_lsb: 0,
240            prev_frame_num_offset: 0,
241            prev_frame_num: 0,
242            prev_ref_frame_num: 0,
243            prev_had_mmco5: false,
244            pending: None,
245            active_size: None,
246            done: Vec::new(),
247            accel: None,
248            accel_error: None,
249            accel_started: false,
250            threads: None,
251        }
252    }
253
254    /// Reconstruct up to `threads` frames at once, each as soon as its
255    /// references are finished. Headers stay in order on the calling thread,
256    /// so [`decode_nal`](Self::decode_nal) can block when too many are
257    /// waiting, and must not be called from the thread pool itself: this does
258    /// nothing there, with one thread, or with an accelerator. Field and MBAFF
259    /// pictures decode in order on the calling thread.
260    ///
261    /// [`take_pictures`](Self::take_pictures) then gives pictures once they
262    /// are finished, leaving out any that failed; decoding carries on past
263    /// those, and [`take_thread_error`](Self::take_thread_error) has the first.
264    pub fn set_threads(&mut self, threads: usize) {
265        if threads > 1 && self.accel.is_none() && crate::pool_can_serve_caller() {
266            self.threads = Some(Threads {
267                jobs: Jobs::new(threads * 2),
268                finished: Arc::default(),
269                error: Arc::default(),
270                next_take: 0,
271                next_job: 0,
272                active: true,
273            });
274        }
275    }
276
277    /// Wait for every picture job to finish.
278    pub fn wait_for_pictures(&self) {
279        if let Some(t) = &self.threads {
280            t.jobs.wait();
281        }
282    }
283
284    /// The first error from a picture job, in decode order, once
285    /// [`wait_for_pictures`](Self::wait_for_pictures) has returned.
286    pub fn take_thread_error(&mut self) -> Option<String> {
287        let t = self.threads.as_ref()?;
288        t.error.lock().unwrap().take().map(|e| e.1)
289    }
290
291    /// Whether [`set_threads`](Self::set_threads) took effect.
292    pub(crate) fn threaded(&self) -> bool {
293        self.threads.is_some()
294    }
295
296    /// The number the next finished picture will have.
297    pub(crate) fn next_output_id(&self) -> u64 {
298        self.threads.as_ref().map_or(0, |t| t.next_job)
299    }
300
301    /// With threads: pictures finished so far by number, in decode order,
302    /// `None` for one that failed.
303    pub(crate) fn take_finished(&mut self) -> Vec<(u64, Option<H264Picture>)> {
304        let mut out = Vec::new();
305        if let Some(t) = &mut self.threads {
306            let mut finished = t.finished.lock().unwrap();
307            while let Some(picture) = finished.remove(&t.next_take) {
308                out.push((t.next_take, picture));
309                t.next_take += 1;
310            }
311        }
312        out
313    }
314
315    /// Back to reconstructing here: every job done, and the buffer holding
316    /// real pictures again.
317    fn stop_jobs(&mut self) {
318        let Some(t) = &mut self.threads else {
319            return;
320        };
321        t.jobs.wait();
322        t.active = false;
323        for p in &mut self.dpb {
324            if let Some(data) = p.slot.take().and_then(|s| s.get()) {
325                p.planes = data.planes.clone();
326                p.mbs = data.mbs.clone();
327            }
328        }
329    }
330
331    /// Queue a picture for [`take_pictures`](Self::take_pictures).
332    fn publish(&mut self, picture: H264Picture) {
333        match &mut self.threads {
334            Some(t) => {
335                t.finished.lock().unwrap().insert(t.next_job, Some(picture));
336                t.next_job += 1;
337            }
338            None => self.done.push(picture),
339        }
340    }
341
342    fn jobs_active(&self) -> bool {
343        self.threads.as_ref().is_some_and(|t| t.active)
344    }
345
346    /// Hand reconstruction to `accel` (see [`H264Accel`]).
347    pub fn set_accel(&mut self, accel: Box<dyn H264Accel>) {
348        self.accel = Some(accel);
349    }
350
351    /// The first error the accelerator reported from
352    /// [`finish_picture`](Self::finish_picture), which cannot return one.
353    pub fn take_accel_error(&mut self) -> Option<String> {
354        self.accel_error.take()
355    }
356
357    /// Decode one NAL unit (without start code or length prefix).
358    pub fn decode_nal(&mut self, nal: &[u8]) -> Result<()> {
359        if nal.is_empty() {
360            return Ok(());
361        }
362        let nal_ref_idc = ((nal[0] >> 5) & 3) as u32;
363        let nal_type = (nal[0] & 31) as u32;
364        match nal_type {
365            1 | 5 => {
366                let rbsp = unescape(&nal[1..]);
367                self.decode_slice(nal, &rbsp, nal_type, nal_ref_idc)
368            }
369            2..=4 => Err("data-partitioned slices are not supported".into()),
370            7 => {
371                let rbsp = unescape(&nal[1..]);
372                let sps = Sps::parse(&rbsp)?;
373                let id = sps.id as usize;
374                self.spss[id] = Some(sps);
375                Ok(())
376            }
377            8 => {
378                let rbsp = unescape(&nal[1..]);
379                let pps = Pps::parse(&rbsp, &self.spss)?;
380                let id = pps.id as usize;
381                self.ppss[id] = Some(pps);
382                Ok(())
383            }
384            9..=11 => {
385                // Access unit delimiter / end of sequence / end of stream: the
386                // current picture, if any, is complete.
387                self.finish_picture();
388                Ok(())
389            }
390            _ => Ok(()),
391        }
392    }
393
394    /// Pictures finished so far, in decode order.
395    pub fn take_pictures(&mut self) -> Vec<H264Picture> {
396        let finished: Vec<_> = self
397            .take_finished()
398            .into_iter()
399            .filter_map(|p| p.1)
400            .collect();
401        self.done.extend(finished);
402        std::mem::take(&mut self.done)
403    }
404
405    fn decode_slice(
406        &mut self,
407        nal: &[u8],
408        rbsp: &[u8],
409        nal_type: u32,
410        nal_ref_idc: u32,
411    ) -> Result<()> {
412        let hdr = SliceHeader::parse(rbsp, nal_type, nal_ref_idc, &self.spss, &self.ppss)?;
413        if hdr.redundant_pic_cnt > 0 {
414            return Ok(());
415        }
416        let structure = if !hdr.field_pic {
417            3
418        } else if hdr.bottom_field {
419            2
420        } else {
421            1
422        };
423        let new_pic = match &self.cur {
424            None => true,
425            Some(c) => {
426                hdr.first_mb == 0
427                    || c.frame_num != hdr.frame_num
428                    || c.pps_id != hdr.pps_id
429                    || c.idr != hdr.idr
430                    || (c.nal_ref_idc == 0) != (nal_ref_idc == 0)
431                    || c.poc_lsb != hdr.poc_lsb
432                    || c.structure != structure
433            }
434        };
435        if new_pic {
436            self.finish_picture();
437            self.start_picture(&hdr)?;
438        }
439        let pps = self.ppss[hdr.pps_id as usize]
440            .clone()
441            .ok_or("missing PPS")?;
442        let refs = self.build_lists(&hdr)?;
443        if let Some(accel) = self.accel.as_mut() {
444            let cur = self.cur.as_ref().unwrap();
445            let sps = cur.sps.clone();
446            let slice = AccelSlice {
447                nal,
448                sps: &sps,
449                pps: &pps,
450                hdr: &hdr,
451                first: !self.accel_started,
452                store_id: self.dpb[cur.store].id,
453                structure,
454                field_poc: cur.pic.field_poc,
455                dpb: &self.dpb,
456                refs: &refs,
457            };
458            self.accel_started = true;
459            return accel.slice(&slice);
460        }
461        let frefs = if hdr.mbaff {
462            self.field_lists(&refs)
463        } else {
464            Default::default()
465        };
466        let jobs = self.jobs_active();
467        let cur = self.cur.as_mut().unwrap();
468        let slice_num = cur.pic.slices.len() as u32;
469        cur.pic.slices.push(SliceDeblock {
470            disable: hdr.disable_deblocking,
471            alpha: hdr.alpha_offset,
472            beta: hdr.beta_offset,
473        });
474        if jobs {
475            cur.work.push(SliceWork {
476                rbsp: rbsp.to_vec(),
477                hdr,
478                pps,
479                refs,
480                slice_num,
481            });
482            return Ok(());
483        }
484        let mut dec = SliceDec::new(
485            &cur.sps,
486            &pps,
487            &hdr,
488            slice_num,
489            &mut cur.pic,
490            &self.dpb,
491            &refs,
492            &frefs,
493            &self.tables,
494        );
495        dec.decode(rbsp)
496    }
497
498    /// MBAFF field macroblocks' lists (§8.4.2.1): each frame of `refs` as
499    /// its two fields, the current macroblock's parity first; `[parity][list]`.
500    fn field_lists(&mut self, refs: &[Vec<RefEntry>; 2]) -> [[Vec<RefEntry>; 2]; 2] {
501        let mut out: [[Vec<RefEntry>; 2]; 2] = Default::default();
502        for (par, lists) in out.iter_mut().enumerate() {
503            for (l, list) in lists.iter_mut().enumerate() {
504                for e in &refs[l] {
505                    for k in 0..2 {
506                        let fp = par ^ k;
507                        let st = &mut self.dpb[e.dpb];
508                        list.push(RefEntry {
509                            dpb: e.dpb,
510                            id: st.id * 4 + 1 + fp as u32,
511                            poc: st.field_poc[fp],
512                            long_term: e.long_term,
513                            structure: 1 + fp as u8,
514                            planes: st.field(fp),
515                        });
516                    }
517                }
518            }
519        }
520        out
521    }
522
523    /// Drop frame stores that are neither references nor the frame waiting
524    /// for its second field (indices into `dpb` shift).
525    fn prune(&mut self) {
526        let keep = self.pending.map(|p| p.0);
527        self.dpb.retain(|p| p.is_ref() || Some(p.id) == keep);
528    }
529
530    fn start_picture(&mut self, hdr: &SliceHeader) -> Result<()> {
531        let pps = self.ppss[hdr.pps_id as usize]
532            .as_ref()
533            .ok_or("missing PPS")?;
534        let sps = self.spss[pps.sps_id as usize]
535            .clone()
536            .ok_or("missing SPS")?;
537        if sps.transform_bypass {
538            return Err("lossless (transform bypass) coding is not supported".into());
539        }
540        if !sps.frame_mbs_only && self.jobs_active() {
541            self.stop_jobs();
542        }
543        let structure: u8 = if !hdr.field_pic {
544            3
545        } else if hdr.bottom_field {
546            2
547        } else {
548            1
549        };
550        // h264_field_start: pair with a waiting first field of the other
551        // parity and the same frame_num; an unmatched one is dropped from
552        // display (but stays a reference if marked).
553        let mut second_store = None;
554        if let Some((id, s, fnum, _)) = self.pending.take() {
555            if structure != 3 && structure != s && fnum == hdr.frame_num {
556                second_store = self.dpb.iter().position(|p| p.id == id);
557            }
558            if second_store.is_none() {
559                self.prune();
560            }
561        }
562        let second_field = second_store.is_some();
563        let size = (sps.width_mbs, sps.height_mbs);
564        if self.active_size != Some(size) {
565            self.dpb.clear();
566            self.active_size = Some(size);
567        }
568        let max_frame_num = 1u32 << sps.log2_max_frame_num;
569        if hdr.idr && !second_field {
570            self.dpb.clear();
571            self.max_lt_idx = None;
572        } else if !second_field {
573            let expected = (self.prev_ref_frame_num + 1) % max_frame_num;
574            if hdr.frame_num != self.prev_ref_frame_num && hdr.frame_num != expected {
575                self.fill_frame_num_gap(&sps, hdr.frame_num);
576            }
577        }
578
579        // Picture order count (§8.2.1); a field sets only its own.
580        let mut poc_msb = 0;
581        let mut frame_num_offset = 0;
582        let (top, bottom) = match sps.poc_type {
583            0 => {
584                let (prev_msb, prev_lsb) = if hdr.idr {
585                    (0, 0)
586                } else {
587                    (self.prev_poc_msb, self.prev_poc_lsb)
588                };
589                let max_lsb = 1i32 << sps.log2_max_poc_lsb;
590                let lsb = hdr.poc_lsb as i32;
591                poc_msb = if lsb < prev_lsb && prev_lsb - lsb >= max_lsb / 2 {
592                    prev_msb + max_lsb
593                } else if lsb > prev_lsb && lsb - prev_lsb > max_lsb / 2 {
594                    prev_msb - max_lsb
595                } else {
596                    prev_msb
597                };
598                let top = poc_msb + lsb;
599                (
600                    top,
601                    if structure == 3 {
602                        top + hdr.delta_poc_bottom
603                    } else {
604                        top
605                    },
606                )
607            }
608            _ => {
609                let prev_off = if self.prev_had_mmco5 {
610                    0
611                } else {
612                    self.prev_frame_num_offset
613                };
614                frame_num_offset = if hdr.idr {
615                    0
616                } else if self.prev_frame_num > hdr.frame_num {
617                    prev_off + max_frame_num as i32
618                } else {
619                    prev_off
620                };
621                if sps.poc_type == 1 {
622                    let n = sps.offset_for_ref_frame.len() as i32;
623                    let mut abs = if n != 0 {
624                        frame_num_offset + hdr.frame_num as i32
625                    } else {
626                        0
627                    };
628                    if hdr.nal_ref_idc == 0 && abs > 0 {
629                        abs -= 1;
630                    }
631                    let mut expected = 0;
632                    if abs > 0 {
633                        let cycle = (abs - 1) / n;
634                        let in_cycle = (abs - 1) % n;
635                        let delta: i32 = sps.offset_for_ref_frame.iter().sum();
636                        expected = cycle * delta
637                            + sps.offset_for_ref_frame[..=in_cycle as usize]
638                                .iter()
639                                .sum::<i32>();
640                    }
641                    if hdr.nal_ref_idc == 0 {
642                        expected += sps.offset_for_non_ref_pic;
643                    }
644                    let top = expected + hdr.delta_poc[0];
645                    let mut bottom = top + sps.offset_for_top_to_bottom_field;
646                    if structure == 3 {
647                        bottom += hdr.delta_poc[1];
648                    }
649                    (top, bottom)
650                } else {
651                    let t = if hdr.idr {
652                        0
653                    } else if hdr.nal_ref_idc == 0 {
654                        2 * (frame_num_offset + hdr.frame_num as i32) - 1
655                    } else {
656                        2 * (frame_num_offset + hdr.frame_num as i32)
657                    };
658                    (t, t)
659                }
660            }
661        };
662
663        let (w_mbs, h_mbs) = (sps.width_mbs as usize, sps.height_mbs as usize);
664        let fill_y = 1u16 << (sps.bit_depth_luma - 1);
665        let fill_c = 1u16 << (sps.bit_depth_chroma - 1);
666        let ch_rows = if sps.chroma_format_idc == 2 { 16 } else { 8 };
667        // A field picture is half the frame's height.
668        let pic_h_mbs = if structure == 3 { h_mbs } else { h_mbs / 2 };
669        // Neither an accelerator nor a job needs the samples here.
670        let accel = self.accel.is_some() || self.jobs_active();
671        let make = |h: usize| {
672            if accel {
673                // The accelerator holds the samples.
674                empty_planes()
675            } else if sps.chroma_format_idc == 0 {
676                [
677                    Plane::new(w_mbs * 16, h * 16, fill_y),
678                    Plane::new(0, 0, 0),
679                    Plane::new(0, 0, 0),
680                ]
681            } else {
682                [
683                    Plane::new(w_mbs * 16, h * 16, fill_y),
684                    Plane::new(w_mbs * 8, h * ch_rows, fill_c),
685                    Plane::new(w_mbs * 8, h * ch_rows, fill_c),
686                ]
687            }
688        };
689        let store = match second_store {
690            Some(i) => i,
691            None => {
692                let id = self.next_id;
693                self.next_id += 1;
694                self.dpb.push(RefPic {
695                    id,
696                    planes: Arc::new(make(h_mbs)),
697                    field_planes: [None, None],
698                    mbs: Arc::new(Vec::new()),
699                    field_mbs: [None, None],
700                    field_poc: [i32::MAX, i32::MAX],
701                    poc: i32::MAX,
702                    frame_num: hdr.frame_num,
703                    frame_num_wrap: hdr.frame_num as i32,
704                    short: 0,
705                    long: 0,
706                    lt_idx: 0,
707                    slot: None,
708                });
709                self.dpb.len() - 1
710            }
711        };
712        {
713            let st = &mut self.dpb[store];
714            if structure & 1 != 0 {
715                st.field_poc[0] = top;
716            }
717            if structure & 2 != 0 {
718                st.field_poc[1] = bottom;
719            }
720            st.poc = st.field_poc[0].min(st.field_poc[1]);
721        }
722        let poc = match structure {
723            1 => top,
724            2 => bottom,
725            _ => top.min(bottom),
726        };
727        self.cur = Some(Current {
728            pic: CurPic {
729                planes: make(pic_h_mbs),
730                mbs: if accel {
731                    Vec::new()
732                } else {
733                    vec![MbInfo::default(); w_mbs * pic_h_mbs]
734                },
735                w_mbs,
736                h_mbs: pic_h_mbs,
737                poc,
738                field_poc: [top, bottom],
739                slices: Vec::new(),
740                decoded: 0,
741            },
742            sps,
743            structure,
744            mbaff: hdr.mbaff,
745            store,
746            second_field,
747            idr: hdr.idr,
748            nal_ref_idc: hdr.nal_ref_idc,
749            frame_num: hdr.frame_num,
750            long_term_reference: hdr.long_term_reference,
751            mmcos: hdr.mmcos.clone(),
752            pps_id: hdr.pps_id,
753            poc_lsb: hdr.poc_lsb,
754            poc_msb,
755            frame_num_offset,
756            work: Vec::new(),
757        });
758        Ok(())
759    }
760
761    /// Insert "non-existing" frames for skipped `frame_num`s (§8.2.5.2), so
762    /// the sliding window and list initialisation see what the encoder did.
763    fn fill_frame_num_gap(&mut self, sps: &Sps, frame_num: u32) {
764        let max = 1u32 << sps.log2_max_frame_num;
765        let mut f = (self.prev_ref_frame_num + 1) % max;
766        let mut guard = 0;
767        // Content of a non-existing frame is unspecified; reuse the newest
768        // reference so a stream that does reference one degrades gracefully.
769        let src = self
770            .dpb
771            .iter()
772            .filter(|p| p.is_ref())
773            .max_by_key(|p| p.id)
774            .map(|p| (p.planes.clone(), p.slot.clone()));
775        let Some((planes, slot)) = src else {
776            self.prev_ref_frame_num = frame_num.wrapping_sub(1) % max;
777            return;
778        };
779        while f != frame_num && guard < max {
780            self.update_wraps(f, max);
781            self.sliding_window(sps, false);
782            let id = self.next_id;
783            self.next_id += 1;
784            let mbs = Arc::new(vec![
785                MbInfo::default();
786                (sps.width_mbs * sps.height_mbs) as usize
787            ]);
788            self.dpb.push(RefPic {
789                id,
790                planes: planes.clone(),
791                field_planes: [None, None],
792                mbs,
793                field_mbs: [None, None],
794                field_poc: [0, 0],
795                poc: 0,
796                frame_num: f,
797                frame_num_wrap: 0,
798                short: 3,
799                long: 0,
800                lt_idx: 0,
801                slot: slot.clone(),
802            });
803            self.prev_ref_frame_num = f;
804            self.prev_frame_num = f;
805            f = (f + 1) % max;
806            guard += 1;
807        }
808    }
809
810    /// Recompute `FrameNumWrap` against the current `frame_num`.
811    fn update_wraps(&mut self, frame_num: u32, max_frame_num: u32) {
812        for p in &mut self.dpb {
813            if p.short != 0 {
814                p.frame_num_wrap = if p.frame_num > frame_num {
815                    p.frame_num as i32 - max_frame_num as i32
816                } else {
817                    p.frame_num as i32
818                };
819            }
820        }
821    }
822
823    fn build_lists(&mut self, hdr: &SliceHeader) -> Result<[Vec<RefEntry>; 2]> {
824        let cur = self.cur.as_ref().unwrap();
825        let max_frame_num = 1u32 << cur.sps.log2_max_frame_num;
826        let structure = cur.structure;
827        let field = structure != 3;
828        let cur_par = (structure == 2) as usize;
829        let cur_poc = cur.pic.poc;
830        let cur_store_id = self.dpb[cur.store].id;
831        self.update_wraps(hdr.frame_num, max_frame_num);
832        let mut lists: [Vec<RefEntry>; 2] = [Vec::new(), Vec::new()];
833        if hdr.slice_type == SliceType::I {
834            return Ok(lists);
835        }
836        // Frames take only stores with both fields marked; fields take any.
837        let full = |m: u8| if field { m != 0 } else { m == 3 };
838        let mut short: Vec<usize> = (0..self.dpb.len())
839            .filter(|&i| full(self.dpb[i].short))
840            .collect();
841        let mut long: Vec<usize> = (0..self.dpb.len())
842            .filter(|&i| full(self.dpb[i].long))
843            .collect();
844        long.sort_by_key(|&i| self.dpb[i].lt_idx);
845        // An ordered list of frame stores -> entries (§8.2.4.2.5 for fields:
846        // alternate parities starting with the current one).
847        let expand = |dpb: &mut Vec<RefPic>, order: &[usize], long_term: bool| -> Vec<RefEntry> {
848            let mark = |p: &RefPic| if long_term { p.long } else { p.short };
849            let mut out = Vec::new();
850            if !field {
851                for &i in order {
852                    let p = &dpb[i];
853                    out.push(RefEntry {
854                        dpb: i,
855                        id: p.id * 4 + 3,
856                        poc: p.poc,
857                        long_term,
858                        structure: 3,
859                        planes: p.planes.clone(),
860                    });
861                }
862                return out;
863            }
864            let sel = [cur_par, 1 - cur_par];
865            let mut idx = [0usize, 0usize];
866            loop {
867                let mut any = false;
868                for (k, &par) in sel.iter().enumerate() {
869                    while idx[k] < order.len() && mark(&dpb[order[idx[k]]]) & (1 << par) == 0 {
870                        idx[k] += 1;
871                    }
872                    if idx[k] < order.len() {
873                        let i = order[idx[k]];
874                        idx[k] += 1;
875                        any = true;
876                        let planes = dpb[i].field(par);
877                        let p = &dpb[i];
878                        out.push(RefEntry {
879                            dpb: i,
880                            id: p.id * 4 + 1 + par as u32,
881                            poc: p.field_poc[par],
882                            long_term,
883                            structure: 1 + par as u8,
884                            planes,
885                        });
886                    }
887                }
888                if !any {
889                    break;
890                }
891            }
892            out
893        };
894        if hdr.slice_type == SliceType::P {
895            short.sort_by_key(|&i| std::cmp::Reverse(self.dpb[i].frame_num_wrap));
896            let mut l = expand(&mut self.dpb, &short, false);
897            l.extend(expand(&mut self.dpb, &long, true));
898            lists[0] = l;
899        } else {
900            // B: by the frame (or pair) POC around the current POC; equal
901            // POCs go before (ffmpeg add_sorted).
902            let mut before: Vec<usize> = short
903                .iter()
904                .copied()
905                .filter(|&i| self.dpb[i].poc <= cur_poc)
906                .collect();
907            let mut after: Vec<usize> = short
908                .iter()
909                .copied()
910                .filter(|&i| !before.contains(&i))
911                .collect();
912            before.sort_by_key(|&i| std::cmp::Reverse(self.dpb[i].poc));
913            after.sort_by_key(|&i| self.dpb[i].poc);
914            let o0: Vec<usize> = before.iter().chain(after.iter()).copied().collect();
915            let o1: Vec<usize> = after.iter().chain(before.iter()).copied().collect();
916            let mut l0 = expand(&mut self.dpb, &o0, false);
917            let mut l1 = expand(&mut self.dpb, &o1, false);
918            let lt = expand(&mut self.dpb, &long, true);
919            l0.extend(lt.iter().cloned());
920            l1.extend(lt);
921            // Identical lists (compared by frame store, as ffmpeg does):
922            // swap the first two of list 1.
923            if l1.len() > 1
924                && l0.len() == l1.len()
925                && l0.iter().zip(&l1).all(|(a, b)| a.dpb == b.dpb)
926            {
927                l1.swap(0, 1);
928            }
929            lists = [l0, l1];
930        }
931        let _ = cur_store_id;
932        let (curr_pic_num, max_pic_num) = if field {
933            (2 * hdr.frame_num as i32 + 1, 2 * max_frame_num as i32)
934        } else {
935            (hdr.frame_num as i32, max_frame_num as i32)
936        };
937        for l in 0..2 {
938            let n = hdr.num_ref_idx[l] as usize;
939            lists[l].truncate(n);
940            if hdr.list_mods[l].is_empty() {
941                continue;
942            }
943            let mut pred = curr_pic_num;
944            let mut idx = 0usize;
945            for m in &hdr.list_mods[l] {
946                // (store index, parity or None for a frame, long-term)
947                let target: Option<(usize, Option<usize>, bool)> = if m.idc < 2 {
948                    let abs = m.value as i32 + 1;
949                    let mut no_wrap = if m.idc == 0 { pred - abs } else { pred + abs };
950                    if no_wrap < 0 {
951                        no_wrap += max_pic_num;
952                    } else if no_wrap >= max_pic_num {
953                        no_wrap -= max_pic_num;
954                    }
955                    pred = no_wrap;
956                    let pic_num = if no_wrap > curr_pic_num {
957                        no_wrap - max_pic_num
958                    } else {
959                        no_wrap
960                    };
961                    if field {
962                        let par = if pic_num & 1 == 1 {
963                            cur_par
964                        } else {
965                            1 - cur_par
966                        };
967                        let fnw = pic_num >> 1;
968                        self.dpb
969                            .iter()
970                            .position(|p| p.short & (1 << par) != 0 && p.frame_num_wrap == fnw)
971                            .map(|i| (i, Some(par), false))
972                    } else {
973                        self.dpb
974                            .iter()
975                            .position(|p| p.short == 3 && p.frame_num_wrap == pic_num)
976                            .map(|i| (i, None, false))
977                    }
978                } else if field {
979                    let par = if m.value & 1 == 1 {
980                        cur_par
981                    } else {
982                        1 - cur_par
983                    };
984                    let lt = m.value >> 1;
985                    self.dpb
986                        .iter()
987                        .position(|p| p.long & (1 << par) != 0 && p.lt_idx == lt)
988                        .map(|i| (i, Some(par), true))
989                } else {
990                    self.dpb
991                        .iter()
992                        .position(|p| p.long == 3 && p.lt_idx == m.value)
993                        .map(|i| (i, None, true))
994                };
995                let Some((i, par, long_term)) = target else {
996                    return Err("ref_pic_list_modification names a missing picture".into());
997                };
998                let e = match par {
999                    None => {
1000                        let p = &self.dpb[i];
1001                        RefEntry {
1002                            dpb: i,
1003                            id: p.id * 4 + 3,
1004                            poc: p.poc,
1005                            long_term,
1006                            structure: 3,
1007                            planes: p.planes.clone(),
1008                        }
1009                    }
1010                    Some(par) => {
1011                        let planes = self.dpb[i].field(par);
1012                        let p = &self.dpb[i];
1013                        RefEntry {
1014                            dpb: i,
1015                            id: p.id * 4 + 1 + par as u32,
1016                            poc: p.field_poc[par],
1017                            long_term,
1018                            structure: 1 + par as u8,
1019                            planes,
1020                        }
1021                    }
1022                };
1023                if idx > lists[l].len() {
1024                    idx = lists[l].len();
1025                }
1026                let eid = e.id;
1027                lists[l].insert(idx, e);
1028                idx += 1;
1029                let mut k = idx;
1030                while k < lists[l].len() {
1031                    if lists[l][k].id == eid {
1032                        lists[l].remove(k);
1033                    } else {
1034                        k += 1;
1035                    }
1036                }
1037            }
1038            lists[l].truncate(n);
1039        }
1040        Ok(lists)
1041    }
1042
1043    /// §8.2.5.3: when the DPB is full, unmark the short-term frame (or pair,
1044    /// or field) with the smallest `FrameNumWrap`. `exclude` is the current
1045    /// frame store (its first field does not count).
1046    fn sliding_window(&mut self, sps: &Sps, _exclude: bool) {
1047        let max = sps.max_num_ref_frames.max(1) as usize;
1048        let n_ref = self.dpb.iter().filter(|p| p.is_ref()).count();
1049        let n_short = self.dpb.iter().filter(|p| p.short != 0).count();
1050        if n_ref >= max
1051            && n_short > 0
1052            && let Some(i) = (0..self.dpb.len())
1053                .filter(|&i| self.dpb[i].short != 0)
1054                .min_by_key(|&i| self.dpb[i].frame_num_wrap)
1055        {
1056            self.dpb[i].short = 0;
1057        }
1058    }
1059
1060    /// Reference marking (§8.2.5) for the finished picture `cur`; returns
1061    /// whether it carried memory_management_control_operation 5.
1062    fn mark(&mut self, cur: &Current) -> bool {
1063        let max_frame_num = 1u32 << cur.sps.log2_max_frame_num;
1064        let structure = cur.structure;
1065        let field = structure != 3;
1066        let cur_par = (structure == 2) as usize;
1067        let cur_bits: u8 = if field { 1 << cur_par } else { 3 };
1068        let cur_id = self.dpb[cur.store].id;
1069        self.update_wraps(cur.frame_num, max_frame_num);
1070        let mut long_term = false;
1071        let mut lt_idx = 0;
1072        let mut had_mmco5 = false;
1073        // Unmark the given fields of store `i`.
1074        fn unmark(p: &mut RefPic, bits: u8, long: bool) {
1075            if long {
1076                p.long &= !bits;
1077            } else {
1078                p.short &= !bits;
1079            }
1080        }
1081        // (store, field bits) of a short-term picNumX / long-term pic num.
1082        let (curr_pic_num, _) = if field {
1083            (2 * cur.frame_num as i32 + 1, 0)
1084        } else {
1085            (cur.frame_num as i32, 0)
1086        };
1087        let find_short = |dpb: &[RefPic], pic_num: i32| -> Option<(usize, u8)> {
1088            if field {
1089                let par = if pic_num & 1 == 1 {
1090                    cur_par
1091                } else {
1092                    1 - cur_par
1093                };
1094                let fnw = pic_num >> 1;
1095                dpb.iter()
1096                    .position(|p| p.short & (1 << par) != 0 && p.frame_num_wrap == fnw)
1097                    .map(|i| (i, 1u8 << par))
1098            } else {
1099                dpb.iter()
1100                    .position(|p| p.short == 3 && p.frame_num_wrap == pic_num)
1101                    .map(|i| (i, 3))
1102            }
1103        };
1104        let find_long = |dpb: &[RefPic], num: u32| -> Option<(usize, u8)> {
1105            if field {
1106                let par = if num & 1 == 1 { cur_par } else { 1 - cur_par };
1107                dpb.iter()
1108                    .position(|p| p.long & (1 << par) != 0 && p.lt_idx == num >> 1)
1109                    .map(|i| (i, 1u8 << par))
1110            } else {
1111                dpb.iter()
1112                    .position(|p| p.long == 3 && p.lt_idx == num)
1113                    .map(|i| (i, 3))
1114            }
1115        };
1116        if cur.idr && !cur.second_field {
1117            if cur.long_term_reference {
1118                long_term = true;
1119                self.max_lt_idx = Some(0);
1120            } else {
1121                self.max_lt_idx = None;
1122            }
1123        } else if cur.second_field
1124            && (self.dpb[cur.store].short != 0 || self.dpb[cur.store].long != 0)
1125            && cur.mmcos.is_none()
1126        {
1127            // The first field already holds the frame's marking: the second
1128            // takes the same (no sliding window, §8.2.5.3).
1129            long_term = self.dpb[cur.store].long != 0;
1130            lt_idx = self.dpb[cur.store].lt_idx;
1131        } else if let Some(ops) = &cur.mmcos {
1132            for m in ops {
1133                let pic_num_x = curr_pic_num - (m.diff_pic_nums_minus1 as i32 + 1);
1134                match m.op {
1135                    1 => {
1136                        if let Some((i, b)) = find_short(&self.dpb, pic_num_x) {
1137                            unmark(&mut self.dpb[i], b, false);
1138                        }
1139                    }
1140                    2 => {
1141                        if let Some((i, b)) = find_long(&self.dpb, m.long_term_pic_num) {
1142                            unmark(&mut self.dpb[i], b, true);
1143                        }
1144                    }
1145                    3 => {
1146                        let idx = m.long_term_frame_idx;
1147                        if let Some((i, b)) = find_short(&self.dpb, pic_num_x) {
1148                            let id = self.dpb[i].id;
1149                            // Free the index unless it holds this field's sibling.
1150                            for p in self.dpb.iter_mut() {
1151                                if p.long != 0 && p.lt_idx == idx && (p.id != id || !field) {
1152                                    p.long = 0;
1153                                }
1154                            }
1155                            let p = &mut self.dpb[i];
1156                            p.short &= !b;
1157                            p.long |= b;
1158                            p.lt_idx = idx;
1159                        }
1160                    }
1161                    4 => {
1162                        let max = m.max_long_term_frame_idx_plus1;
1163                        self.max_lt_idx = max.checked_sub(1);
1164                        for p in self.dpb.iter_mut() {
1165                            if p.long != 0 && p.lt_idx >= max {
1166                                p.long = 0;
1167                            }
1168                        }
1169                    }
1170                    5 => {
1171                        for p in self.dpb.iter_mut() {
1172                            p.short = 0;
1173                            p.long = 0;
1174                        }
1175                        self.max_lt_idx = None;
1176                        had_mmco5 = true;
1177                    }
1178                    6 => {
1179                        let idx = m.long_term_frame_idx;
1180                        for p in self.dpb.iter_mut() {
1181                            if p.long != 0 && p.lt_idx == idx && p.id != cur_id {
1182                                p.long = 0;
1183                            }
1184                        }
1185                        long_term = true;
1186                        lt_idx = idx;
1187                    }
1188                    _ => {}
1189                }
1190            }
1191            if !long_term {
1192                // A stream that overfills the DPB with adaptive marking
1193                // is broken; slide rather than grow without bound.
1194                let max = cur.sps.max_num_ref_frames.max(1) as usize;
1195                let others = self
1196                    .dpb
1197                    .iter()
1198                    .filter(|p| p.is_ref() && p.id != cur_id)
1199                    .count();
1200                if others >= max {
1201                    self.sliding_window(&cur.sps, true);
1202                }
1203            }
1204        } else {
1205            self.sliding_window(&cur.sps, true);
1206        }
1207        let st = &mut self.dpb[cur.store];
1208        if long_term {
1209            st.long |= cur_bits;
1210            st.short &= !cur_bits;
1211            st.lt_idx = lt_idx;
1212        } else {
1213            st.short |= cur_bits;
1214        }
1215        had_mmco5
1216    }
1217
1218    /// Finish the picture in progress, if any: deblock, mark references, and
1219    /// queue a completed frame for output.
1220    pub fn finish_picture(&mut self) {
1221        let Some(mut cur) = self.cur.take() else {
1222            return;
1223        };
1224        let sps = cur.sps.clone();
1225        let accel = self.accel.is_some();
1226        // Marking below drops entries; the slices' indices are into this.
1227        let jobs = self.jobs_active();
1228        let snapshot = jobs.then(|| self.dpb.clone());
1229        let slot = jobs.then(Slot::new);
1230        if jobs {
1231            self.dpb[cur.store].slot = slot.clone();
1232        } else if accel {
1233            if std::mem::take(&mut self.accel_started)
1234                && let Err(e) = self.accel.as_mut().unwrap().end_picture()
1235            {
1236                self.accel_error.get_or_insert(e);
1237            }
1238        } else if cur.mbaff {
1239            deblock::deblock_mbaff(
1240                &mut cur.pic,
1241                sps.bit_depth_luma,
1242                sps.bit_depth_chroma,
1243                sps.chroma_format_idc,
1244            );
1245        } else {
1246            deblock::deblock_picture(
1247                &mut cur.pic,
1248                sps.bit_depth_luma,
1249                sps.bit_depth_chroma,
1250                sps.chroma_format_idc,
1251                cur.structure != 3,
1252            );
1253        }
1254        // Move the samples and motion into the frame store.
1255        let structure = cur.structure;
1256        if !accel && !jobs {
1257            let planes = std::mem::replace(&mut cur.pic.planes, empty_planes());
1258            let mbs = Arc::new(std::mem::take(&mut cur.pic.mbs));
1259            let st = &mut self.dpb[cur.store];
1260            st.field_planes = [None, None];
1261            if structure == 3 {
1262                st.planes = Arc::new(planes);
1263                st.mbs = mbs;
1264            } else {
1265                let par = (structure == 2) as usize;
1266                let dst = Arc::make_mut(&mut st.planes);
1267                for c in 0..3 {
1268                    let (fp, d) = (&planes[c], &mut dst[c]);
1269                    for y in 0..fp.height {
1270                        let o = (2 * y + par) * d.width;
1271                        d.data[o..o + d.width]
1272                            .copy_from_slice(&fp.data[y * fp.width..(y + 1) * fp.width]);
1273                    }
1274                }
1275                st.field_mbs[par] = Some(mbs);
1276            }
1277        }
1278        let mut had_mmco5 = false;
1279        if cur.nal_ref_idc != 0 {
1280            had_mmco5 = self.mark(&cur);
1281            let st = &mut self.dpb[cur.store];
1282            if had_mmco5 {
1283                // The picture now counts as frame_num 0 with its POC rebased.
1284                let temp = match structure {
1285                    1 => st.field_poc[0],
1286                    2 => st.field_poc[1],
1287                    _ => st.field_poc[0].min(st.field_poc[1]),
1288                };
1289                if structure & 1 != 0 {
1290                    st.field_poc[0] -= temp;
1291                }
1292                if structure & 2 != 0 {
1293                    st.field_poc[1] -= temp;
1294                }
1295                st.poc = st.field_poc[0].min(st.field_poc[1]);
1296                st.frame_num = 0;
1297            }
1298            st.frame_num_wrap = st.frame_num as i32;
1299            let frame_num = st.frame_num;
1300            self.prev_ref_frame_num = frame_num;
1301            if had_mmco5 {
1302                self.prev_poc_msb = 0;
1303                self.prev_poc_lsb = if structure == 2 { 0 } else { st.field_poc[0] };
1304            } else {
1305                self.prev_poc_msb = cur.poc_msb;
1306                self.prev_poc_lsb = cur.poc_lsb as i32;
1307            }
1308        }
1309        self.prev_had_mmco5 = had_mmco5;
1310        self.prev_frame_num = if had_mmco5 { 0 } else { cur.frame_num };
1311        self.prev_frame_num_offset = if had_mmco5 { 0 } else { cur.frame_num_offset };
1312        let complete = structure == 3 || cur.second_field;
1313        let st_id = self.dpb[cur.store].id;
1314        if !complete {
1315            self.pending = Some((st_id, structure, cur.frame_num, cur.nal_ref_idc != 0));
1316        }
1317        if let (Some(snapshot), Some(slot)) = (snapshot, slot) {
1318            let poc = self.dpb[cur.store].poc;
1319            let idr = cur.idr || had_mmco5;
1320            self.submit_picture(cur, snapshot, slot, poc, idr);
1321            self.prune();
1322            return;
1323        }
1324        if complete {
1325            let st = &self.dpb[cur.store];
1326            let (chroma, crop, color) = output_format(&sps);
1327            let frame = match self.accel.as_mut() {
1328                Some(a) => match a.frame(st.id, &sps) {
1329                    Ok(f) => f,
1330                    Err(e) => {
1331                        self.accel_error.get_or_insert(e);
1332                        self.prune();
1333                        return;
1334                    }
1335                },
1336                None => DecodedFrame::from_planes(
1337                    &st.planes,
1338                    chroma,
1339                    sps.bit_depth_luma as u8,
1340                    crop,
1341                    color,
1342                ),
1343            };
1344            let picture = H264Picture {
1345                frame,
1346                poc: st.poc,
1347                idr: cur.idr || had_mmco5,
1348            };
1349            self.publish(picture);
1350        }
1351        self.prune();
1352    }
1353
1354    /// Hand a picture, its marking done, to a job.
1355    fn submit_picture(
1356        &mut self,
1357        cur: Current,
1358        dpb: Vec<RefPic>,
1359        slot: Arc<Slot<RefData>>,
1360        poc: i32,
1361        idr: bool,
1362    ) {
1363        let mut deps: Vec<Arc<Slot<RefData>>> = Vec::new();
1364        for entry in cur.work.iter().flat_map(|w| w.refs.iter().flatten()) {
1365            if let Some(dep) = dpb.get(entry.dpb).and_then(|p| p.slot.clone())
1366                && !Arc::ptr_eq(&dep, &slot)
1367                && !deps.iter().any(|d| Arc::ptr_eq(d, &dep))
1368            {
1369                deps.push(dep);
1370            }
1371        }
1372        let t = self.threads.as_mut().unwrap();
1373        let order = t.next_job;
1374        t.next_job += 1;
1375        let (finished, error) = (t.finished.clone(), t.error.clone());
1376        let tables = self.tables.clone();
1377        let sps = cur.sps.clone();
1378        t.jobs.clone().submit(&deps, move || {
1379            let (data, frame) = match caught(|| reconstruct(cur, dpb, &tables)) {
1380                Ok((data, frame)) => (data, Some(frame)),
1381                Err(e) => {
1382                    let mut first = error.lock().unwrap();
1383                    if first.as_ref().is_none_or(|f| order < f.0) {
1384                        *first = Some((order, e));
1385                    }
1386                    (grey_frame(&sps), None)
1387                }
1388            };
1389            let picture = frame.map(|frame| H264Picture { frame, poc, idr });
1390            finished.lock().unwrap().insert(order, picture);
1391            slot.finish(data);
1392        });
1393    }
1394}
1395
1396/// How `sps` says a picture leaves the decoder.
1397#[cfg(feature = "decode")]
1398fn output_format(sps: &Sps) -> (ChromaFormat, [usize; 4], ColorInfo) {
1399    let chroma = match sps.chroma_format_idc {
1400        0 => ChromaFormat::Monochrome,
1401        2 => ChromaFormat::Yuv422,
1402        _ => ChromaFormat::Yuv420,
1403    };
1404    let color = ColorInfo::from_vui(
1405        sps.matrix_coefficients,
1406        sps.full_range,
1407        sps.height_mbs * 16 - sps.crop[2] - sps.crop[3],
1408    );
1409    (chroma, sps.crop.map(|v| v as usize), color)
1410}
1411
1412/// What a failed picture leaves for the ones that reference it.
1413#[cfg(feature = "decode")]
1414fn grey_frame(sps: &Sps) -> RefData {
1415    let (w, h) = (sps.width_mbs as usize * 16, sps.height_mbs as usize * 16);
1416    let (cw, ch) = match sps.chroma_format_idc {
1417        0 => (0, 0),
1418        2 => (w / 2, h),
1419        _ => (w / 2, h / 2),
1420    };
1421    let planes = [
1422        Plane::new(w, h, 1 << (sps.bit_depth_luma - 1)),
1423        Plane::new(cw, ch, 1 << (sps.bit_depth_chroma - 1)),
1424        Plane::new(cw, ch, 1 << (sps.bit_depth_chroma - 1)),
1425    ];
1426    RefData {
1427        planes: Arc::new(planes),
1428        mbs: Arc::new(vec![
1429            MbInfo::default();
1430            (sps.width_mbs * sps.height_mbs) as usize
1431        ]),
1432    }
1433}
1434
1435/// A picture job: its slices, deblocking and what comes out. `dpb` is the
1436/// buffer as this frame saw it, its references all finished by now.
1437#[cfg(feature = "decode")]
1438fn reconstruct(
1439    mut cur: Current,
1440    mut dpb: Vec<RefPic>,
1441    tables: &CavlcTables,
1442) -> Result<(RefData, DecodedFrame)> {
1443    for p in &mut dpb {
1444        if let Some(data) = p.slot.as_ref().and_then(|s| s.get()) {
1445            p.planes = data.planes.clone();
1446            p.mbs = data.mbs.clone();
1447        }
1448    }
1449    let sps = cur.sps.clone();
1450    // The buffers come here rather than in the header walk, which they would
1451    // otherwise hold up.
1452    let blank = grey_frame(&sps);
1453    cur.pic.mbs = (*blank.mbs).clone();
1454    cur.pic.planes = Arc::try_unwrap(blank.planes).unwrap_or_else(|p| (*p).clone());
1455    for mut w in std::mem::take(&mut cur.work) {
1456        // The lists were built before these samples existed.
1457        for entry in w.refs.iter_mut().flatten() {
1458            entry.planes = dpb
1459                .get(entry.dpb)
1460                .ok_or("reference out of range")?
1461                .planes
1462                .clone();
1463        }
1464        let frefs = Default::default();
1465        let mut dec = SliceDec::new(
1466            &sps,
1467            &w.pps,
1468            &w.hdr,
1469            w.slice_num,
1470            &mut cur.pic,
1471            &dpb,
1472            &w.refs,
1473            &frefs,
1474            tables,
1475        );
1476        dec.decode(&w.rbsp)?;
1477    }
1478    deblock::deblock_picture(
1479        &mut cur.pic,
1480        sps.bit_depth_luma,
1481        sps.bit_depth_chroma,
1482        sps.chroma_format_idc,
1483        false,
1484    );
1485    let planes = std::mem::replace(&mut cur.pic.planes, empty_planes());
1486    let (chroma, crop, color) = output_format(&sps);
1487    let frame = DecodedFrame::from_planes(&planes, chroma, sps.bit_depth_luma as u8, crop, color);
1488    let mbs = Arc::new(std::mem::take(&mut cur.pic.mbs));
1489    Ok((
1490        RefData {
1491            planes: Arc::new(planes),
1492            mbs,
1493        },
1494        frame,
1495    ))
1496}