GPUDevice

class wgpu.GPUDevice

Bases: GPUObjectBase

The top-level interface through which GPU objects are created.

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() or GPUAdapter.request_device_async().

property adapter

The adapter object corresponding to this device.

create_bind_group(**parameters)

Create a GPUBindGroup object, which can be used in pass.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) – A list of structs.BindGroupEntry dicts. The resource field is either GPUSampler, GPUTextureView or structs.BufferBinding.

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 to create_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) – A list of structs.BindGroupLayoutEntry dicts. Each contains either a structs.BufferBindingLayout, structs.SamplerBindingLayout, structs.TextureBindingLayout, or structs.StorageTextureBindingLayout.

Example with structs.BufferBindingLayout:

{
    "binding": 0,
    "visibility": wgpu.ShaderStage.COMPUTE,
    "buffer": {
        "type": wgpu.BufferBindingType.storage_buffer,
        "has_dynamic_offset": False,  # optional
        "min_binding_size": 0  # optional
    }
},

Note on 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 to pass.set_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 (flags.BufferUsage) – The ways in which this buffer will be used.

• mapped_at_creation (bool) – Whether the buffer is initially mapped.

create_buffer_with_data(**parameters)

Create a GPUBuffer object initialized with the given data.

This is a convenience function that creates a mapped buffer, writes the given data to it, and then unmaps the buffer.

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 (flags.BufferUsage) – The ways in which this buffer will be used.

Also see GPUBuffer.write_mapped() and GPUQueue.write_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 (structs.ProgrammableStage) – Binds shader module and entrypoint.

async create_compute_pipeline_async(**parameters)

Async version of create_compute_pipeline().

create_pipeline_layout(**parameters)

Create a GPUPipelineLayout object, which can be used in create_render_pipeline() or create_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) – The layout for the new pipeline.

• vertex (structs.VertexState) – Describes the vertex shader entry point of the pipeline and its input buffer layouts.

• primitive (structs.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 (structs.DepthStencilState) – Describes the optional depth-stencil properties, including the testing, operations, and bias. Optional.

• multisample (structs.MultisampleState) – Describes the multi-sampling properties of the pipeline.

• fragment (structs.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 (structs.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 (structs.PrimitiveState) 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 (structs.DepthStencilState) 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 (structs.MultisampleState) dict:

{
    "count": 1,  # optional
    "mask": 0xFFFFFFFF,  # optional
    "alpha_to_coverage_enabled": False  # optional
}

Example fragment (structs.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
        },
        ...
    ]
}

async 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 (enums.AddressMode) – What happens when sampling beyond the x edge. Default “clamp-to-edge”.

• address_mode_v (enums.AddressMode) – What happens when sampling beyond the y edge. Default “clamp-to-edge”.

• address_mode_w (enums.AddressMode) – What happens when sampling beyond the z edge. Default “clamp-to-edge”.

• mag_filter (enums.FilterMode) – Interpolation when zoomed in. Default ‘nearest’.

• min_filter (enums.FilterMode) – Interpolation when zoomed out. Default ‘nearest’.

• mipmap_filter – (enums.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 (enums.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.

The primary shader language is WGSL, though SpirV is also supported, as well as GLSL (experimental).

Parameters:

• label (str) – A human readable label. Optional.

• code (str | bytes) – The shader code, as WGSL, GLSL or SpirV. For GLSL code, the label must be given and contain the word ‘comp’, ‘vert’ or ‘frag’. For SpirV the code must be bytes.

• compilation_hints – currently 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 structs.Extent3D.

• mip_level_count (int) – The number of mip leveles. Default 1.

• sample_count (int) – The number of samples. Default 1.

• dimension (enums.TextureDimension) – The dimensionality of the texture. Default 2d.

• format (TextureFormat) – What channels it stores and how.

• usage (flags.TextureUsage) – 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.

property features

A set of feature names supported by this device.

property limits

A dict with limits for this device.

property queue

The default GPUQueue for this device.