Crate wgpu

Expand description

wgpu is a cross-platform, safe, pure-Rust graphics API. It runs natively on Vulkan, Metal, D3D12, and OpenGL; and on top of WebGL2 and WebGPU on wasm.

The API is based on the WebGPU standard, but is a fully native Rust library. It serves as the core of the WebGPU integration in Firefox, Servo, and Deno.

§Getting Started

The main entry point to the API is the Instance type, from which you can create Adapter, Device, and Surface.

If you are new to wgpu and graphics programming, we recommend starting with Learn Wgpu.

Additionally, WebGPU Fundamentals is a tutorial for WebGPU which is very similar to our API, minus differences between Rust and Javascript.

We have a wiki which has information on useful architecture patterns, debugging tips, and more getting started information.

There are examples for this version available on GitHub.

The API is refcounted, so all handles are cloneable, and if you create a resource which references another, it will automatically keep dependent resources alive.

wgpu uses the coordinate systems of D3D and Metal. Depth ranges from [0, 1].

Render	Texture

wgpu’s MSRV is 1.87.

§Extension Specifications

While the core of wgpu is based on the WebGPU standard, we also support extensions that allow for features that the standard does not have yet. For high-level documentation on how to use these extensions, see documentation on Features or the relevant specification:

🧪EXPERIMENTAL🧪 APIs are subject to change and may allow undefined behavior if used incorrectly.

🧪EXPERIMENTAL🧪 Ray Tracing.
🧪EXPERIMENTAL🧪 Mesh Shading.

§Shader Support

wgpu can consume shaders in WGSL, SPIR-V, and GLSL. Both HLSL and GLSL have compilers to target SPIR-V. All of these shader languages can be used with any backend as we handle all of the conversions. Additionally, support for these shader inputs is not going away.

While WebGPU does not support any shading language other than WGSL, we will automatically convert your non-WGSL shaders if you’re running on WebGPU.

WGSL is always supported by default, but GLSL and SPIR-V need features enabled to compile in support.

To enable WGSL shaders, enable the wgsl feature of wgpu (enabled by default). To enable SPIR-V shaders, enable the spirv feature of wgpu. To enable GLSL shaders, enable the glsl feature of wgpu.

§Feature flags

§Backends

dx12 (enabled by default) — Enables the DX12 backend on Windows.
metal (enabled by default) — Enables the Metal backend on macOS & iOS.
vulkan (enabled by default) — Enables the Vulkan backend on Windows, Linux, and Android.
gles (enabled by default) — Enables the OpenGL/GLES backend on Windows, Linux, Android, and Emscripten.
webgpu (enabled by default) — Enables the WebGPU backend on WebAssembly.

§Conditional Backends

angle — Enables the GLES backend on macOS only for use with ANGLE.
vulkan-portability — Enables the Vulkan backend on macOS & iOS only for use with MoltenVK.
webgl — Enables the GLES backend on WebAssembly only.

§Backend features

drm — Support creating textures from DRM display/window handles.
noop — Enables the noop backend for testing.

This backend allows creating resources such as buffers and textures, but performs no computation. Because it lacks basic functionality, it is only actually used if explicitly enabled through NoopBackendOptions.

Note: In the documentation, if you see that an item depends on a backend, it means that the item is only available when that backend is enabled and the backend is supported on the current platform.

§Shading language support

These features enable support for that input language on all platforms. We will translate the input language to whatever the backend requires.

spirv — Enable accepting SPIR-V shaders as input.
glsl — Enable accepting GLSL shaders as input.
wgsl (enabled by default) — Enable accepting WGSL shaders as input.
naga-ir — Enable accepting naga IR shaders as input.

§Assertions and Serialization

strict_asserts — Apply run-time checks, even in release builds. These are in addition to the validation carried out at public APIs in all builds.
serde — Enables serialization via serde on common wgpu types.

§External libraries

The following features facilitate integration with third-party supporting libraries.

static-dxc — Enables statically linking DXC.

Normally, to use the modern DXC shader compiler with wgpu, the final application must be shipped alongside dxcompiler.dll (min v1.8.2502) (which can be downloaded from Microsoft’s GitHub). This feature statically links a version of DXC so that no external binaries are required to compile DX12 shaders.

§Other

