super-three 0.173.5 → 0.176.0

package/src/materials/nodes/VolumeNodeMaterial.js

@@ -1,20 +1,9 @@
 import NodeMaterial from './NodeMaterial.js';
-import { property } from '../../nodes/core/PropertyNode.js';
-import { materialReference } from '../../nodes/accessors/MaterialReferenceNode.js';
-import { modelWorldMatrixInverse } from '../../nodes/accessors/ModelNode.js';
-import { cameraPosition } from '../../nodes/accessors/Camera.js';
-import { positionGeometry } from '../../nodes/accessors/Position.js';
-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 **/
+import VolumetricLightingModel from '../../nodes/functions/VolumetricLightingModel.js';
+import { BackSide } from '../../constants.js';
 
 /**
- * Node material intended for volume rendering. The volumetric data are
- * defined with an instance of {@link Data3DTexture}.
+ * Volume node material.
  *
  * @augments NodeMaterial
  */
@@ -29,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 ) {
 
@@ -38,144 +27,52 @@ class VolumeNodeMaterial extends NodeMaterial {
 		/**
 		 * This flag can be used for type testing.
 		 *
-		 * @type {Boolean}
+		 * @type {boolean}
 		 * @readonly
 		 * @default true
 		 */
 		this.isVolumeNodeMaterial = true;
 
 		/**
-		 * The base color of the volume.
+		 * Number of steps used for raymarching.
 		 *
-		 * @type {Color}
-		 * @default 100
+		 * @type {number}
+		 * @default 25
 		 */
-		this.base = new Color( 0xffffff );
+		this.steps = 25;
 
 		/**
-		 * A 3D data texture holding the volumetric data.
+		 * Offsets the distance a ray has been traveled through a volume.
+		 * Can be used to implement dithering to reduce banding.
 		 *
-		 * @type {Data3DTexture?}
+		 * @type {Node<float>}
 		 * @default null
 		 */
-		this.map = null;
+		this.offsetNode = null;
 
 		/**
-		 * This number of samples for each ray that hits the mesh's surface
-		 * and travels through the volume.
+		 * Node used for scattering calculations.
 		 *
-		 * @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
-		 * multiple times.
-		 *
-		 * This node can be used to assign a callback function of type `Fn`
-		 * that will be executed 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?}
+		 * @type {Function|FunctionNode<vec4>}
 		 * @default null
 		 */
-		this.testNode = null;
-
-		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 );
-
-		const hitBox = Fn( ( { orig, dir } ) => {
-
-			const box_min = vec3( - 0.5 );
-			const box_max = vec3( 0.5 );
-
-			const inv_dir = dir.reciprocal();
+		this.scatteringNode = null;
 
-			const tmin_tmp = box_min.sub( orig ).mul( inv_dir );
-			const tmax_tmp = box_max.sub( orig ).mul( inv_dir );
+		this.lights = true;
 
-			const tmin = min( tmin_tmp, tmax_tmp );
-			const tmax = max( tmin_tmp, tmax_tmp );
+		this.transparent = true;
+		this.side = BackSide;
 
-			const t0 = max( tmin.x, max( tmin.y, tmin.z ) );
-			const t1 = min( tmax.x, min( tmax.y, tmax.z ) );
+		this.depthTest = false;
+		this.depthWrite = false;
 
-			return vec2( t0, t1 );
-
-		} );
-
-		this.fragmentNode = Fn( () => {
-
-			const vOrigin = varying( vec3( modelWorldMatrixInverse.mul( vec4( cameraPosition, 1.0 ) ) ) );
-			const vDirection = varying( positionGeometry.sub( vOrigin ) );
-
-			const rayDir = vDirection.normalize();
-			const bounds = vec2( hitBox( { orig: vOrigin, dir: rayDir } ) ).toVar();
-
-			bounds.x.greaterThan( bounds.y ).discard();
-
-			bounds.assign( vec2( max( bounds.x, 0.0 ), bounds.y ) );
-
-			const p = vec3( vOrigin.add( bounds.x.mul( rayDir ) ) ).toVar();
-			const inc = vec3( rayDir.abs().reciprocal() ).toVar();
-			const delta = float( min( inc.x, min( inc.y, inc.z ) ) ).toVar( 'delta' ); // used 'delta' name in loop
-
-			delta.divAssign( materialReference( 'steps', 'float' ) );
-
-			const ac = vec4( materialReference( 'base', 'color' ), 0.0 ).toVar();
-
-			Loop( { type: 'float', start: bounds.x, end: bounds.y, update: '+= delta' }, () => {
-
-				const d = property( 'float', 'd' ).assign( map.sample( p.add( 0.5 ) ).r );
-
-				if ( this.testNode !== null ) {
-
-					this.testNode( { map: map, mapValue: d, probe: p, finalColor: ac } ).append();
-
-				} else {
-
-					// default to show surface of mesh
-					ac.a.assign( 1 );
-					Break();
-
-				}
-
-				p.addAssign( rayDir.mul( delta ) );
-
-			} );
-
-			ac.a.equal( 0 ).discard();
+		this.setValues( parameters );
 
-			return vec4( ac );
+	}
 
-		} )();
+	setupLightingModel() {
 
-		super.setup( builder );
+		return new VolumetricLightingModel();
 
 	}
 

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

