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

package/examples/jsm/loaders/TDSLoader.js

@@ -15,22 +15,40 @@ 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
- * @constructor
+ * ```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
+ * @three_import import { TDSLoader } from 'three/addons/loaders/TDSLoader.js';
  */
-
 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 = [];
@@ -39,13 +57,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 {[type]} 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 ) {
 
@@ -86,12 +104,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 ) {
 
@@ -114,9 +131,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 ) {
 
@@ -157,9 +174,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 ) {
 
@@ -203,8 +220,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 ) {
 
@@ -234,9 +251,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 ) {
 
@@ -336,9 +353,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 ) {
 
@@ -398,7 +415,7 @@ class TDSLoader extends Loader {
 
 			} else if ( next.id === MESH_MATRIX ) {
 
-				this.debugMessage( '   Tranformation Matrix (TODO)' );
+				this.debugMessage( '   Transformation Matrix (TODO)' );
 
 				const values = [];
 				for ( let i = 0; i < 12; i ++ ) {
@@ -460,9 +477,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 ) {
 
@@ -528,9 +545,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 ) {
@@ -587,8 +604,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 ) {
@@ -613,9 +630,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 ) {
 
@@ -655,9 +672,9 @@ class TDSLoader extends Loader {
 	/**
 	 * Read percentage value.
 	 *
-	 * @method readPercentage
-	 * @param {Chunk} chunk Chunk to read data from.
-	 * @return {Number} Data read from the dataview.
+	 * @private
+	 * @param {Chunk} chunk - Chunk to read data from.
+	 * @return {number} Data read from the dataview.
 	 */
 	readPercentage( chunk ) {
 
@@ -667,11 +684,9 @@ class TDSLoader extends Loader {
 
 			case INT_PERCENTAGE:
 				return ( subChunk.readShort( ) / 100 );
-				break;
 
 			case FLOAT_PERCENTAGE:
 				return subChunk.readFloat( );
-				break;
 
 			default:
 				this.debugMessage( '      Unknown percentage chunk: ' + subChunk.hexId );
@@ -686,8 +701,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 ) {
 
@@ -701,17 +716,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 ) {
 
@@ -741,10 +759,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() {
 
@@ -770,10 +788,10 @@ class Chunk {
 	}
 
 	/**
-	 * return the ID of this chunk as Hex
+	 * Returns the ID of this chunk as Hex
 	 *
-	 * @method idToString
-	 * @return {String} hex-string of id
+	 * @private
+	 * @return {string} hex-string of id
 	 */
 	get hexId() {
 
@@ -790,8 +808,8 @@ class Chunk {
 	/**
 	 * Read byte value.
 	 *
-	 * @method readByte
-	 * @return {Number} Data read from the dataview.
+	 * @private
+	 * @return {number} Data read from the dataview.
 	 */
 	readByte() {
 
@@ -804,8 +822,8 @@ class Chunk {
 	/**
 	 * Read 32 bit float value.
 	 *
-	 * @method readFloat
-	 * @return {Number} Data read from the dataview.
+	 * @private
+	 * @return {number} Data read from the dataview.
 	 */
 	readFloat() {
 
@@ -827,8 +845,8 @@ class Chunk {
 	/**
 	 * Read 32 bit signed integer value.
 	 *
-	 * @method readInt
-	 * @return {Number} Data read from the dataview.
+	 * @private
+	 * @return {number} Data read from the dataview.
 	 */
 	readInt() {
 
@@ -841,8 +859,8 @@ class Chunk {
 	/**
 	 * Read 16 bit signed integer value.
 	 *
-	 * @method readShort
-	 * @return {Number} Data read from the dataview.
+	 * @private
+	 * @return {number} Data read from the dataview.
 	 */
 	readShort() {
 
@@ -855,8 +873,8 @@ class Chunk {
 	/**
 	 * Read 64 bit unsigned integer value.
 	 *
-	 * @method readDWord
-	 * @return {Number} Data read from the dataview.
+	 * @private
+	 * @return {number} Data read from the dataview.
 	 */
 	readDWord() {
 
@@ -869,8 +887,8 @@ class Chunk {
 	/**
 	 * Read 32 bit unsigned integer value.
 	 *
-	 * @method readWord
-	 * @return {Number} Data read from the dataview.
+	 * @private
+	 * @return {number} Data read from the dataview.
 	 */
 	readWord() {
 
@@ -883,8 +901,8 @@ class Chunk {
 	/**
 	 * Read NULL terminated ASCII string value from chunk-pos.
 	 *
-	 * @method readString
-	 * @return {String} Data read from the dataview.
+	 * @private
+	 * @return {string} Data read from the dataview.
 	 */
 	readString() {
 

package/examples/jsm/loaders/TGALoader.js

@@ -3,14 +3,37 @@ 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
+ * @three_import import { TGALoader } from 'three/addons/loaders/TGALoader.js';
+ */
 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
@@ -366,7 +389,6 @@ class TGALoader extends DataTextureLoader {
 
 					default:
 						throw new Error( 'THREE.TGALoader: Format not supported.' );
-						break;
 
 				}
 
@@ -392,7 +414,6 @@ class TGALoader extends DataTextureLoader {
 
 					default:
 						throw new Error( 'THREE.TGALoader: Format not supported.' );
-						break;
 
 				}
 

package/examples/jsm/loaders/TIFFLoader.js

@@ -6,14 +6,37 @@ 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
+ * @three_import import { TIFFLoader } from 'three/addons/loaders/TIFFLoader.js';
+ */
 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,50 @@ 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
+ * @three_import import { TTFLoader } from 'three/addons/loaders/TTFLoader.js';
  */
-
 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 +84,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 ) {
@@ -117,7 +152,19 @@ class TTFLoader extends Loader {
 
 					} );
 
-					glyphs[ String.fromCodePoint( glyph.unicode ) ] = token;
+					if ( Array.isArray( glyph.unicodes ) && glyph.unicodes.length > 0 ) {
+
+						glyph.unicodes.forEach( function ( unicode ) {
+
+							glyphs[ String.fromCodePoint( unicode ) ] = token;
+
+						} );
+
+					} else {
+
+						glyphs[ String.fromCodePoint( glyph.unicode ) ] = token;
+
+					}
 
 				}