improve KeyframeTrack and subtype docs

mrdoob · May 5, 2024 · 8b421ba · 8b421ba
1 parent 98c070e
commit 8b421ba
Show file tree

Hide file tree

Showing 12 changed files with 103 additions and 33 deletions.
diff --git a/build/three.cjs b/build/three.cjs
@@ -5,7 +5,7 @@
  */
 'use strict';
 
-const REVISION = '164';
+const REVISION = '165dev';
 
 const MOUSE = { LEFT: 0, MIDDLE: 1, RIGHT: 2, ROTATE: 0, DOLLY: 1, PAN: 2 };
 const TOUCH = { ROTATE: 0, PAN: 1, DOLLY_PAN: 2, DOLLY_ROTATE: 3 };
@@ -17322,7 +17322,7 @@ function WebGLExtensions( gl ) {
 
 			if ( extension === null ) {
 
-				console.warn( 'THREE.WebGLRenderer: ' + name + ' extension not supported.' );
+				warnOnce( 'THREE.WebGLRenderer: ' + name + ' extension not supported.' );
 
 			}
 
@@ -42553,7 +42553,16 @@ KeyframeTrack.prototype.DefaultInterpolation = InterpolateLinear;
 /**
  * A Track of Boolean keyframe values.
  */
-class BooleanKeyframeTrack extends KeyframeTrack {}
+class BooleanKeyframeTrack extends KeyframeTrack {
+
+	// No interpolation parameter because only InterpolateDiscrete makes sense.
+	constructor( name, times, values ) {
+
+		super( name, times, values );
+
+	}
+
+}
 
 BooleanKeyframeTrack.prototype.ValueTypeName = 'bool';
 BooleanKeyframeTrack.prototype.ValueBufferType = Array;
@@ -42624,13 +42633,22 @@ class QuaternionKeyframeTrack extends KeyframeTrack {
 
 QuaternionKeyframeTrack.prototype.ValueTypeName = 'quaternion';
 // ValueBufferType is inherited
-QuaternionKeyframeTrack.prototype.DefaultInterpolation = InterpolateLinear;
+// DefaultInterpolation is inherited;
 QuaternionKeyframeTrack.prototype.InterpolantFactoryMethodSmooth = undefined;
 
 /**
  * A Track that interpolates Strings
  */
-class StringKeyframeTrack extends KeyframeTrack {}
+class StringKeyframeTrack extends KeyframeTrack {
+
+	// No interpolation parameter because only InterpolateDiscrete makes sense.
+	constructor( name, times, values ) {
+
+		super( name, times, values );
+
+	}
+
+}
 
 StringKeyframeTrack.prototype.ValueTypeName = 'string';
 StringKeyframeTrack.prototype.ValueBufferType = Array;
@@ -43503,6 +43521,10 @@ class FileLoader extends Loader {
 
 									}
 
+								}, ( e ) => {
+
+									controller.error( e );
+
 								} );
 
 							}
