wgpu API

This document describes the wgpu API, which essentially is a Pythonic version of the WebGPU API. It exposes an API for performing operations, such as rendering and computation, on a Graphics Processing Unit.

Note

The WebGPU API is still being developed and occasionally there are backwards incompatible changes. Since we mostly follow the WebGPU API, there may be backwards incompatible changes to wgpu-py too. This will be so until the WebGPU API settles as a standard. In the mean time, keep an eye on the CHANGELOG.md.

How to read this API

The classes in this API all have a name staring with “GPU”, this helps discern them from flags and enums. These classes are never instantiated directly; new objects are returned by special methods (mostly from the device).

Most methods in this API have no positional arguments; each argument must be referenced by name. Some argument values must be a dict, these can be thought of as “nested” arguments. Many arguments (and dict fields) must be a flag or enum. Some arguments have a default value. Most do not.

Differences from WebGPU

This API is derived from the WebGPU spec, but differs in a few ways:

• Methods names are snake_case (instead of camelCase).

• Enums and flags are represented as objects with snake_case field names.

• Methods that in WebGPU accept a single descriptor, will accept the fields of that descriptor as keyword arguments.

• Async methods have a different name, read more below.

Further changes:

wgpu._classes.apidiff Differences of base API:

• Adds GPU.enumerate_adapters_async() - Method useful for multi-gpu environments

• Adds GPU.enumerate_adapters_sync() - Method useful for multi-gpu environments

• Adds GPUAdapter.summary() - Useful in multi-gpu environments

• Adds GPUBuffer.read_mapped() - Replacement for get_mapped_range

• Adds GPUBuffer.write_mapped() - Replacement for get_mapped_range

• Adds GPUCanvasContext.get_preferred_format() - Better place to define the preferred format

• Adds GPUCanvasContext.present() - The present method is used by the canvas

• Adds GPUDevice.adapter() - Too useful to not-have

• Adds GPUDevice.create_buffer_with_data() - Convenience function

• Adds GPUQueue.read_buffer() - For symmetry with queue.write_buffer

• Adds GPUQueue.read_texture() - For symmetry, and to help work around the bytes_per_row constraint

• Adds GPUTexture.size() - Too useful to not-have

• Adds GPUTextureView.size() - Need to know size e.g. for texture view provided by canvas

• Adds GPUTextureView.texture() - Too useful to not-have

• Changes GPU.get_preferred_canvas_format() - Disabled because we put it on the canvas context

• Changes GPU.request_adapter_async() - arguments include canvas

• Changes GPU.request_adapter_sync() - arguments include canvas

• Changes GPUBindingCommandsMixin.set_bind_group() - In the WebGPU specification, this method has two different signatures.

• Hides GPUBuffer.get_mapped_range()

• Hides GPUDevice.import_external_texture() - Specific to browsers

• Hides GPUDevice.lost_async() - Not a Pythonic API

• Hides GPUDevice.lost_sync() - Not a Pythonic API

• Hides GPUDevice.onuncapturederror() - Specific to browsers

• Hides GPUDevice.pop_error_scope_async()

• Hides GPUDevice.pop_error_scope_sync()

• Hides GPUDevice.push_error_scope()

• Hides GPUQueue.copy_external_image_to_texture() - Specific to browsers

Each backend may implement extra functionality on top of the base API. This is listed in backends.

Async code

Some methods and properties in the WebGPU API are asynchronous. In wgpu-py, these methods are always suffixed with _async. These method also have a synchronous variant, which come in two flafours:

• If the method has the plain method name (no suffix), the synchronous method is available in WebGPU as well. There’s no problem to use this variant.

• If the method ends with _sync, this is a convenience method, added in wgpu-py to fully support synchronous code. However, the synchronous variant is not part of the WebGPU spec, and as a consequence, code that uses this method is less portable (to e.g. pyodide/pyscript).

Overview

This overview attempts to describe how all classes fit together. Scroll down for a list of all flags, enums, structs, and GPU classes.

Adapter, device and canvas

The GPU class represents the API root/entrypoint. An instance is available at wgpu.gpu. This instance is loaded from one the backends.

