@needle-tools/three 0.169.20-experimental.0 → 0.183.2-canary.0

package/examples/jsm/shaders/SMAAShader.js

@@ -5,9 +5,20 @@ import {
 /**
  * WebGL port of Subpixel Morphological Antialiasing (SMAA) v2.8
  * Preset: SMAA 1x Medium (with color edge detection)
- * https://github.com/iryoku/smaa/releases/tag/v2.8
+ *
+ * References:
+ * - {@link https://github.com/iryoku/smaa/releases/tag/v2.8}
+ *
+ * @module SMAAShader
+ * @three_import import { SMAAShader } from 'three/addons/shaders/SMAAShader.js';
  */
 
+/**
+ * SMAA Edges shader.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
+ */
 const SMAAEdgesShader = {
 
 	name: 'SMAAEdgesShader',
@@ -115,6 +126,12 @@ const SMAAEdgesShader = {
 
 };
 
+/**
+ * SMAA Weights shader.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
+ */
 const SMAAWeightsShader = {
 
 	name: 'SMAAWeightsShader',
@@ -371,6 +388,12 @@ const SMAAWeightsShader = {
 
 };
 
+/**
+ * SMAA Blend shader.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
+ */
 const SMAABlendShader = {
 
 	name: 'SMAABlendShader',

package/examples/jsm/shaders/SSAOShader.js

@@ -4,12 +4,21 @@ import {
 } from 'three';
 
 /**
- * References:
- * http://john-chapman-graphics.blogspot.com/2013/01/ssao-tutorial.html
- * https://learnopengl.com/Advanced-Lighting/SSAO
- * https://github.com/McNopper/OpenGL/blob/master/Example28/shader/ssao.frag.glsl
+ * @module SSAOShader
+ * @three_import import { SSAOShader } from 'three/addons/shaders/SSAOShader.js';
  */
 
+/**
+ * SSAO shader.
+ *
+ * References:
+ * - {@link http://john-chapman-graphics.blogspot.com/2013/01/ssao-tutorial.html}
+ * - {@link https://learnopengl.com/Advanced-Lighting/SSAO}
+ * - {@link https://github.com/McNopper/OpenGL/blob/master/Example28/shader/ssao.frag.glsl}
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
+ */
 const SSAOShader = {
 
 	name: 'SSAOShader',
@@ -70,6 +79,16 @@ const SSAOShader = {
 
 		#include <packing>
 
+		#ifdef USE_REVERSED_DEPTH_BUFFER
+
+			const float depthThreshold = 0.0;
+
+		#else
+
+			const float depthThreshold = 1.0;
+
+		#endif
+
 		float getDepth( const in vec2 screenPosition ) {
 
 			return texture2D( tDepth, screenPosition ).x;
@@ -128,10 +147,10 @@ const SSAOShader = {
 
 			float depth = getDepth( vUv );
 
-			if ( depth == 1.0 ) {
+			if ( depth == depthThreshold ) {
 
 				gl_FragColor = vec4( 1.0 ); // don't influence background
-				
+
 			} else {
 
 				float viewZ = getViewZ( depth );
@@ -182,6 +201,12 @@ const SSAOShader = {
 
 };
 
+/**
+ * SSAO depth shader.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
+ */
 const SSAODepthShader = {
 
 	name: 'SSAODepthShader',
@@ -245,6 +270,12 @@ const SSAODepthShader = {
 
 };
 
+/**
+ * SSAO blur shader.
+ *
+ * @constant
+ * @type {Object}
+ */
 const SSAOBlurShader = {
 
 	name: 'SSAOBlurShader',

package/examples/jsm/shaders/SSRShader.js

@@ -2,11 +2,24 @@ 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)](https://lettier.github.io/3d-game-shaders-for-beginners/screen-space-reflection.html).
+ *
+ * @module SSRShader
+ * @three_import import * as SSRShader from 'three/addons/shaders/SSRShader.js';
  */
 
+/**
+ * SSR shader.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
+ */
 const SSRShader = {
 
 	name: 'SSRShader',
@@ -83,7 +96,7 @@ const SSRShader = {
 			float x0=point.x,y0=point.y,z0=point.z;
 			float x=planePoint.x,y=planePoint.y,z=planePoint.z;
 			float d=-(a*x+b*y+c*z);
-			float distance=(a*x0+b*y0+c*z0+d)/sqrt(a*a+b*b+c*c);
+			float distance=a*x0+b*y0+c*z0+d;
 			return distance;
 		}
 		float getDepth( const in vec2 uv ) {
@@ -157,17 +170,17 @@ const SSRShader = {
 			#endif
 			d1=viewPositionToXY(d1viewPosition);
 
-			float totalLen=length(d1-d0);
 			float xLen=d1.x-d0.x;
 			float yLen=d1.y-d0.y;
 			float totalStep=max(abs(xLen),abs(yLen));
 			float xSpan=xLen/totalStep;
 			float ySpan=yLen/totalStep;
-			for(float i=0.;i<float(MAX_STEP);i++){
+			float sStep=1./totalStep;
+			float s=sStep; // start at sStep since loop starts at i=1
+			for(float i=1.;i<float(MAX_STEP);i++){
 				if(i>=totalStep) break;
 				vec2 xy=vec2(d0.x+i*xSpan,d0.y+i*ySpan);
 				if(xy.x<0.||xy.x>resolution.x||xy.y<0.||xy.y>resolution.y) break;
-				float s=length(xy-d0)/totalLen;
 				vec2 uv=xy/resolution;
 
 				float d = getDepth(uv);
@@ -208,7 +221,7 @@ const SSRShader = {
 
 					if(hit){
 						vec3 vN=getViewNormal( uv );
-						if(dot(viewReflectDir,vN)>=0.) continue;
+						if(dot(viewReflectDir,vN)>=0.) break; // treat backfaces as opaque
 						float distance=pointPlaneDistance(vP,viewPosition,viewNormal);
 						if(distance>maxDistance) break;
 						float op=opacity;
@@ -227,12 +240,19 @@ const SSRShader = {
 						break;
 					}
 				}
+				s+=sStep;
 			}
 		}
 	`
 
 };
 
+/**
+ * SSR Depth shader.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
+ */
 const SSRDepthShader = {
 
 	name: 'SSRDepthShader',
@@ -302,6 +322,12 @@ const SSRDepthShader = {
 
 };
 
+/**
+ * SSR Blur shader.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
+ */
 const SSRBlurShader = {
 
 	name: 'SSRBlurShader',

package/examples/jsm/shaders/SepiaShader.js

@@ -1,9 +1,14 @@
 /**
- * Sepia tone shader
- * based on glfx.js sepia shader
- * https://github.com/evanw/glfx.js
+ * @module SepiaShader
+ * @three_import import { SepiaShader } from 'three/addons/shaders/SepiaShader.js';
  */
 
+/**
+ * Sepia tone shader based on [glfx.js sepia shader](https://github.com/evanw/glfx.js).
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
+ */
 const SepiaShader = {
 
 	name: 'SepiaShader',

package/examples/jsm/shaders/SobelOperatorShader.js

@@ -3,12 +3,18 @@ import {
 } from 'three';
 
 /**
- * Sobel Edge Detection (see https://youtu.be/uihBwtPIBxM)
+ * @module SobelOperatorShader
+ * @three_import import { SobelOperatorShader } from 'three/addons/shaders/SobelOperatorShader.js';
+ */
+
+/**
+ * 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',
@@ -79,7 +85,7 @@ const SobelOperatorShader = {
 				Gy[0][1] * tx0y1 + Gy[1][1] * tx1y1 + Gy[2][1] * tx2y1 +
 				Gy[0][2] * tx0y2 + Gy[1][2] * tx1y2 + Gy[2][2] * tx2y2;
 
-		// magnitute of the total gradient
+		// magnitude of the total gradient
 
 			float G = sqrt( ( valueGx * valueGx ) + ( valueGy * valueGy ) );
 

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,19 @@ 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
+ * @three_import import { SubsurfaceScatteringShader } from 'three/addons/shaders/SubsurfaceScatteringShader.js';
+ */
+
+/**
+ * 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/)
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
+ */
 const SubsurfaceScatteringShader = {
 
 	name: 'SubsurfaceScatteringShader',

package/examples/jsm/shaders/TechnicolorShader.js

@@ -1,10 +1,16 @@
 /**
- * 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
+ * @module TriangleBlurShader
+ * @three_import import { TriangleBlurShader } from 'three/addons/shaders/TriangleBlurShader.js';
  */
 
+/**
+ * Simulates the look of the two-strip technicolor process popular in early 20th century films.
+ * 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,22 @@ import {
 } from 'three';
 
 /**
- * Currently contains:
+ * Collection of toon shaders.
  *
- *	toon1
- *	toon2
- *	hatching
- *	dotted
+ * @module TriangleBlurShader
+ * @three_import import * as ToonShader from 'three/addons/shaders/ToonShader.js';
  */
 
+/**
+ * Toon1 shader.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
+ */
 const ToonShader1 = {
 
+	name: 'ToonShader1',
+
 	uniforms: {
 
 		'uDirLightPos': { value: new Vector3() },
@@ -85,7 +91,12 @@ const ToonShader1 = {
 		}`
 
 };
-
+/**
+ * Toon2 shader.
+ *
+ * @constant
+ * @type {Object}
+ */
 const ToonShader2 = {
 
 	uniforms: {
@@ -154,6 +165,12 @@ const ToonShader2 = {
 
 };
 
+/**
+ * Toon Hatching shader.
+ *
+ * @constant
+ * @type {Object}
+ */
 const ToonShaderHatching = {
 
 	uniforms: {
@@ -250,6 +267,12 @@ const ToonShaderHatching = {
 
 };
 
+/**
+ * Toon Dotted shader.
+ *
+ * @constant
+ * @type {Object}
+ */
 const ToonShaderDotted = {
 
 	uniforms: {

package/examples/jsm/shaders/TriangleBlurShader.js

@@ -3,15 +3,20 @@ import {
 } from 'three';
 
 /**
- * Triangle blur shader
- * based on glfx.js triangle blur shader
- * https://github.com/evanw/glfx.js
+ * @module TriangleBlurShader
+ * @three_import import { TriangleBlurShader } from 'three/addons/shaders/TriangleBlurShader.js';
+ */
+
+/**
+ * Triangle blur shader based on [glfx.js triangle blur shader](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,14 @@
 /**
- * Unpack RGBA depth shader
- * - show RGBA encoded depth as monochrome color
+ * @module UnpackDepthRGBAShader
+ * @three_import import { UnpackDepthRGBAShader } from 'three/addons/shaders/UnpackDepthRGBAShader.js';
  */
 
+/**
+ * Depth visualization shader that shows depth values as monochrome color.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
+ */
 const UnpackDepthRGBAShader = {
 
 	name: 'UnpackDepthRGBAShader',
@@ -33,12 +39,19 @@ const UnpackDepthRGBAShader = {
 
 		varying vec2 vUv;
 
-		#include <packing>
-
 		void main() {
 
-			float depth = 1.0 - unpackRGBAToDepth( texture2D( tDiffuse, vUv ) );
-			gl_FragColor = vec4( vec3( depth ), opacity );
+			float depth = texture2D( tDiffuse, vUv ).r;
+
+			#ifdef USE_REVERSED_DEPTH_BUFFER
+
+				gl_FragColor = vec4( vec3( depth ), opacity );
+
+			#else
+
+				gl_FragColor = vec4( vec3( 1.0 - depth ), opacity );
+
+			#endif
 
 		}`
 

package/examples/jsm/shaders/VelocityShader.js

@@ -5,9 +5,16 @@ import {
 } from 'three';
 
 /**
- * Mesh Velocity Shader @bhouston
+ * @module VelocityShader
+ * @three_import import { VelocityShader } from 'three/addons/shaders/VelocityShader.js';
  */
 
+/**
+ * Mesh velocity shader by @bhouston.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
+ */
 const VelocityShader = {
 
 	name: 'VelocityShader',

package/examples/jsm/shaders/VerticalBlurShader.js

@@ -1,12 +1,19 @@
+/**
+ * @module VerticalBlurShader
+ * @three_import import { VerticalBlurShader } from 'three/addons/shaders/VerticalBlurShader.js';
+ */
+
 /**
  * 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,8 @@
+/**
+ * @module VerticalTiltShiftShader
+ * @three_import import { VerticalTiltShiftShader } from 'three/addons/shaders/VerticalTiltShiftShader.js';
+ */
+
 /**
  * Simple fake tilt-shift effect, modulating two pass Gaussian blur (see above) by vertical position
  *
@@ -5,8 +10,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,14 @@
 /**
- * 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
+ * @module VignetteShader
+ * @three_import import { VignetteShader } from 'three/addons/shaders/VignetteShader.js';
  */
 
+/**
+ * Based on [PaintEffect postprocess from ro.me](https://github.com/dataarts/3-dreams-of-black/blob/master/deploy/js/effects/PaintEffect.js).
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
+ */
 const VignetteShader = {
 
 	name: 'VignetteShader',

package/examples/jsm/shaders/VolumeShader.js

@@ -3,14 +3,23 @@ import {
 	Vector3
 } from 'three';
 
+/**
+ * @module VolumeShader
+ * @three_import import { VolumeRenderShader1 } from 'three/addons/shaders/VolumeShader.js';
+ */
+
 /**
  * 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 },
@@ -257,7 +266,7 @@ const VolumeRenderShader1 = {
 						// note: could allow multiple lights
 						for (int i=0; i<1; i++)
 						{
-								 // Get light direction (make sure to prevent zero devision)
+								 // Get light direction (make sure to prevent zero division)
 								vec3 L = normalize(view_ray);	//lightDirs[i];
 								float lightEnabled = float( length(L) > 0.0 );
 								L = normalize(L + (1.0 - lightEnabled));

package/examples/jsm/shaders/WaterRefractionShader.js

@@ -1,3 +1,14 @@
+/**
+ * @module WaterRefractionShader
+ * @three_import import { WaterRefractionShader } from 'three/addons/shaders/WaterRefractionShader.js';
+ */
+
+/**
+ * Basic water refraction shader.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
+ */
 const WaterRefractionShader = {
 
 	name: 'WaterRefractionShader',

package/examples/jsm/textures/FlakesTexture.js

@@ -1,5 +1,19 @@
+/**
+ * Utility class for generating a flakes texture image. This image might be used
+ * as a normal map to produce a car paint like effect.
+ *
+ * @three_import import { FlakesTexture } from 'three/addons/textures/FlakesTexture.js';
+ */
 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' );