perf(pyrowave): elevated GPU scheduling + global-priority encode queue

PyroWave's wavelet encode runs on the GPU's compute/shader cores, so a GPU-bound
game starves it: submit spikes from ~2 ms to ~15 ms under a 95%+ game load and
the stream fps collapses. NVENC is immune (separate encoder ASIC). Two levers to
let the encode get scheduled ahead of the game's rendering:

- Windows process GPU scheduling: D3DKMTSetProcessSchedulingPriorityClass, env
  PUNKTFUNK_GPU_PRIORITY = off|above-normal|high (default)|realtime. Best-effort,
  once per process, non-fatal on refusal (enc/windows/pyrowave.rs).
- Global-priority Vulkan encode queue (Granite patch 0005): request a
  VK_KHR_global_priority queue (PYROWAVE_QUEUE_PRIORITY = off|high|realtime,
  default realtime), downgrading REALTIME→HIGH→none on NOT_PERMITTED so a refused
  class never regresses the encoder to HEVC.

HONEST STATUS: on an RTX 4090 / Windows / WDDM neither moved the ~15 ms spikes —
the graphics-vs-compute preemption granularity is the wall, not the priority
level. Kept because both are correct, harmless (graceful fallback), and may help
other GPUs/drivers. For a GPU-saturated game the working levers are reducing the
encode's GPU cost (4:2:0/8-bit) or H.265; PyroWave holds full rate on the desktop
and in games that leave the GPU headroom.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

crates/pf-encode/Cargo.toml

@@ -67,6 +67,9 @@ windows = { version = "0.62", features = [
     "Win32_Storage_FileSystem",
     "Win32_System_LibraryLoader",
     "Win32_System_Threading",
+    # D3DKMTSetProcessSchedulingPriorityClass — raise the host's WDDM GPU scheduling priority
+    # above a running game so PyroWave's compute-shader encode isn't starved (enc/windows/pyrowave.rs).
+    "Wdk_Graphics_Direct3D",
 ] }
 
 [features]

crates/pf-encode/src/enc/windows/pyrowave.rs

@@ -67,6 +67,65 @@ fn budget_for(bitrate_bps: u64, fps: u32) -> usize {
     ((bitrate_bps / (8 * fps.max(1) as u64)) as usize).max(64 * 1024)
 }
 
+/// Raise this process's WDDM GPU scheduling priority so the wavelet encode isn't starved by a
+/// GPU-bound game. PyroWave encodes on the GPU's compute/shader cores — the exact resource a game
+/// saturates — so under load `pyrowave_encoder_encode_gpu_synchronous` spikes from ~2 ms to
+/// 15-18 ms (measured, RTX 4090 at 95 % game load) and the stream fps collapses; NVENC is immune
+/// because it runs on the separate encoder ASIC. HIGH sits above a game's NORMAL/ABOVE_NORMAL so
+/// the WDDM scheduler services the encode's short compute bursts ahead of the game's rendering.
+/// (REALTIME is deliberately avoided: it needs a privilege and would preempt the desktop
+/// compositor too.) Best-effort + once-per-process: if the class isn't grantable we log and run at
+/// normal priority — no session-fatal path.
+fn raise_process_gpu_priority() {
+    use std::sync::Once;
+    static ONCE: Once = Once::new();
+    ONCE.call_once(|| {
+        use windows::Wdk::Graphics::Direct3D::{
+            D3DKMTSetProcessSchedulingPriorityClass, D3DKMT_SCHEDULINGPRIORITYCLASS_ABOVE_NORMAL,
+            D3DKMT_SCHEDULINGPRIORITYCLASS_HIGH, D3DKMT_SCHEDULINGPRIORITYCLASS_REALTIME,
+        };
+        // `PUNKTFUNK_GPU_PRIORITY` = off | above-normal | high (default) | realtime. REALTIME can
+        // force finer WDDM preemption than HIGH but needs a privilege and preempts the compositor,
+        // so it stays opt-in; `off` skips the call entirely.
+        let (class, label) = match std::env::var("PUNKTFUNK_GPU_PRIORITY")
+            .ok()
+            .as_deref()
+            .map(str::trim)
+            .map(str::to_ascii_lowercase)
+            .as_deref()
+        {
+            Some("off") => {
+                tracing::info!("PyroWave: PUNKTFUNK_GPU_PRIORITY=off — leaving GPU scheduling priority at default");
+                return;
+            }
+            Some("above-normal") | Some("above_normal") => {
+                (D3DKMT_SCHEDULINGPRIORITYCLASS_ABOVE_NORMAL, "ABOVE_NORMAL")
+            }
+            Some("realtime") => (D3DKMT_SCHEDULINGPRIORITYCLASS_REALTIME, "REALTIME"),
+            _ => (D3DKMT_SCHEDULINGPRIORITYCLASS_HIGH, "HIGH"),
+        };
+        // SAFETY: `GetCurrentProcess` returns the current-process pseudo-handle; the D3DKMT call
+        // only sets this process's GPU scheduling class — it creates/frees nothing.
+        let status = unsafe {
+            D3DKMTSetProcessSchedulingPriorityClass(GetCurrentProcess(), class)
+        };
+        if status.is_ok() {
+            tracing::info!(
+                priority = label,
+                "PyroWave: raised process GPU scheduling priority (WDDM) so the wavelet encode is \
+                 serviced ahead of game rendering on the shared shader cores"
+            );
+        } else {
+            tracing::warn!(
+                ?status,
+                priority = label,
+                "PyroWave: could not raise GPU scheduling priority (not grantable) — the encode \
+                 may be starved under heavy game GPU load"
+            );
+        }
+    });
+}
+
 pub struct PyroWaveEncoder {
     // pyrowave owns the whole Vulkan device (create_device_by_compat) — no ash on this side.
     pw_dev: pw::pyrowave_device,
@@ -112,6 +171,9 @@ impl PyroWaveEncoder {
         chroma: crate::ChromaFormat,
         bit_depth: u8,
     ) -> Result<Self> {
+        // Prioritize the host's GPU work over a running game so the compute-shader encode gets
+        // scheduled promptly instead of queuing behind a full frame of the game's rendering.
+        raise_process_gpu_priority();
         let chroma444 = chroma.is_444();
         // A negotiated 10-bit session rides 16-bit UNORM planes carrying the P010-style
         // studio codes the capturer's HDR CSC writes (design/pyrowave-444-hdr.md §2.2) —