Docs: Add page for Timer. (#27394)

mrdoob · Dec 18, 2023 · b99b3fd · b99b3fd
1 parent 6525d32
commit b99b3fd
Show file tree

Hide file tree

Showing 3 changed files with 128 additions and 9 deletions.
diff --git a/docs/examples/en/misc/Timer.html b/docs/examples/en/misc/Timer.html
@@ -0,0 +1,124 @@
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<base href="../../../" />
+		<script src="page.js"></script>
+		<link type="text/css" rel="stylesheet" href="page.css" />
+	</head>
+	<body>
+
+		<h1>[name]</h1>
+
+		<p class="desc">
+			This class is an alternative to [page:Clock] with a different API design and behavior
+			The goal is to avoid the conceptual flaws that became apparent in [page:Clock] over time.
+
+			<ul>
+				<li>[name] has an [page:.update]() method that updates its internal state. That makes it possible to call [page:.getDelta]() and [page:.getElapsed]() multiple times per simulation step without getting different values.</li>
+				<li>The class uses the Page Visibility API to avoid large time delta values when the app is inactive (e.g. tab switched or browser hidden).</li>
+				<li>It's possible to configure a fixed time delta and a time scale value (similar to Unity's Time interface).</li>
+			</ul>
+		</p>
+
+		<h2>Import</h2>
+
+		<p>
+			[name] is an add-on, and must be imported explicitly.
+			See [link:#manual/introduction/Installation Installation / Addons].
+		</p>
+
+		<code>
+			import { Timer } from 'three/addons/misc/Timer.js';
+		</code>
+
+		<h2>Code Example</h2>
+
+		<code>
+		const timer = new Timer();
+
+		function animate() {
+
+			requestAnimationFrame( animate );
+
+			timer.update();
+
+			const delta = timer.getDelta();
+
+			// do something with delta
+
+			renderer.render( scene, camera );
+
+		}
+		</code>
+
+		<h2>Examples</h2>
+
+		<p>
+			[example:webgl_morphtargets_sphere WebGL / morphtargets / sphere]
+		</p>
+
+		<h2>Constructor</h2>
+
+		<h3>Timer()</h3>
+
+		<h2>Methods</h2>
+
+		<h3>[method:this disableFixedDelta]()</h3>
+		<p>
+			Disables the usage of a fixed delta time.
+		</p>
+
+		<h3>[method:this dispose]()</h3>
+		<p>
+			Can be used to free all internal resources. Usually called when the timer instance isn't required anymore.
+		</p>
+
+		<h3>[method:this enableFixedDelta]()</h3>
+		<p>
+			Enables the usage of a fixed delta time.
+		</p>
+
+		<h3>[method:Number getDelta]()</h3>
+		<p>
+			Returns the time delta in seconds.
+		</p>
+
+		<h3>[method:Number getElapsed]()</h3>
+		<p>
+			Returns the elapsed time in seconds.
+		</p>
+
+		<h3>[method:Number getFixedDelta]()</h3>
+		<p>
+			Returns the fixed time delta that has been previously configured via [page:.setFixedDelta]().
+		</p>
+
+		<h3>[method:this reset]()</h3>
+		<p>
+			Resets the time computation for the current simulation step.
+		</p>
+
+		<h3>[method:this setFixedDelta]( [param:Number delta] )</h3>
+		<p>
+			Defines a fixed time delta value which is used to update the timer per simulation step.
+		</p>
+
+		<h3>[method:this setTimescale]( [param:Number timescale] )</h3>
+		<p>
+			Sets a time scale that scales the time delta in [page:.update]().
+		</p>
+
+		<h3>[method:this update]()</h3>
+		<p>
+			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 [page:.getDelta]()).
+		</p>
+
+		<h2>Source</h2>
+
+		<p>
+			[link:https://github.com/mrdoob/three.js/blob/master/examples/jsm/misc/Timer.js examples/jsm/misc/Timer.js]
+		</p>
+	</body>
+</html>
diff --git a/docs/list.json b/docs/list.json
@@ -400,6 +400,10 @@
 				"OBB": "examples/en/math/OBB"
 			},
 
+			"Misc": {
+				"Timer": "examples/en/misc/Timer"
+			},
+
 			"ConvexHull": {
 				"Face": "examples/en/math/convexhull/Face",
 				"HalfEdge": "examples/en/math/convexhull/HalfEdge",

diff --git a/examples/jsm/misc/Timer.js b/examples/jsm/misc/Timer.js
@@ -1,12 +1,3 @@
-/**
- * This class is a new alternative to THREE.Clock with a different API design and behavior.
- * The goal is to avoid the conceptual flaws that became apparent in THREE.Clock over time.
- *
- * - THREE.Timer has an update() method that updates its internal state. That makes it possible to call .getDeltaTime() and
- *    .getElapsedTime() multiple times per simulation step without getting different values.
- * - The class uses the Page Visibility API to avoid large time delta values when the app is inactive (e.g. tab switched or browser hidden).
- * - It's possible to configure a fixed time delta and a time scale value (similar to Unity's Time interface).
- */
 class Timer {
 
 	constructor() {