@plastic-software/three 0.167.3 → 0.174.0

package/src/nodes/accessors/Object3DNode.js

@@ -1,60 +1,113 @@
-import Node, { addNodeClass } from '../core/Node.js';
+import Node from '../core/Node.js';
 import { NodeUpdateType } from '../core/constants.js';
 import UniformNode from '../core/UniformNode.js';
-import { nodeProxy } from '../shadernode/ShaderNode.js';
-
+import { nodeProxy } from '../tsl/TSLBase.js';
 import { Vector3 } from '../../math/Vector3.js';
-
+import { Sphere } from '../../math/Sphere.js';
+
+const _sphere = /*@__PURE__*/ new Sphere();
+
+/**
+ * This node can be used to access transformation related metrics of 3D objects.
+ * Depending on the selected scope, a different metric is represented as a uniform
+ * in the shader. The following scopes are supported:
+ *
+ * - `POSITION`: The object's position in world space.
+ * - `VIEW_POSITION`: The object's position in view/camera space.
+ * - `DIRECTION`: The object's direction in world space.
+ * - `SCALE`: The object's scale in world space.
+ * - `WORLD_MATRIX`: The object's matrix in world space.
+ *
+ * @augments Node
+ */
 class Object3DNode extends Node {
 
-	constructor( scope = Object3DNode.VIEW_MATRIX, object3d = null ) {
+	static get type() {
+
+		return 'Object3DNode';
+
+	}
+
+	/**
+	 * Constructs a new object 3D node.
+	 *
+	 * @param {('position'|'viewPosition'|'direction'|'scale'|'worldMatrix')} scope - The node represents a different type of transformation depending on the scope.
+	 * @param {?Object3D} [object3d=null] - The 3D object.
+	 */
+	constructor( scope, object3d = null ) {
 
 		super();
 
+		/**
+		 * The node reports a different type of transformation depending on the scope.
+		 *
+		 * @type {('position'|'viewPosition'|'direction'|'scale'|'worldMatrix')}
+		 */
 		this.scope = scope;
+
+		/**
+		 * The 3D object.
+		 *
+		 * @type {?Object3D}
+		 * @default null
+		 */
 		this.object3d = object3d;
 
+		/**
+		 * Overwritten since this type of node is updated per object.
+		 *
+		 * @type {string}
+		 * @default 'object'
+		 */
 		this.updateType = NodeUpdateType.OBJECT;
 
+		/**
+		 * Holds the value of the node as a uniform.
+		 *
+		 * @private
+		 * @type {UniformNode}
+		 */
 		this._uniformNode = new UniformNode( null );
 
 	}
 
+	/**
+	 * Overwritten since the node type is inferred from the scope.
+	 *
+	 * @return {string} The node type.
+	 */
 	getNodeType() {
 
 		const scope = this.scope;
 
-		if ( scope === Object3DNode.WORLD_MATRIX || scope === Object3DNode.VIEW_MATRIX ) {
+		if ( scope === Object3DNode.WORLD_MATRIX ) {
 
 			return 'mat4';
 
-		} else if ( scope === Object3DNode.NORMAL_MATRIX ) {
-
-			return 'mat3';
-
 		} else if ( scope === Object3DNode.POSITION || scope === Object3DNode.VIEW_POSITION || scope === Object3DNode.DIRECTION || scope === Object3DNode.SCALE ) {
 
 			return 'vec3';
 
+		} else if ( scope === Object3DNode.RADIUS ) {
+
+			return 'float';
+
 		}
 
 	}
 
+	/**
+	 * Updates the uniform value depending on the scope.
+	 *
+	 * @param {NodeFrame} frame - The current node frame.
+	 */
 	update( frame ) {
 
 		const object = this.object3d;
 		const uniformNode = this._uniformNode;
 		const scope = this.scope;
 
-		if ( scope === Object3DNode.VIEW_MATRIX ) {
-
-			uniformNode.value = object.modelViewMatrix;
-
-		} else if ( scope === Object3DNode.NORMAL_MATRIX ) {
-
-			uniformNode.value = object.normalMatrix;
-
-		} else if ( scope === Object3DNode.WORLD_MATRIX ) {
+		if ( scope === Object3DNode.WORLD_MATRIX ) {
 
 			uniformNode.value = object.matrixWorld;
 
@@ -85,26 +138,43 @@ class Object3DNode extends Node {
 
 			uniformNode.value.applyMatrix4( camera.matrixWorldInverse );
 
+		} else if ( scope === Object3DNode.RADIUS ) {
+
+			const geometry = frame.object.geometry;
+
+			if ( geometry.boundingSphere === null ) geometry.computeBoundingSphere();
+
+			_sphere.copy( geometry.boundingSphere ).applyMatrix4( object.matrixWorld );
+
+			uniformNode.value = _sphere.radius;
+
 		}
 
 	}
 
+	/**
+	 * Generates the code snippet of the uniform node. The node type of the uniform
+	 * node also depends on the selected scope.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {string} The generated code snippet.
+	 */
 	generate( builder ) {
 
 		const scope = this.scope;
 
-		if ( scope === Object3DNode.WORLD_MATRIX || scope === Object3DNode.VIEW_MATRIX ) {
+		if ( scope === Object3DNode.WORLD_MATRIX ) {
 
 			this._uniformNode.nodeType = 'mat4';
 
-		} else if ( scope === Object3DNode.NORMAL_MATRIX ) {
-
-			this._uniformNode.nodeType = 'mat3';
-
 		} else if ( scope === Object3DNode.POSITION || scope === Object3DNode.VIEW_POSITION || scope === Object3DNode.DIRECTION || scope === Object3DNode.SCALE ) {
 
 			this._uniformNode.nodeType = 'vec3';
 
+		} else if ( scope === Object3DNode.RADIUS ) {
+
+			this._uniformNode.nodeType = 'float';
+
 		}
 
 		return this._uniformNode.build( builder );
@@ -129,22 +199,71 @@ class Object3DNode extends Node {
 
 }
 
-Object3DNode.VIEW_MATRIX = 'viewMatrix';
-Object3DNode.NORMAL_MATRIX = 'normalMatrix';
 Object3DNode.WORLD_MATRIX = 'worldMatrix';
 Object3DNode.POSITION = 'position';
 Object3DNode.SCALE = 'scale';
 Object3DNode.VIEW_POSITION = 'viewPosition';
 Object3DNode.DIRECTION = 'direction';
+Object3DNode.RADIUS = 'radius';
 
 export default Object3DNode;
 
-export const objectDirection = nodeProxy( Object3DNode, Object3DNode.DIRECTION );
-export const objectViewMatrix = nodeProxy( Object3DNode, Object3DNode.VIEW_MATRIX );
-export const objectNormalMatrix = nodeProxy( Object3DNode, Object3DNode.NORMAL_MATRIX );
-export const objectWorldMatrix = nodeProxy( Object3DNode, Object3DNode.WORLD_MATRIX );
-export const objectPosition = nodeProxy( Object3DNode, Object3DNode.POSITION );
-export const objectScale = nodeProxy( Object3DNode, Object3DNode.SCALE );
-export const objectViewPosition = nodeProxy( Object3DNode, Object3DNode.VIEW_POSITION );
-
-addNodeClass( 'Object3DNode', Object3DNode );
+/**
+ * TSL function for creating an object 3D node that represents the object's direction in world space.
+ *
+ * @tsl
+ * @function
+ * @param {?Object3D} [object3d=null] - The 3D object.
+ * @returns {Object3DNode<vec3>}
+ */
+export const objectDirection = /*@__PURE__*/ nodeProxy( Object3DNode, Object3DNode.DIRECTION );
+
+/**
+ * TSL function for creating an object 3D node that represents the object's world matrix.
+ *
+ * @tsl
+ * @function
+ * @param {?Object3D} [object3d=null] - The 3D object.
+ * @returns {Object3DNode<mat4>}
+ */
+export const objectWorldMatrix = /*@__PURE__*/ nodeProxy( Object3DNode, Object3DNode.WORLD_MATRIX );
+
+/**
+ * TSL function for creating an object 3D node that represents the object's position in world space.
+ *
+ * @tsl
+ * @function
+ * @param {?Object3D} [object3d=null] - The 3D object.
+ * @returns {Object3DNode<vec3>}
+ */
+export const objectPosition = /*@__PURE__*/ nodeProxy( Object3DNode, Object3DNode.POSITION );
+
+/**
+ * TSL function for creating an object 3D node that represents the object's scale in world space.
+ *
+ * @tsl
+ * @function
+ * @param {?Object3D} [object3d=null] - The 3D object.
+ * @returns {Object3DNode<vec3>}
+ */
+export const objectScale = /*@__PURE__*/ nodeProxy( Object3DNode, Object3DNode.SCALE );
+
+/**
+ * TSL function for creating an object 3D node that represents the object's position in view/camera space.
+ *
+ * @tsl
+ * @function
+ * @param {?Object3D} [object3d=null] - The 3D object.
+ * @returns {Object3DNode<vec3>}
+ */
+export const objectViewPosition = /*@__PURE__*/ nodeProxy( Object3DNode, Object3DNode.VIEW_POSITION );
+
+/**
+ * TSL function for creating an object 3D node that represents the object's radius.
+ *
+ * @tsl
+ * @function
+ * @param {?Object3D} [object3d=null] - The 3D object.
+ * @returns {Object3DNode<vec3>}
+ */
+export const objectRadius = /*@__PURE__*/ nodeProxy( Object3DNode, Object3DNode.RADIUS );

package/src/nodes/accessors/PointUVNode.js

@@ -1,12 +1,37 @@
-import Node, { addNodeClass } from '../core/Node.js';
-import { nodeImmutable } from '../shadernode/ShaderNode.js';
-
+import Node from '../core/Node.js';
+import { nodeImmutable } from '../tsl/TSLBase.js';
+
+/**
+ * A node for representing the uv coordinates of points.
+ *
+ * Can only be used with a WebGL backend. In WebGPU, point
+ * primitives always have the size of one pixel and can thus
+ * can't be used as sprite-like objects that display textures.
+ *
+ * @augments Node
+ */
 class PointUVNode extends Node {
 
+	static get type() {
+
+		return 'PointUVNode';
+
+	}
+
+	/**
+	 * Constructs a new point uv node.
+	 */
 	constructor() {
 
 		super( 'vec2' );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isPointUVNode = true;
 
 	}
@@ -21,6 +46,10 @@ class PointUVNode extends Node {
 
 export default PointUVNode;
 
-export const pointUV = nodeImmutable( PointUVNode );
-
-addNodeClass( 'PointUVNode', PointUVNode );
+/**
+ * TSL object that represents the uv coordinates of points.
+ *
+ * @tsl
+ * @type {PointUVNode}
+ */
+export const pointUV = /*@__PURE__*/ nodeImmutable( PointUVNode );

package/src/nodes/accessors/Position.js

@@ -0,0 +1,64 @@
+import { attribute } from '../core/AttributeNode.js';
+import { Fn } from '../tsl/TSLCore.js';
+import { modelWorldMatrix } from './ModelNode.js';
+
+/**
+ * TSL object that represents the position attribute of the current rendered object.
+ *
+ * @tsl
+ * @type {AttributeNode<vec3>}
+ */
+export const positionGeometry = /*@__PURE__*/ attribute( 'position', 'vec3' );
+
+/**
+ * TSL object that represents the vertex position in local space of the current rendered object.
+ *
+ * @tsl
+ * @type {AttributeNode<vec3>}
+ */
+export const positionLocal = /*@__PURE__*/ positionGeometry.toVarying( 'positionLocal' );
+
+/**
+ * TSL object that represents the previous vertex position in local space of the current rendered object.
+ * Used in context of {@link VelocityNode} for rendering motion vectors.
+ *
+ * @tsl
+ * @type {AttributeNode<vec3>}
+ */
+export const positionPrevious = /*@__PURE__*/ positionGeometry.toVarying( 'positionPrevious' );
+
+/**
+ * TSL object that represents the vertex position in world space of the current rendered object.
+ *
+ * @tsl
+ * @type {VaryingNode<vec3>}
+ */
+export const positionWorld = /*@__PURE__*/ modelWorldMatrix.mul( positionLocal ).xyz.toVarying( 'v_positionWorld' ).context( { needsPositionReassign: true } );
+
+/**
+ * TSL object that represents the position world direction of the current rendered object.
+ *
+ * @tsl
+ * @type {Node<vec3>}
+ */
+export const positionWorldDirection = /*@__PURE__*/ positionLocal.transformDirection( modelWorldMatrix ).toVarying( 'v_positionWorldDirection' ).normalize().toVar( 'positionWorldDirection' ).context( { needsPositionReassign: true } );
+
+/**
+ * TSL object that represents the vertex position in view space of the current rendered object.
+ *
+ * @tsl
+ * @type {VaryingNode<vec3>}
+ */
+export const positionView = /*@__PURE__*/ ( Fn( ( builder ) => {
+
+	return builder.context.setupPositionView();
+
+}, 'vec3' ).once() )().toVarying( 'v_positionView' ).context( { needsPositionReassign: true } );
+
+/**
+ * TSL object that represents the position view direction of the current rendered object.
+ *
+ * @tsl
+ * @type {VaryingNode<vec3>}
+ */
+export const positionViewDirection = /*@__PURE__*/ positionView.negate().toVarying( 'v_positionViewDirection' ).normalize().toVar( 'positionViewDirection' );