wgpu_hal/vulkan/

mod.rs

/*!
# Vulkan API internals.

## Stack memory

Ash expects slices, which we don't generally have available.
We cope with this requirement by the combination of the following ways:
  - temporarily allocating `Vec` on heap, where overhead is permitted
  - growing temporary local storage

## Framebuffers and Render passes

Render passes are cached on the device and kept forever.

Framebuffers are also cached on the device, but they are removed when
any of the image views (they have) gets removed.
If Vulkan supports image-less framebuffers,
then the actual views are excluded from the framebuffer key.

## Fences

If timeline semaphores are available, they are used 1:1 with wgpu-hal fences.
Otherwise, we manage a pool of `VkFence` objects behind each `hal::Fence`.

!*/

mod adapter;
mod command;
pub mod conv;
mod descriptor;
mod device;
mod drm;
mod instance;
mod memory;
mod pnext_chain;
mod sampler;
mod semaphore_list;
mod swapchain;

pub use adapter::PhysicalDeviceFeatures;
pub(crate) use pnext_chain::PnextChain;

use alloc::{boxed::Box, ffi::CString, sync::Arc, vec::Vec};
use core::{
    borrow::Borrow,
    ffi::{c_void, CStr},
    fmt,
    marker::PhantomData,
    mem,
    num::NonZeroU32,
};

use arrayvec::ArrayVec;
use ash::{ext, khr, vk};
use bytemuck::{Pod, Zeroable};
use hashbrown::HashSet;
use wgpu_sync::{Mutex, RwLock};

use naga::FastHashMap;
use wgt::InternalCounter;

use semaphore_list::SemaphoreList;

pub use memory::MemoryAllocation;
use memory::{MemoryAllocators, MemoryPool};

use crate::vulkan::semaphore_list::{SemaphoreListMode, SemaphoreType};

const MAX_TOTAL_ATTACHMENTS: usize = crate::MAX_COLOR_ATTACHMENTS * 2 + 1;

#[derive(Clone, Debug)]
pub struct Api;

impl crate::Api for Api {
    const VARIANT: wgt::Backend = wgt::Backend::Vulkan;

    type Instance = Instance;
    type Surface = Surface;
    type Adapter = Adapter;
    type Device = Device;

    type Queue = Queue;
    type CommandEncoder = CommandEncoder;
    type CommandBuffer = CommandBuffer;

    type Buffer = Buffer;
    type Texture = Texture;
    type SurfaceTexture = SurfaceTexture;
    type TextureView = TextureView;
    type Sampler = Sampler;
    type QuerySet = QuerySet;
    type Fence = Fence;
    type AccelerationStructure = AccelerationStructure;
    type PipelineCache = PipelineCache;

    type BindGroupLayout = BindGroupLayout;
    type BindGroup = BindGroup;
    type PipelineLayout = PipelineLayout;
    type ShaderModule = ShaderModule;
    type RenderPipeline = RenderPipeline;
    type ComputePipeline = ComputePipeline;
    type RayTracingPipeline = RayTracingPipeline;
}

crate::impl_dyn_resource!(
    Adapter,
    AccelerationStructure,
    BindGroup,
    BindGroupLayout,
    Buffer,
    CommandBuffer,
    CommandEncoder,
    ComputePipeline,
    Device,
    Fence,
    Instance,
    PipelineCache,
    PipelineLayout,
    QuerySet,
    Queue,
    RenderPipeline,
    RayTracingPipeline,
    Sampler,
    ShaderModule,
    Surface,
    SurfaceTexture,
    Texture,
    TextureView
);

struct DebugUtils {
    extension: ext::debug_utils::Instance,
    messenger: vk::DebugUtilsMessengerEXT,

    /// Owning pointer to the debug messenger callback user data.
    ///
    /// `InstanceShared::drop` destroys the debug messenger before
    /// dropping this, so the callback should never receive a dangling
    /// user data pointer.
    #[allow(dead_code)]
    callback_data: Box<DebugUtilsMessengerUserData>,
}

#[derive(Debug)]
pub struct DebugUtilsCreateInfo {
    severity: vk::DebugUtilsMessageSeverityFlagsEXT,
    message_type: vk::DebugUtilsMessageTypeFlagsEXT,
    callback_data: Box<DebugUtilsMessengerUserData>,
}

#[derive(Debug)]
/// The properties related to the validation layer needed for the
/// DebugUtilsMessenger for their workarounds
struct ValidationLayerProperties {
    /// Validation layer description, from `vk::LayerProperties`.
    layer_description: CString,

    /// Validation layer specification version, from `vk::LayerProperties`.
    layer_spec_version: u32,
}

/// User data needed by `instance::debug_utils_messenger_callback`.
///
/// When we create the [`vk::DebugUtilsMessengerEXT`], the `pUserData`
/// pointer refers to one of these values.
#[derive(Debug)]
pub struct DebugUtilsMessengerUserData {
    /// The properties related to the validation layer, if present
    validation_layer_properties: Option<ValidationLayerProperties>,

    /// If the OBS layer is present. OBS never increments the version of their layer,
    /// so there's no reason to have the version.
    has_obs_layer: bool,
}

pub struct InstanceShared {
    raw: ash::Instance,
    extensions: Vec<&'static CStr>,
    flags: wgt::InstanceFlags,
    memory_budget_thresholds: wgt::MemoryBudgetThresholds,
    debug_utils: Option<DebugUtils>,
    get_physical_device_properties: Option<khr::get_physical_device_properties2::Instance>,
    entry: ash::Entry,
    has_nv_optimus: bool,
    android_sdk_version: u32,
    /// The instance API version.
    ///
    /// Which is the version of Vulkan supported for instance-level functionality.
    ///
    /// It is associated with a `VkInstance` and its children,
    /// except for a `VkPhysicalDevice` and its children.
    instance_api_version: u32,

    // The `drop_guard` field must be the last field of this struct so it is dropped last.
    // Do not add new fields after it.
    drop_guard: Option<crate::DropGuard>,
}

impl fmt::Debug for InstanceShared {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let Self {
            raw: _,
            extensions,
            flags,
            memory_budget_thresholds,
            debug_utils: _,
            get_physical_device_properties: _,
            entry: _,
            has_nv_optimus,
            android_sdk_version,
            instance_api_version,
            drop_guard: _,
        } = self;
        f.debug_struct("InstanceShared")
            .field("extensions", extensions)
            .field("flags", flags)
            .field("memory_budget_thresholds", memory_budget_thresholds)
            .field("has_nv_optimus", has_nv_optimus)
            .field("android_sdk_version", android_sdk_version)
            .field("instance_api_version", instance_api_version)
            .finish_non_exhaustive()
    }
}

#[derive(Debug)]
pub struct Instance {
    shared: Arc<InstanceShared>,
}

#[expect(missing_debug_implementations, reason = "TODO?")]
pub struct Surface {
    swapchain: RwLock<Option<Box<dyn swapchain::Swapchain>>>,
    inner: Box<dyn swapchain::Surface>,
}

impl Surface {
    /// Returns the raw Vulkan surface handle.
    ///
    /// Returns `None` if the surface is a DXGI surface.
    pub unsafe fn raw_native_handle(&self) -> Option<vk::SurfaceKHR> {
        Some(
            self.inner
                .as_any()
                .downcast_ref::<swapchain::NativeSurface>()?
                .as_raw(),
        )
    }

    /// Get the raw Vulkan swapchain associated with this surface.
    ///
    /// Returns [`None`] if the surface is not configured or if the swapchain
    /// is a DXGI swapchain.
    pub fn raw_native_swapchain(&self) -> Option<vk::SwapchainKHR> {
        let read = self.swapchain.read();
        Some(
            read.as_ref()?
                .as_any()
                .downcast_ref::<swapchain::NativeSwapchain>()?
                .as_raw(),
        )
    }

    /// Set the present timing information which will be used for the next [presentation](crate::Queue::present()) of this surface,
    /// using [VK_GOOGLE_display_timing].
    ///
    /// This can be used to give an id to presentations, for future use of [`vk::PastPresentationTimingGOOGLE`].
    /// Note that `wgpu-hal` does *not* provide a way to use that API - you should manually access this through [`ash`].
    ///
    /// This can also be used to add a "not before" timestamp to the presentation.
    ///
    /// The exact semantics of the fields are also documented in the [specification](https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkPresentTimeGOOGLE.html) for the extension.
    ///
    /// # Panics
    ///
    /// - If the surface hasn't been configured.
    /// - If the surface has been configured for a DXGI swapchain.
    /// - If the device doesn't [support present timing](wgt::Features::VULKAN_GOOGLE_DISPLAY_TIMING).
    ///
    /// [VK_GOOGLE_display_timing]: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_GOOGLE_display_timing.html
    #[track_caller]
    pub fn set_next_present_time(&self, present_timing: vk::PresentTimeGOOGLE) {
        let mut swapchain = self.swapchain.write();
        swapchain
            .as_mut()
            .expect("Surface should have been configured")
            .as_any_mut()
            .downcast_mut::<swapchain::NativeSwapchain>()
            .expect("Surface should have a native Vulkan swapchain")
            .set_next_present_time(present_timing);
    }

