AF Manager class for dynamic animation frame request/cancel (#1407)

* AFManager class for dynamic animation frame request/cancel

* spacing

* spacing

* rename class

* Add pending AF management

* minor comment

* spacing

* FrameScheduler referenced by LRUCache,PriorityQueue, throttle and QueryManager; updated Dingo Gap VR sample

* camel casing; intialization in LRU, PriorityQueue and QueryManager

* - replace "removeXRSession" with "setXRSession( null )"
- remove unused function
- remove use of "window"
- ensure "flushPending" clears all pending handles
- code style update

* Add tests for FrameScheduler

* small cleanup

* comment

* variable rename

* initial commit for singleton framescheduler

* fix spaces

* Make the FrameScheduler a singleton

* Fix tsts

* Update docs

* FrameScheduler -> Scheduler

* Update the vrDemo

* Add d.ts

---------

Co-authored-by: Garrett Johnson <garrett.kjohnson@gmail.com>

Author: phoenixbf

eslint.config.js

@@ -67,6 +67,7 @@ export default [
 			'@typescript-eslint/no-unused-vars': [ 'error', { args: 'none' } ],
 			'@typescript-eslint/no-explicit-any': 'off',
 			'@typescript-eslint/no-empty-object-type': 'off',
+			'@typescript-eslint/no-unsafe-function-type': 'off',
 		},
 	},
 

example/three/vr.js

