ThreeJS Cameras

ArrayCamera

ArrayCamera can be used to render a scene using a preset group of cameras quickly. This is an important feature of VR scene rendering performance.

An array of sub cameras is always present in an instance of ArrayCamera. The viewport attribute, which defines which part of the viewport is rendered with this camera, must be defined for each sub camera.

Constructor

ArrayCamera( array : Array )

An array of cameras.

Properties and Methods

See the base PerspectiveCamera class for common properties and methods.

.cameras : Array

An array of cameras.

Camera

Cameras have an abstract base class. When creating a new camera, you should always inherit this class.

Constructor

Camera()

Creates a new Camera. Note that this class is not intended to be called directly; you probably want a PerspectiveCamera or OrthographicCamera instead.

Properties and Methods

It inherits the properties and methods from Object3D class that we will talk about in the next articles. The unique properties and methods are as follows:

.layers : Layers

The layers that the camera is a member of. This is an inherited property from Object3D.

Objects must share at least one layer with the camera to be seen when the camera's viewpoint is rendered.

.matrixWorldInverse : Matrix4

This is matrixWorld's inverse. MatrixWorld contains the Matrix, which contains the Camera's world transform.

.projectionMatrix : Matrix4

This is the matrix which contains the projection.

.projectionMatrixInverse : Matrix4

The inverse of projectionMatrix.

.clone ( ) : Camera

Return a new camera with the same properties as this one.

.copy ( source : Camera, recursive : Boolean ) : this

Copy the properties from the source camera into this one.

.getWorldDirection ( target : Vector3 ) : Vector3

target — the result will be copied into this Vector3.

Returns a Vector3 representing the world space direction in which the camera is looking. (Note: A camera looks down its local, negative z-axis).

CubeCamera

Creates 6 cameras that render to a WebGLCubeRenderTarget.

Code Example:

// Create cube render target
const cubeRenderTarget = new THREE.WebGLCubeRenderTarget( 128, { format: THREE.RGBFormat, generateMipmaps: true, minFilter: THREE.LinearMipmapLinearFilter } );


// Create cube camera
const cubeCamera = new THREE.CubeCamera( 1, 100000, cubeRenderTarget );
scene.add( cubeCamera );


// Create car
const chromeMaterial = new THREE.MeshLambertMaterial( { color: 0xffffff, envMap: cubeRenderTarget.texture } );
const car = new Mesh( carGeometry, chromeMaterial );
scene.add( car );


// Update the render target cube
car.visible = false;
cubeCamera.position.copy( car.position );
cubeCamera.update( renderer, scene );


// Render the scene
car.visible = true;
renderer.render( scene, camera );

Constructor

CubeCamera( near : Number, far : Number, renderTarget : WebGLCubeRenderTarget )

near -- The near clipping distance.

far -- The far clipping distance.

renderTarget -- The destination cube render target.

Constructs a CubeCamera that contains 6 PerspectiveCameras that render to a WebGLCubeRenderTarget.

Properties and Methods

The properties and methods are inherited from the Object3D class, the unique ones are as follows:

.renderTarget : WebGLCubeRenderTarget

The destination cube render target.

.update ( renderer : WebGLRenderer, scene : Scene ) : undefined

renderer -- The current WebGL renderer

scene -- The current scene

Call this to update the renderTarget.

OrthographicCamera

A camera that makes use of orthographic projection.

The size of an object in the rendered image remains constant regardless of its distance from the camera in this projection mode.

This can be useful for rendering 2D scenes and user interface elements, among other things.

Code Example:

const camera = new THREE.OrthographicCamera( width / - 2, width / 2, height / 2, height / - 2, 1, 1000 );
scene.add( camera );

Constructor

OrthographicCamera( left : Number, right : Number, top : Number, bottom : Number, near : Number, far : Number )

left — Camera frustum left plane.

right — Camera frustum right plane.

top — Camera frustum top plane.

bottom — Camera frustum bottom plane.

near — Camera frustum near plane.

far — Camera frustum far plane.

Properties

It inherits the properties from Camera class, the additional properties are as follows:

.bottom : Float

Camera frustum bottom plane.

.far : Float

Camera frustum far plane. Default is 2000.

Must be greater than the current value of near plane.

.left : Float

Camera frustum left plane.

.near : Float

Camera frustum near plane. Default is 0.1.

The valid range is between 0 and the current value of the far plane. Note that, unlike for the PerspectiveCamera, 0 is a valid value for an OrthographicCamera's near plane.

.right : Float

Camera frustum right plane.

.top : Float

Camera frustum top plane.

.view : Object

Set by setViewOffset. Default is null.

.zoom : number

Gets or sets the zoom factor of the camera. Default is 1.

Methods

The methods are inherited from the Camera class and the additional methods are as follows:

.setViewOffset ( fullWidth : Float, fullHeight : Float, x : Float, y : Float, width : Float, height : Float ) : undefined

fullWidth — full width of multiview setup

