@plastic-software/three 0.174.0 → 0.175.0

package/examples/jsm/renderers/SVGRenderer.js

@@ -15,22 +15,66 @@ import {
 	RenderableSprite
 } from '../renderers/Projector.js';
 
+/**
+ * Can be used to wrap SVG elements into a 3D object.
+ *
+ * @augments Object3D
+ */
 class SVGObject extends Object3D {
 
+	/**
+	 * Constructs a new SVG object.
+	 *
+	 * @param {SVGElement} node - The SVG element.
+	 */
 	constructor( node ) {
 
 		super();
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isSVGObject = true;
 
+		/**
+		 * This SVG element.
+		 *
+		 * @type {SVGElement}
+		 */
 		this.node = node;
 
 	}
 
 }
 
+/**
+ * This renderer an be used to render geometric data using SVG. The produced vector
+ * graphics are particular useful in the following use cases:
+ *
+ * - Animated logos or icons.
+ * - Interactive 2D/3D diagrams or graphs.
+ * - Interactive maps.
+ * - Complex or animated user interfaces.
+ *
+ * `SVGRenderer` has various advantages. It produces crystal-clear and sharp output which
+ * is independent of the actual viewport resolution.SVG elements can be styled via CSS.
+ * And they have good accessibility since it's possible to add metadata like title or description
+ * (useful for search engines or screen readers).
+ *
+ * There are, however, some important limitations:
+ * - No advanced shading.
+ * - No texture support.
+ * - No shadow support.
+ */
 class SVGRenderer {
 
+	/**
+	 * Constructs a new SVG renderer.
+	 */
 	constructor() {
 
 		let _renderData, _elements, _lights,
@@ -70,16 +114,60 @@ class SVGRenderer {
 			_projector = new Projector(),
 			_svg = document.createElementNS( 'http://www.w3.org/2000/svg', 'svg' );
 
+		/**
+		 * The DOM where the renderer appends its child-elements.
+		 *
+		 * @type {DOMElement}
+		 */
 		this.domElement = _svg;
 
+		/**
+		 * Whether to automatically perform a clear before a render call or not.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.autoClear = true;
+
+		/**
+		 * Whether to sort 3D objects or not.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.sortObjects = true;
+
+		/**
+		 * Whether to sort elements or not.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.sortElements = true;
 
+		/**
+		 * Number of fractional pixels to enlarge polygons in order to
+		 * prevent anti-aliasing gaps. Range is `[0,1]`.
+		 *
+		 * @type {number}
+		 * @default 0.5
+		 */
 		this.overdraw = 0.5;
 
+		/**
+		 * The output color space.
+		 *
+		 * @type {(SRGBColorSpace|LinearSRGBColorSpace)}
+		 * @default SRGBColorSpace
+		 */
 		this.outputColorSpace = SRGBColorSpace;
 
+		/**
+		 * Provides information about the number of
+		 * rendered vertices and faces.
+		 *
+		 * @type {Object}
+		 */
 		this.info = {
 
 			render: {
@@ -91,6 +179,12 @@ class SVGRenderer {
 
 		};
 
+		/**
+		 * Sets the render quality. Setting to `high` means This value indicates that the browser
+		 * tries to improve the SVG quality over rendering speed and geometric precision.
+		 *
+		 * @param {('low'|'high')} quality - The quality.
+		 */
 		this.setQuality = function ( quality ) {
 
 			switch ( quality ) {
@@ -102,6 +196,11 @@ class SVGRenderer {
 
 		};
 
+		/**
+		 * Sets the clear color.
+		 *
+		 * @param {(number|Color|string)} color - The clear color to set.
+		 */
 		this.setClearColor = function ( color ) {
 
 			_clearColor.set( color );
@@ -110,6 +209,12 @@ class SVGRenderer {
 
 		this.setPixelRatio = function () {};
 
+		/**
+		 * Resizes the renderer to the given width and height.
+		 *
+		 * @param {number} width - The width of the renderer.
+		 * @param {number} height - The height of the renderer.
+		 */
 		this.setSize = function ( width, height ) {
 
 			_svgWidth = width; _svgHeight = height;
@@ -124,6 +229,11 @@ class SVGRenderer {
 
 		};
 
+		/**
+		 * Returns an object containing the width and height of the renderer.
+		 *
+		 * @return {{width:number,height:number}} The size of the renderer.
+		 */
 		this.getSize = function () {
 
 			return {
@@ -133,6 +243,11 @@ class SVGRenderer {
 
 		};
 
+		/**
+		 * Sets the precision of the data used to create a paths.
+		 *
+		 * @param {number} precision - The precision to set.
+		 */
 		this.setPrecision = function ( precision ) {
 
 			_precision = precision;
@@ -157,6 +272,9 @@ class SVGRenderer {
 
 		}
 
+		/**
+		 * Performs a manual clear with the defined clear color.
+		 */
 		this.clear = function () {
 
 			removeChildNodes();
@@ -164,6 +282,12 @@ class SVGRenderer {
 
 		};
 
+		/**
+		 * Renders the given scene using the given camera.
+		 *
+		 * @param {Object3D} scene - A scene or any other type of 3D object.
+		 * @param {Camera} camera - The camera.
+		 */
 		this.render = function ( scene, camera ) {
 
 			if ( camera instanceof Camera === false ) {

package/examples/jsm/shaders/ACESFilmicToneMappingShader.js

@@ -1,11 +1,15 @@
+/** @module ACESFilmicToneMappingShader */
+
 /**
- * ACES Filmic Tone Mapping Shader by Stephen Hill
- * source: https://github.com/selfshadow/ltc_code/blob/master/webgl/shaders/ltc/ltc_blit.fs
+ * ACES Filmic Tone Mapping Shader by Stephen Hill.
+ * Reference: [ltc_blit.fs]{@link https://github.com/selfshadow/ltc_code/blob/master/webgl/shaders/ltc/ltc_blit.fs}
+ *
+ * This implementation of ACES is modified to accommodate a brighter viewing environment.
+ * The scale factor of 1/0.6 is subjective. See discussion in #19621.
  *
- * this implementation of ACES is modified to accommodate a brighter viewing environment.
- * the scale factor of 1/0.6 is subjective. see discussion in #19621.
+ * @constant
+ * @type {ShaderMaterial~Shader}
  */
-
 const ACESFilmicToneMappingShader = {
 
 	name: 'ACESFilmicToneMappingShader',

package/examples/jsm/shaders/AfterimageShader.js

@@ -1,9 +1,11 @@
+/** @module AfterimageShader */
+
 /**
- * Afterimage shader
- * I created this effect inspired by a demo on codepen:
- * https://codepen.io/brunoimbrizi/pen/MoRJaN?page=1&
+ * Inspired by [Three.js FBO motion trails]{@link https://codepen.io/brunoimbrizi/pen/MoRJaN?page=1&}.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
  */
-
 const AfterimageShader = {
 
 	name: 'AfterimageShader',

package/examples/jsm/shaders/BasicShader.js

@@ -1,7 +1,11 @@
+/** @module BasicShader */
+
 /**
- * Simple test shader
+ * Simple shader for testing.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
  */
-
 const BasicShader = {
 
 	name: 'BasicShader',

package/examples/jsm/shaders/BleachBypassShader.js

@@ -1,9 +1,13 @@
+
+/** @module BleachBypassShader */
+
 /**
- * Bleach bypass shader [http://en.wikipedia.org/wiki/Bleach_bypass]
- * - based on Nvidia example
- * http://developer.download.nvidia.com/shaderlibrary/webpages/shader_library.html#post_bleach_bypass
+ * Bleach bypass shader [http://en.wikipedia.org/wiki/Bleach_bypass] based on
+ * [Nvidia Shader library]{@link http://developer.download.nvidia.com/shaderlibrary/webpages/shader_library.html#post_bleach_bypass}.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
  */
-
 const BleachBypassShader = {
 
 	name: 'BleachBypassShader',

package/examples/jsm/shaders/BlendShader.js

@@ -1,7 +1,11 @@
+/** @module BlendShader */
+
 /**
- * Blend two textures
+ * Blends two textures.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
  */
-
 const BlendShader = {
 
 	name: 'BlendShader',

package/examples/jsm/shaders/BokehShader.js

@@ -1,9 +1,12 @@
+/** @module BokehShader */
+
 /**
- * Depth-of-field shader with bokeh
- * ported from GLSL shader by Martins Upitis
- * http://artmartinsh.blogspot.com/2010/02/glsl-lens-blur-filter-with-bokeh.html
+ * Depth-of-field shader with bokeh ported from
+ * [GLSL shader by Martins Upitis]{@link http://artmartinsh.blogspot.com/2010/02/glsl-lens-blur-filter-with-bokeh.html}.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
  */
-
 const BokehShader = {
 
 	name: 'BokehShader',

package/examples/jsm/shaders/BokehShader2.js

@@ -2,12 +2,16 @@ import {
 	Vector2
 } from 'three';
 
+/** @module BokehShader2 */
+
 /**
- * Depth-of-field shader with bokeh
- * ported from GLSL shader by Martins Upitis
- * http://blenderartists.org/forum/showthread.php?237488-GLSL-depth-of-field-with-bokeh-v2-4-(update)
+ * Depth-of-field shader with bokeh ported from
+ * [GLSL shader by Martins Upitis]{@link http://blenderartists.org/forum/showthread.php?237488-GLSL-depth-of-field-with-bokeh-v2-4-(update)}.
  *
  * Requires #define RINGS and SAMPLES integers
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
  */
 const BokehShader = {
 

package/examples/jsm/shaders/BrightnessContrastShader.js

@@ -1,10 +1,13 @@
+/** @module BrightnessContrastShader */
+
 /**
- * Brightness and contrast adjustment
- * https://github.com/evanw/glfx.js
- * brightness: -1 to 1 (-1 is solid black, 0 is no change, and 1 is solid white)
- * contrast: -1 to 1 (-1 is solid gray, 0 is no change, and 1 is maximum contrast)
+ * Brightness and contrast adjustment {@link https://github.com/evanw/glfx.js}.
+ * Brightness: -1 to 1 (-1 is solid black, 0 is no change, and 1 is solid white)
+ * Contrast: -1 to 1 (-1 is solid gray, 0 is no change, and 1 is maximum contrast)
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
  */
-
 const BrightnessContrastShader = {
 
 	name: 'BrightnessContrastShader',

package/examples/jsm/shaders/ColorCorrectionShader.js

@@ -2,10 +2,14 @@ import {
 	Vector3
 } from 'three';
 
+/** @module ColorCorrectionShader */
+
 /**
- * Color correction
+ * Color correction shader.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
  */
-
 const ColorCorrectionShader = {
 
 	name: 'ColorCorrectionShader',

package/examples/jsm/shaders/ColorifyShader.js

@@ -2,10 +2,14 @@ import {
 	Color
 } from 'three';
 
+/** @module ColorifyShader */
+
 /**
- * Colorify shader
+ * Colorify shader.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
  */
-
 const ColorifyShader = {
 
 	name: 'ColorifyShader',

package/examples/jsm/shaders/ConvolutionShader.js

@@ -2,11 +2,14 @@ import {
 	Vector2
 } from 'three';
 
+/** @module ConvolutionShader */
+
 /**
- * Convolution shader
- * ported from o3d sample to WebGL / GLSL
+ * Convolution shader ported from o3d sample to WebGL / GLSL.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
  */
-
 const ConvolutionShader = {
 
 	name: 'ConvolutionShader',
@@ -62,42 +65,7 @@ const ConvolutionShader = {
 
 			gl_FragColor = sum;
 
-		}`,
-
-	buildKernel: function ( sigma ) {
-
-		// We lop off the sqrt(2 * pi) * sigma term, since we're going to normalize anyway.
-
-		const kMaxKernelSize = 25;
-		let kernelSize = 2 * Math.ceil( sigma * 3.0 ) + 1;
-
-		if ( kernelSize > kMaxKernelSize ) kernelSize = kMaxKernelSize;
-
-		const halfWidth = ( kernelSize - 1 ) * 0.5;
-
-		const values = new Array( kernelSize );
-		let sum = 0.0;
-		for ( let i = 0; i < kernelSize; ++ i ) {
-
-			values[ i ] = gauss( i - halfWidth, sigma );
-			sum += values[ i ];
-
-		}
-
-		// normalize the kernel
-
-		for ( let i = 0; i < kernelSize; ++ i ) values[ i ] /= sum;
-
-		return values;
-
-	}
-
+		}`
 };
 
-function gauss( x, sigma ) {
-
-	return Math.exp( - ( x * x ) / ( 2.0 * sigma * sigma ) );
-
-}
-
 export { ConvolutionShader };

package/examples/jsm/shaders/CopyShader.js

@@ -1,7 +1,11 @@
+/** @module CopyShader */
+
 /**
- * Full-screen textured quad shader
+ * Full-screen copy shader pass.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
  */
-
 const CopyShader = {
 
 	name: 'CopyShader',

package/examples/jsm/shaders/DOFMipMapShader.js

@@ -1,9 +1,13 @@
+/** @module DOFMipMapShader */
+
 /**
- * Depth-of-field shader using mipmaps
- * - from Matt Handley @applmak
- * - requires power-of-2 sized render target with enabled mipmaps
+ * Depth-of-field shader using mipmaps from Matt Handley @applmak.
+ *
+ * Requires power-of-2 sized render target with enabled mipmaps.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
  */
-
 const DOFMipMapShader = {
 
 	name: 'DOFMipMapShader',

package/examples/jsm/shaders/DepthLimitedBlurShader.js

@@ -2,10 +2,16 @@ import {
 	Vector2
 } from 'three';
 
+/** @module DepthLimitedBlurShader */
+
 /**
  * TODO
+ *
+ * Used by {@link SAOPass}.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
  */
-
 const DepthLimitedBlurShader = {
 
 	name: 'DepthLimitedBlurShader',

package/examples/jsm/shaders/DigitalGlitch.js

@@ -1,15 +1,15 @@
+/** @module DigitalGlitch */
+
 /**
- * RGB Shift Shader
- * Shifts red and blue channels from center in opposite directions
- * Ported from http://kriss.cx/tom/2009/05/rgb-shift/
- * by Tom Butterworth / http://kriss.cx/tom/
+ * Digital glitch shader.
  *
- * amount: shift distance (1 is width of input)
- * angle: shift angle in radians
+ * @constant
+ * @type {ShaderMaterial~Shader}
  */
-
 const DigitalGlitch = {
 
+	name: 'DigitalGlitch',
+
 	uniforms: {
 
 		'tDiffuse': { value: null }, //diffuse texture

package/examples/jsm/shaders/DotScreenShader.js

@@ -2,12 +2,14 @@ import {
 	Vector2
 } from 'three';
 
+/** @module DotScreenShader */
+
 /**
- * Dot screen shader
- * based on glfx.js sepia shader
- * https://github.com/evanw/glfx.js
+ * Dot screen shader based on [glfx.js sepia shader]{@link https://github.com/evanw/glfx.js}.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
  */
-
 const DotScreenShader = {
 
 	name: 'DotScreenShader',

package/examples/jsm/shaders/ExposureShader.js

@@ -1,7 +1,11 @@
+/** @module ExposureShader */
+
 /**
- * Exposure shader
+ * TODO
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
  */
-
 const ExposureShader = {
 
 	name: 'ExposureShader',

package/examples/jsm/shaders/FXAAShader.js

@@ -2,6 +2,18 @@ import {
 	Vector2
 } from 'three';
 
+/** @module FXAAShader */
+
+/**
+ * FXAA algorithm from NVIDIA, C# implementation by Jasper Flick, GLSL port by Dave Hoskins.
+ *
+ * References:
+ * - {@link http://developer.download.nvidia.com/assets/gamedev/files/sdk/11/FXAA_WhitePaper.pdf}.
+ * - {@link https://catlikecoding.com/unity/tutorials/advanced-rendering/fxaa/}.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
+ */
 const FXAAShader = {
 
 	name: 'FXAAShader',
@@ -26,10 +38,6 @@ const FXAAShader = {
 
 	fragmentShader: /* glsl */`
 
-		// FXAA algorithm from NVIDIA, C# implementation by Jasper Flick, GLSL port by Dave Hoskins
-		// http://developer.download.nvidia.com/assets/gamedev/files/sdk/11/FXAA_WhitePaper.pdf
-		// https://catlikecoding.com/unity/tutorials/advanced-rendering/fxaa/
-
 		uniform sampler2D tDiffuse;
 		uniform vec2 resolution;
 		varying vec2 vUv;
@@ -138,7 +146,7 @@ const FXAAShader = {
 			float nGradient = abs( nLuminance - l.m );
 
 			e.pixelStep = e.isHorizontal ? texSize.y : texSize.x;
-			
+
 			if (pGradient < nGradient) {
 
 				e.pixelStep = -e.pixelStep;
@@ -218,7 +226,7 @@ const FXAAShader = {
 				nDistance = uv.x - nuv.x;
 
 			} else {
-				
+
 				pDistance = puv.y - uv.y;
 				nDistance = uv.y - nuv.y;
 
@@ -279,7 +287,7 @@ const FXAAShader = {
 		void main() {
 
 			gl_FragColor = ApplyFXAA( tDiffuse, resolution.xy, vUv );
-			
+
 		}`
 
 };

package/examples/jsm/shaders/FilmShader.js

@@ -1,3 +1,13 @@
+/** @module FilmShader */
+
+/**
+ * TODO
+ *
+ * Used by {@link FilmPass}.
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
+ */
 const FilmShader = {
 
 	name: 'FilmShader',

package/examples/jsm/shaders/FocusShader.js

@@ -1,9 +1,11 @@
+/** @module FocusShader */
+
 /**
- * Focus shader
- * based on PaintEffect postprocess from ro.me
- * http://code.google.com/p/3-dreams-of-black/source/browse/deploy/js/effects/PaintEffect.js
+ * Focus shader 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 FocusShader = {
 
 	name: 'FocusShader',

package/examples/jsm/shaders/FreiChenShader.js

@@ -2,13 +2,17 @@ import {
 	Vector2
 } from 'three';
 
+/** @module FreiChenShader */
+
 /**
- * Edge Detection Shader using Frei-Chen filter
- * Based on http://rastergrid.com/blog/2011/01/frei-chen-edge-detector
+ * Edge Detection Shader using Frei-Chen filter.
+ * Based on {@link http://rastergrid.com/blog/2011/01/frei-chen-edge-detector}.
  *
  * aspect: vec2 of (1/width, 1/height)
+ *
+ * @constant
+ * @type {ShaderMaterial~Shader}
  */
-
 const FreiChenShader = {
 
 	name: 'FreiChenShader',