Canvas, camera, and interaction#

These modules provide canvases, cameras, lights, and input handling for interactive visualizations.

Canvas and windowing#

class webgpu.canvas.Canvas(device, canvas, multisample_count=4)#

Bases: object

Canvas management class, handles “global” state, like webgpu device, canvas, frame and depth buffer

color_attachments(loadOp: LoadOp)#

depth_format: TextureFormat#

depth_stencil_attachment(loadOp: LoadOp)#

depth_texture: Texture = None#

depth_texture_view = None#

destroy_textures()#

device: Device#

height: int = 0#

multisample: MultisampleState = None#

multisample_texture: Texture = None#

multisample_texture_view = None#

on_resize(func: Callable)#

on_update_html_canvas(func: Callable)#

on_visibility(func: Callable)#: Register callback for visibility changes. Called with True/False.

resize()#

save_screenshot(filename: str)#

select_attachments(loadOp: LoadOp)#

select_depth_stencil_attachment(loadOp: LoadOp)#

select_depth_texture: Texture = None#

select_depth_texture_view = None#

select_texture: Texture = None#

select_texture_view = None#

target_texture: Texture = None#

target_texture_view = None#

update_html_canvas(html_canvas)#: Reconfigure the canvas with the current HTML canvas element. This is necessary when the HTML canvas element changes, disappears (e.g. when switching a tab) and appears again.

width: int = 0#

webgpu.canvas.debounce(arg=None, *, rate_hz=60)#

webgpu.canvas.init_webgpu(html_canvas)#: Initialize WebGPU, create device and canvas

webgpu.canvas.set_default_clear_color(color)#: Set the clear color used by Canvas instances created afterwards.

Camera and lighting#

class webgpu.camera.Camera#

Bases: object

Interactive camera that holds a transform and notifies registered observers on change.

get_shader_code()#

register_callbacks(input_handler, get_position_fn=None)#

Idempotent: unregisters existing handlers for this input_handler first. get_position_fn is used for dblclick center-on-point (per-canvas).

register_dblclick_center(input_handler, get_position_fn)#: Register only the double-click-to-center handler (used in JS-engine mode, where rotate/pan/zoom are handled in the browser).

register_observer(callback)#

Idempotent: registering the same callback twice has no additional effect.

reset(pmin, pmax)#: Fit the camera to the axis-aligned box [pmin, pmax] and notify observers.

reset_xy(flip: bool = False)#: Reset to a top-down XY view and notify observers.

reset_xz(flip: bool = False)#: Reset to an XZ view and notify observers.

reset_yz(flip: bool = False)#: Reset to a YZ view and notify observers.

unregister_callbacks(input_handler)#: Remove previously registered handlers from the given input_handler.

unregister_dblclick_center(input_handler)#: Remove a previously registered double-click-to-center handler.

unregister_observer(callback)#: Remove a previously registered observer callback.

class webgpu.camera.CameraUniforms(**kwargs)#

Bases: UniformBase

Uniforms class, derived from ctypes.Structure to ensure correct memory layout

aspect#: Structure/Union member

dpr#: Structure/Union member

height#: Structure/Union member

model_view#: Structure/Union member

model_view_projection#: Structure/Union member

normal_mat#: Structure/Union member

rot_mat#: Structure/Union member

update(transform, canvas, write_buffer=True)#

Recompute projection/model-view matrices from transform and canvas dimensions.

Returns (model_view_proj, model_view) matrices, or (None, None) if canvas is unavailable.

With write_buffer False the matrices are computed but the GPU buffer is not uploaded (JS-engine mode, where the browser owns the camera).

view#: Structure/Union member

width#: Structure/Union member

class webgpu.camera.Transform#

Bases: object

3D transform with translation/rotation/scale around a configurable center.

copy()#

init(pmin, pmax)#: Initialize the transform to frame the axis-aligned box [pmin, pmax].

map_point(point)#

property mat#

reset_xy(flip: bool = False)#: Reset to a view looking along +Z onto the XY plane, optionally flipped.

