gfx-rs/wgpu

Configuration

wgpu has three configuration surfaces:

Cargo features — chosen at build time on the parent wgpu crate.
InstanceDescriptor / InstanceFlags — chosen at runtime by the application.
Environment variables — read by *::from_env helpers in wgpu-types.

The README's "Environment Variables" section is the human-friendly summary. This page lists what's available in the source.

Cargo features (parent `wgpu` crate)

Backends:

vulkan, metal, dx12, gles, noop — enable each wgpu-hal backend.
webgpu — wasm-only browser backend.
vulkan-portability — enable Vulkan portability subset (MoltenVK on macOS).
angle — route GLES through ANGLE on macOS.
static-dxc — link DXC statically via mach-dxcompiler-rs.

Shader frontends:

wgsl (default), glsl, spirv, naga-ir.

Misc:

serde, arbitrary — derive support.
trace, replay — wgpu-core tracing.
web — convenience for web targets.
fragile-send-sync-non-atomic-wasm — wasm without atomics.
custom — expose wgpu::backend::custom for user-pluggable backends.
std (default) — disable for no_std builds.

The full list with doc comments is rendered into the API docs by document_features::document_features!() in wgpu/src/lib.rs. The source is wgpu/Cargo.toml.

InstanceFlags

Defined in wgpu-types/src/instance.rs.

Flag	Effect
`DEBUG`	Enable backend-specific debug layers.
`VALIDATION`	Enable validation layers (e.g., VK_LAYER_KHRONOS_validation).
`GPU_BASED_VALIDATION`	Enable D3D12 GPU-based validation where supported.
`DISCARD_HAL_LABELS`	Strip object labels before they reach the HAL — small perf win.
`ALLOW_UNDERLYING_NONCOMPLIANT_ADAPTER`	Surface adapters that don't fully comply with WebGPU.
`AUTOMATIC_SHADER_FALLBACK`	Allow naga to apply automatic conversions on shader failure.

InstanceFlags::from_env() reads the corresponding env vars (see below).

Environment variables

Backend selection

WGPU_BACKEND=vulkan,metal,dx12,gl,noop — comma-separated list of backends to try.
WGPU_ADAPTER_NAME=<substr> — case-insensitive adapter name match.
WGPU_POWER_PREF=low|high — override RequestAdapterOptions::power_preference.
WGPU_FORCE_FALLBACK_ADAPTER=1 — force a fallback (software) adapter.

DX12

WGPU_DX12_COMPILER=dxc|static-dxc|fxc — pick the HLSL compiler.

Debugging

WGPU_DEBUG=1 — set InstanceFlags::DEBUG.
WGPU_VALIDATION=1 — set InstanceFlags::VALIDATION.
WGPU_GPU_BASED_VALIDATION=1 — set InstanceFlags::GPU_BASED_VALIDATION.
WGPU_DISCARD_HAL_LABELS=1 — set InstanceFlags::DISCARD_HAL_LABELS.
WGPU_ALLOW_NONCOMPLIANT_ADAPTER=1 — set the corresponding flag.
WGPU_AUTOMATIC_SHADER_FALLBACK=1 — set the corresponding flag.

CTS / Deno

When running through cts_runner or Deno, the corresponding DENO_WEBGPU_* variables apply:

DENO_WEBGPU_BACKEND, DENO_WEBGPU_ADAPTER_NAME, DENO_WEBGPU_POWER_PREFERENCE, DENO_WEBGPU_DX12_COMPILER.

Logging

RUST_LOG=... — standard env_logger syntax. CI's ci.yml uses RUST_LOG=debug,wasm_bindgen_wasm_interpreter=warn,wasm_bindgen_cli_support=warn,walrus=warn,naga=info.
RUST_BACKTRACE=full — show backtraces on panics.

CI-only

CARGO_INCREMENTAL=false — incremental builds disabled in CI for cache hit rate.
RUSTFLAGS=-D warnings, RUSTDOCFLAGS=-D warnings — promote warnings to errors.
WASM_BINDGEN_TEST_TIMEOUT=300 — 5-minute timeout for wasm tests.
PKG_CONFIG_ALLOW_CROSS=1 — for Android cross-compiles.
CACHE_SUFFIX=e — cache-busting key.
WGPU_CI=true — flag to enable CI-only behavior in tests.

InstanceDescriptor fields

Defined in wgpu-types/src/instance.rs. The relevant ones beyond flags and backends:

dx12_shader_compiler: Dx12Compiler — choose dxc, static-dxc, or fxc programmatically.
gles_minor_version: Gles3MinorVersion — request a specific GLES minor version.
gl_fence_behavior: GlFenceBehavior — choose how GL fences are emitted.
display: Option<Box<dyn WgpuHasDisplayHandle>> — pre-existing display handle (winit's OwnedDisplayHandle for example).
noop: NoopBackendOptions — noop-backend-specific options.

DeviceDescriptor fields

required_features: Features — features that must be available.
required_limits: Limits — minimum limits.
memory_hints: MemoryHints — Performance, MemoryUsage, or Manual { suballocated_device_memory_block_size }.
trace: Trace — Off, Directory(PathBuf), etc. for API tracing.
label: Label<'_>.