@plastic-software/three 0.174.0 → 0.175.1

package/examples/jsm/shaders/SSRShader.js

@@ -2,11 +2,23 @@ import {
 	Matrix4,
 	Vector2
 } from 'three';
+
+
 /**
+ * A collection of shaders used for SSR.
+ *
  * References:
- * https://lettier.github.io/3d-game-shaders-for-beginners/screen-space-reflection.html
+ * - [3D Game Shaders For Beginners, Screen Space Reflection (SSR)]{@link https://lettier.github.io/3d-game-shaders-for-beginners/screen-space-reflection.html}.
+ *
+ * @module SSRShader
  */
 
+/**
+ * SSR shader.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
+ */
 const SSRShader = {
 
 	name: 'SSRShader',
@@ -233,6 +245,12 @@ const SSRShader = {
 
 };
 
+/**
+ * SSR Depth shader.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
+ */
 const SSRDepthShader = {
 
 	name: 'SSRDepthShader',
@@ -302,6 +320,12 @@ const SSRDepthShader = {
 
 };
 
+/**
+ * SSR Blur shader.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
+ */
 const SSRBlurShader = {
 
 	name: 'SSRBlurShader',

package/examples/jsm/shaders/SepiaShader.js

@@ -1,9 +1,11 @@
+/** @module SepiaShader */
+
 /**
- * Sepia tone shader
- * based on glfx.js sepia shader
- * https://github.com/evanw/glfx.js
+ * Sepia tone shader based on [glfx.js sepia shader]{@link https://github.com/evanw/glfx.js}.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
  */
-
 const SepiaShader = {
 
 	name: 'SepiaShader',

package/examples/jsm/shaders/SobelOperatorShader.js

@@ -2,13 +2,16 @@ import {
 	Vector2
 } from 'three';
 
+/** @module SobelOperatorShader */
+
 /**
- * Sobel Edge Detection (see https://youtu.be/uihBwtPIBxM)
+ * Sobel Edge Detection (see {@link https://youtu.be/uihBwtPIBxM}).
  *
  * As mentioned in the video the Sobel operator expects a grayscale image as input.
  *
+ * @constant
+ * @type {ShaderMaterial~Shader}
  */
-
 const SobelOperatorShader = {
 
 	name: 'SobelOperatorShader',

package/examples/jsm/shaders/SubsurfaceScatteringShader.js

@@ -5,14 +5,6 @@ import {
 	UniformsUtils
 } from 'three';
 
-/**
- * ------------------------------------------------------------------------------------------
- * Subsurface Scattering shader
- * Based on GDC 2011 – Approximating Translucency for a Fast, Cheap and Convincing Subsurface Scattering Look
- * https://colinbarrebrisebois.com/2011/03/07/gdc-2011-approximating-translucency-for-a-fast-cheap-and-convincing-subsurface-scattering-look/
- *------------------------------------------------------------------------------------------
- */
-
 function replaceAll( string, find, replace ) {
 
 	return string.split( find ).join( replace );
@@ -22,6 +14,16 @@ function replaceAll( string, find, replace ) {
 const meshphong_frag_head = ShaderChunk[ 'meshphong_frag' ].slice( 0, ShaderChunk[ 'meshphong_frag' ].indexOf( 'void main() {' ) );
 const meshphong_frag_body = ShaderChunk[ 'meshphong_frag' ].slice( ShaderChunk[ 'meshphong_frag' ].indexOf( 'void main() {' ) );
 
+/** @module SubsurfaceScatteringShader */
+
+/**
+ * Subsurface Scattering shader.
+ *
+ * Based on GDC 2011 – [Approximating Translucency for a Fast, Cheap and Convincing Subsurface Scattering Look]{@link https://colinbarrebrisebois.com/2011/03/07/gdc-2011-approximating-translucency-for-a-fast-cheap-and-convincing-subsurface-scattering-look/}
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
+ */
 const SubsurfaceScatteringShader = {
 
 	name: 'SubsurfaceScatteringShader',

package/examples/jsm/shaders/TechnicolorShader.js

@@ -1,10 +1,13 @@
+/** @module TriangleBlurShader */
+
 /**
- * Technicolor Shader
  * Simulates the look of the two-strip technicolor process popular in early 20th century films.
- * More historical info here: http://www.widescreenmuseum.com/oldcolor/technicolor1.htm
- * Demo here: http://charliehoey.com/technicolor_shader/shader_test.html
+ * More historical info here: {@link http://www.widescreenmuseum.com/oldcolor/technicolor1.htm}
+ * Demo here: {@link http://charliehoey.com/technicolor_shader/shader_test.html}
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
  */
-
 const TechnicolorShader = {
 
 	name: 'TechnicolorShader',

package/examples/jsm/shaders/ToonShader.js

@@ -4,16 +4,21 @@ import {
 } from 'three';
 
 /**
- * Currently contains:
+ * Collection of toon shaders.
  *
- *	toon1
- *	toon2
- *	hatching
- *	dotted
- */
+ * @module TriangleBlurShader
+ * */
 
+/**
+ * Toon1 shader.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
+ */
 const ToonShader1 = {
 
+	name: 'ToonShader1',
+
 	uniforms: {
 
 		'uDirLightPos': { value: new Vector3() },
@@ -85,7 +90,12 @@ const ToonShader1 = {
 		}`
 
 };
-
+/**
+ * Toon2 shader.
+ *
+ * @constant
+ * @type {Object}
+ */
 const ToonShader2 = {
 
 	uniforms: {
@@ -154,6 +164,12 @@ const ToonShader2 = {
 
 };
 
+/**
+ * Toon Hatching shader.
+ *
+ * @constant
+ * @type {Object}
+ */
 const ToonShaderHatching = {
 
 	uniforms: {
@@ -250,6 +266,12 @@ const ToonShaderHatching = {
 
 };
 
+/**
+ * Toon Dotted shader.
+ *
+ * @constant
+ * @type {Object}
+ */
 const ToonShaderDotted = {
 
 	uniforms: {

package/examples/jsm/shaders/TriangleBlurShader.js

@@ -2,16 +2,18 @@ import {
 	Vector2
 } from 'three';
 
+/** @module TriangleBlurShader */
+
 /**
- * Triangle blur shader
- * based on glfx.js triangle blur shader
- * https://github.com/evanw/glfx.js
+ * Triangle blur shader based on [glfx.js triangle blur shader]{@link https://github.com/evanw/glfx.js}.
  *
  * A basic blur filter, which convolves the image with a
  * pyramid filter. The pyramid filter is separable and is applied as two
  * perpendicular triangle filters.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
  */
-
 const TriangleBlurShader = {
 
 	name: 'TriangleBlurShader',

package/examples/jsm/shaders/UnpackDepthRGBAShader.js

@@ -1,8 +1,11 @@
+/** @module UnpackDepthRGBAShader */
+
 /**
- * Unpack RGBA depth shader
- * - show RGBA encoded depth as monochrome color
+ * Unpack RGBA depth shader that shows RGBA encoded depth as monochrome color.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
  */
-
 const UnpackDepthRGBAShader = {
 
 	name: 'UnpackDepthRGBAShader',

package/examples/jsm/shaders/VelocityShader.js

@@ -4,10 +4,14 @@ import {
 	Matrix4
 } from 'three';
 
+/** @module VelocityShader */
+
 /**
- * Mesh Velocity Shader @bhouston
+ * Mesh velocity shader by @bhouston.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
  */
-
 const VelocityShader = {
 
 	name: 'VelocityShader',

package/examples/jsm/shaders/VerticalBlurShader.js

@@ -1,12 +1,16 @@
+/** @module VerticalBlurShader */
+
 /**
  * Two pass Gaussian blur filter (horizontal and vertical blur shaders)
- * - see http://www.cake23.de/traveling-wavefronts-lit-up.html
+ * - see {@link http://www.cake23.de/traveling-wavefronts-lit-up.html}
  *
  * - 9 samples per pass
  * - standard deviation 2.7
  * - "h" and "v" parameters should be set to "1 / width" and "1 / height"
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
  */
-
 const VerticalBlurShader = {
 
 	name: 'VerticalBlurShader',

package/examples/jsm/shaders/VerticalTiltShiftShader.js

@@ -1,3 +1,5 @@
+/** @module VerticalTiltShiftShader */
+
 /**
  * Simple fake tilt-shift effect, modulating two pass Gaussian blur (see above) by vertical position
  *
@@ -5,8 +7,10 @@
  * - standard deviation 2.7
  * - "h" and "v" parameters should be set to "1 / width" and "1 / height"
  * - "r" parameter control where "focused" horizontal line lies
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
  */
-
 const VerticalTiltShiftShader = {
 
 	name: 'VerticalTiltShiftShader',

package/examples/jsm/shaders/VignetteShader.js

@@ -1,9 +1,11 @@
+/** @module VignetteShader */
+
 /**
- * Vignette shader
- * based on PaintEffect postprocess from ro.me
- * http://code.google.com/p/3-dreams-of-black/source/browse/deploy/js/effects/PaintEffect.js
+ * Based on [PaintEffect postprocess from ro.me]{@link http://code.google.com/p/3-dreams-of-black/source/browse/deploy/js/effects/PaintEffect.js}.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
  */
-
 const VignetteShader = {
 
 	name: 'VignetteShader',

package/examples/jsm/shaders/VolumeShader.js

@@ -3,14 +3,20 @@ import {
 	Vector3
 } from 'three';
 
+/** @module VolumeShader */
+
 /**
  * Shaders to render 3D volumes using raycasting.
  * The applied techniques are based on similar implementations in the Visvis and Vispy projects.
  * This is not the only approach, therefore it's marked 1.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
  */
-
 const VolumeRenderShader1 = {
 
+	name: 'VolumeRenderShader1',
+
 	uniforms: {
 		'u_size': { value: new Vector3( 1, 1, 1 ) },
 		'u_renderstyle': { value: 0 },

package/examples/jsm/shaders/WaterRefractionShader.js

@@ -1,3 +1,11 @@
+/** @module WaterRefractionShader */
+
+/**
+ * Basic water refraction shader.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
+ */
 const WaterRefractionShader = {
 
 	name: 'WaterRefractionShader',

package/examples/jsm/textures/FlakesTexture.js

@@ -1,5 +1,17 @@
+/**
+ * Utility class for generating a flakes texture image. This image might be used
+ * as a normal map to produce a car paint like effect.
+ */
 class FlakesTexture {
 
+	/**
+	 * Generates a new flakes texture image. The result is a canvas
+	 * that can be used as an input for {@link CanvasTexture}.
+	 *
+	 * @param {number} [width=512] - The width of the image.
+	 * @param {number} [height=512] - The height of the image.
+	 * @return {HTMLCanvasElement} The generated image.
+	 */
 	constructor( width = 512, height = 512 ) {
 
 		const canvas = document.createElement( 'canvas' );

package/examples/jsm/transpiler/Transpiler.js

@@ -1,12 +1,43 @@
+/**
+ * A class that transpiles shader code from one language into another.
+ *
+ * `Transpiler` can only be used to convert GLSL into TSL right now. It is intended
+ * to support developers when they want to migrate their custom materials from the
+ * current to the new node-based material system.
+ */
 class Transpiler {
 
+	/**
+	 * Constructs a new transpiler.
+	 *
+	 * @param {GLSLDecoder} decoder - The GLSL decoder.
+	 * @param {TSLEncoder} encoder - The TSL encoder.
+	 */
 	constructor( decoder, encoder ) {
 
+		/**
+		 * The GLSL decoder. This component parse GLSL and produces
+		 * a language-independent AST for further processing.
+		 *
+		 * @type {GLSLDecoder}
+		 */
 		this.decoder = decoder;
+
+		/**
+		 * The TSL encoder. It takes the AST and emits TSL code.
+		 *
+		 * @type {TSLEncoder}
+		 */
 		this.encoder = encoder;
 
 	}
 
+	/**
+	 * Parses the given GLSL source and returns TSL syntax.
+	 *
+	 * @param {string} source - The GLSL source.
+	 * @return {string} The TSL code.
+	 */
 	parse( source ) {
 
 		return this.encoder.emit( this.decoder.parse( source ) );

package/examples/jsm/tsl/display/AfterImageNode.js

@@ -41,7 +41,7 @@ class AfterImageNode extends TempNode {
 		 *
 		 * @type {TextureNode}
 		 */
-		this.textureNodeOld = texture();
+		this.textureNodeOld = texture( null );
 
 		/**
 		 * How quickly the after-image fades. A higher value means the after-image

package/examples/jsm/tsl/display/BloomNode.js

@@ -457,7 +457,7 @@ class BloomNode extends TempNode {
 
 		//
 
-		const colorTexture = texture();
+		const colorTexture = texture( null );
 		const gaussianCoefficients = uniformArray( coefficients );
 		const invSize = uniform( new Vector2() );
 		const direction = uniform( new Vector2( 0.5, 0.5 ) );

package/examples/jsm/tsl/display/PixelationPassNode.js

@@ -234,8 +234,8 @@ class PixelationPassNode extends PassNode {
 	 * @param {Scene} scene - The scene to render.
 	 * @param {Camera} camera - The camera to render the scene with.
 	 * @param {Node<float> | number} [pixelSize=6] - The pixel size.
-	 * @param {Node<float> | number} [normalEdgeStrength=03] - The normal edge strength.
-	 * @param {Node<float> | number} [depthEdgeStrength=03] - The depth edge strength.
+	 * @param {Node<float> | number} [normalEdgeStrength=0.3] - The normal edge strength.
+	 * @param {Node<float> | number} [depthEdgeStrength=0.4] - The depth edge strength.
 	 */
 	constructor( scene, camera, pixelSize = 6, normalEdgeStrength = 0.3, depthEdgeStrength = 0.4 ) {
 
@@ -324,8 +324,8 @@ class PixelationPassNode extends PassNode {
  * @param {Scene} scene - The scene to render.
  * @param {Camera} camera - The camera to render the scene with.
  * @param {Node<float> | number} [pixelSize=6] - The pixel size.
- * @param {Node<float> | number} [normalEdgeStrength=03] - The normal edge strength.
- * @param {Node<float> | number} [depthEdgeStrength=03] - The depth edge strength.
+ * @param {Node<float> | number} [normalEdgeStrength=0.3] - The normal edge strength.
+ * @param {Node<float> | number} [depthEdgeStrength=0.4] - The depth edge strength.
  * @returns {PixelationPassNode}
  */
 export const pixelationPass = ( scene, camera, pixelSize, normalEdgeStrength, depthEdgeStrength ) => nodeObject( new PixelationPassNode( scene, camera, pixelSize, normalEdgeStrength, depthEdgeStrength ) );

package/examples/jsm/tsl/display/SSRNode.js

@@ -98,7 +98,7 @@ class SSRNode extends TempNode {
 		this._ssrRenderTarget.texture.name = 'SSRNode.SSR';
 
 		/**
-		 * Controls how far a fragment can reflect
+		 * Controls how far a fragment can reflect.
 		 *
 		 *
 		 * @type {UniformNode<float>}

package/examples/jsm/tsl/lighting/TiledLightsNode.js

@@ -34,6 +34,13 @@ export const circleIntersectsAABB = /*@__PURE__*/ Fn( ( [ circleCenter, radius,
 const _vector3 = /*@__PURE__*/ new Vector3();
 const _size = /*@__PURE__*/ new Vector2();
 
+/**
+ * A custom version of `LightsNode` implementing tiled lighting. This node is used in
+ * {@link TiledLighting} to overwrite the renderer's default lighting with
+ * a custom implementation.
+ *
+ * @augments LightsNode
+ */
 class TiledLightsNode extends LightsNode {
 
 	static get type() {
@@ -42,6 +49,12 @@ class TiledLightsNode extends LightsNode {
 
 	}
 
+	/**
+	 * Constructs a new tiled lights node.
+	 *
+	 * @param {number} [maxLights=1024] - The maximum number of lights.
+	 * @param {number} [tileSize=32] - The tile size.
+	 */
 	constructor( maxLights = 1024, tileSize = 32 ) {
 
 		super();
@@ -49,7 +62,20 @@ class TiledLightsNode extends LightsNode {
 		this.materialLights = [];
 		this.tiledLights = [];
 
+		/**
+		 * The maximum number of lights.
+		 *
+		 * @type {number}
+		 * @default 1024
+		 */
 		this.maxLights = maxLights;
+
+		/**
+		 * The tile size.
+		 *
+		 * @type {number}
+		 * @default 32
+		 */
 		this.tileSize = tileSize;
 
 		this._bufferSize = null;
@@ -171,7 +197,7 @@ class TiledLightsNode extends LightsNode {
 		const tileOffset = element.div( stride );
 		const tileIndex = this._screenTileIndex.mul( int( 2 ) ).add( tileOffset );
 
-		return this._lightIndexes.element( tileIndex ).element( element.modInt( stride ) );
+		return this._lightIndexes.element( tileIndex ).element( element.mod( stride ) );
 
 	}
 
@@ -315,7 +341,7 @@ class TiledLightsNode extends LightsNode {
 			const tileOffset = elementIndex.div( stride );
 			const tileIndex = instanceIndex.mul( int( 2 ) ).add( tileOffset );
 
-			return lightIndexes.element( tileIndex ).element( elementIndex.modInt( stride ) );
+			return lightIndexes.element( tileIndex ).element( elementIndex.mod( stride ) );
 
 		};
 
@@ -326,7 +352,7 @@ class TiledLightsNode extends LightsNode {
 			const tiledBufferSize = bufferSize.clone().divideScalar( tileSize ).floor();
 
 			const tileScreen = vec2(
-				instanceIndex.modInt( tiledBufferSize.width ),
+				instanceIndex.mod( tiledBufferSize.width ),
 				instanceIndex.div( tiledBufferSize.width )
 			).mul( tileSize ).div( screenSize );
 

package/examples/jsm/tsl/math/Bayer.js

@@ -1,8 +1,21 @@
 import { TextureLoader } from 'three';
 import { Fn, int, ivec2, textureLoad } from 'three/tsl';
 
+/** @module Bayer */
+
 let bayer16Texture = null;
 
+/**
+ * This TSL function can be used to sample a Bayer16 texture which is a 16x16 texture with a Bayer Matrix pattern.
+ * It can be used for dithering effects but also as an alternative to blue-noise. When used with Ray Marching
+ * specifically in {@link VolumeNodeMaterial#offsetNode}, it reduces banding problem, thus being able to use
+ * fewer steps without affecting the visuals as much.
+ *
+ * @tsl
+ * @function
+ * @param {Node<vec2>} uv - The uv to sample the bayer16 texture.
+ * @return {Node<vec4>} The sampled bayer value.
+ */
 export const bayer16 = Fn( ( [ uv ] ) => {
 
 	if ( bayer16Texture === null ) {
@@ -13,6 +26,6 @@ export const bayer16 = Fn( ( [ uv ] ) => {
 
 	}
 
-	return textureLoad( bayer16Texture, ivec2( uv ).modInt( int( 16 ) ) );
+	return textureLoad( bayer16Texture, ivec2( uv ).mod( int( 16 ) ) );
 
 } );

package/examples/jsm/tsl/utils/Raymarching.js

@@ -1,5 +1,7 @@
 import { varying, vec4, modelWorldMatrixInverse, cameraPosition, positionGeometry, float, Fn, Loop, max, min, vec2, vec3 } from 'three/tsl';
 
+/** @module Raymarching */
+
 const hitBox = /*@__PURE__*/ Fn( ( { orig, dir } ) => {
 
 	const box_min = vec3( - 0.5 );
@@ -21,7 +23,8 @@ const hitBox = /*@__PURE__*/ Fn( ( { orig, dir } ) => {
 } );
 
 /**
- * Performs raymarching box-area using the specified number of steps and a callback function.
+ * TSL function for performing raymarching in a box-area using the specified number of steps
+ * and a callback function.
  *
  * ```js
  * RaymarchingBox( count, ( { positionRay } ) => {
@@ -33,7 +36,6 @@ const hitBox = /*@__PURE__*/ Fn( ( { orig, dir } ) => {
  * @function
  * @param {number|Node} steps - The number of steps for raymarching.
  * @param {Function|FunctionNode} callback - The callback function to execute at each step.
- * @returns {void}
  */
 export const RaymarchingBox = ( steps, callback ) => {