    /// Set a `pNext` chain of extension structs to be attached to the [`vk::PresentInfoKHR`]
    /// of the next [presentation](crate::Queue::present()) of this surface.
    ///
    /// This supports presentation extensions that `wgpu-hal` has no dedicated support
    /// for, such as [VK_NV_present_metering]. The corresponding device extension must be
    /// enabled at device creation, e.g. with
    /// [`Adapter::open_with_callback()`](super::vulkan::Adapter::open_with_callback).
    ///
    /// The chain is consumed by the next presentation: it replaces any chain set by a
    /// previous call that hasn't been presented yet, and is discarded unread if the
    /// surface is reconfigured first.
    ///
    /// # Safety
    ///
    /// - `chain` must point to a valid `pNext` chain of structs that can extend
    ///   [`vk::PresentInfoKHR`], whose extensions are enabled on the device.
    /// - The chain must stay valid, and must not be read or written, until the next
    ///   presentation of this surface completes or the surface is reconfigured. Fields
    ///   the driver wrote during presentation may be read afterwards.
    ///
    /// # Panics
    ///
    /// - If the surface hasn't been configured.
    /// - If the surface has been configured for a DXGI swapchain.
    ///
    /// [VK_NV_present_metering]: https://registry.khronos.org/vulkan/specs/latest/man/html/VK_NV_present_metering.html
    #[track_caller]
    pub unsafe fn set_next_present_chain(&self, chain: *mut c_void) {
        let mut swapchain = self.swapchain.write();
        let swapchain = swapchain
            .as_mut()
            .expect("Surface should have been configured")
            .as_any_mut()
            .downcast_mut::<swapchain::NativeSwapchain>()
            .expect("Surface should have a native Vulkan swapchain");
        unsafe { swapchain.set_next_present_chain(chain) };
    }

    /// Set a `pNext` chain of extension structs to attach to the
    /// [`vk::SwapchainCreateInfoKHR`] used by the next configuration of this surface.
    ///
    /// This supports swapchain extensions that `wgpu-hal` has no dedicated support
    /// for. One example is `VkSwapchainLatencyCreateInfoNV` from [VK_NV_low_latency2].
    /// The device extension itself must be enabled at device creation, for example
    /// with [`Adapter::open_with_callback()`](super::vulkan::Adapter::open_with_callback).
    ///
    /// The next configuration consumes the chain. A later call replaces a chain that
    /// hasn't been consumed yet. If the surface is dropped first, the chain is
    /// discarded unread. Every configuration creates a new swapchain, so you must set
    /// the chain again before each configuration, including on resize.
    ///
    /// # Safety
    ///
    /// - `chain` must point to a valid `pNext` chain of structs that can extend
    ///   [`vk::SwapchainCreateInfoKHR`]. The extensions in the chain must be enabled
    ///   on the device the surface is configured with.
    /// - The chain must stay valid until the configuration that consumes it returns
    ///   or the surface is dropped. Don't read or write the chain during that time.
    ///   Fields the driver wrote during swapchain creation may be read afterwards.
    ///
    /// # Panics
    ///
    /// - If the surface isn't a native Vulkan surface, such as a DXGI surface.
    ///
    /// [VK_NV_low_latency2]: https://registry.khronos.org/vulkan/specs/latest/man/html/VK_NV_low_latency2.html
    #[track_caller]
    pub unsafe fn set_next_swapchain_create_chain(&self, chain: *mut c_void) {
        let surface = self
            .inner
            .as_any()
            .downcast_ref::<swapchain::NativeSurface>()
            .expect("Surface should be a native Vulkan surface");
        unsafe { surface.set_next_swapchain_create_chain(chain) };
    }
}

#[derive(Debug)]
pub struct SurfaceTexture {
    index: u32,
    texture: Texture,
    metadata: Box<dyn swapchain::SurfaceTextureMetadata>,
}

impl crate::DynSurfaceTexture for SurfaceTexture {}

impl Borrow<Texture> for SurfaceTexture {
    fn borrow(&self) -> &Texture {
        &self.texture
    }
}

impl Borrow<dyn crate::DynTexture> for SurfaceTexture {
    fn borrow(&self) -> &dyn crate::DynTexture {
        &self.texture
    }
}

#[derive(Debug)]
pub struct Adapter {
    raw: vk::PhysicalDevice,
    instance: Arc<InstanceShared>,
    //queue_families: Vec<vk::QueueFamilyProperties>,
    known_memory_flags: vk::MemoryPropertyFlags,
    phd_capabilities: adapter::PhysicalDeviceProperties,
    phd_features: PhysicalDeviceFeatures,
    downlevel_flags: wgt::DownlevelFlags,
    private_caps: PrivateCapabilities,
    workarounds: Workarounds,
}

// TODO there's no reason why this can't be unified--the function pointers should all be the same--it's not clear how to do this with `ash`.
enum ExtensionFn<T> {
    /// The loaded function pointer struct for an extension.
    Extension(T),
    /// The extension was promoted to a core version of Vulkan and the functions on `ash`'s `DeviceV1_x` traits should be used.
    Promoted,
}

struct DeviceExtensionFunctions {
    debug_utils: Option<ext::debug_utils::Device>,
    draw_indirect_count: Option<khr::draw_indirect_count::Device>,
    timeline_semaphore: Option<ExtensionFn<khr::timeline_semaphore::Device>>,
    ray_tracing: Option<RayTracingDeviceExtensionFunctions>,
    ray_tracing_pipelines: Option<khr::ray_tracing_pipeline::Device>,
    mesh_shading: Option<ext::mesh_shader::Device>,
    #[cfg_attr(not(unix), allow(dead_code))]
    external_memory_fd: Option<khr::external_memory_fd::Device>,
}

struct RayTracingDeviceExtensionFunctions {
    acceleration_structure: khr::acceleration_structure::Device,
    buffer_device_address: khr::buffer_device_address::Device,
}

/// Set of internal capabilities, which don't show up in the exposed
/// device geometry, but affect the code paths taken internally.
#[derive(Clone, Debug)]
struct PrivateCapabilities {
    image_view_usage: bool,
    timeline_semaphores: bool,
    texture_d24: bool,
    texture_d24_s8: bool,
    texture_s8: bool,
    /// Ability to present contents to any screen. Only needed to work around broken platform configurations.
    can_present: bool,
    non_coherent_map_mask: wgt::BufferAddress,
    multi_draw_indirect: bool,
    max_draw_indirect_count: u32,

    /// True if this adapter advertises the [`robustBufferAccess`][vrba] feature.
    ///
    /// Note that Vulkan's `robustBufferAccess` is not sufficient to implement
    /// `wgpu_hal`'s guarantee that shaders will not access buffer contents via
    /// a given bindgroup binding outside that binding's [accessible
    /// region][ar]. Enabling `robustBufferAccess` does ensure that
    /// out-of-bounds reads and writes are not undefined behavior (that's good),
    /// but still permits out-of-bounds reads to return data from anywhere
    /// within the buffer, not just the accessible region.
    ///
    /// [ar]: ../struct.BufferBinding.html#accessible-region
    /// [vrba]: https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#features-robustBufferAccess
    robust_buffer_access: bool,

    robust_image_access: bool,

    /// True if this adapter supports the [`VK_EXT_robustness2`] extension's
    /// [`robustBufferAccess2`] feature.
    ///
    /// This is sufficient to implement `wgpu_hal`'s [required bounds-checking][ar] of
    /// shader accesses to buffer contents. If this feature is not available,
    /// this backend must have Naga inject bounds checks in the generated
    /// SPIR-V.
    ///
    /// [`VK_EXT_robustness2`]: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_robustness2.html
    /// [`robustBufferAccess2`]: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkPhysicalDeviceRobustness2FeaturesEXT.html#features-robustBufferAccess2
    /// [ar]: ../struct.BufferBinding.html#accessible-region
    robust_buffer_access2: bool,

    robust_image_access2: bool,
    zero_initialize_workgroup_memory: bool,
    image_format_list: bool,
    maximum_samplers: u32,

    /// True if this adapter supports the [`VK_KHR_shader_integer_dot_product`] extension
    /// (promoted to Vulkan 1.3).
    ///
    /// This is used to generate optimized code for WGSL's `dot4{I, U}8Packed`.
    ///
    /// [`VK_KHR_shader_integer_dot_product`]: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_KHR_shader_integer_dot_product.html
    shader_integer_dot_product: bool,

