@plastic-software/three 0.174.0 → 0.175.1

package/examples/jsm/loaders/TDSLoader.js

@@ -15,21 +15,39 @@ import {
 } from 'three';
 
 /**
- * Autodesk 3DS three.js file loader, based on lib3ds.
+ * A loader for the 3DS format, based on lib3ds.
  *
  * Loads geometry with uv and materials basic properties with texture support.
  *
- * @class TDSLoader
+ * ```js
+ * const loader = new TDSLoader();
+ * loader.setResourcePath( 'models/3ds/portalgun/textures/' );
+ * const object = await loader.loadAsync( 'models/3ds/portalgun/portalgun.3ds' );
+ * scene.add( object );
+ *
+ * @augments Loader
  */
-
 class TDSLoader extends Loader {
 
+	/**
+	 * Constructs a new 3DS loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
+		/**
+		 * Whether debug mode should be enabled or not.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.debug = false;
 
+		// internals
+
 		this.group = null;
 
 		this.materials = [];
@@ -38,13 +56,13 @@ class TDSLoader extends Loader {
 	}
 
 	/**
-	 * Load 3ds file from url.
+	 * Starts loading from the given URL and passes the loaded 3DS asset
+	 * to the `onLoad()` callback.
 	 *
-	 * @method load
-	 * @param {string} url URL for the file.
-	 * @param {Function} onLoad onLoad callback, receives group Object3D as argument.
-	 * @param {Function} onProgress onProgress callback.
-	 * @param {Function} onError onError 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 ) {
 
@@ -85,12 +103,11 @@ class TDSLoader extends Loader {
 	}
 
 	/**
-	 * Parse arraybuffer data and load 3ds file.
+	 * Parses the given 3DS data and returns the resulting data.
 	 *
-	 * @method parse
-	 * @param {ArrayBuffer} arraybuffer Arraybuffer data to be loaded.
-	 * @param {string} path Path for external resources.
-	 * @return {Group} Group loaded from 3ds file.
+	 * @param {ArrayBuffer} arraybuffer - The raw 3DS data as an array buffer.
+	 * @param {string} path - The asset path.
+	 * @return {Group} The parsed asset represented as a group.
 	 */
 	parse( arraybuffer, path ) {
 
@@ -113,9 +130,9 @@ class TDSLoader extends Loader {
 	/**
 	 * Decode file content to read 3ds data.
 	 *
-	 * @method readFile
-	 * @param {ArrayBuffer} arraybuffer Arraybuffer data to be loaded.
-	 * @param {string} path Path for external resources.
+	 * @private
+	 * @param {ArrayBuffer} arraybuffer - Arraybuffer data to be loaded.
+	 * @param {string} path - Path for external resources.
 	 */
 	readFile( arraybuffer, path ) {
 
@@ -156,9 +173,9 @@ class TDSLoader extends Loader {
 	/**
 	 * Read mesh data chunk.
 	 *
-	 * @method readMeshData
-	 * @param {Chunk} chunk to read mesh from
-	 * @param {string} path Path for external resources.
+	 * @private
+	 * @param {Chunk} chunk - to read mesh from
+	 * @param {string} path - Path for external resources.
 	 */
 	readMeshData( chunk, path ) {
 
@@ -202,8 +219,8 @@ class TDSLoader extends Loader {
 	/**
 	 * Read named object chunk.
 	 *
-	 * @method readNamedObject
-	 * @param {Chunk} chunk Chunk in use.
+	 * @private
+	 * @param {Chunk} chunk - Chunk in use.
 	 */
 	readNamedObject( chunk ) {
 
@@ -233,9 +250,9 @@ class TDSLoader extends Loader {
 	/**
 	 * Read material data chunk and add it to the material list.
 	 *
-	 * @method readMaterialEntry
-	 * @param {Chunk} chunk Chunk in use.
-	 * @param {string} path Path for external resources.
+	 * @private
+	 * @param {Chunk} chunk - Chunk in use.
+	 * @param {string} path - Path for external resources.
 	 */
 	readMaterialEntry( chunk, path ) {
 
@@ -335,9 +352,9 @@ class TDSLoader extends Loader {
 	/**
 	 * Read mesh data chunk.
 	 *
-	 * @method readMesh
-	 * @param {Chunk} chunk Chunk in use.
-	 * @return {Mesh} The parsed mesh.
+	 * @private
+	 * @param {Chunk} chunk - Chunk in use.
+	 * @return {Mesh} - The parsed mesh.
 	 */
 	readMesh( chunk ) {
 
@@ -459,9 +476,9 @@ class TDSLoader extends Loader {
 	/**
 	 * Read face array data chunk.
 	 *
-	 * @method readFaceArray
-	 * @param {Chunk} chunk Chunk in use.
-	 * @param {Mesh} mesh Mesh to be filled with the data read.
+	 * @private
+	 * @param {Chunk} chunk - Chunk in use.
+	 * @param {Mesh} mesh - Mesh to be filled with the data read.
 	 */
 	readFaceArray( chunk, mesh ) {
 
@@ -527,9 +544,9 @@ class TDSLoader extends Loader {
 	/**
 	 * Read texture map data chunk.
 	 *
-	 * @method readMap
-	 * @param {Chunk} chunk Chunk in use.
-	 * @param {string} path Path for external resources.
+	 * @private
+	 * @param {Chunk} chunk - Chunk in use.
+	 * @param {string} path - Path for external resources.
 	 * @return {Texture} Texture read from this data chunk.
 	 */
 	readMap( chunk, path ) {
@@ -586,8 +603,8 @@ class TDSLoader extends Loader {
 	/**
 	 * Read material group data chunk.
 	 *
-	 * @method readMaterialGroup
-	 * @param {Chunk} chunk Chunk in use.
+	 * @private
+	 * @param {Chunk} chunk - Chunk in use.
 	 * @return {Object} Object with name and index of the object.
 	 */
 	readMaterialGroup( chunk ) {
@@ -612,9 +629,9 @@ class TDSLoader extends Loader {
 	/**
 	 * Read a color value.
 	 *
-	 * @method readColor
-	 * @param {Chunk} chunk Chunk.
-	 * @return {Color} Color value read..
+	 * @private
+	 * @param {Chunk} chunk - Chunk.
+	 * @return {Color} Color value read.
 	 */
 	readColor( chunk ) {
 
@@ -654,8 +671,8 @@ class TDSLoader extends Loader {
 	/**
 	 * Read percentage value.
 	 *
-	 * @method readPercentage
-	 * @param {Chunk} chunk Chunk to read data from.
+	 * @private
+	 * @param {Chunk} chunk - Chunk to read data from.
 	 * @return {number} Data read from the dataview.
 	 */
 	readPercentage( chunk ) {
@@ -685,8 +702,8 @@ class TDSLoader extends Loader {
 	 *
 	 * Is controlled by a flag to show or hide debug messages.
 	 *
-	 * @method debugMessage
-	 * @param {Object} message Debug message to print to the console.
+	 * @private
+	 * @param {Object} message - Debug message to print to the console.
 	 */
 	debugMessage( message ) {
 
@@ -700,17 +717,20 @@ class TDSLoader extends Loader {
 
 }
 
-
-/** Read data/sub-chunks from chunk */
+/**
+ * Read data/sub-chunks from chunk.
+ *
+ * @private
+ */
 class Chunk {
 
 	/**
 	 * Create a new chunk
 	 *
-	 * @class Chunk
-	 * @param {DataView} data DataView to read from.
-	 * @param {number} position in data.
-	 * @param {Function} debugMessage logging callback.
+	 * @private
+	 * @param {DataView} data - DataView to read from.
+	 * @param {number} position - In data.
+	 * @param {Function} debugMessage - Logging callback.
 	 */
 	constructor( data, position, debugMessage ) {
 
@@ -740,10 +760,10 @@ class Chunk {
 	}
 
 	/**
-	 * read a sub cchunk.
+	 * Reads a sub cchunk.
 	 *
-	 * @method readChunk
-	 * @return {Chunk | null} next sub chunk
+	 * @private
+	 * @return {Chunk | null} next sub chunk.
 	 */
 	readChunk() {
 
@@ -769,9 +789,9 @@ class Chunk {
 	}
 
 	/**
-	 * return the ID of this chunk as Hex
+	 * Returns the ID of this chunk as Hex
 	 *
-	 * @method idToString
+	 * @private
 	 * @return {string} hex-string of id
 	 */
 	get hexId() {
@@ -789,7 +809,7 @@ class Chunk {
 	/**
 	 * Read byte value.
 	 *
-	 * @method readByte
+	 * @private
 	 * @return {number} Data read from the dataview.
 	 */
 	readByte() {
@@ -803,7 +823,7 @@ class Chunk {
 	/**
 	 * Read 32 bit float value.
 	 *
-	 * @method readFloat
+	 * @private
 	 * @return {number} Data read from the dataview.
 	 */
 	readFloat() {
@@ -826,7 +846,7 @@ class Chunk {
 	/**
 	 * Read 32 bit signed integer value.
 	 *
-	 * @method readInt
+	 * @private
 	 * @return {number} Data read from the dataview.
 	 */
 	readInt() {
@@ -840,7 +860,7 @@ class Chunk {
 	/**
 	 * Read 16 bit signed integer value.
 	 *
-	 * @method readShort
+	 * @private
 	 * @return {number} Data read from the dataview.
 	 */
 	readShort() {
@@ -854,7 +874,7 @@ class Chunk {
 	/**
 	 * Read 64 bit unsigned integer value.
 	 *
-	 * @method readDWord
+	 * @private
 	 * @return {number} Data read from the dataview.
 	 */
 	readDWord() {
@@ -868,7 +888,7 @@ class Chunk {
 	/**
 	 * Read 32 bit unsigned integer value.
 	 *
-	 * @method readWord
+	 * @private
 	 * @return {number} Data read from the dataview.
 	 */
 	readWord() {
@@ -882,7 +902,7 @@ class Chunk {
 	/**
 	 * Read NULL terminated ASCII string value from chunk-pos.
 	 *
-	 * @method readString
+	 * @private
 	 * @return {string} Data read from the dataview.
 	 */
 	readString() {

package/examples/jsm/loaders/TGALoader.js

@@ -3,14 +3,36 @@ import {
 	LinearMipmapLinearFilter
 } from 'three';
 
+/**
+ * A loader for the TGA texture format.
+ *
+ * ```js
+ * const loader = new TGALoader();
+ * const texture = await loader.loadAsync( 'textures/crate_color8.tga' );
+ * texture.colorSpace = THREE.SRGBColorSpace; // only for color textures
+ * ```
+ *
+ * @augments DataTextureLoader
+ */
 class TGALoader extends DataTextureLoader {
 
+	/**
+	 * Constructs a new TGA loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
 	}
 
+	/**
+	 * Parses the given TGA texture data.
+	 *
+	 * @param {ArrayBuffer} buffer - The raw texture data.
+	 * @return {DataTextureLoader~TexData} An object representing the parsed texture data.
+	 */
 	parse( buffer ) {
 
 		// reference from vthibault, https://github.com/vthibault/roBrowser/blob/master/src/Loaders/Targa.js

package/examples/jsm/loaders/TIFFLoader.js

@@ -6,14 +6,36 @@ import {
 
 import UTIF from '../libs/utif.module.js';
 
+/**
+ * A loader for the TIFF texture format.
+ *
+ * ```js
+ * const loader = new TIFFLoader();
+ * const texture = await loader.loadAsync( 'textures/tiff/crate_lzw.tif' );
+ * texture.colorSpace = THREE.SRGBColorSpace;
+ * ```
+ *
+ * @augments DataTextureLoader
+ */
 class TIFFLoader extends DataTextureLoader {
 
+	/**
+	 * Constructs a new TIFF loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
 	}
 
+	/**
+	 * Parses the given TIFF texture data.
+	 *
+	 * @param {ArrayBuffer} buffer - The raw texture data.
+	 * @return {DataTextureLoader~TexData} An object representing the parsed texture data.
+	 */
 	parse( buffer ) {
 
 		const ifds = UTIF.decode( buffer );

package/examples/jsm/loaders/TTFLoader.js

@@ -5,21 +5,49 @@ import {
 import opentype from '../libs/opentype.module.js';
 
 /**
- * Requires opentype.js to be included in the project.
+ * A loader for the TTF format.
+ *
  * Loads TTF files and converts them into typeface JSON that can be used directly
  * to create THREE.Font objects.
+ *
+ * ```js
+ * const loader = new TTFLoader();
+ * const json = await loader.loadAsync( 'fonts/ttf/kenpixel.ttf' );
+ * const font = new Font( json );
+ * ```
+ *
+ * @augments Loader
  */
-
 class TTFLoader extends Loader {
 
+	/**
+	 * Constructs a new TTF loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
+		/**
+		 * Whether the TTF commands should be reversed or not.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.reversed = false;
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded TTF 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(Object)} 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;
@@ -55,6 +83,12 @@ class TTFLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given TTF data and returns a JSON for creating a font.
+	 *
+	 * @param {ArrayBuffer} arraybuffer - The raw TTF data as an array buffer.
+	 * @return {Object} The result JSON.
+	 */
 	parse( arraybuffer ) {
 
 		function convert( font, reversed ) {

package/examples/jsm/loaders/USDZLoader.js

@@ -116,14 +116,41 @@ class USDAParser {
 
 }
 
+/**
+ * A loader for the USDZ format.
+ *
+ * USDZ files that use USDC internally are not yet supported, only USDA.
+ *
+ * ```js
+ * const loader = new USDZLoader();
+ * const model = await loader.loadAsync( 'saeukkang.usdz' );
+ * scene.add( model );
+ * ```
+ *
+ * @augments Loader
+ */
 class USDZLoader extends Loader {
 
+	/**
+	 * Constructs a new USDZ loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded USDZ 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 scope = this;
@@ -159,6 +186,12 @@ class USDZLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given USDZ data and returns the resulting group.
+	 *
+	 * @param {ArrayBuffer} buffer - The raw USDZ data as an array buffer.
+	 * @return {Group} The parsed asset as a group.
+	 */
 	parse( buffer ) {
 
 		const parser = new USDAParser();
@@ -173,7 +206,7 @@ class USDZLoader extends Loader {
 
 				if ( filename.endsWith( 'png' ) ) {
 
-					const blob = new Blob( [ zip[ filename ] ], { type: { type: 'image/png' } } );
+					const blob = new Blob( [ zip[ filename ] ], { type: 'image/png' } );
 					data[ filename ] = URL.createObjectURL( blob );
 
 				}

package/examples/jsm/loaders/UltraHDRLoader.js

@@ -12,10 +12,8 @@ import {
 	UVMapping,
 } from 'three';
 
-// UltraHDR Image Format - https://developer.android.com/media/platform/hdr-image-format
-// HDR/EXR to UltraHDR Converter - https://gainmap-creator.monogrid.com/
-
 /**
+ * UltraHDR Image Format - https://developer.android.com/media/platform/hdr-image-format
  *
  * Short format brief:
  *
@@ -30,36 +28,68 @@ import {
  * Binary image storages are prefixed with a unique 0xFFD8 16-bit descriptor.
  */
 
+
+// Calculating this SRGB powers is extremely slow for 4K images and can be sufficiently precalculated for a 3-4x speed boost
+const SRGB_TO_LINEAR = Array( 1024 )
+	.fill( 0 )
+	.map( ( _, value ) =>
+		Math.pow( ( value / 255 ) * 0.9478672986 + 0.0521327014, 2.4 )
+	);
+
 /**
+ * A loader for the Ultra HDR Image Format.
+ *
+ * Existing HDR or EXR textures can be converted to Ultra HDR with this [tool]{@link https://gainmap-creator.monogrid.com/}.
+ *
  * Current feature set:
  * - JPEG headers (required)
  * - XMP metadata (required)
- *  - XMP validation (not implemented)
+ * - XMP validation (not implemented)
  * - EXIF profile (not implemented)
  * - ICC profile (not implemented)
  * - Binary storage for SDR & HDR images (required)
  * - Gainmap metadata (required)
  * - Non-JPEG image formats (not implemented)
  * - Primary image as an HDR image (not implemented)
+ *
+ * ```js
+ * const loader = new UltraHDRLoader();
+ * const texture = await loader.loadAsync( 'textures/equirectangular/ice_planet_close.jpg' );
+ * texture.mapping = THREE.EquirectangularReflectionMapping;
+ *
+ * scene.background = texture;
+ * scene.environment = texture;
+ * ```
+ *
+ * @augments Loader
  */
-
-/* Calculating this SRGB powers is extremely slow for 4K images and can be sufficiently precalculated for a 3-4x speed boost */
-const SRGB_TO_LINEAR = Array( 1024 )
-	.fill( 0 )
-	.map( ( _, value ) =>
-		Math.pow( ( value / 255 ) * 0.9478672986 + 0.0521327014, 2.4 )
-	);
-
 class UltraHDRLoader extends Loader {
 
+	/**
+	 * Constructs a new Ultra HDR loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
+		/**
+		 * The texture type.
+		 *
+		 * @type {(HalfFloatType|FloatType)}
+		 * @default HalfFloatType
+		 */
 		this.type = HalfFloatType;
 
 	}
 
+	/**
+	 * Sets the texture type.
+	 *
+	 * @param {(HalfFloatType|FloatType)} value - The texture type to set.
+	 * @return {RGBELoader} A reference to this loader.
+	 */
 	setDataType( value ) {
 
 		this.type = value;
@@ -68,6 +98,12 @@ class UltraHDRLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given Ultra HDR texture data.
+	 *
+	 * @param {ArrayBuffer} buffer - The raw texture data.
+	 * @param {Function} onLoad - The `onLoad` callback.
+	 */
 	parse( buffer, onLoad ) {
 
 		const xmpMetadata = {
@@ -262,6 +298,16 @@ class UltraHDRLoader extends Loader {
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded Ultra HDR texture
+	 * to the `onLoad()` callback.
+	 *
+	 * @param {string} url - The path/URL of the files to be loaded. This can also be a data URI.
+	 * @param {function(DataTexture, Object)} 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 {DataTexture} The Ultra HDR texture.
+	 */
 	load( url, onLoad, onProgress, onError ) {
 
 		const texture = new DataTexture(