WGPU classes¶
Adapter and device¶
-
class
wgpu.
GPU
¶ Class that represents the root namespace of the API.
-
wgpu.
request_adapter
(**parameters)¶ Get a
GPUAdapter
, the object that represents an abstract wgpu implementation, from which one can request aGPUDevice
.Parameters: - canvas (WgpuCanvasInterface) – The canvas that the adapter should be able to render to (to create a swap chain for, to be precise). Can be None if you’re not rendering to screen (or if you’re confident that the returned adapter will work just fine).
- powerPreference (PowerPreference) – “high-performance” or “low-power”
-
wgpu.
request_adapter_async
(**parameters)¶ Async version of
request_adapter()
.
-
class
wgpu.
GPUAdapter
¶ An adapter represents both an instance of a hardware accelerator (e.g. GPU or CPU) and an implementation of WGPU on top of that accelerator. If an adapter becomes unavailable, it becomes invalid. Once invalid, it never becomes valid again.
-
features
¶ A tuple of supported feature names.
-
is_fallback_adapter
¶ Whether this adapter runs on software (rather than dedicated hardware).
-
limits
¶ A dict with the adapter limits.
-
name
¶ A human-readable name identifying the adapter.
-
properties
¶ A dict with the adapter properties (info on device, backend, etc.)
-
request_device
(**parameters)¶ Request a
GPUDevice
from the adapter.Parameters: - label (str) – A human readable label. Optional.
- required_features (list of str) – the features (extensions) that you need. Default [].
- required_limits (dict) – the various limits that you need. Default {}.
- default_queue (dict, optional) – Descriptor for the default queue.
-
request_device_async
(**parameters)¶ Async version of
request_device()
.
-
-
class
wgpu.
GPUObjectBase
¶ The base class for all GPU objects (the device and all objects belonging to a device).
-
label
¶ A human-readable name identifying the GPU object.
-
-
class
wgpu.
GPUDevice
¶ Subclass of
GPUObjectBase
A device is the logical instantiation of an adapter, through which internal objects are created. It can be shared across threads. A device is the exclusive owner of all internal objects created from it: when the device is lost, all objects created from it become invalid.
Create a device using
GPUAdapter.request_device()
orGPUAdapter.request_device_async()
.-
adapter
¶ The adapter object corresponding to this device.
-
create_bind_group
(**parameters)¶ Create a
GPUBindGroup
object, which can be used inpass.set_bind_group()
to attach a group of resources.Parameters: - label (str) – A human readable label. Optional.
- layout (GPUBindGroupLayout) – The layout (abstract representation) for this bind group.
- entries (list of dict) – A list of dicts, see below.
Example entry dicts:
# For a sampler { "binding" : 0, # slot "resource": a_sampler, } # For a texture view { "binding" : 0, # slot "resource": a_texture_view, } # For a buffer { "binding" : 0, # slot "resource": { "buffer": a_buffer, "offset": 0, "size": 812, } }
-
create_bind_group_layout
(**parameters)¶ Create a
GPUBindGroupLayout
object. One or more such objects are passed tocreate_pipeline_layout()
to specify the (abstract) pipeline layout for resources. See the docs on bind groups for details.Parameters: - label (str) – A human readable label. Optional.
- entries (list of dict) – A list of layout entry dicts.
Example entry dict:
# Buffer { "binding": 0, "visibility": wgpu.ShaderStage.COMPUTE, "buffer": { "type": wgpu.BufferBindingType.storage_buffer, "has_dynamic_offset": False, # optional "min_binding_size": 0 # optional } }, # Sampler { "binding": 1, "visibility": wgpu.ShaderStage.COMPUTE, "sampler": { "type": wgpu.SamplerBindingType.filtering, } }, # Sampled texture { "binding": 2, "visibility": wgpu.ShaderStage.FRAGMENT, "texture": { "sample_type": wgpu.TextureSampleType.float, # optional "view_dimension": wgpu.TextureViewDimension.d2, # optional "multisampled": False, # optional } }, # Storage texture { "binding": 3, "visibility": wgpu.ShaderStage.FRAGMENT, "storage_texture": { "access": wgpu.StorageTextureAccess.read_only, "format": wgpu.TextureFormat.r32float, "view_dimension": wgpu.TextureViewDimension.d2, } },
About
has_dynamic_offset
: For uniform-buffer, storage-buffer, and readonly-storage-buffer bindings, it indicates whether the binding has a dynamic offset. One offset must be passed toset_bind_group
for each dynamic binding in increasing order of binding number.
-
create_buffer
(**parameters)¶ Create a
GPUBuffer
object.Parameters: - label (str) – A human readable label. Optional.
- size (int) – The size of the buffer in bytes.
- usage (BufferUsageFlags) – The ways in which this buffer will be used.
- mapped_at_creation (bool) – Must be False, use create_buffer_with_data() instead.
-
create_buffer_with_data
(**parameters)¶ Create a
GPUBuffer
object initialized with the given data.Parameters: - label (str) – A human readable label. Optional.
- data – Any object supporting the Python buffer protocol (this includes bytes, bytearray, ctypes arrays, numpy arrays, etc.).
- usage (BufferUsageFlags) – The ways in which this buffer will be used.
Also see
GPUQueue.write_buffer()
andGPUQueue.read_buffer()
.
-
create_command_encoder
(**parameters)¶ Create a
GPUCommandEncoder
object. A command encoder is used to record commands, which can then be submitted at once to the GPU.Parameters: label (str) – A human readable label. Optional.
-
create_compute_pipeline
(**parameters)¶ Create a
GPUComputePipeline
object.Parameters: - label (str) – A human readable label. Optional.
- layout (GPUPipelineLayout) – object created with
create_pipeline_layout()
. - compute (dict) – E.g.
{"module": shader_module, entry_point="main"}
.
-
create_compute_pipeline_async
(**parameters)¶ Async version of create_compute_pipeline().
-
create_pipeline_layout
(**parameters)¶ Create a
GPUPipelineLayout
object, which can be used increate_render_pipeline()
orcreate_compute_pipeline()
.Parameters: - label (str) – A human readable label. Optional.
- bind_group_layouts (list) – A list of
GPUBindGroupLayout
objects.
-
create_query_set
(**parameters)¶ Create a
GPUQuerySet
object.
-
create_render_bundle_encoder
(**parameters)¶ Create a
GPURenderBundle
object.TODO: not yet available in wgpu-native
-
create_render_pipeline
(**parameters)¶ Create a
GPURenderPipeline
object.Parameters: - label (str) – A human readable label. Optional.
- layout (GPUPipelineLayout) – A layout created with
create_pipeline_layout()
. - vertex (VertexState) – Describes the vertex shader entry point of the pipeline and its input buffer layouts.
- primitive (PrimitiveState) – Describes the the primitive-related properties of the pipeline. If strip_index_format is present (which means the primitive topology is a strip), and the drawCall is indexed, the vertex index list is split into sub-lists using the maximum value of this index format as a separator. Example: a list with values [1, 2, 65535, 4, 5, 6] of type “uint16” will be split in sub-lists [1, 2] and [4, 5, 6].
- depth_stencil (DepthStencilState) – Describes the optional depth-stencil properties, including the testing, operations, and bias. Optional.
- multisample (MultisampleState) – Describes the multi-sampling properties of the pipeline.
- fragment (FragmentState) – Describes the fragment shader entry point of the pipeline and its output colors. If it’s None, the No Color Output mode is enabled: the pipeline does not produce any color attachment outputs. It still performs rasterization and produces depth values based on the vertex position output. The depth testing and stencil operations can still be used.
In the example dicts below, the values that are marked as optional, the shown value is the default.
Example vertex (VertexState) dict:
{ "module": shader_module, "entry_point": "main", "buffers": [ { "array_stride": 8, "step_mode": wgpu.VertexStepMode.vertex, # optional "attributes": [ { "format": wgpu.VertexFormat.float2, "offset": 0, "shader_location": 0, }, ... ], }, ... ] }
Example primitive (GPUPrimitiveState) dict:
{ "topology": wgpu.PrimitiveTopology.triangle_list, "strip_index_format": wgpu.IndexFormat.uint32, # see note "front_face": wgpu.FrontFace.ccw, # optional "cull_mode": wgpu.CullMode.none, # optional }
Example depth_stencil (GPUDepthStencilState) dict:
{ "format": wgpu.TextureFormat.depth24plus_stencil8, "depth_write_enabled": False, # optional "depth_compare": wgpu.CompareFunction.always, # optional "stencil_front": { # optional "compare": wgpu.CompareFunction.equal, "fail_op": wgpu.StencilOperation.keep, "depth_fail_op": wgpu.StencilOperation.keep, "pass_op": wgpu.StencilOperation.keep, }, "stencil_back": { # optional "compare": wgpu.CompareFunction.equal, "fail_op": wgpu.StencilOperation.keep, "depth_fail_op": wgpu.StencilOperation.keep, "pass_op": wgpu.StencilOperation.keep, }, "stencil_read_mask": 0xFFFFFFFF, # optional "stencil_write_mask": 0xFFFFFFFF, # optional "depth_bias": 0, # optional "depth_bias_slope_scale": 0.0, # optional "depth_bias_clamp": 0.0, # optional }
Example multisample (MultisampleState) dict:
{ "count": 1, # optional "mask": 0xFFFFFFFF, # optional "alpha_to_coverage_enabled": False # optional }
Example fragment (FragmentState) dict. The blend parameter can be None to disable blending (not all texture formats support blending).
{ "module": shader_module, "entry_point": "main", "targets": [ { "format": wgpu.TextureFormat.bgra8unorm_srgb, "blend": { "color": ( wgpu.BlendFactor.One, wgpu.BlendFactor.zero, gpu.BlendOperation.add, ), "alpha": ( wgpu.BlendFactor.One, wgpu.BlendFactor.zero, wgpu.BlendOperation.add, ), } "write_mask": wgpu.ColorWrite.ALL # optional }, ... ] }
-
create_render_pipeline_async
(**parameters)¶ Async version of create_render_pipeline().
-
create_sampler
(**parameters)¶ Create a
GPUSampler
object. Samplers specify how a texture is sampled.Parameters: - label (str) – A human readable label. Optional.
- address_mode_u (AddressMode) – What happens when sampling beyond the x edge. Default “clamp-to-edge”.
- address_mode_v (AddressMode) – What happens when sampling beyond the y edge. Default “clamp-to-edge”.
- address_mode_w (AddressMode) – What happens when sampling beyond the z edge. Default “clamp-to-edge”.
- mag_filter (FilterMode) – Interpolation when zoomed in. Default ‘nearest’.
- min_filter (FilterMode) – Interpolation when zoomed out. Default ‘nearest’.
- mipmap_filter – (MipmapFilterMode): Interpolation between mip levels. Default ‘nearest’.
- lod_min_clamp (float) – The minimum level of detail. Default 0.
- lod_max_clamp (float) – The maxium level of detail. Default 32.
- compare (CompareFunction) – The sample compare operation for depth textures. Only specify this for depth textures. Default None.
- max_anisotropy (int) – The maximum anisotropy value clamp used by the sample, betweet 1 and 16, default 1.
-
create_shader_module
(**parameters)¶ Create a
GPUShaderModule
object from shader source.Parameters: - label (str) – A human readable label. Optional.
- code (str | bytes) – The shader code, as WGSL text or binary SpirV
(or an object implementing
to_spirv()
orto_bytes()
). - hints – unused.
-
create_texture
(**parameters)¶ Create a
GPUTexture
object.Parameters: - label (str) – A human readable label. Optional.
- size (tuple or dict) – The texture size as a 3-tuple or a dict (width, height, depth_or_array_layers).
- mip_level_count (int) – The number of mip leveles. Default 1.
- sample_count (int) – The number of samples. Default 1.
- dimension (TextureDimension) – The dimensionality of the texture. Default 2d.
- format (TextureFormat) – What channels it stores and how.
- usage (TextureUsageFlags) – The ways in which the texture will be used.
- view_formats (optional) – A list of formats that views are allowed to have in addition to the texture’s own view. Using these formats may have a performance penalty.
See https://gpuweb.github.io/gpuweb/#texture-format-caps for a list of available texture formats. Note that less formats are available for storage usage.
-
destroy
()¶ Destroy this device.
-
features
¶ A tuple of strings representing the features (i.e. extensions) with which this device was created.
-
limits
¶ A dict exposing the limits with which this device was created.
-
lost
¶ Provides information about why the device is lost.
-
onuncapturederror
¶ Method called when an error is capured?
-
Buffers and textures¶
-
class
wgpu.
GPUBuffer
¶ Subclass of
GPUObjectBase
A GPUBuffer represents a block of memory that can be used in GPU operations. Data is stored in linear layout, meaning that each byte of the allocation can be addressed by its offset from the start of the buffer, subject to alignment restrictions depending on the operation.
Create a buffer using
GPUDevice.create_buffer()
,GPUDevice.create_buffer_mapped()
orGPUDevice.create_buffer_mapped_async()
.One can sync data in a buffer by mapping it (or by creating a mapped buffer) and then setting/getting the values in the mapped memoryview. Alternatively, one can tell the GPU (via the command encoder) to copy data between buffers and textures.
-
destroy
()¶ An application that no longer requires a buffer can choose to destroy it. Note that this is automatically called when the Python object is cleaned up by the garbadge collector.
-
map_read
()¶ Map the buffer and read the data from it, then unmap. Return a memoryview object. Requires the buffer usage to include MAP_READ.
See queue.read_buffer() for a simpler alternative.
-
map_write
(data)¶ Map the buffer and write the data to it, then unmap. Return a memoryview object. Requires the buffer usage to include MAP_WRITE.
See queue.write_buffer() for a simpler alternative.
-
size
¶ The length of the GPUBuffer allocation in bytes.
-
usage
¶ The allowed usages (int bitmap) for this GPUBuffer, specifying e.g. whether the buffer may be used as a vertex buffer, uniform buffer, target or source for copying data, etc.
-
-
class
wgpu.
GPUTexture
¶ Subclass of
GPUObjectBase
A texture represents a 1D, 2D or 3D color image object. It also can have mipmaps (different levels of varying detail), and arrays. The texture represents the “raw” data. A
GPUTextureView
is used to define how the texture data should be interpreted.Create a texture using
GPUDevice.create_texture()
.-
create_view
(**parameters)¶ Create a
GPUTextureView
object.If no aguments are given, a default view is given, with the same format and dimension as the texture.
Parameters: - label (str) – A human readable label. Optional.
- format (TextureFormat) – What channels it stores and how.
- dimension (TextureViewDimension) – The dimensionality of the texture view.
- aspect (TextureAspect) – Whether this view is used for depth, stencil, or all. Default all.
- base_mip_level (int) – The starting mip level. Default 0.
- mip_level_count (int) – The number of mip levels. Default None.
- base_array_layer (int) – The starting array layer. Default 0.
- array_layer_count (int) – The number of array layers. Default None.
-
destroy
()¶ An application that no longer requires a texture can choose to destroy it. Note that this is automatically called when the Python object is cleaned up by the garbadge collector.
-
dimension
¶ The dimension of the texture.
-
format
¶ The format of the texture.
-
mip_level_count
¶ The total number of the mipmap levels of the texture.
-
sample_count
¶ The number of samples in each texel of the texture.
-
size
¶ The size of the texture in mipmap level 0, as a 3-tuple of ints.
-
usage
¶ The allowed usages for this texture.
-
-
class
wgpu.
GPUTextureView
¶ Subclass of
GPUObjectBase
A texture view represents a way to represent a
GPUTexture
.Create a texture view using
GPUTexture.create_view()
.-
size
¶ The texture size (as a 3-tuple).
-
texture
¶ The texture object to which this is a view.
-
-
class
wgpu.
GPUSampler
¶ Subclass of
GPUObjectBase
A sampler specifies how a texture (view) must be sampled by the shader, in terms of subsampling, sampling between mip levels, and sampling out of the image boundaries.
Create a sampler using
GPUDevice.create_sampler()
.
Bind groups¶
-
class
wgpu.
GPUBindGroupLayout
¶ Subclass of
GPUObjectBase
A bind group layout defines the interface between a set of resources bound in a
GPUBindGroup
and their accessibility in shader stages.Create a bind group layout using
GPUDevice.create_bind_group_layout()
.
-
class
wgpu.
GPUBindGroup
¶ Subclass of
GPUObjectBase
A bind group represents a group of bindings, the shader slot, and a resource (sampler, texture-view, buffer).
Create a bind group using
GPUDevice.create_bind_group()
.
-
class
wgpu.
GPUPipelineLayout
¶ Subclass of
GPUObjectBase
A pipeline layout describes the layout of a pipeline, as a list of
GPUBindGroupLayout
objects.Create a pipeline layout using
GPUDevice.create_pipeline_layout()
.
Shaders and pipelines¶
-
class
wgpu.
GPUShaderModule
¶ Subclass of
GPUObjectBase
A shader module represents a programmable shader.
Create a shader module using
GPUDevice.create_shader_module()
.-
compilation_info
()¶ Get shader compilation info. Always returns empty string at the moment.
-
compilation_info_async
()¶ Async version of compilation_info()
-
-
class
wgpu.
GPUPipelineBase
¶ A mixin class for render and compute pipelines.
-
get_bind_group_layout
(index)¶ Get the bind group layout at the given index.
-
-
class
wgpu.
GPUComputePipeline
¶ Subclass of
GPUPipelineBase
,GPUObjectBase
A compute pipeline represents a single pipeline for computations (no rendering).
Create a compute pipeline using
GPUDevice.create_compute_pipeline()
.
-
class
wgpu.
GPURenderPipeline
¶ Subclass of
GPUPipelineBase
,GPUObjectBase
A render pipeline represents a single pipeline to draw something using a vertex and a fragment shader. The render target can come from a window on the screen or from an in-memory texture (off-screen rendering).
Create a render pipeline using
GPUDevice.create_render_pipeline()
.
Command buffers and encoders¶
-
class
wgpu.
GPUCommandBuffer
¶ Subclass of
GPUObjectBase
A command buffer stores a series of commands, generated by a
GPUCommandEncoder
, to be submitted to aGPUQueue
.Create a command buffer using
GPUCommandEncoder.finish()
.Command buffers are single use, you must only submit them once and submitting them destroys them. Use render bundles to re-use commands.
-
class
wgpu.
GPUCommandsMixin
¶ Mixin for classes that encode commands.
-
class
wgpu.
GPUBindingCommandsMixin
¶ Mixin for classes that defines bindings.
-
set_bind_group
(index, bind_group, dynamic_offsets_data, dynamic_offsets_data_start, dynamic_offsets_data_length)¶ Associate the given bind group (i.e. group or resources) with the given slot/index.
Parameters: - index (int) – The slot to bind at.
- bind_group (GPUBindGroup) – The bind group to bind.
- dynamic_offsets_data (list of int) – A list of offsets (one for each bind group).
- dynamic_offsets_data_start (int) – Not used.
- dynamic_offsets_data_length (int) – Not used.
-
-
class
wgpu.
GPUDebugCommandsMixin
¶ Mixin for classes that support debug groups and markers.
-
insert_debug_marker
(marker_label)¶ Insert the given message into the debug message queue.
-
pop_debug_group
()¶ Pop the active debug group.
-
push_debug_group
(group_label)¶ Push a named debug group into the command stream.
-
-
class
wgpu.
GPURenderCommandsMixin
¶ Mixin for classes that provide rendering commands.
-
draw
(vertex_count, instance_count=1, first_vertex=0, first_instance=0)¶ Run the render pipeline without an index buffer.
Parameters: - vertex_count (int) – The number of vertices to draw.
- instance_count (int) – The number of instances to draw. Default 1.
- first_vertex (int) – The vertex offset. Default 0.
- first_instance (int) – The instance offset. Default 0.
-
draw_indexed
(index_count, instance_count=1, first_index=0, base_vertex=0, first_instance=0)¶ Run the render pipeline using an index buffer.
Parameters: - index_count (int) – The number of indices to draw.
- instance_count (int) – The number of instances to draw. Default 1.
- first_index (int) – The index offset. Default 0.
- base_vertex (int) – A number added to each index in the index buffer. Default 0.
- first_instance (int) – The instance offset. Default 0.
-
draw_indexed_indirect
(indirect_buffer, indirect_offset)¶ Like
draw_indexed()
, but the function arguments are in a buffer.Parameters: - indirect_buffer (GPUBuffer) – The buffer that contains the arguments.
- indirect_offset (int) – The byte offset at which the arguments are.
-
draw_indirect
(indirect_buffer, indirect_offset)¶ Like
draw()
, but the function arguments are in a buffer.Parameters: - indirect_buffer (GPUBuffer) – The buffer that contains the arguments.
- indirect_offset (int) – The byte offset at which the arguments are.
-
set_index_buffer
(buffer, index_format, offset=0, size=None)¶ Set the index buffer for this render pass.
Parameters: - buffer (GPUBuffer) – The buffer that contains the indices.
- index_format (GPUIndexFormat) – The format of the index data contained in buffer. If strip_index_format is given in the call to create_render_pipeline(), it must match.
- offset (int) – The byte offset in the buffer. Default 0.
- size (int) – The number of bytes to use. If zero, the remaining size (after offset) of the buffer is used. Default 0.
-
set_pipeline
(pipeline)¶ Set the pipeline for this render pass.
Parameters: pipeline (GPURenderPipeline) – The pipeline to use.
-
set_vertex_buffer
(slot, buffer, offset=0, size=None)¶ Associate a vertex buffer with a bind slot.
Parameters: - slot (int) – The binding slot for the vertex buffer.
- buffer (GPUBuffer) – The buffer that contains the vertex data.
- offset (int) – The byte offset in the buffer. Default 0.
- size (int) – The number of bytes to use. If zero, the remaining size (after offset) of the buffer is used. Default 0.
-
-
class
wgpu.
GPUCommandEncoder
¶ Subclass of
GPUCommandsMixin
,GPUDebugCommandsMixin
,GPUObjectBase
A command encoder is used to record a series of commands. When done, call
finish()
to obtain a GPUCommandBuffer object.Create a command encoder using
GPUDevice.create_command_encoder()
.-
begin_compute_pass
(**parameters)¶ Record the beginning of a compute pass. Returns a
GPUComputePassEncoder
object.Parameters: - label (str) – A human readable label. Optional.
- timestamp_writes – unused
-
begin_render_pass
(**parameters)¶ Record the beginning of a render pass. Returns a
GPURenderPassEncoder
object.Parameters: - label (str) – A human readable label. Optional.
- color_attachments (list of dict) – List of color attachment dicts. See below.
- depth_stencil_attachment (dict) – A depth stencil attachment dict. See below. Default None.
- occlusion_query_set – Default None. TODO NOT IMPLEMENTED in wgpu-native.
- timestamp_writes – unused
Example color attachment:
{ "view": texture_view, "resolve_target": None, # optional "load_value": (0, 0, 0, 0), # LoadOp.load or a color "store_op": wgpu.StoreOp.store, # optional }
Example depth stencil attachment:
{ "view": texture_view, "depth_load_value": 0.0, "depth_store_op": wgpu.StoreOp.store, "stencil_load_value": wgpu.LoadOp.load, "stencil_store_op": wgpu.StoreOp.store, }
-
clear_buffer
(buffer, offset=0, size=None)¶ Set (part of) the given buffer to zeros.
-
copy_buffer_to_buffer
(source, source_offset, destination, destination_offset, size)¶ Copy the contents of a buffer to another buffer.
Parameters:
-
copy_buffer_to_texture
(source, destination, copy_size)¶ Copy the contents of a buffer to a texture (view).
Parameters: - source (GPUBuffer) – A dict with fields: buffer, offset, bytes_per_row, rows_per_image.
- destination (GPUTexture) – A dict with fields: texture, mip_level, origin.
- copy_size (int) – The number of bytes to copy.
Note that the bytes_per_row must be a multiple of 256.
-
copy_texture_to_buffer
(source, destination, copy_size)¶ Copy the contents of a texture (view) to a buffer.
Parameters: - source (GPUTexture) – A dict with fields: texture, mip_level, origin.
- destination (GPUBuffer) – A dict with fields: buffer, offset, bytes_per_row, rows_per_image.
- copy_size (int) – The number of bytes to copy.
Note that the bytes_per_row must be a multiple of 256.
-
copy_texture_to_texture
(source, destination, copy_size)¶ Copy the contents of a texture (view) to another texture (view).
Parameters: - source (GPUTexture) – A dict with fields: texture, mip_level, origin.
- destination (GPUTexture) – A dict with fields: texture, mip_level, origin.
- copy_size (int) – The number of bytes to copy.
-
finish
(**parameters)¶ Finish recording. Returns a
GPUCommandBuffer
to submit to aGPUQueue
.Parameters: label (str) – A human readable label. Optional.
-
resolve_query_set
(query_set, first_query, query_count, destination, destination_offset)¶ TODO
-
write_timestamp
(query_set, query_index)¶ TODO
-
-
class
wgpu.
GPUComputePassEncoder
¶ Subclass of
GPUCommandsMixin
,GPUDebugCommandsMixin
,GPUBindingCommandsMixin
,GPUObjectBase
A compute-pass encoder records commands related to a compute pass.
Create a compute pass encoder using
GPUCommandEncoder.begin_compute_pass()
.-
dispatch_workgroups
(workgroup_count_x, workgroup_count_y=1, workgroup_count_z=1)¶ Run the compute shader.
Parameters: - x (int) – The number of cycles in index x.
- y (int) – The number of cycles in index y. Default 1.
- z (int) – The number of cycles in index z. Default 1.
-
dispatch_workgroups_indirect
(indirect_buffer, indirect_offset)¶ Like
dispatch_workgroups()
, but the function arguments are in a buffer.Parameters: - indirect_buffer (GPUBuffer) – The buffer that contains the arguments.
- indirect_offset (int) – The byte offset at which the arguments are.
-
end
()¶ Record the end of the compute pass.
-
set_pipeline
(pipeline)¶ Set the pipeline for this compute pass.
Parameters: pipeline (GPUComputePipeline) – The pipeline to use.
-
-
class
wgpu.
GPURenderPassEncoder
¶ Subclass of
GPUCommandsMixin
,GPUDebugCommandsMixin
,GPUBindingCommandsMixin
,GPURenderCommandsMixin
,GPUObjectBase
A render-pass encoder records commands related to a render pass.
Create a render pass encoder using
GPUCommandEncoder.begin_render_pass()
.-
begin_occlusion_query
(query_index)¶ TODO
-
end
()¶ Record the end of the render pass.
-
end_occlusion_query
()¶ TODO
-
execute_bundles
(bundles)¶ TODO: not yet available in wgpu-native
-
set_blend_constant
(color)¶ Set the blend color for the render pass.
Parameters: color (tuple or dict) – A color with fields (r, g, b, a).
-
set_scissor_rect
(x, y, width, height)¶ Set the scissor rectangle for this render pass. The scene is rendered as usual, but is only applied to this sub-rectangle.
Parameters: - x (int) – Horizontal coordinate.
- y (int) – Vertical coordinate.
- width (int) – Horizontal size.
- height (int) – Vertical size.
-
set_stencil_reference
(reference)¶ Set the reference stencil value for this render pass.
Parameters: reference (int) – The reference value.
-
set_viewport
(x, y, width, height, min_depth, max_depth)¶ Set the viewport for this render pass. The whole scene is rendered to this sub-rectangle.
Parameters: - x (int) – Horizontal coordinate.
- y (int) – Vertical coordinate.
- width (int) – Horizontal size.
- height (int) – Vertical size.
- min_depth (int) – Clipping in depth.
- max_depth (int) – Clipping in depth.
-
-
class
wgpu.
GPURenderBundle
¶ Subclass of
GPUObjectBase
TODO: not yet available in wgpu-native
-
class
wgpu.
GPURenderBundleEncoder
¶ Subclass of
GPUCommandsMixin
,GPUDebugCommandsMixin
,GPUBindingCommandsMixin
,GPURenderCommandsMixin
,GPUObjectBase
TODO: not yet available in wgpu-native
-
finish
(**parameters)¶ Finish recording and return a
GPURenderBundle
.Parameters: label (str) – A human readable label. Optional.
-
Other¶
-
class
wgpu.
GPUCanvasContext
¶ A context object associated with a canvas, to present what has been drawn.
-
canvas
¶ The associated canvas object.
-
configure
(**parameters)¶ Configures the presentation context for the associated canvas. Destroys any textures produced with a previous configuration.
Parameters: - device (WgpuDevice) – The GPU device object.
- format (TextureFormat) – The texture format, e.g. “bgra8unorm-srgb”. Default uses the preferred_format.
- usage (TextureUsage) – Default
TextureUsage.OUTPUT_ATTACHMENT
. - color_space (PredefinedColorSpace) – Default “srgb”.
- compositing_alpha_mode (CanvasCompositingAlphaMode) – Default opaque.
- size – The 3D size of the texture to draw to. Default use canvas’ physical size.
-
get_current_texture
()¶ Get the
GPUTexture
that will be composited to the canvas by the context next.NOTE: for the time being, this could return a
GPUTextureView
instead.
-
get_preferred_format
(adapter)¶ Get the preferred swap chain format.
-
present
()¶ Present what has been drawn to the current texture, by compositing it to the canvas. Note that a canvas based on
WgpuCanvasBase
will call this method automatically at the end of each draw event.
-
unconfigure
()¶ Removes the presentation context configuration. Destroys any textures produced while configured.
-
-
class
wgpu.
GPUQueue
¶ Subclass of
GPUObjectBase
A queue can be used to submit command buffers to.
You can obtain a queue object via the
GPUDevice.default_queue
property.-
on_submitted_work_done
()¶ TODO
-
read_buffer
(buffer, buffer_offset=0, size=None)¶ Takes the data contents of the buffer and return them as a memoryview.
Parameters: - buffer – The
GPUBuffer
object to read from. - buffer_offset (int) – The offset in the buffer to start reading from.
- size – The number of bytes to read. Default all minus offset.
This copies the data in the given buffer to a temporary buffer and then maps that buffer to read the data. The given buffer’s usage must include COPY_SRC.
Also see
GPUBuffer.map_read()
.- buffer – The
-
read_texture
(source, data_layout, size)¶ Reads the contents of the texture and return them as a memoryview.
Parameters: - source – A dict with fields: “texture” (a texture object), “origin” (a 3-tuple), “mip_level” (an int, default 0).
- data_layout – A dict with fields: “offset” (an int, default 0), “bytes_per_row” (an int), “rows_per_image” (an int, default 0).
- size – A 3-tuple of ints specifying the size to write.
Unlike
GPUCommandEncoder.copyBufferToTexture()
, there is no alignment requirement on bytes_per_row, although in the current implementation there will be a performance penalty ifbytes_per_row
is not a multiple of 256 (because we’ll be copying data row-by-row in Python).
-
submit
(command_buffers)¶ Submit a
GPUCommandBuffer
to the queue.Parameters: command_buffers (list) – The GPUCommandBuffer
objects to add.
-
write_buffer
(buffer, buffer_offset, data, data_offset=0, size=None)¶ Takes the data contents and schedules a write operation of these contents to the buffer. A snapshot of the data is taken; any changes to the data after this function is called do not affect the buffer contents.
Parameters: - buffer – The
GPUBuffer
object to write to. - buffer_offset (int) – The offset in the buffer to start writing at.
- data – The data to write. Must be contiguous.
- data_offset – The byte offset in the data. Default 0.
- size – The number of bytes to write. Default all minus offset.
This maps the data to a temporary buffer and then copies that buffer to the given buffer. The given buffer’s usage must include COPY_DST.
Also see
GPUDevice.create_buffer_with_data()
andGPUBuffer.map_write()
.- buffer – The
-
write_texture
(destination, data, data_layout, size)¶ Takes the data contents and schedules a write operation of these contents to the destination texture in the queue. A snapshot of the data is taken; any changes to the data after this function is called do not affect the texture contents.
Parameters: - destination – A dict with fields: “texture” (a texture object), “origin” (a 3-tuple), “mip_level” (an int, default 0).
- data – The data to write.
- data_layout – A dict with fields: “offset” (an int, default 0), “bytes_per_row” (an int), “rows_per_image” (an int, default 0).
- size – A 3-tuple of ints specifying the size to write.
Unlike
GPUCommandEncoder.copyBufferToTexture()
, there is no alignment requirement on bytes_per_row.
-
-
class
wgpu.
GPUQuerySet
¶ Subclass of
GPUObjectBase
TODO
-
destroy
()¶ Destroy the queryset.
-
-
class
wgpu.
GPUDeviceLostInfo
¶ An object that contains information about the device being lost.
-
message
¶ The error message specifying the reason for the device being lost.
-
reason
¶ The reason (enums.GPUDeviceLostReason) for the device getting lost. Can be None.
-
-
class
wgpu.
GPUOutOfMemoryError
¶ Subclass of
Exception
,BaseException
An error raised when the GPU is out of memory.
-
class
wgpu.
GPUValidationError
¶ Subclass of
Exception
,BaseException
An error raised when the pipeline could not be validated.
-
message
¶ The error message specifying the reason for invalidation.
-
-
class
wgpu.
GPUCompilationMessage
¶ An object that contains information about a problem with shader compilation.
-
length
¶ The length of the line?
-
line_num
¶ The corresponding line number in the shader source.
-
line_pos
¶ The position on the line in the shader source.
-
message
¶ The warning/error message.
-
offset
¶ Offset of …
-
type
¶ The type of warning/problem.
-
-
class
wgpu.
GPUExternalTexture
¶ Subclass of
GPUObjectBase
Ignore this - specific to browsers.
-
expired
¶ Whether the external texture has been destroyed.
-