pyglet.window.camera

Camera helpers for 2D and 3D rendering.

class Camera2D(
window: Window,
*,
scroll_speed: float = 1.0,
min_zoom: float = 1.0,
max_zoom: float = 4.0,
zoom_speed: float = 1.0,
viewport: ViewportType | None = None,
register_handlers: bool = True,
window_block: UniformBlock | None = None,
copies_per_resource: int = 3,
projection_uniform: str = 'u_projection',
view_uniform: str = 'u_view',
) → None

Bases: BaseCamera[Camera2DView]

Manage an orthographic projection and movable 2D view.

A Camera2D keeps position, zoom, viewport, coordinate conversion, and shader matrix storage together. Select it for a batch or group to draw a world, UI layer, minimap, or other 2D rendering scope.

Added in version 3.0.

Create a 2D camera for a window.

The root view initially uses a lower-left origin and a zoom of 1.0. Unless an explicit viewport is supplied, it follows the full framebuffer as the window is resized or its scale changes.

Parameters:

  • window (Window) – Window whose graphics context and framebuffer dimensions are used by this camera.

  • scroll_speed (float) – Distance applied to each axis by move(). Scale input by elapsed time when using it for continuous movement.

  • min_zoom (float) – Minimum value accepted by zoom.

  • max_zoom (float) – Maximum value accepted by zoom.

  • zoom_speed (float) – Suggested zoom-rate scalar for application input handling.

  • viewport (tuple[int, int, int, int] | None) – Optional fixed root viewport as (x, y, width, height) in framebuffer coordinates. None tracks the full framebuffer.

  • register_handlers (bool) – If True, register for window resize and scale events. Disable this for fixed-size offscreen cameras.

  • window_block (UniformBlock | None) – Optional shader WindowBlock used to create the camera’s uniform-buffer storage on modern graphics backends. By default, the block is obtained from pyglet’s default shader.

  • copies_per_resource (int) – Number of ring-buffered matrix copies reserved for this camera on uniform-buffer backends.

  • projection_uniform (str) – Projection-matrix uniform name used when uniform buffers are unavailable.

  • view_uniform (str) – View-matrix uniform name used when uniform buffers are unavailable.

center_origin() → None

Enable viewport-centered root origin.

Return type:

None

reset_origin() → None

Restore lower-left root origin.

Return type:

None

set_centered_origin(enabled: bool = True) → None

Set whether the root camera origin is viewport-centered.

When enabled, world-space (0, 0) is drawn at the viewport center. When disabled, world-space (0, 0) is drawn at the viewport lower-left.

Return type:

None

set_scissor_area_relative(
x: int,
y: int,
width: int,
height: int,
) → CameraScissor

Set view-relative scissor clipping on the root view.

This clipping follows camera/view movement and zoom, and is applied automatically for group camera scopes.

Return type:

CameraScissor

zoom_in_to_point(x: float, y: float, amount: float) → None

Increase zoom while keeping a screen-space point fixed in world space.

Return type:

None

zoom_out_to_point(x: float, y: float, amount: float) → None

Decrease zoom while keeping a screen-space point fixed in world space.

Return type:

None

zoom_to_point(x: float, y: float, zoom: float) → None

Set zoom while keeping a screen-space point fixed in world space.

Return type:

None

class Camera2DView(
camera: Camera2D,
storage: CameraViewStorage | None,
*,
parent: Camera2DView | None = None,
) → None

Bases: _CameraViewBase[Camera2D]

A transform and viewport scope belonging to a Camera2D.

Views can add position, zoom, viewport, and scissor state while inheriting transforms from a parent view. Create them with Camera2D.create_view().

Added in version 3.0.

set_scissor_area_relative(
x: int,
y: int,
width: int,
height: int,
) → CameraScissor

Set a view-relative scissor area.

Unlike set_scissor_area (window-space), this scissor follows the view’s transform. This is useful for moving UI panels, nested clipped views, and other cases where clipping should travel with the view.

Return type:

CameraScissor

zoom_in_to_point(x: float, y: float, amount: float) → None

Increase zoom while keeping a screen-space point fixed in world space.

Return type:

None

zoom_out_to_point(x: float, y: float, amount: float) → None

