Skip to main content

threers_codec/hevc/
encoder.rs

1//! Frame-level HEVC encoder: pixels in, Annex-B byte stream out.
2//!
3//! [`HevcEncoder`] ties the layers together — it emits VPS/SPS/PPS once, then an
4//! IDR I-slice per frame (milestone 3: `I_PCM`, so lossless in the YUV domain,
5//! no compression yet). Everything is pure Rust returning `Vec<u8>`, so it works
6//! on native and `wasm32` alike; the caller decides where the bytes go.
7
8use crate::hevc::nal::{nal_unit_base, push_annexb, NalUnitType};
9use crate::hevc::params::{write_pps, write_sps, write_vps, HevcConfig, CTB_SIZE};
10use crate::hevc::slice::{slice_segment_rbsp, PaddedYuv};
11
12/// A planar 4:2:0 (`yuv420p`) picture at display resolution. `width`/`height`
13/// must be even (chroma is subsampled 2×2). `y` is `width × height`; `u`/`v` are
14/// `(width/2) × (height/2)`.
15///
16/// `alpha` is an optional full-resolution (`width × height`) opacity plane. When
17/// present it is carried through to a transparent encode (an HEVC auxiliary
18/// alpha layer); `None` means fully opaque. It is populated automatically by
19/// [`from_rgba`](Self::from_rgba) when the source RGBA is not fully opaque.
20#[derive(Clone, Debug)]
21pub struct Yuv420Frame {
22    /// Width in pixels.
23    pub width: u32,
24    /// Height in pixels.
25    pub height: u32,
26    /// Luma, `width * height`.
27    pub y: Vec<u8>,
28    /// Cb, `ceil(width / 2) * ceil(height / 2)`.
29    pub u: Vec<u8>,
30    /// Cr, laid out like `u`.
31    pub v: Vec<u8>,
32    /// Opacity, `width * height`, or `None` for opaque.
33    pub alpha: Option<Vec<u8>>,
34}
35
36impl Yuv420Frame {
37    /// Allocate an all-black (well, all-zero-plane), fully-opaque frame.
38    pub fn new(width: u32, height: u32) -> Self {
39        assert!(
40            width.is_multiple_of(2) && height.is_multiple_of(2),
41            "4:2:0 needs even dimensions"
42        );
43        let (cw, ch) = (width / 2, height / 2);
44        Self {
45            width,
46            height,
47            y: vec![0; (width * height) as usize],
48            u: vec![128; (cw * ch) as usize],
49            v: vec![128; (cw * ch) as usize],
50            alpha: None,
51        }
52    }
53
54    /// Whether this frame carries a non-trivial alpha plane.
55    pub fn is_transparent(&self) -> bool {
56        self.alpha.is_some()
57    }
58
59    /// Convert tightly-packed RGBA8 (`width × height × 4`, top-left origin) to
60    /// 4:2:0 using BT.601 limited-range coefficients with 2×2 box chroma
61    /// subsampling. The alpha channel is preserved full-resolution in
62    /// [`alpha`](Self::alpha) when any pixel is non-opaque, otherwise dropped.
63    pub fn from_rgba(width: u32, height: u32, rgba: &[u8]) -> Self {
64        Self::from_packed(width, height, rgba, [0, 1, 2, 3], "rgba size mismatch")
65    }
66
67    /// [`from_rgba`](Self::from_rgba) for BGRA8 — what VideoToolbox and
68    /// `decode::NativeDecoder::take` (feature `decode`) hand back — without
69    /// swizzling to RGBA first.
70    pub fn from_bgra(width: u32, height: u32, bgra: &[u8]) -> Self {
71        Self::from_packed(width, height, bgra, [2, 1, 0, 3], "bgra size mismatch")
72    }
73
74    /// Packed 8-bit pixels with R, G, B and A at byte offsets `at` within
75    /// each 4-byte pixel.
76    fn from_packed(width: u32, height: u32, rgba: &[u8], at: [usize; 4], what: &str) -> Self {
77        assert!(
78            width.is_multiple_of(2) && height.is_multiple_of(2),
79            "4:2:0 needs even dimensions"
80        );
81        assert_eq!(rgba.len(), (width * height * 4) as usize, "{what}");
82        let [ri, gi, bi, ai] = at;
83        let (w, h) = (width as usize, height as usize);
84        let (cw, ch) = (w / 2, h / 2);
85        let mut y = vec![0u8; w * h];
86        let mut u = vec![0u8; cw * ch];
87        let mut v = vec![0u8; cw * ch];
88
89        // Look before allocating. Fully-opaque input is the common case and its
90        // alpha plane is discarded at the end anyway — at 8K that would be a
91        // 33 MB allocation, filled and freed, for every frame.
92        let any_transparent = rgba.as_chunks::<4>().0.iter().any(|px| px[ai] != 255);
93        let mut a = if any_transparent {
94            vec![0u8; w * h]
95        } else {
96            Vec::new()
97        };
98
99        // Luma (and alpha, when there is any).
100        for i in 0..(w * h) {
101            let (r, g, b) = (
102                rgba[i * 4 + ri] as i32,
103                rgba[i * 4 + gi] as i32,
104                rgba[i * 4 + bi] as i32,
105            );
106            y[i] = clamp8(((66 * r + 129 * g + 25 * b + 128) >> 8) + 16);
107            if any_transparent {
108                a[i] = rgba[i * 4 + ai];
109            }
110        }
111        // Chroma from 2×2 RGB averages.
112        for cy in 0..ch {
113            for cx in 0..cw {
114                let mut r = 0i32;
115                let mut g = 0i32;
116                let mut b = 0i32;
117                for dy in 0..2 {
118                    for dx in 0..2 {
119                        let p = ((cy * 2 + dy) * w + (cx * 2 + dx)) * 4;
120                        r += rgba[p + ri] as i32;
121                        g += rgba[p + gi] as i32;
122                        b += rgba[p + bi] as i32;
123                    }
124                }
125                let (r, g, b) = (r / 4, g / 4, b / 4);
126                u[cy * cw + cx] = clamp8(((-38 * r - 74 * g + 112 * b + 128) >> 8) + 128);
127                v[cy * cw + cx] = clamp8(((112 * r - 94 * g - 18 * b + 128) >> 8) + 128);
128            }
129        }
130        Self {
131            width,
132            height,
133            y,
134            u,
135            v,
136            alpha: any_transparent.then_some(a),
137        }
138    }
139}
140
141#[inline]
142fn clamp8(v: i32) -> u8 {
143    v.clamp(0, 255) as u8
144}
145
146/// A from-scratch HEVC encoder (milestone 3: IDR-only, `I_PCM`).
147pub struct HevcEncoder {
148    cfg: HevcConfig,
149    headers_emitted: bool,
150}
151
152impl HevcEncoder {
153    /// New color (4:2:0) encoder for a `width × height` display picture.
154    pub fn new(width: u32, height: u32) -> Self {
155        Self {
156            cfg: HevcConfig::new(width, height),
157            headers_emitted: false,
158        }
159    }
160
161    /// New monochrome (4:0:0) encoder — the format of a transparent video's
162    /// alpha auxiliary layer. Feed single-plane frames via
163    /// [`encode_gray_frame`](Self::encode_gray_frame).
164    pub fn new_monochrome(width: u32, height: u32) -> Self {
165        Self {
166            cfg: HevcConfig::new_monochrome(width, height),
167            headers_emitted: false,
168        }
169    }
170
171    /// The active configuration (coded size, CTB grid, …).
172    pub fn config(&self) -> &HevcConfig {
173        &self.cfg
174    }
175
176    /// Encode one 4:2:0 frame, returning its Annex-B access unit. The first call
177    /// prepends VPS/SPS/PPS; subsequent calls emit the IDR slice only.
178    pub fn encode_frame(&mut self, frame: &Yuv420Frame) -> Vec<u8> {
179        assert!(
180            self.cfg.has_chroma(),
181            "encode_frame on a monochrome encoder"
182        );
183        assert_eq!(
184            (frame.width, frame.height),
185            (self.cfg.width, self.cfg.height),
186            "frame size differs from encoder size"
187        );
188
189        // Pad each plane up to the coded (CTB-aligned) size by edge replication.
190        let (cw, ch) = (self.cfg.coded_width, self.cfg.coded_height);
191        let y = pad_plane(&frame.y, frame.width, frame.height, cw, ch);
192        let u = pad_plane(&frame.u, frame.width / 2, frame.height / 2, cw / 2, ch / 2);
193        let v = pad_plane(&frame.v, frame.width / 2, frame.height / 2, cw / 2, ch / 2);
194
195        let padded = PaddedYuv {
196            y: &y,
197            u: &u,
198            v: &v,
199            coded_width: cw,
200            coded_height: ch,
201        };
202        self.assemble_au(&padded)
203    }
204
205    /// Encode one monochrome frame — a tightly-packed `width × height` 8-bit
206    /// plane (e.g. an alpha channel). Returns the Annex-B access unit.
207    pub fn encode_gray_frame(&mut self, gray: &[u8]) -> Vec<u8> {
208        assert!(
209            !self.cfg.has_chroma(),
210            "encode_gray_frame on a color encoder"
211        );
212        assert_eq!(
213            gray.len(),
214            (self.cfg.width * self.cfg.height) as usize,
215            "gray plane size differs from encoder size"
216        );
217        let (cw, ch) = (self.cfg.coded_width, self.cfg.coded_height);
218        let y = pad_plane(gray, self.cfg.width, self.cfg.height, cw, ch);
219        let padded = PaddedYuv {
220            y: &y,
221            u: &[],
222            v: &[],
223            coded_width: cw,
224            coded_height: ch,
225        };
226        self.assemble_au(&padded)
227    }
228
229    /// Emit VPS/SPS/PPS (first AU only) + the IDR slice for `padded`.
230    fn assemble_au(&mut self, padded: &PaddedYuv) -> Vec<u8> {
231        let slice = slice_segment_rbsp(&self.cfg, padded);
232        let mut au = Vec::new();
233        if !self.headers_emitted {
234            let mono = !self.cfg.has_chroma();
235            push_annexb(&mut au, &nal_unit_base(NalUnitType::Vps, &write_vps(mono)));
236            push_annexb(
237                &mut au,
238                &nal_unit_base(NalUnitType::Sps, &write_sps(&self.cfg)),
239            );
240            push_annexb(&mut au, &nal_unit_base(NalUnitType::Pps, &write_pps()));
241            self.headers_emitted = true;
242        }
243        push_annexb(&mut au, &nal_unit_base(NalUnitType::IdrNLp, &slice));
244        au
245    }
246}
247
248/// Copy a `sw × sh` plane into a `dw × dh` buffer, replicating the right/bottom
249/// edges into the padding. `dw >= sw`, `dh >= sh`.
250pub(crate) fn pad_plane(src: &[u8], sw: u32, sh: u32, dw: u32, dh: u32) -> Vec<u8> {
251    if sw == dw && sh == dh {
252        return src.to_vec();
253    }
254    let (sw, sh, dw, dh) = (sw as usize, sh as usize, dw as usize, dh as usize);
255    let mut out = vec![0u8; dw * dh];
256    for y in 0..dh {
257        let sy = y.min(sh - 1);
258        for x in 0..dw {
259            let sx = x.min(sw - 1);
260            out[y * dw + x] = src[sy * sw + sx];
261        }
262    }
263    out
264}
265
266// CTB_SIZE is re-exported for callers that want to align sizes themselves.
267pub use crate::hevc::params::CTB_SIZE as CODING_TREE_BLOCK_SIZE;
268const _: () = assert!(CTB_SIZE == 16);
269
270#[cfg(test)]
271mod tests {
272    use super::*;
273    use crate::hevc::nal::START_CODE;
274
275    #[test]
276    fn from_bgra_matches_from_rgba() {
277        let (w, h) = (6u32, 4u32);
278        let rgba: Vec<u8> = (0..w * h * 4).map(|i| (i * 37 % 251) as u8).collect();
279        let bgra: Vec<u8> = rgba
280            .as_chunks::<4>()
281            .0
282            .iter()
283            .flat_map(|p| [p[2], p[1], p[0], p[3]])
284            .collect();
285        let (a, b) = (
286            Yuv420Frame::from_rgba(w, h, &rgba),
287            Yuv420Frame::from_bgra(w, h, &bgra),
288        );
289        assert_eq!((a.y, a.u, a.v, a.alpha), (b.y, b.u, b.v, b.alpha));
290    }
291
292    fn find(hay: &[u8], needle: &[u8]) -> bool {
293        hay.windows(needle.len()).any(|w| w == needle)
294    }
295
296    /// A deterministic, non-flat test frame so a decoder mismatch can't hide in
297    /// uniform data.
298    fn gradient(width: u32, height: u32) -> Yuv420Frame {
299        let mut f = Yuv420Frame::new(width, height);
300        for j in 0..height {
301            for i in 0..width {
302                f.y[(j * width + i) as usize] = ((i * 3 + j * 5) & 0xFF) as u8;
303            }
304        }
305        let (cw, ch) = (width / 2, height / 2);
306        for j in 0..ch {
307            for i in 0..cw {
308                f.u[(j * cw + i) as usize] = ((i * 7 + 30) & 0xFF) as u8;
309                f.v[(j * cw + i) as usize] = ((j * 11 + 60) & 0xFF) as u8;
310            }
311        }
312        f
313    }
314
315    #[test]
316    fn access_unit_has_expected_nals() {
317        let mut enc = HevcEncoder::new(64, 64);
318        let au = enc.encode_frame(&gradient(64, 64));
319        assert!(au.starts_with(&START_CODE));
320        // VPS(0x40 01), SPS(0x42 01), PPS(0x44 01), IDR_N_LP slice (20<<1 = 0x28 01).
321        assert!(find(&au, &[0x40, 0x01]), "VPS NAL header");
322        assert!(find(&au, &[0x42, 0x01]), "SPS NAL header");
323        assert!(find(&au, &[0x44, 0x01]), "PPS NAL header");
324        assert!(find(&au, &[0x28, 0x01]), "IDR slice NAL header");
325
326        // Second frame is slice-only.
327        let au2 = enc.encode_frame(&gradient(64, 64));
328        assert!(!find(&au2, &[0x42, 0x01]), "SPS must not repeat");
329        assert!(find(&au2, &[0x28, 0x01]), "IDR slice present");
330    }
331}