Vulkan backend

Active contributors: Inner Daemons, teoxoy, Connor Fitzgerald, Andy Leiserson

The Vulkan backend (wgpu-hal/src/vulkan/) is the primary HAL backend. It runs on Linux, Android, and Windows natively, and on macOS via MoltenVK. It uses the ash crate for Vulkan bindings and gpu-allocator for memory allocation.

Directory layout

wgpu-hal/src/vulkan/
├── mod.rs            ~56 KB — Api impl, lifecycles
├── adapter.rs        ~145 KB — Adapter/Instance setup, feature detection, limits, format support
├── command.rs        ~50 KB — CommandEncoder
├── conv.rs           ~41 KB — wgpu-core/wgpu-types ↔ Vulkan enum/flag conversions
├── descriptor.rs     ~12 KB — descriptor set/pool management
├── device.rs         ~110 KB — resource creation
├── drm.rs            ~9 KB — Linux DRM integration for surfaces
├── instance.rs       ~40 KB — Instance creation, surface creation, debug utils
├── sampler.rs        ~7 KB — sampler caching
├── semaphore_list.rs ~7 KB — VkSemaphore lifecycle
└── swapchain/        windowing-system-specific surface impl

The 145 KB adapter.rs is where most of the per-feature decisions live: which Vulkan extensions to enable, how Features and Limits map to VkPhysicalDeviceFeatures, how downlevel capabilities are computed.

Key abstractions

Type	File	Purpose
vulkan::Api	wgpu-hal/src/vulkan/mod.rs	The HAL Api impl marker.
vulkan::Instance, Adapter, Device, Queue	wgpu-hal/src/vulkan/{instance,adapter,device,mod}.rs	Lifecycle types.
vulkan::CommandEncoder	wgpu-hal/src/vulkan/command.rs	Wraps a VkCommandBuffer.
vulkan::Buffer, Texture, BindGroup, ...	wgpu-hal/src/vulkan/mod.rs (and device.rs)	Resource structs holding raw Vulkan handles + allocator metadata.
vulkan::DescriptorAllocator	wgpu-hal/src/vulkan/descriptor.rs	Project-internal descriptor pool allocator (recently rewritten in PR #9161).
vulkan::SemaphoreList	wgpu-hal/src/vulkan/semaphore_list.rs	Tracks the semaphores associated with a Queue::submit.
vulkan::Swapchain	wgpu-hal/src/vulkan/swapchain/	Per-surface swapchain state.

How it works

graph TD
    Core[wgpu-core] -->|encode commands| Enc[vulkan::CommandEncoder]
    Enc -->|vkCmdBeginRenderPass etc.| RawCmd[VkCommandBuffer]
    Core -->|create buffer| Dev[vulkan::Device]
    Dev -->|vkCreateBuffer + vkAllocateMemory| Driver[Vulkan driver]
    Dev --- Allocator[gpu-allocator]
    Allocator --> Driver
    Core -->|queue.submit + present| Queue[vulkan::Queue]
    Queue -->|vkQueueSubmit| Driver
    Queue -->|vkQueuePresentKHR| Swap[Swapchain]

Notable features and recent work

• Custom descriptor allocator — recently merged PR #9161 ([vk] implement our own descriptor allocator) replaces the generic descriptor allocator with one tuned for wgpu's bind-group cadence. See wgpu-hal/src/vulkan/descriptor.rs.
• External fence/semaphore APIs — Queue::add_wait_fence, add_signal_fence, add_wait_semaphore (PRs #9461, #9463) let callers coordinate with non-wgpu Vulkan code (e.g. compositors, video decoders, ML frameworks).
• Drop impl for swapchain and surface — PR #9449 reworked surface lifetime to use Drop, eliminating manual cleanup paths.
• DRM surfaces on Linux — wgpu-hal/src/vulkan/drm.rs handles direct render manager (no compositor) surface creation, used by some Linux-native applications.
• MoltenVK on macOS — works via the vulkan-portability feature on the parent wgpu crate. Adds VK_KHR_portability_enumeration / VK_KHR_portability_subset handling in adapter.rs.

Validation

The Vulkan backend integrates with the LunarG validation layer when InstanceFlags::VALIDATION is set. It also installs a debug-utils messenger that pipes VVL warnings through log::warn!. The shared validation_canary (wgpu-hal/src/validation_canary.rs) is set on validation errors so tests can detect them.

Memory allocation

gpu-allocator (a third-party crate, with hashbrown enabled in Cargo.toml) handles sub-allocation of VkDeviceMemory. wgpu-hal/src/vulkan/device.rs calls into it for every buffer/texture creation. Memory budgets and pressure thresholds map onto MemoryBudgetThresholds and MemoryHints from wgpu-types.

Integration points

• Above: wgpu-core (wgpu-core/src/instance.rs, wgpu-core/src/device/).
• Below: ash (Vulkan bindings), gpu-allocator, windows for Windows surfaces, khronos-egl indirectly.
• Sideways: wgpu-hal/src/auxil/renderdoc.rs for capture support; auxil::dxc_shader_compiler is unrelated to Vulkan but lives in the same auxil/.

Entry points for modification

• A new feature — locate the corresponding Features bit in wgpu-types/src/features.rs. Detect support in vulkan/adapter.rs::PhysicalDeviceFeatures::from_extensions_and_requested_features (or sibling). Wire it into the Adapter::physical_device_features block. Plumb the new pipeline state / descriptor flag through vulkan/device.rs.
• A new command — extend the matching trait method in wgpu-hal/src/lib.rs and implement in vulkan/command.rs. Make sure dynamic/ carries the new method.
• A driver bug workaround — backend-specific quirks tend to live in vulkan/adapter.rs (driver detection by VkPhysicalDeviceProperties::vendorID and driverInfo). Add the workaround in adapter feature detection or in the affected device/command method, behind a clearly named flag.