    /// True if this adapter supports 8-bit integers provided by the
    /// [`VK_KHR_shader_float16_int8`] extension (promoted to Vulkan 1.2).
    ///
    /// Allows shaders to declare the "Int8" capability. Note, however, that this
    /// feature alone allows the use of 8-bit integers "only in the `Private`,
    /// `Workgroup` (for non-Block variables), and `Function` storage classes"
    /// ([see spec]). To use 8-bit integers in the interface storage classes (e.g.,
    /// `StorageBuffer`), you also need to enable the corresponding feature in
    /// `VkPhysicalDevice8BitStorageFeatures` and declare the corresponding SPIR-V
    /// capability (e.g., `StorageBuffer8BitAccess`).
    ///
    /// [`VK_KHR_shader_float16_int8`]: https://registry.khronos.org/vulkan/specs/latest/man/html/VK_KHR_shader_float16_int8.html
    /// [see spec]: https://registry.khronos.org/vulkan/specs/latest/man/html/VkPhysicalDeviceShaderFloat16Int8Features.html#extension-features-shaderInt8
    shader_int8: bool,

    /// This is done to panic before undefined behavior, and is imperfect.
    /// Basically, to allow implementations to emulate mv using instancing, if you
    /// want to draw `n` instances to VR, you must draw `2n` instances, but you
    /// can never draw more than `u32::MAX` instances. Therefore, when drawing
    /// multiview on some vulkan implementations, it might restrict the instance
    /// count, which isn't usually a thing in webgpu. We don't expose this limit
    /// because its strange, i.e. only occurs on certain vulkan implementations
    /// if you are drawing more than 128 million instances. We still want to avoid
    /// undefined behavior in this situation, so we panic if the limit is violated.
    multiview_instance_index_limit: u32,

    /// BufferUsages::ACCELERATION_STRUCTURE_SCRATCH allows usage as a scratch buffer.
    /// Vulkan has no way to specify this as a usage, and it maps to other usages, but
    /// these usages do not have as high of an alignment requirement using the buffer as
    ///  a scratch buffer when building acceleration structures.
    scratch_buffer_alignment: u32,

    /// Indicating that depth/stencil texturing operations with `VK_COMPONENT_SWIZZLE_ONE` have defined behavior.
    depth_stencil_swizzle_one_support: bool,

    /// `get_raytracing_pipeline_group_data` requires both a group count and a data size.
    /// The data size parameter is just this * the group count, so we store this to not
    /// require an unnecessary parameter.
    ray_tracing_pipeline_group_data_size: u32,

    /// Whether `VK_ATTACHMENT_STORE_OP_NONE` is supported. This includes:
    /// - `VK_ATTACHMENT_STORE_OP_NONE` provided by `VK_VERSION_1_3`.
    /// - `VK_ATTACHMENT_STORE_OP_NONE_KHR` provided by `VK_KHR_dynamic_rendering`, or `VK_KHR_load_store_op_none` (promoted to Vulkan 1.4).
    /// - `VK_ATTACHMENT_STORE_OP_NONE_QCOM` provided by `VK_QCOM_render_pass_store_ops`.
    /// - `VK_ATTACHMENT_STORE_OP_NONE_EXT` provided by `VK_EXT_load_store_op_none`.
    store_op_none: bool,
}

bitflags::bitflags!(
    /// Workaround flags.
    #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
    pub struct Workarounds: u32 {
        /// Only generate SPIR-V for one entry point at a time.
        const SEPARATE_ENTRY_POINTS = 0x1;
        /// Qualcomm OOMs when there are zero color attachments but a non-null pointer
        /// to a subpass resolve attachment array. This nulls out that pointer in that case.
        const EMPTY_RESOLVE_ATTACHMENT_LISTS = 0x2;
        /// If the following code returns false, then nvidia will end up filling the wrong range.
        ///
        /// ```skip
        /// fn nvidia_succeeds() -> bool {
        ///   # let (copy_length, start_offset) = (0, 0);
        ///     if copy_length >= 4096 {
        ///         if start_offset % 16 != 0 {
        ///             if copy_length == 4096 {
        ///                 return true;
        ///             }
        ///             if copy_length % 16 == 0 {
        ///                 return false;
        ///             }
        ///         }
        ///     }
        ///     true
        /// }
        /// ```
        ///
        /// As such, we need to make sure all calls to vkCmdFillBuffer are aligned to 16 bytes
        /// if they cover a range of 4096 bytes or more.
        const FORCE_FILL_BUFFER_WITH_SIZE_GREATER_4096_ALIGNED_OFFSET_16 = 0x4;
        /// Arm's proprietary driver (observed on r54p2, Mali-G715 / Pixel 9 Pro,
        /// Android 16) ignores negative viewport heights, so it does not do the
        /// Y-flip that maps WebGPU clip space to Vulkan's.
        ///
        /// We flip Y in the vertex shader and use positive-height viewports instead.
        /// This gives the same framebuffer coordinates, so facing does not change.
        /// SPIR-V passthrough shaders do not get this flip.
        const IGNORED_NEGATIVE_VIEWPORT_HEIGHT = 0x8;
    }
);

#[derive(Clone, Debug, Eq, Hash, PartialEq)]
struct AttachmentKey {
    format: vk::Format,
    layout: vk::ImageLayout,
    ops: crate::AttachmentOps,
}

impl AttachmentKey {
    /// Returns an attachment key for a compatible attachment.
    fn compatible(format: vk::Format, layout: vk::ImageLayout) -> Self {
        Self {
            format,
            layout,
            ops: crate::AttachmentOps::all(),
        }
    }
}

#[derive(Clone, Eq, Hash, PartialEq)]
struct ColorAttachmentKey {
    base: AttachmentKey,
    resolve: Option<AttachmentKey>,
}

#[derive(Clone, Eq, Hash, PartialEq)]
struct DepthStencilAttachmentKey {
    base: AttachmentKey,
    stencil_ops: crate::AttachmentOps,
}

#[derive(Clone, Eq, Default, Hash, PartialEq)]
struct RenderPassKey {
    colors: ArrayVec<Option<ColorAttachmentKey>, { crate::MAX_COLOR_ATTACHMENTS }>,
    depth_stencil: Option<DepthStencilAttachmentKey>,
    sample_count: u32,
    multiview_mask: Option<NonZeroU32>,
    depth_read_only: bool,
    stencil_read_only: bool,
}

struct DeviceShared {
    raw: ash::Device,
    family_index: u32,
    queue_flags: vk::QueueFlags,
    queue_index: u32,
    raw_queue: vk::Queue,
    instance: Arc<InstanceShared>,
    physical_device: vk::PhysicalDevice,
    enabled_extensions: Vec<&'static CStr>,
    extension_fns: DeviceExtensionFunctions,
    vendor_id: u32,
    pipeline_cache_validation_key: [u8; 16],
    timestamp_period: f32,
    private_caps: PrivateCapabilities,
    workarounds: Workarounds,
    features: wgt::Features,
    render_passes: Mutex<FastHashMap<RenderPassKey, vk::RenderPass>>,
    sampler_cache: Mutex<sampler::SamplerCache>,
    memory_allocations_counter: InternalCounter,

    /// Because we have cached framebuffers which are not deleted from until
    /// the device is destroyed, if the implementation of vulkan re-uses handles
    /// we need some way to differentiate between the old handle and the new handle.
    /// This factory allows us to have a dedicated identity value for each texture.
    texture_identity_factory: ResourceIdentityFactory<vk::Image>,
    /// As above, for texture views.
    texture_view_identity_factory: ResourceIdentityFactory<vk::ImageView>,

    empty_descriptor_set_layout: vk::DescriptorSetLayout,

    // The `drop_guard` field must be the last field of this struct so it is dropped last.
    // Do not add new fields after it.
    drop_guard: Option<crate::DropGuard>,
}

impl Drop for DeviceShared {
    fn drop(&mut self) {
        for &raw in self.render_passes.lock().values() {
            unsafe { self.raw.destroy_render_pass(raw, None) };
        }
        unsafe {
            self.raw
                .destroy_descriptor_set_layout(self.empty_descriptor_set_layout, None)
        };
        if self.drop_guard.is_none() {
            unsafe { self.raw.destroy_device(None) };
        }
    }
}

#[expect(
    missing_debug_implementations,
    reason = "needs work to not be disastrously verbose"
)]
pub struct Device {
    mem_allocator: MemoryAllocators,
    desc_allocator: Mutex<descriptor::DescriptorAllocator>,
    valid_ash_memory_types: u32,
    naga_options: naga::back::spv::Options<'static>,
    #[cfg(feature = "renderdoc")]
    render_doc: crate::auxil::renderdoc::RenderDoc,
    counters: Arc<wgt::HalCounters>,
    // Struct members are dropped from first to last, put the Device last to ensure that
    // all resources that depends on it are destroyed before it like the mem_allocator
    shared: Arc<DeviceShared>,
}

impl Drop for Device {
    fn drop(&mut self) {}
}

