@plastic-software/three 0.174.0 → 0.175.1

package/src/core/RenderTarget.js

@@ -4,26 +4,107 @@ import { LinearFilter } from '../constants.js';
 import { Vector4 } from '../math/Vector4.js';
 import { Source } from '../textures/Source.js';
 
-/*
- In options, we can specify:
- * Texture parameters for an auto-generated target texture
- * depthBuffer/stencilBuffer: Booleans to indicate if we should generate these buffers
-*/
+/**
+ * A render target is a buffer where the video card draws pixels for a scene
+ * that is being rendered in the background. It is used in different effects,
+ * such as applying postprocessing to a rendered image before displaying it
+ * on the screen.
+ *
+ * @augments EventDispatcher
+ */
 class RenderTarget extends EventDispatcher {
 
+	/**
+	 * Render target options.
+	 *
+	 * @typedef {Object} RenderTarget~Options
+	 * @property {boolean} [generateMipmaps=false] - Whether to generate mipmaps or not.
+	 * @property {number} [magFilter=LinearFilter] - The mag filter.
+	 * @property {number} [minFilter=LinearFilter] - The min filter.
+	 * @property {number} [format=RGBAFormat] - The texture format.
+	 * @property {number} [type=UnsignedByteType] - The texture type.
+	 * @property {?string} [internalFormat=null] - The texture's internal format.
+	 * @property {number} [wrapS=ClampToEdgeWrapping] - The texture's uv wrapping mode.
+	 * @property {number} [wrapT=ClampToEdgeWrapping] - The texture's uv wrapping mode.
+	 * @property {number} [anisotropy=1] - The texture's anisotropy value.
+	 * @property {string} [colorSpace=NoColorSpace] - The texture's color space.
+	 * @property {boolean} [depthBuffer=true] - Whether to allocate a depth buffer or not.
+	 * @property {boolean} [stencilBuffer=false] - Whether to allocate a stencil buffer or not.
+	 * @property {boolean} [resolveDepthBuffer=true] - Whether to resolve the depth buffer or not.
+	 * @property {boolean} [resolveStencilBuffer=true] - Whether  to resolve the stencil buffer or not.
+	 * @property {?Texture} [depthTexture=null] - Reference to a depth texture.
+	 * @property {number} [samples=0] - The MSAA samples count.
+	 * @property {number} [count=1] - Defines the number of color attachments . Must be at least `1`.
+	 */
+
+	/**
+	 * Constructs a new render target.
+	 *
+	 * @param {number} [width=1] - The width of the render target.
+	 * @param {number} [height=1] - The height of the render target.
+	 * @param {RenderTarget~Options} [options] - The configuration object.
+	 */
 	constructor( width = 1, height = 1, options = {} ) {
 
 		super();
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isRenderTarget = true;
 
+		/**
+		 * The width of the render target.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.width = width;
+
+		/**
+		 * The height of the render target.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.height = height;
+
+		/**
+		 * The depth of the render target.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.depth = 1;
 
+		/**
+		 * A rectangular area inside the render target's viewport. Fragments that are
+		 * outside the area will be discarded.
+		 *
+		 * @type {Vector4}
+		 * @default (0,0,width,height)
+		 */
 		this.scissor = new Vector4( 0, 0, width, height );
+
+		/**
+		 * Indicates whether the scissor test should be enabled when rendering into
+		 * this render target or not.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.scissorTest = false;
 
+		/**
+		 * A rectangular area representing the render target's viewport.
+		 *
+		 * @type {Vector4}
+		 * @default (0,0,width,height)
+		 */
 		this.viewport = new Vector4( 0, 0, width, height );
 
 		const image = { width: width, height: height, depth: 1 };
@@ -47,6 +128,12 @@ class RenderTarget extends EventDispatcher {
 		texture.generateMipmaps = options.generateMipmaps;
 		texture.internalFormat = options.internalFormat;
 
+		/**
+		 * An array of textures. Each color attachment is represented as a separate texture.
+		 * Has at least a single entry for the default color attachment.
+		 *
+		 * @type {Array<Texture>}
+		 */
 		this.textures = [];
 
 		const count = options.count;
@@ -58,19 +145,57 @@ class RenderTarget extends EventDispatcher {
 
 		}
 
+		/**
+		 * Whether to allocate a depth buffer or not.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.depthBuffer = options.depthBuffer;
+
+		/**
+		 * Whether to allocate a stencil buffer or not.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.stencilBuffer = options.stencilBuffer;
 
+		/**
+		 * Whether to resolve the depth buffer or not.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.resolveDepthBuffer = options.resolveDepthBuffer;
+
+		/**
+		 * Whether to resolve the stencil buffer or not.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.resolveStencilBuffer = options.resolveStencilBuffer;
 
-		this._depthTexture = null;
-		this.depthTexture = options.depthTexture;
+		this._depthTexture = options.depthTexture;
 
+		/**
+		 * The number of MSAA samples.
+		 *
+		 * A value of `0` disables MSAA.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.samples = options.samples;
 
 	}
 
+	/**
+	 * The texture representing the default color attachment.
+	 *
+	 * @type {Texture}
+	 */
 	get texture() {
 
 		return this.textures[ 0 ];
@@ -92,12 +217,27 @@ class RenderTarget extends EventDispatcher {
 
 	}
 
+	/**
+	 * Instead of saving the depth in a renderbuffer, a texture
+	 * can be used instead which is useful for further processing
+	 * e.g. in context of post-processing.
+	 *
+	 * @type {?DepthTexture}
+	 * @default null
+	 */
 	get depthTexture() {
 
 		return this._depthTexture;
 
 	}
 
+	/**
+	 * Sets the size of this render target.
+	 *
+	 * @param {number} width - The width.
+	 * @param {number} height - The height.
+	 * @param {number} [depth=1] - The depth.
+	 */
 	setSize( width, height, depth = 1 ) {
 
 		if ( this.width !== width || this.height !== height || this.depth !== depth ) {
@@ -123,12 +263,25 @@ class RenderTarget extends EventDispatcher {
 
 	}
 
+	/**
+	 * Returns a new render target with copied values from this instance.
+	 *
+	 * @return {RenderTarget} A clone of this instance.
+	 */
 	clone() {
 
 		return new this.constructor().copy( this );
 
 	}
 
+	/**
+	 * Copies the settings of the given render target. This is a structural copy so
+	 * no resources are shared between render targets after the copy. That includes
+	 * all MRT textures and the depth texture.
+	 *
+	 * @param {RenderTarget} source - The render target to copy.
+	 * @return {RenderTarget} A reference to this instance.
+	 */
 	copy( source ) {
 
 		this.width = source.width;
@@ -169,6 +322,12 @@ class RenderTarget extends EventDispatcher {
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever this instance is no longer used in your app.
+	 *
+	 * @fires RenderTarget#dispose
+	 */
 	dispose() {
 
 		this.dispatchEvent( { type: 'dispose' } );

package/src/core/RenderTarget3D.js

@@ -1,16 +1,41 @@
 import { RenderTarget } from './RenderTarget.js';
 import { Data3DTexture } from '../textures/Data3DTexture.js';
 
+/**
+ * Represents a 3D render target.
+ *
+ * @augments RenderTarget
+ */
 class RenderTarget3D extends RenderTarget {
 
+	/**
+	 * Constructs a new 3D render target.
+	 *
+	 * @param {number} [width=1] - The width of the render target.
+	 * @param {number} [height=1] - The height of the render target.
+	 * @param {number} [depth=1] - The height of the render target.
+	 * @param {RenderTarget~Options} [options] - The configuration object.
+	 */
 	constructor( width = 1, height = 1, depth = 1, options = {} ) {
 
 		super( width, height, options );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isRenderTarget3D = true;
 
 		this.depth = depth;
 
+		/**
+		 * Overwritten with a different texture type.
+		 *
+		 * @type {Data3DTexture}
+		 */
 		this.texture = new Data3DTexture( null, width, height, depth );
 
 		this.texture.isRenderTargetTexture = true;

package/src/core/RenderTargetArray.js

@@ -1,8 +1,21 @@
 import { RenderTarget } from './RenderTarget.js';
 import { DataArrayTexture } from '../textures/DataArrayTexture.js';
 
+/**
+ * Represents an array render target.
+ *
+ * @augments RenderTarget
+ */
 class RenderTargetArray extends RenderTarget {
 
+	/**
+	 * Constructs a new 3D render target.
+	 *
+	 * @param {number} [width=1] - The width of the render target.
+	 * @param {number} [height=1] - The height of the render target.
+	 * @param {number} [depth=1] - The height of the render target.
+	 * @param {RenderTarget~Options} [options] - The configuration object.
+	 */
 	constructor( width = 1, height = 1, depth = 1, options = {} ) {
 
 		super( width, height, options );
@@ -11,6 +24,11 @@ class RenderTargetArray extends RenderTarget {
 
 		this.depth = depth;
 
+		/**
+		 * Overwritten with a different texture type.
+		 *
+		 * @type {DataArrayTexture}
+		 */
 		this.texture = new DataArrayTexture( null, width, height, depth );
 
 		this.texture.isRenderTargetTexture = true;

package/src/core/Uniform.js

@@ -1,11 +1,40 @@
+/**
+ * Represents a uniform which is a global shader variable. They are passed to shader programs.
+ *
+ * When declaring a uniform of a {@link ShaderMaterial}, it is declared by value or by object.
+ * ```js
+ * uniforms: {
+ * 	time: { value: 1.0 },
+ * 	resolution: new Uniform( new Vector2() )
+ * };
+ * ```
+ * Since this class can only be used in context of {@link ShaderMaterial}, it is only supported
+ * in {@link WebGLRenderer}.
+ */
 class Uniform {
 
+	/**
+	 * Constructs a new uniform.
+	 *
+	 * @param {any} value - The uniform value.
+	 */
 	constructor( value ) {
 
+		/**
+		 * The uniform value.
+		 *
+		 * @type {any}
+		 */
 		this.value = value;
 
 	}
 
+	/**
+	 * Returns a new uniform with copied values from this instance.
+	 * If the value has a `clone()` method, the value is cloned as well.
+	 *
+	 * @return {Uniform} A clone of this instance.
+	 */
 	clone() {
 
 		return new Uniform( this.value.clone === undefined ? this.value : this.value.clone() );

package/src/core/UniformsGroup.js

@@ -3,23 +3,72 @@ import { StaticDrawUsage } from '../constants.js';
 
 let _id = 0;
 
+/**
+ * A class for managing multiple uniforms in a single group. The renderer will process
+ * such a definition as a single UBO.
+ *
+ * Since this class can only be used in context of {@link ShaderMaterial}, it is only supported
+ * in {@link WebGLRenderer}.
+ *
+ * @augments EventDispatcher
+ */
 class UniformsGroup extends EventDispatcher {
 
+	/**
+	 * Constructs a new uniforms group.
+	 */
 	constructor() {
 
 		super();
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isUniformsGroup = true;
 
+		/**
+		 * The ID of the 3D object.
+		 *
+		 * @name UniformsGroup#id
+		 * @type {number}
+		 * @readonly
+		 */
 		Object.defineProperty( this, 'id', { value: _id ++ } );
 
+		/**
+		 * The name of the uniforms group.
+		 *
+		 * @type {string}
+		 */
 		this.name = '';
 
+		/**
+		 * The buffer usage.
+		 *
+		 * @type {(StaticDrawUsage|DynamicDrawUsage|StreamDrawUsage|StaticReadUsage|DynamicReadUsage|StreamReadUsage|StaticCopyUsage|DynamicCopyUsage|StreamCopyUsage)}
+		 * @default StaticDrawUsage
+		 */
 		this.usage = StaticDrawUsage;
+
+		/**
+		 * An array holding the uniforms.
+		 *
+		 * @type {Array<Uniform>}
+		 */
 		this.uniforms = [];
 
 	}
 
+	/**
+	 * Adds the given uniform to this uniforms group.
+	 *
+	 * @param {Uniform} uniform - The uniform to add.
+	 * @return {UniformsGroup} A reference to this uniforms group.
+	 */
 	add( uniform ) {
 
 		this.uniforms.push( uniform );
@@ -28,6 +77,12 @@ class UniformsGroup extends EventDispatcher {
 
 	}
 
+	/**
+	 * Removes the given uniform from this uniforms group.
+	 *
+	 * @param {Uniform} uniform - The uniform to remove.
+	 * @return {UniformsGroup} A reference to this uniforms group.
+	 */
 	remove( uniform ) {
 
 		const index = this.uniforms.indexOf( uniform );
@@ -38,6 +93,12 @@ class UniformsGroup extends EventDispatcher {
 
 	}
 
+	/**
+	 * Sets the name of this uniforms group.
+	 *
+	 * @param {string} name - The name to set.
+	 * @return {UniformsGroup} A reference to this uniforms group.
+	 */
 	setName( name ) {
 
 		this.name = name;
@@ -46,6 +107,12 @@ class UniformsGroup extends EventDispatcher {
 
 	}
 
+	/**
+	 * Sets the usage of this uniforms group.
+	 *
+	 * @param {(StaticDrawUsage|DynamicDrawUsage|StreamDrawUsage|StaticReadUsage|DynamicReadUsage|StreamReadUsage|StaticCopyUsage|DynamicCopyUsage|StreamCopyUsage)} value - The usage to set.
+	 * @return {UniformsGroup} A reference to this uniforms group.
+	 */
 	setUsage( value ) {
 
 		this.usage = value;
@@ -54,14 +121,24 @@ class UniformsGroup extends EventDispatcher {
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever this instance is no longer used in your app.
+	 *
+	 * @fires Texture#dispose
+	 */
 	dispose() {
 
 		this.dispatchEvent( { type: 'dispose' } );
 
-		return this;
-
 	}
 
+	/**
+	 * Copies the values of the given uniforms group to this instance.
+	 *
+	 * @param {UniformsGroup} source - The uniforms group to copy.
+	 * @return {UniformsGroup} A reference to this uniforms group.
+	 */
 	copy( source ) {
 
 		this.name = source.name;
@@ -87,6 +164,11 @@ class UniformsGroup extends EventDispatcher {
 
 	}
 
+	/**
+	 * Returns a new uniforms group with copied values from this instance.
+	 *
+	 * @return {UniformsGroup} A clone of this instance.
+	 */
 	clone() {
 
 		return new this.constructor().copy( this );

package/src/extras/Controls.js

@@ -77,8 +77,23 @@ class Controls extends EventDispatcher {
 	/**
 	 * Connects the controls to the DOM. This method has so called "side effects" since
 	 * it adds the module's event listeners to the DOM.
+	 *
+	 * @param {HTMLDOMElement} element - The DOM element to connect to.
 	 */
-	connect() {}
+	connect( element ) {
+
+		if ( element === undefined ) {
+
+			console.warn( 'THREE.Controls: connect() now requires an element.' ); // @deprecated, the warning can be removed with r185
+			return;
+
+		}
+
+		if ( this.domElement !== null ) this.disconnect();
+
+		this.domElement = element;
+
+	}
 
 	/**
 	 * Disconnects the controls from the DOM.