f67d38b35cc5
export.rs
//! NVENC as an Export encoder: [`factory`] is registered in front of the software H.264 encoder
//! (`filmcraft_export::register_encoder`).
//!
//! - H.264: it takes an export only when Export ▸ Hardware encoding is Auto and NVENC can do what
//! the settings ask; otherwise it returns `None` and the software encoder runs, exactly as before.
//! - H.265 (HEVC Main 8-bit 4:2:0 SDR BT.709, or Main 10 HDR: 10-bit 4:2:0, BT.2020, PQ or HLG, limited
//! range; progressive): there is no software encoder, so the Hardware encoding toggle does not apply
//! (as with VideoToolbox) and choosing the format is the opt-in. The export crate hands HDR pictures
//! over (`EncoderFrame::hdr`) only where [`super::hevc_hdr_available`] said this GPU has a 10-bit
//! encoder, otherwise an HDR sequence is tone-mapped to SDR as before. What NVENC cannot do
//! (interlaced, two-pass, non-square pixels, 10-bit on a GPU without it, sizes outside its
//! limits...) is counted as declined and ends the export with an error that says why; when this
//! machine has no HEVC encoder at all, [`filmcraft_export::available`] says so and the factory
//! returns `None` (the export's own "encoder not available" error).
//!
//! A hardware encoder that fails in the middle of an export (a lost device) ends the export with an
//! error naming it; unlike a decoder it cannot be replayed into the software encoder, because the
//! two write different streams.
use filmcraft_export::{
BitrateMode, ColorSignal, EncodedPacket, EncoderFrame, ExportError, ExportSettings, FieldOrder, Format, H264Pass, H264Profile, HardwareEncoding, Result,
VideoEncoder,
};
use filmcraft_isobmff::{AvcConfig, SampleEntry};
use filmcraft_time::FrameRate;
use super::{Codec, Config, Nvenc, Profile, Sei, Signal};
/// The NVENC export encoder.
struct NvencEncoder {
enc: Nvenc,
w: u32,
h: u32,
rate: FrameRate,
/// The stream's colour signal (`colr` / `mdcv` / `clli` on the sample entry for HDR).
signal: ColorSignal,
y: Vec<u8>,
u: Vec<u8>,
v: Vec<u8>,
/// Main 10: the 10-bit planes of the current picture.
y16: Vec<u16>,
u16: Vec<u16>,
v16: Vec<u16>,
}
/// SEI payload types of the HDR10 static metadata (H.265 Annex D): mastering display colour volume
/// and content light level information.
const SEI_MASTERING_DISPLAY: u32 = 137;
const SEI_CONTENT_LIGHT_LEVEL: u32 = 144;
/// The encoder's signal for an export's colour signal: the VUI code points and, for PQ, the HDR10
/// static metadata as SEI messages (the same values and bytes the `mdcv` / `clli` boxes and the software
/// H.264 encoder's SEI carry: [`ColorSignal::static_metadata`]). HLG has no static metadata.
pub fn nvenc_signal(signal: &ColorSignal) -> Signal {
let mut sei = Vec::new();
if let Some((md, (max_cll, max_fall))) = signal.static_metadata() {
sei.push(Sei { payload_type: SEI_MASTERING_DISPLAY, payload: md.to_bytes() });
let mut cll = max_cll.to_be_bytes().to_vec();
cll.extend_from_slice(&max_fall.to_be_bytes());
sei.push(Sei { payload_type: SEI_CONTENT_LIGHT_LEVEL, payload: cll });
}
Signal { primaries: signal.primaries, transfer: signal.transfer, matrix: signal.matrix, sei }
}
fn new_encoder(enc: Nvenc, w: u32, h: u32, rate: FrameRate, signal: ColorSignal) -> NvencEncoder {
NvencEncoder { enc, w, h, rate, signal, y: Vec::new(), u: Vec::new(), v: Vec::new(), y16: Vec::new(), u16: Vec::new(), v16: Vec::new() }
}
impl NvencEncoder {
fn packets(&self, ps: Vec<super::Packet>) -> Vec<EncodedPacket> {
let den = self.rate.den;
let duration = u32::try_from(den).unwrap_or(u32::MAX);
ps.into_iter().map(|p| EncodedPacket { data: p.data, key: p.key, duration, composition_offset: composition_offset(p.pts, p.dts, den) }).collect()
}
}
/// `(pts - dts) × den` as an MP4 composition offset. It is a few frames (the B-frame delay); a
/// hostile value saturates instead of wrapping.
fn composition_offset(pts: i64, dts: i64, den: i64) -> i32 {
let offset = pts.saturating_sub(dts).saturating_mul(den);
i32::try_from(offset).unwrap_or(if offset < 0 { i32::MIN } else { i32::MAX })
}
impl VideoEncoder for NvencEncoder {
fn sample_entry(&self) -> SampleEntry {
let (sps, pps) = self.enc.parameter_sets();
// `config` declines sizes above u16::MAX
let (w, h) = (u16::try_from(self.w).unwrap_or(u16::MAX), u16::try_from(self.h).unwrap_or(u16::MAX));
match self.enc.codec() {
Codec::H264 => SampleEntry::avc(AvcConfig::new(vec![sps.to_vec()], vec![pps.to_vec()], 4), w, h),
Codec::Hevc => {
// `Nvenc::new` built and validated the record, so there is always one for HEVC
let mut e = SampleEntry::hevc(self.enc.hevc_config().cloned().unwrap_or_default(), w, h);
// HDR: `colr` (BT.2020 + PQ / HLG) and, for PQ, `mdcv` / `clli`, as the software H.264 encoder does
// (nclx, whatever the container: readers take it from either). SDR gets a BT.709 `colr` only (#2142).
self.signal.apply_to(&mut e, false);
e
}
}
}
fn timescale(&self) -> u32 {
u32::try_from(self.rate.num).unwrap_or(u32::MAX)
}
fn encode(&mut self, f: &EncoderFrame) -> Result<Vec<EncodedPacket>> {
if f.width != self.w || f.height != self.h {
return Err(ExportError::Encode(format!("NVENC: a {}x{} picture for a {}x{} encoder", f.width, f.height, self.w, self.h)));
}
let (w, h) = (self.w as usize, self.h as usize);
let hint = if self.enc.codec() == Codec::H264 { " (turn Export > Hardware encoding off to use the software encoder)" } else { "" };
let ps = match (self.enc.is_ten_bit(), f.hdr) {
// Main 10 takes the encoded R'G'B' floats: 10-bit limited-range BT.2020 NCL (or the signal's matrix)
(true, Some(rgb)) => {
let (kr, kb) = self.signal.kr_kb();
filmcraft_export::timed(filmcraft_export::Stage::Convert, || {
filmcraft_export::rgbf_to_yuv420_10(rgb, w, h, filmcraft_export::Matrix::new(kr, kb), &mut self.y16, &mut self.u16, &mut self.v16)
})?;
self.enc.encode_10(&self.y16, &self.u16, &self.v16, f.index).map_err(|e| ExportError::Encode(format!("NVENC: {e}{hint}")))?
}
(true, None) => return Err(ExportError::Unsupported("NVENC Main 10 needs the HDR picture (EncoderFrame::hdr)".into())),
(false, Some(_)) => return Err(ExportError::Unsupported("NVENC Main (8-bit) does not take HDR pictures".into())),
// the GPU converts the RGBA picture itself (BT.709 limited range, the same codes as `rgba_to_yuv420_8`)
(false, None) if self.enc.takes_rgba() => self.enc.encode_rgba(f.rgba, f.index).map_err(|e| ExportError::Encode(format!("NVENC: {e}{hint}")))?,
(false, None) => {
filmcraft_export::timed(filmcraft_export::Stage::Convert, || {
filmcraft_export::rgba_to_yuv420_8(f.rgba, w, h, &mut self.y, &mut self.u, &mut self.v)
});
self.enc.encode(&self.y, &self.u, &self.v, f.index).map_err(|e| ExportError::Encode(format!("NVENC: {e}{hint}")))?
}
};
filmcraft_export::note_hw_encode_frame();
Ok(self.packets(ps))
}
fn flush(&mut self) -> Result<Vec<EncodedPacket>> {
let ps = self.enc.flush().map_err(|e| ExportError::Encode(format!("NVENC: {e}")))?;
Ok(self.packets(ps))
}
fn media_start(&self) -> Option<i64> {
// with B-frames the first DTS is `delay` frames before the first PTS
(self.enc.delay() > 0).then_some(i64::from(self.enc.delay()).saturating_mul(self.rate.den))
}
fn hardware(&self) -> Option<&'static str> {
Some("NVENC")
}
}
/// Why NVENC does not take this export (the software encoder does, for H.264), or the encoder's
/// configuration.
fn config(format: Format, w: u32, h: u32, rate: FrameRate, s: &ExportSettings) -> std::result::Result<Config, String> {
let hevc = format == Format::Hevc;
if !(format == Format::H264 || hevc) || s.format.is_mxf() {
return Err("only MP4 / MOV H.264 and H.265 exports".into());
}
let hdr = s.signal.is_hdr();
if hdr && !hevc {
return Err("HDR (8-bit H.264 here carries it with software signalling)".into());
}
// HEVC: BT.709 SDR (Main) or BT.2020 NCL with PQ / HLG (Main 10); any other description is not written
if hevc && (hdr && (s.signal.primaries != 9 || s.signal.matrix != 9) || !hdr && s.signal != ColorSignal::default()) {
return Err(format!("the colour signal {:?} (H.265 here is BT.709, or BT.2020 with PQ / HLG)", s.signal));
}
if !matches!(s.h264_pass, H264Pass::Single) || (hevc && s.bitrate_mode == BitrateMode::Vbr2Pass) {
return Err("two-pass VBR".into());
}
if s.bitrate_mode == BitrateMode::Crf {
return Err("CRF (constant quality)".into());
}
if !hevc && s.h264_intra_only {
return Err("all-intra H.264".into());
}
// the hardware path writes the aspect ratio of H.264 only
if hevc && s.pixel_aspect.is_some_and(|(n, d)| n != d) {
return Err("non-square pixels".into());
}
if s.field_order != FieldOrder::Progressive {
return Err("interlaced output".into());
}
if w == 0 || h == 0 || !w.is_multiple_of(2) || !h.is_multiple_of(2) {
return Err("NVENC needs nonzero even dimensions".into());
}
if w > u32::from(u16::MAX) || h > u32::from(u16::MAX) {
return Err(format!("{w}x{h} does not fit an MP4 sample entry"));
}
if rate.num <= 0 || rate.den <= 0 || rate.num > i64::from(u32::MAX) || rate.den > i64::from(u32::MAX) {
return Err("frame rate".into());
}
let (Ok(num), Ok(den)) = (u32::try_from(rate.num), u32::try_from(rate.den)) else {
return Err("frame rate".into());
};
let fps = (num, den);
let kbps = s.bitrate_kbps.max(100);
Ok(Config {
width: w,
height: h,
fps,
bitrate_kbps: kbps,
max_bitrate_kbps: s.max_bitrate_kbps.filter(|m| *m >= kbps).unwrap_or_else(|| kbps.saturating_add(kbps / 2)),
cbr: s.bitrate_mode == BitrateMode::Cbr,
keyint: s.keyframe_distance.filter(|k| *k > 0).unwrap_or_else(|| (f64::from(fps.0) / f64::from(fps.1) * 2.0).round().max(1.0) as u32),
profile: match (hevc, s.h264_profile) {
(true, _) if hdr => Profile::HevcMain10,
(true, _) => Profile::HevcMain,
(false, H264Profile::Baseline) => Profile::Baseline,
(false, H264Profile::Main) => Profile::Main,
(false, H264Profile::High) => Profile::High,
// 10-bit H.264 and all-intra streams are the built-in encoder's
(false, H264Profile::High10) => return Err("High 10".into()),
},
// the H.264 level setting means nothing for H.265: the encoder picks the level
level: if hevc { None } else { s.h264_level },
sar: s.pixel_aspect,
bframes: true,
})
}
/// The Export encoder factory (see the module documentation).
pub fn factory(format: Format, w: u32, h: u32, rate: FrameRate, s: &ExportSettings) -> Option<Result<Box<dyn VideoEncoder>>> {
if format == Format::Hevc {
// H.265 through NVENC is Windows-only for now; on Linux this backend takes H.264 only
return if cfg!(target_os = "windows") { hevc_factory(w, h, rate, s) } else { None };
}
factory_with(format, w, h, rate, s, |cfg| open(cfg, &Signal::default()))
}
/// Open the encoder for `cfg`. An 8-bit one takes the export's RGBA pictures as they are and converts
/// them on the GPU, which keeps the RGB → 4:2:0 conversion off the CPU (where it competes with the
/// render of the next frames); where the driver refuses RGB input, it takes the CPU's 4:2:0 as before.
/// Main 10 takes its 10-bit planes.
fn open(cfg: &Config, signal: &Signal) -> std::result::Result<Nvenc, String> {
if cfg.profile == Profile::HevcMain10 {
return Nvenc::with_signal(cfg, signal);
}
Nvenc::with_rgba_input(cfg, signal).or_else(|why| {
log::info!("NVENC RGBA input declined ({why}): converting to 4:2:0 on the CPU");
Nvenc::with_signal(cfg, signal)
})
}
/// The H.264 side of [`factory`], with the driver call (`open`) passed in so tests can stand in for it.
fn factory_with(
format: Format,
w: u32,
h: u32,
rate: FrameRate,
s: &ExportSettings,
open: impl FnOnce(&Config) -> std::result::Result<Nvenc, String>,
) -> Option<Result<Box<dyn VideoEncoder>>> {
if s.hardware_encoding != HardwareEncoding::Auto || format != Format::H264 {
return None;
}
let declined = |why: &str| {
log::info!("hardware encoding declined: {why}");
filmcraft_export::note_hw_encode_declined_by("NVENC", why);
None
};
let cfg = match config(format, w, h, rate, s) {
Ok(c) => c,
Err(why) => return declined(&why),
};
match open(&cfg) {
Ok(enc) => {
filmcraft_export::note_hw_encode_session();
Some(Ok(Box::new(new_encoder(enc, w, h, rate, s.signal))))
}
Err(why) => declined(&why),
}
}
/// The H.265 side of [`factory`]: FilmCraft's only HEVC encoder on Windows, so the Hardware encoding toggle
/// does not apply and a request NVENC cannot take is an error, not a fall-through.
fn hevc_factory(w: u32, h: u32, rate: FrameRate, s: &ExportSettings) -> Option<Result<Box<dyn VideoEncoder>>> {
let declined = |why: &str| {
log::info!("hardware H.265 encoding declined: {why}");
filmcraft_export::note_hw_encode_declined();
Some(Err(ExportError::Unsupported(format!("H.265 export with NVENC: {why}"))))
};
let cfg = match config(Format::Hevc, w, h, rate, s) {
Ok(c) => c,
Err(why) => return declined(&why),
};
match open(&cfg, &nvenc_signal(&s.signal)) {
Ok(enc) => {
filmcraft_export::note_hw_encode_session();
Some(Ok(Box::new(new_encoder(enc, w, h, rate, s.signal))))
}
// no HEVC encoder here at all: not a hardware attempt, the export's own "encoder not available" error
Err(why) if !super::hevc_available() => {
log::info!("no hardware H.265 encoder: {why}");
None
}
Err(why) => declined(&why),
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn off_and_unsupported_settings_never_open_the_driver() {
let declined = |format, w, h, s: &ExportSettings| {
assert!(factory_with(format, w, h, FrameRate::FPS_24, s, |_| panic!("must not open the driver")).is_none());
};
let mut s = ExportSettings { hardware_encoding: HardwareEncoding::Off, ..Default::default() };
declined(Format::H264, 640, 360, &s);
s.hardware_encoding = HardwareEncoding::Auto;
declined(Format::ProRes, 640, 360, &s);
declined(Format::H264, 641, 360, &s);
declined(Format::H264, 0, 360, &s);
s.h264_pass = H264Pass::First;
declined(Format::H264, 640, 360, &s);
s.h264_pass = H264Pass::Single;
s.field_order = FieldOrder::UpperFirst;
declined(Format::H264, 640, 360, &s);
s.field_order = FieldOrder::Progressive;
// 10-bit and all-intra H.264 are the built-in encoder's (#1221)
declined(Format::H264, 640, 360, &ExportSettings { h264_profile: H264Profile::High10, ..s.clone() });
declined(Format::H264, 640, 360, &ExportSettings { h264_intra_only: true, ..s.clone() });
}
#[test]
fn missing_or_rejecting_driver_declines_for_software_fallback() {
let s = ExportSettings { hardware_encoding: HardwareEncoding::Auto, ..Default::default() };
let mut attempted = false;
assert!(
factory_with(Format::H264, 640, 360, FrameRate::FPS_24, &s, |cfg| {
attempted = true;
assert_eq!((cfg.width, cfg.height), (640, 360));
Err("no NVIDIA encoder driver".into())
})
.is_none()
);
assert!(attempted);
}
#[test]
fn bitrate_ceiling_does_not_wrap() {
let s = ExportSettings { bitrate_kbps: u32::MAX, ..Default::default() };
assert_eq!(config(Format::H264, 640, 360, FrameRate::FPS_24, &s).unwrap().max_bitrate_kbps, u32::MAX);
}
#[test]
fn composition_offsets_saturate() {
assert_eq!(composition_offset(3, 1, 1001), 2002);
assert_eq!(composition_offset(0, -2, 1001), 2002);
assert_eq!(composition_offset(i64::MAX, i64::MIN, 1001), i32::MAX);
assert_eq!(composition_offset(i64::MIN, i64::MAX, 1001), i32::MIN);
assert_eq!(composition_offset(1 << 40, 0, 1), i32::MAX);
}
#[test]
fn hevc_takes_what_nvenc_can_write_and_declines_the_rest() {
let ok = ExportSettings { format: Format::Hevc, bitrate_kbps: 4000, keyframe_distance: Some(48), ..Default::default() };
let c = config(Format::Hevc, 1280, 720, FrameRate::FPS_24, &ok).unwrap();
assert_eq!((c.profile, c.level, c.keyint, c.fps), (Profile::HevcMain, None, 48, (24, 1)));
// the H.264 level and profile settings mean nothing to HEVC
let h = ExportSettings { h264_level: Some(41), h264_profile: H264Profile::Baseline, ..ok.clone() };
assert_eq!(config(Format::Hevc, 1280, 720, FrameRate::FPS_24, &h).unwrap().level, None);
// HDR (PQ / HLG, BT.2020) is Main 10, SDR stays Main; H.264 still declines HDR
for signal in [ColorSignal::PQ, ColorSignal::HLG] {
let hdr = ExportSettings { signal, ..ok.clone() };
assert_eq!(config(Format::Hevc, 1280, 720, FrameRate::FPS_24, &hdr).unwrap().profile, Profile::HevcMain10);
assert!(config(Format::H264, 1280, 720, FrameRate::FPS_24, &ExportSettings { format: Format::H264, ..hdr }).is_err());
}
// the Hardware encoding toggle does not matter for HEVC (it has no software encoder)
let off = ExportSettings { hardware_encoding: HardwareEncoding::Off, ..ok.clone() };
assert!(config(Format::Hevc, 1280, 720, FrameRate::FPS_24, &off).is_ok());
for (what, s) in [
("an unwritable colour signal", ExportSettings { signal: ColorSignal { primaries: 9, transfer: 1, matrix: 1 }, ..ok.clone() }),
("HDR with BT.709 primaries", ExportSettings { signal: ColorSignal { primaries: 1, transfer: 16, matrix: 9 }, ..ok.clone() }),
("two-pass", ExportSettings { bitrate_mode: BitrateMode::Vbr2Pass, ..ok.clone() }),
("CRF", ExportSettings { bitrate_mode: BitrateMode::Crf, ..ok.clone() }),
("analysis pass", ExportSettings { h264_pass: H264Pass::First, ..ok.clone() }),
("interlaced", ExportSettings { field_order: FieldOrder::UpperFirst, ..ok.clone() }),
("non-square pixels", ExportSettings { pixel_aspect: Some((4, 3)), ..ok.clone() }),
("MXF", ExportSettings { format: Format::MxfOp1a, ..ok.clone() }),
] {
assert!(config(Format::Hevc, 1280, 720, FrameRate::FPS_24, &s).is_err(), "{what}");
}
// hostile sizes and frame rates
assert!(config(Format::Hevc, 70_000, 64, FrameRate::FPS_24, &ok).is_err());
assert!(config(Format::Hevc, 64, 70_000, FrameRate::FPS_24, &ok).is_err());
for rate in [FrameRate { num: 0, den: 1 }, FrameRate { num: 24, den: 0 }, FrameRate { num: -24, den: 1 }, FrameRate { num: i64::MAX, den: 1 }] {
assert!(config(Format::Hevc, 1280, 720, rate, &ok).is_err(), "{rate:?}");
}
// other formats are not NVENC's
assert!(config(Format::ProRes, 1280, 720, FrameRate::FPS_24, &ok).is_err());
}
#[test]
fn the_sei_messages_are_the_hdr10_static_metadata_the_software_h264_path_writes() {
let pq = nvenc_signal(&ColorSignal::PQ);
assert_eq!((pq.primaries, pq.transfer, pq.matrix), (9, 16, 9));
assert_eq!(pq.sei.len(), 2);
// mastering display colour volume (137): the 24-byte payload of ST 2086, the `mdcv` box's bytes
let (md, _) = ColorSignal::PQ.static_metadata().unwrap();
assert_eq!((pq.sei[0].payload_type, pq.sei[0].payload.as_slice()), (137, md.to_bytes().as_slice()));
assert_eq!(pq.sei[0].payload.len(), 24);
// BT.2020 primaries (G, B, R order), D65, 1000 / 0.0001 cd/m2 in 0.0001 units
assert_eq!(
pq.sei[0].payload,
[0x21, 0x34, 0x9B, 0xAA, 0x19, 0x96, 0x08, 0xFC, 0x8A, 0x48, 0x39, 0x08, 0x3D, 0x13, 0x40, 0x42, 0x00, 0x98, 0x96, 0x80, 0x00, 0x00, 0x00, 0x01]
);
// content light level (144): MaxCLL 0, MaxFALL 0 (unknown)
assert_eq!((pq.sei[1].payload_type, pq.sei[1].payload.as_slice()), (144, &[0u8, 0, 0, 0][..]));
// laid out as one SEI RBSP (type, size, payload, ...) these are the bytes the software H.264 encoder
// writes for the same metadata (checked against its real output in the export crate's hdr_tests)
let rbsp: Vec<u8> =
pq.sei.iter().flat_map(|m| [m.payload_type as u8, m.payload.len() as u8].into_iter().chain(m.payload.iter().copied())).chain([0x80]).collect();
assert_eq!(&rbsp[..2], &[137, 24]);
assert_eq!(&rbsp[26..], &[144, 4, 0, 0, 0, 0, 0x80]);
// HLG: the colour description only; SDR: BT.709, no messages
let hlg = nvenc_signal(&ColorSignal::HLG);
assert_eq!((hlg.primaries, hlg.transfer, hlg.matrix, hlg.sei.len()), (9, 18, 9, 0));
assert_eq!(nvenc_signal(&ColorSignal::default()), Signal::default());
}
#[test]
fn oversized_pictures_are_declined() {
let s = ExportSettings { format: Format::H264, hardware_encoding: HardwareEncoding::Auto, ..Default::default() };
assert!(config(Format::H264, 70_000, 64, FrameRate::FPS_24, &s).is_err());
assert!(config(Format::H264, 64, 70_000, FrameRate::FPS_24, &s).is_err());
}
}
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.