@plastic-software/three 0.174.0 → 0.175.1

package/examples/jsm/misc/GPUComputationRenderer.js

@@ -11,10 +11,10 @@ import {
 import { FullScreenQuad } from '../postprocessing/Pass.js';
 
 /**
- * GPUComputationRenderer, based on SimulationRenderer by zz85
+ * GPUComputationRenderer, based on SimulationRenderer by @zz85.
  *
  * The GPUComputationRenderer uses the concept of variables. These variables are RGBA float textures that hold 4 floats
- * for each compute element (texel)
+ * for each compute element (texel).
  *
  * Each variable has a fragment shader that defines the computation made to obtain the variable in question.
  * You can use as many variables you need, and make dependencies so you can use textures of other variables in the shader
@@ -29,12 +29,11 @@ import { FullScreenQuad } from '../postprocessing/Pass.js';
  * a common approach could be to use 'texture' prefixing the variable name; i.e texturePosition, textureVelocity...
  *
  * The size of the computation (sizeX * sizeY) is defined as 'resolution' automatically in the shader. For example:
+ * ```
  * #DEFINE resolution vec2( 1024.0, 1024.0 )
- *
- * -------------
- *
+ * ```
  * Basic use:
- *
+ * ```js
  * // Initialization...
  *
  * // Create computation renderer
@@ -62,7 +61,6 @@ import { FullScreenQuad } from '../postprocessing/Pass.js';
  *		console.error( error );
   * }
  *
- *
  * // In each frame...
  *
  * // Compute!
@@ -73,12 +71,12 @@ import { FullScreenQuad } from '../postprocessing/Pass.js';
  *
  * // Do your rendering
  * renderer.render( myScene, myCamera );
- *
- * -------------
+ * ```
  *
  * Also, you can use utility functions to create ShaderMaterial and perform computations (rendering between textures)
  * Note that the shaders can have multiple input textures.
  *
+ * ```js
  * const myFilter1 = gpuCompute.createShaderMaterial( myFilterFragmentShader1, { theTexture: { value: null } } );
  * const myFilter2 = gpuCompute.createShaderMaterial( myFilterFragmentShader2, { theTexture: { value: null } } );
  *
@@ -99,14 +97,16 @@ import { FullScreenQuad } from '../postprocessing/Pass.js';
  * // And compute each frame, before rendering to screen:
  * gpuCompute.doRenderTarget( myFilter1, myRenderTarget );
  * gpuCompute.doRenderTarget( myFilter2, outputRenderTarget );
+ * ```
  */
-
 class GPUComputationRenderer {
 
 	/**
-	 * @param {number} sizeX Computation problem size is always 2d: sizeX * sizeY elements.
- 	 * @param {number} sizeY Computation problem size is always 2d: sizeX * sizeY elements.
- 	 * @param {WebGLRenderer} renderer The renderer
+	 * Constructs a new GPU computation renderer.
+	 *
+	 * @param {number} sizeX - Computation problem size is always 2d: sizeX * sizeY elements.
+ 	 * @param {number} sizeY - Computation problem size is always 2d: sizeX * sizeY elements.
+ 	 * @param {WebGLRenderer} renderer - The renderer.
 	 */
 	constructor( sizeX, sizeY, renderer ) {
 
@@ -124,6 +124,12 @@ class GPUComputationRenderer {
 
 		const quad = new FullScreenQuad( passThruShader );
 
+		/**
+		 * Sets the data type of the internal textures.
+		 *
+		 * @param {(FloatType|HalfFloatType)} type - The type to set.
+		 * @return {GPUComputationRenderer} A reference to this renderer.
+		 */
 		this.setDataType = function ( type ) {
 
 			dataType = type;
@@ -131,6 +137,14 @@ class GPUComputationRenderer {
 
 		};
 
+		/**
+		 * Adds a compute variable to the renderer.
+		 *
+		 * @param {string} variableName - The variable name.
+		 * @param {string} computeFragmentShader - The compute (fragment) shader source.
+		 * @param {Texture} initialValueTexture - The initial value texture.
+		 * @return {Object} The compute variable.
+		 */
 		this.addVariable = function ( variableName, computeFragmentShader, initialValueTexture ) {
 
 			const material = this.createShaderMaterial( computeFragmentShader );
@@ -153,12 +167,23 @@ class GPUComputationRenderer {
 
 		};
 
+		/**
+		 * Sets variable dependencies.
+		 *
+		 * @param {Object} variable - The compute variable.
+		 * @param {Array<Object>} dependencies - Other compute variables that represents the dependencies.
+		 */
 		this.setVariableDependencies = function ( variable, dependencies ) {
 
 			variable.dependencies = dependencies;
 
 		};
 
+		/**
+		 * Initializes the renderer.
+		 *
+		 * @return {?string} Returns `null` if no errors are detected. Otherwise returns the error message.
+		 */
 		this.init = function () {
 
 			if ( renderer.capabilities.maxVertexTextures === 0 ) {
@@ -227,6 +252,9 @@ class GPUComputationRenderer {
 
 		};
 
+		/**
+		 * Executes the compute. This method is usually called in the animation loop.
+		 */
 		this.compute = function () {
 
 			const currentTextureIndex = this.currentTextureIndex;
@@ -260,18 +288,34 @@ class GPUComputationRenderer {
 
 		};
 
+		/**
+		 * Returns the current render target for the given compute variable.
+		 *
+		 * @param {Object} variable - The compute variable.
+		 * @return {WebGLRenderTarget} The current render target.
+		 */
 		this.getCurrentRenderTarget = function ( variable ) {
 
 			return variable.renderTargets[ this.currentTextureIndex ];
 
 		};
 
+		/**
+		 * Returns the alternate render target for the given compute variable.
+		 *
+		 * @param {Object} variable - The compute variable.
+		 * @return {WebGLRenderTarget} The alternate render target.
+		 */
 		this.getAlternateRenderTarget = function ( variable ) {
 
 			return variable.renderTargets[ this.currentTextureIndex === 0 ? 1 : 0 ];
 
 		};
 
+		/**
+		 * Frees all internal resources. Call this method if you don't need the
+		 * renderer anymore.
+		 */
 		this.dispose = function () {
 
 			quad.dispose();
@@ -303,6 +347,11 @@ class GPUComputationRenderer {
 
 		}
 
+		/**
+		 * Adds a resolution defined for the given material shader.
+		 *
+		 * @param {Object} materialShader - The material shader.
+		 */
 		this.addResolutionDefine = addResolutionDefine;
 
 
@@ -327,6 +376,17 @@ class GPUComputationRenderer {
 
 		this.createShaderMaterial = createShaderMaterial;
 
+		/**
+		 * Creates a new render target from the given parameters.
+		 *
+		 * @param {number} sizeXTexture - The width of the render target.
+		 * @param {number} sizeYTexture - The height of the render target.
+		 * @param {number} wrapS - The wrapS value.
+		 * @param {number} wrapT - The wrapS value.
+		 * @param {number} minFilter - The minFilter value.
+		 * @param {number} magFilter - The magFilter value.
+		 * @return {WebGLRenderTarget} The new render target.
+		 */
 		this.createRenderTarget = function ( sizeXTexture, sizeYTexture, wrapS, wrapT, minFilter, magFilter ) {
 
 			sizeXTexture = sizeXTexture || sizeX;
@@ -352,6 +412,11 @@ class GPUComputationRenderer {
 
 		};
 
+		/**
+		 * Creates a new data texture.
+		 *
+		 * @return {DataTexture} The new data texture.
+		 */
 		this.createTexture = function () {
 
 			const data = new Float32Array( sizeX * sizeY * 4 );
@@ -361,12 +426,14 @@ class GPUComputationRenderer {
 
 		};
 
+		/**
+		 * Renders the given texture into the given render target.
+		 *
+		 * @param {Texture} input - The input.
+		 * @param {WebGLRenderTarget} output - The output.
+		 */
 		this.renderTexture = function ( input, output ) {
 
-			// Takes a texture, and render out in rendertarget
-			// input = Texture
-			// output = RenderTarget
-
 			passThruUniforms.passThruTexture.value = input;
 
 			this.doRenderTarget( passThruShader, output );
@@ -375,6 +442,14 @@ class GPUComputationRenderer {
 
 		};
 
+
+		/**
+		 * Renders the given material into the given render target
+		 * with a full-screen pass.
+		 *
+		 * @param {Material} material - The material.
+		 * @param {WebGLRenderTarget} output - The output.
+		 */
 		this.doRenderTarget = function ( material, output ) {
 
 			const currentRenderTarget = renderer.getRenderTarget();

package/examples/jsm/misc/Gyroscope.js

@@ -12,8 +12,19 @@ const _translationWorld = new Vector3();
 const _quaternionWorld = new Quaternion();
 const _scaleWorld = new Vector3();
 
+/**
+ * A special type of 3D object that takes a position from the scene graph hierarchy
+ * but uses its local rotation as world rotation. It works like real-world gyroscope -
+ * you can move it around using hierarchy while its orientation stays fixed with
+ * respect to the world.
+ *
+ * @augments Object3D
+ */
 class Gyroscope extends Object3D {
 
+	/**
+	 * Constructs a new gyroscope.
+	 */
 	constructor() {
 
 		super();

package/examples/jsm/misc/MD2Character.js

@@ -10,33 +10,111 @@ import {
 } from 'three';
 import { MD2Loader } from '../loaders/MD2Loader.js';
 
+/**
+ * This class represents a management component for animated MD2
+ * character assets.
+ */
 class MD2Character {
 
+	/**
+	 * Constructs a new MD2 character.
+	 */
 	constructor() {
 
+		/**
+		 * The mesh scale.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.scale = 1;
+
+		/**
+		 * The FPS
+		 *
+		 * @type {number}
+		 * @default 6
+		 */
 		this.animationFPS = 6;
 
+		/**
+		 * The root 3D object
+		 *
+		 * @type {Object3D}
+		 */
 		this.root = new Object3D();
 
+		/**
+		 * The body mesh.
+		 *
+		 * @type {?Mesh}
+		 * @default null
+		 */
 		this.meshBody = null;
+
+		/**
+		 * The weapon mesh.
+		 *
+		 * @type {?Mesh}
+		 * @default null
+		 */
 		this.meshWeapon = null;
 
+		/**
+		 * The body skins.
+		 *
+		 * @type {Array<Texture>}
+		 */
 		this.skinsBody = [];
+
+		/**
+		 * The weapon skins.
+		 *
+		 * @type {Array<Texture>}
+		 */
 		this.skinsWeapon = [];
 
+		/**
+		 * The weapon meshes.
+		 *
+		 * @type {Array<Mesh>}
+		 */
 		this.weapons = [];
 
-		this.activeAnimation = null;
-
+		/**
+		 * The name of the active animation clip.
+		 *
+		 * @type {?string}
+		 * @default null
+		 */
+		this.activeAnimationClipName = null;
+
+		/**
+		 * The animation mixer.
+		 *
+		 * @type {?AnimationMixer}
+		 * @default null
+		 */
 		this.mixer = null;
 
+		/**
+		 * The `onLoad` callback function.
+		 *
+		 * @type {Function}
+		 */
 		this.onLoadComplete = function () {};
 
+		// internal
+
 		this.loadCounter = 0;
 
 	}
 
+	/**
+	 * Loads the character model for the given config.
+	 *
+	 * @param {Object} config - The config which defines the model and textures paths.
+	 */
 	loadParts( config ) {
 
 		const scope = this;
@@ -156,6 +234,11 @@ class MD2Character {
 
 	}
 
+	/**
+	 * Sets the animation playback rate.
+	 *
+	 * @param {number} rate - The playback rate to set.
+	 */
 	setPlaybackRate( rate ) {
 
 		if ( rate !== 0 ) {
@@ -170,6 +253,11 @@ class MD2Character {
 
 	}
 
+	/**
+	 * Sets the wireframe material flag.
+	 *
+	 * @param {boolean} wireframeEnabled - Whether to enable wireframe rendering or not.
+	 */
 	setWireframe( wireframeEnabled ) {
 
 		if ( wireframeEnabled ) {
@@ -186,6 +274,12 @@ class MD2Character {
 
 	}
 
+	/**
+	 * Sets the skin defined by the given skin index. This will result in a different texture
+	 * for the body mesh.
+	 *
+	 * @param {number} index - The skin index.
+	 */
 	setSkin( index ) {
 
 		if ( this.meshBody && this.meshBody.material.wireframe === false ) {
@@ -196,6 +290,12 @@ class MD2Character {
 
 	}
 
+	/**
+	 * Sets the weapon defined by the given weapon index. This will result in a different weapon
+	 * hold by the character.
+	 *
+	 * @param {number} index - The weapon index.
+	 */
 	setWeapon( index ) {
 
 		for ( let i = 0; i < this.weapons.length; i ++ ) this.weapons[ i ].visible = false;
@@ -213,6 +313,11 @@ class MD2Character {
 
 	}
 
+	/**
+	 * Sets the defined animation clip as the active animation.
+	 *
+	 * @param {string} clipName - The name of the animation clip.
+	 */
 	setAnimation( clipName ) {
 
 		if ( this.meshBody ) {
@@ -240,6 +345,9 @@ class MD2Character {
 
 	}
 
+	/**
+	 * Synchronizes the weapon with the body animation.
+	 */
 	syncWeaponAnimation() {
 
 		const clipName = this.activeClipName;
@@ -265,6 +373,11 @@ class MD2Character {
 
 	}
 
+	/**
+	 * Updates the animations of the mesh. Must be called inside the animation loop.
+	 *
+	 * @param {number} delta - The delta time in seconds.
+	 */
 	update( delta ) {
 
 		if ( this.mixer ) this.mixer.update( delta );