OBJLoader2 and OBJLoader2Parallel fully updated and aligned docs and js docs.

docs/examples/en/loaders/OBJLoader2.html

@@ -48,24 +48,20 @@
 		</p>
 
 
+		<h2>Properties</h2>
+		<p>See the base [page:Loader] class for common properties.</p>
+
+
 		<h2>Methods</h2>
+		<p>See the base [page:Loader] class for common methods.</p>
+
 
 		<h3>[method:Object3D parse]( [param:arraybuffer content]|[param:String content] )</h3>
 		<p>
 			[[page:arraybuffer content]|[page:String content]] OBJ data as Uint8Array or String
 		</p>
 		<p>
-			Parses OBJ data synchronously from arraybuffer or string and returns the [page:Object3D loaderRoorNode].
-		</p>
-
-
-		<h3>[method:Object3D parseAsync]( [param:arraybuffer content], [param:Function onLoad] )</h3>
-		<p>
-			[page:arraybuffer content] - OBJ data as Uint8Array<br>
-			[page:Function onLoad] - Called after worker successfully completed loading<br>
-		</p>
-		<p>
-			Parses OBJ content asynchronously from arraybuffer.
+			Parses OBJ data synchronously from arraybuffer or string and returns the [page:Object3D baseObject3d].
 		</p>
 
 
@@ -76,128 +72,127 @@
 			[page:Function onProgress] - (optional) A function to be called while the loading is in progress. The argument will be the XMLHttpRequest instance, which contains [page:Integer total] and [page:Integer loaded] bytes.<br>
 			[page:Function onError] - (optional) A function to be called if an error occurs during loading. The function receives the error as an argument.<br>
 			[page:Function onMeshAlter] - (optional) A function to be called after a new mesh raw data becomes available for alteration.<br>
-			[page:boolean useAsync] - (optional) If true, uses async loading with worker, if false loads data synchronously.
 		</p>
 		<p>
 			Use this convenient method to load a file at the given URL. By default the fileLoader uses an ArrayBuffer.
 		</p>
 
 
-		<h3>[method:null run]( [param:LoaderSupport.PrepData params], [param:LoaderSupport.WorkerSupport workerSupportExternal] )</h3>
+		<h3>[method:OBJLoader2 setLogging]( [param:Boolean enabled], [param:Boolean debug] )</h3>
 		<p>
-			[page:LoaderSupport.PrepData params] - prepData All parameters and resources required for execution<br>
-			[page:LoaderSupport.WorkerSupport workerSupportExternal] - Use pre-existing WorkerSupport
+			[page:Boolean enabled] True or false.<br>
+			[page:Boolean debug] True or false.
 		</p>
 		<p>
-			Run the loader according the provided instructions.
+			Enable or disable logging in general (except warn and error), plus enable or disable debug logging.
 		</p>
 
 
-		<h3>[method:null setLogging]( [param:Boolean enabled], [param:Boolean debug] )</h3>
+		<h3>[method:OBJLoader2 setMaterialPerSmoothingGroup] ( [param:boolean materialPerSmoothingGroup] )</h3>
 		<p>
-			[page:Boolean enabled] True or false.<br>
-			[page:Boolean debug] True or false.
+			[page:boolean materialPerSmoothingGroup]
 		</p>
 		<p>
-			Enable or disable logging in general (except warn and error), plus enable or disable debug logging.
+			Tells whether a material shall be created per smoothing group.
 		</p>
 
 
-		<h3>[method:null setModelName] ( [param:String modelName] )</h3>
+		<h3>[method:OBJLoader2 setUseOAsMesh] ( [param:boolean useOAsMesh] )</h3>
 		<p>
-			[page:String modelName]
+			[page:boolean useOAsMesh]
 		</p>
 		<p>
-			Set the name of the model.
+			Usually 'o' is meta-information and does not result in creation of new meshes, but mesh creation on occurrence of "o" can be enforced.
 		</p>
 
 
-		<h3>[method:null setPath] ( [param:String path] )</h3>
+		<h3>[method:OBJLoader2 setUseIndices]( [param:Boolean useIndices] )</h3>
 		<p>
-			[page:String path] - URL
+			[page:Boolean useIndices]
 		</p>
 		<p>
-			The URL of the base path.
+			Instructs loaders to create indexed [page:BufferGeometry].
 		</p>
 
 
