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
zoomof zero, a negative one or one that is not a number starts atminZoominstead — seezoom.
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).
10by 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.1by 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
rectoverlaps 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 nullrect— 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
pointis on screen. For a rolled 2-D camera that is the turned rectangle the screen shows, not the box around it; otherwise whetherpointlies inside visibleBounds. -
lookAt(
Offset target) → void - Alias for setPosition.
-
moveBy(
Offset delta) → void -
Translate the camera by
deltain 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 intooutwhen 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
worldis on screen, in pixels, intoout; 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
worldPointso 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.