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

package/src/loaders/Loader.js

@@ -1,15 +1,64 @@
 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](https://developer.mozilla.org/en-US/docs/Glossary/Request_header)
+		 * used in HTTP request.
+		 *
+		 * @type {Object<string, any>}
+		 */
 		this.requestHeader = {};
 
 		if ( typeof __THREE_DEVTOOLS__ !== 'undefined' ) {
@@ -20,8 +69,25 @@ class Loader {
 
 	}
 
+	/**
+	 * This method needs to be implemented by all concrete loaders. It holds the
+	 * logic for loading assets from the backend.
+	 *
+	 * @abstract
+	 * @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;
@@ -34,8 +100,22 @@ class Loader {
 
 	}
 
+	/**
+	 * This method needs to be implemented by all concrete loaders. It holds the
+	 * logic for parsing the asset into three.js entities.
+	 *
+	 * @abstract
+	 * @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;
@@ -43,6 +123,15 @@ class Loader {
 
 	}
 
+	/**
+	 * Whether the XMLHttpRequest uses credentials such as cookies, authorization
+	 * headers or TLS client certificates, see [XMLHttpRequest.withCredentials](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;
@@ -50,6 +139,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;
@@ -57,6 +152,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;
@@ -64,6 +165,13 @@ class Loader {
 
 	}
 
+	/**
+	 * Sets the given request header.
+	 *
+	 * @param {Object} requestHeader - A [request header](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;
@@ -71,8 +179,44 @@ class Loader {
 
 	}
 
+	/**
+	 * This method can be implemented in loaders for aborting ongoing requests.
+	 *
+	 * @abstract
+	 * @return {Loader} A reference to this instance.
+	 */
+	abort() {
+
+		return this;
+
+	}
+
 }
 
+/**
+ * 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,52 @@ 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;
 
+		/**
+		 * Used for aborting ongoing requests in loaders using this manager.
+		 *
+		 * @private
+		 * @type {AbortController | null}
+		 */
+		this._abortController = null;
+
+		/**
+		 * 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 +101,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 +131,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 +147,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 +166,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 +208,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 +230,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 +250,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 ) {
@@ -133,10 +277,53 @@ class LoadingManager {
 
 		};
 
+		/**
+		 * Can be used to abort ongoing loading requests in loaders using this manager.
+		 * The abort only works if the loaders implement {@link Loader#abort} and `AbortSignal.any()`
+		 * is supported in the browser.
+		 *
+		 * @return {LoadingManager} A reference to this loading manager.
+		 */
+		this.abort = function () {
+
+
+			this.abortController.abort();
+			this._abortController = null;
+
+			return this;
+
+		};
+
+	}
+
+	// TODO: Revert this back to a single member variable once this issue has been fixed
+	// https://github.com/cloudflare/workerd/issues/3657
+
+	/**
+	 * Used for aborting ongoing requests in loaders using this manager.
+	 *
+	 * @type {AbortController}
+	 */
+	get abortController() {
+
+		if ( ! this._abortController ) {
+
+			this._abortController = new AbortController();
+
+		}
+
+		return this._abortController;
+
 	}
 
 }
 
+/**
+ * The global default loading manager.
+ *
+ * @constant
+ * @type {LoadingManager}
+ */
 const DefaultLoadingManager = /*@__PURE__*/ new LoadingManager();
 
 export { DefaultLoadingManager, LoadingManager };

package/src/loaders/MaterialLoader.js

@@ -26,16 +26,48 @@ import {
 	LineBasicMaterial,
 	Material,
 } from '../materials/Materials.js';
-
+import { error, warn } from '../utils.js';
+
+/**
+ * Class for loading materials. 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;
@@ -58,7 +90,7 @@ class MaterialLoader extends Loader {
 
 				} else {
 
-					console.error( e );
+					error( e );
 
 				}
 
@@ -70,6 +102,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;
@@ -78,7 +116,7 @@ class MaterialLoader extends Loader {
 
 			if ( textures[ name ] === undefined ) {
 
-				console.warn( 'THREE.MaterialLoader: Undefined texture', name );
+				warn( 'MaterialLoader: Undefined texture', name );
 
 			}
 
@@ -165,6 +203,7 @@ class MaterialLoader extends Loader {
 		if ( json.alphaToCoverage !== undefined ) material.alphaToCoverage = json.alphaToCoverage;
 		if ( json.premultipliedAlpha !== undefined ) material.premultipliedAlpha = json.premultipliedAlpha;
 		if ( json.forceSinglePass !== undefined ) material.forceSinglePass = json.forceSinglePass;
+		if ( json.allowOverride !== undefined ) material.allowOverride = json.allowOverride;
 
 		if ( json.visible !== undefined ) material.visible = json.visible;
 
@@ -335,6 +374,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 +388,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 = {