OutputCamera class

The output camera: a view of the world and the maths to draw through it.

It holds a position, a zoom and a roll, turns them into a canvas transform, converts between screen and world, and carries the post effects. It does not decide where to look. Shots are virtual cameras — entities with a VirtualCameraComponent — and the CameraBrain picks one, blends to it and writes the result here every frame.

A game with no virtual cameras can still move this by hand: with nothing to choose from, the brain leaves it alone.

In 3-D

The camera also has a depth (z), a pitch and a yaw, and a lens. With none of them set it is isPlanar — a 2-D camera — and draws, converts and culls exactly as a 2-D camera always has. Otherwise its matrices (viewMatrixInto, projectionMatrixInto, canvasMatrixInto) and screenToWorldRay describe a camera in space; screenToWorld then finds the point under the pointer on the world plane z = 0.

The camera's own axes are the world's (WorldAxes): it looks along +Z with +Y down. Its orientation is qY(yaw) · qX(pitch) · qZ(−roll) — the roll negated, because rotation turns the view, the opposite of turning the camera.

Implemented types

Constructors

OutputCamera({Offset position = Offset.zero, double zoom = 1.0, double rotation = 0.0, Size viewportSize = Size.zero, double minZoom = 0.1, double maxZoom = 10.0, double z = 0.0, double pitch = 0.0, double yaw = 0.0, CameraLens lens = const CameraLens()})
A zoom of zero, a negative one or one that is not a number starts at minZoom instead — see zoom.

Properties

effectManager → CameraEffectManager
Attach CameraEffect instances here (fade, letterbox, motion blur…).
final
hashCode → int
The hash code for this object.
no setterinherited
inSpace ↔ bool
Looking at a 3-D scene even when it looks like a 2-D camera: an orthographic view straight along an axis (an editor's front view) still sees space, not a flat level. Set by whoever points it so.
getter/setter pair
isPlanar → bool
Whether this is a plain 2-D camera: no pitch or yaw, orthographic — and not inSpace.
no setteroverride
lens ↔ CameraLens
Orthographic (2-D) or perspective, and how much it sees.
getter/setter pairoverride-getter
maxZoom ↔ double
The highest zoom setZoom, zoomBy, zoomToPoint and apply allow, and what an infinite zoom becomes (see zoom). 10 by default.
getter/setter pair
minZoom ↔ double
The lowest zoom setZoom, zoomBy, zoomToPoint and apply allow, and what a zero, negative or NaN zoom becomes (see zoom). 0.1 by default.
getter/setter pair
pitch ↔ double
Turn about the world X axis, in radians. 0 for a 2-D camera.
getter/setter pair
position ↔ Offset
Camera position in world space (x, y).
getter/setter pairoverride-getter
rotation ↔ double
Rotation in radians.
getter/setter pair
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
state → CameraState
What this camera shows, as a value.
no setter
viewportSize ↔ Size
Viewport size (set by the rendering system each frame).
getter/setter pairoverride
viewVolume → ViewVolume
What the camera sees: the visible rectangle for a 2-D camera, the frustum for one in space. The same object each time, refreshed.
no setteroverride
visibleBounds → Rect
The world area in view, as an axis-aligned box: with a roll (rotation) the screen shows a turned rectangle, and this is the box around it — what culling must keep. For a camera in space, the part of the world plane z = 0 its corners see (everything, when a corner misses it).
no setteroverride
yaw ↔ double
Turn about the world Y axis, in radians. 0 for a 2-D camera.
getter/setter pair
z ↔ double
Depth of the camera — its world z. 0 for a 2-D camera.
getter/setter pair
zoom ↔ double
Zoom level (1.0 = normal, >1 = zoom-in, <1 = zoom-out).
getter/setter pair

Methods

apply(CameraState state) → void
Shows state. Zoom is clamped to [minZoom, maxZoom].
applyTransform(Canvas canvas, Size size) → void
Apply the camera's view transform to canvas.
override
canvasMatrixInto(Matrix4 out) → void
World space → canvas pixels, the matrix applyTransform applies — for a 2-D camera exactly its translate, scale and rotate.
override
isRectVisible(Rect? rect) → bool
Whether the world rectangle rect overlaps visibleBounds — for a rolled camera the box around the screen, so a rectangle near a corner may count as visible while just off screen. A null rect — nothing known about its size — counts as visible, and an inside-out one (the bounds of something flipped) counts as the box it spans.
isVisible(Offset point) → bool
Whether the world point point is on screen. For a rolled 2-D camera that is the turned rectangle the screen shows, not the box around it; otherwise whether point lies inside visibleBounds.
lookAt(Offset target) → void
Alias for setPosition.
moveBy(Offset delta) → void
Translate the camera by delta in world units.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
orientationInto(Quaternion out) → void
The camera's orientation in the world: qY(yaw) · qX(pitch) · qZ(−roll).
projectionMatrixInto(Matrix4 out) → void
Camera space → the engine's clip space (x, y in −1..1 with y down, depth 0..1). An orthographic lens sees viewportSize / zoom world units; a perspective one its field of view.
override
reset() → void
Back to the origin at zoom 1 with no roll, depth, pitch or yaw, the default lens, and every effect removed. minZoom, maxZoom and viewportSize are kept.
screenToWorld(Offset screenPos) → Offset
The world point under screenPos. For a camera in space, the one on the world plane z = 0 (the camera's own position when it cannot see the plane).
screenToWorldRay(Offset screen, [Ray3D? out]) → Ray3D
The ray from the camera through the pixel screen: for a 2-D camera, straight ahead (+Z) from behind the world plane; for a perspective one, from the camera out through the pixel. Written into out when given.
override
setPosition(Offset newPosition) → void
Centres the view on newPosition, in world units. A brain driving this camera overwrites it every frame while it has a virtual camera.
setZoom(double newZoom) → void
Set the camera zoom, clamped to [minZoom, maxZoom].
toString() → String
A string representation of this object.
inherited
viewMatrixInto(Matrix4 out) → void
World space → the camera's own (+X right, +Y down, +Z ahead).
override
viewProjectionInto(Matrix4 out) → void
World space → clip space: projection × view.
override
worldToScreen(Offset worldPos) → Offset
Where the world point worldPos (at z = 0) is on screen.
worldToScreen3(Vector3 world, Vector3 out) → void
Where the world point world is on screen, in pixels, into out; its z is the depth (0 near .. 1 far) for a camera in space.
zoomBy(double factor) → void
Multiply the current zoom by factor.
zoomToPoint(Offset worldPoint, double targetZoom) → void
Zoom toward worldPoint so the point stays fixed on screen.

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Constants

minSafeZoom → const double
The smallest zoom the camera ever holds, whatever it is told: a zoom of 0 would divide every world size on screen by zero.