Glossary

Project-specific vocabulary and acronyms used across the wgpu codebase. WebGPU and Vulkan terms are included only where the wgpu codebase uses them in a specific way.

API and project terms

WebGPU — The W3C standard this project implements. Spec at https://www.w3.org/TR/webgpu/. The standard's WGSL shading language is at https://gpuweb.github.io/gpuweb/wgsl/.

WGSL — WebGPU Shading Language, the WebGPU spec's shading language. The default shader language accepted by wgpu.

HAL — Hardware Abstraction Layer. In this repo it refers to the wgpu-hal crate, which is the unsafe trait surface that backends implement.

Backend — A specific implementation of wgpu-hal::Api for one platform graphics API (Vulkan, Metal, DX12, GLES, noop). Selected at runtime via Backends/WGPU_BACKEND.

Adapter — A handle to a specific GPU on a specific backend. Created via Instance::request_adapter. One physical GPU may produce multiple adapters if multiple backends are enabled.

Device — A logical GPU instance owning resources and queues. Created from an Adapter via Adapter::request_device.

Surface — Something wgpu can present to: a window, a wasm canvas, a Wayland surface, a CAMetalLayer, etc. See wgpu/src/api/surface.rs and wgpu-hal/src/*/surface*.rs.

Trace — An on-disk recording of API calls produced by wgpu-core's Trace infrastructure (wgpu-core/src/device/trace.rs). Replayable by the player crate.

Downlevel — Capabilities below WebGPU's required baseline. Reported via DownlevelCapabilities (wgpu-types/src/lib.rs). Used to gate behavior on weaker drivers (e.g. WebGL2).

Feature — An optional, query-able GPU capability declared in wgt::Features (wgpu-types/src/features.rs). Devices opt in at creation time.

Limit — A numeric capability bound (max texture size, max bind groups, etc.) declared in wgt::Limits (wgpu-types/src/limits.rs). Devices opt in at creation time.

wgpu-core internals

Hub — The collection of resource registries inside wgpu-core::Global (wgpu-core/src/hub.rs, wgpu-core/src/global.rs). One slot per resource type (buffers, textures, ...).

Registry — A typed resource store keyed by Id (wgpu-core/src/registry.rs). Backed by a slot-based Storage (wgpu-core/src/storage.rs).

Id — A 64-bit handle (wgpu-core/src/id.rs) packing index, epoch, and backend bits. Public surface of wgpu-core is in terms of Ids.

Tracker — The state-tracking machinery that records usage of resources within and across passes/command buffers (wgpu-core/src/track/). Drives barrier insertion.

Snatch — A specialized atomic cell used to "snatch" a resource's HAL handle when it's destroyed even while other code holds a reference (wgpu-core/src/snatch.rs).

Lock rank — Static ordering that the lock helpers in wgpu-core/src/lock/ enforce to prevent deadlocks. Each lock site declares its rank.

Pool — Generic deduplicating cache used by pipelines/layouts (wgpu-core/src/pool.rs).

Indirect validation — A separate compute pipeline that validates indirect-draw / indirect-dispatch buffers before the GPU consumes them (wgpu-core/src/indirect_validation/).

Init tracker — Tracks which sub-ranges of buffers/textures have been initialized so that uninitialized memory can be cleared lazily (wgpu-core/src/init_tracker/).

Timestamp normalization — Compute pipeline that converts driver-specific timestamp counters into WebGPU's nanosecond domain (wgpu-core/src/timestamp_normalization/).

wgpu-hal terms

hal::Api — The associated-types trait that defines a backend (wgpu-hal/src/lib.rs). Each backend exposes a marker type implementing it: vulkan::Api, metal::Api, dx12::Api, gles::Api, noop::Api.

DynInstance / DynDevice / ... — Trait-object dyn-friendly versions of the HAL types (wgpu-hal/src/dynamic/). wgpu-core stores these so it can hold multiple backends in one collection.

Acquire / present — wgpu-hal::Surface::acquire_texture and Queue::present are the per-backend hooks for swapchain integration.

Barrier / transition — Explicit resource synchronization primitives. wgpu-hal requires the caller to issue them; wgpu-core's tracker computes them.

naga terms

Naga IR — Naga's internal shader representation (naga/src/ir/). Module-level: a Module containing arenas of Type, Constant, Expression, Function, EntryPoint, etc.

Arena — Naga's index-based container (naga/src/arena.rs). Items are referenced by Handle<T> rather than by reference, so the IR is freely cloneable and serializable.

Handle — A NonZeroU32 index into an Arena<T>. Comparable, hashable, no lifetime.

Span — Source-position information attached to IR items (naga/src/span.rs).

Compact — A pass that removes unreachable items from the IR (naga/src/compact/). Run after parsing or before code generation.

Constant evaluator — Folds constant expressions in the IR at translation time (naga/src/proc/constant_evaluator.rs). Heavily used by WGSL compilation.

Frontend / Front-end — WGSL/GLSL/SPIR-V parser. Lives under naga/src/front/.

Backend / Back-end — SPIR-V/MSL/HLSL/GLSL/WGSL/DOT writer. Lives under naga/src/back/.

Validator — Checks an IR module against the WGSL specification's static rules (naga/src/valid/). Returns a ModuleInfo consumed by backends.

Capabilities / ValidationFlags — Bitflags passed to the validator that gate optional language features (subgroup ops, float64, etc.) (naga/src/valid/mod.rs).

Diagnostic filter — WGSL @diagnostic(...) attribute support (naga/src/diagnostic_filter.rs).

Test infrastructure

CTS — WebGPU Conformance Test Suite (https://github.com/gpuweb/cts). Run via cargo xtask cts, driven by cts_runner/.

#[gpu_test] — Custom test macro for tests that need a real GPU (tests/src/, applied in tests/tests/ and examples/features/). Provides per-adapter expectation handling.

Snapshot test — Naga test that compares generated output (SPIR-V/MSL/HLSL/GLSL/WGSL) against checked-in files under naga/tests/out/.

Player / replay — player/ re-executes a captured trace for regression tests.

hlsl-snapshots — Helper crate for HLSL snapshot tests (naga/hlsl-snapshots/).

Repository roles

Trunk — The main branch (origin/trunk). PRs target trunk.

Bors / merge queue — bors[bot] historically merged PRs; the repo now uses GitHub's merge queue (gh-readonly-queue/* branches in .github/workflows/ci.yml).

xtask — The repo automation crate (xtask/). Implements cargo xtask test, cts, run-wasm, changelog, miri, vendor-web-sys, etc.

naga xtask — A second xtask crate scoped to naga (naga/xtask/), implementing cargo xtask validate <backend> for validating snapshot output with external tools.