counters — Internally count resources and events for debugging purposes. If the counters feature is disabled, the counting infrastructure is removed from the build and the exposed counters always return 0.
fragile-send-sync-non-atomic-wasm — Implement Send and Sync on Wasm, but only if atomics are not enabled.

WebGL/WebGPU objects can not be shared between threads. However, it can be useful to artificially mark them as Send and Sync anyways to make it easier to write cross-platform code. This is technically very unsafe in a multithreaded environment, but on a wasm binary compiled without atomics is a definitionally single-threaded environment.
web (enabled by default) — Use web-specific libraries on WASM

Those libraries (wasm-bindgen, web-sys, js-sys) can only be used when there is a JavaScript context around the WASM VM, e.g., when the WASM binary is used in a browser.
std (enabled by default) — Enables use of the standard library within wgpu and its dependencies.

This can allow for better error reporting and for improved multithreading support.
parking_lot (enabled by default) — Uses parking_lot as the implementation for locking primitives.

This is a recommended feature for most users and should only be disabled when required, e.g., for no_std support. If disabled, either std::sync::Mutex or core::cell::RefCell will be used, based on whether std is enabled or not.
exhaust — Enables exhaust method for TextureFormat of wgpu-types.

This is relevant for wgpu-info.

§Feature Aliases

These features aren’t actually features on the crate itself, but a convenient shorthand for complicated cases.

wgpu_core — Enabled when there is any non-webgpu backend enabled on the platform.
naga — Enabled when target glsl or spirv input is enabled, or when wgpu_core is enabled.

Re-exports§

pub extern crate wgpu_hal as hal;
pub extern crate wgpu_core as wgc;
pub extern crate wgpu_types as wgt;

`Re-exports§`

pub use ::wgc::naga;wgpu_core or naga
pub use raw_window_handle as rwh;

`Modules§`

api 🔒: Types and functions which define our public api and their helper functionality.
backend 🔒
cmp 🔒: We need to impl PartialEq, Eq, PartialOrd, Ord, and Hash for all handle types in wgpu.
customcustom: Provides wrappers custom backend implementations
dispatch 🔒: Infrastructure for dispatching calls to the appropriate “backend”. The “backends” are:
macros 🔒: Convenience macros
util: Utility structures and functions that are built on top of the main wgpu API.

`Macros§`

include_spirv_raw: Macro to load raw SPIR-V data statically, for use with Features::PASSTHROUGH_SHADERS.
include_wgsl: Load WGSL source code from a file at compile time.
vertex_attr_array: Macro to produce an array of VertexAttribute.

`Structs§`

