pygfx.renderers.wgpu.WgpuRenderer

class pygfx.renderers.wgpu.WgpuRenderer(target, *args, pixel_ratio=None, pixel_filter=None, show_fps=False, blend_mode='default', sort_objects=False, enable_events=True, gamma_correction=1.0, **kwargs)

Bases: RootEventHandler, Renderer

Turns Scenes into rasterized images using wgpu.

The current implementation supports various blend_modes which control how transparency is handled during the rendering process. The following modes exist:

  • “default” or None: Select the default: currently this is “ordered2”.

  • “opaque”: single-pass approach that ignores transparency.

  • “ordered1”: single-pass approach that blends fragments (using alpha blending). Can only produce correct results if fragments are drawn from back to front.

  • “ordered2”: two-pass approach that first processes all opaque fragments and then blends transparent fragments (using alpha blending) with depth-write disabled. The visual results are usually better than ordered1, but still depend on the drawing order.

  • “weighted”: two-pass approach for order independent transparency based on alpha weights.

  • “weighted_depth”: two-pass approach for order independent transparency based on alpha weights and depth [1]. Note that the depth range affects the (quality of the) visual result.

  • “weighted_plus”: three-pass approach for order independent transparency, in which the front-most transparent layer is rendered correctly, while transparent layers behind it are blended using alpha weights.

Parameters:

  • target (WgpuCanvas or Texture) – The target to render to. It is also used to determine the size of the render buffer.

  • pixel_ratio (float, optional) – The ratio between the number of pixels in the render buffer versus the number of pixels in the display buffer. If None, this will be 1 for high-res canvases and 2 otherwise. If greater than 1, SSAA (supersampling anti-aliasing) is applied while converting a render buffer to a display buffer. If smaller than 1, pixels from the render buffer are replicated while converting to a display buffer. This has positive performance implications.

  • pixel_filter (float, optional) – The strength of the filter when copying the result to the target/canvas.

  • show_fps (bool) – Whether to display the frames per second. Beware that depending on the GUI toolkit, the canvas may impose a frame rate limit.

  • blend_mode (str) – The method for handling transparency. If None, use "ordered2".

  • sort_objects (bool) – If True, sort objects by depth before rendering. The sorting uses a hierarchical index based on the object’s (1) render_order, (2) distance to the camera (based on the local frame’s origin), (3) the position in the scene graph (flattened depth-first). If False, the rendering order is based on the objects render_order and position in the scene graph only.

  • enable_events (bool) – If True, forward wgpu events to pygfx’s event system.

  • gamma_correction (float) – The gamma correction to apply in the final render stage. Typically a number between 0.0 and 2.0. A value of 1.0 indicates no correction.

References

[1] Morgan McGuire and Louis Bavoil, Weighted Blended Order-Independent Transparency, Journal of Computer Graphics Techniques (JCGT), vol. 2, no. 2, 122-141, 2013

property device

A reference to the global wgpu device.

property target

The render target. Can be a canvas, texture or texture view.

property pixel_ratio

The ratio between the number of internal pixels versus the logical pixels on the canvas.

This can be used to configure the size of the render texture relative to the canvas’ logical size. Can be set to None to set the default. By default the pixel_ratio is 2 on “regular” screens, and the same as the screen pixel ratio on HiDPI screens (usually also 2).

If the used pixel ratio causes the render texture to be larger than the physical size of the canvas, SSAA (super sampling antialiasing) is applied, resulting in a smoother final image with less jagged edges. Alternatively, this value can be set to e.g. 0.5 to lower the resolution.

property pixel_filter

The strength of the filter applied to the final pixels.

The renderer renders everything to an internal texture, which, depending on the pixel_ratio, may have a differens size than the target (i.e. canvas). In the process of rendering the result to the target, a filter is applied, resulting in SSAA if the size was larger, and a smoothing effect otherwise.

When the pixel_filter is 1.0, the default optimal filter is used. Higher values result in more blur. Can be set to 0 to disable the filter.

property rect

The rectangular viewport for the renderer area.

property logical_size

The size of the render target in logical pixels.

property physical_size

The physical size of the internal render texture.

property blend_mode

The method for handling transparency:

  • “default” or None: Select the default: currently this is “ordered2”.

  • “opaque”: single-pass approach that consider every fragment opaque.

  • “ordered1”: single-pass approach that blends fragments (using alpha blending). Can only produce correct results if fragments are drawn from back to front.

  • “ordered2”: two-pass approach that first processes all opaque fragments and then blends transparent fragments (using alpha blending) with depth-write disabled. The visual results are usually better than ordered1, but still depend on the drawing order.

  • “weighted”: two-pass approach that for order independent transparency, using alpha weights.

  • “weighted_depth”: two-pass approach for order independent transparency, with weights based on alpha and depth (McGuire 2013). Note that the depth range affects the (quality of the) visual result.

  • “weighted_plus”: three-pass approach for order independent transparency, in which the front-most transparent layer is rendered correctly, while transparent layers behind it are blended using alpha weights.

property sort_objects

Whether to sort world objects by depth before rendering. Default False.

  • True: the render order is defined by 1) the object’s render_order property; 2) the object’s distance to the camera; 3) the position object in the scene graph (based on a depth-first search).

  • False: don’t sort, the render order is only defined by the render_order and scene graph position.

property gamma_correction

The gamma correction applied in the final composition step.

render(scene: WorldObject, camera: Camera, *, rect=None, clear_color=None, flush=True)

Render a scene with the specified camera as the viewpoint.

Parameters:

  • scene (WorldObject) – The scene to render, a WorldObject that optionally has child objects.

  • camera (Camera) – The camera object to use, which defines the viewpoint and view transform.

  • rect (tuple, optional) – The rectangular region to draw into, expressed in logical pixels, a.k.a. the viewport.

  • clear_color (bool, optional) – Whether to clear the color buffer before rendering. By default this is True on the first call to render() after a flush, and False otherwise.

  • flush (bool, optional) – Whether to flush the rendered result into the target (texture or canvas). Default True.

flush(target=None)

Render the result into the target. This method is called automatically unless you use .render(..., flush=False).

get_pick_info(pos)

Get information about the given window location. The given pos is a 2D point in logical pixels (with the origin at the top-left). Returns a dict with fields:

  • “ndc”: The position in normalized device coordinates, the 3d element

    being the depth (0..1). Can be translated to the position in world coordinates using the camera transforms.

  • “rgba”: The value in the color buffer. All zero’s when rendering directly to the screen (bypassing post-processing).

  • “world_object”: the object at that location (provided that the object supports picking).

  • Additional pick info may be available, depending on the type of object and its material. See the world-object classes for details.

snapshot()

Create a snapshot of the currently rendered image.

request_draw(draw_function=None)

Forwards a request_draw call to the target canvas. If the renderer’s target is not a canvas (e.g. a texture) this function does nothing.

enable_events()

Add event handlers for a specific list of events that are generated by the canvas. The handler is the convert_event method in order to convert the Wgpu event dicts into Pygfx event objects.

disable_events()

Remove the event handlers from the canvas.

convert_event(event: dict)

Converts Wgpu event (dict following jupyter_rfb spec) to Pygfx Event object, adds picking info and then dispatches the event in the Pygfx event system.