Skip to main content

alpha2_native_gpu/
vulkan.rs

1//! Vulkan interop: the device the renderer shares with `FFmpeg`'s decoder and encoder, import
2//! of decoded frames as wgpu plane views with layout transitions and timeline synchronization,
3//! copies of rendered planes into encoder frames, and device capability probes.
4
5use std::{
6    collections::VecDeque,
7    error::Error,
8    ffi::{CStr, c_void},
9    fmt,
10    ptr::NonNull,
11    sync::{
12        Arc, Mutex, Weak,
13        atomic::{AtomicBool, Ordering},
14    },
15};
16
17use alpha2_ffmpeg_bridge::{
18    BridgeError, VulkanDeviceInfo, VulkanFrameAccess, VulkanFrameAccessGuard, VulkanFrameLease,
19    VulkanQueueLock, create_vulkan_device_context,
20};
21use alpha2_gpu::{ExternalQueueLock, GpuContext};
22use ash::vk::{self, Handle};
23use rsmpeg::avutil::AVHWDeviceContext;
24use wgpu_hal::Instance as _;
25
26use crate::{NativeGpuIdentity, NativePlaneLayout};
27
28// Each fallible helper returns 0 or the failing step and writes that step's platform status to
29// `status` (`include/alpha2_native_gpu_status.h`).
30unsafe extern "C" {
31    fn alpha2_native_gpu_vulkan_probe(access: *mut VulkanFrameAccess, status: *mut i32) -> i32;
32    fn alpha2_native_gpu_vulkan_acquire_check(
33        access: *const VulkanFrameAccess,
34        status: *mut i32,
35    ) -> i32;
36    fn alpha2_native_gpu_vulkan_ticket_create(
37        device: u64,
38        allocator: u64,
39        queue_family: u32,
40        output: *mut *mut c_void,
41        status: *mut i32,
42    ) -> i32;
43    fn alpha2_native_gpu_vulkan_ticket_poll(ticket: *const c_void, status: *mut i32) -> i32;
44    fn alpha2_native_gpu_vulkan_ticket_reset(ticket: *mut c_void, status: *mut i32) -> i32;
45    fn alpha2_native_gpu_vulkan_acquire_submit(
46        access: *mut VulkanFrameAccess,
47        ticket: *mut c_void,
48        status: *mut i32,
49    ) -> i32;
50    fn alpha2_native_gpu_vulkan_release(
51        access: *mut VulkanFrameAccess,
52        ticket: *mut c_void,
53        status: *mut i32,
54    ) -> i32;
55    fn alpha2_native_gpu_vulkan_signal(
56        access: *mut VulkanFrameAccess,
57        semaphore: u64,
58        wait_value: u64,
59        signal_value: u64,
60        status: *mut i32,
61    ) -> i32;
62    fn alpha2_native_gpu_vulkan_import_destroy(ticket: *mut c_void);
63    fn alpha2_native_gpu_vulkan_import_retire(ticket: *mut c_void, timeout_ns: u64) -> i32;
64    #[cfg(test)]
65    fn alpha2_native_gpu_vulkan_retained_helpers() -> u64;
66    fn alpha2_native_gpu_vulkan_encode_copier_create(
67        device: u64,
68        queue_family: u32,
69        allocator: u64,
70        output: *mut *mut c_void,
71        status: *mut i32,
72    ) -> i32;
73    fn alpha2_native_gpu_vulkan_encode_copier_destroy(copier: *mut c_void, status: *mut i32)
74    -> i32;
75    fn alpha2_native_gpu_vulkan_encode_copier_slots() -> u32;
76    fn alpha2_native_gpu_vulkan_encode_copier_await_slot(
77        copier: *mut c_void,
78        slot: *mut u32,
79        status: *mut i32,
80    ) -> i32;
81    fn alpha2_native_gpu_vulkan_encode_copier_submit(
82        copier: *mut c_void,
83        access: *mut VulkanFrameAccess,
84        copy: *const VulkanEncodeCopy,
85        status: *mut i32,
86    ) -> i32;
87    fn alpha2_native_gpu_vulkan_set_wait_timeout(nanoseconds: u64);
88    fn alpha2_native_gpu_vulkan_wait_timeout() -> u64;
89}
90
91pub(crate) fn set_wait_timeout(timeout: std::time::Duration) {
92    let nanoseconds = u64::try_from(timeout.as_nanos()).unwrap_or(u64::MAX);
93    // SAFETY: stores one integer the helpers read on each wait.
94    unsafe { alpha2_native_gpu_vulkan_set_wait_timeout(nanoseconds) };
95}
96
97fn wait_timeout() -> std::time::Duration {
98    // SAFETY: reads one integer.
99    std::time::Duration::from_nanos(unsafe { alpha2_native_gpu_vulkan_wait_timeout() })
100}
101
102fn helper_error(operation: &'static str, step: i32, status: i32) -> BridgeError {
103    crate::status::helper_failure(
104        alpha2_ffmpeg_bridge::NativeGpuBackend::Vulkan,
105        operation,
106        step,
107        status,
108    )
109}
110
111/// Fails the Nth call of an import helper on this thread, as a device fault would, so tests
112/// reach the failure branches.
113#[cfg(test)]
114pub(crate) mod inject {
115    use std::cell::Cell;
116    use std::sync::atomic::{AtomicU64, Ordering};
117
118    /// How many waits for given-back tickets have begun in this process.
119    static RETIRES_BEGUN: AtomicU64 = AtomicU64::new(0);
120
121    pub(super) fn retire_begins() {
122        RETIRES_BEGUN.fetch_add(1, Ordering::Release);
123    }
124
125    /// How many waits for given-back tickets have begun in this process, on any thread.
126    pub(crate) fn retires_begun() -> u64 {
127        RETIRES_BEGUN.load(Ordering::Acquire)
128    }
129
130    #[derive(Clone, Copy, Debug)]
131    pub(crate) enum Hook {
132        AcquireSubmit,
133        TicketPoll,
134        TicketReset,
135        Release,
136    }
137
138    thread_local! {
139        static COUNTDOWNS: [Cell<u32>; 4] =
140            const { [Cell::new(0), Cell::new(0), Cell::new(0), Cell::new(0)] };
141        static STATUSES: [Cell<i32>; 4] =
142            const { [Cell::new(0), Cell::new(0), Cell::new(0), Cell::new(0)] };
143    }
144
145    /// Fails the `nth` (1-based) next call of `hook` on this thread with a lost device.
146    pub(crate) fn fail_nth(hook: Hook, nth: u32) {
147        fail_nth_with(hook, nth, super::vk::Result::ERROR_DEVICE_LOST.as_raw());
148    }
149
150    /// Fails the `nth` (1-based) next call of `hook` on this thread with `VkResult` `status`.
151    pub(crate) fn fail_nth_with(hook: Hook, nth: u32, status: i32) {
152        COUNTDOWNS.with(|countdowns| countdowns[hook as usize].set(nth));
153        STATUSES.with(|statuses| statuses[hook as usize].set(status));
154    }
155
156    /// Whether this call of `hook` should fail; if so, returns the chosen status at `step`.
157    pub(super) fn fails(hook: Hook, step: i32, status: &mut i32) -> Option<i32> {
158        let due = COUNTDOWNS.with(|countdowns| {
159            let countdown = &countdowns[hook as usize];
160            match countdown.get() {
161                0 => false,
162                1 => {
163                    countdown.set(0);
164                    true
165                }
166                left => {
167                    countdown.set(left - 1);
168                    false
169                }
170            }
171        });
172        due.then(|| {
173            *status = STATUSES.with(|statuses| statuses[hook as usize].get());
174            step
175        })
176    }
177}
178
179/// An import's frame, locked, with the ticket whose commands move it.
180///
181/// A ticket's command pool, buffers and fences need external synchronization. The lease uses
182/// them only through this, which holds the frame's lock (and so the queue lock `FFmpeg` and the
183/// renderer share). The pool touches a ticket only before a lease takes it and after the lease
184/// gives it back.
185struct LeaseAccess<'a> {
186    frame: VulkanFrameAccessGuard<'a>,
187    ticket: NonNull<c_void>,
188}
189
190/// Calls `alpha2_native_gpu_vulkan_acquire_submit`, or fails first where [`inject`] asks.
191///
192/// # Safety
193/// `lease.ticket` was created for the frame's device and queue family, and `lease.frame` may
194/// record what the acquire submits.
195unsafe fn acquire_submit(lease: &mut LeaseAccess<'_>, status: &mut i32) -> i32 {
196    #[cfg(test)]
197    if let Some(step) = inject::fails(
198        inject::Hook::AcquireSubmit,
199        crate::interop::ALPHA2_GPU_STEP_QUEUE_SUBMIT,
200        status,
201    ) {
202        return step;
203    }
204    // SAFETY: the caller's contract; the guard holds the frame's and the queue's locks.
205    unsafe {
206        alpha2_native_gpu_vulkan_acquire_submit(
207            lease.frame.access_mut(),
208            lease.ticket.as_ptr(),
209            status,
210        )
211    }
212}
213
214/// Calls `alpha2_native_gpu_vulkan_release`, or fails first where [`inject`] asks.
215///
216/// # Safety
217/// `lease.ticket` is the one the frame's acquire was submitted with, and `lease.frame` may
218/// record what the release submits.
219unsafe fn release(lease: &mut LeaseAccess<'_>, status: &mut i32) -> i32 {
220    #[cfg(test)]
221    if let Some(step) = inject::fails(
222        inject::Hook::Release,
223        crate::interop::ALPHA2_GPU_STEP_QUEUE_SUBMIT,
224        status,
225    ) {
226        return step;
227    }
228    // SAFETY: the caller's contract; the guard holds the frame's and the queue's locks.
229    unsafe {
230        alpha2_native_gpu_vulkan_release(lease.frame.access_mut(), lease.ticket.as_ptr(), status)
231    }
232}
233
234/// Calls `alpha2_native_gpu_vulkan_ticket_poll`, or fails first where [`inject`] asks.
235///
236/// # Safety
237/// `ticket` is a live ticket the caller owns.
238unsafe fn ticket_poll(ticket: *const c_void, status: &mut i32) -> i32 {
239    #[cfg(test)]
240    if let Some(step) = inject::fails(
241        inject::Hook::TicketPoll,
242        crate::interop::ALPHA2_GPU_STEP_FENCE_STATUS,
243        status,
244    ) {
245        return step;
246    }
247    // SAFETY: the caller's contract.
248    unsafe { alpha2_native_gpu_vulkan_ticket_poll(ticket, status) }
249}
250
251/// Calls `alpha2_native_gpu_vulkan_ticket_reset`, or fails first where [`inject`] asks.
252///
253/// # Safety
254/// `ticket` is a live ticket the caller owns, and nothing it submitted is running.
255unsafe fn ticket_reset(ticket: *mut c_void, status: &mut i32) -> i32 {
256    #[cfg(test)]
257    if let Some(step) = inject::fails(
258        inject::Hook::TicketReset,
259        crate::interop::ALPHA2_GPU_STEP_RESET_FENCE,
260        status,
261    ) {
262        return step;
263    }
264    // SAFETY: the caller's contract.
265    unsafe { alpha2_native_gpu_vulkan_ticket_reset(ticket, status) }
266}
267
268use crate::interop::Alpha2VulkanEncodeCopy as VulkanEncodeCopy;
269
270/// Reusable NV12 handoff from the renderer's plane textures to encoder frames, one per export.
271///
272/// Owns the command pool and command-buffer ring, so a frame costs one queue submission and no
273/// CPU wait. The copy is ordered after the render by queue order, not by a semaphore: a
274/// submission wgpu rejects signals nothing, and a copy waiting on it would block the shared
275/// queue.
276pub struct VulkanEncodeCopier {
277    copier: *mut c_void,
278    /// The lock `FFmpeg`'s submissions and `GpuContext::submit` take on the shared graphics
279    /// queue.
280    queue_lock: alpha2_ffmpeg_bridge::VulkanQueueLock,
281    retained: Option<Box<RetainedEncodeWork>>,
282    close_failed: bool,
283}
284
285/// Raw Vulkan submissions are invisible to wgpu's tracking, so both ends of every copy and the
286/// device stay alive until its fence completes.
287struct RetainedEncodeWork {
288    copies: Vec<Option<EncodeCopyInputs>>,
289    _context: SharedVulkanContext,
290    #[cfg(test)]
291    lifetime_probe: Option<Arc<()>>,
292}
293
294struct EncodeCopyInputs {
295    _luma: wgpu::Texture,
296    _chroma: wgpu::Texture,
297    _frame: rsmpeg::avutil::AVFrame,
298}
299
300// SAFETY: the C object is only reached through `&mut self`, and the raw pointer is owned solely by
301// this value, which destroys it once.
302unsafe impl Send for VulkanEncodeCopier {}
303
304impl fmt::Debug for VulkanEncodeCopier {
305    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
306        formatter
307            .debug_struct("VulkanEncodeCopier")
308            .finish_non_exhaustive()
309    }
310}
311
312impl Drop for VulkanEncodeCopier {
313    fn drop(&mut self) {
314        if !self.copier.is_null() && !self.close_failed {
315            let _ = self.try_close();
316        }
317        if !self.copier.is_null() {
318            // The C helper did not finish, so keep the whole ownership graph alive rather than
319            // let Rust free what its commands still use.
320            std::mem::forget(self.retained.take());
321        }
322    }
323}
324
325impl VulkanEncodeCopier {
326    /// Waits for outstanding copies and releases their resources.
327    ///
328    /// # Errors
329    /// On timeout or device loss, retains the pending GPU resources and device instead of
330    /// destroying images raw Vulkan work may still use.
331    pub fn finish(mut self) -> Result<(), BridgeError> {
332        self.try_close()
333    }
334
335    fn try_close(&mut self) -> Result<(), BridgeError> {
336        let mut status = 0;
337        // SAFETY: created by the matching constructor and destroyed once; the C side waits for
338        // in-flight copies before freeing anything.
339        let step =
340            unsafe { alpha2_native_gpu_vulkan_encode_copier_destroy(self.copier, &raw mut status) };
341        if step != 0 {
342            self.close_failed = true;
343            return Err(helper_error("encode copier teardown", step, status));
344        }
345        self.copier = std::ptr::null_mut();
346        // `retained` is the last owning field, so the device outlives the queue and lock
347        // references.
348        Ok(())
349    }
350}
351
352impl VulkanEncodeCopier {
353    /// Creates the handoff for one export on `context`'s device.
354    ///
355    /// # Errors
356    /// Returns an error when the command pool, buffers or fences cannot be created, or the
357    /// device has no queue lock for its graphics family.
358    pub fn new(context: &SharedVulkanContext) -> Result<Self, BridgeError> {
359        let gpu = context.gpu();
360        // SAFETY: this context is always Vulkan; the handle is only read.
361        let device = unsafe { gpu.device().as_hal::<wgpu_hal::api::Vulkan>() }
362            .map(|device| device.raw_device().handle().as_raw())
363            .ok_or(BridgeError::InvalidInput("renderer is not Vulkan"))?;
364        let mut copier = std::ptr::null_mut();
365        let mut status = 0;
366        // SAFETY: `device` is this renderer's live logical device; the outputs are valid locals.
367        let step = unsafe {
368            alpha2_native_gpu_vulkan_encode_copier_create(
369                device,
370                0,
371                0,
372                &raw mut copier,
373                &raw mut status,
374            )
375        };
376        if step != 0 {
377            return Err(helper_error("encode copier creation", step, status));
378        }
379        Ok(Self {
380            copier,
381            queue_lock: alpha2_ffmpeg_bridge::VulkanQueueLock::new(context.ffmpeg_device(), 0)?,
382            retained: Some(Box::new(RetainedEncodeWork {
383                copies: (0..Self::slots()).map(|_| None).collect(),
384                _context: context.clone(),
385                #[cfg(test)]
386                lifetime_probe: None,
387            })),
388            close_failed: false,
389        })
390    }
391
392    /// Plane-texture pairs a caller must cycle through to feed this copier.
393    ///
394    /// A single pair is only safe if the caller never runs ahead of the copy. A caller that
395    /// encodes on another thread does, so the pairs must be a ring as deep as the copier's
396    /// command-buffer ring.
397    #[must_use]
398    pub fn slots() -> usize {
399        // SAFETY: a constant read out of the shim; it touches no state.
400        unsafe { alpha2_native_gpu_vulkan_encode_copier_slots() as usize }
401    }
402
403    /// Waits until the slot the next copy will use is free, and returns it.
404    ///
405    /// Call before recording the render that writes the plane textures, and render into this
406    /// pair. The wait is on the copy four submissions ago, so a pipeline keeping up never
407    /// blocks.
408    ///
409    /// # Errors
410    /// Returns an error when the fence wait fails.
411    pub fn await_slot(&mut self) -> Result<usize, BridgeError> {
412        let (mut slot, mut status) = (0_u32, 0);
413        // SAFETY: the copier is live and the output pointers are valid locals.
414        let step = unsafe {
415            alpha2_native_gpu_vulkan_encode_copier_await_slot(
416                self.copier,
417                &raw mut slot,
418                &raw mut status,
419            )
420        };
421        if step != 0 {
422            return Err(helper_error("encode copy slot", step, status));
423        }
424        if let Some(retained) = self.retained.as_mut() {
425            retained.copies[slot as usize] = None;
426        }
427        Ok(slot as usize)
428    }
429
430    /// Copies a renderer-packed NV12 pair into an encoder frame's image.
431    ///
432    /// The submission that wrote the textures must already be on the renderer's queue; queue
433    /// order alone orders the copy after it. If that submission was rejected, the copy still
434    /// runs over whatever the planes held, and the caller fails the frame.
435    ///
436    /// # Errors
437    /// Returns an error when the frame is not one multi-planar image on this device, the
438    /// textures are not Vulkan, or the submission fails.
439    pub fn submit(
440        &mut self,
441        frame: &mut alpha2_ffmpeg_bridge::VulkanEncodeFrameAccess<'_>,
442        luma: &wgpu::Texture,
443        chroma: &wgpu::Texture,
444        size: (u32, u32),
445    ) -> Result<(), BridgeError> {
446        check_encode_copy_size(size, luma.size(), chroma.size(), frame.access().frame())?;
447        let slot = self.await_slot()?;
448        let inputs = EncodeCopyInputs {
449            _luma: luma.clone(),
450            _chroma: chroma.clone(),
451            _frame: frame.retain_frame()?,
452        };
453        let kept = self
454            .retained
455            .as_mut()
456            .and_then(|work| work.copies.get_mut(slot))
457            .ok_or(BridgeError::InvalidInput("invalid encode copier slot"))?;
458        // SAFETY: both textures belong to this Vulkan device and are only read; wgpu still owns
459        // them.
460        let luma_image = unsafe { luma.as_hal::<wgpu_hal::api::Vulkan>() }
461            .map(|texture| unsafe { texture.raw_handle() }.as_raw())
462            .ok_or(BridgeError::InvalidInput("luma plane is not Vulkan"))?;
463        // SAFETY: as above.
464        let chroma_image = unsafe { chroma.as_hal::<wgpu_hal::api::Vulkan>() }
465            .map(|texture| unsafe { texture.raw_handle() }.as_raw())
466            .ok_or(BridgeError::InvalidInput("chroma plane is not Vulkan"))?;
467        let copy = VulkanEncodeCopy {
468            luma_image,
469            chroma_image,
470            width: size.0,
471            height: size.1,
472        };
473        // Every submission to the shared graphics queue holds this lock. The plane textures are
474        // protected by the caller's slot ring, not queue order, since a caller encoding on
475        // another thread can be several frames ahead.
476        let queue = self.queue_lock.lock();
477        let mut status = 0;
478        // SAFETY: the guard holds FFmpeg's frame lock for the call, and the shim validates every
479        // handle it reads from the descriptor.
480        let step = unsafe {
481            alpha2_native_gpu_vulkan_encode_copier_submit(
482                self.copier,
483                frame.access_mut(),
484                &raw const copy,
485                &raw mut status,
486            )
487        };
488        drop(queue);
489        if step != 0 {
490            return Err(helper_error("encode copy", step, status));
491        }
492        *kept = Some(inputs);
493        frame.commit();
494        Ok(())
495    }
496}
497
498/// Refuses a copy extent that is odd or larger than either plane texture or the encoder image.
499fn check_encode_copy_size(
500    (width, height): (u32, u32),
501    luma: wgpu::Extent3d,
502    chroma: wgpu::Extent3d,
503    frame: &alpha2_ffmpeg_bridge::VulkanFrameDescriptor,
504) -> Result<(), BridgeError> {
505    let coded = (
506        u32::try_from(frame.coded_width).unwrap_or(0),
507        u32::try_from(frame.coded_height).unwrap_or(0),
508    );
509    let fits = width != 0
510        && height != 0
511        && width % 2 == 0
512        && height % 2 == 0
513        && width <= luma.width
514        && height <= luma.height
515        && width / 2 <= chroma.width
516        && height / 2 <= chroma.height
517        && width <= coded.0
518        && height <= coded.1;
519    if fits {
520        Ok(())
521    } else {
522        Err(BridgeError::InvalidInput(
523            "encode copy size does not fit its planes or the encoder frame",
524        ))
525    }
526}
527
528/// Checks that a decoded frame can be imported: moves its planes to `SHADER_READ_ONLY` and back
529/// in one submission on its queue, through import-like views, and waits.
530///
531/// # Errors
532/// Returns an error when image-view creation, synchronization, or submission fails.
533pub fn probe_vulkan_submission(lease: &VulkanFrameLease) -> Result<(), BridgeError> {
534    let mut guard = lease.lock_access()?;
535    let mut status = 0;
536    // SAFETY: the guard holds the FFmpeg frame and queue locks, and the helper uses the
537    // descriptor only during this call. It changes only the timeline values, after submitting,
538    // and returns the planes to the frame's layouts.
539    let step = unsafe { alpha2_native_gpu_vulkan_probe(guard.access_mut(), &raw mut status) };
540    // Committed on failure too: a timed-out submission still signals when it runs, and the next
541    // user must signal above it.
542    guard.commit();
543    if step != 0 {
544        return Err(helper_error("decode probe", step, status));
545    }
546    Ok(())
547}
548
549/// Coded extents and coding limits one video-encode profile has on a device.
550#[derive(Clone, Debug, Eq, PartialEq)]
551pub struct VideoEncodeExtent {
552    /// The profile the codec's Vulkan encoder opens on this device (H.264
553    /// `constrained_baseline`, `main` or `high`; HEVC `main`).
554    pub profile: &'static str,
555    /// Smallest accepted width and height in samples.
556    pub minimum: (u32, u32),
557    /// Largest accepted width and height in samples.
558    pub maximum: (u32, u32),
559    /// `VkVideoEncodeCapabilitiesKHR::encodeInputPictureGranularity`, which `FFmpeg` aligns the
560    /// coded size up to before the limits apply. So 158x62 can pass a 160x64 minimum while
561    /// 64x48 fails; compare aligned sizes, not raw ones.
562    pub granularity: (u32, u32),
563    /// `maxPPictureL0ReferenceCount`: references a P picture may use.
564    pub max_p_picture_l0_references: u32,
565    /// `maxBPictureL0ReferenceCount`: forward references a B picture may use. Zero together
566    /// with `max_l1_references` means no B pictures.
567    pub max_b_picture_l0_references: u32,
568    /// `maxL1ReferenceCount`: backward references a B picture may use.
569    pub max_l1_references: u32,
570    /// `VkVideoEncodeCapabilitiesKHR::rateControlModes` as names: `cbr`, `vbr`, `disabled`
571    /// (constant QP).
572    pub rate_control_modes: Vec<&'static str>,
573}
574
575impl VideoEncodeExtent {
576    /// Whether the device can encode B pictures at all.
577    #[must_use]
578    pub const fn supports_b_pictures(&self) -> bool {
579        self.max_b_picture_l0_references > 0 || self.max_l1_references > 0
580    }
581}
582
583impl VideoEncodeExtent {
584    /// Whether an output of this size reaches the encoder's coded limits.
585    #[must_use]
586    pub const fn accepts(&self, width: u32, height: u32) -> bool {
587        let coded = self.coded(width, height);
588        coded.0 >= self.minimum.0
589            && coded.1 >= self.minimum.1
590            && coded.0 <= self.maximum.0
591            && coded.1 <= self.maximum.1
592    }
593
594    /// The coded extent an output of this size is encoded at.
595    #[must_use]
596    pub const fn coded(&self, width: u32, height: u32) -> (u32, u32) {
597        (
598            align_up(width, self.granularity.0),
599            align_up(height, self.granularity.1),
600        )
601    }
602}
603
604const fn align_up(value: u32, granularity: u32) -> u32 {
605    if granularity <= 1 {
606        return value;
607    }
608    value.div_ceil(granularity).saturating_mul(granularity)
609}
610
611/// The H.264 profiles `FFmpeg`'s `h264_vulkan` tries for 8-bit 4:2:0 input, in its order. With
612/// no profile requested it opens the last one the device supports (`vulkan_encode_h264.c`,
613/// `init_profile`), so `high` where available.
614const H264_ENCODE_PROFILES: [(vk::native::StdVideoH264ProfileIdc, &str); 3] = [
615    (
616        vk::native::StdVideoH264ProfileIdc_STD_VIDEO_H264_PROFILE_IDC_BASELINE,
617        "constrained_baseline",
618    ),
619    (
620        vk::native::StdVideoH264ProfileIdc_STD_VIDEO_H264_PROFILE_IDC_MAIN,
621        "main",
622    ),
623    (
624        vk::native::StdVideoH264ProfileIdc_STD_VIDEO_H264_PROFILE_IDC_HIGH,
625        "high",
626    ),
627];
628
629/// What `query` answers for the last of `H264_ENCODE_PROFILES` it answers at all: the profile
630/// `h264_vulkan` would open, and its answer.
631fn last_supported_profile<T>(
632    mut query: impl FnMut(vk::native::StdVideoH264ProfileIdc) -> Option<T>,
633) -> Option<(&'static str, T)> {
634    H264_ENCODE_PROFILES
635        .iter()
636        .filter_map(|&(idc, name)| query(idc).map(|answer| (name, answer)))
637        .last()
638}
639
640/// Codecs the shared device encodes where the adapter has the extension: report name,
641/// extension, and the operation `FFmpeg` is told the encode queue does. AV1 is omitted because
642/// `libsvtav1` encodes it everywhere.
643const ENCODE_EXTENSIONS: [(&str, &CStr, vk::VideoCodecOperationFlagsKHR); 2] = [
644    (
645        "h264",
646        ash::khr::video_encode_h264::NAME,
647        vk::VideoCodecOperationFlagsKHR::ENCODE_H264,
648    ),
649    (
650        "hevc",
651        ash::khr::video_encode_h265::NAME,
652        vk::VideoCodecOperationFlagsKHR::ENCODE_H265,
653    ),
654];
655
656/// The encode operations `codecs` take, for `FFmpeg`'s encode queue.
657fn encode_operations(codecs: &[&str]) -> vk::VideoCodecOperationFlagsKHR {
658    ENCODE_EXTENSIONS
659        .iter()
660        .filter(|(codec, _, _)| codecs.contains(codec))
661        .fold(
662            vk::VideoCodecOperationFlagsKHR::empty(),
663            |operations, (_, _, operation)| operations | *operation,
664        )
665}
666
667/// Queries the coded extents each of `codecs`' 8-bit 4:2:0 encoders accepts, for the profile
668/// its Vulkan encoder opens; codecs whose query fails are left out. Asked of the physical
669/// device because `FFmpeg` only answers by failing to open a session.
670///
671/// Only call for a device exposing `VK_KHR_video_queue`, `VK_KHR_video_encode_queue`, and each
672/// codec's encode extension.
673fn encode_extents(
674    entry: &ash::Entry,
675    instance: &ash::Instance,
676    physical: vk::PhysicalDevice,
677    codecs: &[&'static str],
678) -> Vec<(&'static str, VideoEncodeExtent)> {
679    let video = ash::khr::video_queue::Instance::new(entry, instance);
680    codecs
681        .iter()
682        .filter_map(|&codec| {
683            let extent = match codec {
684                "h264" => h264_encode_extent(&video, physical),
685                "hevc" => hevc_encode_extent(&video, physical),
686                _ => None,
687            }?;
688            Some((codec, extent))
689        })
690        .collect()
691}
692
693/// The 8-bit 4:2:0 capabilities `video` answers for `profile` with `per_codec` chained in, or
694/// `None` when the device lacks the profile.
695fn encode_capabilities<'a>(
696    video: &ash::khr::video_queue::Instance,
697    physical: vk::PhysicalDevice,
698    profile: &vk::VideoProfileInfoKHR<'_>,
699    per_codec: &mut (impl vk::ExtendsVideoCapabilitiesKHR + 'a),
700) -> Option<(
701    (vk::Extent2D, vk::Extent2D),
702    vk::VideoEncodeCapabilitiesKHR<'a>,
703)> {
704    let mut encode = vk::VideoEncodeCapabilitiesKHR::default();
705    let mut capabilities = vk::VideoCapabilitiesKHR::default()
706        .push_next(&mut encode)
707        .push_next(per_codec);
708    // SAFETY: the profile chain lives for the call and the device is this instance's. The caller
709    // checked the video queue, encode queue and codec extensions, without which the loader would
710    // dispatch to a null entry point; with them, an unsupported profile returns an error.
711    let result = unsafe {
712        (video.fp().get_physical_device_video_capabilities_khr)(
713            physical,
714            std::ptr::from_ref(profile),
715            &raw mut capabilities,
716        )
717    };
718    let extents = (capabilities.min_coded_extent, capabilities.max_coded_extent);
719    (result == vk::Result::SUCCESS).then(|| {
720        encode.p_next = std::ptr::null_mut();
721        (extents, encode)
722    })
723}
724
725/// The limits of the H.264 profile `h264_vulkan` opens on the device.
726fn h264_encode_extent(
727    video: &ash::khr::video_queue::Instance,
728    physical: vk::PhysicalDevice,
729) -> Option<VideoEncodeExtent> {
730    let (profile, mut extent) = last_supported_profile(|idc| {
731        let mut h264 = vk::VideoEncodeH264ProfileInfoKHR::default().std_profile_idc(idc);
732        let profile = vk::VideoProfileInfoKHR::default()
733            .video_codec_operation(vk::VideoCodecOperationFlagsKHR::ENCODE_H264)
734            .chroma_subsampling(vk::VideoChromaSubsamplingFlagsKHR::TYPE_420)
735            .luma_bit_depth(vk::VideoComponentBitDepthFlagsKHR::TYPE_8)
736            .chroma_bit_depth(vk::VideoComponentBitDepthFlagsKHR::TYPE_8)
737            .push_next(&mut h264);
738        let mut h264_capabilities = vk::VideoEncodeH264CapabilitiesKHR::default();
739        let (coded, encode) =
740            encode_capabilities(video, physical, &profile, &mut h264_capabilities)?;
741        Some(encode_extent(
742            coded,
743            &encode,
744            (
745                h264_capabilities.max_p_picture_l0_reference_count,
746                h264_capabilities.max_b_picture_l0_reference_count,
747                h264_capabilities.max_l1_reference_count,
748            ),
749        ))
750    })?;
751    extent.profile = profile;
752    Some(extent)
753}
754
755/// The limits of HEVC Main, the profile `hevc_vulkan` opens for 8-bit 4:2:0 input.
756fn hevc_encode_extent(
757    video: &ash::khr::video_queue::Instance,
758    physical: vk::PhysicalDevice,
759) -> Option<VideoEncodeExtent> {
760    let mut hevc = vk::VideoEncodeH265ProfileInfoKHR::default()
761        .std_profile_idc(vk::native::StdVideoH265ProfileIdc_STD_VIDEO_H265_PROFILE_IDC_MAIN);
762    let profile = vk::VideoProfileInfoKHR::default()
763        .video_codec_operation(vk::VideoCodecOperationFlagsKHR::ENCODE_H265)
764        .chroma_subsampling(vk::VideoChromaSubsamplingFlagsKHR::TYPE_420)
765        .luma_bit_depth(vk::VideoComponentBitDepthFlagsKHR::TYPE_8)
766        .chroma_bit_depth(vk::VideoComponentBitDepthFlagsKHR::TYPE_8)
767        .push_next(&mut hevc);
768    let mut hevc_capabilities = vk::VideoEncodeH265CapabilitiesKHR::default();
769    let (coded, encode) = encode_capabilities(video, physical, &profile, &mut hevc_capabilities)?;
770    let mut extent = encode_extent(
771        coded,
772        &encode,
773        (
774            hevc_capabilities.max_p_picture_l0_reference_count,
775            hevc_capabilities.max_b_picture_l0_reference_count,
776            hevc_capabilities.max_l1_reference_count,
777        ),
778    );
779    extent.profile = "main";
780    Some(extent)
781}
782
783/// The limits one profile's capabilities describe; the caller fills in `profile`.
784fn encode_extent(
785    (minimum, maximum): (vk::Extent2D, vk::Extent2D),
786    encode: &vk::VideoEncodeCapabilitiesKHR<'_>,
787    (p_l0, b_l0, l1): (u32, u32, u32),
788) -> VideoEncodeExtent {
789    VideoEncodeExtent {
790        profile: "",
791        minimum: (minimum.width, minimum.height),
792        maximum: (maximum.width, maximum.height),
793        // FFmpeg aligns the coded size to this (`vulkan_encode.c`), not to
794        // `pictureAccessGranularity`; the two differ on some drivers (32 and 16 on Mesa ANV).
795        granularity: (
796            encode.encode_input_picture_granularity.width.max(1),
797            encode.encode_input_picture_granularity.height.max(1),
798        ),
799        max_p_picture_l0_references: p_l0,
800        max_b_picture_l0_references: b_l0,
801        max_l1_references: l1,
802        rate_control_modes: [
803            (vk::VideoEncodeRateControlModeFlagsKHR::CBR, "cbr"),
804            (vk::VideoEncodeRateControlModeFlagsKHR::VBR, "vbr"),
805            (vk::VideoEncodeRateControlModeFlagsKHR::DISABLED, "disabled"),
806        ]
807        .into_iter()
808        .filter(|(flag, _)| encode.rate_control_modes.contains(*flag))
809        .map(|(_, name)| name)
810        .collect(),
811    }
812}
813
814/// A Vulkan layer's specification version.
815#[derive(Copy, Clone, Debug, Eq, Ord, PartialEq, PartialOrd)]
816pub struct VulkanLayerVersion {
817    /// Major version.
818    pub major: u32,
819    /// Minor version.
820    pub minor: u32,
821    /// Patch version (the SDK release).
822    pub patch: u32,
823}
824
825impl VulkanLayerVersion {
826    /// The first Khronos validation layer `FFmpeg`'s video sessions survive. Older ones crash or
827    /// hang on the `pNext` chain `FFmpeg` builds for session setup.
828    pub const VIDEO_SESSIONS: Self = Self {
829        major: 1,
830        minor: 4,
831        patch: 0,
832    };
833
834    /// Unpacks a `VK_MAKE_API_VERSION` value.
835    #[must_use]
836    pub const fn from_packed(version: u32) -> Self {
837        Self {
838            major: vk::api_version_major(version),
839            minor: vk::api_version_minor(version),
840            patch: vk::api_version_patch(version),
841        }
842    }
843}
844
845impl fmt::Display for VulkanLayerVersion {
846    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
847        write!(formatter, "{}.{}.{}", self.major, self.minor, self.patch)
848    }
849}
850
851const KHRONOS_VALIDATION: &str = "VK_LAYER_KHRONOS_validation";
852
853/// The version of the Khronos validation layer the loader activated on `instance`, if any.
854///
855/// Asked of the loader instead of derived from the environment: the deprecated
856/// `vkEnumerateDeviceLayerProperties` returns the instance's activated layers, already
857/// resolved against `VK_INSTANCE_LAYERS`, `VK_LOADER_LAYERS_ENABLE` and
858/// `VK_LOADER_LAYERS_DISABLE` by the loader's own rules, which are easy to reimplement wrong.
859fn activated_validation_layer(
860    instance: &ash::Instance,
861    physical: vk::PhysicalDevice,
862) -> Option<VulkanLayerVersion> {
863    // SAFETY: `physical` was enumerated from `instance`, which is alive for the call.
864    let layers = unsafe { instance.enumerate_device_layer_properties(physical) }.ok()?;
865    layers
866        .iter()
867        .find(|layer| {
868            layer
869                .layer_name_as_c_str()
870                .is_ok_and(|name| name.to_bytes() == KHRONOS_VALIDATION.as_bytes())
871        })
872        .map(|layer| VulkanLayerVersion::from_packed(layer.spec_version))
873}
874
875/// The Vulkan-only HAL instance the shared device is made on, built through `wgpu-hal`
876/// directly because it shares no DX12 compiler and has its own flags.
877fn hal_instance() -> Result<wgpu_hal::vulkan::Instance, SharedVulkanError> {
878    let hal_desc = wgpu_hal::InstanceDescriptor {
879        name: "alpha2 shared Vulkan decode",
880        flags: wgpu::InstanceFlags::from_env_or_default(),
881        memory_budget_thresholds: wgpu::MemoryBudgetThresholds::default(),
882        backend_options: wgpu::BackendOptions::from_env_or_default(),
883        telemetry: None,
884        display: None,
885    };
886    // SAFETY: the returned HAL instance owns its loader and Vulkan instance.
887    unsafe {
888        wgpu_hal::vulkan::Instance::init(&hal_desc)
889            .map_err(|error| SharedVulkanError(format!("Vulkan instance: {error}")))
890    }
891}
892
893/// Holds the shared graphics-queue lock for the renderer's submissions.
894///
895/// Only the [`GpuContext`] it is made for receives it, and that context takes and releases each
896/// hold on the same thread, innermost first, within one queue call. That pairing is the raw
897/// lock's contract, and no other code can reach this value.
898#[derive(Debug)]
899struct SharedQueueLock(VulkanQueueLock);
900
901impl ExternalQueueLock for SharedQueueLock {
902    fn lock(&self) {
903        // SAFETY: the owning context releases each hold with one `unlock` on the same thread, in
904        // reverse order.
905        unsafe { self.0.raw_lock() };
906    }
907
908    fn unlock(&self) {
909        // SAFETY: the context releases only its own innermost hold, on the thread that took it.
910        unsafe { self.0.raw_unlock() };
911    }
912}
913
914/// Failure while creating a logical Vulkan device shared by wgpu and `FFmpeg`.
915#[derive(Debug)]
916pub struct SharedVulkanError(String);
917
918impl fmt::Display for SharedVulkanError {
919    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
920        formatter.write_str(&self.0)
921    }
922}
923
924impl Error for SharedVulkanError {}
925
926impl SharedVulkanError {
927    /// An error with `message`.
928    #[must_use]
929    pub fn new(message: impl Into<String>) -> Self {
930        Self(message.into())
931    }
932}
933
934/// An imported bi-planar 4:2:0 image and its two wgpu plane views.
935#[derive(Debug)]
936pub struct ImportedVulkanFrame {
937    /// Plane-zero luma view.
938    pub y: wgpu::TextureView,
939    /// Plane-one interleaved chroma view.
940    pub uv: wgpu::TextureView,
941    /// Sample layout of the imported planes.
942    pub layout: NativePlaneLayout,
943    /// Allocated image extent (the codec's padded coded size, not the display size), which
944    /// presentation normalizes sample coordinates against.
945    pub coded_size: [u32; 2],
946    /// Submission/lifetime lease for the decoder surface.
947    pub lease: Arc<VulkanImportLease>,
948}
949
950/// Allocation counters of a context's import tickets.
951#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
952pub struct ImportTicketStats {
953    /// Tickets created (a command pool, two command buffers, and a fence each).
954    pub created: u64,
955    /// Imports served by a finished, reset ticket.
956    pub reused: u64,
957    /// Tickets reset and ready for an import.
958    pub idle: usize,
959    /// Tickets whose release may still be running.
960    pub pending: usize,
961    /// Tickets given up because their device could not report them finished.
962    pub abandoned: u64,
963}
964
965/// One import ticket and the device and queue family it was made for.
966struct PooledTicket {
967    ticket: NonNull<c_void>,
968    device: u64,
969    queue_family: u32,
970}
971
972/// A returned ticket waits in `pending` until the fences of what it submitted are seen
973/// signalled (polled without blocking at the next import), then is reset and reused. A ticket
974/// whose device cannot say, or that is still running when too many wait, is never reused: it
975/// is destroyed after a bounded wait or else leaked. Those waits run outside the pool's lock
976/// and tickets retired together share one timeout, so a hung device costs it once.
977#[derive(Default)]
978struct ImportTicketPool {
979    state: Mutex<ImportTicketPoolState>,
980}
981
982#[derive(Default)]
983struct ImportTicketPoolState {
984    idle: Vec<PooledTicket>,
985    pending: VecDeque<PooledTicket>,
986    created: u64,
987    reused: u64,
988    abandoned: u64,
989}
990
991// Frames in flight bound how many tickets an export uses; these bound what a burst leaves.
992const MAX_IDLE_IMPORT_TICKETS: usize = 8;
993const MAX_PENDING_IMPORT_TICKETS: usize = 32;
994
995// SAFETY: a ticket is touched only by the pool under its mutex, or by the one lease that took
996// it, which externally synchronizes its Vulkan objects.
997unsafe impl Send for ImportTicketPool {}
998// SAFETY: as for `Send`: every access goes through the mutex.
999unsafe impl Sync for ImportTicketPool {}
1000
1001impl ImportTicketPool {
1002    fn take(
1003        &self,
1004        device: u64,
1005        allocator: u64,
1006        queue_family: u32,
1007    ) -> Result<PooledTicket, BridgeError> {
1008        let mut state = self
1009            .state
1010            .lock()
1011            .unwrap_or_else(std::sync::PoisonError::into_inner);
1012        state.reclaim();
1013        if let Some(index) = state
1014            .idle
1015            .iter()
1016            .position(|idle| idle.device == device && idle.queue_family == queue_family)
1017        {
1018            state.reused = state.reused.saturating_add(1);
1019            return Ok(state.idle.swap_remove(index));
1020        }
1021        state.created = state.created.saturating_add(1);
1022        drop(state);
1023        let (mut raw, mut status) = (std::ptr::null_mut(), 0);
1024        // SAFETY: `device` and `allocator` are the frame's own, read under its lock; the output
1025        // ticket is owned by the caller.
1026        let step = unsafe {
1027            alpha2_native_gpu_vulkan_ticket_create(
1028                device,
1029                allocator,
1030                queue_family,
1031                &raw mut raw,
1032                &raw mut status,
1033            )
1034        };
1035        if step != 0 {
1036            return Err(helper_error("import ticket creation", step, status));
1037        }
1038        NonNull::new(raw)
1039            .map(|ticket| PooledTicket {
1040                ticket,
1041                device,
1042                queue_family,
1043            })
1044            .ok_or(BridgeError::InvalidInput(
1045                "Vulkan import ticket creation returned no ticket",
1046            ))
1047    }
1048
1049    /// Takes back a ticket whatever it submitted; each submission has a fence the pool polls
1050    /// before reuse.
1051    fn give_back(&self, ticket: PooledTicket) {
1052        let mut state = self
1053            .state
1054            .lock()
1055            .unwrap_or_else(std::sync::PoisonError::into_inner);
1056        state.pending.push_back(ticket);
1057        if state.pending.len() > MAX_PENDING_IMPORT_TICKETS {
1058            state.reclaim();
1059        }
1060        let excess = state
1061            .pending
1062            .len()
1063            .saturating_sub(MAX_PENDING_IMPORT_TICKETS);
1064        let oldest = state.pending.drain(..excess).collect::<Vec<_>>();
1065        state.abandoned = state.abandoned.saturating_add(oldest.len() as u64);
1066        // Imports of the device go on while these wait.
1067        drop(state);
1068        retire(oldest);
1069    }
1070
1071    fn stats(&self) -> ImportTicketStats {
1072        let state = self
1073            .state
1074            .lock()
1075            .unwrap_or_else(std::sync::PoisonError::into_inner);
1076        ImportTicketStats {
1077            created: state.created,
1078            reused: state.reused,
1079            idle: state.idle.len(),
1080            pending: state.pending.len(),
1081            abandoned: state.abandoned,
1082        }
1083    }
1084}
1085
1086impl ImportTicketPoolState {
1087    /// Resets every pending ticket whose release has finished and makes it idle, without
1088    /// waiting.
1089    fn reclaim(&mut self) {
1090        let mut index = 0;
1091        while index < self.pending.len() {
1092            let ticket = self.pending[index].ticket;
1093            let mut status = 0;
1094            // SAFETY: the pool owns every pending ticket.
1095            match unsafe { ticket_poll(ticket.as_ptr(), &mut status) } {
1096                0 => index += 1,
1097                1 => {
1098                    let Some(finished) = self.pending.remove(index) else {
1099                        break;
1100                    };
1101                    // SAFETY: nothing the ticket submitted is still running.
1102                    let reset = unsafe { ticket_reset(ticket.as_ptr(), &mut status) };
1103                    if reset != 0 {
1104                        self.abandoned = self.abandoned.saturating_add(1);
1105                    } else if self.idle.len() < MAX_IDLE_IMPORT_TICKETS {
1106                        self.idle.push(finished);
1107                    } else {
1108                        // SAFETY: finished and reset, so nothing uses it.
1109                        unsafe { alpha2_native_gpu_vulkan_import_destroy(ticket.as_ptr()) };
1110                    }
1111                }
1112                _ => {
1113                    // The device cannot say whether it finished, so leak it rather than free it
1114                    // while running.
1115                    self.pending.remove(index);
1116                    self.abandoned = self.abandoned.saturating_add(1);
1117                }
1118            }
1119        }
1120    }
1121}
1122
1123impl Drop for ImportTicketPool {
1124    fn drop(&mut self) {
1125        let state = self
1126            .state
1127            .get_mut()
1128            .unwrap_or_else(std::sync::PoisonError::into_inner);
1129        for idle in state.idle.drain(..) {
1130            // SAFETY: idle tickets are reset and unused.
1131            unsafe { alpha2_native_gpu_vulkan_import_destroy(idle.ticket.as_ptr()) };
1132        }
1133        retire(state.pending.drain(..));
1134    }
1135}
1136
1137/// Destroys owned tickets once their work has finished, all within one wait timeout; a ticket
1138/// still unfinished then is leaked rather than freed under the GPU.
1139fn retire(tickets: impl IntoIterator<Item = PooledTicket>) {
1140    #[cfg(test)]
1141    inject::retire_begins();
1142    let deadline = std::time::Instant::now().checked_add(wait_timeout());
1143    for pooled in tickets {
1144        let left = deadline.map_or(std::time::Duration::MAX, |deadline| {
1145            deadline.saturating_duration_since(std::time::Instant::now())
1146        });
1147        let nanoseconds = u64::try_from(left.as_nanos()).unwrap_or(u64::MAX);
1148        // SAFETY: the pool gives up the ticket here; the helper frees it only after its fences
1149        // signal.
1150        unsafe { alpha2_native_gpu_vulkan_import_retire(pooled.ticket.as_ptr(), nanoseconds) };
1151    }
1152}
1153
1154/// Owns the imported texture, `FFmpeg` frame, and native transition commands.
1155pub struct VulkanImportLease {
1156    frame: Arc<VulkanFrameLease>,
1157    _texture: wgpu::Texture,
1158    gpu: GpuContext,
1159    batch: Arc<VulkanSubmissionBatch>,
1160    tickets: Arc<ImportTicketPool>,
1161    /// Taken only by the drop, which returns it to `tickets`; used only through [`Self::lock`].
1162    ticket: Option<PooledTicket>,
1163    staged_signals: Mutex<Vec<StagedSignal>>,
1164    queued: AtomicBool,
1165    acquired: AtomicBool,
1166    released: AtomicBool,
1167    retained_bytes: u64,
1168}
1169
1170#[derive(Clone, Copy, Debug)]
1171struct StagedSignal {
1172    semaphore: u64,
1173    acquired_value: u64,
1174    signal_value: u64,
1175}
1176
1177#[derive(Default)]
1178struct VulkanSubmissionBatch {
1179    pending: Mutex<Vec<Weak<VulkanImportLease>>>,
1180}
1181
1182impl VulkanSubmissionBatch {
1183    fn enqueue(&self, lease: &Arc<VulkanImportLease>) {
1184        if !lease.queued.swap(true, Ordering::AcqRel) {
1185            self.pending
1186                .lock()
1187                .unwrap_or_else(std::sync::PoisonError::into_inner)
1188                .push(Arc::downgrade(lease));
1189        }
1190    }
1191
1192    fn flush(&self) -> Result<(), BridgeError> {
1193        let leases = self
1194            .pending
1195            .lock()
1196            .unwrap_or_else(std::sync::PoisonError::into_inner)
1197            .drain(..)
1198            .filter_map(|lease| lease.upgrade())
1199            .filter(|lease| !lease.acquired.load(Ordering::Acquire))
1200            .collect::<Vec<_>>();
1201        if leases.is_empty() {
1202            return Ok(());
1203        }
1204        // Draining cleared the queue, so leases still unacquired after a failure must be
1205        // re-enqueueable.
1206        let result = flush_leases(&leases);
1207        if result.is_err() {
1208            for lease in &leases {
1209                if !lease.acquired.load(Ordering::Acquire) {
1210                    lease.queued.store(false, Ordering::Release);
1211                }
1212            }
1213        }
1214        result
1215    }
1216}
1217
1218/// Acquires every queued import for the renderer's next submission.
1219///
1220/// Each frame is acquired under its own lock from its current state: the barrier starts from
1221/// its current layout and waits on the value `FFmpeg` last signalled. Batching all barriers
1222/// under one lock would let an intervening decode (using a frame as a reference) move a frame
1223/// on, so the batch would wait on a stale value.
1224///
1225/// The sampling submission's signal is staged under that same lock, before `FFmpeg` sees the
1226/// frame again. Otherwise a decode referencing the frame could move it to its DPB layout while
1227/// the renderer still samples it (VUID-vkCmdDraw-None-09600) and signal the frame's timeline
1228/// from the decode queue out of order with the renderer, leaving `FFmpeg` waiting forever.
1229///
1230/// Only one frame lock is held at a time, so this cannot deadlock against a decode that locks
1231/// several frames; the cost is one queue submission per imported frame.
1232fn flush_leases(leases: &[Arc<VulkanImportLease>]) -> Result<(), BridgeError> {
1233    for lease in leases {
1234        let mut access = lease.lock()?;
1235        // Decided under the frame's lock, so a lease two flushes reach is acquired once.
1236        if lease.acquired.load(Ordering::Acquire) {
1237            continue;
1238        }
1239        let mut status = 0;
1240        // SAFETY: the ticket was created for this retained frame at import, and the frame and queue
1241        // stay locked for the submission.
1242        let step = unsafe { acquire_submit(&mut access, &mut status) };
1243        if step != 0 {
1244            return Err(helper_error("import acquire", step, status));
1245        }
1246        lease.acquired.store(true, Ordering::Release);
1247        // The acquire is submitted regardless of staging, so commit its state now.
1248        access.frame.commit();
1249        // SAFETY: staging records as the frame's timeline values the signals added to the
1250        // renderer's next submission, which samples this frame; the layouts stay those the
1251        // acquire recorded.
1252        lease.stage_submission_signal(unsafe { access.frame.access_mut() })?;
1253    }
1254    Ok(())
1255}
1256
1257// SAFETY: shared state is behind locks. The ticket's Vulkan objects are used only through
1258// `LeaseAccess`, under the frame's lock (which also holds the shared queue lock), and the drop
1259// has the lease to itself. Staged signals are behind a mutex, flags are atomics, and the frame
1260// and wgpu objects synchronize themselves.
1261unsafe impl Send for VulkanImportLease {}
1262// SAFETY: as for `Send`: `&self` reaches the ticket only through `Self::lock`.
1263unsafe impl Sync for VulkanImportLease {}
1264
1265impl fmt::Debug for VulkanImportLease {
1266    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1267        formatter
1268            .debug_struct("VulkanImportLease")
1269            .field("released", &self.released.load(Ordering::Acquire))
1270            .field("retained_bytes", &self.retained_bytes)
1271            .finish_non_exhaustive()
1272    }
1273}
1274
1275impl VulkanImportLease {
1276    /// Locks the frame for a use of the ticket, the only way `&self` reaches it.
1277    fn lock(&self) -> Result<LeaseAccess<'_>, BridgeError> {
1278        let ticket = self
1279            .ticket
1280            .as_ref()
1281            .map(|pooled| pooled.ticket)
1282            .ok_or(BridgeError::InvalidInput("missing Vulkan import ticket"))?;
1283        Ok(LeaseAccess {
1284            frame: self.frame.lock_access()?,
1285            ticket,
1286        })
1287    }
1288
1289    /// Approximate decoded-surface bytes retained by this import.
1290    #[must_use]
1291    pub const fn retained_bytes(&self) -> u64 {
1292        self.retained_bytes
1293    }
1294
1295    /// Timeline signals this lease has staged on the wgpu queue: nonzero only between staging
1296    /// the sampling submission and its completion. A nonzero count when the next frame starts
1297    /// staging means a stale signal would ride on it.
1298    #[must_use]
1299    pub fn staged_signals(&self) -> usize {
1300        self.staged_signals
1301            .lock()
1302            .unwrap_or_else(std::sync::PoisonError::into_inner)
1303            .len()
1304    }
1305
1306    /// Queues this import for the next [`Self::flush_submission`], which acquires the frame and
1307    /// adds its timeline signals to the sampling wgpu submission. Queuing twice is harmless.
1308    pub fn prepare_submission(self: &Arc<Self>) {
1309        self.batch.enqueue(self);
1310    }
1311
1312    /// Acquires every queued import of this context, one native submission per frame under that
1313    /// frame's lock, and stages the signals of the sampling wgpu submission.
1314    ///
1315    /// # Errors
1316    /// Returns an error if a frame cannot be locked, its acquire fails, or its signals cannot be
1317    /// staged. Imports not yet acquired can be queued again for a retry.
1318    pub fn flush_submission(&self) -> Result<(), BridgeError> {
1319        self.batch.flush()
1320    }
1321
1322    /// Stages the sampling submission's timeline signals and records them as the frame's values.
1323    /// `access` is the frame's lock, held since the acquire.
1324    fn stage_submission_signal(&self, access: &mut VulkanFrameAccess) -> Result<(), BridgeError> {
1325        let mut staged = self
1326            .staged_signals
1327            .lock()
1328            .unwrap_or_else(std::sync::PoisonError::into_inner);
1329        if !staged.is_empty() || self.released.load(Ordering::Acquire) {
1330            return Ok(());
1331        }
1332        // SAFETY: the queue was created from this context's Vulkan OpenDevice.
1333        let queue = unsafe { self.gpu.queue().as_hal::<wgpu_hal::api::Vulkan>() }
1334            .ok_or(BridgeError::InvalidInput("renderer queue is not Vulkan"))?;
1335        let descriptor = access.frame_mut();
1336        for index in 0..descriptor.images.len() {
1337            if descriptor.images[index] == 0 {
1338                continue;
1339            }
1340            let semaphore = descriptor.semaphores[index];
1341            let acquired_value = descriptor.semaphore_values[index];
1342            if semaphore == 0 {
1343                return Err(BridgeError::InvalidInput("frame has no timeline semaphore"));
1344            }
1345            if let Some(existing) = staged
1346                .iter_mut()
1347                .find(|existing| existing.semaphore == semaphore)
1348            {
1349                existing.acquired_value = existing.acquired_value.max(acquired_value);
1350                existing.signal_value = existing.acquired_value.saturating_add(1);
1351            } else {
1352                staged.push(StagedSignal {
1353                    semaphore,
1354                    acquired_value,
1355                    signal_value: acquired_value.saturating_add(1),
1356                });
1357            }
1358        }
1359        for signal in &*staged {
1360            queue.add_signal_semaphore(
1361                vk::Semaphore::from_raw(signal.semaphore),
1362                Some(signal.signal_value),
1363            );
1364            for index in 0..descriptor.images.len() {
1365                if descriptor.semaphores[index] == signal.semaphore {
1366                    descriptor.semaphore_values[index] = signal.signal_value;
1367                }
1368            }
1369        }
1370        Ok(())
1371    }
1372
1373    /// Records that the wgpu submission sampling this import was made.
1374    ///
1375    /// If the frame's signals were staged on it, the frame already records its value and
1376    /// layout. Otherwise the planes are returned to `FFmpeg`'s layout in a submission of their
1377    /// own.
1378    ///
1379    /// # Errors
1380    /// Returns an error if the frame can no longer be locked or submitted.
1381    pub fn submitted(&self) -> Result<(), BridgeError> {
1382        if self.released.load(Ordering::Acquire) {
1383            return Ok(());
1384        }
1385        if !self
1386            .staged_signals
1387            .lock()
1388            .unwrap_or_else(std::sync::PoisonError::into_inner)
1389            .is_empty()
1390        {
1391            self.released.store(true, Ordering::Release);
1392            return Ok(());
1393        }
1394        let mut access = self.lock()?;
1395        // Decided under the frame's lock, so a lease two callers reach is released once.
1396        if self.released.load(Ordering::Acquire) {
1397            return Ok(());
1398        }
1399        let mut status = 0;
1400        // SAFETY: the ticket was created for this retained frame and this lease owns it until
1401        // queue completion.
1402        let step = unsafe { release(&mut access, &mut status) };
1403        if step != 0 {
1404            return Err(helper_error("import release", step, status));
1405        }
1406        access.frame.commit();
1407        self.released.store(true, Ordering::Release);
1408        Ok(())
1409    }
1410}
1411
1412impl Drop for VulkanImportLease {
1413    /// Leaves the frame in a state `FFmpeg` can continue from, and returns the ticket.
1414    ///
1415    /// An acquired lease whose sampling submission never released it still owes the frame its
1416    /// signal. If the signal was staged, the frame records that value and a later decode may
1417    /// already wait on it, so removing the signal alone would hang the decode queue. Under the
1418    /// frame's lock (held by `FFmpeg` from reading the value to submitting its wait), an
1419    /// unsubmitted signal is taken off wgpu's queue and raised by a submission of its own after
1420    /// the acquire. A lease with nothing staged releases the frame from its current state.
1421    ///
1422    /// The ticket goes back to the pool, which reuses it only after every fence it submitted
1423    /// has signalled, since an acquire may still be waiting on the decoder.
1424    fn drop(&mut self) {
1425        let Some(pooled) = self.ticket.take() else {
1426            return;
1427        };
1428        if self.acquired.load(Ordering::Acquire) && !self.released.load(Ordering::Acquire) {
1429            let staged = std::mem::take(
1430                self.staged_signals
1431                    .get_mut()
1432                    .unwrap_or_else(std::sync::PoisonError::into_inner),
1433            );
1434            if let Ok(frame) = self.frame.lock_access() {
1435                // The drop has the lease, and so its ticket, to itself.
1436                let mut lease = LeaseAccess {
1437                    frame,
1438                    ticket: pooled.ticket,
1439                };
1440                if staged.is_empty() {
1441                    let mut status = 0;
1442                    // SAFETY: the ticket is this frame's and the guard holds its lock.
1443                    if unsafe { release(&mut lease, &mut status) } == 0 {
1444                        lease.frame.commit();
1445                    }
1446                } else {
1447                    // SAFETY: the queue belongs to the shared Vulkan device.
1448                    let queue = unsafe { self.gpu.queue().as_hal::<wgpu_hal::api::Vulkan>() };
1449                    for signal in &staged {
1450                        let unsubmitted = queue.as_ref().is_some_and(|queue| {
1451                            queue.remove_signal_semaphore(vk::Semaphore::from_raw(signal.semaphore))
1452                        });
1453                        if unsubmitted {
1454                            let mut status = 0;
1455                            // SAFETY: the guard holds the frame's and queue's locks; the
1456                            // semaphore is the frame's timeline, which the acquire takes to
1457                            // `acquired_value`.
1458                            let _ = unsafe {
1459                                alpha2_native_gpu_vulkan_signal(
1460                                    lease.frame.access_mut(),
1461                                    signal.semaphore,
1462                                    signal.acquired_value,
1463                                    signal.signal_value,
1464                                    &raw mut status,
1465                                )
1466                            };
1467                        }
1468                    }
1469                }
1470            }
1471        }
1472        self.tickets.give_back(pooled);
1473    }
1474}
1475
1476/// Device features `FFmpeg`'s Vulkan code uses that wgpu does not enable.
1477///
1478/// `FFmpeg` enables these on devices it creates, and uses them regardless on this wgpu-created
1479/// one: `vkQueueSubmit2` needs `synchronization2`, YCbCr conversion needs
1480/// `samplerYcbcrConversion`, profile-independent images need `videoMaintenance1`, and VP9
1481/// decode needs `videoDecodeVP9`.
1482#[derive(Clone, Copy, Debug, Default)]
1483#[allow(clippy::struct_excessive_bools)]
1484struct FfmpegDeviceFeatures {
1485    synchronization2: bool,
1486    sampler_ycbcr_conversion: bool,
1487    video_maintenance1: bool,
1488    video_decode_vp9: bool,
1489}
1490
1491/// The [`FfmpegDeviceFeatures`] `physical` supports; `video_maintenance1` and `video_decode_vp9`
1492/// are only asked for when their extensions are enabled.
1493fn ffmpeg_device_features(
1494    instance: &ash::Instance,
1495    physical: vk::PhysicalDevice,
1496    video_maintenance1: bool,
1497    video_decode_vp9: bool,
1498) -> FfmpegDeviceFeatures {
1499    let mut synchronization2 = vk::PhysicalDeviceSynchronization2Features::default();
1500    let mut ycbcr = vk::PhysicalDeviceSamplerYcbcrConversionFeatures::default();
1501    let mut maintenance = vk::PhysicalDeviceVideoMaintenance1FeaturesKHR::default();
1502    let mut vp9 = VideoDecodeVp9Features::default();
1503    let mut features = vk::PhysicalDeviceFeatures2::default()
1504        .push_next(&mut synchronization2)
1505        .push_next(&mut ycbcr);
1506    if video_maintenance1 {
1507        features = features.push_next(&mut maintenance);
1508    }
1509    if video_decode_vp9 {
1510        features = features.push_next(&mut vp9);
1511    }
1512    // SAFETY: `physical` was enumerated from `instance`, and every chained structure outlives
1513    // the call.
1514    unsafe { instance.get_physical_device_features2(physical, &mut features) };
1515    FfmpegDeviceFeatures {
1516        synchronization2: synchronization2.synchronization2 == vk::TRUE,
1517        sampler_ycbcr_conversion: ycbcr.sampler_ycbcr_conversion == vk::TRUE,
1518        video_maintenance1: video_maintenance1 && maintenance.video_maintenance1 == vk::TRUE,
1519        video_decode_vp9: video_decode_vp9 && vp9.video_decode_vp9 == vk::TRUE,
1520    }
1521}
1522
1523/// Whether the device `features` would create enables `timelineSemaphore`.
1524fn enables_timeline_semaphores(features: &mut wgpu_hal::vulkan::PhysicalDeviceFeatures) -> bool {
1525    let info = features.add_to_device_create(vk::DeviceCreateInfo::default());
1526    let mut next = info.p_next.cast::<vk::BaseInStructure<'_>>();
1527    // SAFETY: every structure of the chain lives in `features`, which outlives this walk, and
1528    // each begins with `sType` and `pNext`.
1529    while let Some(structure) = unsafe { next.as_ref() } {
1530        if structure.s_type == vk::StructureType::PHYSICAL_DEVICE_TIMELINE_SEMAPHORE_FEATURES {
1531            // SAFETY: the structure type names this layout.
1532            let timeline =
1533                unsafe { &*next.cast::<vk::PhysicalDeviceTimelineSemaphoreFeatures<'_>>() };
1534            return timeline.timeline_semaphore == vk::TRUE;
1535        }
1536        next = structure.p_next;
1537    }
1538    false
1539}
1540
1541/// `VK_KHR_video_decode_vp9`, which ash 0.38 (Vulkan 1.3.281) predates. Values from
1542/// `vulkan_core.h` 1.4.330.
1543const VIDEO_DECODE_VP9_NAME: &CStr = c"VK_KHR_video_decode_vp9";
1544const DECODE_VP9: vk::VideoCodecOperationFlagsKHR = vk::VideoCodecOperationFlagsKHR::from_raw(0x8);
1545const VIDEO_DECODE_VP9_FEATURES: vk::StructureType = vk::StructureType::from_raw(1_000_514_000);
1546
1547/// `VkPhysicalDeviceVideoDecodeVP9FeaturesKHR` (`vulkan_core.h` 1.4.330, line 13215).
1548#[repr(C)]
1549#[derive(Clone, Copy, Debug)]
1550struct VideoDecodeVp9Features {
1551    s_type: vk::StructureType,
1552    p_next: *mut c_void,
1553    video_decode_vp9: vk::Bool32,
1554}
1555
1556impl Default for VideoDecodeVp9Features {
1557    fn default() -> Self {
1558        Self {
1559            s_type: VIDEO_DECODE_VP9_FEATURES,
1560            p_next: std::ptr::null_mut(),
1561            video_decode_vp9: vk::FALSE,
1562        }
1563    }
1564}
1565
1566// SAFETY: this is the C structure, starting with `sType` and `pNext`, and the specification
1567// lists it as extending both.
1568unsafe impl vk::ExtendsPhysicalDeviceFeatures2 for VideoDecodeVp9Features {}
1569// SAFETY: as above.
1570unsafe impl vk::ExtendsDeviceCreateInfo for VideoDecodeVp9Features {}
1571
1572impl FfmpegDeviceFeatures {
1573    /// Appends the supported features to the device's creation chain. wgpu builds its own
1574    /// feature structures afterwards and uses none of these. They live for the process because
1575    /// the chain is read after the callback returns.
1576    fn enable(self, create_info: &mut vk::DeviceCreateInfo<'_>) {
1577        let mut info = std::mem::take(create_info);
1578        if self.synchronization2 {
1579            info = info.push_next(Box::leak(Box::new(
1580                vk::PhysicalDeviceSynchronization2Features::default().synchronization2(true),
1581            )));
1582        }
1583        if self.sampler_ycbcr_conversion {
1584            info = info.push_next(Box::leak(Box::new(
1585                vk::PhysicalDeviceSamplerYcbcrConversionFeatures::default()
1586                    .sampler_ycbcr_conversion(true),
1587            )));
1588        }
1589        if self.video_maintenance1 {
1590            info = info.push_next(Box::leak(Box::new(
1591                vk::PhysicalDeviceVideoMaintenance1FeaturesKHR::default().video_maintenance1(true),
1592            )));
1593        }
1594        if self.video_decode_vp9 {
1595            info = info.push_next(Box::leak(Box::new(VideoDecodeVp9Features {
1596                video_decode_vp9: vk::TRUE,
1597                ..VideoDecodeVp9Features::default()
1598            })));
1599        }
1600        *create_info = info;
1601    }
1602}
1603
1604/// One Vulkan logical device adopted by both the renderer and `FFmpeg`.
1605#[derive(Clone)]
1606pub struct SharedVulkanContext {
1607    // Fields drop in order; idle import tickets are Vulkan objects of the device, so they go
1608    // first.
1609    import_tickets: Arc<ImportTicketPool>,
1610    // Drop FFmpeg references before wgpu destroys the raw device.
1611    ffmpeg_device: AVHWDeviceContext,
1612    gpu: GpuContext,
1613    submission_batch: Arc<VulkanSubmissionBatch>,
1614    identity: NativeGpuIdentity,
1615    decode_codecs: Vec<&'static str>,
1616    encode_codecs: Vec<&'static str>,
1617    encode_extents: Vec<(&'static str, VideoEncodeExtent)>,
1618    validation_layer: Option<VulkanLayerVersion>,
1619}
1620
1621impl fmt::Debug for SharedVulkanContext {
1622    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1623        formatter
1624            .debug_struct("SharedVulkanContext")
1625            .field("identity", &self.identity)
1626            .field("decode_codecs", &self.decode_codecs)
1627            .field("encode_codecs", &self.encode_codecs)
1628            .finish_non_exhaustive()
1629    }
1630}
1631
1632impl SharedVulkanContext {
1633    /// Creates the shared device on the adapter the host's choice makes by default
1634    /// ([`choose_shared_vulkan`] under `ALPHA2_GPU_ADAPTER`, decode allowed).
1635    ///
1636    /// # Errors
1637    /// Returns why no adapter carries the shared device.
1638    pub fn create() -> Result<Self, SharedVulkanError> {
1639        let choice = choose_shared_vulkan(&alpha2_gpu::AdapterPolicy::from_env(), true, true)?;
1640        choice.context.ok_or_else(|| {
1641            SharedVulkanError(
1642                choice
1643                    .unavailable
1644                    .unwrap_or_else(|| choice.report.explanation.clone()),
1645            )
1646        })
1647    }
1648
1649    /// Creates the shared Vulkan 1.3 device, with wgpu, video decode, and NV12 support, on the
1650    /// adapter at Vulkan enumeration `index` (as `ALPHA2_GPU_ADAPTER` names it).
1651    ///
1652    /// # Errors
1653    /// Returns why the adapter cannot carry the shared device, or the failing initialization
1654    /// step.
1655    #[allow(clippy::too_many_lines)]
1656    pub fn create_on(index: usize) -> Result<Self, SharedVulkanError> {
1657        let _turn = alpha2_gpu::serialize_acquisition();
1658        let hal_instance = hal_instance()?;
1659        // SAFETY: adapter enumeration does not require a surface.
1660        let mut adapters = unsafe { hal_instance.enumerate_adapters(None) };
1661        if index >= adapters.len() {
1662            return Err(SharedVulkanError(format!(
1663                "there is no Vulkan adapter {index}; there are {}",
1664                adapters.len()
1665            )));
1666        }
1667        let exposed = adapters.swap_remove(index);
1668        let physical = exposed.adapter.raw_physical_device();
1669        let shared_instance = exposed.adapter.shared_instance();
1670        let raw_instance = shared_instance.raw_instance().handle();
1671        let validation_layer = activated_validation_layer(shared_instance.raw_instance(), physical);
1672        let mut plan = adapter_video_plan(shared_instance.raw_instance(), &exposed)
1673            .map_err(SharedVulkanError)?;
1674        let ffmpeg_features = ffmpeg_device_features(
1675            shared_instance.raw_instance(),
1676            physical,
1677            plan.video_extensions
1678                .contains(&ash::khr::video_maintenance1::NAME),
1679            plan.video_extensions.contains(&VIDEO_DECODE_VP9_NAME),
1680        );
1681        plan.restrict_to(ffmpeg_features);
1682        let VideoPlan {
1683            decode_family,
1684            encode_family,
1685            video_extensions,
1686            decode_caps,
1687            decode_codecs,
1688            encode_codecs,
1689        } = plan;
1690        let graphics_family = 0;
1691        // Queried only once the device is known to expose the video queue and codec encode
1692        // extensions (otherwise the loader trampoline has no function behind it), and before
1693        // the adapter moves into wgpu.
1694        let encode_extents = if encode_family.is_some() {
1695            encode_extents(
1696                shared_instance.entry(),
1697                shared_instance.raw_instance(),
1698                physical,
1699                &encode_codecs,
1700            )
1701        } else {
1702            Vec::new()
1703        };
1704        // P010 is optional: without it 8-bit streams still decode and 10-bit sources fall back
1705        // to software.
1706        let required_features = (exposed.features
1707            & (wgpu::Features::TIMESTAMP_QUERY
1708                | wgpu::Features::TEXTURE_FORMAT_P010
1709                | wgpu::Features::TEXTURE_FORMAT_16BIT_NORM))
1710            | wgpu::Features::TEXTURE_FORMAT_NV12;
1711        let required_limits = wgpu::Limits::downlevel_webgl2_defaults()
1712            .using_resolution(exposed.capabilities.limits.clone());
1713        let enabled_extensions = exposed
1714            .adapter
1715            .required_device_extensions(required_features);
1716        let mut device_features = exposed
1717            .adapter
1718            .physical_device_features(&enabled_extensions, required_features);
1719        let core = device_features.get_core();
1720        // `FFmpeg` waits on and signals timeline semaphores; wgpu-hal enables them only where
1721        // the adapter has them.
1722        if !enables_timeline_semaphores(&mut device_features) {
1723            return Err(SharedVulkanError(
1724                "the device does not enable timeline semaphores, which FFmpeg needs".to_owned(),
1725            ));
1726        }
1727        let extra_family = decode_family;
1728        let extra_encode_family =
1729            encode_family.filter(|family| *family != graphics_family && *family != decode_family);
1730        let extra_extensions = video_extensions.clone();
1731        // SAFETY: all added extensions and queues were queried from this adapter.
1732        let open = unsafe {
1733            exposed.adapter.open_with_callback(
1734                required_features,
1735                &required_limits,
1736                &wgpu::MemoryHints::Performance,
1737                Some(Box::new(move |args| {
1738                    ffmpeg_features.enable(args.create_info);
1739                    for extension in extra_extensions {
1740                        if !args.extensions.contains(&extension) {
1741                            args.extensions.push(extension);
1742                        }
1743                    }
1744                    if extra_family != 0 {
1745                        args.queue_create_infos.push(
1746                            vk::DeviceQueueCreateInfo::default()
1747                                .queue_family_index(extra_family)
1748                                .queue_priorities(&[1.0]),
1749                        );
1750                    }
1751                    if let Some(family) = extra_encode_family {
1752                        args.queue_create_infos.push(
1753                            vk::DeviceQueueCreateInfo::default()
1754                                .queue_family_index(family)
1755                                .queue_priorities(&[1.0]),
1756                        );
1757                    }
1758                })),
1759            )
1760        }
1761        .map_err(|error| SharedVulkanError(format!("shared Vulkan device: {error}")))?;
1762        let raw_device = open.device.raw_device().handle();
1763        let device_extensions = open
1764            .device
1765            .enabled_device_extensions()
1766            .iter()
1767            .map(|name| name.to_string_lossy().into_owned())
1768            .collect::<Vec<_>>();
1769        let instance_extensions = shared_instance
1770            .extensions()
1771            .iter()
1772            .map(|name| name.to_string_lossy().into_owned())
1773            .collect::<Vec<_>>();
1774        // SAFETY: the instance, physical device, and device are the ones wgpu just opened with
1775        // these queues and extensions, and `Self` drops the `FFmpeg` context first.
1776        let ffmpeg_device = unsafe {
1777            create_vulkan_device_context(&VulkanDeviceInfo {
1778                instance: raw_instance.as_raw(),
1779                physical_device: physical.as_raw(),
1780                device: raw_device.as_raw(),
1781                graphics_queue_family: 0,
1782                graphics_queue_count: 1,
1783                decode_queue_family: decode_family,
1784                decode_queue_count: 1,
1785                decode_video_caps: decode_caps.as_raw(),
1786                encode_queue_family: encode_family.unwrap_or(0),
1787                encode_queue_count: u32::from(encode_family.is_some()),
1788                encode_video_caps: encode_family
1789                    .map_or(0, |_| encode_operations(&encode_codecs).as_raw()),
1790                core_features: [
1791                    core.shader_image_gather_extended,
1792                    core.fragment_stores_and_atomics,
1793                    core.shader_int64,
1794                    core.vertex_pipeline_stores_and_atomics,
1795                ],
1796                timeline_semaphore: 1,
1797                synchronization2: u32::from(ffmpeg_features.synchronization2),
1798                sampler_ycbcr_conversion: u32::from(ffmpeg_features.sampler_ycbcr_conversion),
1799                video_maintenance1: u32::from(ffmpeg_features.video_maintenance1),
1800                video_decode_vp9: u32::from(ffmpeg_features.video_decode_vp9),
1801                instance_extensions,
1802                device_extensions,
1803            })
1804        }
1805        .map_err(|error| SharedVulkanError(format!("FFmpeg Vulkan device: {error}")))?;
1806        // SAFETY: the adapter and instance originate from the same HAL object.
1807        let wgpu_instance =
1808            unsafe { wgpu::Instance::from_hal::<wgpu_hal::api::Vulkan>(hal_instance) };
1809        // SAFETY: `exposed` was enumerated from the HAL instance `wgpu_instance` now wraps.
1810        let adapter = unsafe { wgpu_instance.create_adapter_from_hal(exposed) };
1811        let descriptor = wgpu::DeviceDescriptor {
1812            label: Some("alpha2 shared Vulkan decode"),
1813            required_features,
1814            required_limits,
1815            ..Default::default()
1816        };
1817        // SAFETY: OpenDevice has the descriptor's exact features and limits.
1818        let (device, queue) = unsafe { adapter.create_device_from_hal(open, &descriptor) }
1819            .map_err(|error| SharedVulkanError(format!("wgpu adoption: {error}")))?;
1820        // wgpu and FFmpeg submit to the same graphics queue, which Vulkan requires to be
1821        // externally synchronized, so both take the same lock.
1822        let queue_lock: Arc<dyn ExternalQueueLock> = Arc::new(SharedQueueLock(
1823            VulkanQueueLock::new(ffmpeg_device.clone(), 0)
1824                .map_err(|error| SharedVulkanError(format!("FFmpeg Vulkan queue lock: {error}")))?,
1825        ));
1826        let gpu = GpuContext::from_parts_with_queue_lock(adapter, device, queue, Some(queue_lock));
1827        Ok(Self {
1828            ffmpeg_device,
1829            gpu,
1830            submission_batch: Arc::new(VulkanSubmissionBatch::default()),
1831            import_tickets: Arc::new(ImportTicketPool::default()),
1832            identity: NativeGpuIdentity {
1833                physical_device: physical.as_raw(),
1834                device: raw_device.as_raw(),
1835                epoch: 1,
1836            },
1837            decode_codecs,
1838            encode_extents,
1839            encode_codecs,
1840            validation_layer,
1841        })
1842    }
1843
1844    /// Renderer context backed by the shared logical device.
1845    #[must_use]
1846    pub fn gpu(&self) -> GpuContext {
1847        self.gpu.clone()
1848    }
1849
1850    /// `FFmpeg` device reference for one decoder session.
1851    #[must_use]
1852    pub fn ffmpeg_device(&self) -> AVHWDeviceContext {
1853        self.ffmpeg_device.clone()
1854    }
1855
1856    /// Raw-device cache identity.
1857    #[must_use]
1858    pub const fn identity(&self) -> NativeGpuIdentity {
1859        self.identity
1860    }
1861
1862    /// Whether this device can present 10-bit decoded planes.
1863    #[must_use]
1864    pub fn supports_ten_bit(&self) -> bool {
1865        self.gpu
1866            .device()
1867            .features()
1868            .contains(wgpu::Features::TEXTURE_FORMAT_P010)
1869    }
1870
1871    /// Decode codecs (`h264`, `hevc`, `av1`, `vp9`) whose extensions the device
1872    /// was created with.
1873    #[must_use]
1874    pub fn decode_codecs(&self) -> &[&'static str] {
1875        &self.decode_codecs
1876    }
1877
1878    /// The Khronos validation layer the loader activated on this instance (by wgpu's
1879    /// validation flag or the environment), and its version.
1880    #[must_use]
1881    pub const fn validation_layer(&self) -> Option<VulkanLayerVersion> {
1882        self.validation_layer
1883    }
1884
1885    /// Why `FFmpeg` must not open a video session on this device, or `None` when it may.
1886    ///
1887    /// Validation layers older than [`VulkanLayerVersion::VIDEO_SESSIONS`] crash or hang in
1888    /// session setup, for decode and encode alike, so both paths ask this.
1889    #[must_use]
1890    pub fn video_session_hazard(&self) -> Option<String> {
1891        self.validation_layer
1892            .filter(|layer| *layer < VulkanLayerVersion::VIDEO_SESSIONS)
1893            .map(|layer| {
1894                format!(
1895                    "the loaded Vulkan validation layer is {layer}, and layers older than {} \
1896                     crash in FFmpeg's video session setup",
1897                    VulkanLayerVersion::VIDEO_SESSIONS
1898                )
1899            })
1900    }
1901
1902    /// Video-encode codecs this device created a queue and extensions for. Empty without an
1903    /// encode queue, in which case `FFmpeg`'s Vulkan encoder cannot open.
1904    #[must_use]
1905    pub fn encode_codecs(&self) -> &[&'static str] {
1906        &self.encode_codecs
1907    }
1908
1909    /// Output sizes this device's encoder of `codec` (`h264`, `hevc`) accepts, from
1910    /// `vkGetPhysicalDeviceVideoCapabilitiesKHR`. Exports outside it take the readback path.
1911    ///
1912    /// `None` when the device does not encode `codec` or the query failed.
1913    #[must_use]
1914    pub fn encode_extent(&self, codec: &str) -> Option<&VideoEncodeExtent> {
1915        self.encode_extents
1916            .iter()
1917            .find(|(encoded, _)| *encoded == codec)
1918            .map(|(_, extent)| extent)
1919    }
1920
1921    /// Allocation counters of the import tickets this device reuses.
1922    #[must_use]
1923    pub fn import_ticket_stats(&self) -> ImportTicketStats {
1924        self.import_tickets.stats()
1925    }
1926
1927    /// Imports one same-device `FFmpeg` NV12 or P010 surface as plane views.
1928    ///
1929    /// The acquire waits on `FFmpeg`'s latest timeline value without a CPU wait. Call
1930    /// `submitted()` on the returned lease right after the wgpu submission that samples it.
1931    ///
1932    /// # Errors
1933    /// Returns an error for a different device, an unsupported image layout, or a failed Vulkan
1934    /// transition submission.
1935    #[allow(clippy::too_many_lines)]
1936    pub fn import_surface(
1937        &self,
1938        frame: Arc<VulkanFrameLease>,
1939    ) -> Result<ImportedVulkanFrame, BridgeError> {
1940        let info = frame.info()?;
1941        if info.device != self.identity.device
1942            || info.physical_device != self.identity.physical_device
1943        {
1944            return Err(BridgeError::InvalidInput(
1945                "decoded frame belongs to another Vulkan device",
1946            ));
1947        }
1948        let layout = match (info.software_format, info.formats[0]) {
1949            (rsmpeg::ffi::AV_PIX_FMT_NV12, format)
1950                if format
1951                    == vk::Format::G8_B8R8_2PLANE_420_UNORM
1952                        .as_raw()
1953                        .cast_unsigned() =>
1954            {
1955                NativePlaneLayout::Nv12
1956            }
1957            (rsmpeg::ffi::AV_PIX_FMT_P010LE, format)
1958                if format
1959                    == vk::Format::G10X6_B10X6R10X6_2PLANE_420_UNORM_3PACK16
1960                        .as_raw()
1961                        .cast_unsigned() =>
1962            {
1963                NativePlaneLayout::P010
1964            }
1965            _ => {
1966                return Err(BridgeError::InvalidInput(
1967                    "only sampled single-image NV12 or P010 is importable",
1968                ));
1969            }
1970        };
1971        if layout == NativePlaneLayout::P010
1972            && !self
1973                .gpu
1974                .device()
1975                .features()
1976                .contains(wgpu::Features::TEXTURE_FORMAT_P010)
1977        {
1978            return Err(BridgeError::InvalidInput(
1979                "shared Vulkan device does not expose P010 plane views",
1980            ));
1981        }
1982        if info.plane_count != 1 || !info.sampled || info.width <= 0 || info.height <= 0 {
1983            return Err(BridgeError::InvalidInput(
1984                "only sampled single-image NV12 or P010 is importable",
1985            ));
1986        }
1987        // The image's extent is the padded coded size; importing it as the display size would
1988        // rescale every sample.
1989        if info.coded_width < info.width || info.coded_height < info.height {
1990            return Err(BridgeError::InvalidInput(
1991                "decoded frame is larger than its allocated image",
1992            ));
1993        }
1994        let coded_width = u32::try_from(info.coded_width)
1995            .map_err(|_| BridgeError::InvalidInput("invalid coded width"))?;
1996        let coded_height = u32::try_from(info.coded_height)
1997            .map_err(|_| BridgeError::InvalidInput("invalid coded height"))?;
1998        let access = frame.lock_access()?;
1999        let mut status = 0;
2000        // SAFETY: the guard holds FFmpeg's frame and queue locks while C reads the frame.
2001        let step =
2002            unsafe { alpha2_native_gpu_vulkan_acquire_check(access.access(), &raw mut status) };
2003        if step != 0 {
2004            return Err(helper_error("import check", step, status));
2005        }
2006        let (device, allocator, queue_family) = {
2007            let access = access.access();
2008            (
2009                access.frame().device,
2010                access.allocator(),
2011                access.queue_family(),
2012            )
2013        };
2014        drop(access);
2015        let ticket = self.import_tickets.take(device, allocator, queue_family)?;
2016        let (texture_format, luma_format, chroma_format) = match layout {
2017            NativePlaneLayout::P010 => (
2018                wgpu::TextureFormat::P010,
2019                wgpu::TextureFormat::R16Unorm,
2020                wgpu::TextureFormat::Rg16Unorm,
2021            ),
2022            _ => (
2023                wgpu::TextureFormat::NV12,
2024                wgpu::TextureFormat::R8Unorm,
2025                wgpu::TextureFormat::Rg8Unorm,
2026            ),
2027        };
2028        let hal_descriptor = wgpu_hal::TextureDescriptor {
2029            label: Some("alpha2 FFmpeg decode surface"),
2030            size: wgpu::Extent3d {
2031                width: coded_width,
2032                height: coded_height,
2033                depth_or_array_layers: 1,
2034            },
2035            mip_level_count: 1,
2036            sample_count: 1,
2037            dimension: wgpu::TextureDimension::D2,
2038            format: texture_format,
2039            usage: wgpu::TextureUses::RESOURCE,
2040            memory_flags: wgpu_hal::MemoryFlags::empty(),
2041            view_formats: Vec::new(),
2042        };
2043        // SAFETY: this context is always Vulkan, and the identity check above established the
2044        // same logical device.
2045        let hal_device = unsafe { self.gpu.device().as_hal::<wgpu_hal::api::Vulkan>() }
2046            .ok_or(BridgeError::InvalidInput("renderer is not Vulkan"))?;
2047        let drop_owner = Arc::clone(&frame);
2048        // SAFETY: FFmpeg created the image with the validated descriptor and keeps it alive via
2049        // `drop_owner`; wgpu must not destroy it.
2050        let hal_texture = unsafe {
2051            hal_device.texture_from_raw(
2052                vk::Image::from_raw(info.images[0]),
2053                &hal_descriptor,
2054                Some(Box::new(move || drop(drop_owner))),
2055                wgpu_hal::vulkan::TextureMemory::External,
2056            )
2057        };
2058        let descriptor = wgpu::TextureDescriptor {
2059            label: Some("alpha2 FFmpeg decode surface"),
2060            size: hal_descriptor.size,
2061            mip_level_count: 1,
2062            sample_count: 1,
2063            dimension: wgpu::TextureDimension::D2,
2064            format: texture_format,
2065            usage: wgpu::TextureUsages::TEXTURE_BINDING,
2066            view_formats: &[],
2067        };
2068        // SAFETY: the batched acquire moves the whole image to the shader-read layout before
2069        // its first wgpu submission, and the HAL texture is this device's.
2070        let texture = unsafe {
2071            self.gpu
2072                .device()
2073                .create_texture_from_hal::<wgpu_hal::api::Vulkan>(
2074                    hal_texture,
2075                    &descriptor,
2076                    wgpu::TextureUses::RESOURCE,
2077                )
2078        };
2079        let y = texture.create_view(&wgpu::TextureViewDescriptor {
2080            label: Some("alpha2 FFmpeg decode Y"),
2081            format: Some(luma_format),
2082            aspect: wgpu::TextureAspect::Plane0,
2083            ..Default::default()
2084        });
2085        let uv = texture.create_view(&wgpu::TextureViewDescriptor {
2086            label: Some("alpha2 FFmpeg decode UV"),
2087            format: Some(chroma_format),
2088            aspect: wgpu::TextureAspect::Plane1,
2089            ..Default::default()
2090        });
2091        let pixels = u64::from(coded_width).saturating_mul(u64::from(coded_height));
2092        let lease = Arc::new(VulkanImportLease {
2093            frame,
2094            _texture: texture,
2095            gpu: self.gpu.clone(),
2096            batch: Arc::clone(&self.submission_batch),
2097            tickets: Arc::clone(&self.import_tickets),
2098            ticket: Some(ticket),
2099            staged_signals: Mutex::new(Vec::new()),
2100            queued: AtomicBool::new(false),
2101            acquired: AtomicBool::new(false),
2102            released: AtomicBool::new(false),
2103            retained_bytes: pixels
2104                .saturating_mul(layout.bytes_per_pixel_numerator())
2105                .div_ceil(2),
2106        });
2107        Ok(ImportedVulkanFrame {
2108            y,
2109            uv,
2110            layout,
2111            coded_size: [coded_width, coded_height],
2112            lease,
2113        })
2114    }
2115}
2116
2117/// What one Vulkan adapter offers the shared device (queue families and video extensions), read
2118/// without opening it.
2119#[derive(Clone, Debug, PartialEq, Eq)]
2120struct VideoPlan {
2121    decode_family: u32,
2122    /// The video-encode queue family, when it has every extension `FFmpeg`'s encoder needs.
2123    encode_family: Option<u32>,
2124    video_extensions: Vec<&'static CStr>,
2125    decode_caps: vk::VideoCodecOperationFlagsKHR,
2126    /// The codecs the decode extensions cover (`h264`, `hevc`, `av1`, `vp9`).
2127    decode_codecs: Vec<&'static str>,
2128    /// The codecs the encode extensions cover; empty without an encode queue.
2129    encode_codecs: Vec<&'static str>,
2130}
2131
2132/// Decode extensions the shared device enables where available: extension, the operation
2133/// `FFmpeg` is told the decode queue does, and the codec name.
2134const DECODE_EXTENSIONS: [(&CStr, vk::VideoCodecOperationFlagsKHR, &str); 4] = [
2135    (
2136        ash::khr::video_decode_h264::NAME,
2137        vk::VideoCodecOperationFlagsKHR::DECODE_H264,
2138        "h264",
2139    ),
2140    (
2141        ash::khr::video_decode_h265::NAME,
2142        vk::VideoCodecOperationFlagsKHR::DECODE_H265,
2143        "hevc",
2144    ),
2145    (
2146        ash::khr::video_decode_av1::NAME,
2147        vk::VideoCodecOperationFlagsKHR::DECODE_AV1,
2148        "av1",
2149    ),
2150    (VIDEO_DECODE_VP9_NAME, DECODE_VP9, "vp9"),
2151];
2152
2153#[derive(Clone, Copy, Debug)]
2154struct QueueFamily {
2155    flags: vk::QueueFlags,
2156    count: u32,
2157}
2158
2159/// Whether the shared device can be made on an adapter with `families`, the extensions
2160/// `supports` answers for, and NV12 plane views (`nv12`), and with what queues and extensions.
2161///
2162/// The graphics queue must be family 0 (wgpu-hal's shared-device path) and carry the compute
2163/// and transfer work `FFmpeg` submits to it. Decode needs its own queue family and at least
2164/// H.264. Encode is optional.
2165fn video_plan(
2166    families: &[QueueFamily],
2167    supports: impl Fn(&CStr) -> bool,
2168    nv12: bool,
2169) -> Result<VideoPlan, String> {
2170    if !nv12 {
2171        return Err("Vulkan adapter does not support NV12 plane views".to_owned());
2172    }
2173    let family = |flag: vk::QueueFlags| {
2174        families
2175            .iter()
2176            .position(|family| family.flags.contains(flag) && family.count > 0)
2177            .and_then(|index| u32::try_from(index).ok())
2178    };
2179    let graphics_family =
2180        family(vk::QueueFlags::GRAPHICS).ok_or("Vulkan adapter has no graphics queue")?;
2181    if graphics_family != 0 {
2182        return Err("wgpu-hal shared-device path requires graphics queue family 0".to_owned());
2183    }
2184    if !families[0]
2185        .flags
2186        .contains(vk::QueueFlags::COMPUTE | vk::QueueFlags::TRANSFER)
2187    {
2188        return Err("graphics queue family lacks FFmpeg compute/transfer capabilities".to_owned());
2189    }
2190    let decode_family = family(vk::QueueFlags::VIDEO_DECODE_KHR)
2191        .ok_or("Vulkan adapter has no video-decode queue")?;
2192    if decode_family == graphics_family {
2193        return Err(
2194            "shared Vulkan device requires a decode queue separate from wgpu graphics".to_owned(),
2195        );
2196    }
2197    if decode_family >= crate::interop::ALPHA2_MAX_QUEUE_FAMILIES {
2198        return Err(format!(
2199            "the video-decode queue family {decode_family} is above the FFmpeg queue lock table"
2200        ));
2201    }
2202    let base = [
2203        ash::khr::video_queue::NAME,
2204        ash::khr::video_decode_queue::NAME,
2205    ];
2206    if !base.iter().all(|extension| supports(extension))
2207        || !supports(ash::khr::video_decode_h264::NAME)
2208    {
2209        return Err("Vulkan H.264 video decode is unavailable".to_owned());
2210    }
2211    let mut video_extensions = base.to_vec();
2212    let mut decode_caps = vk::VideoCodecOperationFlagsKHR::empty();
2213    let mut decode_codecs = Vec::new();
2214    for (extension, operation, codec) in DECODE_EXTENSIONS {
2215        if supports(extension) {
2216            video_extensions.push(extension);
2217            decode_caps |= operation;
2218            decode_codecs.push(codec);
2219        }
2220    }
2221    // FFmpeg's Vulkan encoders need the encode queue and `video_maintenance1` (sessions without
2222    // pre-allocated DPB images), neither of which wgpu enables.
2223    let encode_base = [
2224        ash::khr::video_encode_queue::NAME,
2225        ash::khr::video_maintenance1::NAME,
2226    ];
2227    let encoded: Vec<(&'static str, &'static CStr)> = ENCODE_EXTENSIONS
2228        .iter()
2229        .filter(|(_, extension, _)| supports(extension))
2230        .map(|(codec, extension, _)| (*codec, *extension))
2231        .collect();
2232    // An encode family above the lock table could not be serialized with wgpu, so it is not used.
2233    let encode_family = family(vk::QueueFlags::VIDEO_ENCODE_KHR)
2234        .filter(|family| *family < crate::interop::ALPHA2_MAX_QUEUE_FAMILIES)
2235        .filter(|_| encode_base.iter().all(|extension| supports(extension)) && !encoded.is_empty());
2236    let encode_codecs = if encode_family.is_some() {
2237        video_extensions.extend_from_slice(&encode_base);
2238        video_extensions.extend(encoded.iter().map(|(_, extension)| *extension));
2239        encoded.iter().map(|(codec, _)| *codec).collect()
2240    } else {
2241        Vec::new()
2242    };
2243    Ok(VideoPlan {
2244        decode_family,
2245        encode_family,
2246        video_extensions,
2247        decode_caps,
2248        decode_codecs,
2249        encode_codecs,
2250    })
2251}
2252
2253impl VideoPlan {
2254    /// Drops what the device cannot enable: VP9 decode without `videoDecodeVP9`, and encode without
2255    /// `videoMaintenance1`, which `FFmpeg`'s encoders need.
2256    fn restrict_to(&mut self, features: FfmpegDeviceFeatures) {
2257        if !features.video_decode_vp9 {
2258            self.video_extensions
2259                .retain(|extension| *extension != VIDEO_DECODE_VP9_NAME);
2260            self.decode_caps &= !DECODE_VP9;
2261            self.decode_codecs.retain(|codec| *codec != "vp9");
2262        }
2263        if !features.video_maintenance1 && self.encode_family.is_some() {
2264            let encode_extensions: Vec<&CStr> = [
2265                ash::khr::video_encode_queue::NAME,
2266                ash::khr::video_maintenance1::NAME,
2267            ]
2268            .into_iter()
2269            .chain(ENCODE_EXTENSIONS.iter().map(|(_, extension, _)| *extension))
2270            .collect();
2271            self.video_extensions
2272                .retain(|extension| !encode_extensions.contains(extension));
2273            self.encode_family = None;
2274            self.encode_codecs.clear();
2275        }
2276    }
2277}
2278
2279/// [`video_plan`] for `exposed`, read from its instance.
2280fn adapter_video_plan(
2281    instance: &ash::Instance,
2282    exposed: &wgpu_hal::ExposedAdapter<wgpu_hal::api::Vulkan>,
2283) -> Result<VideoPlan, String> {
2284    let physical = exposed.adapter.raw_physical_device();
2285    // SAFETY: `physical` was enumerated from this instance.
2286    let families: Vec<QueueFamily> =
2287        unsafe { instance.get_physical_device_queue_family_properties(physical) }
2288            .iter()
2289            .map(|family| QueueFamily {
2290                flags: family.queue_flags,
2291                count: family.queue_count,
2292            })
2293            .collect();
2294    // SAFETY: `physical` was enumerated from this instance.
2295    let extensions = unsafe { instance.enumerate_device_extension_properties(physical) }
2296        .map_err(|error| format!("Vulkan extensions: {error}"))?;
2297    let supports = |name: &CStr| {
2298        extensions.iter().any(|property| {
2299            property
2300                .extension_name_as_c_str()
2301                .is_ok_and(|candidate| candidate == name)
2302        })
2303    };
2304    video_plan(
2305        &families,
2306        supports,
2307        exposed
2308            .features
2309            .contains(wgpu::Features::TEXTURE_FORMAT_NV12),
2310    )
2311}
2312
2313/// One Vulkan adapter as the shared device's choice sees it, read without opening a device.
2314#[derive(Clone, Debug)]
2315pub struct VulkanCandidate {
2316    /// Position in the Vulkan enumeration, as `ALPHA2_GPU_ADAPTER` and
2317    /// [`SharedVulkanContext::create_on`] use it.
2318    pub index: usize,
2319    /// Position in the loader's physical-device order, which `FFmpeg` takes for its own device.
2320    pub loader_index: Option<usize>,
2321    /// The adapter's name, which a name pin matches.
2322    pub name: String,
2323    /// Its kind, for the high-performance order.
2324    pub device_type: wgpu::DeviceType,
2325    /// Whether the shared device can be made on it, or why not.
2326    pub shares: Result<(), String>,
2327    /// The codecs its decode extensions cover.
2328    pub decode_codecs: Vec<&'static str>,
2329    /// The codecs its encode queue and extensions cover.
2330    pub encode_codecs: Vec<&'static str>,
2331}
2332
2333/// Every Vulkan adapter, in enumeration order, with what it offers the shared device.
2334///
2335/// # Errors
2336/// Returns why there is no Vulkan instance.
2337pub fn vulkan_candidates() -> Result<Vec<VulkanCandidate>, SharedVulkanError> {
2338    let _turn = alpha2_gpu::serialize_acquisition();
2339    let hal_instance = hal_instance()?;
2340    // SAFETY: adapter enumeration does not require a surface.
2341    let adapters = unsafe { hal_instance.enumerate_adapters(None) };
2342    Ok(adapters
2343        .iter()
2344        .enumerate()
2345        .map(|(index, exposed)| {
2346            let instance = exposed.adapter.shared_instance().raw_instance();
2347            let physical = exposed.adapter.raw_physical_device();
2348            // SAFETY: the instance is alive for the call; enumeration has no other precondition.
2349            let loader_index = unsafe { instance.enumerate_physical_devices() }
2350                .ok()
2351                .and_then(|order| order.iter().position(|device| *device == physical));
2352            let plan = adapter_video_plan(instance, exposed);
2353            VulkanCandidate {
2354                index,
2355                loader_index,
2356                name: exposed.info.name.clone(),
2357                device_type: exposed.info.device_type,
2358                decode_codecs: plan
2359                    .as_ref()
2360                    .map(|plan| plan.decode_codecs.clone())
2361                    .unwrap_or_default(),
2362                encode_codecs: plan
2363                    .as_ref()
2364                    .map(|plan| plan.encode_codecs.clone())
2365                    .unwrap_or_default(),
2366                shares: plan.map(|_| ()),
2367            }
2368        })
2369        .collect())
2370}
2371
2372/// The record the adapter choice ranks `candidate` by. GPU decode and encode both need the
2373/// shared device, so an adapter that cannot carry it does neither.
2374fn candidate_record(
2375    candidate: &VulkanCandidate,
2376    decode_allowed: bool,
2377) -> alpha2_gpu::AdapterRecord {
2378    let mut record = alpha2_gpu::AdapterRecord::unasked(
2379        candidate.index,
2380        candidate.name.clone(),
2381        "vulkan",
2382        candidate.device_type == wgpu::DeviceType::Cpu,
2383    );
2384    record.renders = Ok(());
2385    record.decodes = match (&candidate.shares, decode_allowed) {
2386        (Err(reason), _) => Err(reason.clone()),
2387        (Ok(()), false) => Err("decode is in software".to_owned()),
2388        (Ok(()), true) => Ok(()),
2389    };
2390    record.gpu_encodes = alpha2_gpu::GPU_ENCODE_CODECS
2391        .iter()
2392        .map(|&codec| {
2393            let answer = match &candidate.shares {
2394                Err(reason) => Err(reason.clone()),
2395                Ok(()) if candidate.encode_codecs.contains(&codec) => Ok(()),
2396                Ok(()) => Err(format!(
2397                    "{} has no Vulkan video encoder for {codec}",
2398                    candidate.name
2399                )),
2400            };
2401            (codec, answer)
2402        })
2403        .collect();
2404    record
2405}
2406
2407/// The shared device the adapter choice made, its report, and why there is none if so.
2408pub struct SharedVulkanChoice<T = SharedVulkanContext> {
2409    /// The shared device, when one was made.
2410    pub context: Option<T>,
2411    /// Which adapter the policy took and why, with every Vulkan adapter's record.
2412    pub report: alpha2_gpu::AdapterChoiceReport,
2413    /// Why no shared device was made although one was wanted.
2414    pub unavailable: Option<String>,
2415}
2416
2417/// Makes the shared Vulkan device on the adapter `policy` takes, ranked as every host ranks
2418/// adapters ([`alpha2_gpu::rank_adapters`]): under `auto`, the adapter encoding the most codecs
2419/// on the GPU, then one that decodes when `decode_allowed`, then high-performance order.
2420/// Without `wanted` nothing is made and the report says where the product device renders.
2421///
2422/// If making the device fails, the failure goes into that adapter's record and the choice runs
2423/// again: `auto` tries the next capable adapter, while `performance` and a pin keep their
2424/// adapter and render without a shared device.
2425///
2426/// # Errors
2427/// Returns why there is no Vulkan instance to choose on.
2428pub fn choose_shared_vulkan(
2429    policy: &alpha2_gpu::AdapterPolicy,
2430    decode_allowed: bool,
2431    wanted: bool,
2432) -> Result<SharedVulkanChoice, SharedVulkanError> {
2433    let candidates = vulkan_candidates()?;
2434    Ok(choose_over(
2435        candidates,
2436        policy,
2437        decode_allowed,
2438        wanted,
2439        |index| SharedVulkanContext::create_on(index).map_err(|error| error.to_string()),
2440    ))
2441}
2442
2443/// [`choose_shared_vulkan`] over `candidates`, making the device with `create_on`.
2444fn choose_over<T>(
2445    mut candidates: Vec<VulkanCandidate>,
2446    policy: &alpha2_gpu::AdapterPolicy,
2447    decode_allowed: bool,
2448    wanted: bool,
2449    mut create_on: impl FnMut(usize) -> Result<T, String>,
2450) -> SharedVulkanChoice<T> {
2451    // In product request order, so ties render where the product device would.
2452    let kinds: Vec<(usize, wgpu::DeviceType)> = candidates
2453        .iter()
2454        .enumerate()
2455        .map(|(at, candidate)| (at, candidate.device_type))
2456        .collect();
2457    let order = alpha2_gpu::product_order(&kinds);
2458    let mut ordered: Vec<Option<VulkanCandidate>> = candidates.drain(..).map(Some).collect();
2459    let mut candidates: Vec<VulkanCandidate> = order
2460        .into_iter()
2461        .filter_map(|at| ordered[at].take())
2462        .collect();
2463    loop {
2464        let records: Vec<alpha2_gpu::AdapterRecord> = candidates
2465            .iter()
2466            .map(|candidate| candidate_record(candidate, decode_allowed))
2467            .collect();
2468        let ranked = match alpha2_gpu::rank_adapters(&records, policy, decode_allowed) {
2469            Ok(ranked) => ranked,
2470            Err(reason) => {
2471                return SharedVulkanChoice {
2472                    context: None,
2473                    report: alpha2_gpu::AdapterChoiceReport {
2474                        policy: policy.clone(),
2475                        chosen: None,
2476                        reason: alpha2_gpu::ChoiceReason::NoSharedDevice,
2477                        explanation: reason.clone(),
2478                        records,
2479                    },
2480                    unavailable: wanted.then_some(reason),
2481                };
2482            }
2483        };
2484        let mut report = alpha2_gpu::AdapterChoiceReport::ranked(policy.clone(), records, &ranked);
2485        let first = ranked.order[0];
2486        if !wanted {
2487            return SharedVulkanChoice {
2488                context: None,
2489                report,
2490                unavailable: None,
2491            };
2492        }
2493        let candidate = &mut candidates[first];
2494        if let Err(reason) = &candidate.shares {
2495            let unavailable = format!(
2496                "{} cannot share a device with the video decoder and encoder: {reason}",
2497                candidate.name
2498            );
2499            if !policy.is_pin() {
2500                report.reason = alpha2_gpu::ChoiceReason::NoSharedDevice;
2501            }
2502            report.explanation = format!("{}; {unavailable}", report.explanation);
2503            return SharedVulkanChoice {
2504                context: None,
2505                report,
2506                unavailable: Some(unavailable),
2507            };
2508        }
2509        match create_on(candidate.index) {
2510            Ok(context) => {
2511                return SharedVulkanChoice {
2512                    context: Some(context),
2513                    report,
2514                    unavailable: None,
2515                };
2516            }
2517            Err(reason) => candidate.shares = Err(format!("the shared device failed: {reason}")),
2518        }
2519    }
2520}
2521
2522/// Whether `ALPHA2_GPU_ADAPTER` pins one adapter, which probes opening their own devices then
2523/// keep to.
2524#[must_use]
2525pub fn adapter_pinned() -> bool {
2526    alpha2_gpu::AdapterPolicy::from_env().is_pin()
2527}
2528
2529/// The loader physical-device index of the adapter the host's choice makes the shared device
2530/// on: the `device` index `FFmpeg`'s `av_hwdevice_ctx_create` takes. Probes that open their own
2531/// device pass it, so they use the device an export runs on.
2532///
2533/// # Errors
2534/// Returns why no device is chosen: no Vulkan instance, or no adapter the policy takes that
2535/// could carry the shared device.
2536pub fn shared_device_index() -> Result<usize, SharedVulkanError> {
2537    let candidates = vulkan_candidates()?;
2538    let mut chosen = None;
2539    let choice = choose_over(
2540        candidates.clone(),
2541        &alpha2_gpu::AdapterPolicy::from_env(),
2542        true,
2543        true,
2544        |index| {
2545            chosen = Some(index);
2546            Ok(())
2547        },
2548    );
2549    let index = chosen.ok_or_else(|| {
2550        SharedVulkanError(
2551            choice
2552                .unavailable
2553                .unwrap_or_else(|| "no Vulkan adapter could carry the shared device".to_owned()),
2554        )
2555    })?;
2556    candidates
2557        .iter()
2558        .find(|candidate| candidate.index == index)
2559        .and_then(|candidate| candidate.loader_index)
2560        .ok_or_else(|| SharedVulkanError("the chosen adapter is not in the device list".into()))
2561}
2562
2563#[cfg(test)]
2564#[path = "vulkan_failure_tests.rs"]
2565mod failure_tests;
2566
2567#[cfg(test)]
2568#[path = "vulkan_tests.rs"]
2569mod tests;