super-three 0.173.4 → 0.175.0

package/src/nodes/display/PassNode.js

@@ -10,14 +10,12 @@ import { Vector2 } from '../../math/Vector2.js';
 import { DepthTexture } from '../../textures/DepthTexture.js';
 import { RenderTarget } from '../../core/RenderTarget.js';
 
-/** @module PassNode **/
-
 const _size = /*@__PURE__*/ new Vector2();
 
 /**
  * Represents the texture of a pass node.
  *
- * @augments module:TextureNode~TextureNode
+ * @augments TextureNode
  */
 class PassTextureNode extends TextureNode {
 
@@ -68,7 +66,7 @@ class PassTextureNode extends TextureNode {
  * An extension of `PassTextureNode` which allows to manage more than one
  * internal texture. Relevant for the `getPreviousTexture()` related API.
  *
- * @augments module:PassTextureNode~PassTextureNode
+ * @augments PassTextureNode
  */
 class PassMultipleTextureNode extends PassTextureNode {
 
@@ -82,8 +80,8 @@ class PassMultipleTextureNode extends PassTextureNode {
 	 * Constructs a new pass texture node.
 	 *
 	 * @param {PassNode} passNode - The pass node.
-	 * @param {String} textureName - The output texture name.
-	 * @param {Boolean} [previousTexture=false] - Whether previous frame data should be used or not.
+	 * @param {string} textureName - The output texture name.
+	 * @param {boolean} [previousTexture=false] - Whether previous frame data should be used or not.
 	 */
 	constructor( passNode, textureName, previousTexture = false ) {
 
@@ -96,14 +94,14 @@ class PassMultipleTextureNode extends PassTextureNode {
 		/**
 		 * The output texture name.
 		 *
-		 * @type {String}
+		 * @type {string}
 		 */
 		this.textureName = textureName;
 
 		/**
 		 * Whether previous frame data should be used or not.
 		 *
-		 * @type {Boolean}
+		 * @type {boolean}
 		 */
 		this.previousTexture = previousTexture;
 
@@ -201,7 +199,7 @@ class PassNode extends TempNode {
 		 * The pass's pixel ratio. Will be kept automatically kept in sync with the renderer's pixel ratio.
 		 *
 		 * @private
-		 * @type {Number}
+		 * @type {number}
 		 * @default 1
 		 */
 		this._pixelRatio = 1;
@@ -209,7 +207,7 @@ class PassNode extends TempNode {
 		/**
 		 * The pass's pixel width. Will be kept automatically kept in sync with the renderer's width.
 		 * @private
-		 * @type {Number}
+		 * @type {number}
 		 * @default 1
 		 */
 		this._width = 1;
@@ -217,7 +215,7 @@ class PassNode extends TempNode {
 		/**
 		 * The pass's pixel height. Will be kept automatically kept in sync with the renderer's height.
 		 * @private
-		 * @type {Number}
+		 * @type {number}
 		 * @default 1
 		 */
 		this._height = 1;
@@ -242,7 +240,7 @@ class PassNode extends TempNode {
 		 * A dictionary holding the internal result textures.
 		 *
 		 * @private
-		 * @type {Object<String, Texture>}
+		 * @type {Object<string, Texture>}
 		 */
 		this._textures = {
 			output: renderTarget.texture,
@@ -253,7 +251,7 @@ class PassNode extends TempNode {
 		 * A dictionary holding the internal texture nodes.
 		 *
 		 * @private
-		 * @type {Object<String, TextureNode>}
+		 * @type {Object<string, TextureNode>}
 		 */
 		this._textureNodes = {};
 
@@ -278,7 +276,7 @@ class PassNode extends TempNode {
 		 * Used for computing velocity/motion vectors.
 		 *
 		 * @private
-		 * @type {Object<String, Texture>}
+		 * @type {Object<string, Texture>}
 		 */
 		this._previousTextures = {};
 
@@ -287,7 +285,7 @@ class PassNode extends TempNode {
 		 * Used for computing velocity/motion vectors.
 		 *
 		 * @private
-		 * @type {Object<String, TextureNode>}
+		 * @type {Object<string, TextureNode>}
 		 */
 		this._previousTextureNodes = {};
 
@@ -311,15 +309,19 @@ class PassNode extends TempNode {
 		 * A MRT node configuring the MRT settings.
 		 *
 		 * @private
-		 * @type {MRTNode?}
+		 * @type {?MRTNode}
 		 * @default null
 		 */
 		this._mrt = null;
 
+		this._layers = null;
+
+		this._resolution = 1;
+
 		/**
 		 * This flag can be used for type testing.
 		 *
-		 * @type {Boolean}
+		 * @type {boolean}
 		 * @readonly
 		 * @default true
 		 */
@@ -329,13 +331,54 @@ class PassNode extends TempNode {
 		 * The `updateBeforeType` is set to `NodeUpdateType.FRAME` since the node renders the
 		 * scene once per frame in its {@link PassNode#updateBefore} method.
 		 *
-		 * @type {String}
+		 * @type {string}
 		 * @default 'frame'
 		 */
 		this.updateBeforeType = NodeUpdateType.FRAME;
 
 	}
 
+	/**
+	 * Sets the resolution for the pass.
+	 * The resolution is a factor that is multiplied with the renderer's width and height.
+	 *
+	 * @param {number} resolution - The resolution to set. A value of `1` means full resolution.
+	 * @return {PassNode} A reference to this pass.
+	 */
+	setResolution( resolution ) {
+
+		this._resolution = resolution;
+
+		return this;
+
+	}
+
+	/**
+	 * Gets the current resolution of the pass.
+	 *
+	 * @return {number} The current resolution. A value of `1` means full resolution.
+	 * @default 1
+	 */
+	getResolution() {
+
+		return this._resolution;
+
+	}
+
+	setLayers( layers ) {
+
+		this._layers = layers;
+
+		return this;
+
+	}
+
+	getLayers() {
+
+		return this._layers;
+
+	}
+
 	/**
 	 * Sets the given MRT node to setup MRT for this pass.
 	 *
@@ -364,7 +407,7 @@ class PassNode extends TempNode {
 	/**
 	 * The method is overwritten so it always returns `true`.
 	 *
-	 * @return {Boolean} Whether this node is global or not.
+	 * @return {boolean} Whether this node is global or not.
 	 */
 	isGlobal() {
 
@@ -375,7 +418,7 @@ class PassNode extends TempNode {
 	/**
 	 * Returns the texture for the given output name.
 	 *
-	 * @param {String} name - The output name to get the texture for.
+	 * @param {string} name - The output name to get the texture for.
 	 * @return {Texture} The texture.
 	 */
 	getTexture( name ) {
@@ -402,7 +445,7 @@ class PassNode extends TempNode {
 	/**
 	 * Returns the texture holding the data of the previous frame for the given output name.
 	 *
-	 * @param {String} name - The output name to get the texture for.
+	 * @param {string} name - The output name to get the texture for.
 	 * @return {Texture} The texture holding the data of the previous frame.
 	 */
 	getPreviousTexture( name ) {
@@ -424,7 +467,7 @@ class PassNode extends TempNode {
 	/**
 	 * Switches current and previous textures for the given output name.
 	 *
-	 * @param {String} name - The output name.
+	 * @param {string} name - The output name.
 	 */
 	toggleTexture( name ) {
 
@@ -450,7 +493,7 @@ class PassNode extends TempNode {
 	/**
 	 * Returns the texture node for the given output name.
 	 *
-	 * @param {String} [name='output'] - The output name to get the texture node for.
+	 * @param {string} [name='output'] - The output name to get the texture node for.
 	 * @return {TextureNode} The texture node.
 	 */
 	getTextureNode( name = 'output' ) {
@@ -472,7 +515,7 @@ class PassNode extends TempNode {
 	/**
 	 * Returns the previous texture node for the given output name.
 	 *
-	 * @param {String} [name='output'] - The output name to get the previous texture node for.
+	 * @param {string} [name='output'] - The output name to get the previous texture node for.
 	 * @return {TextureNode} The previous texture node.
 	 */
 	getPreviousTextureNode( name = 'output' ) {
@@ -496,7 +539,7 @@ class PassNode extends TempNode {
 	/**
 	 * Returns a viewZ node of this pass.
 	 *
-	 * @param {String} [name='depth'] - The output name to get the viewZ node for. In most cases the default `'depth'` can be used however the parameter exists for custom depth outputs.
+	 * @param {string} [name='depth'] - The output name to get the viewZ node for. In most cases the default `'depth'` can be used however the parameter exists for custom depth outputs.
 	 * @return {Node} The viewZ node.
 	 */
 	getViewZNode( name = 'depth' ) {
@@ -519,7 +562,7 @@ class PassNode extends TempNode {
 	/**
 	 * Returns a linear depth node of this pass.
 	 *
-	 * @param {String} [name='depth'] - The output name to get the linear depth node for. In most cases the default `'depth'` can be used however the parameter exists for custom depth outputs.
+	 * @param {string} [name='depth'] - The output name to get the linear depth node for. In most cases the default `'depth'` can be used however the parameter exists for custom depth outputs.
 	 * @return {Node} The linear depth node.
 	 */
 	getLinearDepthNode( name = 'depth' ) {
@@ -562,20 +605,48 @@ class PassNode extends TempNode {
 	updateBefore( frame ) {
 
 		const { renderer } = frame;
-		const { scene, camera } = this;
+		const { scene } = this;
+
+		let camera;
+		let pixelRatio;
+
+		const outputRenderTarget = renderer.getOutputRenderTarget();
+
+		if ( outputRenderTarget && outputRenderTarget.isXRRenderTarget === true ) {
 
-		this._pixelRatio = renderer.getPixelRatio();
+			pixelRatio = 1;
+			camera = renderer.xr.getCamera();
 
-		const size = renderer.getSize( _size );
+			renderer.xr.updateCamera( camera );
 
-		this.setSize( size.width, size.height );
+			_size.set( outputRenderTarget.width, outputRenderTarget.height );
+
+		} else {
+
+			camera = this.camera;
+			pixelRatio = renderer.getPixelRatio();
+
+			renderer.getSize( _size );
+
+		}
+
+		this._pixelRatio = pixelRatio;
+
+		this.setSize( _size.width, _size.height );
 
 		const currentRenderTarget = renderer.getRenderTarget();
 		const currentMRT = renderer.getMRT();
+		const currentMask = camera.layers.mask;
 
 		this._cameraNear.value = camera.near;
 		this._cameraFar.value = camera.far;
 
+		if ( this._layers !== null ) {
+
+			camera.layers.mask = this._layers.mask;
+
+		}
+
 		for ( const name in this._previousTextures ) {
 
 			this.toggleTexture( name );
@@ -590,21 +661,23 @@ class PassNode extends TempNode {
 		renderer.setRenderTarget( currentRenderTarget );
 		renderer.setMRT( currentMRT );
 
+		camera.layers.mask = currentMask;
+
 	}
 
 	/**
 	 * Sets the size of the pass's render target. Honors the pixel ratio.
 	 *
-	 * @param {Number} width - The width to set.
-	 * @param {Number} height - The height to set.
+	 * @param {number} width - The width to set.
+	 * @param {number} height - The height to set.
 	 */
 	setSize( width, height ) {
 
 		this._width = width;
 		this._height = height;
 
-		const effectiveWidth = this._width * this._pixelRatio;
-		const effectiveHeight = this._height * this._pixelRatio;
+		const effectiveWidth = this._width * this._pixelRatio * this._resolution;
+		const effectiveHeight = this._height * this._pixelRatio * this._resolution;
 
 		this.renderTarget.setSize( effectiveWidth, effectiveHeight );
 
@@ -613,7 +686,7 @@ class PassNode extends TempNode {
 	/**
 	 * Sets the pixel ratio the pass's render target and updates the size.
 	 *
-	 * @param {Number} pixelRatio - The pixel ratio to set.
+	 * @param {number} pixelRatio - The pixel ratio to set.
 	 */
 	setPixelRatio( pixelRatio ) {
 
@@ -635,7 +708,18 @@ class PassNode extends TempNode {
 
 }
 
+/**
+ * @static
+ * @type {'color'}
+ * @default 'color'
+ */
 PassNode.COLOR = 'color';
+
+/**
+ * @static
+ * @type {'depth'}
+ * @default 'depth'
+ */
 PassNode.DEPTH = 'depth';
 
 export default PassNode;
@@ -643,6 +727,7 @@ export default PassNode;
 /**
  * TSL function for creating a pass node.
  *
+ * @tsl
  * @function
  * @param {Scene} scene - A reference to the scene.
  * @param {Camera} camera - A reference to the camera.
@@ -654,6 +739,7 @@ export const pass = ( scene, camera, options ) => nodeObject( new PassNode( Pass
 /**
  * TSL function for creating a pass texture node.
  *
+ * @tsl
  * @function
  * @param {PassNode} pass - The pass node.
  * @param {Texture} texture - The output texture.
@@ -664,6 +750,7 @@ export const passTexture = ( pass, texture ) => nodeObject( new PassTextureNode(
 /**
  * TSL function for creating a depth pass node.
  *
+ * @tsl
  * @function
  * @param {Scene} scene - A reference to the scene.
  * @param {Camera} camera - A reference to the camera.

package/src/nodes/display/PosterizeNode.js

@@ -1,8 +1,6 @@
 import TempNode from '../core/TempNode.js';
 import { nodeProxy } from '../tsl/TSLBase.js';
 
-/** @module PosterizeNode **/
-
 /**
  * Represents a posterize effect which reduces the number of colors
  * in an image, resulting in a more blocky and stylized appearance.
@@ -58,9 +56,10 @@ export default PosterizeNode;
 /**
  * TSL function for creating a posterize node.
  *
+ * @tsl
  * @function
  * @param {Node} sourceNode - The input color.
  * @param {Node} stepsNode - Controls the intensity of the posterization effect. A lower number results in a more blocky appearance.
  * @returns {PosterizeNode}
  */
-export const posterize = /*@__PURE__*/ nodeProxy( PosterizeNode );
+export const posterize = /*@__PURE__*/ nodeProxy( PosterizeNode ).setParameterLength( 2 );

package/src/nodes/display/RenderOutputNode.js

@@ -4,8 +4,6 @@ import { addMethodChaining, nodeObject } from '../tsl/TSLCore.js';
 import { NoColorSpace, NoToneMapping } from '../../constants.js';
 import { ColorManagement } from '../../math/ColorManagement.js';
 
-/** @module RenderOutputNode **/
-
 /**
  * Normally, tone mapping and color conversion happens automatically
  * before outputting pixel too the default (screen) framebuffer. In certain
@@ -41,8 +39,8 @@ class RenderOutputNode extends TempNode {
 	 * Constructs a new render output node.
 	 *
 	 * @param {Node} colorNode - The color node to process.
-	 * @param {Number} toneMapping - The tone mapping type.
-	 * @param {String} outputColorSpace - The output color space.
+	 * @param {?number} toneMapping - The tone mapping type.
+	 * @param {?string} outputColorSpace - The output color space.
 	 */
 	constructor( colorNode, toneMapping, outputColorSpace ) {
 
@@ -58,21 +56,21 @@ class RenderOutputNode extends TempNode {
 		/**
 		 * The tone mapping type.
 		 *
-		 * @type {Number?}
+		 * @type {?number}
 		 */
 		this.toneMapping = toneMapping;
 
 		/**
 		 * The output color space.
 		 *
-		 * @type {String?}
+		 * @type {?string}
 		 */
 		this.outputColorSpace = outputColorSpace;
 
 		/**
 		 * This flag can be used for type testing.
 		 *
-		 * @type {Boolean}
+		 * @type {boolean}
 		 * @readonly
 		 * @default true
 		 */
@@ -114,10 +112,11 @@ export default RenderOutputNode;
 /**
  * TSL function for creating a posterize node.
  *
+ * @tsl
  * @function
  * @param {Node} color - The color node to process.
- * @param {Number?} [toneMapping=null] - The tone mapping type.
- * @param {String?} [outputColorSpace=null] - The output color space.
+ * @param {?number} [toneMapping=null] - The tone mapping type.
+ * @param {?string} [outputColorSpace=null] - The output color space.
  * @returns {RenderOutputNode}
  */
 export const renderOutput = ( color, toneMapping = null, outputColorSpace = null ) => nodeObject( new RenderOutputNode( nodeObject( color ), toneMapping, outputColorSpace ) );

package/src/nodes/display/ScreenNode.js

@@ -6,13 +6,11 @@ import { Fn, nodeImmutable, vec2 } from '../tsl/TSLBase.js';
 import { Vector2 } from '../../math/Vector2.js';
 import { Vector4 } from '../../math/Vector4.js';
 
-/** @module ScreenNode **/
-
 let screenSizeVec, viewportVec;
 
 /**
  * This node provides a collection of screen related metrics.
- * Depending on {@link module:ScreenNode~ScreenNode#scope}, the nodes can represent
+ * Depending on {@link ScreenNode#scope}, the nodes can represent
  * resolution or viewport data as well as fragment or uv coordinates.
  *
  * @augments Node
@@ -49,7 +47,7 @@ class ScreenNode extends Node {
 		/**
 		 * This flag can be used for type testing.
 		 *
-		 * @type {Boolean}
+		 * @type {boolean}
 		 * @readonly
 		 * @default true
 		 */
@@ -193,6 +191,7 @@ export default ScreenNode;
 /**
  * TSL object that represents normalized screen coordinates, unitless in `[0, 1]`.
  *
+ * @tsl
  * @type {ScreenNode<vec2>}
  */
 export const screenUV = /*@__PURE__*/ nodeImmutable( ScreenNode, ScreenNode.UV );
@@ -200,6 +199,7 @@ export const screenUV = /*@__PURE__*/ nodeImmutable( ScreenNode, ScreenNode.UV )
 /**
  * TSL object that represents the screen resolution in physical pixel units.
  *
+ * @tsl
  * @type {ScreenNode<vec2>}
  */
 export const screenSize = /*@__PURE__*/ nodeImmutable( ScreenNode, ScreenNode.SIZE );
@@ -207,6 +207,7 @@ export const screenSize = /*@__PURE__*/ nodeImmutable( ScreenNode, ScreenNode.SI
 /**
  * TSL object that represents the current `x`/`y` pixel position on the screen in physical pixel units.
  *
+ * @tsl
  * @type {ScreenNode<vec2>}
  */
 export const screenCoordinate = /*@__PURE__*/ nodeImmutable( ScreenNode, ScreenNode.COORDINATE );
@@ -216,6 +217,7 @@ export const screenCoordinate = /*@__PURE__*/ nodeImmutable( ScreenNode, ScreenN
 /**
  * TSL object that represents the viewport rectangle as `x`, `y`, `width` and `height` in physical pixel units.
  *
+ * @tsl
  * @type {ScreenNode<vec4>}
  */
 export const viewport = /*@__PURE__*/ nodeImmutable( ScreenNode, ScreenNode.VIEWPORT );
@@ -223,6 +225,7 @@ export const viewport = /*@__PURE__*/ nodeImmutable( ScreenNode, ScreenNode.VIEW
 /**
  * TSL object that represents the viewport resolution in physical pixel units.
  *
+ * @tsl
  * @type {ScreenNode<vec2>}
  */
 export const viewportSize = viewport.zw;
@@ -230,6 +233,7 @@ export const viewportSize = viewport.zw;
 /**
  * TSL object that represents the current `x`/`y` pixel position on the viewport in physical pixel units.
  *
+ * @tsl
  * @type {ScreenNode<vec2>}
  */
 export const viewportCoordinate = /*@__PURE__*/ screenCoordinate.sub( viewport.xy );
@@ -237,6 +241,7 @@ export const viewportCoordinate = /*@__PURE__*/ screenCoordinate.sub( viewport.x
 /**
  * TSL object that represents normalized viewport coordinates, unitless in `[0, 1]`.
  *
+ * @tsl
  * @type {ScreenNode<vec2>}
  */
 export const viewportUV = /*@__PURE__*/ viewportCoordinate.div( viewportSize );
@@ -248,29 +253,33 @@ export const viewportUV = /*@__PURE__*/ viewportCoordinate.div( viewportSize );
  */
 export const viewportResolution = /*@__PURE__*/ ( Fn( () => { // @deprecated, r169
 
-	console.warn( 'TSL.ViewportNode: "viewportResolution" is deprecated. Use "screenSize" instead.' );
+	console.warn( 'THREE.TSL: "viewportResolution" is deprecated. Use "screenSize" instead.' );
 
 	return screenSize;
 
 }, 'vec2' ).once() )();
 
 /**
+ * @tsl
  * @deprecated since r168. Use {@link screenUV} instead.
+ * @type {Node<vec2>}
  */
 export const viewportTopLeft = /*@__PURE__*/ ( Fn( () => { // @deprecated, r168
 
-	console.warn( 'TSL.ViewportNode: "viewportTopLeft" is deprecated. Use "screenUV" instead.' );
+	console.warn( 'THREE.TSL: "viewportTopLeft" is deprecated. Use "screenUV" instead.' );
 
 	return screenUV;
 
 }, 'vec2' ).once() )();
 
 /**
+ * @tsl
  * @deprecated since r168. Use `screenUV.flipY()` instead.
+ * @type {Node<vec2>}
  */
 export const viewportBottomLeft = /*@__PURE__*/ ( Fn( () => { // @deprecated, r168
 
-	console.warn( 'TSL.ViewportNode: "viewportBottomLeft" is deprecated. Use "screenUV.flipY()" instead.' );
+	console.warn( 'THREE.TSL: "viewportBottomLeft" is deprecated. Use "screenUV.flipY()" instead.' );
 
 	return screenUV.flipY();
 

package/src/nodes/display/ToneMappingFunctions.js

@@ -3,12 +3,11 @@ import { select } from '../math/ConditionalNode.js';
 import { clamp, log2, max, min, pow, mix } from '../math/MathNode.js';
 import { mul, sub, div } from '../math/OperatorNode.js';
 
-/** @module ToneMappingFunctions **/
-
 /**
  * Linear tone mapping, exposure only.
  *
- * @method
+ * @tsl
+ * @function
  * @param {Node<vec3>} color - The color that should be tone mapped.
  * @param {Node<float>} exposure - The exposure.
  * @return {Node<vec3>} The tone mapped color.
@@ -31,7 +30,8 @@ export const linearToneMapping = /*@__PURE__*/ Fn( ( [ color, exposure ] ) => {
  *
  * Reference: {@link https://www.cs.utah.edu/docs/techreports/2002/pdf/UUCS-02-001.pdf}
  *
- * @method
+ * @tsl
+ * @function
  * @param {Node<vec3>} color - The color that should be tone mapped.
  * @param {Node<float>} exposure - The exposure.
  * @return {Node<vec3>} The tone mapped color.
@@ -56,7 +56,8 @@ export const reinhardToneMapping = /*@__PURE__*/ Fn( ( [ color, exposure ] ) =>
  *
  * Reference: {@link http://filmicworlds.com/blog/filmic-tonemapping-operators/}
  *
- * @method
+ * @tsl
+ * @function
  * @param {Node<vec3>} color - The color that should be tone mapped.
  * @param {Node<float>} exposure - The exposure.
  * @return {Node<vec3>} The tone mapped color.
@@ -97,7 +98,8 @@ const RRTAndODTFit = /*@__PURE__*/ Fn( ( [ color ] ) => {
  *
  * Reference: {@link https://github.com/selfshadow/ltc_code/blob/master/webgl/shaders/ltc/ltc_blit.fs}
  *
- * @method
+ * @tsl
+ * @function
  * @param {Node<vec3>} color - The color that should be tone mapped.
  * @param {Node<float>} exposure - The exposure.
  * @return {Node<vec3>} The tone mapped color.
@@ -155,7 +157,8 @@ const agxDefaultContrastApprox = /*@__PURE__*/ Fn( ( [ x_immutable ] ) => {
 /**
  * AgX tone mapping.
  *
- * @method
+ * @tsl
+ * @function
  * @param {Node<vec3>} color - The color that should be tone mapped.
  * @param {Node<float>} exposure - The exposure.
  * @return {Node<vec3>} The tone mapped color.
@@ -196,7 +199,8 @@ export const agxToneMapping = /*@__PURE__*/ Fn( ( [ color, exposure ] ) => {
  *
  * Reference: {@link https://modelviewer.dev/examples/tone-mapping}
  *
- * @method
+ * @tsl
+ * @function
  * @param {Node<vec3>} color - The color that should be tone mapped.
  * @param {Node<float>} exposure - The exposure.
  * @return {Node<vec3>} The tone mapped color.