CameraFocus

Description

sealed class Tinman.Engine.Scenes.Entities.CameraFocus

Derived from

SceneEntityBase abstract

A scene entity that focuses cameras onto a given set of things of interest.

Public / Constructors

Camera​Focus

public constructor CameraFocus → (2)

pointsOfInterest in : PointsOfInterest

[not-null]
The points of interest.

order opt : int32 = 0

See ISceneObject.Order.

Creates a new instance of PointsOfInterest.

Public / Methods

Add

public method Add → (1)

focus in : ICameraFocus

[not-null]
The camera focus target to add.

returns → CameraFocus

this

Adds the given camera focus target.

Apply

public static method Apply → (4)

pointsOfInterest in : PointsOfInterest

[not-null]
The points of interest that represents the scene regions to focus.

cameraFocus in : ICameraFocus

[not-null]
The ICameraFocus to update, in order to focus on pointsOfInterest in.

center in : Vec3D

The center point to focus at. If Vec3D.Undefined, Box3D.Center of PointsOfInterest.ComputeBounds will be used.

scale opt : float64 = 0.75

[>0]
Optional scale factor to apply. The value 1 will fit the pointsOfInterest in exactly into the view cone of the camera. Smaller values will extend the viewport, larger values will shrink the viewport.

returns → bool

true if camera associated with cameraFocus in was modified,
false if the camera was not affected by this call.

Updates the given cameraFocus in object to make it focus on the specified pointsOfInterest in.

The camera focus is applied by performing the following steps:

  1. If center in is Vec3D.Undefined, use Box3D.Center of PointsOfInterest.ComputeBounds of pointsOfInterest in instead.

  2. Call ICameraFocus.FocusCenter passing center in. This will adjust the camera so that it looks at the center point.

  3. Call ICameraFocus.FocusCone to obtain the view cone of the (adjusted) camera and scale the returned cone opening angle with scale opt.

  4. Call PointsOfInterest.ComputeOffset passing the adjusted view cone and the scaled cone opening angle. Then call ICameraFocus.FocusOffset passing the resulting offset. This will move the camera forward or backward, so that the adjusted and scaled view cone contains all points of interest.

  5. Call ICameraFocus.FocusCone to obtain the view ray of the (translated) camera, pass it to PointsOfInterest.ComputeAngle and divide the returned angle by scale opt. The resulting value is passed to ICameraFocus.FocusAngle, which adjusts the zoom level of the camera.

public method Apply → ()

returns → bool

true if one or more ICameraFocus objects have been adjusted,
false false if no camera adjustment took place.

Applies the camera focus.

This method is called from IUpdateableFrameTime.UpdateFrameTime, so there is usually no need to call it directly. However, when ISceneObject.Enabled is set to false, this method may be called to apply the camera focus a single time, instead of repeatedly during animation.

The camera focus is applied by iterating over the list of configured ICameraFocus objects (see Add and Remove) and delegating to the static method Apply.

Clear

public method Clear → ()

Removes all camera focus targets.

Remove

public method Remove → (1)

focus in : ICameraFocus

[not-null]
The camera focus target to remove.

returns → CameraFocus

this

Removes the given camera focus target.

Public / Attributes

Scale

public attribute Scale → (get,set)

value : float64

[>0]
The scale factor to apply to the camera view cone angle.

Specifies the scale factor to use when calling the Apply.

Defaults to 0.75.

See also

CameraFocus.Apply

Target

[Constant]
public attribute Target → (get)

value : PointsOfInterest

[not-null]
The target points of interest.

Returns the target points of this camera focus helper.