-		<h3>[method:null setResourcePath] ( [param:String resourcePath] )</h3>
+		<h3>[method:OBJLoader2 setDisregardNormals]( [param:Boolean disregardNormals] )</h3>
 		<p>
-			[page:String resourcePath] - URL
+			[page:Boolean disregardNormals]
 		</p>
 		<p>
-			Allows to specify resourcePath for dependencies of specified resource.
+			Tells whether normals should be completely disregarded and regenerated.
 		</p>
 
 
-		<h3>[method:null setStreamMeshesTo] ( [param:Object3D streamMeshesTo] )</h3>
+		<h3>[method:OBJLoader2 setModelName] ( [param:String modelName] )</h3>
+		<p>
+			[page:String modelName]
+		</p>
 		<p>
-			[page:Object3D streamMeshesTo] - Object already attached to scenegraph where new meshes will be attached to
+			Set the name of the model.
+		</p>
+
+
+		<h3>[method:OBJLoader2 setBaseObject3d] ( [param:Object3d baseObject3d] )</h3>
+		<p>
+			[page:Object3D baseObject3d - Object already attached to scenegraph where new meshes will be attached to
 		</p>
 		<p>
 			Set the node where the loaded objects will be attached directly.
 		</p>
 
 
-		<h3>[method:null setMaterials] ( Array of [param:Material materials] )</h3>
+		<h3>[method:OBJLoader2 setMaterials] ( [param:Object materials] )</h3>
 		<p>
-			Array of [page:Material materials] - Array of [page:Material Materials]
+			[page:Object materials] -  materials Object with named [page:Material Materials]
 		</p>
 		<p>
-			Set materials loaded by MTLLoader or any other supplier of an Array of [page:Material Materials].
+			Add materials as associated array.
 		</p>
 
 
-		<h3>[method:null setUseIndices]( [param:Boolean useIndices] )</h3>
+		<h3>[method:OBJLoader2 setCallbackOnLoad] ( [param:Function onLoad] )</h3>
 		<p>
-			[page:Boolean useIndices]
+			[page:Function onLoad]
 		</p>
 		<p>
-			Instructs loaders to create indexed [page:BufferGeometry].
+			Register a function that is called when parsing was completed.
 		</p>
 
 
-		<h3>[method:null setDisregardNormals]( [param:Boolean disregardNormals] )</h3>
+		<h3>[method:OBJLoader2 setCallbackOnAssetAvailable] ( [param:Function onAssetAvailable] )</h3>
 		<p>
-			[page:Boolean disregardNormals]
+			[page:Function onAssetAvailable]
 		</p>
 		<p>
-			Tells whether normals should be completely disregarded and regenerated.
+			Register a function that is called once an asset (mesh/material) becomes available.
 		</p>
 
 
-		<h3>[method:null setMaterialPerSmoothingGroup] ( [param:boolean materialPerSmoothingGroup] )</h3>
+		<h3>[method:OBJLoader2 setCallbackOnProgress] ( [param:Function onProgress] )</h3>
 		<p>
-			[page:boolean materialPerSmoothingGroup]
+			[page:Function onProgress]
 		</p>
 		<p>
-			Tells whether a material shall be created per smoothing group.
+			Register a function that is used to report overall processing progress.
 		</p>
 
 
-		<h3>[method:null onProgress]( [param:String type], [param:String text], [param:Number numericalValue] )</h3>
+		<h3>[method:OBJLoader2 setCallbackOnError] ( [param:Function onError] )</h3>
 		<p>
-			[page:String type] - The type of event<br>
-			[page:String text] - Textual description of the event<br>
-			[page:Number numericalValue] - Numerical value describing the progress
+			[page:Function onError]
 		</p>
 		<p>
-			Announce feedback which is give to the registered [page:LoaderSupport.Callbacks].
+			Register an error handler function that is called if errors occur. It can decide to just log or to throw an exception.
 		</p>
 
 
-		<h3>[method:null loadMtl]( [param:String url], [param:Object content], [param:Function callbackOnLoad], [param:String crossOrigin], [param:Object materialOptions]) </h3>
+		<h3>[method:OBJLoader2 setCallbackOnMeshAlter] ( [param:Function onMeshAlter] )</h3>
 		<p>
-			[page:String url] - URL to the file<br>
-			[page:Object content] - The file content as arraybuffer or text<br>
-			[page:Function onLoad] - Callback to be called after successful load<br>
-			[page:Function onProgress] - (optional) A function to be called while the loading is in progress. The argument will be the XMLHttpRequest instance, which contains [page:Integer total] and [page:Integer loaded] bytes.<br>
-			[page:Function onError] - (optional) A function to be called if an error occurs during loading. The function receives the error as an argument.<br>
-			[page:String crossOrigin] - (optional) CORS value<br>
-			[page:Function materialOptions] - (optional) Set material loading options for MTLLoader
+			[page:Function onMeshAlter]
 		</p>
 		<p>
-			Utility method for loading an mtl file according resource description. Provide url or content.
+			Register a function that is called once a single mesh is available and it could be altered by the supplied function.
 		</p>
 
 

docs/examples/en/loaders/OBJLoader2Parallel.html

@@ -46,39 +46,64 @@
 			[page:LoadingManager manager] - The [page:LoadingManager loadingManager] for the loader to use. Default is [page:LoadingManager THREE.DefaultLoadingManager].<br>
 		</p>
 		<p>
-			Creates a new [name]. Use it to load OBJ data from files or to parse OBJ data from arraybuffer or text.
+			Creates a new [name]. Use it to load OBJ data from files or to parse OBJ data from arraybuffer.
+			It extends [page:OBJLoader2]  with the capability to run the parser in a web worker.
 		</p>
 
 
+		<h2>Properties</h2>
+		<p>See the base [page:OBJLoader2] class for common properties.</p>
+
+
 		<h2>Methods</h2>
+		<p>See the base [page:OBJLoader2] class for common methods. </p>
+
+
+		<h3>[method:Object3D parse]</h3>
+		<p>See [page:OBJLoader2.parse].<br>
+			The callback [page:OBJLoader2.setCallbackOnLoad OBJLoader2.onLoad] needs to be set to be able to receive the content if used in parallel mode.
+			Fallback is possible via [page:OBJLoader2Parallel.setExecuteParallel].
+		</p>
+
+
+		<h3>[method:null load]</h3>
+		<p>See [page:OBJLoader2.load].</p>
+
 
-		<h3>[method:Object3D parse]( [param:arraybuffer content]|[param:String content] )</h3>
+		<h3>[method:OBJLoader2Parallel setExecuteParallel] ( [param:boolean executeParallel] )</h3>
 		<p>
-			[[page:arraybuffer content]|[page:String content]] OBJ data as Uint8Array or String
+			[page:boolean executeParallel] - True or False
 		</p>
 		<p>
-			Parses OBJ data synchronously from arraybuffer or string and returns the [page:Object3D loaderRoorNode].
+			Execution of parse in parallel via Worker is default, but synchronous [page:OBJLoader2] parsing can be enforced via false here.
 		</p>
 
 
-		<h3>[method:null load]( [param:String url], [param:Function onLoad], [param:Function onProgress], [param:Function onError], [param:Function onMeshAlter], [param:boolean useAsync] )</h3>
+		<h3>[method:OBJLoader2Parallel setPreferJsmWorker] ( [param:boolean preferJsmWorker] )</h3>
 		<p>
-			[page:String url] - A string containing the path/URL of the file to be loaded.<br>
-			[page:Function onLoad] - A function to be called after loading is successfully completed. The function receives loaded [page:Object3D] as an argument.<br>
-			[page:Function onProgress] - (optional) A function to be called while the loading is in progress. The argument will be the XMLHttpRequest instance, which contains [page:Integer total] and [page:Integer loaded] bytes.<br>
-			[page:Function onError] - (optional) A function to be called if an error occurs during loading. The function receives the error as an argument.<br>
-			[page:Function onMeshAlter] - (optional) A function to be called after a new mesh raw data becomes available for alteration.<br>
-			[page:boolean useAsync] - (optional) If true, uses async loading with worker, if false loads data synchronously.
+			[page:boolean preferJsmWorker] - True or False
 		</p>
 		<p>
-			Use this convenient method to load a file at the given URL. By default the fileLoader uses an ArrayBuffer.
+			Set whether jsm modules in workers should be used. This requires browser support which is currently only experimental.
+		</p>
+
+
+		<h3>[method:WorkerExecutionSupport getWorkerExecutionSupport] ()</h3>
+		<p>
+			Allow to get hold of [page:WorkerExecutionSupport] for configuration purposes.
+		</p>
+
+
+		<h3>[method:CodeBuilderInstructions buildWorkerCode] ()</h3>
+		<p>
+			Provide instructions on what is to be contained in the worker.
 		</p>
 
 
 		<h2>Source</h2>
 
 		<p>
-			[link:https://github.com/mrdoob/three.js/blob/master/examples/jsm/loaders/OBJLoader2Parallel.js examples/jsm/loaders/OBJLoader2.js]
+			[link:https://github.com/mrdoob/three.js/blob/master/examples/jsm/loaders/OBJLoader2Parallel.js examples/jsm/loaders/OBJLoader2Parallel.js]
 		</p>
 	</body>
 </html>

examples/jsm/loaders/OBJLoader2.js

@@ -15,10 +15,10 @@ import { MeshReceiver } from "./obj2/shared/MeshReceiver.js";
 import { MaterialHandler } from "./obj2/shared/MaterialHandler.js";
 
 /**
- * Use this class to load OBJ data from files or to parse OBJ data from an arraybuffer
- * @class
+ * Creates a new OBJLoader2. Use it to load OBJ data from files or to parse OBJ data from arraybuffer or text.
  *
  * @param {LoadingManager} [manager] The loadingManager for the loader to use. Default is {@link LoadingManager}
+ * @constructor
  */
 const OBJLoader2 = function ( manager ) {
 	Loader.call( this, manager );
@@ -307,7 +307,7 @@ OBJLoader2.prototype = Object.assign( Object.create( Loader.prototype ), {
 	},
 
 	/**
-	 * Parses OBJ data synchronously from arraybuffer or string.
+	 * Parses OBJ data synchronously from arraybuffer or string and returns the {@link Object3D}.
 	 *
 	 * @param {arraybuffer|string} content OBJ data as Uint8Array or String
 	 * @return {Object3D}

examples/jsm/loaders/OBJLoader2Parallel.js

@@ -24,10 +24,10 @@ import {
 
 
 /**
- * Extends {OBJLoader2} with the capability to run the parser {OBJLoader2Parser} in web worker
- * with help of {WorkerExecutionSupport}.
+ * Creates a new OBJLoader2Parallel. Use it to load OBJ data from files or to parse OBJ data from arraybuffer.
+ * It extends {@link OBJLoader2} with the capability to run the parser in a web worker.
  *
- * @param [LoadingManager] manager
+ * @param [LoadingManager] manager The loadingManager for the loader to use. Default is {@link LoadingManager}
  * @constructor
  */
 const OBJLoader2Parallel = function ( manager ) {
@@ -48,30 +48,34 @@ OBJLoader2Parallel.prototype = Object.assign( Object.create( OBJLoader2.prototyp
 
 	constructor: OBJLoader2Parallel,
 
-	setPreferJsmWorker: function ( preferJsmWorker ) {
+	/**
+	 * Execution of parse in parallel via Worker is default, but normal {OBJLoader2} parsing can be enforced via false here.
+	 *
+	 * @param executeParallel True or False
+	 * @return {OBJLoader2Parallel}
+	 */
+	setExecuteParallel: function ( executeParallel ) {
 
-		this.preferJsmWorker = preferJsmWorker === true;
+		this.executeParallel = executeParallel === true;
 		return this;
 
 	},
 
 	/**
-	 * Execution of parse in parallel via Worker is default, but normal {OBJLoader2} parsing can be enforced via false here.
-	 *
-	 * @param executeParallel
+	 * Set whether jsm modules in workers should be used. This requires browser support which is currently only experimental.
+	 * @param preferJsmWorker True or False
 	 * @return {OBJLoader2Parallel}
 	 */
-	setExecuteParallel: function ( executeParallel ) {
+	setPreferJsmWorker: function ( preferJsmWorker ) {
 
-		this.executeParallel = executeParallel === true;
+		this.preferJsmWorker = preferJsmWorker === true;
 		return this;
 
 	},
 
 	/**
-	 * Allow to get hold of {WorkerExecutionSupport} for configuratin purposes
-	 *
-	 * @return {WorkerExecutionSupport|WorkerExecutionSupport}
+	 * Allow to get hold of {@link WorkerExecutionSupport} for configuration purposes.
+	 * @return {WorkerExecutionSupport}
 	 */
 	getWorkerExecutionSupport: function () {
 
@@ -80,8 +84,7 @@ OBJLoader2Parallel.prototype = Object.assign( Object.create( OBJLoader2.prototyp
 	},
 
 	/**
-	 * Provides instructions on what is to be contained in the worker
-	 *
+	 * Provide instructions on what is to be contained in the worker.
 	 * @return {CodeBuilderInstructions}
 	 */
 	buildWorkerCode: function () {
@@ -111,9 +114,6 @@ OBJLoader2Parallel.prototype = Object.assign( Object.create( OBJLoader2.prototyp
 
 	},
 
-	/**
-	 * @private
-	 */
 	_configure: function () {
 
 		if ( this.parser.callbacks.onLoad === this.parser._onLoad ) {
@@ -141,34 +141,27 @@ OBJLoader2Parallel.prototype = Object.assign( Object.create( OBJLoader2.prototyp
 	},
 
 	/**
-	 * Load is intercepted from {OBJLoader2}. It replaces the regular onLoad callback as the final worker result will be
-	 * returned later by its own callbackOnLoad.
-	 *
-	 * @param {string}  url A string containing the path/URL of the file to be loaded.
-	 * @param {function} onLoad A function to be called after loading is successfully completed. The function receives loaded Object3D as an argument.
-	 * @param {function} [onFileLoadProgress] A function to be called while the loading is in progress. The argument will be the XMLHttpRequest instance, which contains total and Integer bytes.
-	 * @param {function} [onError] A function to be called if an error occurs during loading. The function receives the error as an argument.
-	 * @param {function} [onMeshAlter] Called after worker successfully delivered a single mesh
+	 * See {@link OBJLoader2.load}
 	 */
 	load: function ( content, onLoad, onFileLoadProgress, onError, onMeshAlter ) {
 
  		let scope = this;
 		function interceptOnLoad ( object3d, message ) {
 
-			if ( object3d instanceof Object3D ) {
-
-				onLoad( object3d, message );
-
-			}
-			else {
+			if ( object3d.name === 'OBJLoader2ParallelDummy' ) {
 
-				if ( object3d == 'OBJLoader2Parallel' && scope.parser.logging.enabled && scope.parser.logging.debug ) {
+				if ( scope.parser.logging.enabled && scope.parser.logging.debug ) {
 
 					console.debug( 'Received dummy answer from OBJLoader2Parallel#parse' );
 
 				}
 
 			}
+			else {
+
+				onLoad( object3d, message );
+
+			}
 
 		}
 
@@ -177,9 +170,9 @@ OBJLoader2Parallel.prototype = Object.assign( Object.create( OBJLoader2.prototyp
 	},
 
 	/**
-	 * Parses OBJ data in parallel with web worker.
-	 *
-	 * @param {arraybuffer} content OBJ data as Uint8Array or String
+	 * See {@link OBJLoader2.parse}
+	 * The callback onLoad needs to be set to be able to receive the content if used in parallel mode.
+	 * Fallback is possible via {@link OBJLoader2Parallel#setExecuteParallel}.
 	 */
 	parse: function ( content ) {
 
@@ -188,27 +181,29 @@ OBJLoader2Parallel.prototype = Object.assign( Object.create( OBJLoader2.prototyp
 			this._configure();
 
 			this.workerExecutionSupport.executeParallel(
-				{
-					params: {
-						modelName: this.modelName,
-						instanceNo: this.instanceNo,
-						useIndices: this.parser.useIndices,
-						disregardNormals: this.parser.disregardNormals,
-						materialPerSmoothingGroup: this.parser.materialPerSmoothingGroup,
-						useOAsMesh: this.parser.useOAsMesh,
-					},
-					materials: this.materialHandler.getMaterialsJSON(),
-					data: {
-						input: content,
-						options: null
-					},
-					logging: {
-						enabled: this.parser.logging.enabled,
-						debug: this.parser.logging.debug
-					}
-				} );
-
-			return 'OBJLoader2Parallel';
+			{
+				params: {
+					modelName: this.modelName,
+					instanceNo: this.instanceNo,
+					useIndices: this.parser.useIndices,
+					disregardNormals: this.parser.disregardNormals,
+					materialPerSmoothingGroup: this.parser.materialPerSmoothingGroup,
+					useOAsMesh: this.parser.useOAsMesh,
+				},
+				materials: this.materialHandler.getMaterialsJSON(),
+				data: {
+					input: content,
+					options: null
+				},
+				logging: {
+					enabled: this.parser.logging.enabled,
+					debug: this.parser.logging.debug
+				}
+			} );
+
+			let dummy = new Object3D();
+			dummy.name = 'OBJLoader2ParallelDummy';
+			return dummy;
 		}
 		else {