pygfx.renderers.wgpu.WgpuRenderer

class pygfx.renderers.wgpu.WgpuRenderer(target, *args, pixel_scale=None, pixel_ratio=None, pixel_filter: Literal['nearest', 'linear', 'tent', 'disk', 'bspline', 'mitchell', 'catmull'] = 'mitchell', show_fps=False, sort_objects=True, enable_events=True, gamma_correction=1.0, ppaa='default', **kwargs)

Bases: RootEventHandler, Renderer

Turns Scenes into rasterized images using wgpu.

Parameters:

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

  • pixel_scale (float, optional) – The scale between the internal resolution and the physical resolution of the canvas. Setting to None (default) selects 1 if the screens looks to be HiDPI and 2 otherwise.

  • pixel_ratio (float, optional) – The ratio between the number of internal pixels versus the logical pixels on the canvas. If both pixel_ratio and pixel_scale are set, pixel_ratio is ignored.

  • pixel_filter (str, PixelFilter, optional) – The type of interpolation / reconstruction filter to use. Default ‘mitchell’.

  • 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.

  • sort_objects (bool) – If True, sort objects by depth before rendering. If False, the rendering order is mainly based on the objects render_order and position in the scene graph.

  • 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.

  • ppaa (str, optional) – The post-processing anti-aliasing to apply: “default”, “none”, “fxaa”, “ddaa”. By default it resolves to “ddaa”.

property device

A reference to the global wgpu device.

property target

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

property pixel_scale: float

The scale between the internal resolution and the physical resolution of the canvas.

  • If the scale is 1, the internal texture has the same size as the target.

  • If the scale is larger than 1, you’re doing SSAA.

  • If the scale is smaller than 1, you’re rendering at a low resolution, and then upscaling the result.

Note that a pixel_scale of 1 or 2 is more performant than fractional values.

Setting this value to None, will select a hirez configuration: It selects 1 if the target looks like a HiDPI screen (i.e. canvas.pixel_ratio>=2), and 2 otherwise. That way, the internal texture size is the same, regardless of the user’s system/monitor.

property pixel_ratio: float

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

pixel_ratio = pixel_scale * canvas.pixel_ratio

Setting this prop also changes the pixel_scale. This can be used to configure the size of the internal texture relative to the canvas’ logical size.

Setting this value to None is the same as setting pixel_scale to None, and results in a pixel_ratio of at least 2.

Note that setting pixel_ratio to 2.0 does not have the same effect, because the canvas pixel_ratio can be e.g. 1.5, in which case the resulting pixel_scale becomes fractional.

property pixel_filter: Literal['nearest', 'linear', 'tent', 'disk', 'bspline', 'mitchell', 'catmull']

The type of interpolation / reconstruction filter to use when flushing the result.

See pygfx.utils.enums.PixelFilter.

The renderer renders everything to an internal texture, which, depending on the pixel_scale, may have a different physical 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 target size is smaller, and upsampling when the target size is larger. When the internal texture has the same size as the target, no filter is applied (equivalent to nearest).

The filter defines how the interpolation is done (when the source and target are not of the same size).

property ppaa: Literal['default', 'none', 'fxaa', 'ddaa']

The post-processing anti-aliasing to apply.

  • “default”: use the value specified by PYGFX_DEFAULT_PPAA, defaulting to “ddaa”.

  • “none”: do not apply aliasing.

  • “fxaa”: applies Fast Approxomate AA, a common method.

  • “ddaa”: applies Directional Diffusion AA, a modern improved method.

The PYGFX_DEFAULT_PPAA environment variable can e.g. be set to “none” for image tests, so that the image tests don’t fail when we update the ddaa method.

Note that SSAA can be achieved by using a pixel_scale > 1. This can be well combined with PPAA, since the PPAA is applied before downsampling to the target texture.

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 sort_objects

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

By default, the render order is defined by:

  1. the object’s render_order property;

  2. whether the object is opaque/transparent/weighted/unknown;

  3. the object’s distance to the camera;

  4. the object’s position in the scene graph (based on a depth-first search).

If sort_objects is False, step 3 (sorting using the camera transform) is omitted.

property gamma_correction

The gamma correction applied in the final composition step.

property effect_passes

A tuple of EffectPass instances.

Together they form a chain of post-processing passes to produce the final visual result. They are executed in order when the rendered image is flushed to the target (e.g. the screen).

clear(*, all=False, color=False, depth=False, weights=False)

Clear one or more of the render targets.

Users typically don’t need to use this method. But sometimes it can be convenient to e.g. render a scene, and then clear the depth before rendering another scene.

  • all: clear all render targets; a fully clean sheeth.

  • color: clear the color buffer to rgba all zeros.

  • depth: clear the depth buffer.

  • weights: clear the render targets for weighted blending (the accum and reveal textures).

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

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 (bool, optional) – Whether to clear the color and depth buffers 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.