Merge pull request #10122 from looeee/docs/cameras/improve

Improved Camera docs

docs/api/cameras/Camera.html

@@ -20,46 +20,66 @@
 
 		<h3>[name]()</h3>
 		<div>
-			This constructor sets the following properties to the correct type: matrixWorldInverse and projectionMatrix.
+			This constructor sets the following properties to the correct type:
+			[page:Camera.matrixWorldInverse matrixWorldInverse] and [page:Camera.projectionMatrix projectionMatrix].
 
 		</div>
 
 
 		<h2>Properties</h2>
+		<div>See the base [page:Object3D] class for common properties.</div>
+
+		<h3>[property:Boolean isCamera]</h3>
+		<div>
+			Used to check whether this or derived classes are cameras. Default is *true*.<br /><br />
+
+			You should not change this, as it used internally by the renderer for optimisation.
+		</div>
 
 		<h3>[property:Matrix4 matrixWorldInverse]</h3>
-		<div>This is the inverse of matrixWorld. MatrixWorld contains the Matrix which has the world transform of the Camera.</div>
+		<div>
+			This is the inverse of matrixWorld. MatrixWorld contains the Matrix which has
+			the world transform of the Camera.
+		</div>
 
 		<h3>[property:Matrix4 projectionMatrix]</h3>
 		<div>This is the matrix which contains the projection.</div>
 
 		<h3>[property:Layers layers]</h3>
 		<div>
-		The layer membership of the camera. Only objects that have at least one layer in common with the camera will be visible. 
+		The [page:Layers layers] that the camera is a member of. This is an inherited
+		property from [page:Object3D].<br /><br />
+
+		Objects must share at least one layer with the camera to be seen
+		when the camera's viewpoint is rendered.
 		</div>
 
 		<h2>Methods</h2>
+		<div>See the base [page:Objct3D] class for common methods.</div>
 
-		<h3>[method:Vector3 getWorldDirection]( [page:Vector3 vector] )</h3>
+		<h3>[method:Vector3 getWorldDirection]( [page:Vector3 optionalTarget] )</h3>
 		<div>
-		vector — (optional)<br />
-		<br />
-		It returns a vector representing the direction in which the camera is looking, in world space.
+		vector — (optional)<br /><br />
+
+		Returns a vector representing the direction in which the camera is looking,
+		in world space. If the [page:Vector3 optionalTarget] is set, returns a vector representing the direction
+		from the camera's position to the [page:Vector3 optionalTarget].
 		</div>
 
 
-		<h3>[method:null lookAt]( [page:Vector3 vector] )</h3>
+		<h3>[method:null lookAt]( [page:Vector3 target] )</h3>
 		<div>
-		vector — point to look at<br />
-		<br />
-		This makes the camera look at the vector position in the global space as long as the parent of this camera is the scene or at position (0,0,0).
+		target — position in 3D space for the camera to point towards<br /><br />
+
+		This makes the camera look at the vector position in the global space as long as
+		the parent of this camera is the scene or at position (0,0,0).
 		</div>
 
 		<h3>[method:Camera clone]( [page:Camera camera] )</h3>
 		<div>
-		camera — camera to clone<br />
-		<br />
-		It returns a clone of camera.
+		camera — camera to clone<br /><br />
+
+		Returns a clone of camera.
 		</div>
 
 

docs/api/cameras/CubeCamera.html

@@ -43,21 +43,20 @@
 		<h2>Constructor</h2>
 
 
-		<h3>[name]( [page:number near], [page:number far], [page:number cubeResolution] )</h3>
+		<h3>[name]( [page:Number near], [page:Number far], [page:Number cubeResolution] )</h3>
 		<div>
 		near -- The near clipping distance. <br />
 		far -- The far clipping distance <br />
-		cubeResolution -- Sets the width of the cube.
+		cubeResolution -- Sets the length of the cube's edges.
 		</div>
 		<div>
-		Constructs a CubeCamera that contains 6 [page:PerspectiveCamera PerspectiveCameras] that then
-		render to a [page:WebGLRenderTargetCube]
+		Constructs a CubeCamera that contains 6 [page:PerspectiveCamera PerspectiveCameras] that
+		render to a [page:WebGLRenderTargetCube].
 		</div>
 
 
 		<h2>Properties</h2>
-
-
+		<div>See the base [page:Object3D] class for common properties.</div>
 
 		<h3>[property:WebGLRenderTargetCube renderTarget]</h3>
 		<div>
@@ -65,7 +64,7 @@
 		</div>
 
 		<h2>Methods</h2>
