@plastic-software/three 0.174.0 → 0.175.0

package/src/textures/FramebufferTexture.js

@@ -1,17 +1,79 @@
 import { Texture } from './Texture.js';
 import { NearestFilter } from '../constants.js';
 
+/**
+ * This class can only be used in combination with `copyFramebufferToTexture()` methods
+ * of renderers. It extracts the contents of the current bound framebuffer and provides it
+ * as a texture for further usage.
+ *
+ * ```js
+ * const pixelRatio = window.devicePixelRatio;
+ * const textureSize = 128 * pixelRatio;
+ *
+ * const frameTexture = new FramebufferTexture( textureSize, textureSize );
+ *
+ * // calculate start position for copying part of the frame data
+ * const vector = new Vector2();
+ * vector.x = ( window.innerWidth * pixelRatio / 2 ) - ( textureSize / 2 );
+ * vector.y = ( window.innerHeight * pixelRatio / 2 ) - ( textureSize / 2 );
+ *
+ * renderer.render( scene, camera );
+ *
+ * // copy part of the rendered frame into the framebuffer texture
+ * renderer.copyFramebufferToTexture( frameTexture, vector );
+ * ```
+ *
+ * @augments Texture
+ */
 class FramebufferTexture extends Texture {
 
+	/**
+	 * Constructs a new framebuffer texture.
+	 *
+	 * @param {number} width - The width of the texture.
+	 * @param {number} height - The height of the texture.
+	 */
 	constructor( width, height ) {
 
 		super( { width, height } );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isFramebufferTexture = true;
 
+		/**
+		 * How the texture is sampled when a texel covers more than one pixel.
+		 *
+		 * Overwritten and set to `NearestFilter` by default to disable filtering.
+		 *
+		 * @type {(NearestFilter|NearestMipmapNearestFilter|NearestMipmapLinearFilter|LinearFilter|LinearMipmapNearestFilter|LinearMipmapLinearFilter)}
+		 * @default NearestFilter
+		 */
 		this.magFilter = NearestFilter;
+
+		/**
+		 * How the texture is sampled when a texel covers less than one pixel.
+		 *
+		 * Overwritten and set to `NearestFilter` by default to disable filtering.
+		 *
+		 * @type {(NearestFilter|NearestMipmapNearestFilter|NearestMipmapLinearFilter|LinearFilter|LinearMipmapNearestFilter|LinearMipmapLinearFilter)}
+		 * @default NearestFilter
+		 */
 		this.minFilter = NearestFilter;
 
+		/**
+		 * Whether to generate mipmaps (if possible) for a texture.
+		 *
+		 * Overwritten and set to `false` by default.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.generateMipmaps = false;
 
 		this.needsUpdate = true;

package/src/textures/Source.js

@@ -3,29 +3,98 @@ import { generateUUID } from '../math/MathUtils.js';
 
 let _sourceId = 0;
 
+/**
+ * Represents the data source of a texture.
+ *
+ * The main purpose of this class is to decouple the data definition from the texture
+ * definition so the same data can be used with multiple texture instances.
+ */
 class Source {
 
+	/**
+	 * Constructs a new video texture.
+	 *
+	 * @param {any} [data=null] - The data definition of a texture.
+	 */
 	constructor( data = null ) {
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isSource = true;
 
+		/**
+		 * The ID of the source.
+		 *
+		 * @name Source#id
+		 * @type {number}
+		 * @readonly
+		 */
 		Object.defineProperty( this, 'id', { value: _sourceId ++ } );
 
+		/**
+		 * The UUID of the source.
+		 *
+		 * @type {string}
+		 * @readonly
+		 */
 		this.uuid = generateUUID();
 
+		/**
+		 * The data definition of a texture.
+		 *
+		 * @type {any}
+		 */
 		this.data = data;
+
+		/**
+		 * This property is only relevant when {@link Source#needsUpdate} is set to `true` and
+		 * provides more control on how texture data should be processed. When `dataReady` is set
+		 * to `false`, the engine performs the memory allocation (if necessary) but does not transfer
+		 * the data into the GPU memory.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.dataReady = true;
 
+		/**
+		 * This starts at `0` and counts how many times {@link Source#needsUpdate} is set to `true`.
+		 *
+		 * @type {number}
+		 * @readonly
+		 * @default 0
+		 */
 		this.version = 0;
 
 	}
 
+	/**
+	 * When the property is set to `true`, the engine allocates the memory
+	 * for the texture (if necessary) and triggers the actual texture upload
+	 * to the GPU next time the source is used.
+	 *
+	 * @type {boolean}
+	 * @default false
+	 * @param {boolean} value
+	 */
 	set needsUpdate( value ) {
 
 		if ( value === true ) this.version ++;
 
 	}
 
+	/**
+	 * Serializes the source into JSON.
+	 *
+	 * @param {?(Object|string)} meta - An optional value holding meta information about the serialization.
+	 * @return {Object} A JSON object representing the serialized source.
+	 * @see {@link ObjectLoader#parse}
+	 */
 	toJSON( meta ) {
 
 		const isRootObject = ( meta === undefined || typeof meta === 'string' );

package/src/textures/Texture.js

@@ -35,11 +35,11 @@ class Texture extends EventDispatcher {
 	 * @param {number} [wrapS=ClampToEdgeWrapping] - The wrapS value.
 	 * @param {number} [wrapT=ClampToEdgeWrapping] - The wrapT value.
 	 * @param {number} [magFilter=LinearFilter] - The mag filter value.
-	 * @param {number} [minFilter=LinearFilter] - The min filter value.
-	 * @param {number} [format=RGBAFormat] - The min filter value.
-	 * @param {number} [type=UnsignedByteType] - The min filter value.
-	 * @param {number} [anisotropy=Texture.DEFAULT_ANISOTROPY] - The min filter value.
-	 * @param {string} [colorSpace=NoColorSpace] - The min filter value.
+	 * @param {number} [minFilter=LinearMipmapLinearFilter] - The min filter value.
+	 * @param {number} [format=RGBAFormat] - The texture format.
+	 * @param {number} [type=UnsignedByteType] - The texture type.
+	 * @param {number} [anisotropy=Texture.DEFAULT_ANISOTROPY] - The anisotropy value.
+	 * @param {string} [colorSpace=NoColorSpace] - The color space.
 	 */
 	constructor( image = Texture.DEFAULT_IMAGE, mapping = Texture.DEFAULT_MAPPING, wrapS = ClampToEdgeWrapping, wrapT = ClampToEdgeWrapping, magFilter = LinearFilter, minFilter = LinearMipmapLinearFilter, format = RGBAFormat, type = UnsignedByteType, anisotropy = Texture.DEFAULT_ANISOTROPY, colorSpace = NoColorSpace ) {
 

package/src/textures/VideoFrameTexture.js

@@ -1,21 +1,52 @@
 import { VideoTexture } from './VideoTexture.js';
 
+/**
+ * This class can be used as an alternative way to define video data. Instead of using
+ * an instance of `HTMLVideoElement` like with `VideoTexture`, `VideoFrameTexture` expects each frame is
+ * defined manually via {@link VideoFrameTexture#setFrame}. A typical use case for this module is when
+ * video frames are decoded with the WebCodecs API.
+ *
+ * ```js
+ * const texture = new THREE.VideoFrameTexture();
+ * texture.setFrame( frame );
+ * ```
+ *
+ * @augments VideoTexture
+ */
 class VideoFrameTexture extends VideoTexture {
 
+	/**
+	 * Constructs a new video frame texture.
+	 *
+	 * @param {number} [mapping=Texture.DEFAULT_MAPPING] - The texture mapping.
+	 * @param {number} [wrapS=ClampToEdgeWrapping] - The wrapS value.
+	 * @param {number} [wrapT=ClampToEdgeWrapping] - The wrapT value.
+	 * @param {number} [magFilter=LinearFilter] - The mag filter value.
+	 * @param {number} [minFilter=LinearFilter] - The min filter value.
+	 * @param {number} [format=RGBAFormat] - The texture format.
+	 * @param {number} [type=UnsignedByteType] - The texture type.
+	 * @param {number} [anisotropy=Texture.DEFAULT_ANISOTROPY] - The anisotropy value.
+	 */
 	constructor( mapping, wrapS, wrapT, magFilter, minFilter, format, type, anisotropy ) {
 
 		super( {}, mapping, wrapS, wrapT, magFilter, minFilter, format, type, anisotropy );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isVideoFrameTexture = true;
 
 	}
 
-	update() {
-
-		// overwrites `VideoTexture.update()` with an empty method since
-		// this type of texture is updated via `setFrame()`.
-
-	}
+	/**
+	 * This method overwritten with an empty implementation since
+	 * this type of texture is updated via `setFrame()`.
+	 */
+	update() {}
 
 	clone() {
 
@@ -23,6 +54,12 @@ class VideoFrameTexture extends VideoTexture {
 
 	}
 
+	/**
+	 * Sets the current frame of the video. This will automatically update the texture
+	 * so the data can be used for rendering.
+	 *
+	 * @param {VideoFrame} frame - The video frame.
+	 */
 	setFrame( frame ) {
 
 		this.image = frame;

package/src/textures/VideoTexture.js

@@ -1,17 +1,56 @@
 import { LinearFilter } from '../constants.js';
 import { Texture } from './Texture.js';
 
+/**
+ * A texture for use with a video.
+ *
+ * ```js
+ * // assuming you have created a HTML video element with id="video"
+ * const video = document.getElementById( 'video' );
+ * const texture = new THREE.VideoTexture( video );
+ * ```
+ *
+ * Note: After the initial use of a texture, its dimensions, format, and type
+ * cannot be changed. Instead, call {@link Texture#dispose} on the texture and instantiate a new one.
+ *
+ * @augments Texture
+ */
 class VideoTexture extends Texture {
 
-	constructor( video, mapping, wrapS, wrapT, magFilter, minFilter, format, type, anisotropy ) {
+	/**
+	 * Constructs a new video texture.
+	 *
+	 * @param {Video} video - The video element to use as a data source for the texture.
+	 * @param {number} [mapping=Texture.DEFAULT_MAPPING] - The texture mapping.
+	 * @param {number} [wrapS=ClampToEdgeWrapping] - The wrapS value.
+	 * @param {number} [wrapT=ClampToEdgeWrapping] - The wrapT value.
+	 * @param {number} [magFilter=LinearFilter] - The mag filter value.
+	 * @param {number} [minFilter=LinearFilter] - The min filter value.
+	 * @param {number} [format=RGBAFormat] - The texture format.
+	 * @param {number} [type=UnsignedByteType] - The texture type.
+	 * @param {number} [anisotropy=Texture.DEFAULT_ANISOTROPY] - The anisotropy value.
+	 */
+	constructor( video, mapping, wrapS, wrapT, magFilter = LinearFilter, minFilter = LinearFilter, format, type, anisotropy ) {
 
 		super( video, mapping, wrapS, wrapT, magFilter, minFilter, format, type, anisotropy );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isVideoTexture = true;
 
-		this.minFilter = minFilter !== undefined ? minFilter : LinearFilter;
-		this.magFilter = magFilter !== undefined ? magFilter : LinearFilter;
-
+		/**
+		 * Whether to generate mipmaps (if possible) for a texture.
+		 *
+		 * Overwritten and set to `false` by default.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.generateMipmaps = false;
 
 		const scope = this;
@@ -37,6 +76,12 @@ class VideoTexture extends Texture {
 
 	}
 
+	/**
+	 * This method is called automatically by the renderer and sets {@link Texture#needsUpdate}
+	 * to `true` every time a new frame is available.
+	 *
+	 * Only relevant if `requestVideoFrameCallback` is not supported in the browser.
+	 */
 	update() {
 
 		const video = this.image;

package/examples/jsm/geometries/ParametricGeometries.js

@@ -1,254 +0,0 @@
-import {
-	Curve,
-	Vector3
-} from 'three';
-
-import { ParametricGeometry } from './ParametricGeometry.js';
-
-/**
- * Experimenting of primitive geometry creation using Surface Parametric equations
- */
-
-const ParametricGeometries = {
-
-	klein: function ( v, u, target ) {
-
-		u *= Math.PI;
-		v *= 2 * Math.PI;
-
-		u = u * 2;
-		let x, z;
-		if ( u < Math.PI ) {
-
-			x = 3 * Math.cos( u ) * ( 1 + Math.sin( u ) ) + ( 2 * ( 1 - Math.cos( u ) / 2 ) ) * Math.cos( u ) * Math.cos( v );
-			z = - 8 * Math.sin( u ) - 2 * ( 1 - Math.cos( u ) / 2 ) * Math.sin( u ) * Math.cos( v );
-
-		} else {
-
-			x = 3 * Math.cos( u ) * ( 1 + Math.sin( u ) ) + ( 2 * ( 1 - Math.cos( u ) / 2 ) ) * Math.cos( v + Math.PI );
-			z = - 8 * Math.sin( u );
-
-		}
-
-		const y = - 2 * ( 1 - Math.cos( u ) / 2 ) * Math.sin( v );
-
-		target.set( x, y, z );
-
-	},
-
-	plane: function ( width, height ) {
-
-		return function ( u, v, target ) {
-
-			const x = u * width;
-			const y = 0;
-			const z = v * height;
-
-			target.set( x, y, z );
-
-		};
-
-	},
-
-	mobius: function ( u, t, target ) {
-
-		// flat mobius strip
-		// http://www.wolframalpha.com/input/?i=M%C3%B6bius+strip+parametric+equations&lk=1&a=ClashPrefs_*Surface.MoebiusStrip.SurfaceProperty.ParametricEquations-
-		u = u - 0.5;
-		const v = 2 * Math.PI * t;
-
-		const a = 2;
-
-		const x = Math.cos( v ) * ( a + u * Math.cos( v / 2 ) );
-		const y = Math.sin( v ) * ( a + u * Math.cos( v / 2 ) );
-		const z = u * Math.sin( v / 2 );
-
-		target.set( x, y, z );
-
-	},
-
-	mobius3d: function ( u, t, target ) {
-
-		// volumetric mobius strip
-
-		u *= Math.PI;
-		t *= 2 * Math.PI;
-
-		u = u * 2;
-		const phi = u / 2;
-		const major = 2.25, a = 0.125, b = 0.65;
-
-		let x = a * Math.cos( t ) * Math.cos( phi ) - b * Math.sin( t ) * Math.sin( phi );
-		const z = a * Math.cos( t ) * Math.sin( phi ) + b * Math.sin( t ) * Math.cos( phi );
-		const y = ( major + x ) * Math.sin( u );
-		x = ( major + x ) * Math.cos( u );
-
-		target.set( x, y, z );
-
-	}
-
-};
-
-
-/*********************************************
- *
- * Parametric Replacement for TubeGeometry
- *
- *********************************************/
-
-ParametricGeometries.TubeGeometry = class TubeGeometry extends ParametricGeometry {
-
-	constructor( path, segments = 64, radius = 1, segmentsRadius = 8, closed = false ) {
-
-		const numpoints = segments + 1;
-
-		const frames = path.computeFrenetFrames( segments, closed ),
-			tangents = frames.tangents,
-			normals = frames.normals,
-			binormals = frames.binormals;
-
-		const position = new Vector3();
-
-		function ParametricTube( u, v, target ) {
-
-			v *= 2 * Math.PI;
-
-			const i = Math.floor( u * ( numpoints - 1 ) );
-
-			path.getPointAt( u, position );
-
-			const normal = normals[ i ];
-			const binormal = binormals[ i ];
-
-			const cx = - radius * Math.cos( v ); // TODO: Hack: Negating it so it faces outside.
-			const cy = radius * Math.sin( v );
-
-			position.x += cx * normal.x + cy * binormal.x;
-			position.y += cx * normal.y + cy * binormal.y;
-			position.z += cx * normal.z + cy * binormal.z;
-
-			target.copy( position );
-
-		}
-
-		super( ParametricTube, segments, segmentsRadius );
-
-		// proxy internals
-
-		this.tangents = tangents;
-		this.normals = normals;
-		this.binormals = binormals;
-
-		this.path = path;
-		this.segments = segments;
-		this.radius = radius;
-		this.segmentsRadius = segmentsRadius;
-		this.closed = closed;
-
-	}
-
-};
-
-
-/*********************************************
-  *
-  * Parametric Replacement for TorusKnotGeometry
-  *
-  *********************************************/
-ParametricGeometries.TorusKnotGeometry = class TorusKnotGeometry extends ParametricGeometries.TubeGeometry {
-
-	constructor( radius = 200, tube = 40, segmentsT = 64, segmentsR = 8, p = 2, q = 3 ) {
-
-		class TorusKnotCurve extends Curve {
-
-			getPoint( t, optionalTarget = new Vector3() ) {
-
-				const point = optionalTarget;
-
-				t *= Math.PI * 2;
-
-				const r = 0.5;
-
-				const x = ( 1 + r * Math.cos( q * t ) ) * Math.cos( p * t );
-				const y = ( 1 + r * Math.cos( q * t ) ) * Math.sin( p * t );
-				const z = r * Math.sin( q * t );
-
-				return point.set( x, y, z ).multiplyScalar( radius );
-
-			}
-
-		}
-
-		const segments = segmentsT;
-		const radiusSegments = segmentsR;
-		const extrudePath = new TorusKnotCurve();
-
-		super( extrudePath, segments, tube, radiusSegments, true, false );
-
-		this.radius = radius;
-		this.tube = tube;
-		this.segmentsT = segmentsT;
-		this.segmentsR = segmentsR;
-		this.p = p;
-		this.q = q;
-
-	}
-
-};
-
-/*********************************************
-  *
-  * Parametric Replacement for SphereGeometry
-  *
-  *********************************************/
-ParametricGeometries.SphereGeometry = class SphereGeometry extends ParametricGeometry {
-
-	constructor( size, u, v ) {
-
-		function sphere( u, v, target ) {
-
-			u *= Math.PI;
-			v *= 2 * Math.PI;
-
-			const x = size * Math.sin( u ) * Math.cos( v );
-			const y = size * Math.sin( u ) * Math.sin( v );
-			const z = size * Math.cos( u );
-
-			target.set( x, y, z );
-
-		}
-
-		super( sphere, u, v );
-
-	}
-
-};
-
-
-/*********************************************
-  *
-  * Parametric Replacement for PlaneGeometry
-  *
-  *********************************************/
-
-ParametricGeometries.PlaneGeometry = class PlaneGeometry extends ParametricGeometry {
-
-	constructor( width, depth, segmentsWidth, segmentsDepth ) {
-
-		function plane( u, v, target ) {
-
-			const x = u * width;
-			const y = 0;
-			const z = v * depth;
-
-			target.set( x, y, z );
-
-		}
-
-		super( plane, segmentsWidth, segmentsDepth );
-
-	}
-
-};
-
-export { ParametricGeometries };