@plastic-software/three 0.167.4 → 0.174.0

package/src/nodes/accessors/BuiltinNode.js

@@ -0,0 +1,63 @@
+import Node from '../core/Node.js';
+import { nodeProxy } from '../tsl/TSLBase.js';
+
+/**
+ * The node allows to set values for built-in shader variables. That is
+ * required for features like hardware-accelerated vertex clipping.
+ *
+ * @augments Node
+ */
+class BuiltinNode extends Node {
+
+	/**
+	 * Constructs a new builtin node.
+	 *
+	 * @param {string} name - The name of the built-in shader variable.
+	 */
+	constructor( name ) {
+
+		super( 'float' );
+
+		/**
+		 * The name of the built-in shader variable.
+		 *
+		 * @type {string}
+		 */
+		this.name = name;
+
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
+		this.isBuiltinNode = true;
+
+	}
+
+	/**
+	 * Generates the code snippet of the builtin node.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {string} The generated code snippet.
+	 */
+	generate( /* builder */ ) {
+
+		return this.name;
+
+	}
+
+}
+
+export default BuiltinNode;
+
+/**
+ * TSL function for creating a builtin node.
+ *
+ * @tsl
+ * @function
+ * @param {string} name - The name of the built-in shader variable.
+ * @returns {BuiltinNode}
+ */
+export const builtin = nodeProxy( BuiltinNode );

package/src/nodes/accessors/Camera.js

@@ -0,0 +1,129 @@
+import { uniform } from '../core/UniformNode.js';
+import { renderGroup, sharedUniformGroup } from '../core/UniformGroupNode.js';
+import { Vector3 } from '../../math/Vector3.js';
+import { Fn } from '../tsl/TSLBase.js';
+import { uniformArray } from './UniformArrayNode.js';
+
+/**
+ * TSL object that represents the current `index` value of the camera if used ArrayCamera.
+ *
+ * @tsl
+ * @type {UniformNode<uint>}
+ */
+export const cameraIndex = /*@__PURE__*/ uniform( 0, 'uint' ).setGroup( sharedUniformGroup( 'cameraIndex' ) ).toVarying( 'v_cameraIndex' );
+
+/**
+ * TSL object that represents the `near` value of the camera used for the current render.
+ *
+ * @tsl
+ * @type {UniformNode<float>}
+ */
+export const cameraNear = /*@__PURE__*/ uniform( 'float' ).label( 'cameraNear' ).setGroup( renderGroup ).onRenderUpdate( ( { camera } ) => camera.near );
+
+/**
+ * TSL object that represents the `far` value of the camera used for the current render.
+ *
+ * @tsl
+ * @type {UniformNode<float>}
+ */
+export const cameraFar = /*@__PURE__*/ uniform( 'float' ).label( 'cameraFar' ).setGroup( renderGroup ).onRenderUpdate( ( { camera } ) => camera.far );
+
+/**
+ * TSL object that represents the projection matrix of the camera used for the current render.
+ *
+ * @tsl
+ * @type {UniformNode<mat4>}
+ */
+export const cameraProjectionMatrix = /*@__PURE__*/ ( Fn( ( { camera } ) => {
+
+	let cameraProjectionMatrix;
+
+	if ( camera.isArrayCamera && camera.cameras.length > 0 ) {
+
+		const matrices = [];
+
+		for ( const subCamera of camera.cameras ) {
+
+			matrices.push( subCamera.projectionMatrix );
+
+		}
+
+		const cameraProjectionMatrices = uniformArray( matrices ).setGroup( renderGroup ).label( 'cameraProjectionMatrices' );
+
+		cameraProjectionMatrix = cameraProjectionMatrices.element( cameraIndex ).toVar( 'cameraProjectionMatrix' );
+
+	} else {
+
+		cameraProjectionMatrix = uniform( 'mat4' ).label( 'cameraProjectionMatrix' ).setGroup( renderGroup ).onRenderUpdate( ( { camera } ) => camera.projectionMatrix );
+
+	}
+
+	return cameraProjectionMatrix;
+
+} ).once() )();
+
+/**
+ * TSL object that represents the inverse projection matrix of the camera used for the current render.
+ *
+ * @tsl
+ * @type {UniformNode<mat4>}
+ */
+export const cameraProjectionMatrixInverse = /*@__PURE__*/ uniform( 'mat4' ).label( 'cameraProjectionMatrixInverse' ).setGroup( renderGroup ).onRenderUpdate( ( { camera } ) => camera.projectionMatrixInverse );
+
+/**
+ * TSL object that represents the view matrix of the camera used for the current render.
+ *
+ * @tsl
+ * @type {UniformNode<mat4>}
+ */
+export const cameraViewMatrix = /*@__PURE__*/ ( Fn( ( { camera } ) => {
+
+	let cameraViewMatrix;
+
+	if ( camera.isArrayCamera && camera.cameras.length > 0 ) {
+
+		const matrices = [];
+
+		for ( const subCamera of camera.cameras ) {
+
+			matrices.push( subCamera.matrixWorldInverse );
+
+		}
+
+		const cameraViewMatrices = uniformArray( matrices ).setGroup( renderGroup ).label( 'cameraViewMatrices' );
+
+		cameraViewMatrix = cameraViewMatrices.element( cameraIndex ).toVar( 'cameraViewMatrix' );
+
+	} else {
+
+		cameraViewMatrix = uniform( 'mat4' ).label( 'cameraViewMatrix' ).setGroup( renderGroup ).onRenderUpdate( ( { camera } ) => camera.matrixWorldInverse );
+
+	}
+
+	return cameraViewMatrix;
+
+} ).once() )();
+
+/**
+ * TSL object that represents the world matrix of the camera used for the current render.
+ *
+ * @tsl
+ * @type {UniformNode<mat4>}
+ */
+export const cameraWorldMatrix = /*@__PURE__*/ uniform( 'mat4' ).label( 'cameraWorldMatrix' ).setGroup( renderGroup ).onRenderUpdate( ( { camera } ) => camera.matrixWorld );
+
+/**
+ * TSL object that represents the normal matrix of the camera used for the current render.
+ *
+ * @tsl
+ * @type {UniformNode<mat3>}
+ */
+export const cameraNormalMatrix = /*@__PURE__*/ uniform( 'mat3' ).label( 'cameraNormalMatrix' ).setGroup( renderGroup ).onRenderUpdate( ( { camera } ) => camera.normalMatrix );
+
+/**
+ * TSL object that represents the position in world space of the camera used for the current render.
+ *
+ * @tsl
+ * @type {UniformNode<vec3>}
+ */
+export const cameraPosition = /*@__PURE__*/ uniform( new Vector3() ).label( 'cameraPosition' ).setGroup( renderGroup ).onRenderUpdate( ( { camera }, self ) => self.value.setFromMatrixPosition( camera.matrixWorld ) );

