super-three 0.173.5 → 0.176.0

package/src/loaders/Loader.js

@@ -1,21 +1,86 @@
 import { DefaultLoadingManager } from './LoadingManager.js';
 
+/**
+ * Abstract base class for loaders.
+ *
+ * @abstract
+ */
 class Loader {
 
+	/**
+	 * Constructs a new loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
+		/**
+		 * The loading manager.
+		 *
+		 * @type {LoadingManager}
+		 * @default DefaultLoadingManager
+		 */
 		this.manager = ( manager !== undefined ) ? manager : DefaultLoadingManager;
 
+		/**
+		 * The crossOrigin string to implement CORS for loading the url from a
+		 * different domain that allows CORS.
+		 *
+		 * @type {string}
+		 * @default 'anonymous'
+		 */
 		this.crossOrigin = 'anonymous';
+
+		/**
+		 * Whether the XMLHttpRequest uses credentials.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.withCredentials = false;
+
+		/**
+		 * The base path from which the asset will be loaded.
+		 *
+		 * @type {string}
+		 */
 		this.path = '';
+
+		/**
+		 * The base path from which additional resources like textures will be loaded.
+		 *
+		 * @type {string}
+		 */
 		this.resourcePath = '';
+
+		/**
+		 * The [request header]{@link https://developer.mozilla.org/en-US/docs/Glossary/Request_header}
+		 * used in HTTP request.
+		 *
+		 * @type {Object<string, any>}
+		 */
 		this.requestHeader = {};
 
 	}
 
+	/**
+	 * This method needs to be implemented by all concrete loaders. It holds the
+	 * logic for loading assets from the backend.
+	 *
+	 * @param {string} url - The path/URL of the file to be loaded.
+	 * @param {Function} 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 */ ) {}
 
