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 targetingemscripten
. -
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 viaserde
on common wgpu types.replay
— Allow deserializing of trace capture files that were written with thetrace
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
— ImplementSend
andSync
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
andSync
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.
§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
ornaga
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.
- Adapter
Info - Information about an adapter.
- Backends
- Represents the backends that wgpu will use.
- Bind
Group - Handle to a binding group.
- Bind
Group Descriptor - Describes a group of bindings and the resources to be bound.
- Bind
Group Entry - An element of a
BindGroupDescriptor
, consisting of a bindable resource and the slot to bind it to. - Bind
Group Layout - Handle to a binding group layout.
- Bind
Group Layout Descriptor - Describes a
BindGroupLayout
. - Bind
Group Layout Entry - Describes a single binding inside a bind group.
- Blend
Component - Describes a blend component of a
BlendState
. - Blend
State - Describe the blend state of a render pipeline,
within
ColorTargetState
. - Buffer
- Handle to a GPU-accessible buffer.
- Buffer
Async Error - Error occurred when trying to async map a buffer.
- Buffer
Binding - Describes the segment of a buffer to bind.
- Buffer
Slice - A slice of a
Buffer
, to be mapped, used for vertex or index data, or the like. - Buffer
Usages - Different ways that you can use a buffer.
- Buffer
View - A read-only view of a mapped buffer’s bytes.
- Buffer
View Mut - A write-only view of a mapped buffer’s bytes.
- Color
- RGBA double precision color.
- Color
Target State - Describes the color state of a render pipeline.
- Color
Writes - Color write mask. Disabled color channels will not be written to.
- Command
Buffer - Handle to a command buffer on the GPU.
- Command
Buffer Descriptor - Describes a
CommandBuffer
. - Command
Encoder - Encodes a series of GPU operations.
- Compilation
Info - Compilation information for a shader module.
- Compilation
Message - A single message from the shader compilation process.
- Compute
Pass - In-progress recording of a compute pass.
- Compute
Pass Descriptor - Describes the attachments of a compute pass.
- Compute
Pass Timestamp Writes - Describes the timestamp writes of a compute pass.
- Compute
Pipeline - Handle to a compute pipeline.
- Compute
Pipeline Descriptor - Describes a compute pipeline.
- Core
Counters wgpu-core
’s internal counters.- Create
Surface Error Instance::create_surface()
or a related function failed.- Depth
Bias State - Describes the biasing setting for the depth target.
- Depth
Stencil State - Describes the depth/stencil state in a render pipeline.
- Device
- Open connection to a graphics and/or compute device.
- Downlevel
Capabilities - Lists various ways the underlying platform does not conform to the WebGPU standard.
- Downlevel
Flags - 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.
- Fragment
State - Describes the fragment processing in a render pipeline.
- HalCounters
wgpu-hal
’s internal counters.- Image
Copy Buffer Base - View of a buffer which can be used to copy to/from a texture.
- Image
Copy Texture Base - View of a texture which can be used to copy to/from a buffer/texture.
- Image
Copy Texture Tagged Base - View of a texture which can be used to copy to a texture, including color space and alpha premultiplication information.
- Image
Data Layout - Layout of a texture in a buffer’s memory.
- Image
Subresource Range - Subresource range within an image
- Instance
- Context for all other wgpu objects. Instance of wgpu.
- Instance
Descriptor - Options for creating an instance.
- Instance
Flags - Instance debugging flags.
- Internal
Counters - All internal counters, exposed for debugging purposes.
- Limits
- Represents the sets of limits an adapter/device supports.
- Multisample
State - 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.
- Pipeline
Cache - Handle to a pipeline cache, which is used to accelerate
creating
RenderPipeline
s andComputePipeline
s in subsequent executions - Pipeline
Cache Descriptor - Describes a pipeline cache, which allows reusing compilation work between program runs.
- Pipeline
Compilation Options - Advanced options for use when a pipeline is compiled
- Pipeline
Layout - Handle to a pipeline layout.
- Pipeline
Layout Descriptor - Describes a
PipelineLayout
. - Pipeline
Statistics Types - Flags for which pipeline data should be recorded.
- Presentation
Timestamp - Nanosecond timestamp used by the presentation engine.
- Primitive
State - Describes the state of primitive assembly and rasterization in a render pipeline.
- Push
Constant Range - A range of push constant memory to pass to a shader stage.
- Query
Set - Handle to a query set.
- Queue
- Handle to a command queue on a device.
- Queue
Write Buffer View - A write-only view into a staging buffer.
- Render
Bundle - Pre-prepared reusable bundle of GPU operations.
- Render
Bundle Depth Stencil - Describes the depth/stencil attachment for render bundles.
- Render
Bundle Encoder - Encodes a series of GPU operations into a reusable “render bundle”.
- Render
Bundle Encoder Descriptor - Describes a
RenderBundleEncoder
. - Render
Pass - In-progress recording of a render pass: a list of render commands in a
CommandEncoder
. - Render
Pass Color Attachment - Describes a color attachment to a
RenderPass
. - Render
Pass Depth Stencil Attachment - Describes a depth/stencil attachment to a
RenderPass
. - Render
Pass Descriptor - Describes the attachments of a render pass.
- Render
Pass Timestamp Writes - Describes the timestamp writes of a render pass.
- Render
Pipeline - Handle to a rendering (graphics) pipeline.
- Render
Pipeline Descriptor - Describes a render (graphics) pipeline.
- Request
Adapter Options Base - Options for requesting adapter.
- Request
Device Error - Requesting a device from an
Adapter
failed. - Sampler
- Handle to a sampler.
- Sampler
Descriptor - Describes a
Sampler
. - Shader
Module - Handle to a compiled shader module.
- Shader
Module Descriptor - Descriptor for use with
Device::create_shader_module
. - Shader
Module Descriptor SpirV - Descriptor for a shader module given by SPIR-V binary, for use with
Device::create_shader_module_spirv
. - Shader
Stages - Describes the shader stages that a binding will be visible from.
- Source
Location - A human-readable representation for a span, tailored for text source.
- Stencil
Face State - Describes stencil state in a render pipeline.
- Stencil
State - State of the stencil operation (fixed-pipeline stage).
- Submission
Index - Identifier for a particular call to
Queue::submit
. Can be used as part of an argument toDevice::poll
to block for a particular submission to finish. - Surface
- Handle to a presentable surface.
- Surface
Capabilities - Defines the capabilities of a given surface and adapter.
- Surface
Texture - Surface texture that can be rendered to.
Result of a successful call to
Surface::get_current_texture
. - Texture
- Handle to a texture on the GPU.
- Texture
Format Feature Flags - Feature flags for a texture format.
- Texture
Format Features - Features supported by a given texture format
- Texture
Usages - Different ways that you can use a texture.
- Texture
View - Handle to a texture view.
- Texture
View Descriptor - Describes a
TextureView
. - Vertex
Attribute - Vertex inputs (attributes) to shaders.
- Vertex
Buffer Layout - Describes how the vertex buffer is interpreted.
- Vertex
State - Describes the vertex processing in a render pipeline.
Enums§
- Address
Mode - How edges should be handled in texture addressing.
- Astc
Block - ASTC block dimensions
- Astc
Channel - ASTC RGBA channel
- Backend
- Backends supported by wgpu.
- Binding
Resource - Resource that can be bound to a pipeline.
- Binding
Type - Specific type of a binding.
- Blend
Factor - Alpha blend factor.
- Blend
Operation - Alpha blend operation.
- Buffer
Binding Type - Specific type of a buffer binding.
- Compare
Function - Comparison function used for depth and stencil operations.
- Compilation
Message Type - The type of a compilation message.
- Composite
Alpha Mode - Specifies how the alpha channel of the textures should be handled during compositing.
- Device
Lost Reason - Reason for “lose the device”.
- Device
Type - Supported physical device types.
- Dx12
Compiler - Selects which DX12 shader compiler to use.
- Error
- Error type
- Error
Filter - Filter for error scopes.
- Face
- Face of a vertex.
- Filter
Mode - Texel mixing mode when sampling between texels.
- Front
Face - Vertex winding order which classifies the “front” face of a triangle.
- Gles3
Minor Version - Selects which OpenGL ES 3 minor version to request.
- Index
Format - Format of indices used with pipeline.
- LoadOp
- Operation to perform to the output attachment at the start of a render pass.
- Maintain
Base - Passed to
Device::poll
to control how and if it should block. - Maintain
Result - Result of a maintain operation.
- MapMode
- Type of buffer mapping.
- Memory
Hints - Hints to the device about the memory allocation strategy.
- Polygon
Mode - Type of drawing mode for polygons
- Power
Preference - Power Preference when choosing a physical adapter.
- Predefined
Color Space - Color spaces supported on the web.
- Present
Mode - Behavior of the presentation engine based on frame rate.
- Primitive
Topology - Primitive type the input mesh is composed of.
- Query
Type - Type of query contained in a QuerySet.
- Sampler
Binding Type - Specific type of a sampler binding.
- Sampler
Border Color - Color variation to use when sampler addressing mode is
AddressMode::ClampToBorder
- Shader
Model - Collections of shader features a device supports if they support less than WebGPU normally allows.
- Shader
Source - Source of a shader module.
- Stencil
Operation - Operation to perform on the stencil value.
- Storage
Texture Access - Specific type of a sample in a texture binding.
- StoreOp
- Operation to perform to the output attachment at the end of a render pass.
- Surface
Error - Result of an unsuccessful call to
Surface::get_current_texture
. - Surface
Status - Status of the received surface image.
- Surface
Target - The window/canvas/surface/swap-chain/etc. a surface is attached to, for use with safe surface creation.
- Surface
Target Unsafe - The window/canvas/surface/swap-chain/etc. a surface is attached to, for use with unsafe surface creation.
- Texture
Aspect - Kind of data the texture holds.
- Texture
Dimension - Dimensionality of a texture.
- Texture
Format - Underlying texture data format.
- Texture
Sample Type - Specific type of a sample in a texture binding.
- Texture
View Dimension - Dimensions of a particular texture view.
- Vertex
Format - Vertex Format for a
VertexAttribute
(input). - Vertex
Step Mode - 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§
- Uncaptured
Error Handler - Type for the callback of uncaptured error handler
- Wasm
NotSend - Wasm
NotSend Sync - Wasm
NotSync - Window
Handle - Super trait for window handles as used in
SurfaceTarget
.
Type Aliases§
- Buffer
Address - Integral type used for buffer offsets.
- Buffer
Descriptor - Describes a
Buffer
. - Buffer
Size - Integral type used for buffer slice sizes.
- Command
Encoder Descriptor - Describes a
CommandEncoder
. - Device
Descriptor - Describes a
Device
. - Dynamic
Offset - Integral type used for dynamic bind group offsets.
- Error
Source - Lower level source of the error.
- Image
Copy Buffer - View of a buffer which can be used to copy to/from a texture.
- Image
Copy Texture - View of a texture which can be used to copy to/from a buffer/texture.
- Image
Copy Texture Tagged - View of a texture which can be used to copy to a texture, including color space and alpha premultiplication information.
- Label
- Object debugging label.
- Maintain
- Passed to
Device::poll
to control how and if it should block. - Query
SetDescriptor - Describes a
QuerySet
. - Render
Bundle Descriptor - Describes a
RenderBundle
. - Request
Adapter Options - Additional information required when requesting an adapter.
- Shader
Location - Integral type used for binding locations in shaders.
- Surface
Configuration - Describes a
Surface
. - Texture
Descriptor - Describes a
Texture
.