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
andprojection_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
- 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:skip or replace the default validation
share
camera_data
orprojection_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 therender_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 input4.0/3.0
or1.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 input4.0/3.0
or1.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.
- 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 equalright
bottom
cannot equaltop
This property raises a
ZeroProjectionDimension
exception if any axis pairs are equal. You can handle this exception as aValueError
.
- 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
- 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 input4.0/3.0
or1.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_height: int
The height of the viewport. Defines the number of pixels drawn too vertically.
- property viewport_width: int
The width of the viewport. Defines the number of pixels drawn too horizontally.