Class vxlCamera

Determines which region of the scene will be visible to the user.

Constructor

vxlCamera(p_view, p_type)
A vxlCamera object simplifies WebGL programming by providing a simple object interface to the lower level matrix manipulations that are required to view a 3D scene.

A vxlCamera is always associated to one vxlView object. However, one vxlView object can host multiple cameras (through its vxlCameraManager)


Author: Diego Cantor.

Parameters:

vxlView p_view

Object p_type

the type of camera

Methods

.changeAzimuth(el)
Changes the initial azimuth of the camera

Parameters:

Type Name Description
Number el

the azimuth increment in degrees

.changeElevation(el)
Changes the initial elevation of the camera

Parameters:

Type Name Description
Number el

the elevation increment in degrees

.changeRoll(rl)
Changes the initial roll of the camera

Parameters:

Type Name Description
Number rl

the roll increment in degrees

.closeUp(actor)
Performs a close up of an actor.

Parameters:

Type Name Description
String|vxlActor actor

The name of the actor or the actor object this camera will look at.

See:

Close-up (Wikipedia)
.createLandmark(name, position, focalPoint, roll)
Creates a new landmark without moving the camera. It basically defines 'future' landmarks.

Parameters:

Type Name Description
String name

the landmark given name

Array|vec3 position

the position of this landmark

Array|vec3 focalPoint

the desired focalPoint for the camera at the landmark

roll

See:

