pyglet.graphics.framebuffer

Framebuffer render targets and utilities.

class RenderTexture

A fixed texture-backed rendering target.

Entering the context binds the framebuffer, clears it, installs a camera whose viewport matches the texture, and makes that camera the window default for ordinary pyglet draw calls. All previous state is restored on exit.

The generated texture remains owned by the caller after delete() releases the framebuffer and optional depth buffer.

Creating the target allocates GPU resources, and drawing into it submits GPU work. Avoid repeatedly creating short-lived targets in performance sensitive code.

This class is useful for a persistent off-screen surface, such as a minimap, post-processing input, or dynamically updated sprite texture:

target = pyglet.graphics.RenderTexture(512, 512)

with target:
    scene_batch.draw()

sprite = pyglet.sprite.Sprite(target.texture)

# The texture remains usable after the target is deleted.
target.delete()

The render target does not switch graphics contexts. When using multiple windows, make its owning context current with window.switch_to() before constructing, entering, clearing, or deleting it.

Added in version 3.0.

__init__(
width: int,
height: int,
*,
clear_color: tuple[float, float, float, float] = (0.0, 0.0, 0.0, 0.0),
depth: bool = False,
filters: TextureFilter | tuple[TextureFilter, TextureFilter] | None = None,
address_mode: AddressMode = AddressMode.CLAMP_TO_EDGE,
camera: BaseCamera | None = None,
context: SurfaceContext | None = None,
) → None

Create a render target and its color texture.

Parameters:

  • width (int) – Width of the color texture in pixels.

  • height (int) – Height of the color texture in pixels.

  • clear_color (tuple[float, float, float, float]) – RGBA color used whenever the target is entered.

  • depth (bool) – If True, attach a 24-bit depth renderbuffer.

  • filters (TextureFilter | tuple[TextureFilter, TextureFilter] | None) – Minification and magnification filters for the color texture.

  • address_mode (AddressMode) – Sampling behavior outside the color texture’s normalized bounds.

  • camera (BaseCamera | None) – Optional camera used while rendering. Its viewport is temporarily set to the texture dimensions. A dedicated Camera2D is created by default.

  • context (SurfaceContext | None) – Graphics context that owns the target. The current context is used when omitted.

delete(*, delete_texture: bool = False) → None

Release framebuffer resources.

Parameters:

delete_texture (bool) – Also delete the generated color texture. By default the texture remains available to sprites, models, and shaders.

Return type:

None

class TextureRenderTarget

A reusable framebuffer and camera for rendering independent textures.

Use render_to_texture() for each output. The framebuffer, camera, and same-sized depth buffer are retained between calls, while each successful scope yields a new caller-owned texture.

Reuse avoids repeated framebuffer and camera setup, but every output still allocates a texture and performs GPU rendering. Generating many textures, especially every frame, can remain expensive.

This avoids repeatedly constructing target state when generating many textures, while still allocating a distinct texture for every result:

target = pyglet.graphics.TextureRenderTarget()
textures = []

for batch, width, height in jobs:
    with target.render_to_texture(width, height) as texture:
        batch.draw()
    textures.append(texture)

target.delete()

# The returned textures are independent and remain valid.
for texture in textures:
    texture.delete()

The render target does not switch graphics contexts. When using multiple windows, make its owning context current with window.switch_to() before constructing, rendering with, or deleting it.

Added in version 3.0.

__init__(
*,
clear_color: tuple[float, float, float, float] = (0.0, 0.0, 0.0, 0.0),
depth: bool = False,
camera: BaseCamera | None = None,
context: SurfaceContext | None = None,
) → None

Create a reusable texture render target.

Parameters:

  • clear_color (tuple[float, float, float, float]) – RGBA color used for every output texture.

  • depth (bool) – If True, attach a 24-bit depth renderbuffer. It is retained for outputs of the same size and recreated when the size changes.

  • camera (BaseCamera | None) – Optional camera used while rendering. Its viewport is temporarily set to the current output dimensions. A dedicated Camera2D is created by default.

  • context (SurfaceContext | None) – Graphics context that owns the target. The current context is used when omitted.

render_to_texture(
width: int,
height: int,
*,
filters: TextureFilter | tuple[TextureFilter, TextureFilter] | None = None,
address_mode: AddressMode = AddressMode.CLAMP_TO_EDGE,
) → Iterator[Texture]

Render one scope into a new caller-owned texture.

The target creates and attaches a texture of the requested size, clears it on entry, and restores the previous framebuffer, camera, viewport, and scissor state on exit. The framebuffer and camera remain available for the next call.

If drawing raises an exception, the incomplete texture is deleted. On success, ownership of the texture passes to the caller.

Parameters:

  • width (int) – Width of the output texture in pixels.

  • height (int) – Height of the output texture in pixels.

  • filters (TextureFilter | tuple[TextureFilter, TextureFilter] | None) – Minification and magnification filters for the output texture.

  • address_mode (AddressMode) – Sampling behavior outside the texture’s normalized bounds.

Yields:

The newly created output texture.

Return type:

Iterator[Texture]