The GPUAdapter represents a hardware or software device, with specific features, limits and properties. To actually start using that hardware for computations or rendering, a GPUDevice object must be requisted from the adapter. This is a logical unit to control your hardware (or software). The device is the central object; most other GPU objects are created from it. Also see the convenience function wgpu.utils.get_default_device(). Information on the adapter can be obtained using wgpu.GPUAdapter.info (a dict similar to GPUAdapterInfo) or wgpu.GPUAdapter.summary.

A device is controlled with a specific backend API. By default one is selected automatically. This can be overridden by setting the WGPU_BACKEND_TYPE environment variable to “Vulkan”, “Metal”, “D3D12”, or “OpenGL”.

The device and all objects created from it inherit from GPUObjectBase - they represent something on the GPU.

In most render use-cases you want the result to be presented to a canvas on the screen. The GPUCanvasContext is the bridge between wgpu and the underlying GUI backend.

Buffers and textures

A GPUBuffer can be created from a device. It is used to hold data, that can be uploaded using it’s API. From the shader’s point of view, the buffer can be accessed as a typed array.

A GPUTexture is similar to a buffer, but has some image-specific features. A texture can be 1D, 2D or 3D, can have multiple levels of detail (i.e. lod or mipmaps). The texture itself represents the raw data, you can create one or more GPUTextureView objects for it, that can be attached to a shader.

To let a shader sample from a texture, you also need a GPUSampler that defines the filtering and sampling behavior beyond the edges.

Bind groups

Shaders need access to resources like buffers, texture views, and samplers. The access to these resources occurs via so called bindings. There are integer slots, which must be specifie both via the API, and in the shader.

Bindings are organized into GPUBindGroup s, which are essentially a list of GPUBinding s.

Further, in wgpu you need to specify a GPUBindGroupLayout, providing meta-information about the binding (type, texture dimension etc.).

Multiple bind groups layouts are collected in a GPUPipelineLayout, which represents a complete layout description for a pipeline.

Shaders and pipelines

The wgpu API knows three kinds of shaders: compute, vertex and fragment. Pipelines define how the shader is run, and with what resources.

Shaders are represented by a GPUShaderModule.

Compute shaders are combined with a pipelinelayout into a GPUComputePipeline. Similarly, a vertex and (optional) fragment shader are combined with a pipelinelayout into a GPURenderPipeline. Both of these inherit from GPUPipelineBase.

Command buffers and encoders

The actual rendering occurs by recording a series of commands and then submitting these commands.

The root object to generate commands with is the GPUCommandEncoder. This class inherits from GPUCommandsMixin (because it generates commands), and GPUDebugCommandsMixin (because it supports debugging).

Commands specific to compute and rendering are generated with a GPUComputePassEncoder and GPURenderPassEncoder respectively. You get these from the command encoder by the corresponding begin_x_pass() method. These pass encoders inherit from GPUBindingCommandsMixin (because you associate a pipeline) and the latter also from GPURenderCommandsMixin.

When you’re done generating commands, you call finish() and get the list of commands as an opaque object: the GPUCommandBuffer. You don’t really use this object except for submitting it to the GPUQueue.

The command buffers are one-time use. The GPURenderBundle and GPURenderBundleEncoder can be used to record commands to be used multiple times, but this is not yet implemented in wgpu-py.

Error handling

Errors in wgpu-native are raised as Python errors where possible. Uncaught errors and warnings are logged using the wgpu logger.

There are specific exceptions that can be raised: * GPUError is the generic (base) error class. * GPUValidationError is for wgpu validation errors. Shader errors also fall into this category. * GPUOutOfMemoryError is a wgpu MemoryError. * GPUInternalError when wgpu reaches a internal error state. * GPUPipelineError for errors related to the pipeline. * GPUDeviceLostInfo when the device is lost.

TODO

These classes are not supported and/or documented yet. GPUCompilationMessage GPUCompilationInfo GPUQuerySet

List of flags, enums, and structs

• Flags
  • BufferUsage
  • ColorWrite
  • MapMode
  • ShaderStage
  • TextureUsage
• Enums
  • AddressMode
  • AutoLayoutMode
  • BlendFactor
  • BlendOperation
  • BufferBindingType
  • BufferMapState
  • CanvasAlphaMode
  • CanvasToneMappingMode
  • CompareFunction
  • CompilationMessageType
  • CullMode
  • DeviceLostReason
  • ErrorFilter
  • FeatureName
  • FilterMode
  • FrontFace
  • IndexFormat
  • LoadOp
  • MipmapFilterMode
  • PipelineErrorReason
  • PowerPreference
  • PrimitiveTopology
  • QueryType
  • SamplerBindingType
  • StencilOperation
  • StorageTextureAccess
  • StoreOp
  • TextureAspect
  • TextureDimension
  • TextureFormat
  • TextureSampleType
  • TextureViewDimension
  • VertexFormat
  • VertexStepMode
