@plastic-software/three 0.174.0 → 0.175.0

package/examples/jsm/loaders/RGBMLoader.js

@@ -7,17 +7,53 @@ import {
 	DataUtils
 } from 'three';
 
+/**
+ * A loader for the RGBM HDR texture format.
+ *
+ * ```js
+ * const loader = new RGBMLoader();
+ * loader.setMaxRange( 16 );
+ *
+ * const texture = await loader.loadAsync( 'textures/memorial.png' );
+ * ```
+ *
+ * @augments DataTextureLoader
+ */
 class RGBMLoader extends DataTextureLoader {
 
+	/**
+	 * Constructs a new RGBM loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
+		/**
+		 * The texture type.
+		 *
+		 * @type {(HalfFloatType|FloatType)}
+		 * @default HalfFloatType
+		 */
 		this.type = HalfFloatType;
-		this.maxRange = 7; // more information about this property at https://iwasbeingirony.blogspot.com/2010/06/difference-between-rgbm-and-rgbd.html
+
+		/**
+		 * More information about this property at [The difference between RGBM and RGBD]{@link https://iwasbeingirony.blogspot.com/2010/06/difference-between-rgbm-and-rgbd.html}
+		 *
+		 * @type {(7|16)}
+		 * @default 7
+		 */
+		this.maxRange = 7;
 
 	}
 
