@plastic-software/three 0.174.0 → 0.175.1

package/examples/jsm/misc/ProgressiveLightMapGPU.js

@@ -4,7 +4,7 @@ import { add, float, mix, output, sub, texture, uniform, uv, vec2, vec4 } from '
 import { potpack } from '../libs/potpack.module.js';
 
 /**
- * Progressive Light Map Accumulator, by [zalo](https://github.com/zalo/)
+ * Progressive Light Map Accumulator, by [zalo]{@link https://github.com/zalo/}.
  *
  * To use, simply construct a `ProgressiveLightMap` object,
  * `plmap.addObjectsToLightMap(object)` an array of semi-static
@@ -15,16 +15,31 @@ import { potpack } from '../libs/potpack.module.js';
  * This should begin accumulating lightmaps which apply to
  * your objects, so you can start jittering lighting to achieve
  * the texture-space effect you're looking for.
+ *
+ * This class can only be used with {@link WebGPURenderer}.
+ * When using {@link WebGLRenderer}, import from `ProgressiveLightMap.js`.
  */
 class ProgressiveLightMap {
 
 	/**
-	 * @param {WebGPURenderer} renderer An instance of WebGPURenderer.
-	 * @param {number} [resolution=1024] The side-long dimension of you total lightmap.
+	 * @param {WebGPURenderer} renderer - The renderer.
+	 * @param {number} [resolution=1024] - The side-long dimension of the total lightmap.
 	 */
 	constructor( renderer, resolution = 1024 ) {
 
+		/**
+		 * The renderer.
+		 *
+		 * @type {WebGPURenderer}
+		 */
 		this.renderer = renderer;
+
+		/**
+		 * The side-long dimension of the total lightmap.
+		 *
+		 * @type {number}
+		 * @default 1024
+		 */
 		this.resolution = resolution;
 
 		this._lightMapContainers = [];
@@ -57,7 +72,8 @@ class ProgressiveLightMap {
 
 	/**
 	 * Sets these objects' materials' lightmaps and modifies their uv1's.
-	 * @param {Object3D} objects An array of objects and lights to set up your lightmap.
+	 *
+	 * @param {Array<Object3D>} objects - An array of objects and lights to set up your lightmap.
 	 */
 	addObjectsToLightMap( objects ) {
 
@@ -96,9 +112,9 @@ class ProgressiveLightMap {
 			object.receiveShadow = true;
 			object.renderOrder = 1000 + ob;
 
-			// Prepare UV boxes for potpack
+			// Prepare UV boxes for potpack (potpack will update x and y)
 			// TODO: Size these by object surface area
-			uv_boxes.push( { w: 1 + ( padding * 2 ), h: 1 + ( padding * 2 ), index: ob } );
+			uv_boxes.push( { w: 1 + ( padding * 2 ), h: 1 + ( padding * 2 ), index: ob, x: 0, y: 0 } );
 
 			this._lightMapContainers.push( { basicMat: object.material, object: object } );
 
@@ -150,10 +166,11 @@ class ProgressiveLightMap {
 	}
 
 	/**
-	 * This function renders each mesh one at a time into their respective surface maps
-	 * @param {Camera} camera Standard Rendering Camera
-	 * @param {number} blendWindow When >1, samples will accumulate over time.
-	 * @param {boolean} blurEdges  Whether to fix UV Edges via blurring
+	 * This function renders each mesh one at a time into their respective surface maps.
+	 *
+	 * @param {Camera} camera - The camera the scene is rendered with.
+	 * @param {number} [blendWindow=100] - When >1, samples will accumulate over time.
+	 * @param {boolean} [blurEdges=true] - Whether to fix UV Edges via blurring.
 	 */
 	update( camera, blendWindow = 100, blurEdges = true ) {
 
@@ -213,9 +230,10 @@ class ProgressiveLightMap {
 	}
 
 	/**
-	 * Draw the lightmap in the main scene.  Call this after adding the objects to it.
-	 * @param {boolean} visible Whether the debug plane should be visible.
-	 * @param {Vector3} position Where the debug plane should be drawn.
+	 * Draws the lightmap in the main scene. Call this after adding the objects to it.
+	 *
+	 * @param {boolean} visible - Whether the debug plane should be visible
+	 * @param {Vector3} [position] - Where the debug plane should be drawn
 	*/
 	showDebugLightmap( visible, position = null ) {
 
@@ -254,6 +272,8 @@ class ProgressiveLightMap {
 
 	/**
 	 * Creates the Blurring Plane.
+	 *
+	 * @private
 	 */
 	_initializeBlurPlane() {
 

package/examples/jsm/misc/RollerCoaster.js

@@ -8,8 +8,19 @@ import {
 	Vector3
 } from 'three';
 
+/**
+ * A procedural roller coaster geometry.
+ *
+ * @augments BufferGeometry
+ */
 class RollerCoasterGeometry extends BufferGeometry {
 
+	/**
+	 * Constructs a new geometry.
+	 *
+	 * @param {Curve} curve - The curve to generate the geometry along.
+ 	 * @param {number} divisions - The number of divisions which defines the detail of the geometry.
+	 */
 	constructor( curve, divisions ) {
 
 		super();
@@ -222,8 +233,19 @@ class RollerCoasterGeometry extends BufferGeometry {
 
 }
 
+/**
+ * A procedural roller coaster lifters geometry.
+ *
+ * @augments BufferGeometry
+ */
 class RollerCoasterLiftersGeometry extends BufferGeometry {
 
+	/**
+	 * Constructs a new geometry.
+	 *
+	 * @param {Curve} curve - The curve to generate the geometry along.
+ 	 * @param {number} divisions - The number of divisions which defines the detail of the geometry.
+	 */
 	constructor( curve, divisions ) {
 
 		super();
@@ -398,8 +420,19 @@ class RollerCoasterLiftersGeometry extends BufferGeometry {
 
 }
 
+/**
+ * A procedural roller coaster shadow geometry.
+ *
+ * @augments BufferGeometry
+ */
 class RollerCoasterShadowGeometry extends BufferGeometry {
 
+	/**
+	 * Constructs a new geometry.
+	 *
+	 * @param {Curve} curve - The curve to generate the geometry along.
+ 	 * @param {number} divisions - The number of divisions which defines the detail of the geometry.
+	 */
 	constructor( curve, divisions ) {
 
 		super();
@@ -470,8 +503,16 @@ class RollerCoasterShadowGeometry extends BufferGeometry {
 
 }
 
+/**
+ * A procedural sky geometry.
+ *
+ * @augments BufferGeometry
+ */
 class SkyGeometry extends BufferGeometry {
 
+	/**
+	 * Constructs a new geometry.
+	 */
 	constructor() {
 
 		super();
@@ -503,8 +544,19 @@ class SkyGeometry extends BufferGeometry {
 
 }
 
+/**
+ * A procedural trees geometry.
+ *
+ * @augments BufferGeometry
+ */
 class TreesGeometry extends BufferGeometry {
 
+	/**
+	 * Constructs a new geometry.
+	 *
+	 * @param {Mesh} landscape - A mesh representing the landscape. Trees will be positioned
+	 * randomly on the landscape's surface.
+	 */
 	constructor( landscape ) {
 
 		super();

package/examples/jsm/misc/Timer.js

@@ -1,5 +1,22 @@
+/**
+ * This class is an alternative to {@link Clock} with a different API design and behavior.
+ * The goal is to avoid the conceptual flaws that became apparent in `Clock` over time.
+ *
+ * - `Timer` has an `update()` method that updates its internal state. That makes it possible to
+ * call `getDelta()` and `getElapsed()` multiple times per simulation step without getting different values.
+ * - The class can make use of the Page Visibility API to avoid large time delta values when the app
+ * is inactive (e.g. tab switched or browser hidden).
+ *
+ * ```js
+ * const timer = new Timer();
+ * timer.connect( document ); // use Page Visibility API
+ * ```
+ */
 class Timer {
 
+	/**
+	 * Constructs a new timer.
+	 */
 	constructor() {
 
 		this._previousTime = 0;
@@ -16,6 +33,13 @@ class Timer {
 
 	}
 
+	/**
+	 * Connect the timer to the given document.Calling this method is not mandatory to
+	 * use the timer but enables the usage of the Page Visibility API to avoid large time
+	 * delta values.
+	 *
+	 * @param {Document} document - The document.
+	 */
 	connect( document ) {
 
 		this._document = document;
@@ -32,6 +56,9 @@ class Timer {
 
 	}
 
+	/**
+	 * Disconnects the timer from the DOM and also disables the usage of the Page Visibility API.
+	 */
 	disconnect() {
 
 		if ( this._pageVisibilityHandler !== null ) {
@@ -45,24 +72,46 @@ class Timer {
 
 	}
 
+	/**
+	 * Returns the time delta in seconds.
+	 *
+	 * @return {number} The time delta in second.
+	 */
 	getDelta() {
 
 		return this._delta / 1000;
 
 	}
 
+	/**
+	 * Returns the elapsed time in seconds.
+	 *
+	 * @return {number} The elapsed time in second.
+	 */
 	getElapsed() {
 
 		return this._elapsed / 1000;
 
 	}
 
+	/**
+	 * Returns the timescale.
+	 *
+	 * @return {number} The timescale.
+	 */
 	getTimescale() {
 
 		return this._timescale;
 
 	}
 
+	/**
+	 * Sets the given timescale which scale the time delta computation
+	 * in `update()`.
+	 *
+	 * @param {number} timescale - The timescale to set.
+	 * @return {Timer} A reference to this timer.
+	 */
 	setTimescale( timescale ) {
 
 		this._timescale = timescale;
@@ -71,6 +120,11 @@ class Timer {
 
 	}
 
+	/**
+	 * Resets the time computation for the current simulation step.
+	 *
+	 * @return {Timer} A reference to this timer.
+	 */
 	reset() {
 
 		this._currentTime = now() - this._startTime;
@@ -79,14 +133,26 @@ class Timer {
 
 	}
 
+	/**
+	 * Can be used to free all internal resources. Usually called when
+	 * the timer instance isn't required anymore.
+	 */
 	dispose() {
 
 		this.disconnect();
 
-		return this;
-
 	}
 
+	/**
+	 * Updates the internal state of the timer. This method should be called
+	 * once per simulation step and before you perform queries against the timer
+	 * (e.g. via `getDelta()`).
+	 *
+	 * @param {number} timestamp - The current time in milliseconds. Can be obtained
+	 * from the `requestAnimationFrame` callback argument. If not provided, the current
+	 * time will be determined with `performance.now`.
+	 * @return {Timer} A reference to this timer.
+	 */
 	update( timestamp ) {
 
 		if ( this._pageVisibilityHandler !== null && this._document.hidden === true ) {
@@ -109,8 +175,19 @@ class Timer {
 
 }
 
+/**
+ * A special version of a timer with a fixed time delta value.
+ * Can be useful for testing and debugging purposes.
+ *
+ * @augments Timer
+ */
 class FixedTimer extends Timer {
 
+	/**
+	 * Constructs a new timer.
+	 *
+	 * @param {number} [fps=60] - The fixed FPS of this timer.
+	 */
 	constructor( fps = 60 ) {
 
 		super();

package/examples/jsm/misc/TubePainter.js

@@ -9,6 +9,19 @@ import {
 	Vector3
 } from 'three';
 
+/**
+ * @classdesc This module can be used to paint tube-like meshes
+ * along a sequence of points. This module is used in a XR
+ * painter demo.
+ *
+ * ```js
+ * const painter = new TubePainter();
+ * scene.add( painter.mesh );
+ * ```
+ *
+ * @name TubePainter
+ * @class
+ */
 function TubePainter() {
 
 	const BUFFER_SIZE = 1000000 * 3;
@@ -190,10 +203,50 @@ function TubePainter() {
 	}
 
 	return {
+		/**
+		 * The "painted" tube mesh. Must be added to the scene.
+		 *
+		 * @name TubePainter#mesh
+		 * @type {Mesh}
+		 */
 		mesh: mesh,
+
+		/**
+		 * Moves the current painting position to the given value.
+		 *
+		 * @method
+		 * @name TubePainter#moveTo
+		 * @param {Vector3} position The new painting position.
+		 */
 		moveTo: moveTo,
+
+		/**
+		 * Draw a stroke from the current position to the given one.
+		 * This method extends the tube while drawing with the XR
+		 * controllers.
+		 *
+		 * @method
+		 * @name TubePainter#lineTo
+		 * @param {Vector3} position The destination position.
+		 */
 		lineTo: lineTo,
+
+		/**
+		 * Sets the size of newly rendered tube segments.
+		 *
+		 * @method
+		 * @name TubePainter#setSize
+		 * @param {number} size The size.
+		 */
 		setSize: setSize,
+
+		/**
+		 * Updates the internal geometry buffers so the new painted
+		 * segments are rendered.
+		 *
+		 * @method
+		 * @name TubePainter#update
+		 */
 		update: update
 	};