• Structs
  • BindGroupDescriptor
  • BindGroupEntry
  • BindGroupLayoutDescriptor
  • BindGroupLayoutEntry
  • BlendComponent
  • BlendState
  • BufferBinding
  • BufferBindingLayout
  • BufferDescriptor
  • CanvasConfiguration
  • CanvasToneMapping
  • Color
  • ColorTargetState
  • CommandBufferDescriptor
  • CommandEncoderDescriptor
  • ComputePassDescriptor
  • ComputePassTimestampWrites
  • ComputePipelineDescriptor
  • CopyExternalImageDestInfo
  • CopyExternalImageSourceInfo
  • DepthStencilState
  • DeviceDescriptor
  • Extent3D
  • ExternalTextureDescriptor
  • FragmentState
  • MultisampleState
  • Origin2D
  • Origin3D
  • PipelineErrorInit
  • PipelineLayoutDescriptor
  • PrimitiveState
  • ProgrammableStage
  • QuerySetDescriptor
  • QueueDescriptor
  • RenderBundleDescriptor
  • RenderBundleEncoderDescriptor
  • RenderPassColorAttachment
  • RenderPassDepthStencilAttachment
  • RenderPassDescriptor
  • RenderPassLayout
  • RenderPassTimestampWrites
  • RenderPipelineDescriptor
  • RequestAdapterOptions
  • SamplerBindingLayout
  • SamplerDescriptor
  • ShaderModuleCompilationHint
  • ShaderModuleDescriptor
  • StencilFaceState
  • StorageTextureBindingLayout
  • TexelCopyBufferInfo
  • TexelCopyBufferLayout
  • TexelCopyTextureInfo
  • TextureBindingLayout
  • TextureDescriptor
  • TextureViewDescriptor
  • UncapturedErrorEventInit
  • VertexAttribute
  • VertexBufferLayout
  • VertexState

List of GPU classes

The classes that make up the wgpu API. These can be accessed via wgpu.classes, but are also available in the root wgpu namespace.

GPU	GPU()
GPUAdapterInfo	GPUAdapterInfo()
GPUAdapter	GPUAdapter()
GPUBindGroup	GPUBindGroup()
GPUBindGroupLayout	GPUBindGroupLayout()
GPUBindingCommandsMixin	GPUBindingCommandsMixin()
GPUBuffer	GPUBuffer()
GPUCanvasContext	GPUCanvasContext()
GPUCommandBuffer	GPUCommandBuffer()
GPUCommandEncoder	GPUCommandEncoder()
GPUCommandsMixin	GPUCommandsMixin()
GPUCompilationInfo	GPUCompilationInfo()
GPUCompilationMessage	GPUCompilationMessage()
GPUComputePassEncoder	GPUComputePassEncoder()
GPUComputePipeline	GPUComputePipeline()
GPUDebugCommandsMixin	GPUDebugCommandsMixin()
GPUDevice	GPUDevice()
GPUDeviceLostInfo	GPUDeviceLostInfo()
GPUError	GPUError()
GPUInternalError	GPUInternalError()
GPUObjectBase	GPUObjectBase()
GPUOutOfMemoryError	GPUOutOfMemoryError()
GPUPipelineBase	GPUPipelineBase()
GPUPipelineError	GPUPipelineError()
GPUPipelineLayout	GPUPipelineLayout()
GPUQuerySet	GPUQuerySet()
GPUQueue	GPUQueue()
GPURenderBundle	GPURenderBundle()
GPURenderBundleEncoder	GPURenderBundleEncoder()
GPURenderCommandsMixin	GPURenderCommandsMixin()
GPURenderPassEncoder	GPURenderPassEncoder()
GPURenderPipeline	GPURenderPipeline()
GPUSampler	GPUSampler()
GPUShaderModule	GPUShaderModule()
GPUTexture	GPUTexture()
GPUTextureView	GPUTextureView()
GPUValidationError	GPUValidationError()