/// Semaphores for forcing queue submissions to run in order.
///
/// The [`wgpu_hal::Queue`] trait promises that if two calls to [`submit`] are
/// ordered, then the first submission will finish on the GPU before the second
/// submission begins. To get this behavior on Vulkan we need to pass semaphores
/// to [`vkQueueSubmit`] for the commands to wait on before beginning execution,
/// and to signal when their execution is done.
///
/// Normally this can be done with a single semaphore, waited on and then
/// signalled for each submission. At any given time there's exactly one
/// submission that would signal the semaphore, and exactly one waiting on it,
/// as Vulkan requires.
///
/// However, as of Oct 2021, bug [#5508] in the Mesa ANV drivers caused them to
/// hang if we use a single semaphore. The workaround is to alternate between
/// two semaphores. The bug has been fixed in Mesa, but we should probably keep
/// the workaround until, say, Oct 2026.
///
/// [`wgpu_hal::Queue`]: crate::Queue
/// [`submit`]: crate::Queue::submit
/// [`vkQueueSubmit`]: https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#vkQueueSubmit
/// [#5508]: https://gitlab.freedesktop.org/mesa/mesa/-/issues/5508
#[derive(Clone)]
struct RelaySemaphores {
    /// The semaphore the next submission should wait on before beginning
    /// execution on the GPU. This is `None` for the first submission, which
    /// should not wait on anything at all.
    wait: Option<vk::Semaphore>,

    /// The semaphore the next submission should signal when it has finished
    /// execution on the GPU.
    signal: vk::Semaphore,
}

impl RelaySemaphores {
    fn new(device: &DeviceShared) -> Result<Self, crate::DeviceError> {
        Ok(Self {
            wait: None,
            signal: device.new_binary_semaphore("RelaySemaphores: 1")?,
        })
    }

    /// Advances the semaphores, returning the semaphores that should be used for a submission.
    fn advance(&mut self, device: &DeviceShared) -> Result<Self, crate::DeviceError> {
        let old = self.clone();

        // Build the state for the next submission.
        match self.wait {
            None => {
                // The `old` values describe the first submission to this queue.
                // The second submission should wait on `old.signal`, and then
                // signal a new semaphore which we'll create now.
                self.wait = Some(old.signal);
                self.signal = device.new_binary_semaphore("RelaySemaphores: 2")?;
            }
            Some(ref mut wait) => {
                // What this submission signals, the next should wait.
                mem::swap(wait, &mut self.signal);
            }
        };

        Ok(old)
    }

    /// Destroys the semaphores.
    unsafe fn destroy(&self, device: &ash::Device) {
        unsafe {
            if let Some(wait) = self.wait {
                device.destroy_semaphore(wait, None);
            }
            device.destroy_semaphore(self.signal, None);
        }
    }
}

pub struct Queue {
    raw: vk::Queue,
    device: Arc<DeviceShared>,
    family_index: u32,
    relay_semaphores: Mutex<RelaySemaphores>,
    signal_semaphores: Mutex<SemaphoreList>,
    wait_semaphores: Mutex<SemaphoreList>,
    /// A caller-provided `pNext` chain to attach to the [`vk::SubmitInfo`] of the
    /// next call to [`submit()`](crate::Queue::submit).
    ///
    /// Set only through [`Queue::set_next_submit_chain()`].
    next_submit_chain: Mutex<Option<PnextChain>>,
}

impl fmt::Debug for Queue {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let Self {
            raw: _,
            device: _,
            family_index,
            relay_semaphores: _,
            signal_semaphores: _,
            wait_semaphores: _,
            next_submit_chain: _,
        } = self;
        f.debug_struct("Queue")
            .field("family_index", family_index)
            .finish_non_exhaustive()
    }
}

impl Queue {
    pub fn as_raw(&self) -> vk::Queue {
        self.raw
    }
}

impl Drop for Queue {
    fn drop(&mut self) {
        unsafe { self.relay_semaphores.lock().destroy(&self.device.raw) };
    }
}
#[derive(Debug)]
enum BufferMemoryBacking {
    Managed(MemoryAllocation),
    VulkanMemory {
        memory: vk::DeviceMemory,
        offset: u64,
        size: u64,
    },
}
impl BufferMemoryBacking {
    fn memory(&self) -> vk::DeviceMemory {
        match self {
            Self::Managed(m) => unsafe { m.memory() },
            Self::VulkanMemory { memory, .. } => *memory,
        }
    }
    fn offset(&self) -> u64 {
        match self {
            Self::Managed(m) => m.offset(),
            Self::VulkanMemory { offset, .. } => *offset,
        }
    }
    fn size(&self) -> u64 {
        match self {
            Self::Managed(m) => m.size(),
            Self::VulkanMemory { size, .. } => *size,
        }
    }
}
/// Describes who owns a [`Buffer`]'s `vk::Buffer` handle and its backing memory,
/// and therefore what cleanup is required when the buffer is destroyed.
#[derive(Debug)]
enum BufferOwnership {
    /// wgpu-hal owns the `vk::Buffer` and its backing memory. On cleanup the buffer
    /// handle is destroyed and the memory is released.
    Managed(Mutex<BufferMemoryBacking>),
    /// wgpu-hal owns the `vk::Buffer` handle but the backing memory is kept alive
    /// by the caller. On cleanup only the buffer handle is destroyed.
    RawHandle,
    /// Caller owns the `vk::Buffer` and its backing memory. On cleanup the
    /// [`crate::DropGuard`] runs the caller's cleanup callback and wgpu-hal touches
    /// neither the handle nor the memory.
    External(crate::DropGuard),
}

#[derive(Debug)]
pub struct Buffer {
    raw: vk::Buffer,

    // This field must be last, because it may contain a `DropGuard` which needs to be dropped after all other fields.
    ownership: BufferOwnership,
}
impl Buffer {
    /// # Safety
    ///
    /// - `vk_buffer`'s memory must be managed by the caller
    /// - Externally imported buffers can't be mapped by `wgpu`
    pub unsafe fn from_raw(vk_buffer: vk::Buffer) -> Self {
        Self {
            raw: vk_buffer,
            ownership: BufferOwnership::RawHandle,
        }
    }

    /// # Safety
    /// - `vk_buffer` must outlive the returned `Buffer`.
    /// - wgpu-hal will NOT call `vkDestroyBuffer`; the caller remains responsible for the buffer handle's destruction.
    ///   The `drop_callback` runs when the `Buffer` drops and may be used to release caller-side bookkeeping.
    /// - Externally imported buffers can't be mapped by `wgpu`.
    pub unsafe fn from_raw_externally_owned(
        vk_buffer: vk::Buffer,
        drop_callback: crate::DropCallback,
    ) -> Self {
        Self {
            raw: vk_buffer,
            ownership: BufferOwnership::External(crate::DropGuard::new(drop_callback)),
        }
    }

    /// # Safety
    /// - We will use this buffer and the buffer's backing memory range as if we have exclusive ownership over it, until the wgpu resource is dropped and the wgpu-hal object is cleaned up
    /// - Externally imported buffers can't be mapped by `wgpu`
    /// - `offset` and `size` must be valid with the allocation of `memory`
    pub unsafe fn from_raw_managed(
        vk_buffer: vk::Buffer,
        memory: vk::DeviceMemory,
        offset: u64,
        size: u64,
    ) -> Self {
        Self {
            raw: vk_buffer,
            ownership: BufferOwnership::Managed(Mutex::new(BufferMemoryBacking::VulkanMemory {
                memory,
                offset,
                size,
            })),
        }
    }

    /// # Safety
    /// - The buffer handle must not be manually destroyed
    pub unsafe fn raw_handle(&self) -> vk::Buffer {
        self.raw
    }
}

impl crate::DynBuffer for Buffer {}

#[derive(Debug)]
pub struct AccelerationStructure {
    raw: vk::AccelerationStructureKHR,
    buffer: vk::Buffer,
    allocation: MemoryAllocation,
    compacted_size_query: Option<vk::QueryPool>,
}

impl crate::DynAccelerationStructure for AccelerationStructure {}

impl AccelerationStructure {
    /// Returns the raw Vulkan acceleration structure handle.
    ///
    /// This allows recording acceleration structure commands that `wgpu-hal` doesn't
    /// support. If those commands come from a device extension, enable it with
    /// [`Adapter::open_with_callback`].
    ///
    /// For a device address, use
    /// [`crate::Device::get_acceleration_structure_device_address`] instead.
    ///
    /// `wgpu` doesn't observe an external build, and rejects an acceleration structure
    /// that it never built. Call `wgpu::CommandEncoder::mark_acceleration_structures_built`
    /// on the encoder that recorded the build.
    ///
    /// # Safety
    ///
    /// - The acceleration structure handle must not be manually destroyed, or used after
    ///   the acceleration structure is dropped
    /// - External work using the handle must be synchronized against `wgpu`'s own reads
    ///   and writes, such as compaction
    /// - An external build must not write more data than the size the acceleration
    ///   structure was created with
    pub unsafe fn raw_handle(&self) -> vk::AccelerationStructureKHR {
        self.raw
    }
}