fullHeight — full height of multiview setup

x — horizontal offset of subcamera

y — vertical offset of subcamera

width — width of subcamera

height — height of subcamera

Sets an offset in a larger viewing frustum. This is useful for multi-window or multi-monitor/multi-machine setups. For an example on how to use it see PerspectiveCamera.

.clearViewOffset () : undefined

Removes any offset set by the .setViewOffset method.

.updateProjectionMatrix () : undefined

Updates the camera projection matrix. Must be called after any change of parameters.

.toJSON (meta : Object) : Object

meta -- object containing metadata such as textures or images in objects' descendants.

Convert the camera to three.js JSON Object/Scene format.

PerspectiveCamera

A camera with perspective projection.

This projection mode is intended to simulate how the human eye sees. It is the most widely used projection mode for rendering a 3D scene.

Code Example:

const camera = new THREE.PerspectiveCamera( 45, width / height, 1, 1000 );
scene.add( camera );

Constructor

PerspectiveCamera( fov : Number, aspect : Number, near : Number, far : Number )

fov — Camera frustum vertical field of view.

aspect — Camera frustum aspect ratio.

near — Camera frustum near plane.

far — Camera frustum far plane.

Properties

The properties are inherited from the Camera class and the additional properties are as follows:

.aspect : Float

Camera frustum aspect ratio, usually the canvas width / canvas height. Default is 1 (square canvas).

.far : Float

Camera frustum far plane. Default is 2000.

Must be greater than the current value of near plane.

.filmGauge : Float

Film size used for the larger axis. Default is 35 (millimeters). This parameter does not influence the projection matrix unless .filmOffset is set to a nonzero value.

.filmOffset : Float

Horizontal off-center offset in the same unit as .filmGauge. Default is 0.

.focus : Float

Object distance used for stereoscopy and depth-of-field effects. This parameter does not influence the projection matrix unless a StereoCamera is being used. Default is 10.

.fov : Float

Camera frustum vertical field of view, from bottom to top of view, in degrees. Default is 50.

.near : Float

Camera frustum near plane. Default is 0.1.

The valid range is greater than 0 and less than the current value of the far plane. Note that, unlike for the OrthographicCamera, 0 is not a valid value for a PerspectiveCamera's near plane.

.view : Object

Frustum window specification or null. This is set using the .setViewOffset method and cleared using .clearViewOffset.

.zoom : number

Gets or sets the zoom factor of the camera. Default is 1.

Methods

The methods are inherited from the Camera class and the additional methods are as follows:

.clearViewOffset () : undefined

Removes any offset set by the .setViewOffset method.

.getEffectiveFOV () : Float

Returns the current vertical field of view angle in degrees considering .zoom.

.getFilmHeight () : Float

Returns the height of the image on the film. If .aspect is less than or equal to one (portrait format), the result equals .filmGauge.

.getFilmWidth () : Float

Returns the width of the image on the film. If .aspect is greater than or equal to one (landscape format), the result equals .filmGauge.

.getFocalLength () : Float

Returns the focal length of the current .fov in respect to .filmGauge.

.setFocalLength ( focalLength : Float ) : undefined

Sets the FOV by focal length in respect to the current .filmGauge.

By default, the focal length is specified for a 35mm (full frame) camera.

.setViewOffset ( fullWidth : Float, fullHeight : Float, x : Float, y : Float, width : Float, height : Float ) : undefined

fullWidth — full width of multiview setup

fullHeight — full height of multiview setup

x — horizontal offset of subcamera

y — vertical offset of subcamera

width — width of subcamera

height — height of subcamera

Sets an offset in a larger frustum. This is useful for multi-window or multi-monitor/multi-machine setups.

For example, if you have 3x2 monitors and each monitor is 1920x1080 and the monitors are in grid like this:

+---+---+---+

| A | B | C |

+---+---+---+

| D | E | F |

+---+---+---+

then for each monitor you would call it like this:

const w = 1920;
const h = 1080;
const fullWidth = w * 3;
const fullHeight = h * 2;


// A
camera.setViewOffset( fullWidth, fullHeight, w * 0, h * 0, w, h );
// B
camera.setViewOffset( fullWidth, fullHeight, w * 1, h * 0, w, h );
// C
camera.setViewOffset( fullWidth, fullHeight, w * 2, h * 0, w, h );
// D
camera.setViewOffset( fullWidth, fullHeight, w * 0, h * 1, w, h );
// E
camera.setViewOffset( fullWidth, fullHeight, w * 1, h * 1, w, h );
// F
camera.setViewOffset( fullWidth, fullHeight, w * 2, h * 1, w, h );

Note there is no reason monitors have to be the same size or in a grid.

.updateProjectionMatrix () : undefined

Updates the camera projection matrix. Must be called after any change of parameters.

.toJSON (meta : Object) : Object

meta -- object containing metadata such as textures or images in objects' descendants.

Convert the camera to three.js JSON Object/Scene format.