super-three 0.171.0 → 0.173.0

package/src/renderers/common/XRRenderTarget.js

@@ -0,0 +1,74 @@
+import { RenderTarget } from '../../core/RenderTarget.js';
+
+/**
+ * A special type of render target that is used when rendering
+ * with the WebXR Device API.
+ *
+ * @private
+ * @augments RenderTarget
+ */
+class XRRenderTarget extends RenderTarget {
+
+	/**
+	 * Constructs a new XR render target.
+	 *
+	 * @param {Number} [width=1] - The width of the render target.
+	 * @param {Number} [height=1] - The height of the render target.
+	 * @param {Object} [options={}] - The configuration options.
+	 */
+	constructor( width = 1, height = 1, options = {} ) {
+
+		super( width, height, options );
+
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
+		this.isXRRenderTarget = true;
+
+		/**
+		 * Whether the attachments of the render target
+		 * are defined by external textures. This flag is
+		 * set to `true` when using the WebXR Layers API.
+		 *
+		 * @type {Boolean}
+		 * @default false
+		 */
+		this.hasExternalTextures = false;
+
+		/**
+		 * Whether a depth buffer should automatically be allocated
+		 * for this XR render target or not.
+		 *
+		 * Allocating a depth buffer is the default behavior of XR render
+		 * targets. However, when using the WebXR Layers API, this flag
+		 * must be set to `false` when the `ignoreDepthValues` property of
+		 * the projection layers evaluates to `false`.
+		 *
+		 * Reference: {@link https://www.w3.org/TR/webxrlayers-1/#dom-xrprojectionlayer-ignoredepthvalues}.
+		 *
+		 * @type {Boolean}
+		 * @default true
+		 */
+		this.autoAllocateDepthBuffer = true;
+
+	}
+
+	copy( source ) {
+
+		super.copy( source );
+
+		this.hasExternalTextures = source.hasExternalTextures;
+		this.autoAllocateDepthBuffer = source.autoAllocateDepthBuffer;
+
+		return this;
+
+	}
+
+
+}
+
+export { XRRenderTarget };

package/src/renderers/common/extras/PMREMGenerator.js

@@ -69,7 +69,9 @@ const _axisDirections = [
 	/*@__PURE__*/ new Vector3( 1, 1, 1 )
 ];
 
