super-three 0.170.1 → 0.172.0

package/src/materials/nodes/PointsNodeMaterial.js

@@ -4,6 +4,16 @@ import { PointsMaterial } from '../PointsMaterial.js';
 
 const _defaultValues = /*@__PURE__*/ new PointsMaterial();
 
+/**
+ * Node material version of `PointsMaterial`.
+ *
+ * Since WebGPU can render point primitives only with a size of one pixel,
+ * this material type does not evaluate the `size` and `sizeAttenuation`
+ * property of `PointsMaterial`. Use {@link InstancedPointsNodeMaterial}
+ * instead if you need points with a size larger than one pixel.
+ *
+ * @augments NodeMaterial
+ */
 class PointsNodeMaterial extends NodeMaterial {
 
 	static get type() {
@@ -12,31 +22,30 @@ class PointsNodeMaterial extends NodeMaterial {
 
 	}
 
+	/**
+	 * Constructs a new points 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.isPointsNodeMaterial = true;
 
-		this.lights = false;
-		this.transparent = true;
-
-		this.sizeNode = null;
-
 		this.setDefaultValues( _defaultValues );
 
 		this.setValues( parameters );
 
 	}
 
-	copy( source ) {
-
-		this.sizeNode = source.sizeNode;
-
-		return super.copy( source );
-
-	}
-
 }
 
 export default PointsNodeMaterial;

package/src/materials/nodes/ShadowNodeMaterial.js

@@ -5,6 +5,11 @@ import { ShadowMaterial } from '../ShadowMaterial.js';
 
 const _defaultValues = /*@__PURE__*/ new ShadowMaterial();
 
+/**
+ * Node material version of `ShadowMaterial`.
+ *
+ * @augments NodeMaterial
+ */
 class ShadowNodeMaterial extends NodeMaterial {
 
 	static get type() {
@@ -13,12 +18,31 @@ class ShadowNodeMaterial extends NodeMaterial {
 
 	}
 
+	/**
+	 * Constructs a new shadow 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.isShadowNodeMaterial = true;
 
+		/**
+		 * Set to `true` because so it's possible to implement
+		 * the shadow mask effect.
+		 *
+		 * @type {Boolean}
+		 * @default true
+		 */
 		this.lights = true;
 
 		this.setDefaultValues( _defaultValues );
@@ -27,6 +51,11 @@ class ShadowNodeMaterial extends NodeMaterial {
 
 	}
 
+	/**
+	 * Setups the lighting model.
+	 *
+	 * @return {ShadowMaskModel} The lighting model.
+	 */
 	setupLightingModel( /*builder*/ ) {
 
 		return new ShadowMaskModel();

package/src/materials/nodes/SpriteNodeMaterial.js

@@ -2,7 +2,7 @@ import NodeMaterial from './NodeMaterial.js';
 import { cameraProjectionMatrix } from '../../nodes/accessors/Camera.js';
 import { materialRotation } from '../../nodes/accessors/MaterialNode.js';
 import { modelViewMatrix, modelWorldMatrix } from '../../nodes/accessors/ModelNode.js';
-import { positionLocal } from '../../nodes/accessors/Position.js';
+import { positionGeometry } from '../../nodes/accessors/Position.js';
 import { rotate } from '../../nodes/utils/RotateNode.js';
 import { float, vec2, vec3, vec4 } from '../../nodes/tsl/TSLBase.js';
 
@@ -11,6 +11,11 @@ import { reference } from '../../nodes/accessors/ReferenceBaseNode.js';
 
 const _defaultValues = /*@__PURE__*/ new SpriteMaterial();
 
+/**
+ * Node material version of `SpriteMaterial`.
+ *
+ * @augments NodeMaterial
+ */
 class SpriteNodeMaterial extends NodeMaterial {
 
 	static get type() {
@@ -19,17 +24,66 @@ class SpriteNodeMaterial extends NodeMaterial {
 
 	}
 
+	/**
+	 * Constructs a new sprite 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.isSpriteNodeMaterial = true;
 
-		this.lights = false;
 		this._useSizeAttenuation = true;
 
+		/**
+		 * This property makes it possible to define the position of the sprite with a
+		 * node. That can be useful when the material is used with instanced rendering
+		 * and node data are defined with an instanced attribute node:
+		 * ```js
+		 * const positionAttribute = new InstancedBufferAttribute( new Float32Array( positions ), 3 );
+		 * material.positionNode = instancedBufferAttribute( positionAttribute );
+		 * ```
+		 * Another possibility is to compute the instanced data with a compute shader:
+		 * ```js
+		 * const positionBuffer = instancedArray( particleCount, 'vec3' );
+		 * particleMaterial.positionNode = positionBuffer.toAttribute();
+		 * ```
+		 *
+		 * @type {Node<vec2>?}
+		 * @default null
+		 */
 		this.positionNode = null;
+
+		/**
+		 * The rotation of sprite materials is by default inferred from the `rotation`,
+		 * property. This node property allows to overwrite the default and define
+		 * the rotation with a node instead.
+		 *
+		 * If you don't want to overwrite the rotation but modify the existing
+		 * value instead, use {@link module:MaterialNode.materialRotation}.
+		 *
+		 * @type {Node<float>?}
+		 * @default null
+		 */
 		this.rotationNode = null;
+
+		/**
+		 * This node property provides an additional way to scale sprites next to
+		 * `Object3D.scale`. The scale transformation based in `Object3D.scale`
+		 * is multiplied with the scale value of this node in the vertex shader.
+		 *
+		 * @type {Node<vec2>?}
+		 * @default null
+		 */
 		this.scaleNode = null;
 
 		this.setDefaultValues( _defaultValues );
@@ -38,17 +92,22 @@ class SpriteNodeMaterial extends NodeMaterial {
 
 	}
 
-	setupPosition( { object, camera, context } ) {
+	/**
+	 * Setups the position node in view space. This method implements
+	 * the sprite specific vertex shader.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {Node<vec3>} The position in view space.
+	 */
+	setupPositionView( builder ) {
 
-		const sizeAttenuation = this.sizeAttenuation;
+		const { object, camera } = builder;
 
-		// < VERTEX STAGE >
+		const sizeAttenuation = this.sizeAttenuation;
 
 		const { positionNode, rotationNode, scaleNode } = this;
 
-		const vertex = positionLocal;
-
-		let mvPosition = modelViewMatrix.mul( vec3( positionNode || 0 ) );
+		const mvPosition = modelViewMatrix.mul( vec3( positionNode || 0 ) );
 
 		let scale = vec2( modelWorldMatrix[ 0 ].xyz.length(), modelWorldMatrix[ 1 ].xyz.length() );
 
@@ -58,8 +117,7 @@ class SpriteNodeMaterial extends NodeMaterial {
 
 		}
 
-
-		if ( ! sizeAttenuation ) {
+		if ( sizeAttenuation === false ) {
 
 			if ( camera.isPerspectiveCamera ) {
 
@@ -74,11 +132,11 @@ class SpriteNodeMaterial extends NodeMaterial {
 
 		}
 
-		let alignedPosition = vertex.xy;
+		let alignedPosition = positionGeometry.xy;
 
 		if ( object.center && object.center.isVector2 === true ) {
 
-			const center = reference( 'center', 'vec2' );
+			const center = reference( 'center', 'vec2', object );
 
 			alignedPosition = alignedPosition.sub( center.sub( 0.5 ) );
 
@@ -90,13 +148,7 @@ class SpriteNodeMaterial extends NodeMaterial {
 
 		const rotatedPosition = rotate( alignedPosition, rotation );
 
-		mvPosition = vec4( mvPosition.xy.add( rotatedPosition ), mvPosition.zw );
-
-		const modelViewProjection = cameraProjectionMatrix.mul( mvPosition );
-
-		context.vertex = vertex;
-
-		return modelViewProjection;
+		return vec4( mvPosition.xy.add( rotatedPosition ), mvPosition.zw );
 
 	}
 
@@ -110,6 +162,12 @@ class SpriteNodeMaterial extends NodeMaterial {
 
 	}
 
+	/**
+	 * Whether to use size attenuation or not.
+	 *
+	 * @type {Boolean}
+	 * @default true
+	 */
 	get sizeAttenuation() {
 
 		return this._useSizeAttenuation;

package/src/materials/nodes/VolumeNodeMaterial.js

@@ -8,7 +8,16 @@ import { Fn, varying, float, vec2, vec3, vec4 } from '../../nodes/tsl/TSLBase.js
 import { min, max } from '../../nodes/math/MathNode.js';
 import { Loop, Break } from '../../nodes/utils/LoopNode.js';
 import { texture3D } from '../../nodes/accessors/Texture3DNode.js';
+import { Color } from '../../math/Color.js';
 
+/** @module VolumeNodeMaterial **/
+
+/**
+ * Node material intended for volume rendering. The volumetic data are
+ * defined with an instance of {@link Data3DTexture}.
+ *
+ * @augments NodeMaterial
+ */
 class VolumeNodeMaterial extends NodeMaterial {
 
 	static get type() {
@@ -17,18 +26,85 @@ class VolumeNodeMaterial extends NodeMaterial {
 
 	}
 
-	constructor( params = {} ) {
+	/**
+	 * Constructs a new volume 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.isVolumeNodeMaterial = true;
+
+		/**
+		 * The base color of the volume.
+		 *
+		 * @type {Color}
+		 * @default 100
+		 */
+		this.base = new Color( 0xffffff );
+
+		/**
+		 * A 3D data texture holding the volumetric data.
+		 *
+		 * @type {Data3DTexture?}
+		 * @default null
+		 */
+		this.map = null;
+
+		/**
+		 * This number of samples for each ray that hits the mesh's surface
+		 * and travels through the volume.
+		 *
+		 * @type {Number}
+		 * @default 100
+		 */
+		this.steps = 100;
+
+		/**
+		 * Callback for {@link VolumeNodeMaterial#testNode}.
+		 *
+		 * @callback testNodeCallback
+		 * @param {Data3DTexture<float>} map - The 3D texture.
+		 * @param {Node<float>} mapValue - The sampled value inside the volume.
+		 * @param {Node<vec3>} probe - The probe which is the entry point of the ray on the mesh's surface.
+		 * @param {Node<vec4>} finalColor - The final color.
+		 */
+
+		/**
+		 * The volume rendering of this material works by shooting rays
+		 * from the camera position through each fragment of the mesh's
+		 * surface and sample the inner volume in a raymarching fashion
+		 * mutiple times.
+		 *
+		 * This node can be used to assign a callback function of type `Fn`
+		 * that will be exexuted per sample. The callback receives the
+		 * texture, the sampled texture value as well as position on the surface
+		 * where the rays enters the volume. The last parameter is a color
+		 * that allows the callback to determine the final color.
+		 *
+		 * @type {testNodeCallback?}
+		 * @default null
+		 */
 		this.testNode = null;
 
-		this.setValues( params );
+		this.setValues( parameters );
 
 	}
 
+	/**
+	 * Setups the vertex and fragment stage of this node material.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 */
 	setup( builder ) {
 
 		const map = texture3D( this.map, null, 0 );
@@ -75,7 +151,7 @@ class VolumeNodeMaterial extends NodeMaterial {
 
 			Loop( { type: 'float', start: bounds.x, end: bounds.y, update: '+= delta' }, () => {
 
-				const d = property( 'float', 'd' ).assign( map.uv( p.add( 0.5 ) ).r );
+				const d = property( 'float', 'd' ).assign( map.sample( p.add( 0.5 ) ).r );
 
 				if ( this.testNode !== null ) {
 

package/src/materials/nodes/manager/NodeMaterialObserver.js

@@ -51,18 +51,65 @@ const refreshUniforms = [
 	'transmissionMap'
 ];
 
+/**
+ * This class is used by {@link WebGPURenderer} as management component.
+ * It's primary purpose is to determine whether render objects require a
+ * refresh right before they are going to be rendered or not.
+ */
 class NodeMaterialObserver {
 
+	/**
+	 * Constructs a new node material observer.
+	 *
+	 * @param {NodeBuilder} builder - The node builder.
+	 */
 	constructor( builder ) {
 
+		/**
+		 * A node material can be used by more than one render object so the
+		 * monitor must maintain a list of render objects.
+		 *
+		 * @type {WeakMap<RenderObject,Object>}
+		 */
 		this.renderObjects = new WeakMap();
+
+		/**
+		 * Whether the material uses node objects or not.
+		 *
+		 * @type {Boolean}
+		 */
 		this.hasNode = this.containsNode( builder );
+
+		/**
+		 * Whether the node builder's 3D object is animated or not.
+		 *
+		 * @type {Boolean}
+		 */
 		this.hasAnimation = builder.object.isSkinnedMesh === true;
+
+		/**
+		 * A list of all possible material uniforms
+		 *
+		 * @type {Array<String>}
+		 */
 		this.refreshUniforms = refreshUniforms;
+
+		/**
+		 * Holds the current render ID from the node frame.
+		 *
+		 * @type {Number}
+		 * @default 0
+		 */
 		this.renderId = 0;
 
 	}
 
+	/**
+	 * Returns `true` if the given render object is verified for the first time of this observer.
+	 *
+	 * @param {RenderObject} renderObject - The render object.
+	 * @return {Boolean} Whether the given render object is verified for the first time of this observer.
+	 */
 	firstInitialization( renderObject ) {
 
 		const hasInitialized = this.renderObjects.has( renderObject );
@@ -79,6 +126,12 @@ class NodeMaterialObserver {
 
 	}
 
+	/**
+	 * Returns monitoring data for the given render object.
+	 *
+	 * @param {RenderObject} renderObject - The render object.
+	 * @return {Object} The monitoring data.
+	 */
 	getRenderObjectData( renderObject ) {
 
 		let data = this.renderObjects.get( renderObject );
@@ -132,6 +185,13 @@ class NodeMaterialObserver {
 
 	}
 
+	/**
+	 * Returns an attribute data structure holding the attributes versions for
+	 * monitoring.
+	 *
+	 * @param {Object} attributes - The geometry attributes.
+	 * @return {Object} An object for monitoring the versions of attributes.
+	 */
 	getAttributesData( attributes ) {
 
 		const attributesData = {};
@@ -150,6 +210,13 @@ class NodeMaterialObserver {
 
 	}
 
+	/**
+	 * Returns `true` if the node builder's material uses
+	 * node properties.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {Boolean} Whether the node builder's material uses node properties or not.
+	 */
 	containsNode( builder ) {
 
 		const material = builder.material;
@@ -168,6 +235,13 @@ class NodeMaterialObserver {
 
 	}
 
+	/**
+	 * Returns a material data structure holding the material property values for
+	 * monitoring.
+	 *
+	 * @param {Material} material - The material.
+	 * @return {Object} An object for monitoring material properties.
+	 */
 	getMaterialData( material ) {
 
 		const data = {};
@@ -202,6 +276,12 @@ class NodeMaterialObserver {
 
 	}
 
+	/**
+	 * Returns `true` if the given render object has not changed its state.
+	 *
+	 * @param {RenderObject} renderObject - The render object.
+	 * @return {Boolean} Whether the given render object has changed its state or not.
+	 */
 	equals( renderObject ) {
 
 		const { object, material, geometry } = renderObject;
@@ -382,6 +462,13 @@ class NodeMaterialObserver {
 
 	}
 
+	/**
+	 * Checks if the given render object requires a refresh.
+	 *
+	 * @param {RenderObject} renderObject - The render object.
+	 * @param {NodeFrame} nodeFrame - The current node frame.
+	 * @return {Boolean} Whether the given render object requires a refresh or not.
+	 */
 	needsRefresh( renderObject, nodeFrame ) {
 
 		if ( this.hasNode || this.hasAnimation || this.firstInitialization( renderObject ) )

package/src/nodes/Nodes.js

@@ -67,7 +67,6 @@ export { default as MaterialReferenceNode } from './accessors/MaterialReferenceN
 export { default as RendererReferenceNode } from './accessors/RendererReferenceNode.js';
 export { default as MorphNode } from './accessors/MorphNode.js';
 export { default as ModelNode } from './accessors/ModelNode.js';
-export { default as ModelViewProjectionNode } from './accessors/ModelViewProjectionNode.js';
 export { default as Object3DNode } from './accessors/Object3DNode.js';
 export { default as PointUVNode } from './accessors/PointUVNode.js';
 export { default as ReferenceNode } from './accessors/ReferenceNode.js';
@@ -104,11 +103,6 @@ export { default as FunctionNode } from './code/FunctionNode.js';
 export { default as ScriptableNode } from './code/ScriptableNode.js';
 export { default as ScriptableValueNode } from './code/ScriptableValueNode.js';
 
-// fog
-export { default as FogNode } from './fog/FogNode.js';
-export { default as FogRangeNode } from './fog/FogRangeNode.js';
-export { default as FogExp2Node } from './fog/FogExp2Node.js';
-
 // geometry
 export { default as RangeNode } from './geometry/RangeNode.js';
 
@@ -132,6 +126,7 @@ export { default as BasicEnvironmentNode } from './lighting/BasicEnvironmentNode
 export { default as IrradianceNode } from './lighting/IrradianceNode.js';
 export { default as AONode } from './lighting/AONode.js';
 export { default as AnalyticLightNode } from './lighting/AnalyticLightNode.js';
+export { default as ShadowBaseNode } from './lighting/ShadowBaseNode.js';
 export { default as ShadowNode } from './lighting/ShadowNode.js';
 
 // pmrem

package/src/nodes/TSL.js

@@ -115,9 +115,7 @@ export * from './code/ScriptableNode.js';
 export * from './code/ScriptableValueNode.js';
 
 // fog
-export * from './fog/FogNode.js';
-export * from './fog/FogRangeNode.js';
-export * from './fog/FogExp2Node.js';
+export * from './fog/Fog.js';
 
 // geometry
 export * from './geometry/RangeNode.js';
@@ -133,6 +131,7 @@ export * from './gpgpu/AtomicFunctionNode.js';
 export * from './accessors/Lights.js';
 export * from './lighting/LightsNode.js';
 export * from './lighting/LightingContextNode.js';
+export * from './lighting/ShadowBaseNode.js';
 export * from './lighting/ShadowNode.js';
 export * from './lighting/PointLightNode.js';
 

package/src/nodes/accessors/AccessorsUtils.js

@@ -6,11 +6,38 @@ import { mix } from '../math/MathNode.js';
 import { anisotropy, anisotropyB, roughness } from '../core/PropertyNode.js';
 import { positionViewDirection } from './Position.js';
 
+/** @module AccessorsUtils **/
+
+/**
+ * TSL object that represents the TBN matrix in view space.
+ *
+ * @type {Node<mat3>}
+ */
 export const TBNViewMatrix = /*@__PURE__*/ mat3( tangentView, bitangentView, normalView );
 
+/**
+ * TSL object that represents the parallax direction.
+ *
+ * @type {Node<mat3>}
+ */
 export const parallaxDirection = /*@__PURE__*/ positionViewDirection.mul( TBNViewMatrix )/*.normalize()*/;
+
+/**
+ * TSL function for computing parallax uv coordinates.
+ *
+ * @function
+ * @param {Node<vec2>} uv - A uv node.
+ * @param {Node<vec2>} scale - A scale node.
+ * @returns {Node<vec2>} Parallax uv coordinates.
+ */
 export const parallaxUV = ( uv, scale ) => uv.sub( parallaxDirection.mul( scale ) );
 
+/**
+ * TSL function for computing bent normals.
+ *
+ * @function
+ * @returns {Node<vec3>} Bent normals.
+ */
 export const transformedBentNormalView = /*@__PURE__*/ ( () => {
 
 	// https://google.github.io/filament/Filament.md.html#lighting/imagebasedlights/anisotropy

package/src/nodes/accessors/Arrays.js

@@ -1,25 +1,44 @@
 import StorageInstancedBufferAttribute from '../../renderers/common/StorageInstancedBufferAttribute.js';
 import StorageBufferAttribute from '../../renderers/common/StorageBufferAttribute.js';
 import { storage } from './StorageBufferNode.js';
-import { getLengthFromType } from '../core/NodeUtils.js';
-
+import { getLengthFromType, getTypedArrayFromType } from '../core/NodeUtils.js';
+
+/** @module Arrays **/
+
+/**
+ * TSL function for creating a storage buffer node with a configured `StorageBufferAttribute`.
+ *
+ * @function
+ * @param {Number} count - The data count.
+ * @param {String} [type='float'] - The data type.
+ * @returns {StorageBufferNode}
+ */
 export const attributeArray = ( count, type = 'float' ) => {
 
 	const itemSize = getLengthFromType( type );
+	const typedArray = getTypedArrayFromType( type );
 
-	const buffer = new StorageBufferAttribute( count, itemSize );
+	const buffer = new StorageBufferAttribute( count, itemSize, typedArray );
 	const node = storage( buffer, type, count );
 
 	return node;
 
 };
 
-
+/**
+ * TSL function for creating a storage buffer node with a configured `StorageInstancedBufferAttribute`.
+ *
+ * @function
+ * @param {Number} count - The data count.
+ * @param {String} [type='float'] - The data type.
+ * @returns {StorageBufferNode}
+ */
 export const instancedArray = ( count, type = 'float' ) => {
 
 	const itemSize = getLengthFromType( type );
+	const typedArray = getTypedArrayFromType( type );
 
-	const buffer = new StorageInstancedBufferAttribute( count, itemSize );
+	const buffer = new StorageInstancedBufferAttribute( count, itemSize, typedArray );
 	const node = storage( buffer, type, count );
 
 	return node;