wgpu-types

wgpu-types (wgpu-types/) holds the plain-data types shared by wgpu, wgpu-core, and wgpu-hal, plus by every direct embedder of wgpu-core (Firefox, Deno). Everything in here is #![no_std]-compatible and free of platform code.

Purpose

• Provide a stable, FFI-friendly vocabulary for textures, buffers, features, limits, etc.
• Avoid pulling Vulkan/Metal/DX12/GL types into crates that don't need them.
• Act as the version-coordination point: wgpu-types releases drive coordinated upgrades across wgpu, wgpu-core, wgpu-hal, and downstream embedders.

Directory layout

wgpu-types/
├── Cargo.toml
└── src/
    ├── lib.rs              crate root
    ├── adapter.rs          AdapterInfo, DeviceType
    ├── assertions.rs
    ├── backend.rs          Backend, Backends bitflags (~37 KB)
    ├── binding.rs          BindGroupLayoutEntry, BindingType, ...
    ├── buffer.rs           BufferUsages, BufferAddress, ...
    ├── cast_utils.rs
    ├── counters.rs         InternalCounters
    ├── device.rs           DeviceLostReason, ShaderRuntimeChecks
    ├── env.rs              env-var parsing helpers
    ├── error.rs
    ├── features.rs         Features bitflags (~85 KB)
    ├── instance.rs         InstanceDescriptor, InstanceFlags
    ├── limits.rs           Limits (~56 KB)
    ├── math.rs
    ├── origin_extent.rs    Origin2d, Origin3d, Extent3d
    ├── ray_tracing.rs      ray-tracing types
    ├── render.rs           PrimitiveState, BlendState, ColorTargetState, ... (~36 KB)
    ├── send_sync.rs
    ├── shader.rs           ShaderStage, ShaderLocation
    ├── surface.rs          SurfaceCapabilities, PresentMode, ... (~15 KB)
    ├── texture/
    ├── texture.rs          TextureFormat, TextureUsages, ... (~40 KB)
    ├── tokens.rs
    ├── transfers.rs        TexelCopyBufferLayout, ...
    ├── vertex.rs           VertexAttribute, VertexFormat, VertexStepMode
    └── write_only.rs       WriteOnly, WriteOnlyIter (~42 KB)

The big files are features.rs, limits.rs, texture.rs, render.rs, and the backend.rs with all the per-backend option structs. Each one is heavy on declaration and bitflag definitions; logic is minimal.

Key abstractions

Type	File	Purpose
Features	wgpu-types/src/features.rs	Bitflags enumerating optional GPU features. FeaturesWGPU and FeaturesWebGPU split.
Limits	wgpu-types/src/limits.rs	Numeric capability bounds. default(), downlevel_defaults(), etc.
TextureFormat	wgpu-types/src/texture.rs	Every format wgpu knows about.
BufferUsages, TextureUsages	wgpu-types/src/{buffer,texture}.rs	Bitflags for resource intent.
Backend, Backends	wgpu-types/src/backend.rs	Backend identifiers and bitflags.
InstanceDescriptor, InstanceFlags	wgpu-types/src/instance.rs	Instance configuration.
BackendOptions (Dx12, Gl, Noop)	wgpu-types/src/backend.rs	Per-backend configuration carried in InstanceDescriptor.
DownlevelCapabilities, DownlevelFlags, DownlevelLimits	wgpu-types/src/lib.rs	Sub-baseline reporting.
WriteOnly, WriteOnlyIter	wgpu-types/src/write_only.rs	A type for writing into device-mapped memory without reading back (for performance and Wasm uncached-memory reasons).

Constants

wgpu-types exports a number of standard alignment constants:

• COPY_BUFFER_ALIGNMENT, COPY_BYTES_PER_ROW_ALIGNMENT
• IMMEDIATE_DATA_ALIGNMENT, MAP_ALIGNMENT
• QUERY_RESOLVE_BUFFER_ALIGNMENT, QUERY_SET_MAX_QUERIES
• MAXIMUM_SUBGROUP_MAX_SIZE, MINIMUM_SUBGROUP_MIN_SIZE
• VERTEX_ALIGNMENT

These mirror values from the WebGPU spec; they're re-exported by wgpu so user code can reference them without a separate dependency.

How it works

This is a passive types crate. There's no runtime behavior besides constructors, Default impls, and a few helpers in cast_utils.rs, math.rs, and env.rs.

env.rs deserves a callout: the *::from_env() helpers on InstanceDescriptor, Backends, etc. parse the standard set of WGPU_* environment variables. See reference/configuration.

Integration points

• Re-exported by: wgpu (basically every public type via pub use wgt::... in wgpu/src/lib.rs); wgpu-core and wgpu-hal use them directly.
• Independent of: any backend; this crate has no vulkan, metal, dx12, or gles cfg blocks.
• Optional features: serde, arbitrary, counters, std, replay, trace. Disabled by default to keep the crate light.

Entry points for modification

• A new feature flag — add a bit to Features in features.rs, then propagate the new bit through wgpu-core/src/limits.rs, the relevant wgpu-hal backends, and any user-facing API.
• A new texture format — add a variant to TextureFormat, update its match arms across the file (block size, sample type, copy support, etc.). Then propagate to the naga::ir::StorageFormat mapping in wgpu-core/src/validation.rs.
• A new limit — add a field to Limits. Make sure Limits::default, Limits::downlevel_defaults, Limits::downlevel_webgl2_defaults, and the limit-checking helpers in wgpu-core/src/limits.rs all stay in sync.

Changes here ripple widely, so PRs that touch wgpu-types are typically cross-crate and warrant prior discussion (per CONTRIBUTING.md).