+	/**
+	 * Sets the texture type.
+	 *
+	 * @param {(HalfFloatType|FloatType)} value - The texture type to set.
+	 * @return {RGBMLoader} A reference to this loader.
+	 */
 	setDataType( value ) {
 
 		this.type = value;
@@ -25,6 +61,12 @@ class RGBMLoader extends DataTextureLoader {
 
 	}
 
+	/**
+	 * Sets the maximum range.
+	 *
+	 * @param {(7|16)} value - The maximum range to set.
+	 * @return {RGBMLoader} A reference to this loader.
+	 */
 	setMaxRange( value ) {
 
 		this.maxRange = value;
@@ -32,6 +74,16 @@ class RGBMLoader extends DataTextureLoader {
 
 	}
 
+	/**
+	 * Starts loading from the given URLs and passes the loaded RGBM cube map
+	 * to the `onLoad()` callback.
+	 *
+	 * @param {Array<string>} urls - The paths/URLs of the files to be loaded. This can also be a data URIs.
+	 * @param {function(CubeTexture)} onLoad - Executed when the loading process has been finished.
+	 * @param {onProgressCallback} onProgress - Executed while the loading is in progress.
+	 * @param {onErrorCallback} onError - Executed when errors occur.
+	 * @return {CubeTexture} The cube texture.
+	 */
 	loadCubemap( urls, onLoad, onProgress, onError ) {
 
 		const texture = new CubeTexture();
@@ -81,6 +133,14 @@ class RGBMLoader extends DataTextureLoader {
 
 	}
 
+	/**
+	 * Async version of {@link RGBMLoader#loadCubemap}.
+	 *
+	 * @async
+	 * @param {Array<string>} urls - The paths/URLs of the files to be loaded. This can also be a data URIs.
+	 * @param {onProgressCallback} onProgress - Executed while the loading is in progress.
+	 * @return {Promise<CubeTexture>} A Promise that resolves with the loaded cube map.
+	 */
 	loadCubemapAsync( urls, onProgress ) {
 
 		return new Promise( ( resolve, reject ) => {
@@ -91,6 +151,12 @@ class RGBMLoader extends DataTextureLoader {
 
 	}
 
+	/**
+	 * Parses the given RGBM texture data.
+	 *
+	 * @param {ArrayBuffer} buffer - The raw texture data.
+	 * @return {DataTextureLoader~TexData} An object representing the parsed texture data.
+	 */
 	parse( buffer ) {
 
 		const img = UPNG.decode( buffer );

package/examples/jsm/loaders/STLLoader.js

@@ -10,65 +10,68 @@ import {
 } from 'three';
 
 /**
- * Description: A THREE loader for STL ASCII files, as created by Solidworks and other CAD programs.
+ * A loader for the STL format, as created by Solidworks and other CAD programs.
  *
- * Supports both binary and ASCII encoded files, with automatic detection of type.
- *
- * The loader returns a non-indexed buffer geometry.
+ * Supports both binary and ASCII encoded files. The loader returns a non-indexed buffer geometry.
  *
  * Limitations:
- *  Binary decoding supports "Magics" color format (http://en.wikipedia.org/wiki/STL_(file_format)#Color_in_binary_STL).
- *  There is perhaps some question as to how valid it is to always assume little-endian-ness.
- *  ASCII decoding assumes file is UTF-8.
- *
- * Usage:
- *  const loader = new STLLoader();
- *  loader.load( './models/stl/slotted_disk.stl', function ( geometry ) {
- *    scene.add( new THREE.Mesh( geometry ) );
- *  });
+ * - Binary decoding supports "Magics" color format (http://en.wikipedia.org/wiki/STL_(file_format)#Color_in_binary_STL).
+ * - There is perhaps some question as to how valid it is to always assume little-endian-ness.
+ * - ASCII decoding assumes file is UTF-8.
  *
+ * ```js
+ * const loader = new STLLoader();
+ * const geometry = await loader.loadAsync( './models/stl/slotted_disk.stl' )
+ * scene.add( new THREE.Mesh( geometry ) );
+ * ```
  * For binary STLs geometry might contain colors for vertices. To use it:
- *  // use the same code to load STL as above
- *  if (geometry.hasColors) {
- *    material = new THREE.MeshPhongMaterial({ opacity: geometry.alpha, vertexColors: true });
- *  } else { .... }
- *  const mesh = new THREE.Mesh( geometry, material );
- *
+ * ```js
+ * // use the same code to load STL as above
+ * if ( geometry.hasColors ) {
+ * 	material = new THREE.MeshPhongMaterial( { opacity: geometry.alpha, vertexColors: true } );
+ * }
+ * const mesh = new THREE.Mesh( geometry, material );
+ * ```
  * For ASCII STLs containing multiple solids, each solid is assigned to a different group.
  * Groups can be used to assign a different color by defining an array of materials with the same length of
  * geometry.groups and passing it to the Mesh constructor:
  *
- * const mesh = new THREE.Mesh( geometry, material );
- *
- * For example:
+ * ```js
+ * const materials = [];
+ * const nGeometryGroups = geometry.groups.length;
  *
- *  const materials = [];
- *  const nGeometryGroups = geometry.groups.length;
+ * for ( let i = 0; i < nGeometryGroups; i ++ ) {
+ * 	const material = new THREE.MeshPhongMaterial( { color: colorMap[ i ], wireframe: false } );
+ * 	materials.push( material );
+ * }
  *
- *  const colorMap = ...; // Some logic to index colors.
+ * const mesh = new THREE.Mesh(geometry, materials);
+ * ```
  *
- *  for (let i = 0; i < nGeometryGroups; i++) {
- *
- *		const material = new THREE.MeshPhongMaterial({
- *			color: colorMap[i],
- *			wireframe: false
- *		});
- *
- *  }
- *
- *  materials.push(material);
- *  const mesh = new THREE.Mesh(geometry, materials);
+ * @augments Loader
  */
-
-
 class STLLoader extends Loader {
 
+	/**
+	 * Constructs a new STL loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded STL asset
+	 * to the `onLoad()` callback.
+	 *
+	 * @param {string} url - The path/URL of the file to be loaded. This can also be a data URI.
+	 * @param {function(BufferGeometry)} onLoad - Executed when the loading process has been finished.
+	 * @param {onProgressCallback} onProgress - Executed while the loading is in progress.
+	 * @param {onErrorCallback} onError - Executed when errors occur.
+	 */
 	load( url, onLoad, onProgress, onError ) {
 
 		const scope = this;
@@ -105,6 +108,12 @@ class STLLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given STL data and returns the resulting geometry.
+	 *
+	 * @param {ArrayBuffer} data - The raw STL data as an array buffer.
+	 * @return {BufferGeometry} The parsed geometry.
+	 */
 	parse( data ) {
 
 		function isBinary( data ) {

package/examples/jsm/loaders/SVGLoader.js

@@ -16,20 +16,84 @@ import {
 
 const COLOR_SPACE_SVG = SRGBColorSpace;
 
+/**
+ * A loader for the SVG format.
+ *
+ * Scalable Vector Graphics is an XML-based vector image format for two-dimensional graphics
+ * with support for interactivity and animation.
+ *
+ * ```js
+ * const loader = new SVGLoader();
+ * const data = await loader.loadAsync( 'data/svgSample.svg' );
+ *
+ * const paths = data.paths;
+ * const group = new THREE.Group();
+ *
+ * for ( let i = 0; i < paths.length; i ++ ) {
+ *
+ * 	const path = paths[ i ];
+ * 	const material = new THREE.MeshBasicMaterial( {
+ * 		color: path.color,
+ * 		side: THREE.DoubleSide,
+ * 		depthWrite: false
+ * 	} );
+ *
+ * 	const shapes = SVGLoader.createShapes( path );
+ *
+ * 	for ( let j = 0; j < shapes.length; j ++ ) {
+ *
+ * 		const shape = shapes[ j ];
+ * 		const geometry = new THREE.ShapeGeometry( shape );
+ * 		const mesh = new THREE.Mesh( geometry, material );
+ * 		group.add( mesh );
+ *
+ * 	}
+ *
+ * }
+ *
+ * scene.add( group );
+ * ```
+ *
+ * @augments Loader
+ */
 class SVGLoader extends Loader {
 
+	/**
+	 * Constructs a new SVG loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
-		// Default dots per inch
+		/**
+		 * Default dots per inch.
+		 *
+		 * @type {number}
+		 * @default 90
+		 */
 		this.defaultDPI = 90;
 
-		// Accepted units: 'mm', 'cm', 'in', 'pt', 'pc', 'px'
+		/**
+		 * Default unit.
+		 *
+		 * @type {('mm'|'cm'|'in'|'pt'|'pc'|'px')}
+		 * @default 'px'
+		 */
 		this.defaultUnit = 'px';
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded SVG asset
+	 * to the `onLoad()` callback.
+	 *
+	 * @param {string} url - The path/URL of the file to be loaded. This can also be a data URI.
+	 * @param {function({paths:Array<ShapePath>,xml:string})} onLoad - Executed when the loading process has been finished.
+	 * @param {onProgressCallback} onProgress - Executed while the loading is in progress.
+	 * @param {onErrorCallback} onError - Executed when errors occur.
+	 */
 	load( url, onLoad, onProgress, onError ) {
 
 		const scope = this;
@@ -64,6 +128,13 @@ class SVGLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given SVG data and returns the resulting data.
+	 *
+	 * @param {string} text - The raw SVG data as a string.
+	 * @return {{paths:Array<ShapePath>,xml:string}} An object holding an array of shape paths and the
+	 * SVG XML document.
+	 */
 	parse( text ) {
 
 		const scope = this;
@@ -775,6 +846,7 @@ class SVGLoader extends Loader {
 		* According to https://www.w3.org/TR/SVG/shapes.html#RectElementRXAttribute
 		* rounded corner should be rendered to elliptical arc, but bezier curve does the job well enough
 		*/
+
 		function parseRectNode( node ) {
 
 			const x = parseFloatWithUnits( node.getAttribute( 'x' ) || 0 );
@@ -1916,11 +1988,14 @@ class SVGLoader extends Loader {
 
 	}
 
+	/**
+	 * Creates from the given shape path and array of shapes.
+	 *
+	 * @param {ShapePath} shapePath - The shape path.
+	 * @return {Array<Shape>} An array of shapes.
+	 */
 	static createShapes( shapePath ) {
 
-		// Param shapePath: a shapepath as returned by the parse function of this class
-		// Returns Shape object
-
 		const BIGNUMBER = 999999999;
 
 		const IntersectionLocationType = {
@@ -2360,15 +2435,18 @@ class SVGLoader extends Loader {
 
 	}
 
+	/**
+	 * Returns a stroke style object from the given parameters.
+	 *
+	 * @param {number} [width=1] - The stroke width.
+	 * @param {string} [color='#000'] - The stroke color, as  returned by {@link Color#getStyle}.
+	 * @param {'round'|'bevel'|'miter'|'miter-limit'} [lineJoin='miter'] - The line join style.
+	 * @param {'round'|'square'|'butt'} [lineCap='butt'] - The line cap style.
+	 * @param {number} [miterLimit=4] - Maximum join length, in multiples of the `width` parameter (join is truncated if it exceeds that distance).
+	 * @return {Object} The style object.
+	 */
 	static getStrokeStyle( width, color, lineJoin, lineCap, miterLimit ) {
 
-		// Param width: Stroke width
-		// Param color: As returned by THREE.Color.getStyle()
-		// Param lineJoin: One of "round", "bevel", "miter" or "miter-limit"
-		// Param lineCap: One of "round", "square" or "butt"
-		// Param miterLimit: Maximum join length, in multiples of the "width" parameter (join is truncated if it exceeds that distance)
-		// Returns style object
-
 		width = width !== undefined ? width : 1;
 		color = color !== undefined ? color : '#000';
 		lineJoin = lineJoin !== undefined ? lineJoin : 'miter';
@@ -2385,16 +2463,18 @@ class SVGLoader extends Loader {
 
 	}
 
+	/**
+	 * Creates a stroke from an array of points.
+	 *
+	 * @param {Array<Vector2>} points - The points in 2D space. Minimum 2 points. The path can be open or closed (last point equals to first point).
+	 * @param {Object} style - Object with SVG properties as returned by `SVGLoader.getStrokeStyle()`, or `SVGLoader.parse()` in the `path.userData.style` object.
+	 * @param {number} [arcDivisions=12] - Arc divisions for round joins and endcaps.
+	 * @param {number} [minDistance=0.001] - Points closer to this distance will be merged.
+	 * @return {?BufferGeometry} The stroke geometry. UV coordinates are generated ('u' along path. 'v' across it, from left to right).
+	 * Returns `null` if not geometry was generated.
+	 */
 	static pointsToStroke( points, style, arcDivisions, minDistance ) {
 
-		// Generates a stroke with some width around the given path.
-		// The path can be open or closed (last point equals to first point)
-		// Param points: Array of Vector2D (the path). Minimum 2 points.
-		// Param style: Object with SVG properties as returned by SVGLoader.getStrokeStyle(), or SVGLoader.parse() in the path.userData.style object
-		// Params arcDivisions: Arc divisions for round joins and endcaps. (Optional)
-		// Param minDistance: Points closer to this distance will be merged. (Optional)
-		// Returns BufferGeometry with stroke triangles (In plane z = 0). UV coordinates are generated ('u' along path. 'v' across it, from left to right)
-
 		const vertices = [];
 		const normals = [];
 		const uvs = [];
@@ -2414,6 +2494,19 @@ class SVGLoader extends Loader {
 
 	}
 
+	/**
+	 * Creates a stroke from an array of points.
+	 *
+	 * @param {Array<Vector2>} points - The points in 2D space. Minimum 2 points.
+	 * @param {Object} style - Object with SVG properties as returned by `SVGLoader.getStrokeStyle()`, or `SVGLoader.parse()` in the `path.userData.style` object.
+	 * @param {number} [arcDivisions=12] - Arc divisions for round joins and endcaps.
+	 * @param {number} [minDistance=0.001] - Points closer to this distance will be merged.
+	 * @param {Array<number>} vertices - An array holding vertices.
+	 * @param {Array<number>} normals - An array holding normals.
+	 * @param {Array<number>} uvs - An array holding uvs.
+	 * @param {number} [vertexOffset=0] - The vertex offset.
+	 * @return {number} The number of vertices.
+	 */
 	static pointsToStrokeWithBuffers( points, style, arcDivisions, minDistance, vertices, normals, uvs, vertexOffset ) {
 
 		// This function can be called to update existing arrays or buffers.