API for advanced wgpu usage

pygfx.renderers.wgpu.enable_wgpu_features(*features)

Enable specific features (as strings) on the wgpu device.

WARNING: enabling features means that your code may not work on all devices. The point of wgpu is that it can make a promise that a visualization works and looks the same on any device. Using features breaks that promise, and may cause your code to not work on e.g. mobile devices or certain operating systems.

This function must be called before the first wgpu device is created. In practice this means before the first Renderer is created. It can be called multiple times to enable more features.

For more information on features:

pygfx.renderers.wgpu.register_wgpu_render_function(wobject_cls, material_cls)

Decorator for WGPU rendering functions.

Parameters:

  • wobject_cls (WorldObject) – The world object that this function knows how to render.

  • material_cls (Material) – The world object that this function knows how to render.

class pygfx.renderers.wgpu.Binding(name, type, resource, visibility=3, structname=None)

Simple object to hold together some information about a binding, for internal use.

Parameters:

  • name – the name in wgsl

  • type – “buffer/subtype”, “sampler/subtype”, “texture/subtype”, “storage_texture/subtype”. The subtype depends on the type: BufferBindingType, SamplerBindingType, TextureSampleType, or StorageTextureAccess.

  • resource – the Buffer, GfxTextureView, or GfxSampler object.

  • visibility – wgpu.ShaderStage flag

  • structname – the custom wgsl struct name, if any. otherwise will auto-generate.

Some tips on terminology:

  • A “binding” is a generic term for an object that defines how a

    resource (buffer or texture) is bound to a shader. In this subpackage it likely means a Binding object like this.

  • This binding can be represented with a binding_descriptor and

    binding_layout_descriptor. These are dicts to be passed to wgpu.

  • A list of these binding_layout_descriptor’s can be passed to create_bind_group_layout.

  • A list of these binding_layout’s can be passed to create_bind_group.

  • Multiple bind_group_layout’s can be combined into a pipeline_layout.

get_bind_group_descriptors(slot)

Get the descriptors (dicts) for creating a binding_descriptor and binding_layout_descriptor. A list of these descriptors are combined into a bind_group and bind_group_layout.

class pygfx.renderers.wgpu.WorldObjectShader(wobject, **kwargs)

A base shader for world objects. Must be subclassed to implement a shader for a specific material. This class also implements common functions that can be used in all material-specific renderers.

code_common()

Get the WGSL functions that are pygfx-builtin. These are functions that re used by (about) every WorldObject. More advanced functions, e.g. for lighting calculations, should be loaded from the shaderlib.

code_definitions()

Get the WGSL definitions of types and bindings (uniforms, storage buffers, samplers, and textures).

define_binding(bindgroup, index, binding)

Define a uniform, buffer, sampler, or texture. The produced wgsl will be part of the code returned by get_definitions(). The binding must be a Binding object.

define_bindings(bindgroup, bindings_dict)

Define a collection of bindings organized in a dict.

define_img_colormap(texture, interpolation='linear')

Define the given texture view as the colormap to be used to lookup the final color from the image data. In the WGSL the colormap can be sampled using sample_colormap(). Returns a list of bindings.

define_texcoords_and_colormap(texture, texcoords, interpolation='linear')

Define the given texture as the colormap to be used to lookup the final color from the (per-vertex or per-face) texcoords. In the WGSL the colormap can be sampled using sample_colormap(). Returns a list of bindings.

generate_wgsl(**kwargs)

Generate the final WGSL. Calls get_code() and then resolves the templating variables, varyings, and depth output.

get_bindings(wobject, shared)

Subclasses must return a dict describing the buffers and textures used by this shader.

The result must be a dict of dicts with binding objects (group_slot -> binding_slot -> binding)

get_code()

Implement this to compose the total (but still templated) shader. This method is called by generate_wgsl().

get_pipeline_info(wobject, shared)

Subclasses must return a dict describing pipeline details.

Fields for a compute shader: empty

Fields for a render shader:

  • “cull_mode”

  • “primitive_topology”

get_render_info(wobject, shared)

Subclasses must return a dict describing render details.

Fields for a compute shader:

  • “indices” (3 ints)

Fields for a render shader:

  • “render_mask”

  • “indices” (list of 2 or 4 ints).

property hash

A hash of the current state of the shader. If the hash changed, it’s likely that the shader changed.

class pygfx.renderers.wgpu.Shared(*, canvas=None)

An object to store global data to share between multiple wgpu renderers. Each renderer updates the data and then passes this down to the pipeline containers.

The renderer instantiates and stores the singleton shared object.

pre_render_hook()

Called by the renderer on the beginning of a draw.

property adapter

The shared WGPU adapter object.

property device

The shared WGPU device object.

property uniform_buffer

The shared uniform buffer in which the renderer puts information about the canvas and camera.

property glyph_atlas_texture

The shared glyph atlas (as a texture view and sampler) for objects that want to render text.

property glyph_atlas_info_buffer

A buffer containing per-glyph metadata (rects and more).