Summary

This file defines a 3D scene and the requisite methods.

/**MathWorx Copyright (c) 2008 Shane Steinert-Threlkeld
Dual-licensed under the MIT and GNU GPL Licenses.
For more information, see LICENSE file */

/**@fileoverview This file defines a 3D scene and the requisite methods. */

dependencies = ['point3D', 'Plane'];
require(dependencies);

/**The constructor function for a new Scene3D object.
@class Scene3D defines a new 3D scene (shocking, I know).  A 3D Scene has two main components:
objects (to be displayed), and a camera (from which to view the objects).  In this model of a 3D
scene, the camera is the main mover, not the objects (though they can be moved).  A view plane is
defined through the origin with a normal in the direction from the origin to the camera; the 
objects are projected onto this view plane, which is then matched up with the 2D plane of the 
screen.
@param {Array} objs an Array of Object3D objects to be displayed
@param {point3D} camera the position of the camera (as a point3D object); used to generate initial focus and view plane
@constructor */
function Scene3D(objs, camera) {

	/**The "camera" is the point from which the objects are being viewed.
	@type point3D */
	this.camera = point3D.zero;
	/**The focus is the distance between the camera and the origin (in world coordinates)
	@type Number */
	this.focus = 0;
	/**The objects to be viewed/displayed. An array of Object3D objects.
	@type Array */
	this.objects = new Array();
	/**The view plane, onto which the objects are projected.
	@type Plane */
	this.plane = Plane.XY;

	if(camera) {
		if(camera instanceof point3D) {
			this.camera = camera;
		}
	} else {
		this.camera = new point3D(0, 0, 10);
	}

	this.objects = objs;

	this.focus = this.camera.getLength();
	//NOTE: this.camera will be normalized by Plane constructor function
	this.plane = new Plane(point3D.zero, this.camera); 

}

Scene3D.prototype = {

	draw: function() {

	},

	/**Sets the focus (distance between Origin and camera).
	@param {Number} dist the new focal distance
	@return {Scene3D} this Scene3D object, with updated focus distance and matching camera position */
	setFocus: function(dist) {
		this.focus = dist;
		this.camera = this.camera.multiplyBy(this.focus/this.camera.getLength());
		return this;
	},

	/**Moves the camera to a new position.  Parameters are two angles, one in the XY-plane
	from the positive x-axis and the other from the positive z-axis.
	@param {Number} theta the degree (in radians) to rotate the camera from the positive x-axis
	@param {Number} phi the degree (in radians) to rotate the camera from the positive z-axis
	@return {Scene3D} this Scene3D object, with updated camera and view plane */
	rotateCamera: function(theta, phi) {
		var x = Math.sin(phi)*Math.cos(theta);
		var y = Math.sin(phi)*Math.sin(theta);
		var z = Math.cos(phi);
		var norm = new point3D(x, y, z);
		this.plane = new Plane(point3D.zero, norm);
		this.camera = norm.multiplyBy(this.focus); //creates a new point3D
		return this;
	},

	/**Add an object to the 3D Scene.
	@param {Object3D} obj the object to be added to the 3D Scene
	@return {Scene3D} this Scene3D, with the object added (returns null if obj is not an Object3D) */
	addObject: function(obj) {
		if(!(obj instanceof Object3D)) {
			return null;
		}
		this.objects.push(obj);
		return this;
	},

	project: function() { //use this.plane.pointClosestTo()
	}

} //end Scene3D prototype