#[derive(Debug)]
pub enum TextureMemory {
    // shared memory in GPU allocator (owned by wgpu-hal)
    Allocation(MemoryAllocation),

    // dedicated memory (owned by wgpu-hal)
    Dedicated(vk::DeviceMemory),

    // memory not owned by wgpu
    External,
}

#[derive(Debug)]
pub struct Texture {
    raw: vk::Image,
    memory: TextureMemory,
    format: wgt::TextureFormat,
    copy_size: crate::CopyExtent,
    identity: ResourceIdentity<vk::Image>,

    // The `drop_guard` field must be the last field of this struct so it is dropped last.
    // Do not add new fields after it.
    drop_guard: Option<crate::DropGuard>,
}

impl crate::DynTexture for Texture {}

impl Texture {
    /// # Safety
    ///
    /// - The image handle must not be manually destroyed
    pub unsafe fn raw_handle(&self) -> vk::Image {
        self.raw
    }

    /// # Safety
    ///
    /// - The caller must not free the `vk::DeviceMemory` or
    ///   `gpu_alloc::MemoryBlock` in the returned `TextureMemory`.
    pub unsafe fn memory(&self) -> &TextureMemory {
        &self.memory
    }
}

#[derive(Debug)]
pub struct TextureView {
    raw_texture: vk::Image,
    raw: vk::ImageView,
    _layers: NonZeroU32,
    format: wgt::TextureFormat,
    raw_format: vk::Format,
    base_mip_level: u32,
    dimension: wgt::TextureViewDimension,
    texture_identity: ResourceIdentity<vk::Image>,
    view_identity: ResourceIdentity<vk::ImageView>,
}

impl crate::DynTextureView for TextureView {}

impl TextureView {
    /// # Safety
    ///
    /// - The image view handle must not be manually destroyed
    pub unsafe fn raw_handle(&self) -> vk::ImageView {
        self.raw
    }

    /// Returns the raw texture view, along with its identity.
    fn identified_raw_view(&self) -> IdentifiedTextureView {
        IdentifiedTextureView {
            raw: self.raw,
            identity: self.view_identity,
        }
    }
}

#[derive(Debug)]
pub struct Sampler {
    raw: vk::Sampler,
    create_info: vk::SamplerCreateInfo<'static>,
}

impl crate::DynSampler for Sampler {}

/// Information about a binding within a specific BindGroupLayout / BindGroup.
/// This will be used to construct a [`naga::back::spv::BindingInfo`], where
/// the descriptor set value will be taken from the index of the group.
#[derive(Copy, Clone, Debug)]
struct BindingInfo {
    binding: u32,
    binding_array_size: Option<NonZeroU32>,
}

#[derive(Debug)]
pub struct BindGroupLayout {
    raw: vk::DescriptorSetLayout,
    desc_count: descriptor::DescriptorCounts,
    /// Sorted list of entries.
    entries: Box<[wgt::BindGroupLayoutEntry]>,
    /// Map of original binding index to remapped binding index and optional
    /// array size.
    binding_map: Vec<(u32, BindingInfo)>,
    contains_binding_arrays: bool,
}

impl crate::DynBindGroupLayout for BindGroupLayout {}

#[derive(Debug)]
pub struct PipelineLayout {
    raw: vk::PipelineLayout,
    binding_map: naga::back::spv::BindingMap,
}

impl crate::DynPipelineLayout for PipelineLayout {}

#[derive(Debug)]
pub struct BindGroup {
    set: descriptor::DescriptorSet,
}

impl crate::DynBindGroup for BindGroup {}

/// Miscellaneous allocation recycling pool for `CommandAllocator`.
#[derive(Default)]
struct Temp {
    marker: Vec<u8>,
    buffer_barriers: Vec<vk::BufferMemoryBarrier<'static>>,
    image_barriers: Vec<vk::ImageMemoryBarrier<'static>>,
}

impl Temp {
    fn clear(&mut self) {
        self.marker.clear();
        self.buffer_barriers.clear();
        self.image_barriers.clear();
    }

    fn make_c_str(&mut self, name: &str) -> &CStr {
        self.marker.clear();
        self.marker.extend_from_slice(name.as_bytes());
        self.marker.push(0);
        unsafe { CStr::from_bytes_with_nul_unchecked(&self.marker) }
    }
}

/// Generates unique IDs for each resource of type `T`.
///
/// Because vk handles are not permanently unique, this
/// provides a way to generate unique IDs for each resource.
struct ResourceIdentityFactory<T> {
    #[cfg(not(target_has_atomic = "64"))]
    next_id: Mutex<u64>,
    #[cfg(target_has_atomic = "64")]
    next_id: wgpu_sync::atomic::AtomicU64,
    _phantom: PhantomData<T>,
}

impl<T> ResourceIdentityFactory<T> {
    fn new() -> Self {
        Self {
            #[cfg(not(target_has_atomic = "64"))]
            next_id: Mutex::new(0),
            #[cfg(target_has_atomic = "64")]
            next_id: wgpu_sync::atomic::AtomicU64::new(0),
            _phantom: PhantomData,
        }
    }

    /// Returns a new unique ID for a resource of type `T`.
    fn next(&self) -> ResourceIdentity<T> {
        #[cfg(not(target_has_atomic = "64"))]
        {
            let mut next_id = self.next_id.lock();
            let id = *next_id;
            *next_id += 1;
            ResourceIdentity {
                id,
                _phantom: PhantomData,
            }
        }

        #[cfg(target_has_atomic = "64")]
        ResourceIdentity {
            id: self
                .next_id
                .fetch_add(1, core::sync::atomic::Ordering::Relaxed),
            _phantom: PhantomData,
        }
    }
}

/// A unique identifier for a resource of type `T`.
///
/// This is used as a hashable key for resources, which
/// is permanently unique through the lifetime of the program.
#[derive(Debug, Copy, Clone, Eq, Hash, PartialEq)]
struct ResourceIdentity<T> {
    id: u64,
    _phantom: PhantomData<T>,
}

#[derive(Clone, Eq, Hash, PartialEq)]
struct FramebufferKey {
    raw_pass: vk::RenderPass,
    /// Because this is used as a key in a hash map, we need to include the identity
    /// so that this hashes differently, even if the ImageView handles are the same
    /// between different views.
    attachment_identities: ArrayVec<ResourceIdentity<vk::ImageView>, { MAX_TOTAL_ATTACHMENTS }>,
    /// While this is redundant for calculating the hash, we need access to an array
    /// of all the raw ImageViews when we are creating the actual framebuffer,
    /// so we store this here.
    attachment_views: ArrayVec<vk::ImageView, { MAX_TOTAL_ATTACHMENTS }>,
    extent: wgt::Extent3d,
}

impl FramebufferKey {
    fn push_view(&mut self, view: IdentifiedTextureView) {
        self.attachment_identities.push(view.identity);
        self.attachment_views.push(view.raw);
    }
}

/// A texture view paired with its identity.
#[derive(Copy, Clone)]
struct IdentifiedTextureView {
    raw: vk::ImageView,
    identity: ResourceIdentity<vk::ImageView>,
}

#[derive(Clone, Eq, Hash, PartialEq)]
struct TempTextureViewKey {
    texture: vk::Image,
    /// As this is used in a hashmap, we need to
    /// include the identity so that this hashes differently,
    /// even if the Image handles are the same between different images.
    texture_identity: ResourceIdentity<vk::Image>,
    format: vk::Format,
    mip_level: u32,
    depth_slice: u32,
}

// Any state in this struct that may be dirty after an abandoned encoding must
// be reset for reused encoders in `begin_encoding`.
pub struct CommandEncoder {
    raw: vk::CommandPool,
    device: Arc<DeviceShared>,

    /// The current command buffer, if `self` is in the ["recording"]
    /// state.
    ///
    /// ["recording"]: crate::CommandEncoder
    ///
    /// If non-`null`, the buffer is in the Vulkan "recording" state.
    active: vk::CommandBuffer,

    /// What kind of pass we are currently within: compute or render.
    bind_point: vk::PipelineBindPoint,

    /// Allocation recycling pool for this encoder.
    temp: Temp,

    /// A pool of available command buffers.
    ///
    /// These are all in the Vulkan "initial" state.
    free: Vec<vk::CommandBuffer>,

    /// A pool of discarded command buffers.
    ///
    /// These could be in any Vulkan state except "pending".
    discarded: Vec<vk::CommandBuffer>,

    /// If this is true, the active renderpass enabled a debug span,
    /// and needs to be disabled on renderpass close.
    rpass_debug_marker_active: bool,

    /// If set, the end of the next render/compute pass will write a timestamp at
    /// the given pool & location.
    end_of_pass_timer_query: Option<(vk::QueryPool, u32)>,

    framebuffers: FastHashMap<FramebufferKey, vk::Framebuffer>,
    temp_texture_views: FastHashMap<TempTextureViewKey, IdentifiedTextureView>,

    counters: Arc<wgt::HalCounters>,

