@plastic-software/three 0.174.0 → 0.175.0

package/src/materials/nodes/MeshMatcapNodeMaterial.js

@@ -10,7 +10,7 @@ import { MeshMatcapMaterial } from '../MeshMatcapMaterial.js';
 const _defaultValues = /*@__PURE__*/ new MeshMatcapMaterial();
 
 /**
- * Node material version of `MeshMatcapMaterial`.
+ * Node material version of {@link MeshMatcapMaterial}.
  *
  * @augments NodeMaterial
  */
@@ -25,7 +25,7 @@ class MeshMatcapNodeMaterial extends NodeMaterial {
 	/**
 	 * Constructs a new mesh normal node material.
 	 *
-	 * @param {?Object} parameters - The configuration parameter.
+	 * @param {Object} [parameters] - The configuration parameter.
 	 */
 	constructor( parameters ) {
 

package/src/materials/nodes/MeshNormalNodeMaterial.js

@@ -12,7 +12,7 @@ import { MeshNormalMaterial } from '../MeshNormalMaterial.js';
 const _defaultValues = /*@__PURE__*/ new MeshNormalMaterial();
 
 /**
- * Node material version of `MeshNormalMaterial`.
+ * Node material version of {@link MeshNormalMaterial}.
  *
  * @augments NodeMaterial
  */
@@ -27,7 +27,7 @@ class MeshNormalNodeMaterial extends NodeMaterial {
 	/**
 	 * Constructs a new mesh normal node material.
 	 *
-	 * @param {?Object} parameters - The configuration parameter.
+	 * @param {Object} [parameters] - The configuration parameter.
 	 */
 	constructor( parameters ) {
 

package/src/materials/nodes/MeshPhongNodeMaterial.js

@@ -10,7 +10,7 @@ import { MeshPhongMaterial } from '../MeshPhongMaterial.js';
 const _defaultValues = /*@__PURE__*/ new MeshPhongMaterial();
 
 /**
- * Node material version of `MeshPhongMaterial`.
+ * Node material version of {@link MeshPhongMaterial}.
  *
  * @augments NodeMaterial
  */
@@ -25,7 +25,7 @@ class MeshPhongNodeMaterial extends NodeMaterial {
 	/**
 	 * Constructs a new mesh lambert node material.
 	 *
-	 * @param {?Object} parameters - The configuration parameter.
+	 * @param {Object} [parameters] - The configuration parameter.
 	 */
 	constructor( parameters ) {
 

package/src/materials/nodes/MeshPhysicalNodeMaterial.js

@@ -12,7 +12,7 @@ import { MeshPhysicalMaterial } from '../MeshPhysicalMaterial.js';
 const _defaultValues = /*@__PURE__*/ new MeshPhysicalMaterial();
 
 /**
- * Node material version of `MeshPhysicalMaterial`.
+ * Node material version of {@link MeshPhysicalMaterial}.
  *
  * @augments MeshStandardNodeMaterial
  */
@@ -27,7 +27,7 @@ class MeshPhysicalNodeMaterial extends MeshStandardNodeMaterial {
 	/**
 	 * Constructs a new mesh physical node material.
 	 *
-	 * @param {?Object} parameters - The configuration parameter.
+	 * @param {Object} [parameters] - The configuration parameter.
 	 */
 	constructor( parameters ) {
 

package/src/materials/nodes/MeshSSSNodeMaterial.js

@@ -83,7 +83,7 @@ class MeshSSSNodeMaterial extends MeshPhysicalNodeMaterial {
 	/**
 	 * Constructs a new mesh SSS node material.
 	 *
-	 * @param {?Object} parameters - The configuration parameter.
+	 * @param {Object} [parameters] - The configuration parameter.
 	 */
 	constructor( parameters ) {
 

package/src/materials/nodes/MeshStandardNodeMaterial.js

@@ -12,7 +12,7 @@ import { MeshStandardMaterial } from '../MeshStandardMaterial.js';
 const _defaultValues = /*@__PURE__*/ new MeshStandardMaterial();
 
 /**
- * Node material version of `MeshStandardMaterial`.
+ * Node material version of {@link MeshStandardMaterial}.
  *
  * @augments NodeMaterial
  */
@@ -27,7 +27,7 @@ class MeshStandardNodeMaterial extends NodeMaterial {
 	/**
 	 * Constructs a new mesh standard node material.
 	 *
-	 * @param {?Object} parameters - The configuration parameter.
+	 * @param {Object} [parameters] - The configuration parameter.
 	 */
 	constructor( parameters ) {
 

package/src/materials/nodes/MeshToonNodeMaterial.js

@@ -6,7 +6,7 @@ import { MeshToonMaterial } from '../MeshToonMaterial.js';
 const _defaultValues = /*@__PURE__*/ new MeshToonMaterial();
 
 /**
- * Node material version of `MeshToonMaterial`.
+ * Node material version of {@link MeshToonMaterial}.
  *
  * @augments NodeMaterial
  */
@@ -21,7 +21,7 @@ class MeshToonNodeMaterial extends NodeMaterial {
 	/**
 	 * Constructs a new mesh toon node material.
 	 *
-	 * @param {?Object} parameters - The configuration parameter.
+	 * @param {Object} [parameters] - The configuration parameter.
 	 */
 	constructor( parameters ) {
 

package/src/materials/nodes/NodeMaterial.js

@@ -11,7 +11,7 @@ import { instancedMesh } from '../../nodes/accessors/InstancedMeshNode.js';
 import { batch } from '../../nodes/accessors/BatchNode.js';
 import { materialReference } from '../../nodes/accessors/MaterialReferenceNode.js';
 import { positionLocal, positionView } from '../../nodes/accessors/Position.js';
-import { skinningReference } from '../../nodes/accessors/SkinningNode.js';
+import { skinning } from '../../nodes/accessors/SkinningNode.js';
 import { morphReference } from '../../nodes/accessors/MorphNode.js';
 import { mix } from '../../nodes/math/MathNode.js';
 import { float, vec3, vec4 } from '../../nodes/tsl/TSLBase.js';
@@ -476,7 +476,9 @@ class NodeMaterial extends Material {
 
 			//
 
-			if ( this.outputNode !== null ) resultNode = this.outputNode;
+			const isCustomOutput = this.outputNode !== null;
+
+			if ( isCustomOutput ) resultNode = this.outputNode;
 
 			// MRT
 
@@ -487,6 +489,8 @@ class NodeMaterial extends Material {
 
 				if ( mrt !== null ) {
 
+					if ( isCustomOutput ) output.assign( resultNode );
+
 					resultNode = mrt;
 
 					if ( materialMRT !== null ) {
@@ -695,7 +699,7 @@ class NodeMaterial extends Material {
 
 		if ( object.isSkinnedMesh === true ) {
 
-			skinningReference( object ).append();
+			skinning( object ).append();
 
 		}
 

package/src/materials/nodes/PointsNodeMaterial.js

@@ -11,7 +11,7 @@ import { PointsMaterial } from '../PointsMaterial.js';
 const _defaultValues = /*@__PURE__*/ new PointsMaterial();
 
 /**
- * Node material version of `PointsMaterial`.
+ * Node material version of {@link PointsMaterial}.
  *
  * @augments SpriteNodeMaterial
  */

package/src/materials/nodes/ShadowNodeMaterial.js

@@ -6,7 +6,7 @@ import { ShadowMaterial } from '../ShadowMaterial.js';
 const _defaultValues = /*@__PURE__*/ new ShadowMaterial();
 
 /**
- * Node material version of `ShadowMaterial`.
+ * Node material version of {@link ShadowMaterial}.
  *
  * @augments NodeMaterial
  */
@@ -21,7 +21,7 @@ class ShadowNodeMaterial extends NodeMaterial {
 	/**
 	 * Constructs a new shadow node material.
 	 *
-	 * @param {?Object} parameters - The configuration parameter.
+	 * @param {Object} [parameters] - The configuration parameter.
 	 */
 	constructor( parameters ) {
 
@@ -45,6 +45,15 @@ class ShadowNodeMaterial extends NodeMaterial {
 		 */
 		this.lights = true;
 
+		/**
+		 * Overwritten since shadow materials are transparent
+		 * by default.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
+		this.transparent = true;
+
 		this.setDefaultValues( _defaultValues );
 
 		this.setValues( parameters );

package/src/materials/nodes/SpriteNodeMaterial.js

@@ -12,7 +12,7 @@ import { reference } from '../../nodes/accessors/ReferenceBaseNode.js';
 const _defaultValues = /*@__PURE__*/ new SpriteMaterial();
 
 /**
- * Node material version of `SpriteMaterial`.
+ * Node material version of {@link SpriteMaterial}.
  *
  * @augments NodeMaterial
  */

package/src/materials/nodes/VolumeNodeMaterial.js

@@ -18,7 +18,7 @@ class VolumeNodeMaterial extends NodeMaterial {
 	/**
 	 * Constructs a new volume node material.
 	 *
-	 * @param {?Object} parameters - The configuration parameter.
+	 * @param {Object} [parameters] - The configuration parameter.
 	 */
 	constructor( parameters ) {
 
@@ -41,6 +41,15 @@ class VolumeNodeMaterial extends NodeMaterial {
 		 */
 		this.steps = 25;
 
+		/**
+		 * Offsets the distance a ray has been traveled through a volume.
+		 * Can be used to implement dithering to reduce banding.
+		 *
+		 * @type {Node<float>}
+		 * @default null
+		 */
+		this.offsetNode = null;
+
 		/**
 		 * Node used for scattering calculations.
 		 *

package/src/math/Color.js

@@ -559,7 +559,7 @@ class Color {
 	 * Converts the colors RGB values into the HSL format and stores them into the
 	 * given target object.
 	 *
-	 * @param {{h:0,s:0,l:0}} target - The target object that is used to store the method's result.
+	 * @param {{h:number,s:number,l:number}} target - The target object that is used to store the method's result.
 	 * @param {string} [colorSpace=ColorManagement.workingColorSpace] - The color space.
 	 * @return {{h:number,s:number,l:number}} The HSL representation of this color.
 	 */

package/src/math/MathUtils.js

@@ -470,30 +470,253 @@ function normalize( value, array ) {
 
 }
 
+/**
+ * @class
+ * @classdesc A collection of math utility functions.
+ * @hideconstructor
+ */
 const MathUtils = {
 	DEG2RAD: DEG2RAD,
 	RAD2DEG: RAD2DEG,
+	/**
+	 * Generate a [UUID]{@link https://en.wikipedia.org/wiki/Universally_unique_identifier}
+	 * (universally unique identifier).
+	 *
+	 * @static
+	 * @method
+	 * @return {string} The UUID.
+	 */
 	generateUUID: generateUUID,
+	/**
+	 * Clamps the given value between min and max.
+	 *
+	 * @static
+	 * @method
+	 * @param {number} value - The value to clamp.
+	 * @param {number} min - The min value.
+	 * @param {number} max - The max value.
+	 * @return {number} The clamped value.
+	 */
 	clamp: clamp,
+	/**
+	 * Computes the Euclidean modulo of the given parameters that
+	 * is `( ( n % m ) + m ) % m`.
+	 *
+	 * @static
+	 * @method
+	 * @param {number} n - The first parameter.
+	 * @param {number} m - The second parameter.
+	 * @return {number} The Euclidean modulo.
+	 */
 	euclideanModulo: euclideanModulo,
+	/**
+	 * Performs a linear mapping from range `<a1, a2>` to range `<b1, b2>`
+	 * for the given value.
+	 *
+	 * @static
+	 * @method
+	 * @param {number} x - The value to be mapped.
+	 * @param {number} a1 - Minimum value for range A.
+	 * @param {number} a2 - Maximum value for range A.
+	 * @param {number} b1 - Minimum value for range B.
+	 * @param {number} b2 - Maximum value for range B.
+	 * @return {number} The mapped value.
+	 */
 	mapLinear: mapLinear,
+	/**
+	 * Returns the percentage in the closed interval `[0, 1]` of the given value
+	 * between the start and end point.
+	 *
+	 * @static
+	 * @method
+	 * @param {number} x - The start point
+	 * @param {number} y - The end point.
+	 * @param {number} value - A value between start and end.
+	 * @return {number} The interpolation factor.
+	 */
 	inverseLerp: inverseLerp,
+	/**
+	 * Returns a value linearly interpolated from two known points based on the given interval -
+	 * `t = 0` will return `x` and `t = 1` will return `y`.
+	 *
+	 * @static
+	 * @method
+	 * @param {number} x - The start point
+	 * @param {number} y - The end point.
+	 * @param {number} t - The interpolation factor in the closed interval `[0, 1]`.
+	 * @return {number} The interpolated value.
+	 */
 	lerp: lerp,
+	/**
+	 * Smoothly interpolate a number from `x` to `y` in  a spring-like manner using a delta
+	 * time to maintain frame rate independent movement. For details, see
+	 * [Frame rate independent damping using lerp]{@link http://www.rorydriscoll.com/2016/03/07/frame-rate-independent-damping-using-lerp/}.
+	 *
+	 * @static
+	 * @method
+	 * @param {number} x - The current point.
+	 * @param {number} y - The target point.
+	 * @param {number} lambda - A higher lambda value will make the movement more sudden,
+	 * and a lower value will make the movement more gradual.
+	 * @param {number} dt - Delta time in seconds.
+	 * @return {number} The interpolated value.
+	 */
 	damp: damp,
+	/**
+	 * Returns a value that alternates between `0` and the given `length` parameter.
+	 *
+	 * @static
+	 * @method
+	 * @param {number} x - The value to pingpong.
+	 * @param {number} [length=1] - The positive value the function will pingpong to.
+	 * @return {number} The alternated value.
+	 */
 	pingpong: pingpong,
+	/**
+	 * Returns a value in the range `[0,1]` that represents the percentage that `x` has
+	 * moved between `min` and `max`, but smoothed or slowed down the closer `x` is to
+	 * the `min` and `max`.
+	 *
+	 * See [Smoothstep]{@link http://en.wikipedia.org/wiki/Smoothstep} for more details.
+	 *
+	 * @static
+	 * @method
+	 * @param {number} x - The value to evaluate based on its position between min and max.
+	 * @param {number} min - The min value. Any x value below min will be `0`.
+	 * @param {number} max - The max value. Any x value above max will be `1`.
+	 * @return {number} The alternated value.
+	 */
 	smoothstep: smoothstep,
+	/**
+	 * A [variation on smoothstep]{@link https://en.wikipedia.org/wiki/Smoothstep#Variations}
+	 * that has zero 1st and 2nd order derivatives at x=0 and x=1.
+	 *
+	 * @static
+	 * @method
+	 * @param {number} x - The value to evaluate based on its position between min and max.
+	 * @param {number} min - The min value. Any x value below min will be `0`.
+	 * @param {number} max - The max value. Any x value above max will be `1`.
+	 * @return {number} The alternated value.
+	 */
 	smootherstep: smootherstep,
+	/**
+	 * Returns a random integer from `<low, high>` interval.
+	 *
+	 * @static
+	 * @method
+	 * @param {number} low - The lower value boundary.
+	 * @param {number} high - The upper value boundary
+	 * @return {number} A random integer.
+	 */
 	randInt: randInt,
+	/**
+	 * Returns a random float from `<low, high>` interval.
+	 *
+	 * @static
+	 * @method
+	 * @param {number} low - The lower value boundary.
+	 * @param {number} high - The upper value boundary
+	 * @return {number} A random float.
+	 */
 	randFloat: randFloat,
+	/**
+	 * Returns a random integer from `<-range/2, range/2>` interval.
+	 *
+	 * @static
+	 * @method
+	 * @param {number} range - Defines the value range.
+	 * @return {number} A random float.
+	 */
 	randFloatSpread: randFloatSpread,
+	/**
+	 * Returns a deterministic pseudo-random float in the interval `[0, 1]`.
+	 *
+	 * @static
+	 * @method
+	 * @param {number} [s] - The integer seed.
+	 * @return {number} A random float.
+	 */
 	seededRandom: seededRandom,
+	/**
+	 * Converts degrees to radians.
+	 *
+	 * @static
+	 * @method
+	 * @param {number} degrees - A value in degrees.
+	 * @return {number} The converted value in radians.
+	 */
 	degToRad: degToRad,
+	/**
+	 * Converts radians to degrees.
+	 *
+	 * @static
+	 * @method
+	 * @param {number} radians - A value in radians.
+	 * @return {number} The converted value in degrees.
+	 */
 	radToDeg: radToDeg,
+	/**
+	 * Returns `true` if the given number is a power of two.
+	 *
+	 * @static
+	 * @method
+	 * @param {number} value - The value to check.
+	 * @return {boolean} Whether the given number is a power of two or not.
+	 */
 	isPowerOfTwo: isPowerOfTwo,
+	/**
+	 * Returns the smallest power of two that is greater than or equal to the given number.
+	 *
+	 * @static
+	 * @method
+	 * @param {number} value - The value to find a POT for.
+	 * @return {number} The smallest power of two that is greater than or equal to the given number.
+	 */
 	ceilPowerOfTwo: ceilPowerOfTwo,
+	/**
+	 * Returns the largest power of two that is less than or equal to the given number.
+	 *
+	 * @static
+	 * @method
+	 * @param {number} value - The value to find a POT for.
+	 * @return {number} The largest power of two that is less than or equal to the given number.
+	 */
 	floorPowerOfTwo: floorPowerOfTwo,
+	/**
+	 * Sets the given quaternion from the [Intrinsic Proper Euler Angles]{@link https://en.wikipedia.org/wiki/Euler_angles}
+	 * defined by the given angles and order.
+	 *
+	 * Rotations are applied to the axes in the order specified by order:
+	 * rotation by angle `a` is applied first, then by angle `b`, then by angle `c`.
+	 *
+	 * @static
+	 * @method
+	 * @param {Quaternion} q - The quaternion to set.
+	 * @param {number} a - The rotation applied to the first axis, in radians.
+	 * @param {number} b - The rotation applied to the second axis, in radians.
+	 * @param {number} c - The rotation applied to the third axis, in radians.
+	 * @param {('XYX'|'XZX'|'YXY'|'YZY'|'ZXZ'|'ZYZ')} order - A string specifying the axes order.
+	 */
 	setQuaternionFromProperEuler: setQuaternionFromProperEuler,
+	/**
+	 * Normalizes the given value according to the given typed array.
+	 *
+	 * @static
+	 * @method
+	 * @param {number} value - The float value in the range `[0,1]` to normalize.
+	 * @param {TypedArray} array - The typed array that defines the data type of the value.
+	 * @return {number} The normalize value.
+	 */
 	normalize: normalize,
+	/**
+	 * Denormalizes the given value according to the given typed array.
+	 *
+	 * @static
+	 * @method
+	 * @param {number} value - The value to denormalize.
+	 * @param {TypedArray} array - The typed array that defines the data type of the value.
+	 * @return {number} The denormalize (float) value in the range `[0,1]`.
+	 */
 	denormalize: denormalize
 };
 

package/src/nodes/Nodes.js

@@ -56,6 +56,7 @@ export { default as TriplanarTexturesNode } from './utils/TriplanarTexturesNode.
 export { default as ReflectorNode } from './utils/ReflectorNode.js';
 export { default as RTTNode } from './utils/RTTNode.js';
 export { default as MemberNode } from './utils/MemberNode.js';
+export { default as DebugNode } from './utils/DebugNode.js';
 
 // accessors
 export { default as UniformArrayNode } from './accessors/UniformArrayNode.js';

package/src/nodes/accessors/BatchNode.js

@@ -74,8 +74,8 @@ class BatchNode extends Node {
 
 		const getIndirectIndex = Fn( ( [ id ] ) => {
 
-			const size = int( textureSize( textureLoad( this.batchMesh._indirectTexture ), 0 ) );
-			const x = int( id ).modInt( size );
+			const size = int( textureSize( textureLoad( this.batchMesh._indirectTexture ), 0 ).x );
+			const x = int( id ).mod( size );
 			const y = int( id ).div( size );
 			return textureLoad( this.batchMesh._indirectTexture, ivec2( x, y ) ).x;
 
@@ -91,11 +91,11 @@ class BatchNode extends Node {
 
 		const matricesTexture = this.batchMesh._matricesTexture;
 
-		const size = textureSize( textureLoad( matricesTexture ), 0 );
+		const size = int( textureSize( textureLoad( matricesTexture ), 0 ).x );
 		const j = float( indirectId ).mul( 4 ).toInt().toVar();
 
-		const x = j.modInt( size );
-		const y = j.div( int( size ) );
+		const x = j.mod( size );
+		const y = j.div( size );
 		const batchingMatrix = mat4(
 			textureLoad( matricesTexture, ivec2( x, y ) ),
 			textureLoad( matricesTexture, ivec2( x.add( 1 ), y ) ),
@@ -110,9 +110,9 @@ class BatchNode extends Node {
 
 			const getBatchingColor = Fn( ( [ id ] ) => {
 
-				const size = textureSize( textureLoad( colorsTexture ), 0 ).x;
+				const size = int( textureSize( textureLoad( colorsTexture ), 0 ).x );
 				const j = id;
-				const x = j.modInt( size );
+				const x = j.mod( size );
 				const y = j.div( size );
 				return textureLoad( colorsTexture, ivec2( x, y ) ).rgb;
 
@@ -160,4 +160,4 @@ export default BatchNode;
  * @param {BatchedMesh} batchMesh - A reference to batched mesh.
  * @returns {BatchNode}
  */
-export const batch = /*@__PURE__*/ nodeProxy( BatchNode );
+export const batch = /*@__PURE__*/ nodeProxy( BatchNode ).setParameterLength( 1 );

package/src/nodes/accessors/BuiltinNode.js

@@ -60,4 +60,4 @@ export default BuiltinNode;
  * @param {string} name - The name of the built-in shader variable.
  * @returns {BuiltinNode}
  */
-export const builtin = nodeProxy( BuiltinNode );
+export const builtin = nodeProxy( BuiltinNode ).setParameterLength( 1 );

package/src/nodes/accessors/CubeTextureNode.js

@@ -138,4 +138,4 @@ export default CubeTextureNode;
  * @param {?Node<float>} [biasNode=null] - The bias node.
  * @returns {CubeTextureNode}
  */
-export const cubeTexture = /*@__PURE__*/ nodeProxy( CubeTextureNode );
+export const cubeTexture = /*@__PURE__*/ nodeProxy( CubeTextureNode ).setParameterLength( 1, 4 ).setName( 'cubeTexture' );

package/src/nodes/accessors/InstanceNode.js

@@ -63,14 +63,14 @@ class InstanceNode extends Node {
 		/**
 		 * The node that represents the instance matrix data.
 		 *
-		 * @type {Node}
+		 * @type {?Node}
 		 */
 		this.instanceMatrixNode = null;
 
 		/**
 		 * The node that represents the instance color data.
 		 *
-		 * @type {Node}
+		 * @type {?Node}
 		 */
 		this.instanceColorNode = null;
 
@@ -86,14 +86,14 @@ class InstanceNode extends Node {
 		/**
 		 * A reference to a buffer that is used by `instanceMatrixNode`.
 		 *
-		 * @type {InstancedInterleavedBuffer}
+		 * @type {?InstancedInterleavedBuffer}
 		 */
 		this.buffer = null;
 
 		/**
 		 * A reference to a buffer that is used by `instanceColorNode`.
 		 *
-		 * @type {InstancedBufferAttribute}
+		 * @type {?InstancedBufferAttribute}
 		 */
 		this.bufferColor = null;
 
@@ -220,4 +220,4 @@ export default InstanceNode;
  * @param {InstancedBufferAttribute} instanceColor - Instanced buffer attribute representing the instance colors.
  * @returns {InstanceNode}
  */
-export const instance = /*@__PURE__*/ nodeProxy( InstanceNode );
+export const instance = /*@__PURE__*/ nodeProxy( InstanceNode ).setParameterLength( 3 );

package/src/nodes/accessors/InstancedMeshNode.js

@@ -47,4 +47,4 @@ export default InstancedMeshNode;
  * @param {InstancedMesh} instancedMesh - The instancedMesh.
  * @returns {InstancedMeshNode}
  */
-export const instancedMesh = /*@__PURE__*/ nodeProxy( InstancedMeshNode );
+export const instancedMesh = /*@__PURE__*/ nodeProxy( InstancedMeshNode ).setParameterLength( 1 );