Renderer

Functions for rendering graphics

Set Default Scale Mode

set_default_scale_mode(scale_mode: TextureScaleMode) → None

Set the default TextureScaleMode for new textures. The factory default is TextureScaleMode.LINEAR.

Args

  • scale_mode : The default scaling/filtering mode to use for new textures.

Get Default Scale Mode

get_default_scale_mode() → TextureScaleMode

Get the current default TextureScaleMode for new textures.

Returns

TextureScaleMode : The current default scaling/filtering mode.

Clear

clear(color: Color = ...) → None

Clear the renderer with the specified color.

Args

  • color : The color to clear with. Defaults to black (0, 0, 0, 255).

Raises

  • ValueError : If color values are not between 0 and 255.

Present

present() → None

Present the rendered content to the screen. This finalizes the current frame and displays it. Should be called after all drawing operations for the frame are complete.

Set Present Resolution

set_present_resolution(width: int, height: int) → None

Set a custom resolution for rendering. This creates an internal render target of the specified size, and all rendering will be done to that target, which is then scaled up to the actual screen resolution when presented.

Args

  • width : The width of the render target in pixels.
  • height : The height of the render target in pixels.

Raises

  • ValueError : If width or height are not positive integers.

Get Current Resolution

get_current_resolution() → Vec2

Get the resolution of the current render target for rendering. If a custom render target is set, this will return the size of it. Otherwise, it returns the presenting resolution of the renderer.

Returns

Vec2 : The width and height of the current resolution.

Set Target

set_target(target: Texture | None = None) → None

Set the current render target to the provided Texture.

Args

  • target : A Texture created with TextureAccess.TARGET, or None to unset.

Raises

  • RuntimeError : If the texture is not a TARGET texture.

Draw

draw(
    texture: Texture,
    transform: Transform = ...,
    anchor: Vec2 = ...,
    pivot: Vec2 = ...
) → None

Render a texture.

Args

  • texture : The texture to render.
  • transform : The transform (position, rotation, scale).
  • anchor : The anchor point (0.0-1.0). Defaults to top left (0, 0).
  • pivot : The rotation pivot (0.0-1.0). Defaults to center (0.5, 0.5).
draw(texture: Texture, dst: Rect) → None

Render a texture stretched into a destination rectangle.

This is a simpler alternative to the transform-based draw when you only need to place a texture at a specific screen rectangle without rotation. The source region is determined by the texture's clip area.

Args

  • texture : The texture to render.
  • dst : Destination rectangle on screen.

Read Pixels

read_pixels(src: Rect = ...) → PixelArray

Read pixel data from the renderer within the specified rectangle.

Args

  • src : The rectangle area to read pixels from. Defaults to entire renderer if None.

Returns

PixelArray : An array containing the pixel data.

Raises

  • RuntimeError : If reading pixels fails.

Draw Batch

draw_batch(
    texture: Texture,
    transforms: Sequence[Transform],
    anchor: Vec2 = ...,
    pivot: Vec2 = ...
) → None

Render a texture multiple times with different transforms in a single batch call.

This is significantly faster than calling draw() in a loop because it avoids per-call Python/C++ dispatch overhead.

Args

  • texture : The texture to render.
  • transforms : A list of transforms (position, rotation, scale).
  • anchor : The anchor point (0.0-1.0). Defaults to top left (0, 0).
  • pivot : The rotation pivot (0.0-1.0). Defaults to center (0.5, 0.5).
draw_batch(
    texture: Texture,
    transforms: Annotated[NDArray[numpy.float64], dict(shape=(None, None), order='C', device='cpu', writable=False)],
    anchor: Vec2 = ...,
    pivot: Vec2 = ...
) → None

Render a texture multiple times using a NumPy array for maximum throughput.

Each row of the array describes one instance. The number of columns determines the layout:

  • 2 columns [x, y] — position only (angle=0, scale=1).
  • 3 columns [x, y, angle] — position + rotation (scale=1).
  • 4 columns [x, y, angle, scale] — position + rotation + uniform scale.
  • 5 columns [x, y, angle, scale_x, scale_y] — full transform.

Args

  • texture : The texture to render.
  • transforms : float64 array with shape (N, 2|3|4|5).
  • anchor : The anchor point (0.0-1.0). Defaults to top left (0, 0).
  • pivot : The rotation pivot (0.0-1.0). Defaults to center (0.5, 0.5).

Raises

  • ValueError : If the array does not have 2, 3, 4, or 5 columns.