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 and includes many extensions specific to the native backends. 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.

Most types and functions are documented, but for more general guides and explanations, see the documentation modules.

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.

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:
documentation: General documentation and guides for the wgpu crate.
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.
DisplayChromaticity: CIE 1931 xy chromaticity of a display’s primaries and white point. Each coordinate is [x, y]; a coordinate the platform omits is None.
DisplayCoarseRange: Coarse, boolean dynamic-range and gamut signal.
DisplayHdrInfo: HDR and luminance characteristics of the display backing a Surface, as reported by the platform at query time.
DisplayHeadroom: Relative EDR headroom (Apple): unitless multipliers over current SDR white, where 1.0 means no headroom. Moves with brightness, ambient light, battery, and which display the window is on. Apple exposes no absolute-nit equivalent, so this is separate from DisplayLuminance and can’t be converted to nits.
DisplayLuminance: Absolute luminance levels in nits (cd/m²). Populated only on Windows (via DXGI); None on every other platform.
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.
SurfaceColorSpaces: A set of SurfaceColorSpaces supported by a surface for a particular texture format.
SurfaceFormatCapabilities: A texture format supported by a surface, together with the color spaces in which the surface can present it.
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.
TextureComponentSwizzle: Specifies the texture component swizzle for each channel.
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.
ComponentSwizzle: Specifies the component swizzle for a channel.
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.
DisplayGamut: Coarse gamut classification, mirroring CSS color-gamut.
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 push_error_scope may be configured to catch.
ErrorType: A classification of WebGPU error for implementers of the WebGPU API to use in their own error layer(s).
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.
SurfaceColorSpace: The color space in which the presentation engine interprets the values written to a surface 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: 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: Corresponds to WebGPU GPUVertexFormat.
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 uncaptured_error
WasmNotSend
WasmNotSendSync
WasmNotSync
WebGpuError: A trait for querying the ErrorType classification of an error.
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.
ErrorSourceNon-target_family=wasm, or fragile-send-sync-non-atomic-wasm and non-atomics: 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.
QueueDescriptor: Describes a Queue.
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

Re-exports§

Re-exports§

Modules§

Macros§

Structs§

Enums§

Constants§

Traits§

Type Aliases§

Crate wgpu

`Re-exports§`

`Modules§`

`Macros§`

`Structs§`

`Enums§`

`Constants§`

`Traits§`

`Type Aliases§`