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