/*
* Copyright 2009, Google Inc.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are
* met:
*
* * Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* * Redistributions in binary form must reproduce the above
* copyright notice, this list of conditions and the following disclaimer
* in the documentation and/or other materials provided with the
* distribution.
* * Neither the name of Google Inc. nor the names of its
* contributors may be used to endorse or promote products derived from
* this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
/**
* @fileoverview This file contains sample code for controlling the camera
* (ie view matrix) using the mouse and keyboard.
*/
o3djs.provide('o3djs.cameracontroller');
o3djs.require('o3djs.math');
/**
* A Module for user control of the camera / view matrix.
* @namespace
*/
o3djs.cameracontroller = o3djs.cameracontroller || {};
/**
* The possible modes that a CameraController can be in.
* One of these is usually set when a mouse button is pressed down,
* and then NONE is set when the mouse button is released.
* When the mouse is moved, the DragMode determines what effect the mouse move
* has on the camera parameters (such as position and orientation).
* If the DragMode is NONE, mouse moves have no effect.
* @enum {number}
*/
o3djs.cameracontroller.DragMode = {
/**
* Dragging the mouse has no effect.
*/
NONE: 0,
/**
* Dragging left or right changes rotationAngle,
* dragging up or down changes heightAngle.
*/
SPIN_ABOUT_CENTER: 1,
/**
* Dragging up or down changes the backpedal.
*/
DOLLY_IN_OUT: 2,
/**
* Dragging up or down changes the fieldOfViewAngle.
*/
ZOOM_IN_OUT: 3,
/**
* Dragging up or down changes the amount of perspective.
* Perspective is focused on the centerPos.
* If backpedal is negative or zero, there is no effect.
*/
DOLLY_ZOOM: 4,
/**
* Dragging moves the centerPos around the plane perpendicular to
* the camera view direction.
*/
MOVE_CENTER_IN_VIEW_PLANE: 5,
};
/**
* Creates a CameraController.
* @param {!o3djs.math.Vector3} centerPos The position that the camera is
* looking at and rotating around; or if backpedal is zero, the location
* of the camera. In world space.
* @param {number} backpedal The distance the camera moves back from the
* centerPos.
* @param {number} heightAngle The angle the camera rotates up or down
* (about the x axis that passes through the centerPos). In radians.
* @param {number} rotationAngle The angle the camera rotates left or right
* (about the y axis that passes through the centerPos). In radians.
* @param {number} fieldOfViewAngle The vertical angle of the viewing frustum.
* In radians, between 0 and PI/2. This does not affect the view matrix,
* but it can still be useful to let the CameraController control the
* field of view.
* @param {function(!o3djs.cameracontroller.CameraController): void}
* opt_onChange Pointer to a callback to call when the camera changes.
* @return {!o3djs.cameracontroller.CameraController} The created
* CameraController.
*/
o3djs.cameracontroller.createCameraController = function(centerPos,
backpedal,
heightAngle,
rotationAngle,
fieldOfViewAngle,
opt_onChange) {
return new o3djs.cameracontroller.CameraController(centerPos,
backpedal,
heightAngle,
rotationAngle,
fieldOfViewAngle,
opt_onChange);
};
/**
* Class to hold user-controlled camera information and handle user events.
* It can control and output a view matrix, and can also control some aspects
* of a projection matrix.
*
* Most of the parameters it controls affect the view matrix, and it can
* generate a view matrix based on its parameters.
* It can also control certain parameters that affect the projection matrix,
* such as field of view. Rather than deal with all the parameters needed for
* a projection matrix, this class leaves generation of the projection matrix
* up to the user code, and simply exposes the parameters it has.
* @constructor
* @param {!o3djs.math.Vector3} centerPos The position that the camera is
* looking at and rotating around; or if backpedal is zero, the location
* of the camera. In world space.
* @param {number} backpedal The distance the camera moves back from the
* centerPos.
* @param {number} heightAngle The angle the camera rotates up or down
* (about the x axis that passes through the centerPos). In radians.
* @param {number} rotationAngle The angle the camera rotates left or right
* (about the y axis that passes through the centerPos). In radians.
* @param {number} fieldOfViewAngle The vertical angle of the viewing frustum.
* In radians, between 0 and PI/2. This does not affect the view matrix,
* but it can still be useful to let this class control the field of view.
* @param {function(!o3djs.cameracontroller.CameraController): void}
* opt_onChange Pointer to a callback to call when the camera changes.
*/
o3djs.cameracontroller.CameraController = function(centerPos,
backpedal,
heightAngle,
rotationAngle,
fieldOfViewAngle,
opt_onChange) {
/**
* The position that the camera is looking at and rotating around.
* Or if backpedal is zero, the location of the camera. In world space.
* @type {!o3djs.math.Vector3}
*/
this.centerPos = centerPos;
/**
* The distance the camera moves back from the centerPos.
* @type {number}
*/
this.backpedal = backpedal;
/**
* The angle the camera rotates up or down.
* @type {number}
*/
this.heightAngle = heightAngle;
/**
* The angle the camera rotates left or right.
* @type {number}
*/
this.rotationAngle = rotationAngle;
/**
* The vertical angle of the perspective viewing frustum.
* In radians, between 0 and PI/2. This does not affect the view matrix.
* The user code can access this value and use it to construct a
* projection matrix, or it can simply ignore it.
* @type {number}
*/
this.fieldOfViewAngle = fieldOfViewAngle;
/**
* Points to a callback to call when the camera changes.
* @type {function(!o3djs.cameracontroller.CameraController): void}
*/
this.onChange = opt_onChange || null;
/**
* The current mouse-drag mode, ie what happens when you move the mouse.
* @private
* @type {o3djs.cameracontroller.DragMode}
*/
this.dragMode_ = o3djs.cameracontroller.DragMode.NONE;
/**
* The last X coordinate of the mouse.
* @private
* @type {number}
*/
this.mouseX_ = 0;
/**
* The last Y coordinate of the mouse.
* @private
* @type {number}
*/
this.mouseY_ = 0;
// Some variables to control how quickly the camera changes when you
// move the mouse a certain distance. Feel free to modify these.
// Mouse pixels are converted into arbitrary "units" (for lack of
// a better term), and then "units" are converted into an angle,
// or a distance, etc as the case may be.
/**
* Controls how quickly the mouse moves the camera (in general).
* Used to convert pixels into "units".
* @type {number}
*/
this.pixelsPerUnit = 300.0;
/**
* Controls how quickly the mouse affects rotation angles.
* Used to convert "units" into radians.
* @type {number}
*/
this.radiansPerUnit = 1.0;
/**
* Controls how quickly the mouse affects camera translation.
* Used to convert "units" into world space units of distance.
* @type {number}
*/
this.distancePerUnit = 10.0;
/**
* Controls how quickly the mouse affects zooming.
* Used to convert "units" into zoom factor.
* @type {number}
*/
this.zoomPerUnit = 1.0;
};
/**
* Calculates the center point and backpedal which will make the
* camera view the entire supplied bounding box, assuming a symmetric
* perspective projection. The heightAngle and rotationAngle are
* unchanged.
* @param {!o3d.BoundingBox} The bounding box to enclose in the view
* volume.
* @param {number} aspectRatio The aspect ratio of the viewing plane.
*/
o3djs.cameracontroller.CameraController.prototype.viewAll =
function(boundingBox,
aspectRatio) {
// Form a view matrix facing in the correct direction but whose
// origin is at the center of the bounding box
var minExtent = boundingBox.minExtent;
var maxExtent = boundingBox.maxExtent;
var centerPos = o3djs.math.divVectorScalar(
o3djs.math.addVector(minExtent, maxExtent), 2.0);
var viewMatrix = this.calculateViewMatrix_(centerPos, 0);
var maxBackpedal = 0;
var vertFOV = this.fieldOfViewAngle;
var tanVertFOV = Math.tan(vertFOV);
var horizFOV = Math.atan(aspectRatio * tanVertFOV);
var tanHorizFOV = Math.tan(horizFOV);
var extents = [minExtent, maxExtent];
for (var zi = 0; zi < 2; zi++) {
for (var yi = 0; yi < 2; yi++) {
for (var xi = 0; xi < 2; xi++) {
// Form world space vector of this corner
var vec = [extents[xi][0], extents[yi][1], extents[zi][2], 1];
// Transform by the temporary view matrix
vec = o3djs.math.mulVectorMatrix(vec, viewMatrix);
// Consider only points on the +z side of the origin
if (vec[2] >= 0.0) {
// Figure out the backpedal based on the horizontal and
// vertical view angles, and the z coordinate of the
// corner
maxBackpedal = Math.max(maxBackpedal,
vec[2] + vec[0] / tanHorizFOV);
maxBackpedal = Math.max(maxBackpedal,
vec[2] + vec[1] / tanVertFOV);
}
}
}
}
// Now set up the center point, backpedal and distancePerUnit
this.centerPos = centerPos;
this.backpedal = maxBackpedal;
// This is heuristic based on some experimentation
this.distancePerUnit = maxBackpedal / 5.0;
};
/**
* Calculates the view matrix for this camera.
* @return {!o3djs.math.Matrix4} The view matrix.
*/
o3djs.cameracontroller.CameraController.prototype.calculateViewMatrix =
function() {
return this.calculateViewMatrix_(this.centerPos, this.backpedal);
};
/**
* Calculates the view matrix for this camera given the specified
* center point and backpedal.
* @param {!o3djs.math.Vector3} centerPoint Center point for the
* camera.
* @param {number} backpedal Backpedal from the center point for the
* camera.
*/
o3djs.cameracontroller.CameraController.prototype.calculateViewMatrix_ =
function(centerPoint, backpedal) {
var matrix4 = o3djs.math.matrix4;
var view = matrix4.translation(o3djs.math.negativeVector(centerPoint));
view = matrix4.mul(view, matrix4.rotationY(this.rotationAngle));
view = matrix4.mul(view, matrix4.rotationX(this.heightAngle));
view = matrix4.mul(view, matrix4.translation([0, 0, -backpedal]));
return view;
};
/**
* Change the current mouse-drag mode, ie what happens when you move the mouse.
* Usually you would set it to something when a mouse button is pressed down,
* and then set it to NONE when the button is released.
* @param {o3djs.cameracontroller.DragMode} dragMode The new DragMode.
* @param {number} x The current mouse X coordinate.
* @param {number} y The current mouse Y coordinate.
*/
o3djs.cameracontroller.CameraController.prototype.setDragMode =
function(dragMode, x, y) {
this.dragMode_ = dragMode;
this.mouseX_ = x;
this.mouseY_ = y;
};
/**
* Method which should be called by end user code upon receiving a
* mouse-move event.
* @param {number} x The new mouse X coordinate.
* @param {number} y The new mouse Y coordinate.
*/
o3djs.cameracontroller.CameraController.prototype.mouseMoved = function(x, y) {
var deltaX = (x - this.mouseX_) / this.pixelsPerUnit;
var deltaY = (y - this.mouseY_) / this.pixelsPerUnit;
this.mouseX_ = x;
this.mouseY_ = y;
if (this.dragMode_ == o3djs.cameracontroller.DragMode.SPIN_ABOUT_CENTER) {
this.rotationAngle += deltaX * this.radiansPerUnit;
this.heightAngle += deltaY * this.radiansPerUnit;
}
if (this.dragMode_ == o3djs.cameracontroller.DragMode.DOLLY_IN_OUT) {
this.backpedal += deltaY * this.distancePerUnit;
}
if (this.dragMode_ == o3djs.cameracontroller.DragMode.ZOOM_IN_OUT) {
var width = Math.tan(this.fieldOfViewAngle);
width *= Math.pow(2, deltaY * this.zoomPerUnit);
this.fieldOfViewAngle = Math.atan(width);
}
if (this.dragMode_ == o3djs.cameracontroller.DragMode.DOLLY_ZOOM) {
if (this.backpedal > 0) {
var oldWidth = Math.tan(this.fieldOfViewAngle);
this.fieldOfViewAngle += deltaY * this.radiansPerUnit;
this.fieldOfViewAngle = Math.min(this.fieldOfViewAngle, 0.98 * Math.PI/2);
this.fieldOfViewAngle = Math.max(this.fieldOfViewAngle, 0.02 * Math.PI/2);
var newWidth = Math.tan(this.fieldOfViewAngle);
this.backpedal *= oldWidth / newWidth;
}
}
if (this.dragMode_ ==
o3djs.cameracontroller.DragMode.MOVE_CENTER_IN_VIEW_PLANE) {
var matrix4 = o3djs.math.matrix4;
var translationVector = [-deltaX * this.distancePerUnit,
deltaY * this.distancePerUnit, 0];
var inverseViewMatrix = matrix4.inverse(this.calculateViewMatrix());
translationVector = matrix4.transformDirection(
inverseViewMatrix, translationVector);
this.centerPos = o3djs.math.addVector(this.centerPos, translationVector);
}
if (this.onChange != null &&
this.dragMode_ != o3djs.cameracontroller.DragMode.NONE) {
this.onChange(this);
}
};