reset_xz(flip: bool = False)#: Reset to a view looking along +Y onto the XZ plane, optionally flipped.

reset_yz(flip: bool = False)#: Reset to a view looking along +X onto the YZ plane, optionally flipped.

rotate(ang_x, ang_y=0, center=None)#

scale(s, center=None)#

set_center(center)#

translate(dx=0.0, dy=0.0, dz=0.0)#

class webgpu.light.Light#

Bases: object

get_bindings()#

get_shader_code()#

update(options)#

class webgpu.light.LightUniforms(**kwargs)#

Bases: UniformBase

Uniforms class for light settings, derived from ctypes.Structure to ensure correct memory layout

ambient#: Structure/Union member

diffuse#: Structure/Union member

fill#: Structure/Union member

key#: Structure/Union member

min_diffuse#: Structure/Union member

rim_power#: Structure/Union member

rim_strength#: Structure/Union member

shininess#: Structure/Union member

specular#: Structure/Union member

wrap#: Structure/Union member

Interaction and UI helpers#

Declarative GUI parameters that work in both live and export paths.

A GuiParam describes a single interactive control (dropdown, slider, checkbox) that writes to one or more GPU uniform buffer fields. Multiple renderers can share the same GuiParam instance — it appears once in the GUI.

class webgpu.gui_param.GuiParam(kind, label, *, default, options=None, min=None, max=None, step=None)#

Bases: object

Declarative GUI parameter. Works in both live and export paths.

Examples:

component = GuiParam(“dropdown”, “Component”,: options={“Norm”: -1, “x”: 0, “y”: 1}, default=-1)

component.bind(settings, “component”) # settings.uniform.component component.affects(colormap, “min”, values={-1: 0.1, 0: -1.0, 1: 0.5})

shrink = GuiParam(“slider”, “Shrink”, default=1.0, min=0.0, max=1.0) shrink.bind(mesh_uniform, “shrink”)

affects(ref, field_name, *, values)#

On change, look up selected value in dict and write result to field.

ref: a UniformBase, or object with .uniform/.uniforms attr, or callable. values: dict mapping option values to write values, or a callable

returning such a dict (resolved at export time). E.g. {-1: 0.1, 0: -1.0, 1: 0.5}

bind(ref, field_name)#

Write selected value directly to this uniform field on change.

ref: a UniformBase, or object with .uniform/.uniforms attr, or callable.

export(registry)#: Produce an Interaction for the JS engine.

class webgpu.input_handler.InputHandler#

Bases: object

class Modifiers( alt: bool | None = None, shift: bool | None = None, ctrl: bool | None = None, )#

Bases: object

get_set()#

emit(event: str, ev: dict, *args)#

handle_engine_event(event)#: Dispatch an event forwarded from the JS engine to Python callbacks.

on( event: str, func: Callable, alt: bool | None = None, shift: bool | None = None, ctrl: bool | None = None, )#

on_click( func, alt: bool | None = None, shift: bool | None = None, ctrl: bool | None = None, )#

on_dblclick( func, alt: bool | None = None, shift: bool | None = None, ctrl: bool | None = None, )#

on_drag( func, alt: bool | None = None, shift: bool | None = None, ctrl: bool | None = None, )#

on_mousedown( func, alt: bool | None = None, shift: bool | None = None, ctrl: bool | None = None, )#

on_mousemove( func, alt: bool | None = None, shift: bool | None = None, ctrl: bool | None = None, )#

on_mouseout( func, alt: bool | None = None, shift: bool | None = None, ctrl: bool | None = None, )#

on_mouseup( func, alt: bool | None = None, shift: bool | None = None, ctrl: bool | None = None, )#

on_wheel( func, alt: bool | None = None, shift: bool | None = None, ctrl: bool | None = None, )#

register_callbacks()#

set_canvas(html_canvas)#

set_engine_mode(enabled: bool)#: Switch between JS-engine-owned input and the legacy DOM-handler path.

unregister(event, func: Callable)#

unregister_callbacks()#