    current_pipeline_is_multiview: bool,
}

impl Drop for CommandEncoder {
    fn drop(&mut self) {
        // SAFETY:
        //
        // VUID-vkDestroyCommandPool-commandPool-00041: wgpu_hal requires that a
        // `CommandBuffer` must live until its execution is complete, and that a
        // `CommandBuffer` must not outlive the `CommandEncoder` that built it.
        // Thus, we know that none of our `CommandBuffers` are in the "pending"
        // state.
        //
        // The other VUIDs are pretty obvious.
        unsafe {
            // `vkDestroyCommandPool` also frees any command buffers allocated
            // from that pool, so there's no need to explicitly call
            // `vkFreeCommandBuffers` on `cmd_encoder`'s `free` and `discarded`
            // fields.
            self.device.raw.destroy_command_pool(self.raw, None);
        }

        for (_, fb) in self.framebuffers.drain() {
            unsafe { self.device.raw.destroy_framebuffer(fb, None) };
        }

        for (_, view) in self.temp_texture_views.drain() {
            unsafe { self.device.raw.destroy_image_view(view.raw, None) };
        }

        self.counters.command_encoders.sub(1);
    }
}

impl CommandEncoder {
    /// # Safety
    ///
    /// - The command buffer handle must not be manually destroyed
    pub unsafe fn raw_handle(&self) -> vk::CommandBuffer {
        self.active
    }
}

impl fmt::Debug for CommandEncoder {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("CommandEncoder")
            .field("raw", &self.raw)
            .finish()
    }
}

#[derive(Debug)]
pub struct CommandBuffer {
    raw: vk::CommandBuffer,
}

impl crate::DynCommandBuffer for CommandBuffer {}

#[derive(Debug)]
pub enum ShaderModule {
    Raw(vk::ShaderModule),
    Intermediate {
        naga_shader: crate::NagaShader,
        runtime_checks: wgt::ShaderRuntimeChecks,
    },
}

impl crate::DynShaderModule for ShaderModule {}

#[derive(Debug)]
pub struct RenderPipeline {
    raw: vk::Pipeline,
    is_multiview: bool,
}

impl crate::DynRenderPipeline for RenderPipeline {}

#[derive(Debug)]
pub struct ComputePipeline {
    raw: vk::Pipeline,
}

impl crate::DynComputePipeline for ComputePipeline {}

#[derive(Debug)]
pub struct RayTracingPipeline {
    raw: vk::Pipeline,
}

impl crate::DynRayTracingPipeline for RayTracingPipeline {}

#[derive(Debug)]
pub struct PipelineCache {
    raw: vk::PipelineCache,
}

impl crate::DynPipelineCache for PipelineCache {}

#[derive(Debug)]
pub struct QuerySet {
    raw: vk::QueryPool,
}

impl crate::DynQuerySet for QuerySet {}

/// The [`Api::Fence`] type for [`vulkan::Api`].
///
/// This is an `enum` because there are two possible implementations of
/// `wgpu-hal` fences on Vulkan: Vulkan fences, which work on any version of
/// Vulkan, and Vulkan timeline semaphores, which are easier and cheaper but
/// require non-1.0 features.
///
/// [`Device::create_fence`] returns a [`TimelineSemaphore`] if
/// [`VK_KHR_timeline_semaphore`] is available and enabled, and a [`FencePool`]
/// otherwise.
///
/// [`Api::Fence`]: crate::Api::Fence
/// [`vulkan::Api`]: Api
/// [`Device::create_fence`]: crate::Device::create_fence
/// [`TimelineSemaphore`]: Fence::TimelineSemaphore
/// [`VK_KHR_timeline_semaphore`]: https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#VK_KHR_timeline_semaphore
/// [`FencePool`]: Fence::FencePool
#[derive(Debug)]
pub enum Fence {
    /// A Vulkan [timeline semaphore].
    ///
    /// These are simpler to use than Vulkan fences, since timeline semaphores
    /// work exactly the way [`wpgu_hal::Api::Fence`] is specified to work.
    ///
    /// [timeline semaphore]: https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#synchronization-semaphores
    /// [`wpgu_hal::Api::Fence`]: crate::Api::Fence
    TimelineSemaphore(vk::Semaphore),

    /// A collection of Vulkan [fence]s, each associated with a [`FenceValue`].
    ///
    /// The effective [`FenceValue`] of this variant is the greater of
    /// `last_completed` and the maximum value associated with a signalled fence
    /// in `active`.
    ///
    /// Fences are available in all versions of Vulkan, but since they only have
    /// two states, "signaled" and "unsignaled", we need to use a separate fence
    /// for each queue submission we might want to wait for, and remember which
    /// [`FenceValue`] each one represents.
    ///
    /// One should keep the fence pool read while there are any references to the
    /// fences inside of them. This ensures there are no race conditions when
    /// resetting the fences
    ///
    /// [fence]: https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#synchronization-fences
    /// [`FenceValue`]: crate::FenceValue
    FencePool(RwLock<FencePool>),
}

/// A shared fence type. The arc is expect to have a ref-count of one once a function has finished being called
///
/// A fence should have access synchronised as fence resetting might happen at any point. Resetting checks the ref-count
/// of the fence, so instead of copying the fence, it should have its `Arc` container cloned which shows not to reset
/// this fence as it is being used.
pub(super) type SynchronizedFence = Arc<vk::Fence>;

#[derive(Debug)]
pub struct FencePool {
    last_completed: crate::FenceValue,
    /// The pending fence values have to be ascending.
    active: Vec<(crate::FenceValue, SynchronizedFence)>,
    // Don't need extra synchronisation around the fences here, if they are used they should be put into active.
    free: Vec<vk::Fence>,
}

impl crate::DynFence for Fence {}

impl Fence {
    /// Return the highest [`FenceValue`] among the signalled fences in `active`.
    ///
    /// As an optimization, assume that we already know that the fence has
    /// reached `last_completed`, and don't bother checking fences whose values
    /// are less than that: those fences remain in the `active` array only
    /// because we haven't called `maintain` yet to clean them up.
    ///
    /// [`FenceValue`]: crate::FenceValue
    fn check_active(
        device: &ash::Device,
        mut last_completed: crate::FenceValue,
        active: &[(crate::FenceValue, SynchronizedFence)],
    ) -> Result<crate::FenceValue, crate::DeviceError> {
        for &(value, ref raw) in active.iter() {
            unsafe {
                if value > last_completed
                    && device
                        // Don't need to clone as active should be from a read or
                        // write lock which means this is already synchronised.
                        .get_fence_status(**raw)
                        .map_err(map_host_device_oom_and_lost_err)?
                {
                    last_completed = value;
                }
            }
        }
        Ok(last_completed)
    }

    /// Return the highest signalled [`FenceValue`] for `self`.
    ///
    /// [`FenceValue`]: crate::FenceValue
    fn get_latest(
        &self,
        device: &ash::Device,
        extension: Option<&ExtensionFn<khr::timeline_semaphore::Device>>,
    ) -> Result<crate::FenceValue, crate::DeviceError> {
        match *self {
            Self::TimelineSemaphore(raw) => unsafe {
                Ok(match *extension.unwrap() {
                    ExtensionFn::Extension(ref ext) => ext
                        .get_semaphore_counter_value(raw)
                        .map_err(map_host_device_oom_and_lost_err)?,
                    ExtensionFn::Promoted => device
                        .get_semaphore_counter_value(raw)
                        .map_err(map_host_device_oom_and_lost_err)?,
                })
            },
            Self::FencePool(ref pool) => {
                let FencePool {
                    last_completed,
                    ref active,
                    free: _,
                } = *pool.read();
                Self::check_active(device, last_completed, active)
            }
        }
    }

    /// Trim the internal state of this [`Fence`].
    ///
    /// This function has no externally visible effect, but you should call it
    /// periodically to keep this fence's resource consumption under control.
    ///
    /// For fences using the [`FencePool`] implementation, this function
    /// recycles fences that have been signaled. If you don't call this,
    /// [`Queue::submit`] will just keep allocating a new Vulkan fence every
    /// time it's called.
    ///
    /// [`FencePool`]: Fence::FencePool
    /// [`Queue::submit`]: crate::Queue::submit
    fn maintain(&self, device: &ash::Device) -> Result<(), crate::DeviceError> {
        match *self {
            Self::TimelineSemaphore(_) => {}
            Self::FencePool(ref pool) => {
                let FencePool {
                    ref mut last_completed,
                    ref mut active,
                    ref mut free,
                } = *pool.write();

                let base_free = free.len();
                let latest = Self::check_active(device, *last_completed, active)?;

                active.retain_mut(|&mut (value, ref mut fence)| {
                    if value > latest {
                        true
                    } else if let Some(fence) = Arc::get_mut(fence) {
                        // No other references to these, so we have exclusive access. Add them to free and reset them later,
                        // but drop them from active immediately
                        free.push(*fence);
                        false
                    } else {
                        // some other function is using it. Although this shouldn't be to long,
                        // maintain shouldn't block, and it should be cleared up by the next time it happens
                        true
                    }
                });

                if free.len() != base_free {
                    unsafe { device.reset_fences(&free[base_free..]) }
                        .map_err(map_device_oom_err)?
                }
                *last_completed = latest;
            }
        }
        Ok(())
    }
}