-
+		<div>See the base [page:Object3D] class for common methods.</div>
 
 
 		<h3>[method:null updateCubeMap]( [page:WebGLRenderer renderer], [page:Scene scene] )</h3>
@@ -74,7 +73,7 @@
 		scene -- The current scene
 		</div>
 		<div>
-		Call this to update the renderTarget.
+		Call this to update the [page:CubeCamera.renderTarget renderTarget].
 		</div>
 
 		<h2>Source</h2>

docs/api/cameras/OrthographicCamera.html

@@ -12,7 +12,14 @@
 
 		<h1>[name]</h1>
 
-		<div class="desc">Camera with orthographic projection.</div>
+		<div class="desc">
+			Camera that uses [link:https://en.wikipedia.org/wiki/Orthographic_projection orthographic projection].<br /><br />
+
+			In this projection mode, an object's size in the rendered image stays constant
+			regardless of its distance from the camera.<br /><br />
+
+			This can be useful for rendering 2D scenes and UI elements, amongst other things.
+		</div>
 
 
 		<h2>Example</h2>
@@ -37,42 +44,55 @@ scene.add( camera );</code>
 		<h2>Constructor</h2>
 
 
-		<h3>[name]( [page:Float left], [page:Float right], [page:Float top], [page:Float bottom], [page:Float near], [page:Float far] )</h3>
+		<h3>[name]( [page:Number left], [page:Number right], [page:Number top], [page:Number bottom], [page:Number near], [page:Number far] )</h3>
 		<div>
 		left — Camera frustum left plane.<br />
 		right — Camera frustum right plane.<br />
 		top — Camera frustum top plane.<br />
 		bottom — Camera frustum bottom plane.<br />
 		near — Camera frustum near plane.<br />
-		far — Camera frustum far plane.
+		far — Camera frustum far plane.<br /><br />
+
+		Together these define the camera's [link:https://en.wikipedia.org/wiki/Viewing_frustum viewing frustum].
 		</div>
 
 
 		<h2>Properties</h2>
+		<div>See the base [page:Camera] class for common properties.</div>
 
-		<h3>[property:number zoom]</h3>
-		<div>Gets or sets the zoom factor of the camera. Default is *1*.</div>
+		<h3>[property:Float bottom]</h3>
+		<div>Camera frustum bottom plane.</div>
+
+		<h3>[property:Float far]</h3>
+		<div>Camera frustum far plane. Default is *2000*.</div>
+
+		<h3>[property:Boolean isOrthographicCamera]</h3>
+		<div>
+			Used to test whether this or derived classes are OrthographicCameras. Default is *true*.<br /><br />
+
+			This should not be changed as it is used internally by the renderer for optimisation.
+		</div>
 
 		<h3>[property:Float left]</h3>
 		<div>Camera frustum left plane.</div>
 
+		<h3>[property:Float near]</h3>
+		<div>Camera frustum near plane. Default is *0.1*.</div>
+
 		<h3>[property:Float right]</h3>
 		<div>Camera frustum right plane.</div>
 
 		<h3>[property:Float top]</h3>
 		<div>Camera frustum top plane.</div>
 
-		<h3>[property:Float bottom]</h3>
-		<div>Camera frustum bottom plane.</div>
-
-		<h3>[property:Float near]</h3>
-		<div>Camera frustum near plane. Default is *0.1*.</div>
-
-		<h3>[property:Float far]</h3>
-		<div>Camera frustum far plane. Default is *2000*.</div>
+		<h3>[property:Object view]</h3>
+		<div>Set by [page:OrthographicCamera.setViewOffset setViewOffset]. Default is *null*.</div>
 
+		<h3>[property:number zoom]</h3>
+		<div>Gets or sets the zoom factor of the camera. Default is *1*.</div>
 
 		<h2>Methods</h2>
+		<div>See the base [page:Camera] class for common methods.</div>
 
 		<h3>[method:null setViewOffset]( [page:Float fullWidth], [page:Float fullHeight], [page:Float x], [page:Float y], [page:Float width], [page:Float height] )</h3>
 		<div>
@@ -81,11 +101,11 @@ scene.add( camera );</code>
 		x — horizontal offset of subcamera<br />
 		y — vertical offset of subcamera<br />
 		width — width of subcamera<br />
-		height — height of subcamera
-		</div>
+		height — height of subcamera<br /><br />
 
-		<div>
-		Sets an offset in a larger frustum. This is useful for multi-window or multi-monitor/multi-machine setups. For an example on how to use it see [page:PerspectiveCamera].
+			Sets an offset in a larger [link:https://en.wikipedia.org/wiki/Viewing_frustum viewing frustum].
+			This is useful for multi-window or multi-monitor/multi-machine setups.
+			For an example on how to use it see [page:PerspectiveCamera.setViewOffset PerspectiveCamera].
 		</div>
 
 		<h3>[method:null clearViewOffset]()</h3>
@@ -95,19 +115,12 @@ scene.add( camera );</code>
 
 		<h3>[method:null updateProjectionMatrix]()</h3>
 		<div>
-		Updates the camera projection matrix. Must be called after change of parameters.
+		Updates the camera projection matrix. Must be called after any change of parameters.
 		</div>
 
-		<h3>[method:OrthographicCamera clone]()</h3>
-		<div>
-		<br />
-		Returns a clone of the OrthographicCamera.
-		</div>
-
-
 		<h3>[method:JSON toJSON]()</h3>
 		<div>
-		Return camera data in JSON format.
+		Return the camera's data in JSON format.
 		</div>
 
 

docs/api/cameras/PerspectiveCamera.html

@@ -12,7 +12,12 @@
 
 		<h1>[name]</h1>
 
-		<div class="desc">Camera with perspective projection.</div>
+		<div class="desc">
+			Camera that uses [link:https://en.wikipedia.org/wiki/Perspective_(graphical) perspective projection].<br /><br />
+
+			This projection mode is designed to mimic the way the human eye sees. It is the most
+			common projection mode used for rendering a 3D scene.
+		</div>
 
 
 		<h2>Example</h2>
@@ -31,37 +36,51 @@ scene.add( camera );</code>
 
 		<h2>Constructor</h2>
 
-		<h3>[name]( [page:Float fov], [page:Float aspect], [page:Float near], [page:Float far] )</h3>
+		<h3>[name]( [page:Number fov], [page:Number aspect], [page:Number near], [page:Number far] )</h3>
 		<div>
 		fov — Camera frustum vertical field of view.<br />
 		aspect — Camera frustum aspect ratio.<br />
 		near — Camera frustum near plane.<br />
-		far — Camera frustum far plane.
+		far — Camera frustum far plane.<br /><br />
+
+			Together these define the camera's [link:https://en.wikipedia.org/wiki/Viewing_frustum viewing frustum].
 		</div>
 
 
 		<h2>Properties</h2>
+		<div>See the base [page:Camera] class for common properties.</div>
 
-		<h3>[property:Float fov]</h3>
-		<div>Camera frustum vertical field of view, from bottom to top of view, in degrees. Default is *50*.</div>
-
-		<h3>[property:number zoom]</h3>
-		<div>Gets or sets the zoom factor of the camera. Default is *1*.</div>
-
-		<h3>[property:Float near]</h3>
-		<div>Camera frustum near plane. Default is *0.1*.</div>
+		<h3>[property:Float aspect]</h3>
+		<div>Camera frustum aspect ratio, usually the canvas width / canvas height. Default is *1* (square canvas).</div>
 
 		<h3>[property:Float far]</h3>
 		<div>Camera frustum far plane. Default is *2000*.</div>
 
+		<h3>[property:Float filmGauge]</h3>
+		<div>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.</div>
+
+		<h3>[property:Float filmOffset]</h3>
+		<div>Horizontal off-center offset in the same unit as .filmGauge. Default is *0*.</div>
+
 		<h3>[property:Float focus]</h3>
 		<div>Object distance used for stereoscopy and depth-of-field effects.
-			This parameter does not influence the projection matrix unless a StereoCamera is being used.
+			This parameter does not influence the projection matrix unless a [page:StereoCamera] is being used.
 			Default is *10*.
 		</div>
 
-		<h3>[property:Float aspect]</h3>
-		<div>Camera frustum aspect ratio, usually the canvas width / canvas height. Default is *1* (square canvas).</div>
+		<h3>[property:Float fov]</h3>
+		<div>Camera frustum vertical field of view, from bottom to top of view, in degrees. Default is *50*.</div>
+
+		<h3>[property:Boolean isPerspectiveCamera]</h3>
+		<div>
+			Used to test whether this or derived classes are PerspectiveCameras. Default is *true*.<br /><br />
+
+			This should not be changed as it is used internally by the renderer for optimisation.
+		</div>
+
+
+		<h3>[property:Float near]</h3>
+		<div>Camera frustum near plane. Default is *0.1*.</div>
 
 		<h3>[property:Object view]</h3>
 		<div>
@@ -70,51 +89,42 @@ scene.add( camera );</code>
 			and cleared using [page:PerspectiveCamera.clearViewOffset .clearViewOffset].
 		</div>
 
-		<h3>[property:Float filmGauge]</h3>
-		<div>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.</div>
+		<h3>[property:number zoom]</h3>
+		<div>Gets or sets the zoom factor of the camera. Default is *1*.</div>
+
+
+
 
-		<h3>[property:Float filmOffset]</h3>
-		<div>Horizontal off-center offset in the same unit as .filmGauge. Default is *0*.</div>
 
 		<h2>Methods</h2>
+		<div>See the base [page:Camera] class for common methods.</div>
+
+		<h3>[method:null clearViewOffset]()</h3>
+		<div>Removes any offset set by the [page:PerspectiveCamera.setViewOffset .setViewOffset] method.</div>
 
 		<h3>[method:Float getEffectiveFOV]()</h3>
-		<div>
-		Returns the current vertical field of view angle in degrees considering .zoom.
-		</div>
+		<div>Returns the current vertical field of view angle in degrees considering .zoom.</div>
 
-		<h3>[method:Float getFocalLength]()</h3>
+		<h3>[method:Float getFilmHeight]()</h3>
 		<div>
-		Returns the focal length of the current .fov in respect to .filmGauge.
+		Returns the height of the image on the film. If .aspect is less than or equal to one
+		(portrait format), the result equals .filmGauge.
 		</div>
 
 		<h3>[method:Float getFilmWidth]()</h3>
 		<div>
-		Returns the width of the image on the film. If .aspect is greater than or equal to one (landscape format), the result equals .filmGauge.
+		Returns the width of the image on the film. If .aspect is greater than or equal to one
+		(landscape format), the result equals .filmGauge.
 		</div>
 
-		<h3>[method:Float getFilmHeight]()</h3>
-		<div>
-		Returns the height of the image on the film. If .aspect is less than or equal to one (portrait format), the result equals .filmGauge.
-		</div>
+		<h3>[method:Float getFocalLength]()</h3>
+		<div>Returns the focal length of the current .fov in respect to .filmGauge.</div>
 
 		<h3>[method:null setFocalLength]( [page:Float focalLength] )</h3>
 		<div>
-		Sets the FOV by focal length in respect to the current .filmGauge.
-		</div>
-		<div>
-		By default, the focal length is specified for a 35mm (full frame) camera.
-		</div>
+		Sets the FOV by focal length in respect to the current [page:PerspectiveCamera.filmGauge .filmGauge].<br /><br />
 
-		<h3>[method:null setLens]( [page:Float focalLength], [page:Float filmGauge] )</h3>
-		<div>
-		focalLength — focal length<br />
-		frameGauge — film gauge
-		</div>
-
-		<div>
-		Sets .fov by focal length. Optionally also sets .filmGauge.
-		This method is deprecated, please use .setFocalLength instead.
+		By default, the focal length is specified for a 35mm (full frame) camera.
 		</div>
 
 		<h3>[method:null setViewOffset]( [page:Float fullWidth], [page:Float fullHeight], [page:Float x], [page:Float y], [page:Float width], [page:Float height] )</h3>
@@ -134,11 +144,13 @@ scene.add( camera );</code>
 		<div>
 		For example, if you have 3x2 monitors and each monitor is 1920x1080 and the monitors are in grid like this:<br />
 
-		<pre>+---+---+---+
+		<pre>
++---+---+---+
 | A | B | C |
 +---+---+---+
 | D | E | F |
-+---+---+---+</pre>
++---+---+---+
+		</pre>
 
 		then for each monitor you would call it like this:<br />
 
@@ -164,20 +176,9 @@ 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.
 		</div>
 
-		<h3>[method:null clearViewOffset]()</h3>
-		<div>
-		Removes any offset set by the .setViewOffset method.
-		</div>
-
 		<h3>[method:null updateProjectionMatrix]()</h3>
 		<div>
-		Updates the camera projection matrix. Must be called after change of parameters.
-		</div>
-
-		<h3>[method:PerspectiveCamera clone]()</h3>
-		<div>
-		<br />
-		It returns a clone of PerspectiveCamera.
+		Updates the camera projection matrix. Must be called after any change of parameters.
 		</div>
 
 		<h3>[method:JSON toJSON]()</h3>

docs/api/cameras/StereoCamera.html

@@ -45,10 +45,12 @@
 		<div>Default is *0.064*.</div>
 
 		<h3>[property:PerspectiveCamera cameraL]</h3>
-		<div>Left camera.</div>
+		<div>Left camera. This is added to [page:Layers layer 1] - objects to be rendered
+		by the left camera must also be added to this layer.</div>
 
 		<h3>[property:PerspectiveCamera cameraR]</h3>
-		<div>Right camera.</div>
+		<div>Right camera.This is added to [page:Layers layer 2] - objects to be rendered
+		by the left camera must also be added to this layer.</div>
 
 
 		<h2>Methods</h2>