Timer: Add `connect()`/`disconnect()`. (#30551)

* Timer: Add `connect()`/`disconnect()`.

* Examples: Clean up.

docs/examples/en/misc/Timer.html

@@ -16,7 +16,7 @@
 
 			<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>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).</li>
 			</ul>
 		</p>
 
@@ -60,12 +60,20 @@
 
 		<h2>Constructor</h2>
 
-		<h3>Timer( [param:Boolean usePageVisibilityAPI] )</h3>
+		<h3>Timer()</h3>
+
+		<h2>Methods</h2>
+
+		<h3>[method:this connect]( [param:Document document] )</h3>
 		<p>
-			[page:Boolean usePageVisibilityAPI] - (optional) Whether to use the Page Visibility API to avoid large time delta values in inactive tabs or not. Default is `true`. 
+			Connects 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.
 		</p>
 
-		<h2>Methods</h2>
+		<h3>[method:this disconnect]()</h3>
+		<p>
+			Disconnects the timer from the DOM and also disables the usage of the Page Visibility API.
+		</p>
 
 		<h3>[method:Number getDelta]()</h3>
 		<p>

examples/jsm/misc/Timer.js

@@ -1,6 +1,6 @@
 class Timer {
 
-	constructor( usePageVisibilityAPI = true ) {
+	constructor() {
 
 		this._previousTime = 0;
 		this._currentTime = 0;
@@ -11,11 +11,18 @@ class Timer {
 
 		this._timescale = 1;
 
-		// use Page Visibility API to avoid large time delta values
+		this._document = null;
+		this._pageVisibilityHandler = null;
+
+	}
 
-		this._usePageVisibilityAPI = ( usePageVisibilityAPI === true ) && ( typeof document !== 'undefined' && document.hidden !== undefined );
+	connect( document ) {
 
-		if ( this._usePageVisibilityAPI === true ) {
+		this._document = document;
+
+		// use Page Visibility API to avoid large time delta values
+
+		if ( document.hidden !== undefined ) {
 
 			this._pageVisibilityHandler = handleVisibilityChange.bind( this );
 
@@ -25,6 +32,19 @@ class Timer {
 
 	}
 
+	disconnect() {
+
+		if ( this._pageVisibilityHandler !== null ) {
+
+			this._document.removeEventListener( 'visibilitychange', this._pageVisibilityHandler );
+			this._pageVisibilityHandler = null;
+
+		}
+
+		this._document = null;
+
+	}
+
 	getDelta() {
 
 		return this._delta / 1000;
@@ -61,11 +81,7 @@ class Timer {
 
 	dispose() {
 
-		if ( this._usePageVisibilityAPI === true ) {
-
-			document.removeEventListener( 'visibilitychange', this._pageVisibilityHandler );
-
-		}
+		this.disconnect();
 
 		return this;
 
@@ -73,8 +89,7 @@ class Timer {
 
 	update( timestamp ) {
 
-
-		if ( this._usePageVisibilityAPI === true && document.hidden === true ) {
+		if ( this._pageVisibilityHandler !== null && this._document.hidden === true ) {
 
 			this._delta = 0;
 
@@ -121,7 +136,7 @@ function now() {
 
 function handleVisibilityChange() {
 
-	if ( document.hidden === false ) this.reset();
+	if ( this._document.hidden === false ) this.reset();
 
 }
 

examples/webgl_buffergeometry_lines.html

@@ -51,6 +51,7 @@
 				scene = new THREE.Scene();
 
 				timer = new Timer();
+				timer.connect( document );
 
 				const geometry = new THREE.BufferGeometry();
 				const material = new THREE.LineBasicMaterial( { vertexColors: true } );

examples/webgl_geometry_dynamic.html

@@ -50,6 +50,7 @@
 				camera.position.y = 200;
 
 				timer = new Timer();
+				timer.connect( document );
 
 				scene = new THREE.Scene();
 				scene.background = new THREE.Color( 0xaaccff );

examples/webgl_morphtargets_sphere.html

@@ -49,6 +49,7 @@
 				scene = new THREE.Scene();
 
 				timer = new Timer();
+				timer.connect( document );
 
 				const light1 = new THREE.PointLight( 0xff2200, 50000 );
 				light1.position.set( 100, 100, 100 );

examples/webgpu_display_stereo.html

@@ -62,6 +62,7 @@
 					.load( [ 'px.jpg', 'nx.jpg', 'py.jpg', 'ny.jpg', 'pz.jpg', 'nz.jpg' ] );
 
 				timer = new Timer();
+				timer.connect( document );
 
 				const geometry = new THREE.SphereGeometry( 0.1, 32, 16 );
 

examples/webgpu_postprocessing_difference.html

@@ -62,6 +62,7 @@
 				scene.background = new THREE.Color( 0x0487e2 );
 
 				timer = new Timer();
+				timer.connect( document );
 
 				const texture = new THREE.TextureLoader().load( 'textures/crate.gif' );
 				texture.colorSpace = THREE.SRGBColorSpace;

examples/webgpu_postprocessing_ssaa.html

@@ -87,6 +87,7 @@
 				document.body.appendChild( stats.dom );
 
 				timer = new Timer();
+				timer.connect( document );
 
 				camera = new THREE.PerspectiveCamera( 65, width / height, 3, 10 );
 				camera.position.z = 7;

examples/webgpu_tsl_vfx_linkedparticles.html

@@ -87,6 +87,7 @@
 				scene = new THREE.Scene();
 
 				timer = new Timer();
+				timer.connect( document );
 
 				// renderer