Skip to main content

threers_codec/nvidia/
nvdec.rs

1//! NVDEC through the driver's own parser (`cuvidCreateVideoParser`): it reads
2//! the bitstream and hands back filled-in picture parameters, so nothing
3//! here parses H.264, HEVC, VP9 or AV1 syntax.
4//!
5//! Pictures are copied to the host as they are decoded, in decode order, and
6//! queued under the presentation time of the sample that carried them — the
7//! contract [`NativeDecoder`](crate::decode::NativeDecoder) and the
8//! VideoToolbox session keep, so a picture can be taken as soon as `push`
9//! returns. VP9 and AV1 can code frames that are never shown; for those the
10//! display callback, which only fires for shown frames, does the copy
11//! instead.
12
13use std::ffi::{c_int, c_short, c_uint, c_ulong, c_void};
14use std::sync::OnceLock;
15
16use super::{check, Context, CuResult, Lib, Memcpy2d, MEMORYTYPE_DEVICE, MEMORYTYPE_HOST};
17use crate::decode::{ColorInfo, DecodedFrame, PackedFrame};
18use crate::mp4_demux::{TrackCodec, VideoTrack};
19
20type Parser = *mut c_void;
21type CuvidDecoder = *mut c_void;
22
23const CODEC_H264: c_int = 4;
24const CODEC_HEVC: c_int = 8;
25const CODEC_VP9: c_int = 10;
26const CODEC_AV1: c_int = 11;
27const CHROMA_420: c_int = 1;
28const SURFACE_NV12: c_int = 0;
29const SURFACE_P016: c_int = 1;
30const CREATE_PREFER_CUVID: c_ulong = 4;
31const PKT_TIMESTAMP: c_ulong = 2;
32const PKT_ENDOFPICTURE: c_ulong = 8;
33
34/// `CUVIDEOFORMAT`.
35#[repr(C)]
36#[derive(Clone, Copy)]
37struct VideoFormat {
38    codec: c_int,
39    frame_rate: [c_uint; 2],
40    progressive_sequence: u8,
41    bit_depth_luma_minus8: u8,
42    bit_depth_chroma_minus8: u8,
43    min_num_decode_surfaces: u8,
44    coded_width: c_uint,
45    coded_height: c_uint,
46    /// left, top, right, bottom
47    display_area: [c_int; 4],
48    chroma_format: c_int,
49    bitrate: c_uint,
50    display_aspect_ratio: [c_int; 2],
51    /// video_format:3 | full_range:1 | reserved:4, then primaries, transfer,
52    /// matrix.
53    video_signal_description: [u8; 4],
54    seqhdr_data_length: c_uint,
55}
56const _: () = assert!(std::mem::size_of::<VideoFormat>() == 64);
57
58/// `CUVIDPARSERPARAMS`.
59#[repr(C)]
60struct ParserParams {
61    codec_type: c_int,
62    max_num_decode_surfaces: c_uint,
63    clock_rate: c_uint,
64    error_threshold: c_uint,
65    max_display_delay: c_uint,
66    /// `bAnnexb:1`, reserved:31.
67    flags: c_uint,
68    reserved1: [c_uint; 4],
69    user_data: *mut c_void,
70    sequence: Option<unsafe extern "C" fn(*mut c_void, *mut VideoFormat) -> c_int>,
71    decode: Option<unsafe extern "C" fn(*mut c_void, *mut c_void) -> c_int>,
72    display: Option<unsafe extern "C" fn(*mut c_void, *mut DispInfo) -> c_int>,
73    operating_point: *mut c_void,
74    sei: *mut c_void,
75    reserved2: [*mut c_void; 5],
76    ext_video_info: *mut c_void,
77}
78const _: () = assert!(std::mem::size_of::<ParserParams>() == 136);
79
80/// `CUVIDSOURCEDATAPACKET`.
81#[repr(C)]
82struct Packet {
83    flags: c_ulong,
84    payload_size: c_ulong,
85    payload: *const u8,
86    timestamp: i64,
87}
88
89/// `CUVIDPARSERDISPINFO`.
90#[repr(C)]
91struct DispInfo {
92    picture_index: c_int,
93    progressive_frame: c_int,
94    top_field_first: c_int,
95    repeat_first_field: c_int,
96    timestamp: i64,
97}
98const _: () = assert!(std::mem::size_of::<DispInfo>() == 24);
99
100/// `CUVIDDECODECREATEINFO`.
101#[repr(C)]
102struct CreateInfo {
103    width: c_ulong,
104    height: c_ulong,
105    num_decode_surfaces: c_ulong,
106    codec_type: c_int,
107    chroma_format: c_int,
108    creation_flags: c_ulong,
109    bit_depth_minus8: c_ulong,
110    intra_decode_only: c_ulong,
111    max_width: c_ulong,
112    max_height: c_ulong,
113    reserved1: c_ulong,
114    display_area: [c_short; 4],
115    output_format: c_int,
116    deinterlace_mode: c_int,
117    target_width: c_ulong,
118    target_height: c_ulong,
119    num_output_surfaces: c_ulong,
120    vid_lock: *mut c_void,
121    target_rect: [c_short; 4],
122    enable_histogram: c_ulong,
123    reserved2: [c_ulong; 4],
124}
125#[cfg(unix)]
126const _: () = assert!(std::mem::size_of::<CreateInfo>() == 176);
127
128/// `CUVIDPROCPARAMS`.
129#[repr(C)]
130struct ProcParams {
131    progressive_frame: c_int,
132    second_field: c_int,
133    top_field_first: c_int,
134    unpaired_field: c_int,
135    reserved_flags: c_uint,
136    reserved_zero: c_uint,
137    raw_input_dptr: u64,
138    raw_input_pitch: c_uint,
139    raw_input_format: c_uint,
140    raw_output_dptr: u64,
141    raw_output_pitch: c_uint,
142    reserved1: c_uint,
143    output_stream: *mut c_void,
144    reserved: [c_uint; 46],
145    histogram_dptr: *mut u64,
146    reserved2: [*mut c_void; 1],
147}
148const _: () = assert!(std::mem::size_of::<ProcParams>() == 264);
149
150/// Offset of `CurrPicIdx` in `CUVIDPICPARAMS`, which is otherwise passed
151/// through untouched.
152const PICPARAMS_CURR_PIC_IDX: usize = 8;
153
154/// The NVDEC calls, from `libnvcuvid`.
155pub(crate) struct Cuvid {
156    _lib: Lib,
157    create_parser: unsafe extern "C" fn(*mut Parser, *mut ParserParams) -> CuResult,
158    parse: unsafe extern "C" fn(Parser, *mut Packet) -> CuResult,
159    destroy_parser: unsafe extern "C" fn(Parser) -> CuResult,
160    create_decoder: unsafe extern "C" fn(*mut CuvidDecoder, *mut CreateInfo) -> CuResult,
161    destroy_decoder: unsafe extern "C" fn(CuvidDecoder) -> CuResult,
162    decode_picture: unsafe extern "C" fn(CuvidDecoder, *mut c_void) -> CuResult,
163    map: unsafe extern "C" fn(
164        CuvidDecoder,
165        c_int,
166        *mut u64,
167        *mut c_uint,
168        *mut ProcParams,
169    ) -> CuResult,
170    unmap: unsafe extern "C" fn(CuvidDecoder, u64) -> CuResult,
171}
172
173impl Cuvid {
174    fn load() -> Option<Cuvid> {
175        super::cuda()?;
176        let lib = Lib::open(&["libnvcuvid.so.1", "libnvcuvid.so", "nvcuvid.dll"])?;
177        unsafe {
178            Some(Cuvid {
179                create_parser: lib.sym("cuvidCreateVideoParser")?,
180                parse: lib.sym("cuvidParseVideoData")?,
181                destroy_parser: lib.sym("cuvidDestroyVideoParser")?,
182                create_decoder: lib.sym("cuvidCreateDecoder")?,
183                destroy_decoder: lib.sym("cuvidDestroyDecoder")?,
184                decode_picture: lib.sym("cuvidDecodePicture")?,
185                map: lib.sym("cuvidMapVideoFrame64")?,
186                unmap: lib.sym("cuvidUnmapVideoFrame64")?,
187                _lib: lib,
188            })
189        }
190    }
191}
192
193/// NVDEC, loaded once, or `None` without the driver.
194pub(crate) fn cuvid() -> Option<&'static Cuvid> {
195    static CUVID: OnceLock<Option<Cuvid>> = OnceLock::new();
196    CUVID.get_or_init(Cuvid::load).as_ref()
197}
198
199/// What the callbacks share with the decoder. Boxed, so its address — the
200/// parser's user data — does not move.
201struct State {
202    cuvid: &'static Cuvid,
203    decoder: CuvidDecoder,
204    format: Option<VideoFormat>,
205    /// Copy out from the display callback (VP9, AV1) rather than the decode one.
206    on_display: bool,
207    /// Presentation time of the sample being parsed.
208    pts: i64,
209    /// Pictures copied out during the current `push`.
210    copied: i64,
211    ready: Vec<(i64, PackedFrame)>,
212    error: Option<String>,
213    /// Where the pictures' buffers come from.
214    pool: crate::bytes::FramePool,
215}
216
217impl State {
218    fn fail(&mut self, e: String) -> c_int {
219        self.error.get_or_insert(e);
220        0
221    }
222
223    /// Map surface `index` and copy the display area to the host, as the
224    /// decoder left it: NV12, or P016 above 8 bits.
225    unsafe fn copy_out(&mut self, index: c_int) -> Result<PackedFrame, String> {
226        let fmt = self.format.ok_or("a picture before the sequence header")?;
227        let cuda = super::cuda().ok_or("CUDA went away")?;
228        let mut proc: ProcParams = unsafe { std::mem::zeroed() };
229        proc.progressive_frame = 1;
230        let (mut dptr, mut pitch) = (0u64, 0u32);
231        check("cuvidMapVideoFrame", unsafe {
232            (self.cuvid.map)(self.decoder, index, &mut dptr, &mut pitch, &mut proc)
233        })?;
234        let [left, top, right, bottom] = fmt.display_area;
235        let (w, h) = ((right - left) as usize, (bottom - top) as usize);
236        let deep = fmt.bit_depth_luma_minus8 > 0;
237        let bps = if deep { 2 } else { 1 };
238        let surface_h = fmt.coded_height as usize;
239        let pitch = pitch as usize;
240        // From the pool, not zeroed: the copies below write every byte, and
241        // the lengths are set only once they have.
242        let (luma_len, chroma_len) = (w * h * bps, w.div_ceil(2) * 2 * h.div_ceil(2) * bps);
243        let mut luma = self.pool.take(luma_len);
244        let mut chroma = self.pool.take(chroma_len);
245        let copy = |src: u64, x: usize, y: usize, dst: *mut u8, width: usize, rows: usize| {
246            let mut m = Memcpy2d::zeroed();
247            m.src_memory_type = MEMORYTYPE_DEVICE;
248            m.src_device = src;
249            m.src_pitch = pitch;
250            m.src_x_in_bytes = x;
251            m.src_y = y;
252            m.dst_memory_type = MEMORYTYPE_HOST;
253            m.dst_host = dst.cast();
254            m.dst_pitch = width;
255            m.width_in_bytes = width;
256            m.height = rows;
257            check("cuMemcpy2D", unsafe { (cuda.memcpy_2d)(&m) })
258        };
259        let r = copy(
260            dptr,
261            left as usize * bps,
262            top as usize,
263            luma.as_mut_ptr(),
264            w * bps,
265            h,
266        )
267        .and_then(|_| {
268            let uv = dptr + (pitch * ((surface_h + 1) & !1)) as u64;
269            copy(
270                uv,
271                (left as usize & !1) * bps,
272                top as usize / 2,
273                chroma.as_mut_ptr(),
274                w.div_ceil(2) * 2 * bps,
275                h.div_ceil(2),
276            )
277        });
278        unsafe { (self.cuvid.unmap)(self.decoder, dptr) };
279        r?;
280        // Both copies wrote whole rows, `width` bytes apart, over each
281        // buffer's length.
282        unsafe { luma.set_len(luma_len) };
283        unsafe { chroma.set_len(chroma_len) };
284
285        let vsd = fmt.video_signal_description;
286        let full_range = vsd[0] & 0x08 != 0;
287        Ok(PackedFrame {
288            width: w as u32,
289            height: h as u32,
290            bit_depth: 8 + fmt.bit_depth_luma_minus8,
291            y: luma,
292            uv: chroma,
293            color: ColorInfo::from_vui(Some(vsd[3] as u32), full_range, h as u32),
294        })
295    }
296
297    fn picture(&mut self, index: c_int) -> c_int {
298        match unsafe { self.copy_out(index) } {
299            Ok(f) => {
300                self.ready.push((self.pts + self.copied, f));
301                self.copied += 1;
302                1
303            }
304            Err(e) => self.fail(e),
305        }
306    }
307}
308
309unsafe extern "C" fn on_sequence(user: *mut c_void, fmt: *mut VideoFormat) -> c_int {
310    let s = unsafe { &mut *(user as *mut State) };
311    let f = unsafe { *fmt };
312    if f.chroma_format != CHROMA_420 {
313        return s.fail(format!(
314            "NVDEC path handles 4:2:0 only (chroma format {})",
315            f.chroma_format
316        ));
317    }
318    let surfaces = (f.min_num_decode_surfaces as c_ulong).max(1) + 4;
319    if !s.decoder.is_null() {
320        unsafe { (s.cuvid.destroy_decoder)(s.decoder) };
321        s.decoder = std::ptr::null_mut();
322    }
323    let mut ci: CreateInfo = unsafe { std::mem::zeroed() };
324    ci.width = f.coded_width as c_ulong;
325    ci.height = f.coded_height as c_ulong;
326    ci.max_width = ci.width;
327    ci.max_height = ci.height;
328    ci.num_decode_surfaces = surfaces;
329    ci.codec_type = f.codec;
330    ci.chroma_format = f.chroma_format;
331    ci.creation_flags = CREATE_PREFER_CUVID;
332    ci.bit_depth_minus8 = f.bit_depth_luma_minus8 as c_ulong;
333    ci.output_format = if f.bit_depth_luma_minus8 > 0 {
334        SURFACE_P016
335    } else {
336        SURFACE_NV12
337    };
338    // Copies cover the display area themselves; the output surface is the
339    // whole coded picture so the offsets mean the same on every driver.
340    ci.display_area = [0, 0, f.coded_width as c_short, f.coded_height as c_short];
341    ci.target_width = ci.width;
342    ci.target_height = ci.height;
343    ci.num_output_surfaces = 2;
344    let r = unsafe { (s.cuvid.create_decoder)(&mut s.decoder, &mut ci) };
345    if r != 0 {
346        return s.fail(format!(
347            "cuvidCreateDecoder failed (CUDA error {r}): {}x{} codec {}",
348            f.coded_width, f.coded_height, f.codec
349        ));
350    }
351    s.format = Some(f);
352    surfaces as c_int
353}
354
355unsafe extern "C" fn on_decode(user: *mut c_void, pic: *mut c_void) -> c_int {
356    let s = unsafe { &mut *(user as *mut State) };
357    if s.decoder.is_null() {
358        return s.fail("a picture before the decoder was created".into());
359    }
360    let r = unsafe { (s.cuvid.decode_picture)(s.decoder, pic) };
361    if r != 0 {
362        return s.fail(format!("cuvidDecodePicture failed (CUDA error {r})"));
363    }
364    if s.on_display {
365        return 1;
366    }
367    let index = unsafe {
368        *(pic as *const u8)
369            .add(PICPARAMS_CURR_PIC_IDX)
370            .cast::<c_int>()
371    };
372    s.picture(index)
373}
374
375unsafe extern "C" fn on_display(user: *mut c_void, info: *mut DispInfo) -> c_int {
376    let s = unsafe { &mut *(user as *mut State) };
377    if info.is_null() || !s.on_display {
378        return 1;
379    }
380    s.picture(unsafe { (*info).picture_index })
381}
382
383/// A hardware decoder on an NVIDIA GPU's NVDEC engine, with the interface of
384/// [`NativeDecoder`](crate::decode::NativeDecoder): open it from a demuxed
385/// track, push samples in decode order, take pictures by presentation time.
386///
387/// H.264, HEVC (8- and 10-bit), VP9 and AV1, in 4:2:0, as far as the GPU's
388/// generation decodes them (AV1 from Ampere on).
389pub struct NvdecDecoder {
390    // Field order is drop order: parser and decoder before the context.
391    parser: Parser,
392    state: Box<State>,
393    ctx: Context,
394    codec: TrackCodec,
395    nal_len: usize,
396    /// Parameter sets (or AV1 config OBUs) to put in front of the first sample.
397    prefix: Option<Vec<u8>>,
398    width: u32,
399    height: u32,
400    buf: Vec<u8>,
401}
402
403impl NvdecDecoder {
404    /// Open a session for `track`'s codec and configuration.
405    pub fn new(track: &VideoTrack) -> Result<Self, String> {
406        let cuvid = cuvid().ok_or("no NVIDIA GPU or driver with NVDEC")?;
407        let ctx = Context::new()?;
408        let (codec_type, nal_len, prefix) = match track.codec {
409            TrackCodec::H264 => {
410                let (sets, n) = crate::decode::split_avcc(&track.config)?;
411                (CODEC_H264, n, Some(annexb(&sets)))
412            }
413            TrackCodec::Hevc => {
414                let (sets, n) = crate::decode::split_hvcc(&track.config)?;
415                (CODEC_HEVC, n, Some(annexb(&sets)))
416            }
417            TrackCodec::Vp9 => (CODEC_VP9, 0, None),
418            // `av1C`: four bytes of header, then the configuration OBUs
419            // (normally the sequence header).
420            TrackCodec::Av1 => (
421                CODEC_AV1,
422                0,
423                track
424                    .config
425                    .get(4..)
426                    .filter(|o| !o.is_empty())
427                    .map(<[u8]>::to_vec),
428            ),
429        };
430        let mut state = Box::new(State {
431            cuvid,
432            decoder: std::ptr::null_mut(),
433            format: None,
434            on_display: matches!(track.codec, TrackCodec::Vp9 | TrackCodec::Av1),
435            pts: 0,
436            copied: 0,
437            ready: Vec::new(),
438            error: None,
439            pool: Default::default(),
440        });
441        let mut params: ParserParams = unsafe { std::mem::zeroed() };
442        params.codec_type = codec_type;
443        params.max_num_decode_surfaces = 1;
444        params.clock_rate = 0;
445        params.max_display_delay = 0;
446        params.user_data = (&mut *state as *mut State).cast();
447        params.sequence = Some(on_sequence);
448        params.decode = Some(on_decode);
449        params.display = Some(on_display);
450        let mut parser = std::ptr::null_mut();
451        ctx.with(|| {
452            check("cuvidCreateVideoParser", unsafe {
453                (cuvid.create_parser)(&mut parser, &mut params)
454            })
455        })?;
456        Ok(NvdecDecoder {
457            parser,
458            state,
459            ctx,
460            codec: track.codec,
461            nal_len,
462            prefix,
463            width: track.width,
464            height: track.height,
465            buf: Vec::new(),
466        })
467    }
468
469    /// Size of the track, as the container states it.
470    pub fn size(&self) -> (u32, u32) {
471        (self.width, self.height)
472    }
473
474    /// Hand one coded frame to the decoder, in decode order: an MP4 sample
475    /// (length-prefixed NAL units), a VP9 frame or superframe, or an AV1
476    /// temporal unit. Its picture is copied to the host before this returns.
477    pub fn push(
478        &mut self,
479        sample: &[u8],
480        pts: i64,
481        _dts: i64,
482        _duration: i64,
483    ) -> Result<(), String> {
484        self.buf.clear();
485        if let Some(p) = self.prefix.take() {
486            self.buf.extend_from_slice(&p);
487        }
488        match self.codec {
489            TrackCodec::H264 | TrackCodec::Hevc => {
490                for nal in crate::decode::bits::split_length_prefixed(sample, self.nal_len)? {
491                    self.buf.extend_from_slice(&[0, 0, 0, 1]);
492                    self.buf.extend_from_slice(nal);
493                }
494            }
495            TrackCodec::Vp9 | TrackCodec::Av1 => self.buf.extend_from_slice(sample),
496        }
497        self.state.pts = pts;
498        self.state.copied = 0;
499        let mut pkt = Packet {
500            flags: PKT_TIMESTAMP | PKT_ENDOFPICTURE,
501            payload_size: self.buf.len() as c_ulong,
502            payload: self.buf.as_ptr(),
503            timestamp: pts,
504        };
505        let cuvid = self.state.cuvid;
506        let parser = self.parser;
507        let r = self.ctx.with(|| unsafe { (cuvid.parse)(parser, &mut pkt) });
508        if let Some(e) = self.state.error.take() {
509            return Err(e);
510        }
511        check("cuvidParseVideoData", r)
512    }
513
514    /// The picture for presentation time `pts` as tightly packed BGRA, if it
515    /// has been decoded. Frames before `pts` are dropped on the way past.
516    pub fn take(&mut self, pts: i64) -> Option<Vec<u8>> {
517        self.take_frame(pts).map(|f| f.to_bgra())
518    }
519
520    /// [`take`](Self::take), but the planes at the stream's bit depth.
521    pub fn take_frame(&mut self, pts: i64) -> Option<DecodedFrame> {
522        self.take_packed(pts).map(|f| f.to_decoded())
523    }
524
525    /// [`take`](Self::take), as the decoder left the picture: NV12, or P016
526    /// above 8 bits. No pass over the pixels; for a caller converting on the
527    /// GPU.
528    /// Copy pictures into buffers from `pool` (see
529    /// [`FramePool`](crate::bytes::FramePool)), to be given back there.
530    pub fn set_pool(&mut self, pool: crate::bytes::FramePool) {
531        self.state.pool = pool;
532    }
533
534    pub fn take_packed(&mut self, pts: i64) -> Option<PackedFrame> {
535        let ready = &mut self.state.ready;
536        let hit = ready.iter().position(|(p, _)| *p == pts)?;
537        let (_, frame) = ready.remove(hit);
538        ready.retain(|(p, _)| *p > pts);
539        Some(frame)
540    }
541}
542
543impl Drop for NvdecDecoder {
544    fn drop(&mut self) {
545        let cuvid = self.state.cuvid;
546        let (parser, decoder) = (self.parser, self.state.decoder);
547        self.ctx.with(|| unsafe {
548            if !parser.is_null() {
549                (cuvid.destroy_parser)(parser);
550            }
551            if !decoder.is_null() {
552                (cuvid.destroy_decoder)(decoder);
553            }
554        });
555    }
556}
557
558/// Parameter sets as an Annex B prefix.
559fn annexb(sets: &[&[u8]]) -> Vec<u8> {
560    let mut out = Vec::new();
561    for s in sets {
562        out.extend_from_slice(&[0, 0, 0, 1]);
563        out.extend_from_slice(s);
564    }
565    out
566}