Table Of Contents

Previous topic

21.5. The BoxTree Object

Next topic

21.8. The Canvas Object

This Page

21.6. The Camera Object

Provides functionality for a 3D camera.

This object calculates view, projection and combined transforms for a right-handed coordinate system. It can also calculate frustum planes that can be used for visibility queries.

Required scripts

The Camera and CameraController objects require:

/*{{ javascript("jslib/camera.js") }}*/

21.6.1. Constructor

21.6.1.1. create

Summary

Creates and returns a camera object with default values.

Syntax

var mathDevice = TurbulenzEngine.createMathDevice({});
var camera = Camera.create(mathDevice);

21.6.2. Methods

21.6.2.1. lookAt

Summary

Sets the camera matrix to look at the specified 3D point in world space from another one.

Syntax

camera.lookAt(target, up, origin);
camera.updateViewMatrix();
camera.updateViewProjectionMatrix();
target
A Vector3 object giving a world space position for the camera to look at.
up
A Vector3 object used to compute the roll of the camera. This vector will be normalized as a side effect of this function.
origin
A Vector3 object giving the world space position of the camera.

21.6.2.2. updateViewMatrix

Summary

Updates the camera viewMatrix. Should be called anytime the camera matrix is updated.

Syntax

camera.matrix = mathDevice.m43FromAxisRotation(up, angle);
camera.updateViewMatrix();

21.6.2.3. updateProjectionMatrix

Summary

Updates the camera projectionMatrix. Should be called any time the frustum parameters are changed.

Syntax

var aspectRatio = (deviceWidth / deviceHeight);
if (aspectRatio !== camera.aspectRatio)
{
    camera.aspectRatio = aspectRatio;
    camera.updateProjectionMatrix();
}

21.6.2.4. updateViewProjectionMatrix

Summary

Updates the camera viewProjectionMatrix. Should be called any time the camera matrix or the frustum parameters are changed.

Syntax

camera.matrix = mathDevice.m43FromAxisRotation(up, angle);
camera.updateViewMatrix();

var aspectRatio = (deviceWidth / deviceHeight);
if (aspectRatio !== camera.aspectRatio)
{
    camera.aspectRatio = aspectRatio;
    camera.updateProjectionMatrix();
}

camera.updateViewProjectionMatrix();

21.6.2.5. updateFrustumPlanes

Summary

Updates the camera frustum planes. Required if the camera frustum planes are used after the camera matrix or the frustum parameters have been changed.

Syntax

camera.updateFrustumPlanes();
var frustumPlanes = camera.frustumPlanes;
var isVisible = mathDevice.isInsidePlanesAABB(extents, frustumPlanes);

21.6.2.6. extractFrustumPlanes

Summary

Returns an array with the camera frustum planes. This function is used by updateFrustumPlanes to build the camera frustum planes.

Syntax

camera.matrix = mathDevice.m43FromAxisRotation(up, angle);
camera.updateViewMatrix();
camera.updateViewProjectionMatrix();
var frustum1 = camera.extractFrustumPlanes();

camera.lookAt(target, up, origin);
camera.updateViewMatrix();
camera.updateViewProjectionMatrix();
var frustum2 = camera.extractFrustumPlanes();

Returns an array of 6 Plane objects.

21.6.2.7. getFrustumPoints

Summary

Returns an array with the 8 points in world units that define the camera frustum. Useful for calculating a bounding volume of the camera frustum.

Syntax

camera.updateViewProjectionMatrix();
var frustumPoints = camera.getFrustumPoints();
var sphere = calculateBoundingSphere(frustumPoints);

Returns a JavaScript array of 8 points. Each point is represented as JavaScript array of 3 components.

21.6.2.8. getFrustumFarPoints

Summary

Returns an array with the 4 points in world units of the far plane of the camera frustum. Useful for calculating simple intersections of the camera frustum with other volumes.

Syntax

camera.updateViewProjectionMatrix();
var farPlanePoints = camera.getFrustumFarPoints();

Returns a JavaScript array of 4 points. Each point is represented as JavaScript array of 3 components.

21.6.2.9. isVisibleAABB

Summary

Returns true if the given axis-aligned bounding box is visible from the camera.

Syntax

camera.updateFrustumPlanes();
var isVisible = camera.isVisibleAABB(extents);
extents
The extents of the bounding box.

21.6.3. Properties

21.6.3.1. version

Summary

The version number of the Camera implementation.

Syntax

var cameraVersionNumber = camera.version;

21.6.3.2. viewOffsetX and viewOffsetY

Summary

Shear offsets of the camera frustum. Default to zero.

