super-three 0.171.0 → 0.172.0

package/src/materials/nodes/Line2NodeMaterial.js

@@ -1,5 +1,5 @@
 import NodeMaterial from './NodeMaterial.js';
-import { varyingProperty } from '../../nodes/core/PropertyNode.js';
+import { dashSize, gapSize, varyingProperty } from '../../nodes/core/PropertyNode.js';
 import { attribute } from '../../nodes/core/AttributeNode.js';
 import { cameraProjectionMatrix } from '../../nodes/accessors/Camera.js';
 import { materialColor, materialLineScale, materialLineDashSize, materialLineGapSize, materialLineDashOffset, materialLineWidth, materialOpacity } from '../../nodes/accessors/MaterialNode.js';
@@ -9,7 +9,6 @@ import { mix, smoothstep } from '../../nodes/math/MathNode.js';
 import { Fn, float, vec2, vec3, vec4, If } from '../../nodes/tsl/TSLBase.js';
 import { uv } from '../../nodes/accessors/UV.js';
 import { viewport } from '../../nodes/display/ScreenNode.js';
-import { dashSize, gapSize } from '../../nodes/core/PropertyNode.js';
 import { viewportSharedTexture } from '../../nodes/display/ViewportSharedTextureNode.js';
 
 import { LineDashedMaterial } from '../LineDashedMaterial.js';
@@ -17,6 +16,12 @@ import { NoBlending } from '../../constants.js';
 
 const _defaultValues = /*@__PURE__*/ new LineDashedMaterial();
 
