DX12 backend

Active contributors: Inner Daemons, teoxoy, Connor Fitzgerald

The DX12 backend (wgpu-hal/src/dx12/) targets Direct3D 12 on Windows. It uses Microsoft's windows crate (0.62) for the COM bindings and several supporting crates: gpu-allocator for memory, mach-dxcompiler-rs for static DXC, and the range-alloc crate for descriptor heap suballocation.

Directory layout

wgpu-hal/src/dx12/
├── mod.rs                ~61 KB — Api impl, lifecycles
├── adapter.rs            ~64 KB — DXGI adapter enumeration, feature detection
├── command.rs            ~72 KB — CommandEncoder
├── conv.rs               ~19 KB — type conversions
├── dcomp.rs              DComp/DirectComposition presentation
├── descriptor.rs         ~10 KB — descriptor heap allocation
├── device.rs             ~110 KB — resource creation
├── device_creation.rs    ~7 KB — D3D12 device + queue selection
├── instance.rs           ~8 KB — DXGI factory creation
├── pipeline_desc.rs      ~15 KB — pipeline state desc translation
├── sampler.rs            ~10 KB
├── shader_compilation.rs ~14 KB — DXC/FXC dispatch
├── suballocation.rs      ~21 KB — buffer/texture suballocation
├── view.rs               ~15 KB — descriptor views
└── types.rs              small shared aliases

The 110 KB device.rs is the largest file; adapter.rs and command.rs follow.

Key abstractions

Type	File	Purpose
dx12::Api	wgpu-hal/src/dx12/mod.rs	HAL Api impl.
dx12::Instance, Adapter, Device, Queue	wgpu-hal/src/dx12/{instance,adapter,device,mod}.rs	Lifecycle.
dx12::CommandEncoder	wgpu-hal/src/dx12/command.rs	Wraps ID3D12GraphicsCommandList.
dx12::DescriptorAllocator	wgpu-hal/src/dx12/descriptor.rs	Per-heap descriptor handle suballocator (uses range-alloc).
dx12::SubAllocation	wgpu-hal/src/dx12/suballocation.rs	Buffer/texture allocator (wraps gpu-allocator).
dx12::ShaderCompiler	wgpu-hal/src/dx12/shader_compilation.rs	DXC vs static-DXC vs FXC dispatch.

Shader compilation

D3D12 needs DXIL (DXC output) or DXBC (FXC output). wgpu-naga-bridge calls naga::back::hlsl to produce HLSL source; that source is then handed to one of three compilers, controlled by WGPU_DX12_COMPILER:

Value	Compiler	Notes
dxc (default)	External dxcompiler.dll	Requires v1.8.2502 or newer on PATH (or in the working directory).
static-dxc	mach-dxcompiler-rs	DXC linked statically. Requires the static-dxc feature.
fxc	Built-in legacy compiler	Older, smaller surface, used as fallback.

When DXC isn't found, the backend falls back to FXC and logs a warning.

How it works

graph TD
    Core[wgpu-core] --> Enc[dx12::CommandEncoder]
    Enc --> List[ID3D12GraphicsCommandList]
    Enc -->|barriers| List
    Core --> Dev[dx12::Device]
    Dev -->|CreateCommittedResource| GPU[D3D12 driver]
    Dev --- Alloc[gpu-allocator]
    Alloc --> GPU
    Dev --> Heaps[dx12::DescriptorAllocator]
    Heaps --> GPU
    Core --> Queue[dx12::Queue]
    Queue -->|ExecuteCommandLists| GPU
    Queue -->|Present + waitable swapchain| GPU

Notable features and recent work

• External fence synchronization — PR #9463 added Queue::add_wait_fence / add_signal_fence for coordination with non-wgpu D3D12 code.
• Waitable swapchain — Dx12UseFrameLatencyWaitableObject in wgpu-types exposes the waitable-object behavior; dx12/mod.rs and dx12/swapchain* integrate it.
• DComp presentation path — dx12/dcomp.rs enables DirectComposition for child-surface scenarios where the user doesn't own the HWND.
• Custom descriptor allocator — dx12/descriptor.rs uses range-alloc to manage CPU/GPU descriptor heap ranges. Keeps CreateRenderTargetView-style calls fast.
• PIX markers — auxil::dxgi::pix_markers integrates with WinPixEventRuntime.

Validation

InstanceFlags::DEBUG enables the D3D12 debug layer (requires the Windows SDK to be installed). InstanceFlags::GPU_BASED_VALIDATION enables D3D12's GBV. WGPU_DEBUG=1 and WGPU_VALIDATION=1 set these via env.

xtask install-warp (xtask/src/install_warp.rs) installs the Microsoft WARP DLL for software DX12, used by CI on Windows runners that don't have a real GPU.

Integration points

• Above: wgpu-core.
• Below: windows, windows-core, windows-result, gpu-allocator, range-alloc, mach-dxcompiler-rs (optional).
• Sideways: wgpu-hal/src/auxil/dxc_shader_compiler.rs for shared DXC integration; auxil/dxgi/ for shared DXGI helpers.

Entry points for modification

• A new feature — dx12/adapter.rs does feature detection by querying D3D12_FEATURE_DATA_* structs. Add the relevant query, plumb it through Features/Limits, then implement in device.rs and command.rs.
• Pipeline descriptor changes — dx12/pipeline_desc.rs is the central place for constructing D3D12_GRAPHICS_PIPELINE_STATE_DESC and D3D12_COMPUTE_PIPELINE_STATE_DESC.
• Allocator changes — dx12/suballocation.rs wraps gpu-allocator; dx12/descriptor.rs is project-internal and easier to extend.
• A new shader compiler path — extend dx12/shader_compilation.rs to add a third backend or alternate DXC entrypoint.