@desklink/host 0.2.0 → 0.3.1

package/engine/src/encoder.rs

@@ -7,10 +7,12 @@
 //! and would put a driver dependency on the machine class.
 //!
 //! Tuned for a desktop rather than a camera: screen-content mode, key frames
-//! only on request, and a refinement pass. While the desktop moves, frames are
+//! on request and when the coded size changes, and a refinement pass. While the desktop moves, frames are
 //! coded against the rate target; once it stops, the last frame is coded once
 //! more under a low quantizer ceiling, so what the user reads is sharp without
-//! paying for sharpness on every frame of a scroll.
+//! paying for sharpness on every frame of a scroll. Motion the encoder cannot
+//! code within a frame interval may be coded at half size; the refinement pass
+//! is always full size.
 
 use crate::convert::I420;
 use anyhow::Result;
@@ -30,7 +32,12 @@ extern "C" {
         threads: c_int,
         cpu_used: c_int,
     ) -> *mut NativeEncoder;
-    fn dl_vpx_encode(encoder: *mut NativeEncoder, i420: *const u8, force_keyframe: c_int) -> c_int;
+    fn dl_vpx_encode(
+        encoder: *mut NativeEncoder,
+        i420: *const u8,
+        force_keyframe: c_int,
+        half: c_int,
+    ) -> c_int;
     fn dl_vpx_reconfigure(
         encoder: *mut NativeEncoder,
         bitrate_kbps: c_int,
@@ -47,9 +54,9 @@ extern "C" {
 /// that small text is crisp; the pass happens once per still, not per frame.
 const REFINE_MAX_Q: c_int = 10;
 
-/// libvpx's speed/quality trade for real time. 8 codes a 4K desktop frame well
-/// inside a 30 fps budget on a desktop CPU.
-const CPU_USED: c_int = 8;
+/// libvpx's speed/quality trade for real time. 9 codes full-screen motion at
+/// 1080p in about half the CPU time of 8, and a refined still reads the same.
+const CPU_USED: c_int = 9;
 
 /// One encoded VP9 frame as libvpx produced it.
 pub struct EncodedFrame {
@@ -122,7 +129,7 @@ impl Encoder {
         if unsafe { dl_vpx_reconfigure(self.native, bitrate, REFINE_MAX_Q) } != 0 {
             anyhow::bail!("libvpx refused the refinement ceiling");
         }
-        let packet = self.encode(frame, false);
+        let packet = self.encode(frame, false, false);
         let restored = unsafe { dl_vpx_reconfigure(self.native, bitrate, dl_vpx_motion_max_q()) };
         if restored != 0 {
             anyhow::bail!("libvpx refused to restore the motion ceiling");
@@ -130,7 +137,14 @@ impl Encoder {
         packet
     }
 
-    pub fn encode(&mut self, frame: &I420, force_keyframe: bool) -> Result<EncodedFrame> {
+    /// Code `frame`; with `half`, at half its width and height. Changing the
+    /// coded size makes this frame a key frame.
+    pub fn encode(
+        &mut self,
+        frame: &I420,
+        force_keyframe: bool,
+        half: bool,
+    ) -> Result<EncodedFrame> {
         if frame.width != self.width || frame.height != self.height {
             anyhow::bail!(
                 "encoder is {}x{} but was given {}x{}",
@@ -140,8 +154,14 @@ impl Encoder {
                 frame.height
             );
         }
-        let status =
-            unsafe { dl_vpx_encode(self.native, frame.data.as_ptr(), force_keyframe as c_int) };
+        let status = unsafe {
+            dl_vpx_encode(
+                self.native,
+                frame.data.as_ptr(),
+                force_keyframe as c_int,
+                half as c_int,
+            )
+        };
         if status < 0 {
             anyhow::bail!("libvpx rejected a {}x{} frame", self.width, self.height);
         }
@@ -162,6 +182,69 @@ impl Encoder {
     }
 }
 
+/// Whichever encoder a session's answer chose: VP9, which every session
+/// starts with, or H.264 once a receiver prefers it (see `crate::h264`).
+pub enum VideoEncoder {
+    Vp9(Encoder),
+    H264 {
+        backend: Box<dyn crate::h264::Backend>,
+        size: (usize, usize),
+    },
+}
+
+impl VideoEncoder {
+    /// `half` is VP9's: H.264 codes every frame at full size.
+    pub fn encode(&mut self, frame: &I420, keyframe: bool, half: bool) -> Result<EncodedFrame> {
+        match self {
+            Self::Vp9(encoder) => encoder.encode(frame, keyframe, half),
+            Self::H264 { backend, size } => {
+                fits(frame, *size)?;
+                backend.encode(frame, keyframe)
+            }
+        }
+    }
+
+    pub fn refine(&mut self, frame: &I420) -> Result<EncodedFrame> {
+        match self {
+            Self::Vp9(encoder) => encoder.refine(frame),
+            Self::H264 { backend, size } => {
+                fits(frame, *size)?;
+                backend.refine(frame)
+            }
+        }
+    }
+
+    pub fn set_bitrate(&mut self, bitrate_kbps: u32) -> Result<()> {
+        match self {
+            Self::Vp9(encoder) => encoder.set_bitrate(bitrate_kbps),
+            Self::H264 { backend, .. } => backend.set_bitrate(bitrate_kbps.max(1)),
+        }
+    }
+
+    pub fn size(&self) -> (usize, usize) {
+        match self {
+            Self::Vp9(encoder) => (encoder.width, encoder.height),
+            Self::H264 { size, .. } => *size,
+        }
+    }
+}
+
+/// The H.264 backends hand `frame.data` to C, which reads a whole I420 frame
+/// of the size they were opened at: refuse anything else here, once.
+fn fits(frame: &I420, (width, height): (usize, usize)) -> Result<()> {
+    if (frame.width, frame.height) != (width, height) {
+        anyhow::bail!(
+            "encoder is {width}x{height} but was given {}x{}",
+            frame.width,
+            frame.height
+        );
+    }
+    if frame.data.len() < width * height + 2 * (width / 2) * (height / 2) {
+        anyhow::bail!("a {width}x{height} frame is short of its planes");
+    }
+    Ok(())
+}
+
 impl Drop for Encoder {
     fn drop(&mut self) {
         if !self.native.is_null() {
@@ -197,8 +280,34 @@ mod tests {
     fn encodes_successive_frames_and_refuses_a_mismatched_geometry() {
         let (w, h) = (64usize, 64usize);
         let mut encoder = Encoder::new(w, h, 500, 30, 2).expect("encoder should start");
-        assert!(!encoder.encode(&blank(w, h), true).unwrap().data.is_empty());
-        assert!(!encoder.encode(&blank(w, h), false).unwrap().data.is_empty());
-        assert!(encoder.encode(&blank(32, 32), false).is_err());
+        assert!(!encoder
+            .encode(&blank(w, h), true, false)
+            .unwrap()
+            .data
+            .is_empty());
+        assert!(!encoder
+            .encode(&blank(w, h), false, false)
+            .unwrap()
+            .data
+            .is_empty());
+        assert!(encoder.encode(&blank(32, 32), false, false).is_err());
+    }
+
+    #[test]
+    fn a_half_size_run_starts_and_ends_on_a_key_frame() {
+        let (w, h) = (1280usize, 720usize);
+        let mut encoder = Encoder::new(w, h, 2000, 60, 2).expect("encoder should start");
+        assert!(encoder.encode(&blank(w, h), true, false).unwrap().keyframe);
+        assert!(!encoder.encode(&blank(w, h), false, false).unwrap().keyframe);
+        assert!(
+            encoder.encode(&blank(w, h), false, true).unwrap().keyframe,
+            "size down"
+        );
+        assert!(!encoder.encode(&blank(w, h), false, true).unwrap().keyframe);
+        assert!(
+            encoder.refine(&blank(w, h)).unwrap().keyframe,
+            "size back up"
+        );
+        assert!(!encoder.encode(&blank(w, h), false, false).unwrap().keyframe);
     }
 }

package/engine/src/h264.rs

@@ -0,0 +1,188 @@
+//! H.264 encoding of captured desktops, offered alongside VP9.
+//!
+//! VP9 stays the default: a receiver that states no preference gets it, as it
+//! always has. H.264 exists for receivers whose platform decodes it in
+//! hardware and VP9 only in software — an iPhone's WebRTC stack is one — so the
+//! engine offers both and codes whichever the receiver's answer puts first.
+//!
+//! Platform encoders come first: VideoToolbox on macOS, NVENC or VA-API on
+//! Linux. Where a Linux machine has neither, the engine loads Cisco's prebuilt
+//! openh264 library, fetched at runtime from Cisco and checked against its
+//! published hash — never a copy built from source, and never one shipped in
+//! this package, because Cisco's patent licence covers only its own binary.
+//!
+//! Every backend emits the same stream: Constrained Baseline, Annex-B, no
+//! B-frames and no lookahead (one frame in, one access unit out), an IDR only
+//! when asked for, and the SPS and PPS in front of every IDR so a decoder can
+//! start on any of them. Coded size never changes within a session: the VP9
+//! path's half-size motion has no H.264 counterpart here, since a size change
+//! costs H.264 a new sequence, not just a key frame.
+
+use crate::convert::I420;
+use crate::encoder::EncodedFrame;
+use anyhow::Result;
+use std::sync::Mutex;
+
+/// One H.264 encoder backend. All take I420 at the size they were opened with.
+pub trait Backend: Send {
+    /// Code `frame`; `keyframe` forces an IDR. The access unit is Annex-B, and
+    /// an IDR carries its SPS and PPS in front of the slice.
+    fn encode(&mut self, frame: &I420, keyframe: bool) -> Result<EncodedFrame>;
+    /// Code `frame` again, unchanged, as an inter frame under
+    /// [`REFINE_MAX_QP`]: the detail the motion frames could not afford.
+    fn refine(&mut self, frame: &I420) -> Result<EncodedFrame>;
+    /// Change the rate target, in kilobits per second, for the frames that follow.
+    fn set_bitrate(&mut self, bitrate_kbps: u32) -> Result<()>;
+}
+
+/// The quantizer ceiling of a refinement pass, on H.264's 0–51 scale: small
+/// text reads sharp, and the pass happens once per still, not per frame.
+pub const REFINE_MAX_QP: u32 = 20;
+
+/// The `profile-level-id` every backend's stream satisfies: Constrained
+/// Baseline (`42e0`) at level 5.2, the bound for a 4K desktop at 60 fps. A
+/// receiver matches on the profile; the level is an upper bound, and the
+/// offer's `level-asymmetry-allowed=1` lets each side keep its own.
+pub const PROFILE_LEVEL_ID: &str = "42e034";
+
+/// Which encoder a session would get.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Info {
+    /// `videotoolbox`, `nvenc`, `vaapi` or `openh264`.
+    pub encoder: &'static str,
+    pub hardware: bool,
+}
+
+type Opener = fn(usize, usize, u32, u32) -> Result<Box<dyn Backend>>;
+
+/// Level 5.2's frame size limit, in 16x16 macroblocks: the most the offer's
+/// `PROFILE_LEVEL_ID` promises, and more than a 4096x2160 desktop needs.
+const MAX_MACROBLOCKS: usize = 36_864;
+
+/// `DESKLINK_H264_ENCODER`: one backend to use alone, `off` for none.
+fn only() -> Option<String> {
+    std::env::var("DESKLINK_H264_ENCODER")
+        .ok()
+        .filter(|only| !only.is_empty())
+}
+
+/// The backends this build has, best first.
+fn candidates() -> Vec<(Info, Opener)> {
+    let mut all: Vec<(Info, Opener)> = Vec::new();
+    #[cfg(target_os = "macos")]
+    all.push((
+        Info {
+            encoder: "videotoolbox",
+            hardware: true,
+        },
+        |w, h, kbps, fps| Ok(Box::new(crate::h264_vt::Encoder::open(w, h, kbps, fps)?)),
+    ));
+    #[cfg(target_os = "linux")]
+    {
+        all.push((
+            Info {
+                encoder: "nvenc",
+                hardware: true,
+            },
+            |w, h, kbps, fps| Ok(Box::new(crate::h264_nvenc::Encoder::open(w, h, kbps, fps)?)),
+        ));
+        all.push((
+            Info {
+                encoder: "vaapi",
+                hardware: true,
+            },
+            |w, h, kbps, fps| Ok(Box::new(crate::h264_vaapi::Encoder::open(w, h, kbps, fps)?)),
+        ));
+        all.push((
+            Info {
+                encoder: "openh264",
+                hardware: false,
+            },
+            |w, h, kbps, fps| {
+                Ok(Box::new(crate::h264_openh264::Encoder::open(
+                    w, h, kbps, fps,
+                )?))
+            },
+        ));
+    }
+    if let Some(only) = only() {
+        all.retain(|(info, _)| info.encoder == only);
+    }
+    all
+}
+
+/// Whether H.264 is offered for a surface this size. Some encoders open at
+/// sizes they then refuse to code, so a session is refused H.264 at its offer
+/// rather than ended by its first frame.
+pub fn fits(width: usize, height: usize) -> bool {
+    width >= 16 && height >= 16 && width.div_ceil(16) * height.div_ceil(16) <= MAX_MACROBLOCKS
+}
+
+/// Open the best backend that starts for this size.
+pub fn open(
+    width: usize,
+    height: usize,
+    bitrate_kbps: u32,
+    fps: u32,
+) -> Result<(Box<dyn Backend>, Info)> {
+    if !fits(width, height) {
+        anyhow::bail!("H.264 is not offered for a {width}x{height} surface");
+    }
+    // One backend opens at a time: driver libraries initialize on first use,
+    // and two GPU stacks coming up together in one process is where drivers
+    // have been seen to deadlock.
+    static OPENING: Mutex<()> = Mutex::new(());
+    let _opening = OPENING.lock().unwrap_or_else(|p| p.into_inner());
+    let mut refusals = Vec::new();
+    for (info, open) in candidates() {
+        match open(width, height, bitrate_kbps.max(1), fps.max(1)) {
+            Ok(backend) => return Ok((backend, info)),
+            Err(error) => refusals.push(format!("{}: {error:#}", info.encoder)),
+        }
+    }
+    anyhow::bail!(
+        "no H.264 encoder starts for {width}x{height} ({})",
+        if refusals.is_empty() {
+            String::from("none enabled")
+        } else {
+            refusals.join("; ")
+        }
+    )
+}
+
+/// What the last probe found; `None` until one has run.
+static PROBED: Mutex<Option<Option<Info>>> = Mutex::new(None);
+
+/// The backend a session would get, found by starting a small encoder and
+/// coding one frame with it — a driver that lists H.264 but cannot open a
+/// session is common enough that listing is no evidence. Cached: opening a
+/// hardware session is not free. Never fetches anything.
+pub fn probe() -> Option<Info> {
+    let mut probed = PROBED.lock().unwrap_or_else(|p| p.into_inner());
+    *probed.get_or_insert_with(|| {
+        let (width, height) = (320, 240);
+        let blank = I420 {
+            width,
+            height,
+            data: vec![128u8; width * height * 3 / 2],
+        };
+        let (mut backend, info) = open(width, height, 500, 30).ok()?;
+        backend.encode(&blank, true).ok()?;
+        Some(info)
+    })
+}
+
+/// The backend for a session about to be offered: [`probe`], and on Linux,
+/// when no encoder is present, fetch Cisco's openh264 once and probe again.
+/// Blocks for the fetch; call it off the async runtime.
+pub fn prepare() -> Option<Info> {
+    if let Some(info) = probe() {
+        return Some(info);
+    }
+    #[cfg(target_os = "linux")]
+    if only().is_none_or(|only| only == "openh264") && crate::h264_openh264::fetch_once() {
+        *PROBED.lock().unwrap_or_else(|p| p.into_inner()) = None;
+        return probe();
+    }
+    None
+}

package/engine/src/h264_nvenc.rs

@@ -0,0 +1,308 @@
+//! H.264 on NVIDIA GPUs through NVENC, wrapped by the C shim in
+//! `native/nvenc_shim.c`.
+//!
+//! The driver's libraries are opened at runtime, so the engine starts the same
+//! on a machine without an NVIDIA GPU; there [`Encoder::open`] just fails with
+//! the reason. Synchronous, P frames only, ultra-low-latency tuning: the access
+//! unit is complete when `encode` returns.
+
+use crate::convert::I420;
+use crate::encoder::EncodedFrame;
+use crate::h264::REFINE_MAX_QP;
+use anyhow::Result;
+use std::ffi::CStr;
+use std::os::raw::{c_char, c_int};
+
+#[repr(C)]
+struct NativeEncoder {
+    _private: [u8; 0],
+}
+
+extern "C" {
+    fn dl_nvenc_create(
+        width: c_int,
+        height: c_int,
+        bitrate_kbps: c_int,
+        fps: c_int,
+        error: *mut c_char,
+        error_len: usize,
+    ) -> *mut NativeEncoder;
+    fn dl_nvenc_encode(encoder: *mut NativeEncoder, i420: *const u8, force_idr: c_int) -> c_int;
+    fn dl_nvenc_reconfigure(
+        encoder: *mut NativeEncoder,
+        bitrate_kbps: c_int,
+        max_qp: c_int,
+    ) -> c_int;
+    fn dl_nvenc_packet_data(encoder: *const NativeEncoder) -> *const u8;
+    fn dl_nvenc_packet_size(encoder: *const NativeEncoder) -> usize;
+    fn dl_nvenc_packet_is_key(encoder: *const NativeEncoder) -> c_int;
+    fn dl_nvenc_error(encoder: *const NativeEncoder) -> *const c_char;
+    fn dl_nvenc_destroy(encoder: *mut NativeEncoder);
+}
+
+pub struct Encoder {
+    native: *mut NativeEncoder,
+    width: usize,
+    height: usize,
+    bitrate_kbps: u32,
+}
+
+// Moved to the pipeline thread and only used there; the shim makes its CUDA
+// context current around each call rather than binding it to a thread.
+unsafe impl Send for Encoder {}
+
+impl Encoder {
+    pub fn open(width: usize, height: usize, bitrate_kbps: u32, fps: u32) -> Result<Self> {
+        let mut error = [0 as c_char; 256];
+        let native = unsafe {
+            dl_nvenc_create(
+                width as c_int,
+                height as c_int,
+                bitrate_kbps.max(1) as c_int,
+                fps.max(1) as c_int,
+                error.as_mut_ptr(),
+                error.len(),
+            )
+        };
+        if native.is_null() {
+            let reason = unsafe { CStr::from_ptr(error.as_ptr()) }.to_string_lossy();
+            anyhow::bail!("{reason}");
+        }
+        Ok(Self {
+            native,
+            width,
+            height,
+            bitrate_kbps: bitrate_kbps.max(1),
+        })
+    }
+
+    fn failure(&self, what: &str) -> anyhow::Error {
+        let reason = unsafe { CStr::from_ptr(dl_nvenc_error(self.native)) }.to_string_lossy();
+        anyhow::anyhow!("NVENC {what}: {reason}")
+    }
+}
+
+impl crate::h264::Backend for Encoder {
+    fn encode(&mut self, frame: &I420, keyframe: bool) -> Result<EncodedFrame> {
+        if frame.width != self.width || frame.height != self.height {
+            anyhow::bail!(
+                "encoder is {}x{} but was given {}x{}",
+                self.width,
+                self.height,
+                frame.width,
+                frame.height
+            );
+        }
+        if frame.data.len() < self.width * self.height * 3 / 2 {
+            anyhow::bail!("an I420 frame of {} bytes is short", frame.data.len());
+        }
+        if unsafe { dl_nvenc_encode(self.native, frame.data.as_ptr(), keyframe as c_int) } != 1 {
+            return Err(self.failure("could not code a frame"));
+        }
+        let (data, size) = unsafe {
+            (
+                dl_nvenc_packet_data(self.native),
+                dl_nvenc_packet_size(self.native),
+            )
+        };
+        Ok(EncodedFrame {
+            data: unsafe { std::slice::from_raw_parts(data, size) }.to_vec(),
+            keyframe: unsafe { dl_nvenc_packet_is_key(self.native) } != 0,
+        })
+    }
+
+    /// NVENC caps the quantizer through its rate-control config, which it
+    /// changes in place between frames without an IDR: the ceiling goes down
+    /// for this one frame and comes back off after it.
+    fn refine(&mut self, frame: &I420) -> Result<EncodedFrame> {
+        let bitrate = self.bitrate_kbps as c_int;
+        if unsafe { dl_nvenc_reconfigure(self.native, bitrate, REFINE_MAX_QP as c_int) } != 0 {
+            return Err(self.failure("refused the refinement ceiling"));
+        }
+        let coded = self.encode(frame, false);
+        if unsafe { dl_nvenc_reconfigure(self.native, bitrate, 0) } != 0 {
+            return Err(self.failure("refused to lift the refinement ceiling"));
+        }
+        coded
+    }
+
+    fn set_bitrate(&mut self, bitrate_kbps: u32) -> Result<()> {
+        let bitrate_kbps = bitrate_kbps.max(1);
+        if unsafe { dl_nvenc_reconfigure(self.native, bitrate_kbps as c_int, 0) } != 0 {
+            return Err(self.failure(&format!("refused a {bitrate_kbps} kbps target")));
+        }
+        self.bitrate_kbps = bitrate_kbps;
+        Ok(())
+    }
+}
+
+impl Drop for Encoder {
+    fn drop(&mut self) {
+        unsafe { dl_nvenc_destroy(self.native) };
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::h264::Backend;
+
+    /// Fine detail, like text, scrolled sideways by `t`.
+    fn pattern(width: usize, height: usize, t: usize) -> I420 {
+        let mut data = vec![128u8; width * height * 3 / 2];
+        for y in 0..height {
+            for x in 0..width {
+                data[y * width + x] = ((x + 4 * t) ^ (3 * y)) as u8;
+            }
+        }
+        I420 {
+            width,
+            height,
+            data,
+        }
+    }
+
+    fn nal_types(au: &[u8]) -> Vec<u8> {
+        let mut types = Vec::new();
+        let mut i = 0;
+        while i + 3 < au.len() {
+            if au[i..i + 3] == [0, 0, 1] {
+                types.push(au[i + 3] & 0x1f);
+                i += 3;
+            } else {
+                i += 1;
+            }
+        }
+        types
+    }
+
+    fn open(width: usize, height: usize) -> Option<Encoder> {
+        match Encoder::open(width, height, 4000, 30) {
+            Ok(encoder) => Some(encoder),
+            Err(error) => {
+                eprintln!("skipping: NVENC unavailable: {error:#}");
+                None
+            }
+        }
+    }
+
+    #[test]
+    fn idr_on_request_only_and_refine_is_inter() {
+        let (w, h) = (640, 480);
+        let Some(mut encoder) = open(w, h) else {
+            return;
+        };
+        let first = encoder.encode(&pattern(w, h, 0), false).unwrap();
+        assert!(first.data.starts_with(&[0, 0, 0, 1]), "Annex-B");
+        assert_eq!(nal_types(&first.data), [7, 8, 5]);
+        assert!(first.keyframe);
+
+        let next = encoder.encode(&pattern(w, h, 1), false).unwrap();
+        assert_eq!(nal_types(&next.data), [1]);
+        assert!(!next.keyframe);
+
+        let forced = encoder.encode(&pattern(w, h, 2), true).unwrap();
+        assert_eq!(nal_types(&forced.data), [7, 8, 5]);
+        assert!(forced.keyframe);
+
+        let still = pattern(w, h, 3);
+        let motion = encoder.encode(&still, false).unwrap();
+        let refined = encoder.refine(&still).unwrap();
+        assert_eq!(nal_types(&refined.data), [1]);
+        assert!(!refined.keyframe);
+        eprintln!(
+            "motion frame {} bytes, refinement {} bytes",
+            motion.data.len(),
+            refined.data.len()
+        );
+
+        encoder.set_bitrate(1500).unwrap();
+        let after = encoder.encode(&pattern(w, h, 4), false).unwrap();
+        assert_eq!(nal_types(&after.data), [1]);
+        assert!(!after.keyframe);
+
+        assert!(encoder.encode(&pattern(320, 240, 0), false).is_err());
+    }
+
+    #[test]
+    fn the_refinement_ceiling_is_lifted_for_the_motion_after_it() {
+        let (w, h) = (640, 480);
+        let Ok(mut encoder) = Encoder::open(w, h, 300, 30) else {
+            return;
+        };
+        // Fresh detail every frame, which no reference predicts: the rate
+        // control, not motion search, decides these sizes.
+        let noise = |t: usize| {
+            let mut frame = pattern(w, h, 0);
+            for (i, pixel) in frame.data[..w * h].iter_mut().enumerate() {
+                *pixel = ((i ^ t).wrapping_mul(2_654_435_761) >> 13) as u8;
+            }
+            frame
+        };
+        let coded = |encoder: &mut Encoder, from: usize| -> usize {
+            (from..from + 10)
+                .map(|t| encoder.encode(&noise(t), false).unwrap().data.len())
+                .sum()
+        };
+        coded(&mut encoder, 0);
+        let before = coded(&mut encoder, 10);
+        encoder.refine(&noise(19)).unwrap();
+        let after = coded(&mut encoder, 20);
+        assert!(
+            after < before * 2,
+            "motion after a refinement is back under the rate target: {before} then {after} bytes"
+        );
+    }
+
+    #[test]
+    fn sizes_off_the_macroblock_grid_open_and_code() {
+        for (w, h) in [(1366, 768), (1918, 1078)] {
+            let Some(mut encoder) = open(w, h) else {
+                return;
+            };
+            assert!(encoder.encode(&pattern(w, h, 0), false).unwrap().keyframe);
+            assert!(!encoder.encode(&pattern(w, h, 1), false).unwrap().keyframe);
+        }
+    }
+
+    /// Not a check: writes `$DESKLINK_NVENC_DUMP` (60 frames at 1282x722, an
+    /// IDR at 30 and a refinement at 45) for an external decoder, and prints
+    /// the mean encode time at 1080p and 4K.
+    #[test]
+    #[ignore]
+    fn dump_and_time() {
+        use std::time::Instant;
+        if let Ok(path) = std::env::var("DESKLINK_NVENC_DUMP") {
+            let (w, h) = (1282, 722);
+            let Some(mut encoder) = Encoder::open(w, h, 1500, 30).ok() else {
+                return;
+            };
+            let mut out = Vec::new();
+            for t in 0..60 {
+                let frame = pattern(w, h, t.min(44));
+                let coded = match t {
+                    45 => encoder.refine(&frame),
+                    _ => encoder.encode(&frame, t == 30),
+                }
+                .unwrap();
+                if (44..=46).contains(&t) {
+                    eprintln!("frame {t}: {} bytes", coded.data.len());
+                }
+                out.extend_from_slice(&coded.data);
+            }
+            std::fs::write(path, out).unwrap();
+        }
+        for (w, h) in [(1920, 1080), (3840, 2160)] {
+            let Some(mut encoder) = Encoder::open(w, h, 20_000, 60).ok() else {
+                return;
+            };
+            let frames: Vec<_> = (0..4).map(|t| pattern(w, h, t)).collect();
+            encoder.encode(&frames[0], true).unwrap();
+            let start = Instant::now();
+            for t in 0..60 {
+                encoder.encode(&frames[t % 4], false).unwrap();
+            }
+            eprintln!("{w}x{h}: {:?} per frame", start.elapsed() / 60);
+        }
+    }
+}