-//
+// maps blur materials to their uniforms dictionary
+
+const _uniformsMap = new WeakMap();
 
 // WebGPU Face indices
 const _faceLib = [
@@ -77,8 +79,8 @@ const _faceLib = [
 	0, 4, 2
 ];
 
-const direction = getDirection( uv(), attribute( 'faceIndex' ) ).normalize();
-const outputDirection = vec3( direction.x, direction.y.negate(), direction.z );
+const _direction = /*@__PURE__*/ getDirection( uv(), attribute( 'faceIndex' ) ).normalize();
+const _outputDirection = /*@__PURE__*/ vec3( _direction.x, _direction.y, _direction.z );
 
 /**
  * This class generates a Prefiltered, Mipmapped Radiance Environment Map
@@ -128,6 +130,14 @@ class PMREMGenerator {
 	 * in radians to be applied to the scene before PMREM generation. Optional near
 	 * and far planes ensure the scene is rendered in its entirety (the cubeCamera
 	 * is placed at the origin).
+	 *
+	 * @param {Scene} scene - The scene to be captured.
+	 * @param {Number} [sigma=0] - The blur radius in radians.
+	 * @param {Number} [near=0.1] - The near plane distance.
+	 * @param {Number} [far=100] - The far plane distance.
+	 * @param {RenderTarget?} [renderTarget=null] - The render target to use.
+	 * @return {RenderTarget} The resulting PMREM.
+	 * @see fromSceneAsync
 	 */
 	fromScene( scene, sigma = 0, near = 0.1, far = 100, renderTarget = null ) {
 
@@ -168,6 +178,21 @@ class PMREMGenerator {
 
 	}
 
+	/**
+	 * Generates a PMREM from a supplied Scene, which can be faster than using an
+	 * image if networking bandwidth is low. Optional sigma specifies a blur radius
+	 * in radians to be applied to the scene before PMREM generation. Optional near
+	 * and far planes ensure the scene is rendered in its entirety (the cubeCamera
+	 * is placed at the origin).
+	 *
+	 * @param {Scene} scene - The scene to be captured.
+	 * @param {Number} [sigma=0] - The blur radius in radians.
+	 * @param {Number} [near=0.1] - The near plane distance.
+	 * @param {Number} [far=100] - The far plane distance.
+	 * @param {RenderTarget?} [renderTarget=null] - The render target to use.
+	 * @return {Promise<RenderTarget>} The resulting PMREM.
+	 * @see fromScene
+	 */
 	async fromSceneAsync( scene, sigma = 0, near = 0.1, far = 100, renderTarget = null ) {
 
 		if ( this._hasInitialized === false ) await this._renderer.init();
@@ -180,6 +205,11 @@ class PMREMGenerator {
 	 * Generates a PMREM from an equirectangular texture, which can be either LDR
 	 * or HDR. The ideal input image size is 1k (1024 x 512),
 	 * as this matches best with the 256 x 256 cubemap output.
+	 *
+	 * @param {Texture} equirectangular - The equirectangular texture to be converted.
+	 * @param {RenderTarget?} [renderTarget=null] - The render target to use.
+	 * @return {RenderTarget} The resulting PMREM.
+	 * @see fromEquirectangularAsync
 	 */
 	fromEquirectangular( equirectangular, renderTarget = null ) {
 
@@ -201,6 +231,16 @@ class PMREMGenerator {
 
 	}
 
+	/**
+	 * Generates a PMREM from an equirectangular texture, which can be either LDR
+	 * or HDR. The ideal input image size is 1k (1024 x 512),
+	 * as this matches best with the 256 x 256 cubemap output.
+	 *
+	 * @param {Texture} equirectangular - The equirectangular texture to be converted.
+	 * @param {RenderTarget?} [renderTarget=null] - The render target to use.
+	 * @return {Promise<RenderTarget>} The resulting PMREM.
+	 * @see fromEquirectangular
+	 */
 	async fromEquirectangularAsync( equirectangular, renderTarget = null ) {
 
 		if ( this._hasInitialized === false ) await this._renderer.init();
@@ -213,6 +253,11 @@ class PMREMGenerator {
 	 * Generates a PMREM from an cubemap texture, which can be either LDR
 	 * or HDR. The ideal input cube size is 256 x 256,
 	 * as this matches best with the 256 x 256 cubemap output.
+	 *
+	 * @param {Texture} cubemap - The cubemap texture to be converted.
+	 * @param {RenderTarget?} [renderTarget=null] - The render target to use.
+	 * @return {RenderTarget} The resulting PMREM.
+	 * @see fromCubemapAsync
 	 */
 	fromCubemap( cubemap, renderTarget = null ) {
 
@@ -234,6 +279,16 @@ class PMREMGenerator {
 
 	}
 
+	/**
+	 * Generates a PMREM from an cubemap texture, which can be either LDR
+	 * or HDR. The ideal input cube size is 256 x 256,
+	 * with the 256 x 256 cubemap output.
+	 *
+	 * @param {Texture} cubemap - The cubemap texture to be converted.
+	 * @param {RenderTarget?} [renderTarget=null] - The render target to use.
+	 * @return {Promise<RenderTarget>} The resulting PMREM.
+	 * @see fromCubemap
+	 */
 	async fromCubemapAsync( cubemap, renderTarget = null ) {
 
 		if ( this._hasInitialized === false ) await this._renderer.init();
@@ -245,6 +300,8 @@ class PMREMGenerator {
 	/**
 	 * Pre-compiles the cubemap shader. You can get faster start-up by invoking this method during
 	 * your texture's network fetch for increased concurrency.
+	 *
+	 * @returns {Promise}
 	 */
 	async compileCubemapShader() {
 
@@ -260,6 +317,8 @@ class PMREMGenerator {
 	/**
 	 * Pre-compiles the equirectangular shader. You can get faster start-up by invoking this method during
 	 * your texture's network fetch for increased concurrency.
+	 *
+	 * @returns {Promise}
 	 */
 	async compileEquirectangularShader() {
 
@@ -406,8 +465,8 @@ class PMREMGenerator {
 		cubeCamera.far = far;
 
 		// px, py, pz, nx, ny, nz
-		const upSign = [ - 1, 1, - 1, - 1, - 1, - 1 ];
-		const forwardSign = [ 1, 1, 1, - 1, - 1, - 1 ];
+		const upSign = [ 1, 1, 1, 1, - 1, 1 ];
+		const forwardSign = [ 1, - 1, 1, - 1, 1, - 1 ];
 
 		const renderer = this._renderer;
 
@@ -562,6 +621,12 @@ class PMREMGenerator {
 	 * the blur latitudinally (around the poles), and then longitudinally (towards
 	 * the poles) to approximate the orthogonally-separable blur. It is least
 	 * accurate at the poles, but still does a decent job.
+	 *
+	 * @param {RenderTarget} cubeUVRenderTarget - The cubemap render target.
+	 * @param {Number} lodIn - The input level-of-detail.
+	 * @param {Number} lodOut - The output level-of-detail.
+	 * @param {Number} sigma - The blur radius in radians.
+	 * @param {Vector3} [poleAxis] - The pole axis.
 	 */
 	_blur( cubeUVRenderTarget, lodIn, lodOut, sigma, poleAxis ) {
 
@@ -604,7 +669,7 @@ class PMREMGenerator {
 		const blurMesh = this._lodMeshes[ lodOut ];
 		blurMesh.material = blurMaterial;
 
-		const blurUniforms = blurMaterial.uniforms;
+		const blurUniforms = _uniformsMap.get( blurMaterial );
 
 		const pixels = this._sizeLods[ lodIn ] - 1;
 		const radiansPerPixel = isFinite( sigmaRadians ) ? Math.PI / ( 2 * pixels ) : 2 * Math.PI / ( 2 * MAX_SAMPLES - 1 );
@@ -808,7 +873,7 @@ function _getBlurShader( lodMax, width, height ) {
 		latitudinal,
 		weights,
 		poleAxis,
-		outputDirection,
+		outputDirection: _outputDirection,
 		dTheta,
 		samples,
 		envMap,
@@ -819,9 +884,10 @@ function _getBlurShader( lodMax, width, height ) {
 	};
 
 	const material = _getMaterial( 'blur' );
-	material.uniforms = materialUniforms; // TODO: Move to outside of the material
 	material.fragmentNode = blur( { ...materialUniforms, latitudinal: latitudinal.equal( 1 ) } );
 
+	_uniformsMap.set( material, materialUniforms );
+
 	return material;
 
 }
@@ -829,7 +895,7 @@ function _getBlurShader( lodMax, width, height ) {
 function _getCubemapMaterial( envTexture ) {
 
 	const material = _getMaterial( 'cubemap' );
-	material.fragmentNode = cubeTexture( envTexture, outputDirection );
+	material.fragmentNode = cubeTexture( envTexture, _outputDirection );
 
 	return material;
 
@@ -838,7 +904,7 @@ function _getCubemapMaterial( envTexture ) {
 function _getEquirectMaterial( envTexture ) {
 
 	const material = _getMaterial( 'equirect' );
-	material.fragmentNode = texture( envTexture, equirectUV( outputDirection ), 0 );
+	material.fragmentNode = texture( envTexture, equirectUV( _outputDirection ), 0 );
 
 	return material;
 

package/src/renderers/common/nodes/NodeBuilderState.js

@@ -1,34 +1,128 @@
 import BindGroup from '../BindGroup.js';
 
+/**
+ * This module represents the state of a node builder after it was
+ * used to build the nodes for a render object. The state holds the
+ * results of the build for further processing in the renderer.
+ *
+ * Render objects with identical cache keys share the same node builder state.
+ *
+ * @private
+ */
 class NodeBuilderState {
 
-	constructor( vertexShader, fragmentShader, computeShader, nodeAttributes, bindings, updateNodes, updateBeforeNodes, updateAfterNodes, monitor, transforms = [] ) {
-
+	/**
+	 * Constructs a new node builder state.
+	 *
+	 * @param {String?} vertexShader - The native vertex shader code.
+	 * @param {String?} fragmentShader - The native fragment shader code.
+	 * @param {String?} computeShader - The native compute shader code.
+	 * @param {Array<NodeAttribute>} nodeAttributes - An array of node attributes.
+	 * @param {Array<BindGroup>} bindings - An array of bind groups.
+	 * @param {Array<Node>} updateNodes - An array of nodes that implement their `update()` method.
+	 * @param {Array<Node>} updateBeforeNodes - An array of nodes that implement their `updateBefore()` method.
+	 * @param {Array<Node>} updateAfterNodes - An array of nodes that implement their `updateAfter()` method.
+	 * @param {NodeMaterialObserver} observer - A node material observer.
+	 * @param {Array<Object>} transforms - An array with transform attribute objects. Only relevant when using compute shaders with WebGL 2.
+	 */
+	constructor( vertexShader, fragmentShader, computeShader, nodeAttributes, bindings, updateNodes, updateBeforeNodes, updateAfterNodes, observer, transforms = [] ) {
+
+		/**
+		 * The native vertex shader code.
+		 *
+		 * @type {String}
+		 */
 		this.vertexShader = vertexShader;
+
+		/**
+		 * The native fragment shader code.
+		 *
+		 * @type {String}
+		 */
 		this.fragmentShader = fragmentShader;
+
+		/**
+		 * The native compute shader code.
+		 *
+		 * @type {String}
+		 */
 		this.computeShader = computeShader;
+
+		/**
+		 * An array with transform attribute objects.
+		 * Only relevant when using compute shaders with WebGL 2.
+		 *
+		 * @type {Array<Object>}
+		 */
 		this.transforms = transforms;
 
+		/**
+		 * An array of node attributes representing
+		 * the attributes of the shaders.
+		 *
+		 * @type {Array<NodeAttribute>}
+		 */
 		this.nodeAttributes = nodeAttributes;
+
+		/**
+		 * An array of bind groups representing the uniform or storage
+		 * buffers, texture or samplers of the shader.
+		 *
+		 * @type {Array<BindGroup>}
+		 */
 		this.bindings = bindings;
 
+		/**
+		 * An array of nodes that implement their `update()` method.
+		 *
+		 * @type {Array<Node>}
+		 */
 		this.updateNodes = updateNodes;
+
+		/**
+		 * An array of nodes that implement their `updateBefore()` method.
+		 *
+		 * @type {Array<Node>}
+		 */
 		this.updateBeforeNodes = updateBeforeNodes;
-		this.updateAfterNodes = updateAfterNodes;
 
-		this.monitor = monitor;
+		/**
+		 * An array of nodes that implement their `updateAfter()` method.
+		 *
+		 * @type {Array<Node>}
+		 */
+		this.updateAfterNodes = updateAfterNodes;
 
+		/**
+		 * A node material observer.
+		 *
+		 * @type {NodeMaterialObserver}
+		 */
+		this.observer = observer;
+
+		/**
+		 * How often this state is used by render objects.
+		 *
+		 * @type {Number}
+		 */
 		this.usedTimes = 0;
 
 	}
 
+	/**
+	 * This method is used to create a array of bind groups based
+	 * on the existing bind groups of this state. Shared groups are
+	 * not cloned.
+	 *
+	 * @return {Array<BindGroup>} A array of bind groups.
+	 */
 	createBindings() {
 
 		const bindings = [];
 
 		for ( const instanceGroup of this.bindings ) {
 
-			const shared = instanceGroup.bindings[ 0 ].groupNode.shared;
+			const shared = instanceGroup.bindings[ 0 ].groupNode.shared; // All bindings in the group must have the same groupNode.
 
 			if ( shared !== true ) {
 

package/src/renderers/common/nodes/NodeLibrary.js

@@ -1,13 +1,52 @@
+/**
+ * The purpose of a node library is to assign node implementations
+ * to existing library features. In `WebGPURenderer` lights, materials
+ * which are not based on `NodeMaterial` as well as tone mapping techniques
+ * are implemented with node-based modules.
+ *
+ * @private
+ */
 class NodeLibrary {
 
+	/**
+	 * Constructs a new node library.
+	 */
 	constructor() {
 
+		/**
+		 * A weak map that maps lights to light nodes.
+		 *
+		 * @type {WeakMap<Light.constructor,AnalyticLightNode.constructor>}
+		 */
 		this.lightNodes = new WeakMap();
+
+		/**
+		 * A map that maps materials to node materials.
+		 *
+		 * @type {Map<String,NodeMaterial.constructor>}
+		 */
 		this.materialNodes = new Map();
+
+		/**
+		 * A map that maps tone mapping techniques (constants)
+		 * to tone mapping node functions.
+		 *
+		 * @type {Map<Number,Function>}
+		 */
 		this.toneMappingNodes = new Map();
 
 	}
 
+	/**
+	 * Returns a matching node material instance for the given material object.
+	 *
+	 * This method also assigns/copies the properties of the given material object
+	 * to the node material. This is done to make sure the current material
+	 * configuration carries over to the node version.
+	 *
+	 * @param {Material} material - A material.
+	 * @return {NodeMaterial} The corresponding node material.
+	 */
 	fromMaterial( material ) {
 
 		if ( material.isNodeMaterial ) return material;
@@ -32,42 +71,85 @@ class NodeLibrary {
 
 	}
 
+	/**
+	 * Adds a tone mapping node function for a tone mapping technique (constant).
+	 *
+	 * @param {Function} toneMappingNode - The tone mapping node function.
+	 * @param {Number} toneMapping - The tone mapping.
+	 */
 	addToneMapping( toneMappingNode, toneMapping ) {
 
 		this.addType( toneMappingNode, toneMapping, this.toneMappingNodes );
 
 	}
 
+	/**
+	 * Returns a tone mapping node function for a tone mapping technique (constant).
+	 *
+	 * @param {Number} toneMapping - The tone mapping.
+	 * @return {Function?} The tone mapping node function. Returns `null` if no node function is found.
+	 */
 	getToneMappingFunction( toneMapping ) {
 
 		return this.toneMappingNodes.get( toneMapping ) || null;
 
 	}
 
+	/**
+	 * Returns a node material class definition for a material type.
+	 *
+	 * @param {String} materialType - The material type.
+	 * @return {NodeMaterial.constructor?} The node material class definition. Returns `null` if no node material is found.
+	 */
 	getMaterialNodeClass( materialType ) {
 
 		return this.materialNodes.get( materialType ) || null;
 
 	}
 
+	/**
+	 * Adds a node material class definition for a given material type.
+	 *
+	 * @param {NodeMaterial.constructor} materialNodeClass - The node material class definition.
+	 * @param {String} materialClassType - The material type.
+	 */
 	addMaterial( materialNodeClass, materialClassType ) {
 
 		this.addType( materialNodeClass, materialClassType, this.materialNodes );
 
 	}
 
+	/**
+	 * Returns a light node class definition for a light class definition.
+	 *
+	 * @param {Light.constructor} light - The light class definition.
+	 * @return {AnalyticLightNode.constructor?} The light node class definition. Returns `null` if no light node is found.
+	 */
 	getLightNodeClass( light ) {
 
 		return this.lightNodes.get( light ) || null;
 
 	}
 
+	/**
+	 * Adds a light node class definition for a given light class definition.
+	 *
+	 * @param {AnalyticLightNode.constructor} lightNodeClass - The light node class definition.
+	 * @param {Light.constructor} lightClass - The light class definition.
+	 */
 	addLight( lightNodeClass, lightClass ) {
 
 		this.addClass( lightNodeClass, lightClass, this.lightNodes );
 
 	}
 
+	/**
+	 * Adds a node class definition for the given type to the provided type library.
+	 *
+	 * @param {Any} nodeClass - The node class definition.
+	 * @param {Number|String} type - The object type.
+	 * @param {Map} library - The type library.
+	 */
 	addType( nodeClass, type, library ) {
 
 		if ( library.has( type ) ) {
@@ -84,6 +166,13 @@ class NodeLibrary {
 
 	}
 
+	/**
+	 * Adds a node class definition for the given class definition to the provided type library.
+	 *
+	 * @param {Any} nodeClass - The node class definition.
+	 * @param {Any} baseClass - The class definition.
+	 * @param {WeakMap} library - The type library.
+	 */
 	addClass( nodeClass, baseClass, library ) {
 
 		if ( library.has( baseClass ) ) {

package/src/renderers/common/nodes/NodeSampledTexture.js

@@ -1,24 +1,68 @@
 import { SampledTexture } from '../SampledTexture.js';
 
+/**
+ * A special form of sampled texture binding type.
+ * It's texture value is managed by a node object.
+ *
+ * @private
+ * @augments SampledTexture
+ */
 class NodeSampledTexture extends SampledTexture {
 
+	/**
+	 * Constructs a new node-based sampled texture.
+	 *
+	 * @param {String} name - The textures's name.
+	 * @param {TextureNode} textureNode - The texture node.
+	 * @param {UniformGroupNode} groupNode - The uniform group node.
+	 * @param {String?} [access=null] - The access type.
+	 */
 	constructor( name, textureNode, groupNode, access = null ) {
 
 		super( name, textureNode ? textureNode.value : null );
 
+		/**
+		 * The texture node.
+		 *
+		 * @type {TextureNode}
+		 */
 		this.textureNode = textureNode;
+
+		/**
+		 * The uniform group node.
+		 *
+		 * @type {UniformGroupNode}
+		 */
 		this.groupNode = groupNode;
 
+		/**
+		 * The access type.
+		 *
+		 * @type {String?}
+		 * @default null
+		 */
 		this.access = access;
 
 	}
 
+	/**
+	 * Overwrites the default to additionally check if the node value has changed.
+	 *
+	 * @param {Number} generation - The generation.
+	 * @return {Boolean} Whether an update is required or not.
+	 */
 	needsBindingsUpdate( generation ) {
 
 		return this.textureNode.value !== this.texture || super.needsBindingsUpdate( generation );
 
 	}
 
+	/**
+	 * Updates the binding.
+	 *
+	 * @return {Boolean} Whether the texture has been updated and must be
+	 * uploaded to the GPU.
+	 */
 	update() {
 
 		const { textureNode } = this;
@@ -37,24 +81,68 @@ class NodeSampledTexture extends SampledTexture {
 
 }
 
+/**
+ * A special form of sampled cube texture binding type.
+ * It's texture value is managed by a node object.
+ *
+ * @private
+ * @augments NodeSampledTexture
+ */
 class NodeSampledCubeTexture extends NodeSampledTexture {
 
-	constructor( name, textureNode, groupNode, access ) {
+	/**
+	 * Constructs a new node-based sampled cube texture.
+	 *
+	 * @param {String} name - The textures's name.
+	 * @param {TextureNode} textureNode - The texture node.
+	 * @param {UniformGroupNode} groupNode - The uniform group node.
+	 * @param {String?} [access=null] - The access type.
+	 */
+	constructor( name, textureNode, groupNode, access = null ) {
 
 		super( name, textureNode, groupNode, access );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isSampledCubeTexture = true;
 
 	}
 
 }
 
+/**
+ * A special form of sampled 3D texture binding type.
+ * It's texture value is managed by a node object.
+ *
+ * @private
+ * @augments NodeSampledTexture
+ */
 class NodeSampledTexture3D extends NodeSampledTexture {
 
-	constructor( name, textureNode, groupNode, access ) {
+	/**
+	 * Constructs a new node-based sampled 3D texture.
+	 *
+	 * @param {String} name - The textures's name.
+	 * @param {TextureNode} textureNode - The texture node.
+	 * @param {UniformGroupNode} groupNode - The uniform group node.
+	 * @param {String?} [access=null] - The access type.
+	 */
+	constructor( name, textureNode, groupNode, access = null ) {
 
 		super( name, textureNode, groupNode, access );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isSampledTexture3D = true;
 
 	}