vxlLandmark
.doLandmarkAnimation(steps)
The animation map has one entry per gotoLandmark step steps = [ ['landmark_1',duration_1, fps_1], ['landmark_2',duration_2, fps_2], ... ['landmark_N,duration_N,fps_N]]; }

Parameters:

Type Name Description
steps

.dolly(value)
Performs the dollying operation in the direction indicated by the camera normal axis. The dollying mechanism offered by a camera makes sure that the camera moves fast towards the object when the distance is large and slow when it is very close to the object. For that effect, every time that the new position (after dollying) is calculated, the field dstep is computed.

Parameters:

Type Name Description
Number value

the dollying value

.follow(actor, trackingType)
Follows a given actor. If this operation is called on an ORBITING camera, the camera mode will change to be a TRACKING camera.

Parameters:

Type Name Description
vxlActor|String actor

actor to track (It can be the actor name or the actor instance)

String trackingType

one of the possible values of vxl.def.camera.tracking

See:

.getLandmarks()
Returns a list of known landmarks
mat4 .getViewTransform()
Inverts the camera mattrix to obtain the correspondent Model-View Transform

Returns:

{mat4} m the Model-View Transform
.gotoLandmark(name, length, fps)
Retrieves the landmark by name from the known landmarks

Parameters:

Type Name Description
String name

the landmark name

Number length

(optional) the duration of the animation

Number fps

(optional) the number of frames per second (estmate) two landmarks.

See:

vxlLandmark
.longShot()
The camera moves to a position where all the actors in the scene are viewed. The actors are seen in full within their surrounding environment. A long shot uses the global bounding box of the view's scene

See:

Long Shot (Wikipedia)
.lookAt(actor)
Looks at a given actor without displacing the camera

Parameters:

Type Name Description
String|vxlActor actor

The name of the actor or the actor object this camera will look at.

.pan(dx, dy)
Translates the camera side-to-side and up-and-down

Parameters:

Type Name Description
Number dx

the horizontal displacement

Number dy

the vertical displacement

.refresh()
This method updates the 3D scene This is the call stack: vxlCamera.refresh -> vxlView.refresh -> vxlRenderer.render
.rotate(azimuth, elevation, roll)
Changes the azimuth and elevation with respect to the current camera axes

Parameters:

Type Name Description
Number azimuth

the relative azimuth

Number elevation

the relative elevation

Number roll

the relative roll

.setAspectRatio(p_aspect)

Forces the aspect ratio of the camera to a certain value.

To go back to the default aspect ratio that relies on the dimensions of the view associated to this camera use: setAspectRatio(undefined)

Parameters:

Type Name Description
Number p_aspect

the new aspect ratio

.setAzimuth(el)
Sets the initial azimuth of the camera

Parameters:

Type Name Description
Number el

the azimuth in degrees

.setDistance(d)
Position the camera to a given distance from the current focal point

Parameters:

Type Name Description
Number d

the distance

.setElevation(el)
Sets the initial elevation of the camera

Parameters:

Type Name Description
Number el

the elevation in degrees

.setFieldOfView(fov)
Changes the field of view of the camera

Parameters:

Type Name Description
fov

See:

Angle of view
.setFocalPoint(x, y, z)
Looks at a given point in space (sets the focal point of this camera). Note: If the camera is doing cinematic tracking, the up vector will be affected.

Parameters:

Type Name Description
Number|Array|vec3 x

it can be the x coordinate, a 3-dimensional Array or a vec3 (glMatrix)

Number y

if x is a number, then this parameter corresponds to the y-coordinate

Number z

if x is a number, then this parameter corresponds to the z-coordinate

.setLandmark(name)
Saves the current camera state in a landmark

Parameters:

Type Name Description
String name

the landmark name

See:

vxlLandmark
.setMatrix(matrix)
Sets the camera matrix

Parameters:

Type Name Description
mat4 matrix

the new camera matrix

.setPerspective(p_near, p_far, p_angle, p_aspect)
Sets the perspective of the camera. Defines the viewing frustum and its shape

Parameters:

Type Name Description
Number p_near

the distance from the camera to the near plane

Number p_far

the distance from the camera to the far plane

Number p_angle

the vertical field of view in degrees

Number p_aspect

the desired aspect ratio (optional). If not defined the camera automatically selects the current width/height radio of the respective view.

.setPosition(y, z, z)

Sets the camera position in the scene This method has three parameters x,y,z which represent the coordinates for the camera's position.

This method takes into account the current focal point. The camera will look at the focal point after this operation. If you want to move the camera position and the focal point simultaneously, then use vxlCamera.translate.

* @param {Number, Array} x the x-coordinate. x can also be an Array [a,b,c] in this case the y and z parameters are discarded.

Parameters:

Type Name Description
Number y

the y-coordinate

Number z

the z-coordinate

z

.setRoll(angle)
Sets the initial roll of the camera Rotates the camera around its view (forward) axis

Parameters:

Type Name Description
Number angle

the roll angle

.setTrackingMode(mode)
Sets the tracking type of this camera when it follows an actor

To set the tracking type of the camera myCamera you should make sure that your camera is of tracking type with: myCamera.setType(vxl.def.camera.type.TRACKING). For instance:

 var actor = vxl.api.getActor('cone'); //from the current scene
 var camera = vxl.c.camera;
 camera.setType(vxl.def.camera.type.TRACKING);
 camera.setTrackingMode(vxl.def.camera.tracking.ROTATIONAL);
 camera.follow(actor);

a shorter way would be:

 var actor = vxl.api.getActor('cone'); //from the current scene
 var camera = vxl.c.camera;
 camera.setType(vxl.def.camera.type.TRACKING);
 camera.follow(actor, vxl.def.camera.tracking.ROTATIONAL);

Parameters:

Type Name Description
mode

See:

vxlCamera#follow, vxl.def.camera.tracking
.setType(p_type, p_tracking_mode)
Establishes the type of camera

Parameters:

Type Name Description
vxl.def.camera.type p_type

the type of camera

vxl.def.camera.tracking p_tracking_mode

if the camera is of tracking type, the tracking mode can be set as an optional parameter here.

See:

vxl.def.camera.type, vxl.def.camera.tracking
.setWorldRotation(flag)
If flag is true, it reverses the azimuth and elevation angles. Subsequent calls to rotate, setAzimuth, setElevation, changeAzimuth or changeElevation will cause the inverted effect. setRoll or changeRoll is not affected by this method. This inversion is useful when one wants to simulate that the world is moving, instead of the camera. By default the camera angles are not reversed.

Parameters:

Type Name Description
flag

.status()
Prints a summary of the camera variables on the browser's console
.stopLandmarkAnimation()
If there is a landmark based animation in progress it will stop it.
.translate(x, y, z)
Translates the camera by a given vector

Parameters:

Type Name Description
Number|Array|vec3 x

it can be the x coordinate, a 3-dimensional Array or a vec3 (glMatrix)

Number y

if x is a number, then this parameter corresponds to the y-coordinate

Number z

if x is a number, then this parameter corresponds to the z-coordinate

.unfollow()
Stops following an actor
.updatePerspective()
Updates the current perspective matrix when one of the internal perspective variables [near,far,fov] has changed, or when the view has changed its dimensions [width, height]
.updateWithActor(actor)
Updates the camera according to the current tracking mode. This method is a callback used by the vxlActor class to notify the camera of any actor transformations. This is applicable of course only when this camera is following the actor passed as parameter here

Parameters:

Type Name Description
vxlActor actor

the actor being followed by this camera