+	/**
+	 * A async version of {@link Loader#load}.
+	 *
+	 * @param {string} url - The path/URL of the file to be loaded.
+	 * @param {onProgressCallback} [onProgress] - Executed while the loading is in progress.
+	 * @return {Promise} A Promise that resolves when the asset has been loaded.
+	 */
 	loadAsync( url, onProgress ) {
 
 		const scope = this;
@@ -28,8 +93,21 @@ class Loader {
 
 	}
 
+	/**
+	 * This method needs to be implemented by all concrete loaders. It holds the
+	 * logic for parsing the asset into three.js entities.
+	 *
+	 * @param {any} data - The data to parse.
+	 */
 	parse( /* data */ ) {}
 
+	/**
+	 * Sets the `crossOrigin` String to implement CORS for loading the URL
+	 * from a different domain that allows CORS.
+	 *
+	 * @param {string} crossOrigin - The `crossOrigin` value.
+	 * @return {Loader} A reference to this instance.
+	 */
 	setCrossOrigin( crossOrigin ) {
 
 		this.crossOrigin = crossOrigin;
@@ -37,6 +115,15 @@ class Loader {
 
 	}
 
+	/**
+	 * Whether the XMLHttpRequest uses credentials such as cookies, authorization
+	 * headers or TLS client certificates, see [XMLHttpRequest.withCredentials]{@link https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/withCredentials}.
+	 *
+	 * Note: This setting has no effect if you are loading files locally or from the same domain.
+	 *
+	 * @param {boolean} value - The `withCredentials` value.
+	 * @return {Loader} A reference to this instance.
+	 */
 	setWithCredentials( value ) {
 
 		this.withCredentials = value;
@@ -44,6 +131,12 @@ class Loader {
 
 	}
 
+	/**
+	 * Sets the base path for the asset.
+	 *
+	 * @param {string} path - The base path.
+	 * @return {Loader} A reference to this instance.
+	 */
 	setPath( path ) {
 
 		this.path = path;
@@ -51,6 +144,12 @@ class Loader {
 
 	}
 
+	/**
+	 * Sets the base path for dependent resources like textures.
+	 *
+	 * @param {string} resourcePath - The resource path.
+	 * @return {Loader} A reference to this instance.
+	 */
 	setResourcePath( resourcePath ) {
 
 		this.resourcePath = resourcePath;
@@ -58,6 +157,13 @@ class Loader {
 
 	}
 
+	/**
+	 * Sets the given request header.
+	 *
+	 * @param {Object} requestHeader - A [request header]{@link https://developer.mozilla.org/en-US/docs/Glossary/Request_header}
+	 * for configuring the HTTP request.
+	 * @return {Loader} A reference to this instance.
+	 */
 	setRequestHeader( requestHeader ) {
 
 		this.requestHeader = requestHeader;
@@ -67,6 +173,30 @@ class Loader {
 
 }
 
+/**
+ * Callback for onProgress in loaders.
+ *
+ * @callback onProgressCallback
+ * @param {ProgressEvent} event - An instance of `ProgressEvent` that represents the current loading status.
+ */
+
+/**
+ * Callback for onError in loaders.
+ *
+ * @callback onErrorCallback
+ * @param {Error} error - The error which occurred during the loading process.
+ */
+
+/**
+ * The default material name that is used by loaders
+ * when creating materials for loaded 3D objects.
+ *
+ * Note: Not all loaders might honor this setting.
+ *
+ * @static
+ * @type {string}
+ * @default '__DEFAULT'
+ */
 Loader.DEFAULT_MATERIAL_NAME = '__DEFAULT';
 
 export { Loader };

package/src/loaders/LoaderUtils.js

@@ -1,41 +1,14 @@
+/**
+ * A class with loader utility functions.
+ */
 class LoaderUtils {
 
-	static decodeText( array ) { // @deprecated, r165
-
-		console.warn( 'THREE.LoaderUtils: decodeText() has been deprecated with r165 and will be removed with r175. Use TextDecoder instead.' );
-
-		if ( typeof TextDecoder !== 'undefined' ) {
-
-			return new TextDecoder().decode( array );
-
-		}
-
-		// Avoid the String.fromCharCode.apply(null, array) shortcut, which
-		// throws a "maximum call stack size exceeded" error for large arrays.
-
-		let s = '';
-
-		for ( let i = 0, il = array.length; i < il; i ++ ) {
-
-			// Implicitly assumes little-endian.
-			s += String.fromCharCode( array[ i ] );
-
-		}
-
-		try {
-
-			// merges multi-byte utf-8 characters.
-
-			return decodeURIComponent( escape( s ) );
-
-		} catch ( e ) { // see #16358
-
-			return s;
-
-		}
-
-	}
-
+	/**
+	 * Extracts the base URL from the given URL.
+	 *
+	 * @param {string} url -The URL to extract the base URL from.
+	 * @return {string} The extracted base URL.
+	 */
 	static extractUrlBase( url ) {
 
 		const index = url.lastIndexOf( '/' );
@@ -46,6 +19,15 @@ class LoaderUtils {
 
 	}
 
+	/**
+	 * Resolves relative URLs against the given path. Absolute paths, data urls,
+	 * and blob URLs will be returned as is. Invalid URLs will return an empty
+	 * string.
+	 *
+	 * @param {string} url -The URL to resolve.
+	 * @param {string} path - The base path for relative URLs to be resolved against.
+	 * @return {string} The resolved URL.
+	 */
 	static resolveURL( url, path ) {
 
 		// Invalid URL

package/src/loaders/LoadingManager.js

@@ -1,5 +1,29 @@
+/**
+ * Handles and keeps track of loaded and pending data. A default global
+ * instance of this class is created and used by loaders if not supplied
+ * manually.
+ *
+ * In general that should be sufficient, however there are times when it can
+ * be useful to have separate loaders - for example if you want to show
+ * separate loading bars for objects and textures.
+ *
+ * ```js
+ * const manager = new THREE.LoadingManager();
+ * manager.onLoad = () => console.log( 'Loading complete!' );
+ *
+ * const loader1 = new OBJLoader( manager );
+ * const loader2 = new ColladaLoader( manager );
+ * ```
+ */
 class LoadingManager {
 
+	/**
+	 * Constructs a new loading manager.
+	 *
+	 * @param {Function} [onLoad] - Executes when all items have been loaded.
+	 * @param {Function} [onProgress] - Executes when single items have been loaded.
+	 * @param {Function} [onError] - Executes when an error occurs.
+	 */
 	constructor( onLoad, onProgress, onError ) {
 
 		const scope = this;
@@ -13,11 +37,44 @@ class LoadingManager {
 		// Refer to #5689 for the reason why we don't set .onStart
 		// in the constructor
 
+		/**
+		 * Executes when an item starts loading.
+		 *
+		 * @type {Function|undefined}
+		 * @default undefined
+		 */
 		this.onStart = undefined;
+
+		/**
+		 * Executes when all items have been loaded.
+		 *
+		 * @type {Function|undefined}
+		 * @default undefined
+		 */
 		this.onLoad = onLoad;
+
+		/**
+		 * Executes when single items have been loaded.
+		 *
+		 * @type {Function|undefined}
+		 * @default undefined
+		 */
 		this.onProgress = onProgress;
+
+		/**
+		 * Executes when an error occurs.
+		 *
+		 * @type {Function|undefined}
+		 * @default undefined
+		 */
 		this.onError = onError;
 
+		/**
+		 * This should be called by any loader using the manager when the loader
+		 * starts loading an item.
+		 *
+		 * @param {string} url - The URL to load.
+		 */
 		this.itemStart = function ( url ) {
 
 			itemsTotal ++;
@@ -36,6 +93,12 @@ class LoadingManager {
 
 		};
 
+		/**
+		 * This should be called by any loader using the manager when the loader
+		 * ended loading an item.
+		 *
+		 * @param {string} url - The URL of the loaded item.
+		 */
 		this.itemEnd = function ( url ) {
 
 			itemsLoaded ++;
@@ -60,6 +123,12 @@ class LoadingManager {
 
 		};
 
+		/**
+		 * This should be called by any loader using the manager when the loader
+		 * encounters an error when loading an item.
+		 *
+		 * @param {string} url - The URL of the item that produces an error.
+		 */
 		this.itemError = function ( url ) {
 
 			if ( scope.onError !== undefined ) {
@@ -70,6 +139,13 @@ class LoadingManager {
 
 		};
 
+		/**
+		 * Given a URL, uses the URL modifier callback (if any) and returns a
+		 * resolved URL. If no URL modifier is set, returns the original URL.
+		 *
+		 * @param {string} url - The URL to load.
+		 * @return {string} The resolved URL.
+		 */
 		this.resolveURL = function ( url ) {
 
 			if ( urlModifier ) {
@@ -82,6 +158,40 @@ class LoadingManager {
 
 		};
 
+		/**
+		 * If provided, the callback will be passed each resource URL before a
+		 * request is sent. The callback may return the original URL, or a new URL to
+		 * override loading behavior. This behavior can be used to load assets from
+		 * .ZIP files, drag-and-drop APIs, and Data URIs.
+		 *
+		 * ```js
+		 * const blobs = {'fish.gltf': blob1, 'diffuse.png': blob2, 'normal.png': blob3};
+		 *
+		 * const manager = new THREE.LoadingManager();
+		 *
+		 * // Initialize loading manager with URL callback.
+		 * const objectURLs = [];
+		 * manager.setURLModifier( ( url ) => {
+		 *
+		 * 	url = URL.createObjectURL( blobs[ url ] );
+		 * 	objectURLs.push( url );
+		 * 	return url;
+		 *
+		 * } );
+		 *
+		 * // Load as usual, then revoke the blob URLs.
+		 * const loader = new GLTFLoader( manager );
+		 * loader.load( 'fish.gltf', (gltf) => {
+		 *
+		 * 	scene.add( gltf.scene );
+		 * 	objectURLs.forEach( ( url ) => URL.revokeObjectURL( url ) );
+		 *
+		 * } );
+		 * ```
+		 *
+		 * @param {function(string):string} transform - URL modifier callback. Called with an URL and must return a resolved URL.
+		 * @return {LoadingManager} A reference to this loading manager.
+		 */
 		this.setURLModifier = function ( transform ) {
 
 			urlModifier = transform;
@@ -90,6 +200,20 @@ class LoadingManager {
 
 		};
 
+		/**
+		 * Registers a loader with the given regular expression. Can be used to
+		 * define what loader should be used in order to load specific files. A
+		 * typical use case is to overwrite the default loader for textures.
+		 *
+		 * ```js
+		 * // add handler for TGA textures
+		 * manager.addHandler( /\.tga$/i, new TGALoader() );
+		 * ```
+		 *
+		 * @param {string} regex - A regular expression.
+		 * @param {Loader} loader - A loader that should handle matched cases.
+		 * @return {LoadingManager} A reference to this loading manager.
+		 */
 		this.addHandler = function ( regex, loader ) {
 
 			handlers.push( regex, loader );
@@ -98,6 +222,12 @@ class LoadingManager {
 
 		};
 
+		/**
+		 * Removes the loader for the given regular expression.
+		 *
+		 * @param {string} regex - A regular expression.
+		 * @return {LoadingManager} A reference to this loading manager.
+		 */
 		this.removeHandler = function ( regex ) {
 
 			const index = handlers.indexOf( regex );
@@ -112,6 +242,12 @@ class LoadingManager {
 
 		};
 
+		/**
+		 * Can be used to retrieve the registered loader for the given file path.
+		 *
+		 * @param {string} file - The file path.
+		 * @return {?Loader} The registered loader. Returns `null` if no loader was found.
+		 */
 		this.getHandler = function ( file ) {
 
 			for ( let i = 0, l = handlers.length; i < l; i += 2 ) {
@@ -137,6 +273,12 @@ class LoadingManager {
 
 }
 
+/**
+ * The global default loading manager.
+ *
+ * @constant
+ * @type {LoadingManager}
+ */
 const DefaultLoadingManager = /*@__PURE__*/ new LoadingManager();
 
 export { DefaultLoadingManager, LoadingManager };

package/src/loaders/MaterialLoader.js

@@ -27,15 +27,46 @@ import {
 	Material,
 } from '../materials/Materials.js';
 
+/**
+ * Class for loading geometries. The files are internally
+ * loaded via {@link FileLoader}.
+ *
+ * ```js
+ * const loader = new THREE.MaterialLoader();
+ * const material = await loader.loadAsync( 'material.json' );
+ * ```
+ * This loader does not support node materials. Use {@link NodeMaterialLoader} instead.
+ *
+ * @augments Loader
+ */
 class MaterialLoader extends Loader {
 
+	/**
+	 * Constructs a new material loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
+
+		/**
+		 * A dictionary holding textures used by the material.
+		 *
+		 * @type {Object<string,Texture>}
+		 */
 		this.textures = {};
 
 	}
 
+	/**
+	 * Starts loading from the given URL and pass the loaded material 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(Material)} 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;
@@ -70,6 +101,12 @@ class MaterialLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given JSON object and returns a material.
+	 *
+	 * @param {Object} json - The serialized material.
+	 * @return {Material} The parsed material.
+	 */
 	parse( json ) {
 
 		const textures = this.textures;
@@ -335,6 +372,13 @@ class MaterialLoader extends Loader {
 
 	}
 
+	/**
+	 * Textures are not embedded in the material JSON so they have
+	 * to be injected before the loading process starts.
+	 *
+	 * @param {Object} value - A dictionary holding textures for material properties.
+	 * @return {MaterialLoader} A reference to this material loader.
+	 */
 	setTextures( value ) {
 
 		this.textures = value;
@@ -342,12 +386,25 @@ class MaterialLoader extends Loader {
 
 	}
 
+	/**
+	 * Creates a material for the given type.
+	 *
+	 * @param {string} type - The material type.
+	 * @return {Material} The new material.
+	 */
 	createMaterialFromType( type ) {
 
 		return MaterialLoader.createMaterialFromType( type );
 
 	}
 
+	/**
+	 * Creates a material for the given type.
+	 *
+	 * @static
+	 * @param {string} type - The material type.
+	 * @return {Material} The new material.
+	 */
 	static createMaterialFromType( type ) {
 
 		const materialLib = {

package/src/loaders/ObjectLoader.js

@@ -63,14 +63,43 @@ import { getTypedArray } from '../utils.js';
 import { Box3 } from '../math/Box3.js';
 import { Sphere } from '../math/Sphere.js';
 
+/**
+ * A loader for loading a JSON resource in the [JSON Object/Scene format]{@link https://github.com/mrdoob/three.js/wiki/JSON-Object-Scene-format-4}.
+ * The files are internally loaded via {@link FileLoader}.
+ *
+ * ```js
+ * const loader = new THREE.ObjectLoader();
+ * const obj = await loader.loadAsync( 'models/json/example.json' );
+ * scene.add( obj );
+ *
+ * // Alternatively, to parse a previously loaded JSON structure
+ * const object = await loader.parseAsync( a_json_object );
+ * scene.add( object );
+ * ```
+ *
+ * @augments Loader
+ */
 class ObjectLoader extends Loader {
 
+	/**
+	 * Constructs a new object loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
 	}
 
+	/**
+	 * Starts loading from the given URL and pass the loaded 3D object 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(Object3D)} 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;
@@ -117,6 +146,14 @@ class ObjectLoader extends Loader {
 
 	}
 
+	/**
+	 * Async version of {@link ObjectLoader#load}.
+	 *
+	 * @async
+	 * @param {string} url - The path/URL of the file to be loaded. This can also be a data URI.
+	 * @param {onProgressCallback} onProgress - Executed while the loading is in progress.
+	 * @return {Promise<Object3D>} A Promise that resolves with the loaded 3D object.
+	 */
 	async loadAsync( url, onProgress ) {
 
 		const scope = this;
@@ -145,6 +182,14 @@ class ObjectLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given JSON. This is used internally by {@link ObjectLoader#load}
+	 * but can also be used directly to parse a previously loaded JSON structure.
+	 *
+	 * @param {Object} json - The serialized 3D object.
+	 * @param {onLoad} onLoad - Executed when all resources (e.g. textures) have been fully loaded.
+	 * @return {Object3D} The parsed 3D object.
+	 */
 	parse( json, onLoad ) {
 
 		const animations = this.parseAnimations( json.animations );
@@ -191,6 +236,12 @@ class ObjectLoader extends Loader {
 
 	}
 
+	/**
+	 * Async version of {@link ObjectLoader#parse}.
+	 *
+	 * @param {Object} json - The serialized 3D object.
+	 * @return {Promise<Object3D>} A Promise that resolves with the parsed 3D object.
+	 */
 	async parseAsync( json ) {
 
 		const animations = this.parseAnimations( json.animations );
@@ -212,6 +263,8 @@ class ObjectLoader extends Loader {
 
 	}
 
+	// internals
+
 	parseShapes( json ) {
 
 		const shapes = {};

package/src/loaders/TextureLoader.js

@@ -2,14 +2,47 @@ import { ImageLoader } from './ImageLoader.js';
 import { Texture } from '../textures/Texture.js';
 import { Loader } from './Loader.js';
 
+/**
+ * Class for loading textures. Images are internally
+ * loaded via {@link ImageLoader}.
+ *
+ * ```js
+ * const loader = new THREE.TextureLoader();
+ * const texture = await loader.loadAsync( 'textures/land_ocean_ice_cloud_2048.jpg' );
+ *
+ * const material = new THREE.MeshBasicMaterial( { map:texture } );
+ * ```
+ * Please note that `TextureLoader` has dropped support for progress
+ * events in `r84`. For a `TextureLoader` that supports progress events, see
+ * [this thread]{@link https://github.com/mrdoob/three.js/issues/10439#issuecomment-293260145}.
+ *
+ * @augments Loader
+ */
 class TextureLoader extends Loader {
 
+	/**
+	 * Constructs a new texture loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
 	}
 
+	/**
+	 * Starts loading from the given URL and pass the fully loaded texture
+	 * to the `onLoad()` callback. The method also returns a new texture object which can
+	 * directly be used for material creation. If you do it this way, the texture
+	 * may pop up in your scene once the respective loading process is finished.
+	 *
+	 * @param {string} url - The path/URL of the file to be loaded. This can also be a data URI.
+	 * @param {function(Texture)} onLoad - Executed when the loading process has been finished.
+	 * @param {onProgressCallback} onProgress - Unsupported in this loader.
+	 * @param {onErrorCallback} onError - Executed when errors occur.
+	 * @return {Texture} The texture.
+	 */
 	load( url, onLoad, onProgress, onError ) {
 
 		const texture = new Texture();