@@ -1,4 +1,4 @@
-import { TilesRenderer } from '3d-tiles-renderer';
+import { TilesRenderer, Scheduler } from '3d-tiles-renderer';
 import {
 	Scene,
 	DirectionalLight,
@@ -98,18 +98,6 @@ function init() {
 	tiles.setCamera( camera );
 	tiles.setResolutionFromRenderer( camera, renderer );
 
-
-	// We define a custom scheduling callback to handle also active WebXR sessions
-	const tilesSchedulingCB = func => {
-
-		tasks.push( func );
-
-	};
-
-	// We set our scheduling callback for tiles downloading and parsing
-	tiles.downloadQueue.schedulingCallback = tilesSchedulingCB;
-	tiles.parseQueue.schedulingCallback = tilesSchedulingCB;
-
 	tiles.lruCache.maxSize = 1200;
 	tiles.lruCache.minSize = 900;
 
@@ -230,6 +218,8 @@ function handleCamera() {
 
 			xrSession = renderer.xr.getSession();
 
+			Scheduler.setXRSession( xrSession );
+
 		}
 
 	} else {
@@ -246,6 +236,8 @@ function handleCamera() {
 
 			xrSession = null;
 
+			Scheduler.setXRSession( null );
+
 		}
 
 	}

src/core/renderer/API.md

@@ -539,6 +539,15 @@ Priority queue for scheduling async work with a concurrency limit. Items are
 sorted by `priorityCallback` and dispatched up to `maxJobs` at a time.
 
 
+### .running
+
+```js
+readonly running: boolean
+```
+
+returns whether tasks are queued or actively running
+
+
 ### .maxJobs
 
 ```js
@@ -567,18 +576,6 @@ Comparator used to sort queued items. Higher-priority items should sort last
 (i.e. return positive when `itemA` should run before `itemB`). Defaults to `null`.
 
 
-### .schedulingCallback
-
-```js
-schedulingCallback: ( func: function ) => void
-```
-
-Callback used to schedule when to run jobs next, so more work doesn't happen in a
-single frame than there is time for. Defaults to `requestAnimationFrame`. Should be
-overridden in scenarios where `requestAnimationFrame` is not reliable, such as when
-running in WebXR.
-
-
 ### .sort
 
 ```js
@@ -651,6 +648,48 @@ Error thrown when a queued item's promise is rejected because the item was remov
 before its callback could run.
 
 
+## Scheduler
+
+Class used within TilesRenderer for scheduling requestAnimationFrame events and
+toggling between XRSession rAF and window rAF toggles.
+
+
+### static .setXRSession
+
+```js
+static setXRSession( session: XRSession ): void
+```
+
+Sets the active "XRSession" value to use to scheduling rAF callbacks.
+
+
+### static .requestAnimationFrame
+
+```js
+static requestAnimationFrame( cb: function ): number
+```
+
+Request animation frame (defer to XR session if set)
+
+
+### static .cancelAnimationFrame
+
+```js
+static cancelAnimationFrame( handle: number ): void
+```
+
+Cancel animation frame via handle (defer to XR session if set)
+
+
+### static .flushPending
+
+```js
+static flushPending(): void
+```
+
+Flush and complete pending AFs (defer to XR session if set)
+
+
 ## TilesRendererBase
 
 Base class for 3D Tiles renderers. Manages tile loading, caching, traversal,

src/core/renderer/utilities/LRUCache.js

@@ -1,3 +1,5 @@
+import { Scheduler } from './Scheduler.js';
+
 const GIGABYTE_BYTES = 2 ** 30;
 
 /**
@@ -450,7 +452,7 @@ class LRUCache {
 
 		if ( needsRerun ) {
 
-			this.unloadingHandle = requestAnimationFrame( () => this.scheduleUnload() );
+			this.unloadingHandle = Scheduler.requestAnimationFrame( () => this.scheduleUnload() );
 
 		}
 
@@ -461,7 +463,7 @@ class LRUCache {
 	 */
 	scheduleUnload() {
 
-		cancelAnimationFrame( this.unloadingHandle );
+		Scheduler.cancelAnimationFrame( this.unloadingHandle );
 
 		if ( ! this.scheduled ) {
 

src/core/renderer/utilities/PriorityQueue.js

@@ -1,3 +1,5 @@
+import { Scheduler } from './Scheduler.js';
+
 /**
  * Error thrown when a queued item's promise is rejected because the item was removed
  * before its callback could run.
@@ -45,13 +47,38 @@ export class PriorityQueueItemRemovedError extends Error {
  */
 export class PriorityQueue {
 
-	// returns whether tasks are queued or actively running
+	/**
+	 * returns whether tasks are queued or actively running
+	 * @readonly
+	 * @type {boolean}
+	 */
 	get running() {
 
 		return this.items.length !== 0 || this.currJobs !== 0;
 
 	}
 
+	/**
+	 * Callback used to schedule when to run jobs next, so more work doesn't happen in a
+	 * single frame than there is time for. Defaults to `requestAnimationFrame`. Should be
+	 * overridden in scenarios where `requestAnimationFrame` is not reliable, such as when
+	 * running in WebXR.
+	 * @type {SchedulingCallback}
+	 * @deprecated
+	 */
+	get schedulingCallback() {
+
+		return this._schedulingCallback;
+
+	}
+
+	set schedulingCallback( cb ) {
+
+		console.log( 'PriorityQueue: Setting "schedulingCallback" has been deprecated. Use Scheduler to switch to an XRSession rAF, instead.' );
+		this._schedulingCallback = cb;
+
+	}
+
 	constructor() {
 
 		/**
@@ -78,16 +105,9 @@ export class PriorityQueue {
 		 */
 		this.priorityCallback = null;
 
-		/**
-		 * Callback used to schedule when to run jobs next, so more work doesn't happen in a
-		 * single frame than there is time for. Defaults to `requestAnimationFrame`. Should be
-		 * overridden in scenarios where `requestAnimationFrame` is not reliable, such as when
-		 * running in WebXR.
-		 * @type {SchedulingCallback}
-		 */
-		this.schedulingCallback = func => {
+		this._schedulingCallback = func => {
 
-			requestAnimationFrame( func );
+			Scheduler.requestAnimationFrame( func );
 
 		};
 
@@ -289,7 +309,7 @@ export class PriorityQueue {
 
 		if ( ! this.scheduled ) {
 
-			this.schedulingCallback( this._runjobs );
+			this._schedulingCallback( this._runjobs );
 
 			this.scheduled = true;
 

src/core/renderer/utilities/Scheduler.d.ts

@@ -0,0 +1,8 @@
+export class Scheduler {
+
+	static setXRSession( session: XRSession ): void;
+	static requestAnimationFrame( cb: Function ): number;
+	static cancelAnimationFrame( handle: number ): void;
+	static flushPending(): void;
+
+}

src/core/renderer/utilities/Scheduler.js

@@ -0,0 +1,98 @@
+/**
+ * Class used within TilesRenderer for scheduling requestAnimationFrame events and
+ * toggling between XRSession rAF and window rAF toggles.
+ */
+class Scheduler {
+
+	static pending = new Map();
+	static session = null;
+
+	/**
+	 * Sets the active "XRSession" value to use to scheduling rAF callbacks.
+	 * @param {XRSession} session
+	 */
+	static setXRSession( session ) {
+
+		// call "flush" before assigning xr session to ensure callbacks are
+		// cancelled on the previous handle
+		if ( session !== this.session ) {
+
+			this.flushPending();
+			this.session = session;
+
+		}
+
+	}
+
+	/**
+	 * Request animation frame (defer to XR session if set)
+	 * @param {Function} cb
+	 * @returns {number}
+	 */
+	static requestAnimationFrame( cb ) {
+
+		const { session, pending } = this;
+		let handle;
+
+		const func = () => {
+
+			pending.delete( handle );
+			cb();
+
+		};
+
+		if ( ! session ) {
+
+			handle = requestAnimationFrame( func );
+
+		} else {
+
+			handle = session.requestAnimationFrame( func );
+
+		}
+
+		pending.set( handle, cb );
+
+		return handle;
+
+	}
+
+	/**
+	 * Cancel animation frame via handle (defer to XR session if set)
+	 * @param {number} handle
+	 */
+	static cancelAnimationFrame( handle ) {
+
+		const { pending, session } = this;
+		pending.delete( handle );
+
+		if ( ! session ) {
+
+			cancelAnimationFrame( handle );
+
+		} else {
+
+			session.cancelAnimationFrame( handle );
+
+		}
+
+	}
+
+
+	/**
+	 * Flush and complete pending AFs (defer to XR session if set)
+	 */
+	static flushPending() {
+
+		this.pending.forEach( ( cb, handle ) => {
+
+			cb();
+			this.cancelAnimationFrame( handle );
+
+		} );
+
+	}
+
+}
+
+export { Scheduler };

src/core/renderer/utilities/throttle.js

@@ -1,3 +1,5 @@
+import { Scheduler } from './Scheduler.js';
+
 // function that rate limits the amount of time a function can be called to once
 // per frame, initially queuing a new call for the next frame.
 export function throttle( callback ) {
@@ -7,7 +9,7 @@ export function throttle( callback ) {
 
 		if ( handle === null ) {
 
-			handle = requestAnimationFrame( () => {
+			handle = Scheduler.requestAnimationFrame( () => {
 
 				handle = null;
 				callback();

src/r3f/utilities/QueryManager.js

@@ -9,6 +9,7 @@ import {
 } from 'three';
 import { SceneObserver } from './SceneObserver.js';
 import { Ellipsoid } from '3d-tiles-renderer/three';
+import { Scheduler } from '../../core/renderer/utilities/Scheduler.js';
 
 const _raycaster = /* @__PURE__ */ new Raycaster();
 const _line0 = /* @__PURE__ */ new Line3();
@@ -201,7 +202,7 @@ export class QueryManager extends EventDispatcher {
 		if ( this.autoRun && ! this.scheduled ) {
 
 			this.scheduled = true;
-			requestAnimationFrame( () => {
+			Scheduler.requestAnimationFrame( () => {
 
 				this.scheduled = false;
 				this._runJobs();