impl crate::Queue for Queue {
    type A = Api;

    unsafe fn submit(
        &self,
        command_buffers: &[&CommandBuffer],
        surface_textures: &[&SurfaceTexture],
        (signal_fence, signal_value): (&Fence, crate::FenceValue),
    ) -> Result<(), crate::DeviceError> {
        let mut fence_raw = vk::Fence::null();

        let mut wait_semaphores = SemaphoreList::new(SemaphoreListMode::Wait);
        let mut signal_semaphores = SemaphoreList::new(SemaphoreListMode::Signal);

        // Assert that we will not deadlock as we try to lock each `SurfaceTexture`'s
        // metadata.
        //
        // The documentation for [`wgpu_hal::Queue::submit`] requires that
        // `surface_textures` must not contain duplicates, so simply iterating over
        // the slice and locking each one should be fine.
        debug_assert!(
            {
                let mut check = HashSet::with_capacity(surface_textures.len());
                // We compare the Box by pointer, as Eq isn't well defined for SurfaceSemaphores.
                for st in surface_textures {
                    let ptr: *const () = <*const _>::cast(&*st.metadata);
                    check.insert(ptr as usize);
                }
                check.len() == surface_textures.len()
            },
            "More than one surface texture is being used from the same swapchain. This will cause a deadlock in release."
        );

        let locked_swapchain_semaphores = surface_textures
            .iter()
            .map(|st| st.metadata.get_semaphore_guard())
            .collect::<Vec<_>>();

        for mut semaphores in locked_swapchain_semaphores {
            semaphores.set_used_fence_value(signal_value);

            // If we're the first submission to operate on this image, wait on
            // its acquire semaphore, to make sure the presentation engine is
            // done with it.
            if let Some(sem) = semaphores.get_acquire_wait_semaphore() {
                wait_semaphores.push_wait(sem, vk::PipelineStageFlags::TOP_OF_PIPE);
            }

            // Get a semaphore to signal when we're done writing to this surface
            // image. Presentation of this image will wait for this.
            let signal_semaphore = semaphores.get_submit_signal_semaphore(&self.device)?;
            signal_semaphores.push_signal(signal_semaphore);
        }

        let mut guard = self.signal_semaphores.lock();
        if !guard.is_empty() {
            signal_semaphores.append(&mut guard);
        }

        let mut wait_guard = self.wait_semaphores.lock();
        if !wait_guard.is_empty() {
            wait_semaphores.append(&mut wait_guard);
        }

        // In order for submissions to be strictly ordered, we encode a dependency between each submission
        // using a pair of semaphores. This adds a wait if it is needed, and signals the next semaphore.
        let semaphore_state = self.relay_semaphores.lock().advance(&self.device)?;

        if let Some(sem) = semaphore_state.wait {
            wait_semaphores.push_wait(
                SemaphoreType::Binary(sem),
                vk::PipelineStageFlags::TOP_OF_PIPE,
            );
        }

        signal_semaphores.push_signal(SemaphoreType::Binary(semaphore_state.signal));

        // We need to signal our wgpu::Fence if we have one, this adds it to the signal list.
        signal_fence.maintain(&self.device.raw)?;
        // Keeping the Arc around is probably unneeded - the fence should never be signaled as it was reset,
        // and newer submits should not happen until this submit is done. Therefore, it should be too high
        // to be reset.
        let shared_fence;
        match *signal_fence {
            Fence::TimelineSemaphore(raw) => {
                signal_semaphores.push_signal(SemaphoreType::Timeline(raw, signal_value));
            }
            Fence::FencePool(ref pool) => {
                let FencePool {
                    ref mut active,
                    ref mut free,
                    ..
                } = *pool.write();
                shared_fence = match free.pop() {
                    Some(raw) => Arc::new(raw),
                    None => unsafe {
                        let fence = self
                            .device
                            .raw
                            .create_fence(&vk::FenceCreateInfo::default(), None)
                            .map_err(map_host_device_oom_err)?;
                        Arc::new(fence)
                    },
                };
                fence_raw = *shared_fence;
                active.push((signal_value, shared_fence.clone()));
            }
        }

        let vk_cmd_buffers = command_buffers
            .iter()
            .map(|cmd| cmd.raw)
            .collect::<Vec<_>>();

        let mut vk_info = vk::SubmitInfo::default().command_buffers(&vk_cmd_buffers);
        let mut vk_timeline_info = mem::MaybeUninit::uninit();
        vk_info = SemaphoreList::add_to_submit(
            &mut wait_semaphores,
            &mut signal_semaphores,
            vk_info,
            &mut vk_timeline_info,
        );

        let submit_chain = self.next_submit_chain.lock().take();
        if let Some(chain) = submit_chain {
            // SAFETY: The contract on `Queue::set_next_submit_chain()` keeps the chain
            // valid and unaliased until this submission is made.
            vk_info.p_next = unsafe { chain.splice_into(vk_info.p_next) };
        }

        profiling::scope!("vkQueueSubmit");
        unsafe {
            self.device
                .raw
                .queue_submit(self.raw, &[vk_info], fence_raw)
                .map_err(map_host_device_oom_and_lost_err)?
        };
        Ok(())
    }

    unsafe fn present(
        &self,
        surface: &Surface,
        texture: SurfaceTexture,
    ) -> Result<(), crate::SurfaceError> {
        let mut swapchain = surface.swapchain.write();

        unsafe { swapchain.as_mut().unwrap().present(self, texture) }
    }

    unsafe fn get_timestamp_period(&self) -> f32 {
        self.device.timestamp_period
    }

    unsafe fn wait_for_idle(&self) -> Result<(), crate::DeviceError> {
        unsafe { self.device.raw.queue_wait_idle(self.raw) }
            .map_err(map_host_device_oom_and_lost_err)
    }
}

impl Queue {
    pub fn raw_device(&self) -> &ash::Device {
        &self.device.raw
    }

    pub fn add_signal_semaphore(&self, semaphore: vk::Semaphore, semaphore_value: Option<u64>) {
        let mut guard = self.signal_semaphores.lock();
        if let Some(value) = semaphore_value {
            guard.push_signal(SemaphoreType::Timeline(semaphore, value));
        } else {
            guard.push_signal(SemaphoreType::Binary(semaphore));
        }
    }

    /// Remove `semaphore` from the pending signal list if it is still present.
    ///
    /// Returns `true` if the semaphore was found and removed. If the submit
    /// already consumed it, this is a harmless no-op that returns `false`.
    pub fn remove_signal_semaphore(&self, semaphore: vk::Semaphore) -> bool {
        self.signal_semaphores.lock().remove(semaphore)
    }

    /// Stage a semaphore wait on the next [`crate::Queue::submit`] call.
    ///
    /// `semaphore_value` selects the kind of payload the wait targets:
    ///
    /// - `Some(value)` - wait until `semaphore` (a timeline semaphore) has been signalled to at least `value`.
    /// - `None` - wait on a binary semaphore signal.
    ///
    /// `stage` is the pipeline stage at which the wait blocks downstream
    /// work (e.g. `vk::PipelineStageFlags::TOP_OF_PIPE` to gate the
    /// entire submission, or a more specific stage when only that stage
    /// reads the synchronised resource).
    pub fn add_wait_semaphore(
        &self,
        semaphore: vk::Semaphore,
        semaphore_value: Option<u64>,
        stage: vk::PipelineStageFlags,
    ) {
        let mut guard = self.wait_semaphores.lock();
        if let Some(value) = semaphore_value {
            guard.push_wait(SemaphoreType::Timeline(semaphore, value), stage);
        } else {
            guard.push_wait(SemaphoreType::Binary(semaphore), stage);
        }
    }

    /// Remove `semaphore` from the pending wait list if it is still present.
    ///
    /// Returns `true` if the semaphore was found and removed. If the submit
    /// already consumed it, this is a no-op that returns `false`.
    pub fn remove_wait_semaphore(&self, semaphore: vk::Semaphore) -> bool {
        self.wait_semaphores.lock().remove(semaphore)
    }

