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

property adapter: GPUAdapter

The adapter object corresponding to this device.

property adapter_info: GPUAdapterInfo

The adapter.info dict.

create_bind_group(**parameters)

Create a GPUBindGroup object, which can be used in pass.set_bind_group() to attach a group of resources.

Parameters:

Example entry dicts:

# For a sampler
wgpu.BindGroupEntry(
    binding=0,
    resource=a_sampler,
)
# For a texture view
wgpu.BindGroupEntry(
    binding=1,
    resource=a_texture_view,
)
# For a buffer
wgpu.BindGroupEntry(
    binding=2,
    resource=wgpu.BufferBinding(
        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:

Example with buffer binding:

wgpu.BindGroupLayoutEntry(
    binding=0,
    visibility=wgpu.ShaderStage.COMPUTE,
    buffer=wgpu.BufferBindingLayout(
        type="storage",
        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.

Alignment: the size must be a multiple of 4.

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.

Alignment: if the size (in bytes) of data is not a multiple of 4, the buffer

size is rounded up to the nearest multiple of 4.

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:
create_compute_pipeline_async(**parameters)

Async version of create_compute_pipeline().

Both versions are compatible with WebGPU.

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 GPURenderBundleEncoder object.

Render bundles represent a pre-recorded bundle of commands. In cases where the same commands are issued across multiple views or frames, using a rander bundle can improve performance by removing the overhead of repeating the commands.

Parameters:

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

  • color_formats (list) – A list of the GPUTextureFormats of the color attachments for this pass or bundle.

  • depth_stencil_format (GPUTextureFormat) – The format of the depth/stencil attachment for this pass or bundle.

  • sample_count (int) – The number of samples per pixel in the attachments for this pass or bundle. Default 1.

  • depth_read_only (bool) – If true, indicates that the render bundle does not modify the depth component of any depth-stencil attachments. Default False.

  • stencil_read_only (bool) – If true, indicates that the render bundle does not modify the stencil component of any depth-stencil attachments. Default False.

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 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]. The primitive state supports an additional field polygon_mode that can be set to “line” or “point”. To do so, the primitive state must be given as a dict, and the the device must be requested with the native-only features “polygon-mode-line” or “polygon-mode-point”.

  • 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 examples below, the values that are marked as optional, the shown value is the default.

Example vertex (structs.VertexState):

wgpu.VertexState(
    module=a_shader_module,
    entry_point="main",
    buffers=[
        wgpu.VertexBufferLayout(
            array_stride=8,
            step_mode="vertex",  # optional
            attributes=[
                wgpu.VertexAttribute(
                    format="floar32",
                    offset=0,
                    shader_location=0,
                ),
                # ...
            ],
        ),
    ],
)

Example primitive (structs.PrimitiveState):

wgpu.PrimitiveState(
    topology="triangle-list", # optional
    strip_index_format="uint32",  # see note
    front_face="ccw",  # optional
    cull_mode="none",  # optional
)

Example depth_stencil (structs.DepthStencilState):

wgpu.DepthStencilState(
    format="depth24plus-stencil8",
    depth_write_enabled=False,  # optional
    depth_compare="less",  # optional
    stencil_front=wgpu.StencilFaceState(  # optional
        compare="equal",
        fail_op="keep",
        depth_fail_op="keep",
        pass_op="keep",
    ),
    stencil_back=wgpu.StencilFaceState(  # optional
        compare="equal",
        fail_op="keep",
        depth_fail_op="keep",
        pass_op="keep",
    ),
    stencil_read_mask=0xFFFFFFFF,  # optional
    stencil_write_mask=0xFFFFFFFF,  # optional
    depth_bias=0,  # optional
    depth_bias_clamp=0.0,  # optional
    depth_bias_slope_scale=0.0,  # optional
)

Example multisample (structs.MultisampleState):

wgpu.MultisampleState(
    count=1,  # optional
    mask=0xFFFFFFFF,  # optional
    alpha_to_coverage_enabled=False,  # optional
)

Example fragment (structs.FragmentState). The blend parameter can be None to disable blending (not all texture formats support blending).

wgpu.FragmentState(
    module=a_shader_module,
    entry_point="main",
    targets=[
        wgpu.ColorTargetState(
            format="bgra8unorm-srgb",
            blend=wgpu.BlendState(
                color=wgpu.BlendComponent(
                    operation="add",
                    src_factor="one",
                    dst_factor="zero",
                ),
                alpha=wgpu.BlendComponent(
                    operation="add",
                    src_factor="one",
                    dst_factor="zero",
                ),
            ),
        ),
        # ...
    ],
)
create_render_pipeline_async(**parameters)

Async version of create_render_pipeline().

Both versions are compatible with WebGPU.

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 maximum 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 fewer formats are available for storage usage.

destroy() → None

Destroy this device.

This cleans up all its resources and puts it in an unusable state. Note that all objects get cleaned up properly automatically; this is only intended to support explicit destroying.

NOTE: not yet implemented; for the moment this does nothing.

property features: set

A set of feature names supported by this device.

property limits: dict

A dict with limits for this device.

property queue: GPUQueue

The default GPUQueue for this device.