+/**
+ * This node material can be used to render lines with a size larger than one
+ * by representing them as instanced meshes.
+ *
+ * @augments NodeMaterial
+ */
 class Line2NodeMaterial extends NodeMaterial {
 
 	static get type() {
@@ -25,49 +30,120 @@ class Line2NodeMaterial extends NodeMaterial {
 
 	}
 
-	constructor( params = {} ) {
+	/**
+	 * Constructs a new node material for wide line rendering.
+	 *
+	 * @param {Object?} parameters - The configuration parameter.
+	 */
+	constructor( parameters = {} ) {
 
 		super();
 
-		this.lights = false;
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
+		this.isLine2NodeMaterial = true;
 
 		this.setDefaultValues( _defaultValues );
 
-		this.useAlphaToCoverage = true;
-		this.useColor = params.vertexColors;
-		this.useDash = params.dashed;
-		this.useWorldUnits = false;
-
+		/**
+		 * Whether vertex colors should be used or not.
+		 *
+		 * @type {Boolean}
+		 * @default false
+		 */
+		this.useColor = parameters.vertexColors;
+
+		/**
+		 * The dash offset.
+		 *
+		 * @type {Number}
+		 * @default 0
+		 */
 		this.dashOffset = 0;
+
+		/**
+		 * The line width.
+		 *
+		 * @type {Number}
+		 * @default 0
+		 */
 		this.lineWidth = 1;
 
+		/**
+		 * Defines the lines color.
+		 *
+		 * @type {Node<vec3>?}
+		 * @default null
+		 */
 		this.lineColorNode = null;
 
+		/**
+		 * Defines the offset.
+		 *
+		 * @type {Node<float>?}
+		 * @default null
+		 */
 		this.offsetNode = null;
+
+		/**
+		 * Defines the dash scale.
+		 *
+		 * @type {Node<float>?}
+		 * @default null
+		 */
 		this.dashScaleNode = null;
+
+		/**
+		 * Defines the dash size.
+		 *
+		 * @type {Node<float>?}
+		 * @default null
+		 */
 		this.dashSizeNode = null;
+
+		/**
+		 * Defines the gap size.
+		 *
+		 * @type {Node<float>?}
+		 * @default null
+		 */
 		this.gapSizeNode = null;
 
+		/**
+		 * Blending is set to `NoBlending` since transparency
+		 * is not supported, yet.
+		 *
+		 * @type {Number}
+		 * @default 0
+		 */
 		this.blending = NoBlending;
 
-		this.setValues( params );
+		this._useDash = parameters.dashed;
+		this._useAlphaToCoverage = true;
+		this._useWorldUnits = false;
+
+		this.setValues( parameters );
 
 	}
 
+	/**
+	 * Setups the vertex and fragment stage of this node material.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 */
 	setup( builder ) {
 
-		this.setupShaders( builder );
-
-		super.setup( builder );
-
-	}
-
-	setupShaders( { renderer } ) {
+		const { renderer } = builder;
 
-		const useAlphaToCoverage = this.alphaToCoverage;
+		const useAlphaToCoverage = this._useAlphaToCoverage;
 		const useColor = this.useColor;
-		const useDash = this.dashed;
-		const useWorldUnits = this.worldUnits;
+		const useDash = this._useDash;
+		const useWorldUnits = this._useWorldUnits;
 
 		const trimSegment = Fn( ( { start, end } ) => {
 
@@ -101,7 +177,7 @@ class Line2NodeMaterial extends NodeMaterial {
 			if ( useDash ) {
 
 				const dashScaleNode = this.dashScaleNode ? float( this.dashScaleNode ) : materialLineScale;
-				const offsetNode = this.offsetNode ? float( this.offsetNodeNode ) : materialLineDashOffset;
+				const offsetNode = this.offsetNode ? float( this.offsetNode ) : materialLineDashOffset;
 
 				const instanceDistanceStart = attribute( 'instanceDistanceStart' );
 				const instanceDistanceEnd = attribute( 'instanceDistanceEnd' );
@@ -278,7 +354,7 @@ class Line2NodeMaterial extends NodeMaterial {
 			if ( useDash ) {
 
 				const dashSizeNode = this.dashSizeNode ? float( this.dashSizeNode ) : materialLineDashSize;
-				const gapSizeNode = this.dashSizeNode ? float( this.dashGapNode ) : materialLineGapSize;
+				const gapSizeNode = this.gapSizeNode ? float( this.gapSizeNode ) : materialLineGapSize;
 
 				dashSize.assign( dashSizeNode );
 				gapSize.assign( gapSizeNode );
@@ -395,56 +471,74 @@ class Line2NodeMaterial extends NodeMaterial {
 
 		}
 
-	}
+		super.setup( builder );
 
+	}
 
+	/**
+	 * Whether the lines should sized in world units or not.
+	 * When set to `false` the unit is pixel.
+	 *
+	 * @type {Boolean}
+	 * @default false
+	 */
 	get worldUnits() {
 
-		return this.useWorldUnits;
+		return this._useWorldUnits;
 
 	}
 
 	set worldUnits( value ) {
 
-		if ( this.useWorldUnits !== value ) {
+		if ( this._useWorldUnits !== value ) {
 
-			this.useWorldUnits = value;
+			this._useWorldUnits = value;
 			this.needsUpdate = true;
 
 		}
 
 	}
 
-
+	/**
+	 * Whether the lines should be dashed or not.
+	 *
+	 * @type {Boolean}
+	 * @default false
+	 */
 	get dashed() {
 
-		return this.useDash;
+		return this._useDash;
 
 	}
 
 	set dashed( value ) {
 
-		if ( this.useDash !== value ) {
+		if ( this._useDash !== value ) {
 
-			this.useDash = value;
+			this._useDash = value;
 			this.needsUpdate = true;
 
 		}
 
 	}
 
-
+	/**
+	 * Whether alpha to coverage should be used or not.
+	 *
+	 * @type {Boolean}
+	 * @default true
+	 */
 	get alphaToCoverage() {
 
-		return this.useAlphaToCoverage;
+		return this._useAlphaToCoverage;
 
 	}
 
 	set alphaToCoverage( value ) {
 
-		if ( this.useAlphaToCoverage !== value ) {
+		if ( this._useAlphaToCoverage !== value ) {
 
-			this.useAlphaToCoverage = value;
+			this._useAlphaToCoverage = value;
 			this.needsUpdate = true;
 
 		}

package/src/materials/nodes/LineBasicNodeMaterial.js

@@ -4,6 +4,11 @@ import { LineBasicMaterial } from '../LineBasicMaterial.js';
 
 const _defaultValues = /*@__PURE__*/ new LineBasicMaterial();
 
+/**
+ * Node material version of `LineBasicMaterial`.
+ *
+ * @augments NodeMaterial
+ */
 class LineBasicNodeMaterial extends NodeMaterial {
 
 	static get type() {
@@ -12,14 +17,24 @@ class LineBasicNodeMaterial extends NodeMaterial {
 
 	}
 
+	/**
+	 * Constructs a new line basic node material.
+	 *
+	 * @param {Object?} parameters - The configuration parameter.
+	 */
 	constructor( parameters ) {
 
 		super();
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isLineBasicNodeMaterial = true;
 
-		this.lights = false;
-
 		this.setDefaultValues( _defaultValues );
 
 		this.setValues( parameters );

package/src/materials/nodes/LineDashedNodeMaterial.js

@@ -8,6 +8,11 @@ import { LineDashedMaterial } from '../LineDashedMaterial.js';
 
 const _defaultValues = /*@__PURE__*/ new LineDashedMaterial();
 
+/**
+ * Node material version of `LineDashedMaterial`.
+ *
+ * @augments NodeMaterial
+ */
 class LineDashedNodeMaterial extends NodeMaterial {
 
 	static get type() {
@@ -16,33 +21,101 @@ class LineDashedNodeMaterial extends NodeMaterial {
 
 	}
 
+	/**
+	 * Constructs a new line dashed node material.
+	 *
+	 * @param {Object?} parameters - The configuration parameter.
+	 */
 	constructor( parameters ) {
 
 		super();
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isLineDashedNodeMaterial = true;
 
-		this.lights = false;
-
 		this.setDefaultValues( _defaultValues );
 
+		/**
+		 * The dash offset.
+		 *
+		 * @type {Number}
+		 * @default 0
+		 */
 		this.dashOffset = 0;
 
+		/**
+		 * The offset of dash materials is by default inferred from the `dashOffset`
+		 * property. This node property allows to overwrite the default
+		 * and define the offset with a node instead.
+		 *
+		 * If you don't want to overwrite the offset but modify the existing
+		 * value instead, use {@link module:MaterialNode.materialLineDashOffset}.
+		 *
+		 * @type {Node<float>?}
+		 * @default null
+		 */
 		this.offsetNode = null;
+
+		/**
+		 * The scale of dash materials is by default inferred from the `scale`
+		 * property. This node property allows to overwrite the default
+		 * and define the scale with a node instead.
+		 *
+		 * If you don't want to overwrite the scale but modify the existing
+		 * value instead, use {@link module:MaterialNode.materialLineScale}.
+		 *
+		 * @type {Node<float>?}
+		 * @default null
+		 */
 		this.dashScaleNode = null;
+
+		/**
+		 * The dash size of dash materials is by default inferred from the `dashSize`
+		 * property. This node property allows to overwrite the default
+		 * and define the dash size with a node instead.
+		 *
+		 * If you don't want to overwrite the dash size but modify the existing
+		 * value instead, use {@link module:MaterialNode.materialLineDashSize}.
+		 *
+		 * @type {Node<float>?}
+		 * @default null
+		 */
 		this.dashSizeNode = null;
+
+		/**
+		 * The gap size of dash materials is by default inferred from the `gapSize`
+		 * property. This node property allows to overwrite the default
+		 * and define the gap size with a node instead.
+		 *
+		 * If you don't want to overwrite the gap size but modify the existing
+		 * value instead, use {@link module:MaterialNode.materialLineGapSize}.
+		 *
+		 * @type {Node<float>?}
+		 * @default null
+		 */
 		this.gapSizeNode = null;
 
 		this.setValues( parameters );
 
 	}
 
-	setupVariants() {
+	/**
+	 * Setups the dash specific node variables.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 */
+	setupVariants( /* builder */ ) {
 
-		const offsetNode = this.offsetNode ? float( this.offsetNodeNode ) : materialLineDashOffset;
+		const offsetNode = this.offsetNode ? float( this.offsetNode ) : materialLineDashOffset;
 		const dashScaleNode = this.dashScaleNode ? float( this.dashScaleNode ) : materialLineScale;
 		const dashSizeNode = this.dashSizeNode ? float( this.dashSizeNode ) : materialLineDashSize;
-		const gapSizeNode = this.dashSizeNode ? float( this.dashGapNode ) : materialLineGapSize;
+		const gapSizeNode = this.gapSizeNode ? float( this.gapSizeNode ) : materialLineGapSize;
 
 		dashSize.assign( dashSizeNode );
 		gapSize.assign( gapSizeNode );

package/src/materials/nodes/MeshBasicNodeMaterial.js

@@ -10,6 +10,11 @@ import { MeshBasicMaterial } from '../MeshBasicMaterial.js';
 
 const _defaultValues = /*@__PURE__*/ new MeshBasicMaterial();
 
+/**
+ * Node material version of `MeshBasicMaterial`.
+ *
+ * @augments NodeMaterial
+ */
 class MeshBasicNodeMaterial extends NodeMaterial {
 
 	static get type() {
@@ -18,12 +23,32 @@ class MeshBasicNodeMaterial extends NodeMaterial {
 
 	}
 
+	/**
+	 * Constructs a new mesh basic node material.
+	 *
+	 * @param {Object?} parameters - The configuration parameter.
+	 */
 	constructor( parameters ) {
 
 		super();
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isMeshBasicNodeMaterial = true;
 
+		/**
+		 * Although the basic material is by definition unlit, we set
+		 * this property to `true` since we use a lighting model to compute
+		 * the outgoing light of the fragment shader.
+		 *
+		 * @type {Boolean}
+		 * @default true
+		 */
 		this.lights = true;
 
 		this.setDefaultValues( _defaultValues );
@@ -32,12 +57,25 @@ class MeshBasicNodeMaterial extends NodeMaterial {
 
 	}
 
+	/**
+	 * Basic materials are not affected by normal and bump maps so we
+	 * return by default {@link module:Normal.normalView}.
+	 *
+	 * @return {Node<vec3>} The normal node.
+	 */
 	setupNormal() {
 
 		return normalView; // see #28839
 
 	}
 
+	/**
+	 * Overwritten since this type of material uses {@link BasicEnvironmentNode}
+	 * to implement the default environment mapping.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {BasicEnvironmentNode<vec3>?} The environment node.
+	 */
 	setupEnvironment( builder ) {
 
 		const envNode = super.setupEnvironment( builder );
@@ -46,6 +84,13 @@ class MeshBasicNodeMaterial extends NodeMaterial {
 
 	}
 
+	/**
+	 * This method must be overwriten since light maps are evaluated
+	 * with a special scaling factor for basic materials.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {BasicLightMapNode<vec3>?} The light map node.
+	 */
 	setupLightMap( builder ) {
 
 		let node = null;
@@ -60,12 +105,23 @@ class MeshBasicNodeMaterial extends NodeMaterial {
 
 	}
 
+	/**
+	 * The material overwrites this method because `lights` is set to `true` but
+	 * we still want to return the diffuse color as the outgoing light.
+	 *
+	 * @return {Node<vec3>} The outgoing light node.
+	 */
 	setupOutgoingLight() {
 
 		return diffuseColor.rgb;
 
 	}
 
+	/**
+	 * Setups the lighting model.
+	 *
+	 * @return {BasicLightingModel} The lighting model.
+	 */
 	setupLightingModel() {
 
 		return new BasicLightingModel();

package/src/materials/nodes/MeshLambertNodeMaterial.js

@@ -6,6 +6,11 @@ import { MeshLambertMaterial } from '../MeshLambertMaterial.js';
 
 const _defaultValues = /*@__PURE__*/ new MeshLambertMaterial();
 
+/**
+ * Node material version of `MeshLambertMaterial`.
+ *
+ * @augments NodeMaterial
+ */
 class MeshLambertNodeMaterial extends NodeMaterial {
 
 	static get type() {
@@ -14,12 +19,30 @@ class MeshLambertNodeMaterial extends NodeMaterial {
 
 	}
 
+	/**
+	 * Constructs a new mesh lambert node material.
+	 *
+	 * @param {Object?} parameters - The configuration parameter.
+	 */
 	constructor( parameters ) {
 
 		super();
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isMeshLambertNodeMaterial = true;
 
+		/**
+		 * Set to `true` because lambert materials react on lights.
+		 *
+		 * @type {Boolean}
+		 * @default true
+		 */
 		this.lights = true;
 
 		this.setDefaultValues( _defaultValues );
@@ -28,6 +51,13 @@ class MeshLambertNodeMaterial extends NodeMaterial {
 
 	}
 
+	/**
+	 * Overwritten since this type of material uses {@link BasicEnvironmentNode}
+	 * to implement the default environment mapping.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {BasicEnvironmentNode<vec3>?} The environment node.
+	 */
 	setupEnvironment( builder ) {
 
 		const envNode = super.setupEnvironment( builder );
@@ -36,6 +66,11 @@ class MeshLambertNodeMaterial extends NodeMaterial {
 
 	}
 
+	/**
+	 * Setups the lighting model.
+	 *
+	 * @return {PhongLightingModel} The lighting model.
+	 */
 	setupLightingModel( /*builder*/ ) {
 
 		return new PhongLightingModel( false ); // ( specular ) -> force lambert

package/src/materials/nodes/MeshMatcapNodeMaterial.js

@@ -9,6 +9,11 @@ import { MeshMatcapMaterial } from '../MeshMatcapMaterial.js';
 
 const _defaultValues = /*@__PURE__*/ new MeshMatcapMaterial();
 
+/**
+ * Node material version of `MeshMatcapMaterial`.
+ *
+ * @augments NodeMaterial
+ */
 class MeshMatcapNodeMaterial extends NodeMaterial {
 
 	static get type() {
@@ -17,12 +22,22 @@ class MeshMatcapNodeMaterial extends NodeMaterial {
 
 	}
 
+	/**
+	 * Constructs a new mesh normal node material.
+	 *
+	 * @param {Object?} parameters - The configuration parameter.
+	 */
 	constructor( parameters ) {
 
 		super();
 
-		this.lights = false;
-
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isMeshMatcapNodeMaterial = true;
 
 		this.setDefaultValues( _defaultValues );
@@ -31,6 +46,11 @@ class MeshMatcapNodeMaterial extends NodeMaterial {
 
 	}
 
+	/**
+	 * Setups the matcap specific node variables.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 */
 	setupVariants( builder ) {
 
 		const uv = matcapUV;

package/src/materials/nodes/MeshNormalNodeMaterial.js

@@ -9,6 +9,11 @@ import { MeshNormalMaterial } from '../MeshNormalMaterial.js';
 
 const _defaultValues = /*@__PURE__*/ new MeshNormalMaterial();
 
+/**
+ * Node material version of `MeshNormalMaterial`.
+ *
+ * @augments NodeMaterial
+ */
 class MeshNormalNodeMaterial extends NodeMaterial {
 
 	static get type() {
@@ -17,12 +22,22 @@ class MeshNormalNodeMaterial extends NodeMaterial {
 
 	}
 
+	/**
+	 * Constructs a new mesh normal node material.
+	 *
+	 * @param {Object?} parameters - The configuration parameter.
+	 */
 	constructor( parameters ) {
 
 		super();
 
-		this.lights = false;
-
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isMeshNormalNodeMaterial = true;
 
 		this.setDefaultValues( _defaultValues );
@@ -31,6 +46,10 @@ class MeshNormalNodeMaterial extends NodeMaterial {
 
 	}
 
+	/**
+	 * Overwrites the default implementation by computing the diffuse color
+	 * based on the normal data.
+	 */
 	setupDiffuseColor() {
 
 		const opacityNode = this.opacityNode ? float( this.opacityNode ) : materialOpacity;