@plastic-software/three 0.174.0 → 0.175.0

package/examples/jsm/loaders/IESLoader.js

@@ -11,12 +11,38 @@ import {
 	DataUtils
 } from 'three';
 
+/**
+ * A loader for the IES format.
+ *
+ * The loaded texture should be assigned to {@link IESSpotLight#map}.
+ *
+ * ```js
+ * const loader = new IESLoader();
+ * const texture = await loader.loadAsync( 'ies/007cfb11e343e2f42e3b476be4ab684e.ies' );
+ *
+ * const spotLight = new THREE.IESSpotLight( 0xff0000, 500 );
+ * spotLight.iesMap = texture;
+ * ```
+ *
+ * @augments Loader
+ */
 class IESLoader extends Loader {
 
+	/**
+	 * Constructs a new IES loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
+		/**
+		 * The texture type.
+		 *
+		 * @type {(HalfFloatType|FloatType)}
+		 * @default HalfFloatType
+		 */
 		this.type = HalfFloatType;
 
 	}
@@ -112,6 +138,15 @@ class IESLoader extends Loader {
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded IES texture
+	 * 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(DataTexture)} 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 loader = new FileLoader( this.manager );
@@ -129,6 +164,12 @@ class IESLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given IES data.
+	 *
+	 * @param {string} text - The raw IES data.
+	 * @return {DataTexture} THE IES data as a texture.
+	 */
 	parse( text ) {
 
 		const type = this.type;

package/examples/jsm/loaders/KMZLoader.js

@@ -7,14 +7,40 @@ import {
 import { ColladaLoader } from '../loaders/ColladaLoader.js';
 import * as fflate from '../libs/fflate.module.js';
 
+/**
+ * A loader for the KMZ format.
+ *
+ * ```js
+ * const loader = new KMZLoader();
+ * const kmz = await loader.loadAsync( './models/kmz/Box.kmz' );
+ *
+ * scene.add( kmz.scene );
+ * ```
+ *
+ * @augments Loader
+ */
 class KMZLoader extends Loader {
 
+	/**
+	 * Constructs a new KMZ loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded KMZ 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({scene:Group})} 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;
@@ -50,6 +76,12 @@ class KMZLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given KMZ data and returns an object holding the scene.
+	 *
+	 * @param {ArrayBuffer} data - The raw KMZ data as an array buffer.
+	 * @return {{scene:Group}} The parsed KMZ asset.
+	 */
 	parse( data ) {
 
 		function findFile( url ) {

package/examples/jsm/loaders/KTX2Loader.js

@@ -1,17 +1,3 @@
-/**
- * Loader for KTX 2.0 GPU Texture containers.
- *
- * KTX 2.0 is a container format for various GPU texture formats. The loader
- * supports Basis Universal GPU textures, which can be quickly transcoded to
- * a wide variety of GPU texture compression formats, as well as some
- * uncompressed DataTexture and Data3DTexture formats.
- *
- * References:
- * - KTX: http://github.khronos.org/KTX-Specification/
- * - DFD: https://www.khronos.org/registry/DataFormat/specs/1.3/dataformat.1.3.html#basicdescriptor
- * - BasisU HDR: https://github.com/BinomialLLC/basis_universal/wiki/UASTC-HDR-Texture-Specification-v1.0
- */
-
 import {
 	CompressedTexture,
 	CompressedArrayTexture,
@@ -79,8 +65,39 @@ let _activeLoaders = 0;
 
 let _zstd;
 
+/**
+ * A loader for KTX 2.0 GPU Texture containers.
+ *
+ * KTX 2.0 is a container format for various GPU texture formats. The loader supports Basis Universal GPU textures,
+ * which can be quickly transcoded to a wide variety of GPU texture compression formats. While KTX 2.0 also allows
+ * other hardware-specific formats, this loader does not yet parse them.
+ *
+ * This loader parses the KTX 2.0 container and transcodes to a supported GPU compressed texture format.
+ * The required WASM transcoder and JS wrapper are available from the `examples/jsm/libs/basis` directory.
+ *
+ * This loader relies on Web Assembly which is not supported in older browsers.
+ *
+ * References:
+ * - [KTX specification]{@link http://github.khronos.org/KTX-Specification/}
+ * - [DFD]{@link https://www.khronos.org/registry/DataFormat/specs/1.3/dataformat.1.3.html#basicdescriptor}
+ * - [BasisU HDR]{@link https://github.com/BinomialLLC/basis_universal/wiki/UASTC-HDR-Texture-Specification-v1.0}
+ *
+ * ```js
+ * const loader = new KTX2Loader();
+ * loader.setTranscoderPath( 'examples/jsm/libs/basis/' );
+ * loader.detectSupport( renderer );
+ * const texture = loader.loadAsync( 'diffuse.ktx2' );
+ * ```
+ *
+ * @augments Loader
+ */
 class KTX2Loader extends Loader {
 
+	/**
+	 * Constructs a new KTX2 loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
@@ -106,6 +123,14 @@ class KTX2Loader extends Loader {
 
 	}
 
+	/**
+	 * Sets the transcoder path.
+	 *
+	 * The WASM transcoder and JS wrapper are available from the `examples/jsm/libs/basis` directory.
+	 *
+	 * @param {string} path - The transcoder path to set.
+	 * @return {KTX2Loader} A reference to this loader.
+	 */
 	setTranscoderPath( path ) {
 
 		this.transcoderPath = path;
@@ -114,14 +139,28 @@ class KTX2Loader extends Loader {
 
 	}
 
-	setWorkerLimit( num ) {
+	/**
+	 * Sets the maximum number of Web Workers to be allocated by this instance.
+	 *
+	 * @param {number} workerLimit - The worker limit.
+	 * @return {KTX2Loader} A reference to this loader.
+	 */
+	setWorkerLimit( workerLimit ) {
 
-		this.workerPool.setWorkerLimit( num );
+		this.workerPool.setWorkerLimit( workerLimit );
 
 		return this;
 
 	}
 
+
+	/**
+	 * Async version of {@link KTX2Loader#detectSupport}.
+	 *
+	 * @async
+	 * @param {WebGPURenderer|WebGLRenderer} renderer - The renderer.
+	 * @return {Promise} A Promise that resolves when the support has been detected.
+	 */
 	async detectSupportAsync( renderer ) {
 
 		this.workerConfig = {
@@ -138,6 +177,13 @@ class KTX2Loader extends Loader {
 
 	}
 
+	/**
+	 * Detects hardware support for available compressed texture formats, to determine
+	 * the output format for the transcoder. Must be called before loading a texture.
+	 *
+	 * @param {WebGPURenderer|WebGLRenderer} renderer - The renderer.
+	 * @return {KTX2Loader} A reference to this loader.
+	 */
 	detectSupport( renderer ) {
 
 		if ( renderer.isWebGPURenderer === true ) {
@@ -172,6 +218,8 @@ class KTX2Loader extends Loader {
 
 	}
 
+	// TODO: Make this method private
+
 	init() {
 
 		if ( ! this.transcoderPending ) {
@@ -243,6 +291,15 @@ class KTX2Loader extends Loader {
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded KTX2 texture
+	 * 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(CompressedTexture)} 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 ) {
 
 		if ( this.workerConfig === null ) {
@@ -264,6 +321,14 @@ class KTX2Loader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given KTX2 data.
+	 *
+	 * @param {ArrayBuffer} buffer - The raw KTX2 data as an array buffer.
+	 * @param {function(CompressedTexture)} onLoad - Executed when the loading/parsing process has been finished.
+	 * @param {onErrorCallback} onError - Executed when errors occur.
+	 * @returns {Promise} A Promise that resolves when the parsing has been finished.
+	 */
 	parse( buffer, onLoad, onError ) {
 
 		if ( this.workerConfig === null ) {
@@ -323,6 +388,7 @@ class KTX2Loader extends Loader {
 	}
 
 	/**
+	 * @private
 	 * @param {ArrayBuffer} buffer
 	 * @param {?Object} config
 	 * @return {Promise<CompressedTexture|CompressedArrayTexture|DataTexture|Data3DTexture>}
@@ -364,6 +430,10 @@ class KTX2Loader extends Loader {
 
 	}
 
+	/**
+	 * Frees internal resources. This method should be called
+	 * when the loader is no longer required.
+	 */
 	dispose() {
 
 		this.workerPool.dispose();
@@ -371,8 +441,6 @@ class KTX2Loader extends Loader {
 
 		_activeLoaders --;
 
-		return this;
-
 	}
 
 }

package/examples/jsm/loaders/KTXLoader.js

@@ -3,21 +3,41 @@ import {
 } from 'three';
 
 /**
- * for description see https://www.khronos.org/opengles/sdk/tools/KTX/
- * for file layout see https://www.khronos.org/opengles/sdk/tools/KTX/file_format_spec/
+ * A loader for the KTX texture compression format.
  *
- * ported from https://github.com/BabylonJS/Babylon.js/blob/master/src/Misc/khronosTextureContainer.ts
+ * References:
+ * - [The KTX File Format and Tools]{@link https://www.khronos.org/opengles/sdk/tools/KTX/}
+ * - [Babylon.JS khronosTextureContainer.ts]{@link https://github.com/BabylonJS/Babylon.js/blob/master/src/Misc/khronosTextureContainer.ts}
+ *
+ * ```js
+ * const loader = new KTXLoader();
+ *
+ * const map = loader.load( 'textures/compressed/lensflare_ASTC8x8.ktx' )
+ * map.colorSpace = THREE.SRGBColorSpace; // only for color textures
+ * ```
+ *
+ * @augments CompressedTextureLoader
  */
-
-
 class KTXLoader extends CompressedTextureLoader {
 
+	/**
+	 * Constructs a new KTX loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
 	}
 
+	/**
+	 * Parses the given KTX texture data.
+	 *
+	 * @param {ArrayBuffer} buffer - The raw texture data.
+	 * @param {boolean} loadMipmaps - Whether to load mipmaps or not.
+	 * @return {CompressedTextureLoader~TexData} An object representing the parsed texture data.
+	 */
 	parse( buffer, loadMipmaps ) {
 
 		const ktx = new KhronosTextureContainer( buffer, 1 );
@@ -35,7 +55,6 @@ class KTXLoader extends CompressedTextureLoader {
 
 }
 
-
 const HEADER_LEN = 12 + ( 13 * 4 ); // identifier + header elements (not including key value meta-data pairs)
 // load types
 const COMPRESSED_2D = 0; // uses a gl.compressedTexImage2D()
@@ -46,6 +65,7 @@ const COMPRESSED_2D = 0; // uses a gl.compressedTexImage2D()
 class KhronosTextureContainer {
 
 	/**
+	 * @private
 	 * @param {ArrayBuffer} arrayBuffer - contents of the KTX container file
 	 * @param {number} facesExpected - should be either 1 or 6, based whether a cube texture or or
 	 * @param {boolean} threeDExpected - provision for indicating that data should be a 3D texture, not implemented

package/examples/jsm/loaders/LDrawLoader.js

@@ -1746,10 +1746,44 @@ function createObject( loader, elements, elementSize, isConditionalSegments = fa
 
 }
 
-//
-
+/**
+ * A loader for the LDraw format.
+ *
+ * [LDraw]{@link https://ldraw.org/} (LEGO Draw) is an [open format specification]{@link https://ldraw.org/article/218.html}
+ * for describing LEGO and other construction set 3D models.
+ *
+ * An LDraw asset (a text file usually with extension .ldr, .dat or .txt) can describe just a single construction
+ * piece, or an entire model. In the case of a model the LDraw file can reference other LDraw files, which are
+ * loaded from a library path set with `setPartsLibraryPath`. You usually download the LDraw official parts library,
+ * extract to a folder and point setPartsLibraryPath to it.
+ *
+ * Library parts will be loaded by trial and error in subfolders 'parts', 'p' and 'models'. These file accesses
+ * are not optimal for web environment, so a script tool has been made to pack an LDraw file with all its dependencies
+ * into a single file, which loads much faster. See section 'Packing LDraw models'. The LDrawLoader example loads
+ * several packed files. The official parts library is not included due to its large size.
+ *
+ * `LDrawLoader` supports the following extensions:
+ * - !COLOUR: Color and surface finish declarations.
+ * - BFC: Back Face Culling specification.
+ * - !CATEGORY: Model/part category declarations.
+ * - !KEYWORDS: Model/part keywords declarations.
+ *
+ * ```js
+ * const loader = new LDrawLoader();
+ * loader.setConditionalLineMaterial( LDrawConditionalLineMaterial ); // the type of line material depends on the used renderer
+ * const object = await loader.loadAsync( 'models/ldraw/officialLibrary/models/car.ldr_Packed.mpd' );
+ * scene.add( object );
+ * ```
+ *
+ * @augments Loader
+ */
 class LDrawLoader extends Loader {
 
+	/**
+	 * Constructs a new LDraw loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
@@ -1784,6 +1818,14 @@ class LDrawLoader extends Loader {
 
 	}
 
+	/**
+	 * This method must be called prior to `load()` unless the model to load does not reference
+	 * library parts (usually it will be a model with all its parts packed in a single file).
+	 *
+	 * @param {string} path - Path to library parts files to load referenced parts from.
+	 * This is different from Loader.setPath, which indicates the path to load the main asset from.
+	 * @return {LDrawLoader} A reference to this loader.
+	 */
 	setPartsLibraryPath( path ) {
 
 		this.partsLibraryPath = path;
@@ -1791,6 +1833,14 @@ class LDrawLoader extends Loader {
 
 	}
 
+	/**
+	 * Sets the conditional line material type which depends on the used renderer.
+	 * Use {@link LDrawConditionalLineMaterial} when using `WebGLRenderer` and
+	 * {@link LDrawConditionalLineNodeMaterial} when using `WebGPURenderer`.
+	 *
+	 * @param {(LDrawConditionalLineMaterial.constructor|LDrawConditionalLineNodeMaterial.constructor)} type - The conditional line material type.
+	 * @return {LDrawLoader} A reference to this loader.
+	 */
 	setConditionalLineMaterial( type ) {
 
 		this.ConditionalLineMaterial = type;
@@ -1799,6 +1849,17 @@ class LDrawLoader extends Loader {
 
 	}
 
+	/**
+	 * This async method preloads materials from a single LDraw file. In the official
+	 * parts library there is a special file which is loaded always the first (LDConfig.ldr)
+	 * and contains all the standard color codes. This method is intended to be used with
+	 * not packed files, for example in an editor where materials are preloaded and parts
+	 * are loaded on demand.
+	 *
+	 * @async
+	 * @param {string} url - Path of the LDraw materials asset.
+	 * @return {Promise} A Promise that resolves when the preload has finished.
+	 */
 	async preloadMaterials( url ) {
 
 		const fileLoader = new FileLoader( this.manager );
@@ -1827,6 +1888,15 @@ class LDrawLoader extends Loader {
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded LDraw 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(Group)} 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 fileLoader = new FileLoader( this.manager );
@@ -1839,7 +1909,7 @@ class LDrawLoader extends Loader {
 			this.setMaterials( [] );
 
 			this.partsCache
-				.parseModel( text, this.materialLibrary )
+				.parseModel( text )
 				.then( group => {
 
 					this.applyMaterialsToMesh( group, MAIN_COLOUR_CODE, this.materialLibrary, true );
@@ -1854,10 +1924,17 @@ class LDrawLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given LDraw data and returns the resulting group.
+	 *
+	 * @param {string} text - The raw VRML data as a string.
+	 * @param {function(Group)} onLoad - Executed when the loading/parsing process has been finished.
+	 * @param {onErrorCallback} onError - Executed when errors occur.
+	 */
 	parse( text, onLoad, onError ) {
 
 		this.partsCache
-			.parseModel( text, this.materialLibrary )
+			.parseModel( text )
 			.then( group => {
 
 				this.applyMaterialsToMesh( group, MAIN_COLOUR_CODE, this.materialLibrary, true );
@@ -1888,6 +1965,14 @@ class LDrawLoader extends Loader {
 
 	}
 
+	/**
+	 * Sets a map which maps referenced library filenames to new filenames.
+	 * If a fileMap is not specified (the default), library parts will be accessed by trial and
+	 * error in subfolders 'parts', 'p' and 'models'.
+	 *
+	 * @param {Object<string,string>} fileMap - The file map to set.
+	 * @return {LDrawLoader} A reference to this loader.
+	 */
 	setFileMap( fileMap ) {
 
 		this.fileMap = fileMap;
@@ -1912,6 +1997,12 @@ class LDrawLoader extends Loader {
 
 	}
 
+	/**
+	 * Returns a material for the given color code.
+	 *
+	 * @param {string} colorCode - The color code.
+	 * @return {?Material} The material. Returns `null` if no material has been found.
+	 */
 	getMaterial( colorCode ) {
 
 		if ( colorCode.startsWith( '0x2' ) ) {
@@ -2027,12 +2118,31 @@ class LDrawLoader extends Loader {
 
 	}
 
+	/**
+	 * Returns the Material for the main LDraw color.
+	 *
+	 * For an already loaded LDraw asset, returns the Material associated with the main color code.
+	 * This method can be useful to modify the main material of a model or part that exposes it.
+	 *
+	 * The main color code is the standard way to color an LDraw part. It is '16' for triangles and
+	 * '24' for edges. Usually a complete model will not expose the main color (that is, no part
+	 * uses the code '16' at the top level, because they are assigned other specific colors) An LDraw
+	 *  part file on the other hand will expose the code '16' to be colored, and can have additional
+	 * fixed colors.
+	 *
+	 * @return {?Material} The material. Returns `null` if no material has been found.
+	 */
 	getMainMaterial() {
 
 		return this.getMaterial( MAIN_COLOUR_CODE );
 
 	}
 
+	/**
+	 * Returns the material for the edges main LDraw color.
+	 *
+	 * @return {?Material} The material. Returns `null` if no material has been found.
+	 */
 	getMainEdgeMaterial() {
 
 		const mat = this.getMaterial( MAIN_EDGE_COLOUR_CODE );
@@ -2151,7 +2261,7 @@ class LDrawLoader extends Loader {
 
 						if ( ! parseLuminance( lineParser.getToken() ) ) {
 
-							throw new Error( 'LDrawLoader: Invalid luminance value in material definition' + LineParser.getLineNumberString() + '.' );
+							throw new Error( 'LDrawLoader: Invalid luminance value in material definition' + lineParser.getLineNumberString() + '.' );
 
 						}
 

package/examples/jsm/loaders/LUT3dlLoader.js

@@ -1,41 +1,71 @@
-// http://download.autodesk.com/us/systemdocs/help/2011/lustre/index.html?url=./files/WSc4e151a45a3b785a24c3d9a411df9298473-7ffd.htm,topicNumber=d0e9492
-// https://community.foundry.com/discuss/topic/103636/format-spec-for-3dl?mode=Post&postID=895258
-
 import {
 	ClampToEdgeWrapping,
 	Data3DTexture,
 	FileLoader,
-	FloatType,
 	LinearFilter,
 	Loader,
 	RGBAFormat,
 	UnsignedByteType,
 } from 'three';
 
+/**
+ * A loader for the 3DL LUT format.
+ *
+ * References:
+ * - [3D LUTs]{@link http://download.autodesk.com/us/systemdocs/help/2011/lustre/index.html?url=./files/WSc4e151a45a3b785a24c3d9a411df9298473-7ffd.htm,topicNumber=d0e9492}
+ * - [Format Spec for .3dl]{@link https://community.foundry.com/discuss/topic/103636/format-spec-for-3dl?mode=Post&postID=895258}
+ *
+ * ```js
+ * const loader = new LUT3dlLoader();
+ * const map = loader.loadAsync( 'luts/Presetpro-Cinematic.3dl' );
+ * ```
+ *
+ * @augments Loader
+ */
 export class LUT3dlLoader extends Loader {
 
+	/**
+	 * Constructs a new 3DL LUT loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
+		/**
+		 * The texture type.
+		 *
+		 * @type {(UnsignedByteType|FloatType)}
+		 * @default UnsignedByteType
+		 */
 		this.type = UnsignedByteType;
 
 	}
 
+	/**
+	 * Sets the texture type.
+	 *
+	 * @param {(UnsignedByteType|FloatType)} type - The texture type to set.
+	 * @return {LUT3dlLoader} A reference to this loader.
+	 */
 	setType( type ) {
 
-		if ( type !== UnsignedByteType && type !== FloatType ) {
-
-			throw new Error( 'LUT3dlLoader: Unsupported type' );
-
-		}
-
 		this.type = type;
 
 		return this;
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded 3DL LUT 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({size:number,texture3D:Data3DTexture})} 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 loader = new FileLoader( this.manager );
@@ -67,6 +97,12 @@ export class LUT3dlLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given 3DL LUT data and returns the resulting 3D data texture.
+	 *
+	 * @param {string} input - The raw 3DL LUT data as a string.
+	 * @return {{size:number,texture3D:Data3DTexture}} The parsed 3DL LUT.
+	 */
 	parse( input ) {
 
 		const regExpGridInfo = /^[\d ]+$/m;