Adapter: Handle to a physical graphics and/or compute device.
AdapterInfo: Information about an adapter.
AllocatorReport: A report that can be generated for informational purposes using Allocator::generate_report().
BackendOptions: Options that are passed to a given backend.
Backends: Represents the backends that wgpu will use.
BindGroup: Handle to a binding group.
BindGroupDescriptor: Describes a group of bindings and the resources to be bound.
BindGroupEntry: An element of a BindGroupDescriptor, consisting of a bindable resource and the slot to bind it to.
BindGroupLayout: Handle to a binding group layout.
BindGroupLayoutDescriptor: Describes a BindGroupLayout.
BindGroupLayoutEntry: Describes a single binding inside a bind group.
Blas: Bottom Level Acceleration Structure (BLAS).
BlasAabbGeometry: Definition for an axis-aligned bounding box geometry group for a bottom level acceleration structure.
BlasAsyncError: Error occurred when trying to asynchronously prepare a blas for compaction.
BlasBuildEntry: Builds the given sets of geometry into the given Blas.
BlasTriangleGeometry: Definition for a triangle geometry for a Bottom Level Acceleration Structure (BLAS).
BlendComponent: Describes a blend component of a BlendState.
BlendState: Describe the blend state of a render pipeline, within ColorTargetState.
Buffer: Handle to a GPU-accessible buffer.
BufferAsyncError: Error occurred when trying to async map a buffer.
BufferBinding: Describes the segment of a buffer to bind.
BufferSlice: A slice of a Buffer, to be mapped, used for vertex or index data, or the like.
BufferTextureCopyInfo: Information about a copy between a buffer and a texture.
BufferTransition: A buffer transition for use with CommandEncoder::transition_resources.
BufferUsages: Different ways that you can use a buffer.
BufferUses: Similar to BufferUsages, but used only for CommandEncoder::transition_resources.
BufferView: A read-only view of a mapped buffer’s bytes.
BufferViewMut: A write-only view of a mapped buffer’s bytes.
Color: RGBA double precision color.
ColorTargetState: Describes the color state of a render pipeline.
ColorWrites: Color write mask. Disabled color channels will not be written to.
CommandBuffer: Handle to a command buffer on the GPU.
CommandBufferDescriptor: Describes a CommandBuffer.
CommandEncoder: Encodes a series of GPU operations.
CompilationInfo: Compilation information for a shader module.
CompilationMessage: A single message from the shader compilation process.
ComputePass: In-progress recording of a compute pass.
ComputePassDescriptor: Describes the attachments of a compute pass.
ComputePassTimestampWrites: Describes the timestamp writes of a compute pass.
ComputePipeline: Handle to a compute pipeline.
ComputePipelineDescriptor: Describes a compute pipeline.
ContextBlasAabbGeometry: Context version of BlasAabbGeometry.
ContextBlasBuildEntry: Context version see BlasBuildEntry.
ContextBlasTriangleGeometry: Context version of BlasTriangleGeometry.
CooperativeMatrixProperties: Describes a supported cooperative matrix configuration.
CopyExternalImageDestInfo: View of a texture which can be used to copy to a texture, including color space and alpha premultiplication information.
CoreCounters: wgpu-core’s part of InternalCounters.
CreateSurfaceError: Instance::create_surface() or a related function failed.
DepthBiasState: Describes the biasing setting for the depth target.
DepthStencilState: Describes the depth/stencil state in a render pipeline.
Device: Open connection to a graphics and/or compute device.
DownlevelCapabilities: Lists various ways the underlying platform does not conform to the WebGPU standard.
DownlevelFlags: Binary flags listing features that may or may not be present on downlevel adapters.
DownlevelLimits: Represents the sets of additional limits on an adapter, which take place when running on downlevel backends.
Dx12BackendOptions: Configuration for the DX12 backend.
ErrorScopeGuard: Guard for an error scope pushed with Device::push_error_scope().
ExperimentalFeatures: Token of the user agreeing to access experimental features.
Extent3d: Extent of a texture related operation.
ExternalTexture: Handle to an external texture on the GPU.
ExternalTextureTransferFunction: Parameters describing a gamma encoding transfer function in the form tf = { k * linear | linear < b { a * pow(linear, 1/g) - (a-1) | linear >= b
Features: Features that are not guaranteed to be supported.
FeaturesWGPU: Features that are not guaranteed to be supported.
FeaturesWebGPU: Features that are not guaranteed to be supported.
ForceShaderModelToken: Used to force wgpu to expose certain features on passthrough shaders even when those features aren’t present on runtime-compiled shaders
FragmentState: Describes the fragment processing in a render pipeline.
GlBackendOptions: Configuration for the OpenGL/OpenGLES backend.
HalCounters: wgpu-hal’s part of InternalCounters.
ImageSubresourceRange: Subresource range within an image
Instance: Contains the various entry points to start interacting with the system’s GPUs.
InstanceDescriptor: Options for creating an instance.
InstanceFlags: Instance debugging flags.
InternalCounters: All internal counters, exposed for debugging purposes.
Limits: Represents the sets of limits an adapter/device supports.
LoadOpDontCare: Token of the user agreeing to use LoadOp::DontCare.
MapRangeError: Error returned by BufferSlice::get_mapped_range and BufferSlice::get_mapped_range_mut.
MemoryBudgetThresholds: Memory budget thresholds used by backends to try to avoid high memory pressure situations.
MeshPipelineDescriptor: Describes a mesh shader (graphics) pipeline.
MeshState: Describes the mesh shader stage in a mesh shader pipeline.
MultisampleState: Describes the multi-sampling state of a render pipeline.
NoopBackendOptions: Configuration for the noop backend.
Operations: Pair of load and store operations for an attachment aspect.
Origin2d: Origin of a copy from a 2D image.
Origin3d: Origin of a copy to/from a texture.
PassthroughShaderEntryPoint: Describes a single entry point in a passthrough shader descriptor.
PipelineCache: Handle to a pipeline cache, which is used to accelerate creating RenderPipelines and ComputePipelines in subsequent executions
PipelineCacheDescriptor: Describes a pipeline cache, which allows reusing compilation work between program runs.
PipelineCompilationOptions: Advanced options for use when a pipeline is compiled
PipelineLayout: Handle to a pipeline layout.
PipelineLayoutDescriptor: Describes a PipelineLayout.
PipelineStatisticsTypes: Flags for which pipeline data should be recorded in a query.
PresentationTimestamp: Nanosecond timestamp used by the presentation engine.
PrimitiveState: Describes the state of primitive assembly and rasterization in a render pipeline.
QuerySet: Handle to a query set.
Queue: Handle to a command queue on a device.
QueueWriteBufferView: A write-only view into a staging buffer.
RenderBundle: Pre-prepared reusable bundle of GPU operations.
RenderBundleDepthStencil: Describes the depth/stencil attachment for render bundles.
RenderBundleEncoder: Encodes a series of GPU operations into a reusable “render bundle”.
RenderBundleEncoderDescriptor: Describes a RenderBundleEncoder.
RenderPass: In-progress recording of a render pass: a list of render commands in a CommandEncoder.
RenderPassColorAttachment: Describes a color attachment to a RenderPass.
RenderPassDepthStencilAttachment: Describes a depth/stencil attachment to a RenderPass.
RenderPassDescriptor: Describes the attachments of a render pass.
RenderPassTimestampWrites: Describes the timestamp writes of a render pass.
RenderPipeline: Handle to a rendering (graphics) pipeline.
RenderPipelineDescriptor: Describes a render (graphics) pipeline.
RequestAdapterOptionsBase: Options for requesting adapter.
RequestDeviceError: Requesting a device from an Adapter failed.
Sampler: Handle to a sampler.
ShaderModule: Handle to a compiled shader module.
ShaderModuleDescriptor: Descriptor for use with Device::create_shader_module.
ShaderRuntimeChecks: Describes how shader bound checks should be performed.
ShaderStages: Describes the shader stages that a binding will be visible from.
SourceLocation: A human-readable representation for a span, tailored for text source.
StencilFaceState: Describes stencil state in a render pipeline.
StencilState: State of the stencil operation (fixed-pipeline stage).
SubmissionIndex: Identifier for a particular call to Queue::submit. Can be used as part of an argument to Device::poll to block for a particular submission to finish.
Surface: Handle to a presentable surface.
SurfaceCapabilities: Defines the capabilities of a given surface and adapter.
SurfaceTexture: Surface texture that can be rendered to. Result of a successful call to Surface::get_current_texture.
TaskState: Describes the task shader stage in a mesh shader pipeline.
TexelCopyBufferInfoBase: View of a buffer which can be used to copy to/from a texture.
TexelCopyBufferLayout: Layout of a texture in a buffer’s memory.
TexelCopyTextureInfoBase: View of a texture which can be used to copy to/from a buffer/texture.
Texture: Handle to a texture on the GPU.
TextureChannel: Represents the different format channels of a texture format.
TextureFormatFeatureFlags: Feature flags for a texture format.
TextureFormatFeatures: Features supported by a given texture format
TextureTransition: A texture transition for use with CommandEncoder::transition_resources.
TextureUsages: Different ways that you can use a texture.
TextureUses: Similar to TextureUsages, but used only for CommandEncoder::transition_resources.
TextureView: Handle to a texture view.
Tlas: Top Level Acceleration Structure (TLAS).
TlasInstance: Safe instance for a Tlas.
VertexAttribute: Vertex inputs (attributes) to shaders.
VertexBufferLayout: Specifies an interpretation of the bytes of a vertex buffer as vertex attributes.
VertexState: Describes the vertex processing in a render pipeline.
WgslLanguageFeatures: WGSL language extensions.
WriteOnly: Like &'a mut T, but allows only write operations.
WriteOnlyIter: Iterator over the elements of WriteOnly<[T]>.

`Enums§`

AddressMode: How edges should be handled in texture addressing.
AstcBlock: ASTC block dimensions
AstcChannel: ASTC RGBA channel
Backend: Backends supported by wgpu.
BindingResource: Resource to be bound by a BindGroup for use with a pipeline.
BindingType: Type of a binding in a bind group layout.
BlasGeometries: Contains the sets of geometry that go into a Blas.
BlendFactor: Alpha blend factor.
BlendOperation: Alpha blend operation.
BufferBindingType: Specific type of a buffer binding.
CompareFunction: Comparison function used for depth and stencil operations.
CompilationMessageType: The type of a compilation message.
CompositeAlphaMode: Specifies how the alpha channel of the textures should be handled during compositing.
ContextBlasGeometries: Context version of BlasGeometries.
CooperativeScalarType: The underlying scalar type of the cooperative matrix component.
CurrentSurfaceTexture: Result of a call to Surface::get_current_texture.
DeviceLostReason: Corresponds to a GPUDeviceLostReason.
DeviceType: Supported physical device types.
Dx12Compiler: Selects which DX12 shader compiler to use.
Dx12SwapchainKind: Selects which kind of swapchain to use on DX12.
Dx12UseFrameLatencyWaitableObject: Whether and how to use a waitable handle obtained from GetFrameLatencyWaitableObject.
DxcShaderModel: DXC shader model.
Error: Errors resulting from usage of GPU APIs.
ErrorFilter: Kinds of Errors a Device::push_error_scope() may be configured to catch.
ExternalTextureFormat: Format of an ExternalTexture. This indicates the number of underlying planes used by the ExternalTexture as well as each plane’s format.
Face: Face of a vertex.
FilterMode: Texel mixing mode when sampling between texels.
FrontFace: Vertex winding order which classifies the “front” face of a triangle.
GlDebugFns: Controls whether OpenGL debug functions are enabled.
GlFenceBehavior: Dictate the behavior of fences in OpenGL.
Gles3MinorVersion: Selects which OpenGL ES 3 minor version to request.
IndexFormat: Format of indices used with pipeline.
LoadOp: Operation to perform to the output attachment at the start of a render pass.
MapMode: Type of buffer mapping.
MemoryHints: Hints to the device about the memory allocation strategy.
MipmapFilterMode: Texel mixing mode when sampling between texels.
PollError: Error states after a device poll.
PollStatus: Status of device poll operation.
PolygonMode: Type of drawing mode for polygons
PowerPreference: Power Preference when choosing a physical adapter.
PredefinedColorSpace: Color spaces supported on the web.
PresentMode: Timing and queueing with which frames are actually displayed to the user.
PrimitiveTopology: Primitive type the input mesh is composed of.
QueryType: Type of queries contained in a QuerySet.
RequestAdapterError: Error when Instance::request_adapter() fails.
SamplerBindingType: Specific type of a sampler binding.
SamplerBorderColor: Color variation to use when sampler addressing mode is AddressMode::ClampToBorder
ShaderModel: Collections of shader features a device supports if they support less than WebGPU normally allows.
ShaderSource: Source of a shader module.
StencilOperation: Operation to perform on the stencil value.
StorageTextureAccess: Specific type of a sample in a texture binding.
StoreOp: Operation to perform to the output attachment at the end of a render pass.
SurfaceStatus: Status of the received surface image.
SurfaceTarget: The window/canvas/surface/swap-chain/etc. a surface is attached to, for use with safe surface creation.
SurfaceTargetUnsafe: The window/canvas/surface/swap-chain/etc. a surface is attached to, for use with unsafe surface creation.
TextureAspect: Selects a subset of the data a Texture holds.
TextureDimension: Dimensionality of a texture.
TextureFormat: Format in which a texture’s texels are stored in GPU memory.
TextureSampleType: Specific type of a sample in a texture binding.
TextureViewDimension: Dimensions of a particular texture view.
Trace: Controls API call tracing and specifies where the trace is written.
VertexFormat: Vertex Format for a VertexAttribute (input).
VertexStepMode: Whether a vertex buffer is indexed by vertex or by instance.

`Constants§`

AABB_GEOMETRY_MIN_STRIDE: Minimum stride for AABB geometry (24 bytes: two vec3<f32>). Minimum stride for AABB geometry (24 bytes: two vec3<f32>).
COPY_BUFFER_ALIGNMENT: Buffer to buffer copy as well as buffer clear offsets and sizes must be aligned to this number.
COPY_BYTES_PER_ROW_ALIGNMENT: Buffer-texture copies must have bytes_per_row aligned to this number.
IMMEDIATE_DATA_ALIGNMENT: Ranges of writes to immediate data must be at least this aligned.
MAP_ALIGNMENT: Minimum alignment of buffer mappings.
MAXIMUM_SUBGROUP_MAX_SIZE: The maximum allowed value for AdapterInfo::subgroup_max_size.
MINIMUM_SUBGROUP_MIN_SIZE: The minimum allowed value for AdapterInfo::subgroup_min_size.
QUERY_RESOLVE_BUFFER_ALIGNMENT: An offset into the query resolve buffer has to be aligned to this.
QUERY_SET_MAX_QUERIES: Maximum number of query result slots that can be requested in a QuerySetDescriptor.
QUERY_SIZE: Size in bytes of a single piece of query data.
VERTEX_ALIGNMENT: Vertex buffer offsets and strides have to be a multiple of this number.
VERTEX_STRIDE_ALIGNMENTDeprecated: Vertex buffer strides have to be a multiple of this number.

`Traits§`

DisplayAndWindowHandle: Super trait for a pair of display and window handles as used in SurfaceTarget.
UncapturedErrorHandler: The callback of Device::on_uncaptured_error().
WasmNotSend
WasmNotSendSync
WasmNotSync
WindowHandle: Send/Sync blanket trait for [HasWindowHandle] used in SurfaceTarget.

`Type Aliases§`

AccelerationStructureFlags: Flags for an acceleration structure.
AccelerationStructureGeometryFlags: Flags for a geometry inside a bottom level acceleration structure.
AccelerationStructureUpdateMode: Update mode for acceleration structure builds.
BlasAABBGeometrySizeDescriptor: Descriptor for the size defining attributes of an AABB geometry group in a bottom level acceleration structure.
BlasGeometrySizeDescriptors: Descriptor for the size defining attributes, for a bottom level acceleration structure.
BlasTriangleGeometrySizeDescriptor: Descriptor for the size defining attributes of a triangle geometry, for a bottom level acceleration structure.
BufferAddress: Integral type used for Buffer offsets and sizes.
BufferDescriptor: Describes a Buffer.
BufferSize: Integral type used for BufferSlice sizes.
CommandEncoderDescriptor: Describes a CommandEncoder.
CreateBlasDescriptor: Descriptor to create bottom level acceleration structures.
CreateTlasDescriptor: Descriptor to create top level acceleration structures.
DeviceDescriptor: Describes a Device.
DynamicOffset: Integral type used for dynamic bind group offsets.
ErrorSource: Lower level source of the error.
ExternalTextureDescriptor: Describes an ExternalTexture.
Label: Object debugging label.
PollType: Passed to Device::poll to control how and if it should block.
QuerySetDescriptor: Describes a QuerySet.
RenderBundleDescriptor: Describes a RenderBundle.
RequestAdapterOptions: Additional information required when requesting an adapter.
SamplerDescriptor: Describes a Sampler.
ShaderLocation: Integral type used for binding locations in shaders.
ShaderModuleDescriptorPassthrough: Descriptor for a shader module given by any of several sources. At least one of the shader types that may be used by the backend must be Some
SurfaceConfiguration: Describes a Surface.
TexelCopyBufferInfo: View of a buffer which can be used to copy to/from a texture.
TexelCopyTextureInfo: View of a texture which can be used to copy to/from a buffer/texture.
TextureDescriptor: Describes a Texture.
TextureViewDescriptor: Describes a TextureView.

Crate wgpu

Crate wgpu Copy item path

§Getting Started

§Extension Specifications

§Shader Support

§Feature flags

§Backends

§Conditional Backends

§Backend features

§Shading language support

§Assertions and Serialization

§External libraries

§Other

§Feature Aliases

Re-exports§

Re-exports§

Modules§

Macros§

Structs§

Enums§

Constants§

Traits§

Type Aliases§

Crate wgpu

`Re-exports§`

`Modules§`

`Macros§`

`Structs§`

`Enums§`

`Constants§`

`Traits§`

`Type Aliases§`