Docs: More JSDoc. (#30574)

Author: Mugen87

src/cameras/ArrayCamera.js

@@ -1,13 +1,41 @@
 import { PerspectiveCamera } from './PerspectiveCamera.js';
 
+/**
+ * This type of camera can be used in order to efficiently render a scene with a
+ * predefined set of cameras. This is an important performance aspect for
+ * rendering VR scenes.
+ *
+ * An instance of `ArrayCamera` always has an array of sub cameras. It's mandatory
+ * to define for each sub camera the `viewport` property which determines the
+ * part of the viewport that is rendered with this camera.
+ *
+ * @augments PerspectiveCamera
+ */
 class ArrayCamera extends PerspectiveCamera {
 
+	/**
+	 * Constructs a new array camera.
+	 *
+	 * @param {Array<PerspectiveCamera>} [array=[]] - An array of perspective sub cameras.
+	 */
 	constructor( array = [] ) {
 
 		super();
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isArrayCamera = true;
 
+		/**
+		 * An array of perspective sub cameras.
+		 *
+		 * @type {Array<PerspectiveCamera>}
+		 */
 		this.cameras = array;
 		this.index = 0;
 

src/cameras/CubeCamera.js

@@ -5,16 +5,72 @@ import { PerspectiveCamera } from './PerspectiveCamera.js';
 const fov = - 90; // negative fov is not an error
 const aspect = 1;
 
+/**
+ * A special type of camera that is positioned in 3D space to render its surroundings into a
+ * cube render target. The render target can then be used as an environment map for rendering
+ * realtime reflections in your scene.
+ *
+ * ```js
+ * // Create cube render target
+ * const cubeRenderTarget = new THREE.WebGLCubeRenderTarget( 256, { generateMipmaps: true, minFilter: THREE.LinearMipmapLinearFilter } );
+ *
+ * // Create cube camera
+ * const cubeCamera = new THREE.CubeCamera( 1, 100000, cubeRenderTarget );
+ * scene.add( cubeCamera );
+ *
+ * // Create car
+ * const chromeMaterial = new THREE.MeshLambertMaterial( { color: 0xffffff, envMap: cubeRenderTarget.texture } );
+ * const car = new THREE.Mesh( carGeometry, chromeMaterial );
+ * scene.add( car );
+ *
+ * // Update the render target cube
+ * car.visible = false;
+ * cubeCamera.position.copy( car.position );
+ * cubeCamera.update( renderer, scene );
+ *
+ * // Render the scene
+ * car.visible = true;
+ * renderer.render( scene, camera );
+ * ```
+ *
+ * @augments Object3D
+ */
 class CubeCamera extends Object3D {
 
+	/**
+	 * Constructs a new cube camera.
+	 *
+	 * @param {number} near - The camera's near plane.
+	 * @param {number} far - The camera's far plane.
+	 * @param {WebGLCubeRenderTarget} renderTarget - The cube render target.
+	 */
 	constructor( near, far, renderTarget ) {
 
 		super();
 
 		this.type = 'CubeCamera';
 
+		/**
+		 * A reference to the cube render target.
+		 *
+		 * @type {WebGLCubeRenderTarget}
+		 */
 		this.renderTarget = renderTarget;
+
+		/**
+		 * The current active coordinate system.
+		 *
+		 * @type {?(WebGLCoordinateSystem|WebGPUCoordinateSystem)}
+		 * @default null
+		 */
 		this.coordinateSystem = null;
+
+		/**
+		 * The current active mipmap level
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.activeMipmapLevel = 0;
 
 		const cameraPX = new PerspectiveCamera( fov, aspect, near, far );
@@ -43,6 +99,9 @@ class CubeCamera extends Object3D {
 
 	}
 
+	/**
+	 * Must be called when the coordinate system of the cube camera is changed.
+	 */
 	updateCoordinateSystem() {
 
 		const coordinateSystem = this.coordinateSystem;
@@ -109,6 +168,13 @@ class CubeCamera extends Object3D {
 
 	}
 
+	/**
+	 * Calling this method will render the given scene with the given renderer
+	 * into the cube render target of the camera.
+	 *
+	 * @param {(Renderer|WebGLRenderer)} renderer - The renderer.
+	 * @param {Scene} scene - The scene to render.
+	 */
 	update( renderer, scene ) {
 
 		if ( this.parent === null ) this.updateMatrixWorld();

src/cameras/OrthographicCamera.js

@@ -1,24 +1,109 @@
 import { Camera } from './Camera.js';
 
+/**
+ * Camera that uses [orthographic projection]{@link https://en.wikipedia.org/wiki/Orthographic_projection}.
+ *
+ * In this projection mode, an object's size in the rendered image stays
+ * constant regardless of its distance from the camera. This can be useful
+ * for rendering 2D scenes and UI elements, amongst other things.
+ *
+ * @augments Camera
+ */
 class OrthographicCamera extends Camera {
 
+	/**
+	 * Constructs a new orthographic camera.
+	 *
+	 * @param {number} [left=-1] - The left plane of the camera's frustum.
+	 * @param {number} [right=1] - The right plane of the camera's frustum.
+	 * @param {number} [top=1] - The top plane of the camera's frustum.
+	 * @param {number} [bottom=-1] - The bottom plane of the camera's frustum.
+	 * @param {number} [near=0.1] - The camera's near plane.
+	 * @param {number} [far=2000] - The camera's far plane.
+	 */
 	constructor( left = - 1, right = 1, top = 1, bottom = - 1, near = 0.1, far = 2000 ) {
 
 		super();
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isOrthographicCamera = true;
 
 		this.type = 'OrthographicCamera';
 
+		/**
+		 * The zoom factor of the camera.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.zoom = 1;
+
+		/**
+		 * Represents the frustum window specification. This property should not be edited
+		 * directly but via {@link PerspectiveCamera#setViewOffset} and {@link PerspectiveCamera#clearViewOffset}.
+		 *
+		 * @type {?Object}
+		 * @default null
+		 */
 		this.view = null;
 
+		/**
+		 * The left plane of the camera's frustum.
+		 *
+		 * @type {number}
+		 * @default -1
+		 */
 		this.left = left;
+
+		/**
+		 * The right plane of the camera's frustum.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.right = right;
+
+		/**
+		 * The top plane of the camera's frustum.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.top = top;
+
+		/**
+		 * The bottom plane of the camera's frustum.
+		 *
+		 * @type {number}
+		 * @default -1
+		 */
 		this.bottom = bottom;
 
+		/**
+		 * The camera's near plane. The valid range is greater than `0`
+		 * and less than the current value of {@link OrthographicCamera#far}.
+		 *
+		 * Note that, unlike for the {@link PerspectiveCamera}, `0` is a
+		 * valid value for an orthographic camera's near plane.
+		 *
+		 * @type {number}
+		 * @default 0.1
+		 */
 		this.near = near;
+
+		/**
+		 * The camera's far plane. Must be greater than the
+		 * current value of {@link OrthographicCamera#near}.
+		 *
+		 * @type {number}
+		 * @default 2000
+		 */
 		this.far = far;
 
 		this.updateProjectionMatrix();
@@ -43,6 +128,18 @@ class OrthographicCamera extends Camera {
 
 	}
 
+	/**
+	 * Sets an offset in a larger frustum. This is useful for multi-window or
+	 * multi-monitor/multi-machine setups.
+	 *
+	 * @param {number} fullWidth - The full width of multiview setup.
+	 * @param {number} fullHeight - The full height of multiview setup.
+	 * @param {number} x - The horizontal offset of the subcamera.
+	 * @param {number} y - The vertical offset of the subcamera.
+	 * @param {number} width - The width of subcamera.
+	 * @param {number} height - The height of subcamera.
+	 * @see {@link PerspectiveCamera#setViewOffset}
+	 */
 	setViewOffset( fullWidth, fullHeight, x, y, width, height ) {
 
 		if ( this.view === null ) {
@@ -71,6 +168,9 @@ class OrthographicCamera extends Camera {
 
 	}
 
+	/**
+	 * Removes the view offset from the projection matrix.
+	 */
 	clearViewOffset() {
 
 		if ( this.view !== null ) {
@@ -83,6 +183,10 @@ class OrthographicCamera extends Camera {
 
 	}
 
+	/**
+	 * Updates the camera's projection matrix. Must be called after any change of
+	 * camera properties.
+	 */
 	updateProjectionMatrix() {
 
 		const dx = ( this.right - this.left ) / ( 2 * this.zoom );