Camera

Camera

This class represents a view into a 3D scene and how that view should map to a 2D rendering surface.

Constructor

new Camera(fovopt, aspectopt, nearopt, faropt)

Parameters:
Name Type Attributes Default Description
fov number <optional>
45

The full vertical angle of view, in degrees.

aspect number <optional>
1

Aspect ratio of the 3D canvas used.

near number <optional>
1

Near plane clip distance.

far number <optional>
1000

Far plane clip distance.

Members

(static) Inside

Intersection response from camera.intersect

(static) Intersects

Intersection response from camera.intersect

(static) Outside

Intersection response from camera.intersect

(static) Parallel

Projection mode for parallel/ortographic frustum

(static) Perspective

Projection mode for perspective frustum

Methods

checkInverseModelView()

Update the inverse modelView matrix if necessary.

checkInverseModelViewProjection()

Update the inverse modelViewProjection matrix if necessary.

checkModelView()

Update the modelView matrix if necessary.

checkModelViewProjection()

Update the modelViewProjection matrix if necessary.

checkProjection()

Update the projection matrix if necessary.

contains(bound) → {number}

Checks a bounding volume against the planes of this camera's frustum and returns if it is completely inside of, outside of, or intersecting.
Example returns are Camera.Inside, Camera.Outside or Camera.Intersects.

Parameters:
Name Type Description
bound BoundingVolume

The BoundingVolume to check for culling.

copy(source)

Copy the settings of a source camera to this camera.

Parameters:
Name Type Description
source Camera

getFarPlaneDepth()

getFrustumCoordinates(worldPosition, storeopt) → {Vector3}

Converts a position in world coordinate space to a x, y, z frustum position using the current settings of this camera.

Parameters:
Name Type Attributes Description
worldPosition Vector3

the position in space to retrieve frustum coordinates for.

store Vector3 <optional>

Use to avoid object creation. if not null, the results are stored in the given vector and returned.
Otherwise, a new vector is created.

getNearPlaneDepth()

getNormalizedDeviceCoordinates(worldPosition, storeopt) → {Vector3}

Converts a position in world coordinate space to normalized device coordinates by applying the modelViewProjection from this camera.

Parameters:
Name Type Attributes Description
worldPosition Vector3

The position in space to retrieve coordinates for.

store Vector3 <optional>

Use to avoid object creation. If not null, the results are stored in the given vector and returned.
Otherwise, a new vector is created.

getPickRay(screenX, screenY, screenWidth, screenHeight, storeopt) → {Ray}

Calculate a Pick Ray using the given screen position at the near plane of this camera and the camera's position in space.

Parameters:
Name Type Attributes Description
screenX number

The screen x position.

screenY number

The screen y position.

screenWidth number

The screen width.

screenHeight number

The screen height.

store Ray <optional>

The Ray to store the result in. If null, a new Ray is created and returned.

getProjectionMatrix() → {Matrix4}

getScreenCoordinates(worldPosition, screenWidth, screenHeight, storeopt) → {Vector3}

Converts a position in world coordinate space to an x, y screen position and non linear depth value using the current settings of this camera.

Parameters:
Name Type Attributes Description
worldPosition Vector3

The position in world space to retrieve screen coordinates for.

screenWidth number

The screen width.

screenHeight number

The screen height.

store Vector3 <optional>

Use to avoid object creation. if not null, the results are stored in the given vector and returned. Otherwise, a new vector is
created.

getViewInverseMatrix() → {Matrix4}

getViewMatrix() → {Matrix4}

getViewport()

getViewProjectionInverseMatrix() → {Matrix4}

getViewProjectionMatrix() → {Matrix4}

getWorldCoordinates(screenX, screenY, screenWidth, screenHeight, zDepth, storeopt) → {Vector3}

Converts a local x, y screen position and depth value to world coordinates based on the current settings of this camera.

Parameters:
Name Type Attributes Description
screenX number

The screen x position (x=0 is the leftmost coordinate of the screen).

screenY number

The screen y position (y=0 is the top of the screen).

screenWidth number

The screen width.

screenHeight number

The screen height.

zDepth number