@@ -76,28 +76,28 @@ class NodeMaterialObserver {
 		/**
 		 * Whether the material uses node objects or not.
 		 *
-		 * @type {Boolean}
+		 * @type {boolean}
 		 */
 		this.hasNode = this.containsNode( builder );
 
 		/**
 		 * Whether the node builder's 3D object is animated or not.
 		 *
-		 * @type {Boolean}
+		 * @type {boolean}
 		 */
 		this.hasAnimation = builder.object.isSkinnedMesh === true;
 
 		/**
 		 * A list of all possible material uniforms
 		 *
-		 * @type {Array<String>}
+		 * @type {Array<string>}
 		 */
 		this.refreshUniforms = refreshUniforms;
 
 		/**
 		 * Holds the current render ID from the node frame.
 		 *
-		 * @type {Number}
+		 * @type {number}
 		 * @default 0
 		 */
 		this.renderId = 0;
@@ -108,7 +108,7 @@ class NodeMaterialObserver {
 	 * 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.
+	 * @return {boolean} Whether the given render object is verified for the first time of this observer.
 	 */
 	firstInitialization( renderObject ) {
 
@@ -216,7 +216,7 @@ class NodeMaterialObserver {
 	 * node properties.
 	 *
 	 * @param {NodeBuilder} builder - The current node builder.
-	 * @return {Boolean} Whether the node builder's material uses node properties or not.
+	 * @return {boolean} Whether the node builder's material uses node properties or not.
 	 */
 	containsNode( builder ) {
 
@@ -281,7 +281,7 @@ 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.
+	 * @return {boolean} Whether the given render object has changed its state or not.
 	 */
 	equals( renderObject ) {
 
@@ -475,7 +475,7 @@ class NodeMaterialObserver {
 	 *
 	 * @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.
+	 * @return {boolean} Whether the given render object requires a refresh or not.
 	 */
 	needsRefresh( renderObject, nodeFrame ) {
 

package/src/math/Box2.js

@@ -2,17 +2,52 @@ import { Vector2 } from './Vector2.js';
 
 const _vector = /*@__PURE__*/ new Vector2();
 
+/**
+ * Represents an axis-aligned bounding box (AABB) in 2D space.
+ */
 class Box2 {
 
+	/**
+	 * Constructs a new bounding box.
+	 *
+	 * @param {Vector2} [min=(Infinity,Infinity)] - A vector representing the lower boundary of the box.
+	 * @param {Vector2} [max=(-Infinity,-Infinity)] - A vector representing the upper boundary of the box.
+	 */
 	constructor( min = new Vector2( + Infinity, + Infinity ), max = new Vector2( - Infinity, - Infinity ) ) {
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isBox2 = true;
 
+		/**
+		 * The lower boundary of the box.
+		 *
+		 * @type {Vector2}
+		 */
 		this.min = min;
+
+		/**
+		 * The upper boundary of the box.
+		 *
+		 * @type {Vector2}
+		 */
 		this.max = max;
 
 	}
 
+	/**
+	 * Sets the lower and upper boundaries of this box.
+	 * Please note that this method only copies the values from the given objects.
+	 *
+	 * @param {Vector2} min - The lower boundary of the box.
+	 * @param {Vector2} max - The upper boundary of the box.
+	 * @return {Box2} A reference to this bounding box.
+	 */
 	set( min, max ) {
 
 		this.min.copy( min );
@@ -22,6 +57,13 @@ class Box2 {
 
 	}
 
+	/**
+	 * Sets the upper and lower bounds of this box so it encloses the position data
+	 * in the given array.
+	 *
+	 * @param {Array<Vector2>} points - An array holding 2D position data as instances of {@link Vector2}.
+	 * @return {Box2} A reference to this bounding box.
+	 */
 	setFromPoints( points ) {
 
 		this.makeEmpty();
@@ -36,6 +78,14 @@ class Box2 {
 
 	}
 
+	/**
+	 * Centers this box on the given center vector and sets this box's width, height and
+	 * depth to the given size values.
+	 *
+	 * @param {Vector2} center - The center of the box.
+	 * @param {Vector2} size - The x and y dimensions of the box.
+	 * @return {Box2} A reference to this bounding box.
+	 */
 	setFromCenterAndSize( center, size ) {
 
 		const halfSize = _vector.copy( size ).multiplyScalar( 0.5 );
@@ -46,12 +96,23 @@ class Box2 {
 
 	}
 
+	/**
+	 * Returns a new box with copied values from this instance.
+	 *
+	 * @return {Box2} A clone of this instance.
+	 */
 	clone() {
 
 		return new this.constructor().copy( this );
 
 	}
 
+	/**
+	 * Copies the values of the given box to this instance.
+	 *
+	 * @param {Box2} box - The box to copy.
+	 * @return {Box2} A reference to this bounding box.
+	 */
 	copy( box ) {
 
 		this.min.copy( box.min );
@@ -61,6 +122,11 @@ class Box2 {
 
 	}
 
+	/**
+	 * Makes this box empty which means in encloses a zero space in 2D.
+	 *
+	 * @return {Box2} A reference to this bounding box.
+	 */
 	makeEmpty() {
 
 		this.min.x = this.min.y = + Infinity;
@@ -70,6 +136,13 @@ class Box2 {
 
 	}
 
+	/**
+	 * Returns true if this box includes zero points within its bounds.
+	 * Note that a box with equal lower and upper bounds still includes one
+	 * point, the one both bounds share.
+	 *
+	 * @return {boolean} Whether this box is empty or not.
+	 */
 	isEmpty() {
 
 		// this is a more robust check for empty than ( volume <= 0 ) because volume can get positive with two negative axes
@@ -78,18 +151,36 @@ class Box2 {
 
 	}
 
+	/**
+	 * Returns the center point of this box.
+	 *
+	 * @param {Vector2} target - The target vector that is used to store the method's result.
+	 * @return {Vector2} The center point.
+	 */
 	getCenter( target ) {
 
 		return this.isEmpty() ? target.set( 0, 0 ) : target.addVectors( this.min, this.max ).multiplyScalar( 0.5 );
 
 	}
 
+	/**
+	 * Returns the dimensions of this box.
+	 *
+	 * @param {Vector2} target - The target vector that is used to store the method's result.
+	 * @return {Vector2} The size.
+	 */
 	getSize( target ) {
 
 		return this.isEmpty() ? target.set( 0, 0 ) : target.subVectors( this.max, this.min );
 
 	}
 
+	/**
+	 * Expands the boundaries of this box to include the given point.
+	 *
+	 * @param {Vector2} point - The point that should be included by the bounding box.
+	 * @return {Box2} A reference to this bounding box.
+	 */
 	expandByPoint( point ) {
 
 		this.min.min( point );
@@ -99,6 +190,15 @@ class Box2 {
 
 	}
 
+	/**
+	 * Expands this box equilaterally by the given vector. The width of this
+	 * box will be expanded by the x component of the vector in both
+	 * directions. The height of this box will be expanded by the y component of
+	 * the vector in both directions.
+	 *
+	 * @param {Vector2} vector - The vector that should expand the bounding box.
+	 * @return {Box2} A reference to this bounding box.
+	 */
 	expandByVector( vector ) {
 
 		this.min.sub( vector );
@@ -108,6 +208,13 @@ class Box2 {
 
 	}
 
+	/**
+	 * Expands each dimension of the box by the given scalar. If negative, the
+	 * dimensions of the box will be contracted.
+	 *
+	 * @param {number} scalar - The scalar value that should expand the bounding box.
+	 * @return {Box2} A reference to this bounding box.
+	 */
 	expandByScalar( scalar ) {
 
 		this.min.addScalar( - scalar );
@@ -117,6 +224,12 @@ class Box2 {
 
 	}
 
+	/**
+	 * Returns `true` if the given point lies within or on the boundaries of this box.
+	 *
+	 * @param {Vector2} point - The point to test.
+	 * @return {boolean} Whether the bounding box contains the given point or not.
+	 */
 	containsPoint( point ) {
 
 		return point.x >= this.min.x && point.x <= this.max.x &&
@@ -124,6 +237,13 @@ class Box2 {
 
 	}
 
+	/**
+	 * Returns `true` if this bounding box includes the entirety of the given bounding box.
+	 * If this box and the given one are identical, this function also returns `true`.
+	 *
+	 * @param {Box2} box - The bounding box to test.
+	 * @return {boolean} Whether the bounding box contains the given bounding box or not.
+	 */
 	containsBox( box ) {
 
 		return this.min.x <= box.min.x && box.max.x <= this.max.x &&
@@ -131,6 +251,13 @@ class Box2 {
 
 	}
 
+	/**
+	 * Returns a point as a proportion of this box's width and height.
+	 *
+	 * @param {Vector2} point - A point in 2D space.
+	 * @param {Vector2} target - The target vector that is used to store the method's result.
+	 * @return {Vector2} A point as a proportion of this box's width and height.
+	 */
 	getParameter( point, target ) {
 
 		// This can potentially have a divide by zero if the box
@@ -143,6 +270,12 @@ class Box2 {
 
 	}
 
+	/**
+	 * Returns `true` if the given bounding box intersects with this bounding box.
+	 *
+	 * @param {Box2} box - The bounding box to test.
+	 * @return {boolean} Whether the given bounding box intersects with this bounding box.
+	 */
 	intersectsBox( box ) {
 
 		// using 4 splitting planes to rule out intersections
@@ -152,18 +285,41 @@ class Box2 {
 
 	}
 
+	/**
+	 * Clamps the given point within the bounds of this box.
+	 *
+	 * @param {Vector2} point - The point to clamp.
+	 * @param {Vector2} target - The target vector that is used to store the method's result.
+	 * @return {Vector2} The clamped point.
+	 */
 	clampPoint( point, target ) {
 
 		return target.copy( point ).clamp( this.min, this.max );
 
 	}
 
+	/**
+	 * Returns the euclidean distance from any edge of this box to the specified point. If
+	 * the given point lies inside of this box, the distance will be `0`.
+	 *
+	 * @param {Vector2} point - The point to compute the distance to.
+	 * @return {number} The euclidean distance.
+	 */
 	distanceToPoint( point ) {
 
 		return this.clampPoint( point, _vector ).distanceTo( point );
 
 	}
 
+	/**
+	 * Computes the intersection of this bounding box and the given one, setting the upper
+	 * bound of this box to the lesser of the two boxes' upper bounds and the
+	 * lower bound of this box to the greater of the two boxes' lower bounds. If
+	 * there's no overlap, makes this box empty.
+	 *
+	 * @param {Box2} box - The bounding box to intersect with.
+	 * @return {Box2} A reference to this bounding box.
+	 */
 	intersect( box ) {
 
 		this.min.max( box.min );
@@ -175,6 +331,14 @@ class Box2 {
 
 	}
 
+	/**
+	 * Computes the union of this box and another and the given one, setting the upper
+	 * bound of this box to the greater of the two boxes' upper bounds and the
+	 * lower bound of this box to the lesser of the two boxes' lower bounds.
+	 *
+	 * @param {Box2} box - The bounding box that will be unioned with this instance.
+	 * @return {Box2} A reference to this bounding box.
+	 */
 	union( box ) {
 
 		this.min.min( box.min );
@@ -184,6 +348,13 @@ class Box2 {
 
 	}
 
+	/**
+	 * Adds the given offset to both the upper and lower bounds of this bounding box,
+	 * effectively moving it in 2D space.
+	 *
+	 * @param {Vector2} offset - The offset that should be used to translate the bounding box.
+	 * @return {Box2} A reference to this bounding box.
+	 */
 	translate( offset ) {
 
 		this.min.add( offset );
@@ -193,6 +364,12 @@ class Box2 {
 
 	}
 
+	/**
+	 * Returns `true` if this bounding box is equal with the given one.
+	 *
+	 * @param {Box2} box - The box to test for equality.
+	 * @return {boolean} Whether this bounding box is equal with the given one.
+	 */
 	equals( box ) {
 
 		return box.min.equals( this.min ) && box.max.equals( this.max );