Camera 2D

class arcade.Camera2D(viewport: Rect | None = None, position: Point2 | None = None, up: tuple[float, float] = (0.0, 1.0), zoom: float = 1.0, projection: Rect | None = None, near: float = -100.0, far: float = 100.0, *, scissor: Rect | None = None, render_target: Framebuffer | None = None, window: Window | None = None)[source]

Bases:

A simple orthographic camera.

It provides properties to access every important variable for controlling the camera. 3D properties such as pos, and up are constrained to a 2D plane. There is no access to the forward vector (as a property).

There are also ease of use methods for matching the viewport and projector to the window size.

Provides many helpful values:
  • The position and rotation or the camera

  • 8 positions along the edge of the camera’s viewable area

  • the bounding box of the area the camera sees

  • Viewport, and Scissor box for controlling where to draw to

Warning

Do not replace the camera_data and projection_data instances after initialization!

Replacing the camera data and projection data may break controllers. Their contents are exposed via properties rather than directly to prevent this.

Parameters:
  • viewport – A Rect which defines the pixel bounds which the camera fits its image to. If the viewport is not 1:1 with the projection then positions in world space won’t match pixels on screen.

  • position – The 2D position of the camera in the XY plane.

  • up – A 2D vector which describes which direction is up (defines the +Y-axis of the camera space).

  • zoom – A scalar value which is inversely proportional to the size of the camera projection. i.e. a zoom of 2.0 halves the size of the projection, doubling the perceived size of objects.

  • projection – A Rect which defines the world space bounds which the camera projects to the viewport.

  • near – The near clipping plane of the camera.

  • far – The far clipping plane of the camera.

  • scissor – A Rect which will crop the camera’s output to this area on screen. Unlike the viewport this has no influence on the visuals rendered with the camera only the area shown.

  • render_target – The FrameBuffer that the camera may use. Warning if the target isn’t the screen it won’t automatically show up on screen.

  • window – The Arcade Window to bind the camera to. Defaults to the currently active window.

aabb() Rect[source]

Retrieve the axis-aligned bounds box of the camera’s view area. If the camera isn’t rotated , this will be precisely the view area, but it will cover a larger area when it is rotated. Useful for CPU culling

activate() Generator[Self, None, None][source]

Set internal projector as window projector, and set the projection and view matrix.

This method works with ‘with’ blocks. After using this method it automatically resets the projector to the one previously in use.

property angle: float

An angle representation of the 2D UP vector. This starts with 0 degrees as [0, 1] rotating clock-wise.

property bottom: float

The bottom edge of the projection in world space. This is not adjusted with the camera position.

Note

this IS scaled by zoom. If this isn’t what you want, you have to calculate the value manually from projection_data

property bottom_center: Vec2

Get the bottom most position the camera can see

property bottom_left: Vec2

Get the bottom left most corner the camera can see

property bottom_right: Vec2

Get the bottom right most corner the camera can see

property center_left: Vec2

Get the left most point the camera can see

property center_right: Vec2

Get the right most point the camera can see

equalise() None[source]

Forces the projection to match the size of the viewport. When matching the projection to the viewport the method keeps the projections center in the same relative place.

classmethod from_camera_data(*, camera_data: CameraData | None = None, projection_data: OrthographicProjectionData | None = None, render_target: Framebuffer | None = None, viewport: Rect | None = None, scissor: Rect | None = None, window: Window | None = None) Self[source]

Make a Camera2D directly from data objects.

This classmethod allows advanced users to:

  1. skip or replace the default validation

  2. share camera_data or projection_data between cameras

Warning

Be careful when sharing data objects! Any action on a camera which changes a shared object changes it for every camera which uses the same object.

Shared Value

Example Use(s)

camera_data

Mini-maps, reflection, and ghosting effects.

projection_data

Simplified rendering configuration

render_target

Complex rendering setups

Parameters:
  • camera_data – A CameraData describing the position, up, forward and zoom.

  • projection_data – A OrthographicProjectionData which describes the left, right, top, bottom, far, near planes and the viewport for an orthographic projection.

  • render_target

    A non-screen Framebuffer for this camera to draw into. When specified,

    • nothing will draw directly to the screen

    • the buffer’s internal viewport will be ignored

  • viewport – A viewport as a Rect. This overrides any viewport the render_target may have.

  • scissor – The OpenGL scissor box to use when drawing.

  • window – The Arcade Window to bind the camera to. Defaults to the currently active window.

property height: float

The height of the projection from bottom to top. This is in world space coordinates not pixel coordinates.

Note

this IS scaled by zoom. If this isn’t what you want, you have to calculate the value manually from projection_data

property left: float

The left edge of the projection in world space. This is not adjusted with the camera position.

Note

this IS scaled by zoom. If this isn’t what you want, you have to calculate the value manually from projection_data

match_target(viewport: bool = True, projection: bool = True, scissor: bool = True, position: bool = False, aspect: float | None = None) None[source]

Sets the viewport to the size of the Camera2D’s render target.

Parameters:
  • viewport – Flag whether to equalise the viewport to the area of the render target

  • projection – Flag whether to equalise the size of the projection to match the render target

  • fixed (The projection center stays)

  • size. (and the new projection matches only in)

  • scissor – Flag whether to update the scissor value.

  • position – Flag whether to also center the camera to the value. Off by default

  • aspect – The ratio between width and height that the value should be constrained to. i.e. for an aspect ratio of 4:3 you should input 4.0/3.0 or 1.33333.... Cannot be equal to zero. If unset then the value will not be updated.

Raises:

ValueError – Will be raised if the Camera2D was has no render target.

match_window(viewport: bool = True, projection: bool = True, scissor: bool = True, position: bool = False, aspect: float | None = None) None[source]