Decrease zoom while keeping a screen-space point fixed in world space.

Return type:

None

zoom_to_point(x: float, y: float, zoom: float) → None

Set zoom while keeping a screen-space point fixed in world space.

This is useful for mouse-wheel zooming: pass the cursor coordinates and the desired new zoom, and the view position will shift so the world point under the cursor stays when zooming.

Return type:

None

class Camera3D(
window: Window,
*,
position: Vec3 | None = None,
target: Vec3 | None = None,
near: float = 0.1,
far: float = 1000.0,
field_of_view: float = 60.0,
walk_speed: float = 10.0,
look_speed: float = 10.0,
viewport: ViewportType | None = None,
register_handlers: bool = True,
window_block: UniformBlock | None = None,
copies_per_resource: int = 3,
projection_uniform: str = 'u_projection',
view_uniform: str = 'u_view',
) → None

Bases: BaseCamera[Camera3DView]

Manage a perspective projection and an oriented 3D view.

Camera3D combines position, pitch/yaw orientation, clipping distances, field of view, coordinate conversion, and shader matrix storage. It can be selected per batch or group for 3D scenes and rendering passes.

Added in version 3.0.

Create a perspective 3D camera for a window.

The initial orientation looks from position toward target. If no target is provided, the camera looks along the negative Z axis. Unless an explicit viewport is supplied, the root view follows the full framebuffer and updates its aspect ratio automatically.

Parameters:

  • window (Window) – Window whose graphics context and framebuffer dimensions are used by this camera.

  • position (Vec3 | None) – Initial world-space camera position. Defaults to the origin.

  • target (Vec3 | None) – Optional world-space point used to initialize pitch and yaw.

  • near (float) – Positive distance to the near clipping plane.

  • far (float) – Distance to the far clipping plane. It must be greater than near.

  • field_of_view (float) – Vertical field of view in degrees.

  • walk_speed (float) – World-space movement rate used by apply_movement_input().

  • look_speed (float) – Suggested rotation-rate scalar for mouse or controller input.

  • viewport (tuple[int, int, int, int] | None) – Optional fixed root viewport as (x, y, width, height) in framebuffer coordinates. None tracks the full framebuffer.

  • register_handlers (bool) – If True, register for window resize and scale events. Disable this for fixed-size offscreen cameras.

  • window_block (UniformBlock | None) – Optional shader WindowBlock used to create the camera’s uniform-buffer storage on modern graphics backends. By default, the block is obtained from pyglet’s default shader.

  • copies_per_resource (int) – Number of ring-buffered matrix copies reserved for this camera on uniform-buffer backends.

  • projection_uniform (str) – Projection-matrix uniform name used when uniform buffers are unavailable.

  • view_uniform (str) – View-matrix uniform name used when uniform buffers are unavailable.

screen_to_world_ray(
x: float,
y: float,
) → tuple[Vec3, Vec3]

Return a world-space ray from a screen-space point for the root view.

Return type:

tuple[Vec3, Vec3]

class Camera3DView(
camera: Camera3D,
storage: CameraViewStorage,
*,
parent: Camera3DView | None = None,
) → None

Bases: _CameraViewBase[Camera3D]

A positional view scope belonging to a Camera3D.

A view adds a local 3D offset to its camera and can define an independent viewport or scissor. Child views can inherit the offsets of their parents.

Added in version 3.0.

screen_to_world_ray(
x: float,
y: float,
) → tuple[Vec3, Vec3]

Return a world-space ray from a screen-space point.

The result is (origin, direction). origin is on the near clip plane and direction is normalized toward the far clip plane.

Return type:

tuple[Vec3, Vec3]

class CameraScissor(x: int, y: int, width: int, height: int) → None

Bases: object

Mutable scissor rectangle for camera/view group-scoped clipping.

set(x: int, y: int, width: int, height: int) → None

Update this scissor rectangle in place.

Ensure’s integer values for backends.

Return type:

None

class CameraViewStorage(*args, **kwargs)

Bases: Protocol

Target for camera matrix writes.

apply(
projection: Mat4,
view: Mat4,
) → None

Apply camera matrices to this region.

Return type:

None

bind_camera(
draw_context: DrawContext,
) → None