package/src/nodes/accessors/ClippingNode.js

@@ -1,91 +1,133 @@
 
 import Node from '../core/Node.js';
-import { nodeObject } from '../shadernode/ShaderNode.js';
-import { positionView } from './PositionNode.js';
-import { diffuseColor, property } from '../core/PropertyNode.js';
-import { Fn } from '../shadernode/ShaderNode.js';
+import { nodeObject, Fn, bool, float } from '../tsl/TSLBase.js';
+import { positionView } from './Position.js';
+import { diffuseColor } from '../core/PropertyNode.js';
 import { Loop } from '../utils/LoopNode.js';
 import { smoothstep } from '../math/MathNode.js';
 import { uniformArray } from './UniformArrayNode.js';
-
+import { builtin } from './BuiltinNode.js';
+
+/**
+ * This node is used in {@link NodeMaterial} to setup the clipping
+ * which can happen hardware-accelerated (if supported) and optionally
+ * use alpha-to-coverage for anti-aliasing clipped edges.
+ *
+ * @augments Node
+ */
 class ClippingNode extends Node {
 
+	static get type() {
+
+		return 'ClippingNode';
+
+	}
+
+	/**
+	 * Constructs a new clipping node.
+	 *
+	 * @param {('default'|'hardware'|'alphaToCoverage')} [scope='default'] - The node's scope. Similar to other nodes,
+	 * the selected scope influences the behavior of the node and what type of code is generated.
+	 */
 	constructor( scope = ClippingNode.DEFAULT ) {
 
 		super();
 
+		/**
+		 * The node's scope. Similar to other nodes, the selected scope influences
+		 * the behavior of the node and what type of code is generated.
+		 *
+		 * @type {('default'|'hardware'|'alphaToCoverage')}
+		 */
 		this.scope = scope;
 
 	}
 
+	/**
+	 * Setups the node depending on the selected scope.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {Node} The result node.
+	 */
 	setup( builder ) {
 
 		super.setup( builder );
 
 		const clippingContext = builder.clippingContext;
-		const { localClipIntersection, localClippingCount, globalClippingCount } = clippingContext;
+		const { intersectionPlanes, unionPlanes } = clippingContext;
 
-		const numClippingPlanes = globalClippingCount + localClippingCount;
-		const numUnionClippingPlanes = localClipIntersection ? numClippingPlanes - localClippingCount : numClippingPlanes;
+		this.hardwareClipping = builder.material.hardwareClipping;
 
 		if ( this.scope === ClippingNode.ALPHA_TO_COVERAGE ) {
 
-			return this.setupAlphaToCoverage( clippingContext.planes, numClippingPlanes, numUnionClippingPlanes );
+			return this.setupAlphaToCoverage( intersectionPlanes, unionPlanes );
+
+		} else if ( this.scope === ClippingNode.HARDWARE ) {
+
+			return this.setupHardwareClipping( unionPlanes, builder );
 
 		} else {
 
-			return this.setupDefault( clippingContext.planes, numClippingPlanes, numUnionClippingPlanes );
+			return this.setupDefault( intersectionPlanes, unionPlanes );
 
 		}
 
 	}
 
-	setupAlphaToCoverage( planes, numClippingPlanes, numUnionClippingPlanes ) {
+	/**
+	 * Setups alpha to coverage.
+	 *
+	 * @param {Array<Vector4>} intersectionPlanes - The intersection planes.
+	 * @param {Array<Vector4>} unionPlanes - The union planes.
+	 * @return {Node} The result node.
+	 */
+	setupAlphaToCoverage( intersectionPlanes, unionPlanes ) {
 
 		return Fn( () => {
 
-			const clippingPlanes = uniformArray( planes );
+			const distanceToPlane = float().toVar( 'distanceToPlane' );
+			const distanceGradient = float().toVar( 'distanceToGradient' );
 
-			const distanceToPlane = property( 'float', 'distanceToPlane' );
-			const distanceGradient = property( 'float', 'distanceToGradient' );
+			const clipOpacity = float( 1 ).toVar( 'clipOpacity' );
 
-			const clipOpacity = property( 'float', 'clipOpacity' );
+			const numUnionPlanes = unionPlanes.length;
 
-			clipOpacity.assign( 1 );
+			if ( this.hardwareClipping === false && numUnionPlanes > 0 ) {
 
-			let plane;
+				const clippingPlanes = uniformArray( unionPlanes );
 
-			Loop( numUnionClippingPlanes, ( { i } ) => {
+				Loop( numUnionPlanes, ( { i } ) => {
 
-				plane = clippingPlanes.element( i );
+					const plane = clippingPlanes.element( i );
 
-				distanceToPlane.assign( positionView.dot( plane.xyz ).negate().add( plane.w ) );
-				distanceGradient.assign( distanceToPlane.fwidth().div( 2.0 ) );
+					distanceToPlane.assign( positionView.dot( plane.xyz ).negate().add( plane.w ) );
+					distanceGradient.assign( distanceToPlane.fwidth().div( 2.0 ) );
 
-				clipOpacity.mulAssign( smoothstep( distanceGradient.negate(), distanceGradient, distanceToPlane ) );
+					clipOpacity.mulAssign( smoothstep( distanceGradient.negate(), distanceGradient, distanceToPlane ) );
 
-				clipOpacity.equal( 0.0 ).discard();
+				} );
 
-			} );
+			}
 
-			if ( numUnionClippingPlanes < numClippingPlanes ) {
+			const numIntersectionPlanes = intersectionPlanes.length;
 
-				const unionClipOpacity = property( 'float', 'unionclipOpacity' );
+			if ( numIntersectionPlanes > 0 ) {
 
-				unionClipOpacity.assign( 1 );
+				const clippingPlanes = uniformArray( intersectionPlanes );
+				const intersectionClipOpacity = float( 1 ).toVar( 'intersectionClipOpacity' );
 
-				Loop( { start: numUnionClippingPlanes, end: numClippingPlanes }, ( { i } ) => {
+				Loop( numIntersectionPlanes, ( { i } ) => {
 
-					plane = clippingPlanes.element( i );
+					const plane = clippingPlanes.element( i );
 
 					distanceToPlane.assign( positionView.dot( plane.xyz ).negate().add( plane.w ) );
 					distanceGradient.assign( distanceToPlane.fwidth().div( 2.0 ) );
 
-					unionClipOpacity.mulAssign( smoothstep( distanceGradient.negate(), distanceGradient, distanceToPlane ).oneMinus() );
+					intersectionClipOpacity.mulAssign( smoothstep( distanceGradient.negate(), distanceGradient, distanceToPlane ).oneMinus() );
 
 				} );
 
-				clipOpacity.mulAssign( unionClipOpacity.oneMinus() );
+				clipOpacity.mulAssign( intersectionClipOpacity.oneMinus() );
 
 			}
 
@@ -97,30 +139,42 @@ class ClippingNode extends Node {
 
 	}
 
-	setupDefault( planes, numClippingPlanes, numUnionClippingPlanes ) {
+	/**
+	 * Setups the default clipping.
+	 *
+	 * @param {Array<Vector4>} intersectionPlanes - The intersection planes.
+	 * @param {Array<Vector4>} unionPlanes - The union planes.
+	 * @return {Node} The result node.
+	 */
+	setupDefault( intersectionPlanes, unionPlanes ) {
 
 		return Fn( () => {
 
-			const clippingPlanes = uniformArray( planes );
+			const numUnionPlanes = unionPlanes.length;
 
-			let plane;
+			if ( this.hardwareClipping === false && numUnionPlanes > 0 ) {
 
-			Loop( numUnionClippingPlanes, ( { i } ) => {
+				const clippingPlanes = uniformArray( unionPlanes );
 
-				plane = clippingPlanes.element( i );
-				positionView.dot( plane.xyz ).greaterThan( plane.w ).discard();
+				Loop( numUnionPlanes, ( { i } ) => {
 
-			} );
+					const plane = clippingPlanes.element( i );
+					positionView.dot( plane.xyz ).greaterThan( plane.w ).discard();
+
+				} );
+
+			}
 
-			if ( numUnionClippingPlanes < numClippingPlanes ) {
+			const numIntersectionPlanes = intersectionPlanes.length;
 
-				const clipped = property( 'bool', 'clipped' );
+			if ( numIntersectionPlanes > 0 ) {
 
-				clipped.assign( true );
+				const clippingPlanes = uniformArray( intersectionPlanes );
+				const clipped = bool( true ).toVar( 'clipped' );
 
-				Loop( { start: numUnionClippingPlanes, end: numClippingPlanes }, ( { i } ) => {
+				Loop( numIntersectionPlanes, ( { i } ) => {
 
-					plane = clippingPlanes.element( i );
+					const plane = clippingPlanes.element( i );
 					clipped.assign( positionView.dot( plane.xyz ).greaterThan( plane.w ).and( clipped ) );
 
 				} );
@@ -133,13 +187,68 @@ class ClippingNode extends Node {
 
 	}
 
+	/**
+	 * Setups hardware clipping.
+	 *
+	 * @param {Array<Vector4>} unionPlanes - The union planes.
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {Node} The result node.
+	 */
+	setupHardwareClipping( unionPlanes, builder ) {
+
+		const numUnionPlanes = unionPlanes.length;
+
+		builder.enableHardwareClipping( numUnionPlanes );
+
+		return Fn( () => {
+
+			const clippingPlanes = uniformArray( unionPlanes );
+			const hw_clip_distances = builtin( builder.getClipDistance() );
+
+			Loop( numUnionPlanes, ( { i } ) => {
+
+				const plane = clippingPlanes.element( i );
+
+				const distance = positionView.dot( plane.xyz ).sub( plane.w ).negate();
+				hw_clip_distances.element( i ).assign( distance );
+
+			} );
+
+		} )();
+
+	}
+
 }
 
 ClippingNode.ALPHA_TO_COVERAGE = 'alphaToCoverage';
 ClippingNode.DEFAULT = 'default';
+ClippingNode.HARDWARE = 'hardware';
 
 export default ClippingNode;
 
+/**
+ * TSL function for setting up the default clipping logic.
+ *
+ * @tsl
+ * @function
+ * @returns {ClippingNode}
+ */
 export const clipping = () => nodeObject( new ClippingNode() );
 
+/**
+ * TSL function for setting up alpha to coverage.
+ *
+ * @tsl
+ * @function
+ * @returns {ClippingNode}
+ */
 export const clippingAlpha = () => nodeObject( new ClippingNode( ClippingNode.ALPHA_TO_COVERAGE ) );
+
+/**
+ * TSL function for setting up hardware-based clipping.
+ *
+ * @tsl
+ * @function
+ * @returns {ClippingNode}
+ */
+export const hardwareClipping = () => nodeObject( new ClippingNode( ClippingNode.HARDWARE ) );

package/src/nodes/accessors/CubeTextureNode.js

@@ -1,26 +1,63 @@
 import TextureNode from './TextureNode.js';
-import { reflectVector, refractVector } from './ReflectVectorNode.js';
-import { addNodeClass } from '../core/Node.js';
-import { addNodeElement, nodeProxy, vec3 } from '../shadernode/ShaderNode.js';
+import { reflectVector, refractVector } from './ReflectVector.js';
+import { nodeProxy, vec3 } from '../tsl/TSLBase.js';
 
 import { CubeReflectionMapping, CubeRefractionMapping, WebGPUCoordinateSystem } from '../../constants.js';
+import { materialEnvRotation } from './MaterialProperties.js';
 
+/**
+ * This type of uniform node represents a cube texture.
+ *
+ * @augments TextureNode
+ */
 class CubeTextureNode extends TextureNode {
 
+	static get type() {
+
+		return 'CubeTextureNode';
+
+	}
+
+	/**
+	 * Constructs a new cube texture node.
+	 *
+	 * @param {CubeTexture} value - The cube texture.
+	 * @param {?Node<vec3>} [uvNode=null] - The uv node.
+	 * @param {?Node<int>} [levelNode=null] - The level node.
+	 * @param {?Node<float>} [biasNode=null] - The bias node.
+	 */
 	constructor( value, uvNode = null, levelNode = null, biasNode = null ) {
 
 		super( value, uvNode, levelNode, biasNode );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isCubeTextureNode = true;
 
 	}
 
+	/**
+	 * Overwrites the default implementation to return a fixed value `'cubeTexture'`.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {string} The input type.
+	 */
 	getInputType( /*builder*/ ) {
 
 		return 'cubeTexture';
 
 	}
 
+	/**
+	 * Returns a default uvs based on the mapping type of the cube texture.
+	 *
+	 * @return {Node<vec3>} The default uv attribute.
+	 */
 	getDefaultUV() {
 
 		const texture = this.value;
@@ -43,24 +80,43 @@ class CubeTextureNode extends TextureNode {
 
 	}
 
+	/**
+	 * Overwritten with an empty implementation since the `updateMatrix` flag is ignored
+	 * for cube textures. The uv transformation matrix is not applied to cube textures.
+	 *
+	 * @param {boolean} value - The update toggle.
+	 */
 	setUpdateMatrix( /*updateMatrix*/ ) { } // Ignore .updateMatrix for CubeTextureNode
 
+	/**
+	 * Setups the uv node. Depending on the backend as well as the texture type, it might be necessary
+	 * to modify the uv node for correct sampling.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @param {Node} uvNode - The uv node to setup.
+	 * @return {Node} The updated uv node.
+	 */
 	setupUV( builder, uvNode ) {
 
 		const texture = this.value;
 
 		if ( builder.renderer.coordinateSystem === WebGPUCoordinateSystem || ! texture.isRenderTargetTexture ) {
 
-			return vec3( uvNode.x.negate(), uvNode.yz );
-
-		} else {
-
-			return uvNode;
+			uvNode = vec3( uvNode.x.negate(), uvNode.yz );
 
 		}
 
+		return materialEnvRotation.mul( uvNode );
+
 	}
 
+	/**
+	 * Generates the uv code snippet.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @param {Node} cubeUV - The uv node to generate code for.
+	 * @return {string} The generated code snippet.
+	 */
 	generateUV( builder, cubeUV ) {
 
 		return cubeUV.build( builder, 'vec3' );
@@ -71,8 +127,15 @@ class CubeTextureNode extends TextureNode {
 
 export default CubeTextureNode;
 
-export const cubeTexture = nodeProxy( CubeTextureNode );
-
-addNodeElement( 'cubeTexture', cubeTexture );
-
-addNodeClass( 'CubeTextureNode', CubeTextureNode );
+/**
+ * TSL function for creating a cube texture node.
+ *
+ * @tsl
+ * @function
+ * @param {CubeTexture} value - The cube texture.
+ * @param {?Node<vec3>} [uvNode=null] - The uv node.
+ * @param {?Node<int>} [levelNode=null] - The level node.
+ * @param {?Node<float>} [biasNode=null] - The bias node.
+ * @returns {CubeTextureNode}
+ */
+export const cubeTexture = /*@__PURE__*/ nodeProxy( CubeTextureNode );