Skip to main content

threers_codec/decode/
bits.rs

1//! Reading side of the bitstream layer: an MSB-first bit reader with
2//! Exp-Golomb, and NAL unit splitting and unescaping.
3//!
4//! The mirror of [`crate::bitstream`]. Reads past the end return zeros
5//! rather than failing, because a truncated slice is something a decoder has to
6//! survive, not something it can always detect before it has read too far —
7//! callers check [`BitReader::overrun`] at the points where it matters.
8
9/// MSB-first reader over an RBSP (emulation prevention already removed).
10#[derive(Clone)]
11pub struct BitReader<'a> {
12    data: &'a [u8],
13    /// Bit position from the start of `data`.
14    pos: usize,
15}
16
17impl<'a> BitReader<'a> {
18    /// A reader at the first bit of `data`.
19    pub fn new(data: &'a [u8]) -> Self {
20        BitReader { data, pos: 0 }
21    }
22
23    /// The whole buffer being read.
24    pub fn data(&self) -> &'a [u8] {
25        self.data
26    }
27
28    /// Bit position from the start of the buffer.
29    pub fn pos(&self) -> usize {
30        self.pos
31    }
32
33    /// Move to bit `pos` from the start of the buffer.
34    pub fn set_pos(&mut self, pos: usize) {
35        self.pos = pos;
36    }
37
38    /// The buffer's length in bits.
39    pub fn len_bits(&self) -> usize {
40        self.data.len() * 8
41    }
42
43    /// Bits left before the end of the buffer (negative once overrun).
44    pub fn bits_left(&self) -> isize {
45        self.len_bits() as isize - self.pos as isize
46    }
47
48    /// Whether reads have run past the end of the buffer.
49    pub fn overrun(&self) -> bool {
50        self.pos > self.len_bits()
51    }
52
53    /// Whether the next read starts on a byte boundary.
54    pub fn is_byte_aligned(&self) -> bool {
55        self.pos & 7 == 0
56    }
57
58    /// Skip to the next byte boundary (no-op when already on one).
59    pub fn byte_align(&mut self) {
60        self.pos = (self.pos + 7) & !7;
61    }
62
63    /// Byte offset of the reader, rounded up to the next byte boundary.
64    pub fn byte_pos(&self) -> usize {
65        (self.pos + 7) >> 3
66    }
67
68    #[inline(always)]
69    fn load64(&self, byte: usize) -> u64 {
70        if byte + 8 <= self.data.len() {
71            u64::from_be_bytes(self.data[byte..byte + 8].try_into().unwrap())
72        } else {
73            let mut b = [0u8; 8];
74            for (i, slot) in b.iter_mut().enumerate() {
75                if let Some(&v) = self.data.get(byte + i) {
76                    *slot = v;
77                }
78            }
79            u64::from_be_bytes(b)
80        }
81    }
82
83    /// The next `n` bits (`n <= 32`) without consuming them.
84    #[inline(always)]
85    pub fn peek(&self, n: u32) -> u32 {
86        if n == 0 {
87            return 0;
88        }
89        let v = self.load64(self.pos >> 3) << (self.pos & 7);
90        (v >> (64 - n)) as u32
91    }
92
93    /// Consume `n` bits.
94    #[inline(always)]
95    pub fn skip(&mut self, n: u32) {
96        self.pos += n as usize;
97    }
98
99    /// `u(n)`, `n <= 32`.
100    #[inline(always)]
101    pub fn u(&mut self, n: u32) -> u32 {
102        let v = self.peek(n);
103        self.pos += n as usize;
104        v
105    }
106
107    /// `u(1)` as a `bool`.
108    #[inline(always)]
109    pub fn flag(&mut self) -> bool {
110        self.u(1) != 0
111    }
112
113    /// `ue(v)`. Saturates on codes longer than 32 bits, which no conforming
114    /// stream contains.
115    pub fn ue(&mut self) -> u32 {
116        let peek = self.peek(32);
117        let lz = peek.leading_zeros();
118        if lz < 16 {
119            let len = 2 * lz + 1;
120            let v = self.peek(len);
121            self.pos += len as usize;
122            return v - 1;
123        }
124        if lz >= 32 {
125            // 32+ zeros: either garbage or the end of the buffer.
126            self.pos += 32;
127            return u32::MAX;
128        }
129        self.pos += lz as usize;
130        let v = self.u(lz + 1) as u64;
131        (v - 1) as u32
132    }
133
134    /// `se(v)`.
135    pub fn se(&mut self) -> i32 {
136        let k = self.ue() as i64;
137        if k & 1 == 1 {
138            ((k + 1) / 2) as i32
139        } else {
140            (-(k / 2)) as i32
141        }
142    }
143
144    /// `more_rbsp_data()`: whether anything other than the stop bit and its
145    /// alignment zeros is left.
146    pub fn more_rbsp_data(&self) -> bool {
147        let Some(last) = self.data.iter().rposition(|&b| b != 0) else {
148            return false;
149        };
150        let stop = last * 8 + 7 - self.data[last].trailing_zeros() as usize;
151        self.pos < stop
152    }
153}
154
155/// Remove emulation prevention bytes: every `00 00 03` becomes `00 00`.
156pub fn unescape(nal: &[u8]) -> Vec<u8> {
157    let mut out = Vec::with_capacity(nal.len());
158    let mut zeros = 0usize;
159    let mut i = 0;
160    while i < nal.len() {
161        let b = nal[i];
162        if zeros >= 2 && b == 3 {
163            zeros = 0;
164            i += 1;
165            continue;
166        }
167        if b == 0 {
168            zeros += 1;
169        } else {
170            zeros = 0;
171        }
172        out.push(b);
173        i += 1;
174    }
175    out
176}
177
178/// Split a length-prefixed sample (`avcC`/`hvcC` style) into NAL units.
179pub fn split_length_prefixed(sample: &[u8], len_size: usize) -> Result<Vec<&[u8]>, String> {
180    let mut out = Vec::new();
181    let mut at = 0usize;
182    while at < sample.len() {
183        if at + len_size > sample.len() {
184            return Err("sample ended inside a NAL length".into());
185        }
186        let mut n = 0usize;
187        for &b in &sample[at..at + len_size] {
188            n = (n << 8) | b as usize;
189        }
190        at += len_size;
191        if at + n > sample.len() {
192            return Err(format!("NAL of {n} bytes runs past the sample"));
193        }
194        if n > 0 {
195            out.push(&sample[at..at + n]);
196        }
197        at += n;
198    }
199    Ok(out)
200}
201
202/// Split an Annex B byte stream on its start codes.
203pub fn split_annexb(stream: &[u8]) -> Vec<&[u8]> {
204    let mut starts = Vec::new();
205    let mut i = 0;
206    while i + 3 <= stream.len() {
207        if stream[i] == 0 && stream[i + 1] == 0 && stream[i + 2] == 1 {
208            starts.push(i + 3);
209            i += 3;
210        } else {
211            i += 1;
212        }
213    }
214    let mut out = Vec::with_capacity(starts.len());
215    for (k, &s) in starts.iter().enumerate() {
216        let mut e = if k + 1 < starts.len() {
217            starts[k + 1] - 3
218        } else {
219            stream.len()
220        };
221        // Trailing zeros belong to the next start code (`00 00 00 01`) or
222        // are padding.
223        while e > s && stream[e - 1] == 0 {
224            e -= 1;
225        }
226        if e > s {
227            out.push(&stream[s..e]);
228        }
229    }
230    out
231}
232
233#[cfg(test)]
234mod tests {
235    use super::*;
236    use crate::bitstream::BitWriter;
237
238    #[test]
239    fn exp_golomb_round_trips() {
240        let mut w = BitWriter::new();
241        let vals = [
242            0u32,
243            1,
244            2,
245            3,
246            7,
247            8,
248            254,
249            255,
250            65534,
251            65535,
252            1 << 20,
253            0xFFFF_FFFE,
254        ];
255        for &v in &vals {
256            w.write_ue(v);
257        }
258        let svals = [0i32, 1, -1, 2, -2, 1000, -1000, 1 << 20, -(1 << 20)];
259        for &v in &svals {
260            w.write_se(v);
261        }
262        w.write_bits(0b101, 3);
263        let bytes = w.finish();
264        let mut r = BitReader::new(&bytes);
265        for &v in &vals {
266            assert_eq!(r.ue(), v);
267        }
268        for &v in &svals {
269            assert_eq!(r.se(), v);
270        }
271        assert_eq!(r.u(3), 0b101);
272    }
273
274    #[test]
275    fn unescape_drops_only_emulation_bytes() {
276        assert_eq!(
277            unescape(&[0, 0, 3, 1, 0, 0, 3, 0, 0, 3]),
278            vec![0, 0, 1, 0, 0, 0, 0]
279        );
280        assert_eq!(unescape(&[0, 3, 0, 0, 3, 3]), vec![0, 3, 0, 0, 3]);
281    }
282
283    #[test]
284    fn more_rbsp_data_stops_at_the_stop_bit() {
285        // 1 data bit, then the stop bit and alignment.
286        let d = [0b1100_0000u8];
287        let mut r = BitReader::new(&d);
288        assert!(r.more_rbsp_data());
289        r.skip(1);
290        assert!(!r.more_rbsp_data());
291    }
292
293    #[test]
294    fn annexb_splits_three_and_four_byte_start_codes() {
295        let s = [0, 0, 0, 1, 0x67, 1, 2, 0, 0, 1, 0x68, 3, 0, 0, 0, 1, 0x65];
296        let n = split_annexb(&s);
297        assert_eq!(n, vec![&[0x67u8, 1, 2][..], &[0x68, 3][..], &[0x65][..]]);
298    }
299}