The href="http://www.sjbaker.org/steve/omniv/love\_your\_z\_buffer.html">www.sjbaker.org/steve/omniv/love\_your\_z\_buffer.html non linear depth between 0 and 1 into the camera view. 0 indicates the near plane of the camera and 1 indicates the far plane.

store Vector3 <optional>

Use to avoid object creation. If not null, the results are stored in the given vector and returned. Otherwise, a new vector is
created.

getWorldPosition(screenX, screenY, screenWidth, screenHeight, zDepth, storeopt) → {Vector3}

Converts a local x, y screen position and depth value to world coordinates based on the current settings of this camera.
This function calls getWorldCoordinates after converting zDepth to screen space.

Parameters:
Name Type Attributes Description
screenX number

The screen x position.

screenY number

The screen y position.

screenWidth number

The screen width.

screenHeight number

The screen height.

zDepth number

The depth into the camera view in world distance.

store Vector3 <optional>

Use to avoid object creation. if not null, the results are stored in the given vector and returned. Otherwise, a new vector is
created.

getWorldTransform()

lookAt(pos, worldUpVector)

A convenience method for auto-setting the frame based on a world position the user desires the camera to look at. It points the camera towards
the given position using the difference between that position and the current camera location as a direction vector and the general
worldUpVector to compute up and left camera vectors.

Parameters:
Name Type Description
pos Vector3

Where to look at in terms of world coordinates.

worldUpVector Vector3

A vector indicating the up direction of the world. (often Vector3.UNIT_Y or Vector3.UNIT_Z).

normalize()

Ensure our up, left and direction are unit-length vectors.

onFrameChange()

Updates the values of the world planes associated with this camera.

onFrustumChange()

Updates internal frustum coefficient values to reflect the current frustum plane values.
This is an optimization to move normalization/rotation of plane normals out to be done
only when the frustum values change.

pack(sceneBounds)

Compress this camera's near and far frustum planes to be smaller if possible,
using the given bounds as a measure.

Parameters:
Name Type Description
sceneBounds BoundingVolume

The scene bounds.

setFrame(location, left, up, direction)

Sets the location and the left, up and direction axes of the camera.

Parameters:
Name Type Description
location Vector3
left Vector3
up Vector3
direction Vector3

setFrustum(near, far, left, right, top, bottom, aspect)

Sets the frustum plane values of this camera using the given values.

Parameters:
Name Type Description
near number
far number
left number
right number
top number
bottom number
aspect number

setFrustumPerspective(fov, aspect, near, far)

Sets the frustum plane values of this camera using the given perspective values.

Parameters:
Name Type Description
fov number

The full angle of view on the Y axis, in degrees.

aspect number

The aspect ratio of our view (generally in [0, 1]). Often this is canvas width / canvas height.

near number

Near plane value

far number

Far plane value

setProjectionMatrixPerspective(projectionMatrix)

Sets the frustum plane values of this camera based on the provided projection matrix. Assumes the provided
matrix is a standard opengl perspective projection as described in: http://www.songho.ca/opengl/gl_projectionmatrix.html.
Has no effect if the camera is not using the Camera.Perspective projection mode.

Parameters:
Name Type Description
projectionMatrix Matrix4

setProjectionMode(projectionMode)

Sets the projection mode of the camera. (Camera.Perspective / Camera.Parallel)

Parameters:
Name Type Description
projectionMode ProjectionMode

The new projection mode - Camera.Perspective or Camera.Parallel

setToObliqueMatrix(clipPlane)

Clip using an oblique frustum different from the view frustum

Parameters:
Name Type Description
clipPlane Vector4

Clipping plane. (nx, ny, nz, constant)

setViewMatrix(viewMatrix)

Sets the location and the left, up and direction axes of the camera
based on the provided view matrix. Derived from: http://ksimek.github.io/2012/08/22/extrinsic/

Parameters:
Name Type Description
viewMatrix Matrix4

update()

Forces all aspect of the camera to be updated from internal values, and sets all dirty flags to true so that the next apply() call will fully
set this camera to the render context.

updateModelViewMatrix()

Updates the value of our model view matrix.

updateProjectionMatrix()

Updates the value of our projection matrix.