    /// Set a `pNext` chain of extension structs to attach to the [`vk::SubmitInfo`]
    /// of the next [`submit()`](crate::Queue::submit) on this queue.
    ///
    /// This supports submission extensions that `wgpu-hal` has no dedicated support
    /// for. One example is `VkLatencySubmissionPresentIdNV` from `VK_NV_low_latency2`.
    /// The device extension itself must be enabled at device creation, for example
    /// with [`Adapter::open_with_callback()`](super::vulkan::Adapter::open_with_callback).
    ///
    /// The next submission on this queue consumes the chain, and a later call
    /// replaces a chain that hasn't been submitted yet. One `wgpu` or `wgpu-core`
    /// submit maps to one submission here, but layers above `wgpu-hal` also make
    /// housekeeping submissions of their own, for example when a buffer is mapped,
    /// and those consume the chain too. Set the chain right before the submission
    /// it applies to, with no other queue or buffer-mapping work in between.
    ///
    /// # Safety
    ///
    /// - `chain` must point to a valid `pNext` chain of structs that can extend
    ///   [`vk::SubmitInfo`]. The extensions in the chain must be enabled on this
    ///   queue's device.
    /// - The chain must stay valid until the next submission on this queue is made
    ///   or the queue is dropped. Don't read or write the chain during that time.
    ///   Fields the driver wrote during submission may be read afterwards.
    pub unsafe fn set_next_submit_chain(&self, chain: *mut c_void) {
        *self.next_submit_chain.lock() = Some(PnextChain::new(chain));
    }
}

/// Maps
///
/// - VK_ERROR_OUT_OF_HOST_MEMORY
/// - VK_ERROR_OUT_OF_DEVICE_MEMORY
fn map_host_device_oom_err(err: vk::Result) -> crate::DeviceError {
    match err {
        vk::Result::ERROR_OUT_OF_HOST_MEMORY | vk::Result::ERROR_OUT_OF_DEVICE_MEMORY => {
            get_oom_err(err)
        }
        e => get_unexpected_err(e),
    }
}

/// Maps
///
/// - VK_ERROR_OUT_OF_HOST_MEMORY
/// - VK_ERROR_OUT_OF_DEVICE_MEMORY
/// - VK_ERROR_DEVICE_LOST
fn map_host_device_oom_and_lost_err(err: vk::Result) -> crate::DeviceError {
    match err {
        vk::Result::ERROR_DEVICE_LOST => get_lost_err(),
        other => map_host_device_oom_err(other),
    }
}

/// Maps
///
/// - VK_ERROR_OUT_OF_HOST_MEMORY
/// - VK_ERROR_OUT_OF_DEVICE_MEMORY
/// - VK_ERROR_FRAGMENTATION
fn map_host_device_oom_and_fragmentation_err(err: vk::Result) -> crate::DeviceError {
    match err {
        vk::Result::ERROR_FRAGMENTATION => get_oom_err(err),
        other => map_host_device_oom_err(other),
    }
}

/// Maps
///
/// - VK_ERROR_OUT_OF_HOST_MEMORY
/// - VK_ERROR_OUT_OF_DEVICE_MEMORY
/// - VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR
fn map_host_device_oom_and_ioca_err(err: vk::Result) -> crate::DeviceError {
    // We don't use VK_KHR_buffer_device_address
    // VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR
    map_host_device_oom_err(err)
}

/// Maps
///
/// - VK_ERROR_OUT_OF_HOST_MEMORY
fn map_host_oom_err(err: vk::Result) -> crate::DeviceError {
    match err {
        vk::Result::ERROR_OUT_OF_HOST_MEMORY => get_oom_err(err),
        e => get_unexpected_err(e),
    }
}

/// Maps
///
/// - VK_ERROR_OUT_OF_DEVICE_MEMORY
fn map_device_oom_err(err: vk::Result) -> crate::DeviceError {
    match err {
        vk::Result::ERROR_OUT_OF_DEVICE_MEMORY => get_oom_err(err),
        e => get_unexpected_err(e),
    }
}

/// Maps
///
/// - VK_ERROR_OUT_OF_HOST_MEMORY
/// - VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR
fn map_host_oom_and_ioca_err(err: vk::Result) -> crate::DeviceError {
    // We don't use VK_KHR_buffer_device_address
    // VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR
    map_host_oom_err(err)
}

/// Maps
///
/// - VK_ERROR_OUT_OF_HOST_MEMORY
/// - VK_ERROR_OUT_OF_DEVICE_MEMORY
/// - VK_PIPELINE_COMPILE_REQUIRED_EXT
/// - VK_ERROR_INVALID_SHADER_NV
fn map_pipeline_err(err: vk::Result) -> crate::DeviceError {
    // We don't use VK_EXT_pipeline_creation_cache_control
    // VK_PIPELINE_COMPILE_REQUIRED_EXT
    // We don't use VK_NV_glsl_shader
    // VK_ERROR_INVALID_SHADER_NV
    map_host_device_oom_err(err)
}

/// Returns [`crate::DeviceError::Unexpected`] or panics if the `internal_error_panic`
/// feature flag is enabled.
fn get_unexpected_err(_err: vk::Result) -> crate::DeviceError {
    #[cfg(feature = "internal_error_panic")]
    panic!("Unexpected Vulkan error: {_err:?}");

    #[allow(unreachable_code)]
    crate::DeviceError::Unexpected
}

/// Returns [`crate::DeviceError::OutOfMemory`].
fn get_oom_err(_err: vk::Result) -> crate::DeviceError {
    crate::DeviceError::OutOfMemory
}

/// Returns [`crate::DeviceError::Lost`] or panics if the `device_lost_panic`
/// feature flag is enabled.
fn get_lost_err() -> crate::DeviceError {
    #[cfg(feature = "device_lost_panic")]
    panic!("Device lost");

    #[allow(unreachable_code)]
    crate::DeviceError::Lost
}

#[derive(Clone, Copy, Pod, Zeroable)]
#[repr(C)]
struct RawTlasInstance {
    transform: [f32; 12],
    custom_data_and_mask: u32,
    shader_binding_table_record_offset_and_flags: u32,
    acceleration_structure_reference: u64,
}

/// Arguments to the [`CreateDeviceCallback`].
#[derive(Debug)]
pub struct CreateDeviceCallbackArgs<'arg, 'pnext, 'this>
where
    'this: 'pnext,
{
    /// The extensions to enable for the device. You must not remove anything from this list,
    /// but you may add to it.
    pub extensions: &'arg mut Vec<&'static CStr>,
    /// The physical device features to enable. You may enable features, but must not disable any.
    pub device_features: &'arg mut PhysicalDeviceFeatures,
    /// The queue create infos for the device. You may substitute a different queue, but:
    /// 1. Any queue you provide must be compatible with `wgpu`'s usage,
    /// 2. You must not leave the vector empty,
    /// 3. `wgpu` currently only uses the first entry.
    pub queue_create_infos: &'arg mut Vec<vk::DeviceQueueCreateInfo<'pnext>>,
    /// The create info for the device. You may add or modify things in the pnext chain, but
    /// do not turn features off. Additionally, do not add things to the list of extensions,
    /// or to the feature set, as all changes to that member will be overwritten.
    pub create_info: &'arg mut vk::DeviceCreateInfo<'pnext>,
    /// We need to have `'this` in the struct, so we can declare that all lifetimes coming from
    /// captures in the closure will live longer (and hence satisfy) `'pnext`. However, we
    /// don't actually directly use `'this`
    _phantom: PhantomData<&'this ()>,
}

/// Callback to allow changing the vulkan device creation parameters.
///
/// # Safety:
/// - If you want to add extensions, add the to the `Vec<'static CStr>` not the create info,
///   as the create info value will be overwritten.
/// - Callback must not remove features.
/// - Callback must not change anything to what the instance does not support.
pub type CreateDeviceCallback<'this> =
    dyn for<'arg, 'pnext> FnOnce(CreateDeviceCallbackArgs<'arg, 'pnext, 'this>) + 'this;

/// Arguments to the [`CreateInstanceCallback`].
#[expect(missing_debug_implementations, reason = "TODO?")]
pub struct CreateInstanceCallbackArgs<'arg, 'pnext, 'this>
where
    'this: 'pnext,
{
    /// The extensions to enable for the instance. You must not remove anything from this list,
    /// but you may add to it.
    pub extensions: &'arg mut Vec<&'static CStr>,
    /// The create info for the instance. You may add or modify things in the pnext chain, but
    /// do not turn features off. Additionally, do not add things to the list of extensions,
    /// all changes to that member will be overwritten.
    pub create_info: &'arg mut vk::InstanceCreateInfo<'pnext>,
    /// Vulkan entry point.
    pub entry: &'arg ash::Entry,
    /// We need to have `'this` in the struct, so we can declare that all lifetimes coming from
    /// captures in the closure will live longer (and hence satisfy) `'pnext`. However, we
    /// don't actually directly use `'this`
    _phantom: PhantomData<&'this ()>,
}

/// Callback to allow changing the vulkan instance creation parameters.
///
/// # Safety:
/// - If you want to add extensions, add the to the `Vec<'static CStr>` not the create info,
///   as the create info value will be overwritten.
/// - Callback must not remove features.
/// - Callback must not change anything to what the instance does not support.
pub type CreateInstanceCallback<'this> =
    dyn for<'arg, 'pnext> FnOnce(CreateInstanceCallbackArgs<'arg, 'pnext, 'this>) + 'this;