@@ -50996,13 +51018,15 @@ function ascSort( a, b ) {
 
 function intersect( object, raycaster, intersects, recursive ) {
 
+	let stopTraversal = false;
+
 	if ( object.layers.test( raycaster.layers ) ) {
 
-		object.raycast( raycaster, intersects );
+		stopTraversal = object.raycast( raycaster, intersects );
 
 	}
 
-	if ( recursive === true ) {
+	if ( recursive === true && stopTraversal !== true ) {
 
 		const children = object.children;
 

diff --git a/build/three.module.js b/build/three.module.js
@@ -3,7 +3,7 @@
  * Copyright 2010-2024 Three.js Authors
  * SPDX-License-Identifier: MIT
  */
-const REVISION = '164';
+const REVISION = '165dev';
 
 const MOUSE = { LEFT: 0, MIDDLE: 1, RIGHT: 2, ROTATE: 0, DOLLY: 1, PAN: 2 };
 const TOUCH = { ROTATE: 0, PAN: 1, DOLLY_PAN: 2, DOLLY_ROTATE: 3 };
@@ -17320,7 +17320,7 @@ function WebGLExtensions( gl ) {
 
 			if ( extension === null ) {
 
-				console.warn( 'THREE.WebGLRenderer: ' + name + ' extension not supported.' );
+				warnOnce( 'THREE.WebGLRenderer: ' + name + ' extension not supported.' );
 
 			}
 
@@ -42551,7 +42551,16 @@ KeyframeTrack.prototype.DefaultInterpolation = InterpolateLinear;
 /**
  * A Track of Boolean keyframe values.
  */
-class BooleanKeyframeTrack extends KeyframeTrack {}
+class BooleanKeyframeTrack extends KeyframeTrack {
+
+	// No interpolation parameter because only InterpolateDiscrete makes sense.
+	constructor( name, times, values ) {
+
+		super( name, times, values );
+
+	}
+
+}
 
 BooleanKeyframeTrack.prototype.ValueTypeName = 'bool';
 BooleanKeyframeTrack.prototype.ValueBufferType = Array;
@@ -42622,13 +42631,22 @@ class QuaternionKeyframeTrack extends KeyframeTrack {
 
 QuaternionKeyframeTrack.prototype.ValueTypeName = 'quaternion';
 // ValueBufferType is inherited
-QuaternionKeyframeTrack.prototype.DefaultInterpolation = InterpolateLinear;
+// DefaultInterpolation is inherited;
 QuaternionKeyframeTrack.prototype.InterpolantFactoryMethodSmooth = undefined;
 
 /**
  * A Track that interpolates Strings
  */
-class StringKeyframeTrack extends KeyframeTrack {}
+class StringKeyframeTrack extends KeyframeTrack {
+
+	// No interpolation parameter because only InterpolateDiscrete makes sense.
+	constructor( name, times, values ) {
+
+		super( name, times, values );
+
+	}
+
+}
 
 StringKeyframeTrack.prototype.ValueTypeName = 'string';
 StringKeyframeTrack.prototype.ValueBufferType = Array;
@@ -43501,6 +43519,10 @@ class FileLoader extends Loader {
 
 									}
 
+								}, ( e ) => {
+
+									controller.error( e );
+
 								} );
 
 							}
@@ -50994,13 +51016,15 @@ function ascSort( a, b ) {
 
 function intersect( object, raycaster, intersects, recursive ) {
 
+	let stopTraversal = false;
+
 	if ( object.layers.test( raycaster.layers ) ) {
 
-		object.raycast( raycaster, intersects );
+		stopTraversal = object.raycast( raycaster, intersects );
 
 	}
 
-	if ( recursive === true ) {
+	if ( recursive === true && stopTraversal !== true ) {
 
 		const children = object.children;
 

diff --git a/build/three.module.min.js b/build/three.module.min.js
diff --git a/docs/api/en/animation/tracks/BooleanKeyframeTrack.html b/docs/api/en/animation/tracks/BooleanKeyframeTrack.html
@@ -23,14 +23,18 @@ <h3>
 			[page:Array times] - (required) array of keyframe times.<br />
 			[page:Array values] - values for the keyframes at the times specified.<br />
 		</p>
+		<p>
+			This keyframe track type has no interpolation parameter because the
+			interpolation is always [page:Animation InterpolateDiscrete].
+		</p>
 
 		<h2>Properties</h2>
 
 		<p class="desc">See [page:KeyframeTrack] for inherited properties.</p>
 
 		<h3>[property:Constant DefaultInterpolation]</h3>
 		<p>
-			The default interpolation type to use, [page:Animation InterpolateDiscrete].
+			The default interpolation type to use. Only [page:Animation InterpolateDiscrete] makes sense for this track type.
 		</p>
 
 		<h3>[property:Array ValueBufferType]</h3>

diff --git a/docs/api/en/animation/tracks/ColorKeyframeTrack.html b/docs/api/en/animation/tracks/ColorKeyframeTrack.html
@@ -20,7 +20,7 @@ <h1>[name]</h1>
 		<h2>Constructor</h2>
 
 		<h3>
-			[name]( [param:String name], [param:Array times], [param:Array values] )
+			[name]( [param:String name], [param:Array times], [param:Array values], [param:Constant interpolation] )
 		</h3>
 		<p>
 			[page:String name] - (required) identifier for the KeyframeTrack.<br />

diff --git a/docs/api/en/animation/tracks/NumberKeyframeTrack.html b/docs/api/en/animation/tracks/NumberKeyframeTrack.html
@@ -16,7 +16,7 @@ <h1>[name]</h1>
 		<h2>Constructor</h2>
 
 		<h3>
-			[name]( [param:String name], [param:Array times], [param:Array values] )
+			[name]( [param:String name], [param:Array times], [param:Array values], [param:Constant interpolation] )
 		</h3>
 		<p>
 			[page:String name] - (required) identifier for the KeyframeTrack.<br />

diff --git a/docs/api/en/animation/tracks/QuaternionKeyframeTrack.html b/docs/api/en/animation/tracks/QuaternionKeyframeTrack.html
@@ -16,14 +16,14 @@ <h1>[name]</h1>
 		<h2>Constructor</h2>
 
 		<h3>
-			[name]( [param:String name], [param:Array times], [param:Array values] )
+			[name]( [param:String name], [param:Array times], [param:Array values], [param:Constant interpolation] )
 		</h3>
 		<p>
-			[page:String name] (required) identifier for the KeyframeTrack.<br />
-			[page:Array times] (required) array of keyframe times.<br />
-			[page:Array values] values for the keyframes at the times specified, a
+			[page:String name] - (required) identifier for the KeyframeTrack.<br />
+			[page:Array times] - (required) array of keyframe times.<br />
+			[page:Array values] - values for the keyframes at the times specified, a
 			flat array of quaternion components.<br />
-			[page:Constant interpolation] the type of interpolation to use. See
+			[page:Constant interpolation] - the type of interpolation to use. See
 			[page:Animation Animation Constants] for possible values. Default is
 			[page:Animation InterpolateLinear].
 		</p>

diff --git a/docs/api/en/animation/tracks/StringKeyframeTrack.html b/docs/api/en/animation/tracks/StringKeyframeTrack.html
@@ -24,9 +24,10 @@ <h3>
 			[page:String name] - (required) identifier for the KeyframeTrack.<br />
 			[page:Array times] - (required) array of keyframe times.<br />
 			[page:Array values] - values for the keyframes at the times specified.<br />
-			[page:Constant interpolation] - the type of interpolation to use. See
-			[page:Animation Animation Constants] for possible values. Default is
-			[page:Animation InterpolateDiscrete].
+		</p>
+		<p>
+			This keyframe track type has no interpolation parameter because the
+			interpolation is always [page:Animation InterpolateDiscrete].
 		</p>
 
 		<h2>Properties</h2>
@@ -35,7 +36,7 @@ <h2>Properties</h2>
 
 		<h3>[property:Constant DefaultInterpolation]</h3>
 		<p>
-			The default interpolation type to use, [page:Animation InterpolateDiscrete].
+			The default interpolation type to use. Only [page:Animation InterpolateDiscrete] makes sense for this track type.
 		</p>
 
 		<h3>[property:Array ValueBufferType]</h3>
@@ -70,4 +71,4 @@ <h2>Source</h2>
 		</p>
 	</body>
 
-</html>
+</html>
diff --git a/docs/api/en/animation/tracks/VectorKeyframeTrack.html b/docs/api/en/animation/tracks/VectorKeyframeTrack.html
@@ -17,7 +17,7 @@ <h1>[name]</h1>
 		<h2>Constructor</h2>
 
 		<h3>
-			[name]( [param:String name], [param:Array times], [param:Array values] )
+			[name]( [param:String name], [param:Array times], [param:Array values], [param:Constant interpolation] )
 		</h3>
 		<p>
 			[page:String name] - (required) identifier for the KeyframeTrack.<br />

diff --git a/src/animation/tracks/BooleanKeyframeTrack.js b/src/animation/tracks/BooleanKeyframeTrack.js
@@ -4,7 +4,16 @@ import { KeyframeTrack } from '../KeyframeTrack.js';
 /**
  * A Track of Boolean keyframe values.
  */
-class BooleanKeyframeTrack extends KeyframeTrack {}
+class BooleanKeyframeTrack extends KeyframeTrack {
+
+	// No interpolation parameter because only InterpolateDiscrete makes sense.
+	constructor( name, times, values ) {
+
+		super( name, times, values );
+
+	}
+
+}
 
 BooleanKeyframeTrack.prototype.ValueTypeName = 'bool';
 BooleanKeyframeTrack.prototype.ValueBufferType = Array;

diff --git a/src/animation/tracks/QuaternionKeyframeTrack.js b/src/animation/tracks/QuaternionKeyframeTrack.js
@@ -1,4 +1,3 @@
-import { InterpolateLinear } from '../../constants.js';
 import { KeyframeTrack } from '../KeyframeTrack.js';
 import { QuaternionLinearInterpolant } from '../../math/interpolants/QuaternionLinearInterpolant.js';
 
@@ -17,7 +16,7 @@ class QuaternionKeyframeTrack extends KeyframeTrack {
 
 QuaternionKeyframeTrack.prototype.ValueTypeName = 'quaternion';
 // ValueBufferType is inherited
-QuaternionKeyframeTrack.prototype.DefaultInterpolation = InterpolateLinear;
+// DefaultInterpolation is inherited;
 QuaternionKeyframeTrack.prototype.InterpolantFactoryMethodSmooth = undefined;
 
 export { QuaternionKeyframeTrack };
diff --git a/src/animation/tracks/StringKeyframeTrack.js b/src/animation/tracks/StringKeyframeTrack.js
@@ -4,7 +4,16 @@ import { KeyframeTrack } from '../KeyframeTrack.js';
 /**
  * A Track that interpolates Strings
  */
-class StringKeyframeTrack extends KeyframeTrack {}
+class StringKeyframeTrack extends KeyframeTrack {
+
+	// No interpolation parameter because only InterpolateDiscrete makes sense.
+	constructor( name, times, values ) {
+
+		super( name, times, values );
+
+	}
+
+}
 
 StringKeyframeTrack.prototype.ValueTypeName = 'string';
 StringKeyframeTrack.prototype.ValueBufferType = Array;