Crate wgpu

A cross-platform graphics and compute library based on WebGPU.

To start using the API, create an Instance.

Feature flags

Backends

⚠️ WIP: Not all backends can be manually configured today. On Windows, Linux & Android the Vulkan & GLES backends are always enabled. See #3514 for more details.

• dx12 (enabled by default) — Enables the DX12 backend on Windows.

• metal (enabled by default) — Enables the Metal backend on macOS & iOS.

• webgpu (enabled by default) — Enables the WebGPU backend on Wasm. Disabled when targeting emscripten.

• angle — Enables the GLES backend via ANGLE on macOS using.

• vulkan-portability — Enables the Vulkan backend on macOS & iOS.

• webgl — Enables the GLES backend on Wasm

  • ⚠️ WIP: Currently will also enable GLES dependencies on any other targets.

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

• 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.

Logging & Tracing

The following features do not have any effect on the WebGPU backend.

• 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.
• replay — Allow deserializing of trace capture files that were written with the trace feature. To replay a trace file use the wgpu player.

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 we know we are definitely not in a multithreaded environment.

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 and dxil.dll (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.

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 any non-wgsl shader input is enabled.

Re-exports

• pub use ::wgc as core;
  wgpu_core
• pub use ::hal;
  wgpu_core
• pub use ::wgc::naga;
  wgpu_core or naga
• pub use raw_window_handle as rwh;

Modules

• 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::SPIRV_SHADER_PASSTHROUGH.
• 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.
• 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).
• 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.
• BufferUsages
  Different ways that you can use a buffer.
• 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.
• ContextBlasBuildEntry
  Context version see BlasBuildEntry.
• ContextBlasTriangleGeometry
  Context version of BlasTriangleGeometry.
• CoreCounters
  wgpu-core’s internal counters.
• 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.
• Extent3d
  Extent of a texture related operation.
• Features
  Features that are not guaranteed to be supported.
• FragmentState
  Describes the fragment processing in a render pipeline.
• HalCounters
  wgpu-hal’s internal counters.
• ImageSubresourceRange
  Subresource range within an image
• Instance
  Context for all other wgpu objects. Instance of wgpu.
• 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.
• MultisampleState
  Describes the multi-sampling state of a render pipeline.
• 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.
• 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.
• PresentationTimestamp
  Nanosecond timestamp used by the presentation engine.
• PrimitiveState
  Describes the state of primitive assembly and rasterization in a render pipeline.
• PushConstantRange
  A range of push constant memory to pass to a shader stage.
• 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.
• ShaderModuleDescriptorSpirV
  Descriptor for a shader module given by SPIR-V binary, for use with Device::create_shader_module_spirv.
• 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.
• 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.
• TextureFormatFeatureFlags
  Feature flags for a texture format.
• TextureFormatFeatures
  Features supported by a given texture format
• TextureUsages
  Different ways that you can use a texture.
• TextureView
  Handle to a texture view.
• Tlas
  Top Level Acceleration Structure (TLAS).
• TlasBuildEntry
  Entry for a top level acceleration structure build. Used with raw instance buffers for an unvalidated builds. See TlasPackage for the safe version.
• TlasInstance
  Safe instance for a Tlas.
• TlasPackage
  The safe version of TlasEntry, containing TlasInstances instead of a raw buffer.
• VertexAttribute
  Vertex inputs (attributes) to shaders.
• VertexBufferLayout
  Describes how the vertex buffer is interpreted.
• VertexState
  Describes the vertex processing in a render pipeline.

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 that can be bound to a pipeline.
• BindingType
  Specific type of a binding.
• 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.
• DeviceLostReason
  Reason for “lose the device”.
• DeviceType
  Supported physical device types.
• Dx12Compiler
  Selects which DX12 shader compiler to use.
• Error
  Error type
• ErrorFilter
  Filter for error scopes.
• 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.
• 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.
• MaintainBase
  Passed to Device::poll to control how and if it should block.
• MaintainResult
  Result of a maintain operation.
• MapMode
  Type of buffer mapping.
• MemoryHints
  Hints to the device about the memory allocation strategy.
• PolygonMode
  Type of drawing mode for polygons
• PowerPreference
  Power Preference when choosing a physical adapter.
• PredefinedColorSpace
  Color spaces supported on the web.
• PresentMode
  Behavior of the presentation engine based on frame rate.
• PrimitiveTopology
  Primitive type the input mesh is composed of.
• QueryType
  Type of query contained in a QuerySet.
• 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.
• SurfaceError
  Result of an unsuccessful call to Surface::get_current_texture.
• 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
  Kind of data the texture holds.
• TextureDimension
  Dimensionality of a texture.
• TextureFormat
  Underlying texture data format.
• TextureSampleType
  Specific type of a sample in a texture binding.
• TextureViewDimension
  Dimensions of a particular texture view.
• VertexFormat
  Vertex Format for a VertexAttribute (input).
• VertexStepMode
  Whether a vertex buffer is indexed by vertex or by instance.

Constants

• 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.
• MAP_ALIGNMENT
  Size to align mappings.
• PUSH_CONSTANT_ALIGNMENT
  Alignment all push constants need
• QUERY_RESOLVE_BUFFER_ALIGNMENT
  An offset into the query resolve buffer has to be aligned to this.
• QUERY_SET_MAX_QUERIES
  Maximum queries in a query set
• QUERY_SIZE
  Size of a single piece of query data.
• VERTEX_STRIDE_ALIGNMENT
  Vertex buffer strides have to be aligned to this number.

Traits

• UncapturedErrorHandler
  Type for the callback of uncaptured error handler
• WasmNotSendNon-WebAssembly, or fragile-send-sync-non-atomic-wasm and non-atomics
• WasmNotSendSync
• WasmNotSyncNon-WebAssembly, or fragile-send-sync-non-atomic-wasm and non-atomics
• WindowHandle
  Super trait for window handles as 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.
• 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.
• BufferDescriptor
  Describes a Buffer.
• BufferSize
  Integral type used for buffer slice 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.
• ImageCopyBufferDeprecated
  Old name for a TexelCopyBufferInfo.
• ImageCopyTextureDeprecated
  Old name for a TexelCopyTextureInfo.
• ImageCopyTextureTaggedDeprecated
  Old name for a [CopyExternalImageDestInfo].
• ImageDataLayoutDeprecated
  Old name for a TexelCopyBufferLayout.
• Label
  Object debugging label.
• Maintain
  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.
• 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.