dao::camera
Smooth camera moves: panning to a creature, turning behind it, easing the zoom.
Declared in dao/Camera.h.
Classes
| Class | |
|---|---|
| Projection | The projection the scene is drawn with. |
| View | A view of the world: where the eye is and which way it looks. |
Enumerations
Move
enum class Move
A kind of camera move.
| Value | |
|---|---|
Yaw |
EaseYaw. |
Pan |
PanTo. |
Zoom |
EaseZoom. |
MoveEnd
enum class MoveEnd
Why a move ended.
| Value | |
|---|---|
Arrived |
it got close enough to its target |
Player |
the player panned, turned or zoomed the camera |
Retargeted |
the camera started following something else |
Replaced |
a new move of the same kind replaced it |
Stopped |
Stop was called. |
NoCamera |
the camera is gone: a menu, a conversation, a cutscene or loading |
Functions
CloseDistance()
float CloseDistance()
Returns the camera’s distance from its pivot at full zoom, in metres, or 0 if the running build of the game does not support it.
Current()
CameraController * Current()
Returns the camera controller in explore or combat mode, the only modes in which the camera moves.
Returns null in any other mode (a menu, a conversation, a cutscene, loading) or before the game has started
CurrentProjection()
std::optional<Projection> CurrentProjection()
Returns the projection the scene is drawn with.
Returns nullopt with no scene drawn, or off the game thread
CurrentView()
std::optional<View> CurrentView()
Returns the view the scene is drawn from now: where a free view starts.
Call on the game thread.
Returns nullopt with no scene camera
EaseYaw()
void EaseYaw(float radians, float seconds)
Turns the camera to a yaw, in the close view.
| Parameter | |
|---|---|
radians |
the yaw to turn to, measured as SceneCamera::Yaw is |
seconds |
how long the turn takes to all but arrive; it starts quickly and slows into place |
EaseZoom()
void EaseZoom(float zoom, float seconds)
Zooms the camera, as the mouse wheel does.
Below 0.75 the game switches to the tactical view, where the camera does not follow a change of target, so stay at 0.75 or above to remain in the close view. Does nothing if there is no camera (see Current).
| Parameter | |
|---|---|
zoom |
the zoom to reach, on SceneCamera::Zoom’s scale from 1 (close behind the creature) to 0 (the tactical view high above); clamped to 0..1 |
seconds |
how long the zoom takes to all but arrive |
FieldOfView()
std::optional<float> FieldOfView()
Returns the field of view the scene is drawn with: the vertical angle, top to bottom, in degrees.
The horizontal one follows from the window’s shape.
Returns nullopt with no scene drawn, or off the game thread
LastEnd()
std::optional<MoveEnd> LastEnd(Move move)
Returns why the last move of a kind ended.
Returns nullopt while a move of that kind is running, or before the first one
Moving()
bool Moving()
Returns true while any move is running.
Name()
std::string_view Name(MoveEnd why)
Returns a short lower-case name for a reason, for logs, such as “arrived” or “the player”.
OnMoveEnded()
void OnMoveEnded(std::function<void(Move move, MoveEnd why)> callback)
Registers a callback for when a move ends.
The callback runs on the game thread after the move has released the camera, so it may start another move.
| Parameter | |
|---|---|
callback |
called with the kind of move and why it ended |
OnTargetChanged()
void OnTargetChanged(std::function<void(ObjectId now, ObjectId before)> callback)
Registers a callback for when the camera starts following a different object: the player selecting another party member, or a plugin calling Follow or PanTo.
The callback runs on the game thread after the game has handled the change: in the tactical view the camera has stayed where it was, and in the close view the game’s pan has begun. If the callback makes the camera follow something else, it is called again for that change.
| Parameter | |
|---|---|
callback |
called with the object followed now and the one followed before |
PanTo()
void PanTo(ObjectId object, float seconds)
Makes the camera follow an object and glides the focus onto it.
In the tactical view the camera only slides, keeping its height and yaw. In the close view the game itself pans to an object within 15 m and cuts to one farther away, so the move reports Arrived on its first frame while the game’s own pan is still running. Selecting the same creature during the pan does not stop it; selecting another does. To tell whether a pan fell short, check CameraController::FocusOffset or LastEnd, not Focus. Does nothing if there is no camera (see Current).
| Parameter | |
|---|---|
object |
the object to follow, usually a creature |
seconds |
how long the glide takes to all but arrive |
PlayerZoomed()
bool PlayerZoomed()
Returns true if the player has zoomed since the last EaseZoom, either during it or after it arrived.
Returns false before the first EaseZoom.
SetCloseDistance()
void SetCloseDistance(std::optional<float> metres)
Sets the camera’s distance from its pivot at full zoom (1); the game’s default is 3.0.
A larger distance pulls the camera back at the same zoom without switching to the tactical view, which helps frame a creature too big for the default. In the close view the game pulls the camera in toward its pivot when a wall or the ground is in the way. Call on the game thread.
| Parameter | |
|---|---|
metres |
the distance, or nullopt to restore the game’s own |
SetFieldOfView()
void SetFieldOfView(std::optional<float> degrees)
Holds the field of view the scene is drawn with, until it is given back.
It holds through the game’s own changes to it, conversations’ and cutscenes’ among them, and from one area to the next. Call on the game thread.
| Parameter | |
|---|---|
degrees |
the vertical angle, top to bottom, from 1 to 179; nullopt gives back the game’s |
SetFreeView()
bool SetFreeView(std::optional<View> view)
Draws the scene from a view of the plugin’s own, until given back: the game’s fly camera, the camera loose from the party, placed where the view says each time this is called.
Call it each frame from a frame callback while the view holds. The game’s mode becomes GameMode::FlyCam a frame after the first call, and its own fly camera keys are withheld; a plugin moves the view itself, for example from dao::input’s readings. The world’s pick and dao::world::ToScreen follow the drawn view. A script that changes the game’s mode ends the free view: the game goes to that mode, and the next call returns false. Given back, the game’s camera returns to where it was. Call on the game thread.
| Parameter | |
|---|---|
view |
the view, or nullopt to give the camera back to the mode the game was in |
Returns false, with nothing changed, if the game is not exploring or fighting when a free view begins, or has no camera; false too once the game has left the free view on its own
Stop()
void Stop()
Stops every running move where it is; each one ends with MoveEnd::Stopped.
YawBehind()
std::optional<float> YawBehind(ObjectId object)
Returns the yaw that puts the camera behind an object, for EaseYaw.
Returns nullopt if the object has no orientation