Advanced Camera Features
- class arcade.camera.data_types.ZeroProjectionDimension[source]
Bases:
ValueError
A projection’s dimensions were zero along at least one axis.
This usually happens because code tried to set one of the following:
left
equal toright
bottom
equal totop
You can handle this error as a
ValueError
.
- class arcade.camera.data_types.CameraData(position: tuple[float | int, float | int, float | int] | Vec3 = (0.0, 0.0, 0.0), up: tuple[float | int, float | int, float | int] | Vec3 = (0.0, 1.0, 0.0), forward: tuple[float | int, float | int, float | int] | Vec3 = (0.0, 0.0, -1.0), zoom: float = 1.0)[source]
Bases:
Stores position, orientation, and zoom for a camera.
This is like where a camera is placed in 3D space.
- Parameters:
position – The camera’s location in 3D space.
up – The direction which is considered “up” for the camera.
forward – The direction the camera is facing.
zoom – How much the camera is zoomed in or out.
- class arcade.camera.data_types.OrthographicProjectionData(left: float, right: float, bottom: float, top: float, near: float, far: float)[source]
Bases:
Describes an Orthographic projection.
This is by default a Left-handed system. with the X axis going from left to right, The Y axis going from bottom to top, and the Z axis going from towards the screen to away from the screen. This can be made right-handed by making the near value greater than the far value.
- Parameters:
left – Left limit of the projection
right – Right limit of the projection
bottom – Bottom limit of the projection
top – Top limit of the projection
near – Near plane
far – Far plane
- property bottom: float
The bottom-side cutoff value, which gets mapped to -y = 1.0.
Anything to the left of this value is not visible.
- far: float
The ‘farthest’ visible position along the forward direction.
It will get mapped to z = 1.0. Anything father than this value is not visible.
- property left: float
The left-side cutoff value, which gets mapped to x = -1.0.
Anything to the left of this value is not visible.
- property lrbt: tuple[float, float, float, float]
The left, right, bottom, and top values of the projection.
- near: float
The ‘closest’ visible position along the forward direction.
It will get mapped to z = -1.0. Anything closer than this value is not visible.
- class arcade.camera.data_types.PerspectiveProjectionData(aspect: float, fov: float, near: float, far: float)[source]
Bases:
Data for perspective projection.
- Parameters:
aspect – The aspect ratio of the screen (width over height).
fov – The field of view in degrees.
near – The ‘closest’ visible position along the forward direction.
far – The ‘farthest’ visible position along the forward
- far: float
” The ‘farthest’ visible position along the forward direction.
It will get mapped to z = 1.0. Anything father than this value is not visible.
- class arcade.camera.data_types.Projection(*args, **kwargs)[source]
Bases:
Protocol
Matches the data universal in Arcade’s projection data objects.
There are multiple types of projections used in games, but all the common ones share key features. This
Protocol
:Defines those shared elements
Annotates these in code for both humans and automated type checkers
The specific implementations which match it are used inside of implementations of Arcade’s
Projector
behavior. All of these projectors rely on aviewport
as well asnear
andfar
values.The
viewport
is measured in screen pixels. By default, the conventions for this are the same as the rest of Arcade and OpenGL:X is measured rightward from left of the screen
Y is measured up from the bottom of the screen
Although the
near
andfar
values are describe the cutoffs for what the camera sees in world space, the exact meaning differs between projection type.Common Projection Type
Meaning of
near
&far
Simple Orthographic
The Z position in world space
Perspective & Isometric
Where the rear and front clipping planes sit along a camera’s
CameraData.forward
vector.
- class arcade.camera.data_types.Projector(*args, **kwargs)[source]
Bases:
Protocol
Projects from world coordinates to viewport pixel coordinates.
Projectors also support converting in the opposite direction from screen pixel coordinates to world space coordinates.
The two key spatial methods which do this are:
Method
Action
Turn world coordinates into pixel coordinates relative to the origin (bottom left by default).
Convert screen pixel coordinates into world space.
The other required methods are for helping manage which camera is currently used to draw.
- 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
- unproject(screen_coordinate: tuple[float | int, float | int] | Vec2 | tuple[float | int, float | int, float | int] | Vec3) Vec3 [source]
Take in a pixel coordinate and return the associated world coordinate
Essentially reverses the effects of the projector.
- Parameters:
screen_coordinate – A 2D position in pixels should generally be inside the range of the active viewport.
- Returns:
A 3D vector in world space.
- use() None [source]
Set the GL context to use this projector and its settings.
Warning
You may be looking for:py:meth:.activate!
This method only sets rendering state for a given projector. Since it doesn’t restore any afterward, it’s easy to misuse in ways which can cause bugs or temporarily break a game’s rendering until relaunch. For reliable, automatic clean-up see the
activate()
method instead.If you are implementing your own custom projector, this method should only:
Set the Arcade
Window
’scurrent_camera
to this objectCalculate any required view and projection matrices
Set any resulting values on the current
ArcadeContext
, including the:viewport
view_matrix
projection_matrix
This method should never handle cleanup. That is the responsibility of
activate
.
- arcade.camera.data_types.duplicate_camera_data(origin: CameraData)[source]
Clone camera data
- Parameters:
origin – The camera data to clone
- arcade.camera.data_types.constrain_camera_data(data: CameraData, forward_priority: bool = False)[source]
Ensure that the camera data forward and up vectors are length one, and are perpendicular
- Parameters:
data – the camera data to constrain
forward_priority – whether up or forward gets constrained
- arcade.camera.data_types.orthographic_from_rect(rect: Rect, near: float, far: float) OrthographicProjectionData [source]
Create an orthographic projection from a rectangle.
- Parameters:
rect – The rectangle to create the projection from.
near – The near plane of the projection.
far – The far plane of the projection.
- arcade.camera.projection_functions.generate_view_matrix(camera_data: CameraData) Mat4 [source]
Using the ViewData it generates a view matrix from the pyglet Mat4 look at function
- arcade.camera.projection_functions.generate_orthographic_matrix(perspective_data: OrthographicProjectionData, zoom: float = 1.0) Mat4 [source]
Using the OrthographicProjectionData a projection matrix is generated where the size of an object is not affected by depth.
Generally keep the scale value to integers or negative powers of integers (
2^-1, 3^-1, 2^-2
, etc.) to keep the pixels uniform in size. Avoid a zoom of 0.0.
- arcade.camera.projection_functions.generate_perspective_matrix(perspective_data: PerspectiveProjectionData, zoom: float = 1.0) Mat4 [source]
Using the OrthographicProjectionData a projection matrix is generated where the size of the objects is not affected by depth.
Generally keep the scale value to integers or negative powers of integers (
2^-1, 3^-1, 2^-2
, etc.) to keep the pixels uniform in size. Avoid a zoom of 0.0.
- arcade.camera.projection_functions.project_orthographic(world_coordinate: tuple[float | int, float | int] | Vec2 | tuple[float | int, float | int, float | int] | Vec3, viewport: tuple[int, int, int, int], view_matrix: Mat4, projection_matrix: Mat4) Vec2 [source]
- arcade.camera.projection_functions.unproject_orthographic(screen_coordinate: tuple[float | int, float | int] | Vec2 | tuple[float | int, float | int, float | int] | Vec3, viewport: tuple[int, int, int, int], view_matrix: Mat4, projection_matrix: Mat4) Vec3 [source]
- arcade.camera.projection_functions.project_perspective(world_coordinate: tuple[float | int, float | int] | Vec2 | tuple[float | int, float | int, float | int] | Vec3, viewport: tuple[int, int, int, int], view_matrix: Mat4, projection_matrix: Mat4) Vec2 [source]
- arcade.camera.projection_functions.unproject_perspective(screen_coordinate: tuple[float | int, float | int] | Vec2 | tuple[float | int, float | int, float | int] | Vec3, viewport: tuple[int, int, int, int], view_matrix: Mat4, projection_matrix: Mat4) Vec3 [source]
- class arcade.camera.orthographic.OrthographicProjector(*, window: Window | None = None, view: CameraData | None = None, projection: OrthographicProjectionData | None = None, viewport: Rect | None = None, scissor: Rect | None = None)[source]
Bases:
Projector
The simplest from of an orthographic camera. Using ViewData and OrthographicProjectionData PoDs (Pack of Data) it generates the correct projection and view matrices. It also provides methods and a context manager for using the matrices in glsl shaders.
This class provides no methods for manipulating the PoDs.
The current implementation will recreate the view and projection matrices every time the camera is used. If used every frame or multiple times per frame this may be inefficient. If you suspect this is causing slowdowns profile before optimizing with a dirty value check.
Initialize a Projector which produces an orthographic projection matrix using a CameraData and PerspectiveProjectionData PoDs.
- Parameters:
window – The window to bind the camera to. Defaults to the currently active camera.
view – The CameraData PoD. contains the viewport, position, up, forward, and zoom.
projection – The OrthographicProjectionData PoD. contains the left, right, bottom top, near, and far planes.
- activate() Generator[Self, None, None] [source]
Set this camera as the current one, then undo it after.
This method is a context manager you can use inside
with
blocks. Using it this way guarantees that the old camera and its settings will be restored, even if an exception occurs:# Despite an Exception, the previous camera and its settings # will be restored at the end of the with block below: with projector_instance.activate(): sprite_list.draw() _ = 1 / 0 # Guaranteed ZeroDivisionError
- 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: OrthographicProjectionData
The OrthographicProjectionData. Is a read only property.
- 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 position in pixels from the bottom left of the screen. This should ALWAYS be in the range of 0.0 - screen size.
- Returns:
A 3D vector in world space.
- use() None [source]
Sets the active camera to this object. Then generates the view and projection matrices. Finally, the gl context viewport is set, as well as the projection and view matrices.
- property view: CameraData
The CameraData. Is a read only property.
- class arcade.camera.perspective.PerspectiveProjector(*, window: Window | None = None, view: CameraData | None = None, projection: PerspectiveProjectionData | None = None, viewport: Rect | None = None, scissor: Rect | None = None)[source]
Bases:
Projector
The simplest from of a perspective camera.
Warning
Near cutoffs for perspective projection must be greater than zero.
This prevents division by zero errors since perspective involves dividing by distance.
Using ViewData and PerspectiveProjectionData PoDs (Pack of Data) it generates the correct projection and view matrices. It also provides methods and a context manager for using the matrices in glsl shaders.
This class provides no methods for manipulating the PoDs.
The current implementation will recreate the view and projection matrices every time the camera is used. If used every frame or multiple times per frame this may be inefficient. If you suspect this is causing slowdowns profile before optimizing with a dirty value check.
Initialize a Projector which produces a perspective projection matrix using a CameraData and PerspectiveProjectionData PoDs.
- Parameters:
window – The window to bind the camera to. Defaults to the currently active camera.
view – The CameraData PoD. contains the viewport, position, up, forward, and zoom.
projection – The PerspectiveProjectionData PoD. contains the field of view, aspect ratio, and then near and far planes.
- activate() Generator[Self, None, None] [source]
Set this camera as the current one, then undo it after.
This method is a context manager you can use inside
with
blocks. Using it this way guarantees that the old camera and its settings will be restored, even if an exception occurs:# Despite an Exception, the previous camera and its settings # will be restored at the end of the with block below: with projector_instance.activate(): sprite_list.draw() _ = 1 / 0 # Guaranteed ZeroDivisionError
- generate_projection_matrix() Mat4 [source]
Generates a projection matrix.
This is an alias of
arcade.camera.get_perspective_matrix
.
- generate_view_matrix() Mat4 [source]
Generates a view matrix.
This is an alias of=
arcade.camera.get_view_matrix
.
- project(world_coordinate: tuple[float | int, float | int] | Vec2 | tuple[float | int, float | int, float | int] | Vec3) Vec2 [source]
Convert world coordinates to pixel screen coordinates.
If a 2D
Vec2
is provided instead of a 3DVec3
, then one will be calculated to the best of the method’s ability.
- property projection: PerspectiveProjectionData
Get the
PerspectiveProjectionData
.This is a read-only property.
- unproject(screen_coordinate: tuple[float | int, float | int] | Vec2 | tuple[float | int, float | int, float | int] | Vec3) Vec3 [source]
Convert a pixel coordinate into world space.
This reverses the effects of
project()
.- Parameters:
screen_coordinate – A 2D position in pixels from the bottom left of the screen. This should ALWAYS be in the range of 0.0 - screen size.
Returns: A 3D vector in world space.
- use() None [source]
Set the active camera to this object and apply other config.
This includes the following steps:
Set the window’s current camera to this one
Generate appropriate view and projection matrices
Set the GL context’s viewport and scissorbox values
Apply the relevant matrices to Arcade’s
Window
object
- property view: CameraData
Get the internal
CameraData
.This is a read-only property. The CameraData. Is a read only property.
- class arcade.camera.default.ViewportProjector(viewport: Rect | None = None, *, context: ArcadeContext | None = None)[source]
Bases:
A simple Projector which does not rely on any camera PoDs.
Does not have a way of moving, rotating, or zooming the camera. perfect for something like UI or for mapping to an offscreen framebuffer.
- Parameters:
viewport – The viewport to project to.
context – The window context to bind the camera to. Defaults to the currently active window.
- activate() Generator[Self, None, None] [source]
The context manager version of the use method.
usable with the ‘with’ block. e.g. ‘with ViewportProjector.activate() as cam: …’
- 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
- unproject(screen_coordinate: tuple[float | int, float | int] | Vec2 | tuple[float | int, float | int, float | int] | Vec3) Vec3 [source]
Map the screen pos to screen_coordinates.
Due to the nature of viewport projector this does not do anything.
- class arcade.camera.default.DefaultProjector(*, context: ArcadeContext | None = None)[source]
Bases:
ViewportProjector
An extremely limited projector which lacks any kind of control. This is only here to act as the default camera used internally by Arcade. There should be no instance where a developer would want to use this class.
- Parameters:
context – The window context to bind the camera to. Defaults to the currently active window.
- arcade.camera.static.static_from_orthographic(view: CameraData, orthographic: OrthographicProjectionData, viewport: tuple[int, int, int, int] | None = None, *, window: Window | None = None) _StaticCamera [source]
Create a static camera from a CameraData and OrthographicProjectionData
- Parameters:
view – The view matrix to use
orthographic – The orthographic projection to use
viewport – The viewport to use
window – The window to use
- arcade.camera.static.static_from_perspective(view: CameraData, perspective: OrthographicProjectionData, viewport: tuple[int, int, int, int] | None = None, *, window: Window | None = None) _StaticCamera [source]
Create a static camera from a CameraData and PerspectiveProjectionData
- Parameters:
view – The view matrix to use
perspective – The perspective projection to use
viewport – The viewport to use
window – The window
- arcade.camera.static.static_from_raw_orthographic(projection: tuple[float, float, float, float], near: float = -100.0, far: float = 100.0, zoom: float = 1.0, position: Point3 = (0.0, 0.0, 0.0), up: Point3 = (0.0, 1.0, 0.0), forward: Point3 = (0.0, 0.0, -1.0), viewport: tuple[int, int, int, int] | None = None, *, window: Window | None = None) _StaticCamera [source]
Create a static camera from raw orthographic data.
- Parameters:
projection – The orthographic projection to use
near – The near plane
far – The far plane
zoom – The zoom level
position – The position of the camera
up – The up vector
forward – The forward vector
viewport – The viewport
window – The window
- arcade.camera.static.static_from_raw_perspective(aspect: float, fov: float, near: float = -100.0, far: float = 100.0, zoom: float = 1.0, position: Point3 = (0.0, 0.0, 0.0), up: Point3 = (0.0, 1.0, 0.0), forward: Point3 = (0.0, 0.0, -1.0), viewport: tuple[int, int, int, int] | None = None, *, window: Window | None = None) _StaticCamera [source]
Create a static camera from raw perspective data.
- Parameters:
aspect – The aspect ratio
fov – The field of view
near – The near plane
far – The far plane
zoom – The zoom level
position – The position of the camera
up – The up vector
forward – The forward vector
viewport – The viewport
window – The window
- arcade.camera.static.static_from_matrices(view: Mat4, projection: Mat4, viewport: tuple[int, int, int, int] | None, *, window: Window | None = None, project_method: Callable[[Point, tuple[int, int, int, int], Mat4, Mat4], Vec2] | None = None, unproject_method: Callable[[Point, tuple[int, int, int, int], Mat4, Mat4], Vec3] | None = None) _StaticCamera [source]
Create a static camera from raw matrices.
- Parameters:
view – The view matrix
projection – The projection matrix
viewport – The viewport
window – The window
project_method – The project method
unproject_method – The unproject method