Bind or apply committed camera data for drawing.

Return type:

None

commit(draw_context: DrawContext) → None

Commit staged camera data to GPU-visible state when drawing.

Return type:

None

class FPSCamera(window: Window, **kwargs: Any) → None

Bases: Camera3D

First-person camera preset built on Camera3D.

Create a perspective 3D camera for a window.

The initial orientation looks from position toward target. If no target is provided, the camera looks along the negative Z axis. Unless an explicit viewport is supplied, the root view follows the full framebuffer and updates its aspect ratio automatically.

Parameters:

  • window (Window) – Window whose graphics context and framebuffer dimensions are used by this camera.

  • position – Initial world-space camera position. Defaults to the origin.

  • target – Optional world-space point used to initialize pitch and yaw.

  • near – Positive distance to the near clipping plane.

  • far – Distance to the far clipping plane. It must be greater than near.

  • field_of_view – Vertical field of view in degrees.

  • walk_speed – World-space movement rate used by apply_movement_input().

  • look_speed – Suggested rotation-rate scalar for mouse or controller input.

  • viewport – Optional fixed root viewport as (x, y, width, height) in framebuffer coordinates. None tracks the full framebuffer.

  • register_handlers – If True, register for window resize and scale events. Disable this for fixed-size offscreen cameras.

  • window_block – Optional shader WindowBlock used to create the camera’s uniform-buffer storage on modern graphics backends. By default, the block is obtained from pyglet’s default shader.

  • copies_per_resource – Number of ring-buffered matrix copies reserved for this camera on uniform-buffer backends.

  • projection_uniform – Projection-matrix uniform name used when uniform buffers are unavailable.

  • view_uniform – View-matrix uniform name used when uniform buffers are unavailable.

class ThirdPersonCamera(
window: Window,
*,
target: Vec3 | None = None,
distance: float = 8.0,
target_height: float = 1.5,
**kwargs: Any,
) → None

Bases: Camera3D

Third-person orbit camera that follows a target point.

Create a perspective 3D camera for a window.

The initial orientation looks from position toward target. If no target is provided, the camera looks along the negative Z axis. Unless an explicit viewport is supplied, the root view follows the full framebuffer and updates its aspect ratio automatically.

Parameters:

  • window (Window) – Window whose graphics context and framebuffer dimensions are used by this camera.

  • position – Initial world-space camera position. Defaults to the origin.

  • target (Vec3 | None) – Optional world-space point used to initialize pitch and yaw.

  • near – Positive distance to the near clipping plane.

  • far – Distance to the far clipping plane. It must be greater than near.

  • field_of_view – Vertical field of view in degrees.

  • walk_speed – World-space movement rate used by apply_movement_input().

  • look_speed – Suggested rotation-rate scalar for mouse or controller input.

  • viewport – Optional fixed root viewport as (x, y, width, height) in framebuffer coordinates. None tracks the full framebuffer.

  • register_handlers – If True, register for window resize and scale events. Disable this for fixed-size offscreen cameras.

  • window_block – Optional shader WindowBlock used to create the camera’s uniform-buffer storage on modern graphics backends. By default, the block is obtained from pyglet’s default shader.

  • copies_per_resource – Number of ring-buffered matrix copies reserved for this camera on uniform-buffer backends.

  • projection_uniform – Projection-matrix uniform name used when uniform buffers are unavailable.

  • view_uniform – View-matrix uniform name used when uniform buffers are unavailable.

class UniformBufferCameraRegion(
ubo: UniformBufferObject,
*,
copies_per_resource: int | None = None,
) → None

Bases: UniformBufferRegion

Camera storage adapter for UBO-backed data uploads.

commit(
_draw_context: DrawContext | None = None,
) → None

Upload dirty CPU-side data to the next writable GPU range.

Return type:

None

class UniformSetCameraRegion(
*,
projection_uniform: str = 'u_projection',
view_uniform: str = 'u_view',
) → None

Bases: object

Region adapter that updates per-program projection/view uniforms.

Create a per-program uniform camera region.

Parameters:

  • window – Window that this region belongs to controls.

  • projection_uniform (str) – Uniform name to receive the projection matrix.

  • view_uniform (str) – Uniform name to receive the view matrix.