Crate wgpu

Expand description

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_spirvspirv: Macro to load a SPIR-V module statically.
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.
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).
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.
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 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.
Dx12BackendOptions: Configuration for the DX12 backend.
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.
GlBackendOptions: Configuration for the OpenGL/OpenGLES backend.
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.
WgslLanguageFeatures: WGSL language extensions.

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
WasmNotSend
WasmNotSendSync
WasmNotSync
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.

Crate wgpuCopy item path