Syntax

camera.viewOffsetX = 0.1;

21.6.3.3. recipViewWindowX and recipViewWindowY

Summary

Reciprocals to set the field of view of the camera frustum. Default to 1.0.

Syntax

var horizontalFOV = 120;
var degreesToradians = (Math.PI / 180);
camera.recipViewWindowX = 1.0 / Math.tan((horizontalFOV * 0.5) * degreesToradians);

21.6.3.4. infinite

Summary

Sets the far plane of the camera frustum at infinity when true, it effectively disables clipping by that plane. Defaults to false.

Syntax

camera.infinite = true;

21.6.3.5. parallel

Summary

Sets the camera frustum as an orthographic projection. Defaults to false.

Syntax

camera.parallel = true;

21.6.3.6. aspectRatio

Summary

Sets the aspect ratio of the camera frustum. Defaults to 4.0 / 3.0.

Syntax

camera.aspectRatio = 16.0 / 9.0;

21.6.3.7. nearPlane

Summary

Sets the distance in world units from the camera position to the near plane of the camera frustum. Setting the near plane to a value lower than 1 can severely degrade the precision of the Z-buffer. Defaults to 1.0.

Syntax

camera.nearPlane = 4.0;

21.6.3.8. farPlane

Summary

Sets the distance in world units from the camera position to the far plane of the camera frustum. Defaults to 1000.0.

Syntax

camera.farPlane = 3000.0;

21.6.3.9. matrix

Summary

Sets the Matrix43 object that defines the position and orientation of the camera in world space. Defaults to the identity matrix.

Syntax

camera.matrix = mathDevice.m43FromAxisRotation(up, angle);

21.6.3.10. viewMatrix

Summary

The Matrix43 that defines the transform from world space to the camera space. It is effectively the inverse of the camera matrix. Not recommended to be updated by hand, it is better to call the method updateViewMatrix when the camera matrix is changed.

Syntax

var viewMatrix = camera.viewMatrix;

21.6.3.11. projectionMatrix

Summary

The Matrix44 that defines the projection from camera space into screen space. Not recommended to be updated by hand, it is better to call the method updateProjectionMatrix when the frustum parameters are changed.

Syntax

var projectionMatrix = camera.projectionMatrix;

21.6.3.12. viewProjectionMatrix

Summary

The Matrix44 that defines the transform from world space to the projected screen space. Not recommended to be updated by hand, it is better to call the method updateViewProjectionMatrix when the camera matrix or the frustum parameters are changed.

Syntax

var viewProjectionMatrix = camera.viewProjectionMatrix;

21.6.3.13. frustumPlanes

Summary

The array of planes that defines the camera frustum. Not recommended to be updated by hand, it is better to call the method updateFrustumPlanes when the camera matrix or the frustum parameters are changed.

Syntax

var frustumPlanes = camera.frustumPlanes;
var isVisible = mathDevice.isInsidePlanesAABB(extents, frustumPlanes);

21.7. The CameraController Object

Provides functionality for a fly camera controlled by mouse and keyboard. Click on the engine window to enable input capture.

The arrow keys move the camera forwards, backwards, to the left and to the right. The keys W, S, A and D work as the arrow keys. The keys E and Q work as up and down keys. The key enter switches between fullscreen and windowed mode. The mouse movements rotate the camera and rolling the mouse is a quick forward movement. Press the escape key to release the input devices.

21.7.1. Constructor

21.7.1.1. create

Summary

Creates and returns a camera object with default values.

Syntax

var cameraController = CameraController.create(graphicsDevice, inputDevice, camera);
graphicsDevice
The GraphicsDevice object to be set to fullscreen when pressing enter.
inputDevice
The InputDevice object that the controller is going to be attached to.
camera
The Camera object to be controlled.

21.7.2. Methods

21.7.2.1. update

Summary

Updates the camera according to the input events.

Syntax

inputDevice.update();
cameraController.update();

21.7.3. Properties

21.7.3.1. version

Summary

The version number of the CameraController implementation.

Syntax

var cameraVersionNumber = cameraController.version;

21.7.3.2. maxSpeed

Summary

The maximum movement speed for each frame. Defaults to 1.0.

Syntax

cameraController.maxSpeed = (deltaTime * maxSceneSpeed);

21.7.3.3. rotateSpeed

Summary

The rotation speed factor. Defaults to 2.0.

Syntax

cameraController.rotateSpeed = 1.0;

21.7.3.4. mouseRotateFactor

Summary

The mouse rotation speed factor. Defaults to 0.1.

Syntax

cameraController.mouseRotateFactor = 1.0;