Sets the viewport to the size of the window. Should be called when the window is resized.

Parameters:
  • viewport – Flag whether to equalise the viewport to the value.

  • projection – Flag whether to also equalize the projection to the viewport. On by default

  • scissor – Flag whether to also equalize the scissor box to the viewport. On by default

  • position – Flag whether to also center the camera to the viewport. Off by default

  • aspect – The ratio between width and height that the viewport should be constrained to. If unset then the viewport just matches the window size. The aspect ratio describes how much larger the width should be compared to the height. i.e. for an aspect ratio of 4:3 you should input 4.0/3.0 or 1.33333.... Cannot be equal to zero.

point_in_view(point: tuple[float | int, float | int] | Vec2) bool[source]

Take a 2D point in the world, and return whether the point is inside the visible area of the camera.

property position: Vec2

The 2D world position of the camera along the X and Y axes.

project(world_coordinate: tuple[float | int, float | int] | Vec2 | tuple[float | int, float | int, float | int] | Vec3) Vec2[source]

Take a Vec2 or Vec3 of coordinates and return the related screen coordinate

property projection: Rect

Get/set the left, right, bottom, and top projection values.

These are world space values which control how the camera projects the world onto the pixel space of the current viewport area.

Note

this IS scaled by zoom. If this isn’t what you want, you have to calculate the value manually from projection_data

Warning

The axis values cannot be equal!

  • left cannot equal right

  • bottom cannot equal top

This property raises a ZeroProjectionDimension exception if any axis pairs are equal. You can handle this exception as a ValueError.

property projection_data: OrthographicProjectionData

The projection data for the camera.

This is an Orthographic projection. with a right, left, top, bottom, near, and far value.

An easy way to understand the use of the projection is that the right value of the projection tells the camera what value will be at the right most pixel in the viewport.

Due to the view data having a zoom component most use cases will only change the projection on screen resize.

property projection_far: float

The far plane of the projection in world space. This is not adjusted with the camera position.

Note

this IS NOT scaled by zoom.

property projection_near: float

The near plane of the projection in world space. This is not adjusted with the camera position.

Note

this IS NOT scaled by zoom.

render_target: Framebuffer | None

An optional framebuffer to activate at the same time as the projection data, could be the screen, or an offscreen texture

property right: float

The right edge of the projection in world space. This is not adjusted with the camera position.

Note

this IS scaled by zoom. If this isn’t what you want, you have to calculate the value manually from projection_data

scissor: Rect | None

An optional rect which describes what pixels of the active render target should be drawn to when undefined the viewport rect is used.

property top: float

The top edge of the projection in world space. This is not adjusted with the camera position.

Note

this IS scaled by zoom. If this isn’t what you want, you have to calculate the value manually from projection_data

property top_center: Vec2

Get the top most position the camera can see

property top_left: Vec2

Get the top left most corner the camera can see

property top_right: Vec2

Get the top right most corner the camera can see

unproject(screen_coordinate: tuple[float | int, float | int] | Vec2 | tuple[float | int, float | int, float | int] | Vec3) Vec3[source]

Take in a pixel coordinate from within the range of the window size and returns the world space coordinates.

Essentially reverses the effects of the projector.

Parameters:

screen_coordinate – A 2D or 3D position in pixels from the bottom left of the screen.

Returns:

A 3D vector in world space (same as sprites). perfect for finding if the mouse overlaps with a sprite or ui element irrespective of the camera.

property up: Vec2

A 2D vector which describes what is mapped to the +Y direction on screen. This is equivalent to rotating the screen. The base vector is 3D, but this camera only provides a 2D view.

update_values(value: Rect, viewport: bool = True, projection: bool = True, scissor: bool = True, position: bool = False, aspect: float | None = None)[source]

Convienence method for updating the viewport, projection, position and a few others with the same value.

Parameters:
  • value – The rect that the values will be derived from.

  • viewport – Flag whether to equalise the viewport to the value.

  • projection – Flag whether to equalise the size of the projection to match the value.

  • fixed (The projection center stays)

  • size. (and the new projection matches only in)

  • scissor – Flag whether to update the scissor value.

  • position – Flag whether to also center the camera to the value. Off by default

  • aspect – The ratio between width and height that the value should be constrained to. i.e. for an aspect ratio of 4:3 you should input 4.0/3.0 or 1.33333.... Cannot be equal to zero. If unset then the value will not be updated.

use() None[source]

Set internal projector as window projector, and set the projection and view matrix. call every time you want to ‘look through’ this camera.

If you want to use a ‘with’ block use activate() instead.

property view_data: CameraData

The view data for the camera.

This includes:

  • the position

  • forward vector

  • up direction

  • zoom.

Camera controllers use this property.

viewport: Rect

A rect which describes how the final projection should be mapped from unit-space. defaults to the size of the render_target or window

property viewport_bottom: int

The bottom most pixel drawn to on the Y axis.

property viewport_height: int

The height of the viewport. Defines the number of pixels drawn too vertically.

property viewport_left: int

The left most pixel drawn to on the X axis.

property viewport_right: int

The right most pixel drawn to on the X axis.

property viewport_top: int

The top most pixel drawn to on the Y axis.

property viewport_width: int

The width of the viewport. Defines the number of pixels drawn too horizontally.

property width: float

The width of the projection from left to right. This is in world space coordinates not pixel coordinates.

Note

this IS scaled by zoom. If this isn’t what you want, you have to calculate the value manually from projection_data

property zoom: float

A scalar value which describes how much the projection should be scaled towards from its center.

A value of 2.0 causes the projection to be half its original size. This causes sprites to appear 2.0x larger.