pygfx.renderers.WgpuRenderer

class pygfx.renderers.WgpuRenderer(target, *args, pixel_ratio=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 wich 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.

  • 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 all objects in the scene before rendering them. The sort 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 position in the scene graph (flattened in depth-first order).

  • 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

Examples

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. By default (value is None) the used pixel ratio follows the screens pixel ratio on high-res displays, and is 2 otherwise.

If the used pixel ratio causes the render texture to be larger than the physical size of the canvas, SSAA 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 (e.g. for performance during interaction).

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 wich 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 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 defined by the scene graph alone.

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.