@gnsx/three 0.184.19 → 0.185.2

package/src/profiler/ProfilerService.js

@@ -9,14 +9,22 @@
  *   __gnsx_profiler.downloadTrace()  // download gnsx-trace.json for Speedscope / Perfetto
  *   __gnsx_profiler.reset()          // clear samples and trace
  *   __gnsx_profiler.disable()
+ *
+ * Chrome trace: `tid=1` is synchronous work; `@profile` on async methods records the
+ * promise lifetime on `tid=2` so long async does not flatten the main row. For manual
+ * spans, use `beginSpan` / `endSpan` with `{ asyncTimeline: true }` in a `.finally()`.
  */
 
 const RING_SIZE = 120;
 const FRAME_BUDGET_MS = 1000 / 60;
-/** Max events in the trace log (~50s at 60fps with 8 labels). */
-const MAX_TRACE_EVENTS = 50_000;
+const TRACE_TID_MAIN = 1;
+const TRACE_TID_ASYNC = 2;
 const NOOP = () => {};
 
+const DUMMY_SPAN = Object.freeze( { label: '', t0: 0, _seq: 0 } );
+const NOOP_BEGIN_SPAN = () => DUMMY_SPAN;
+const NOOP_END_SPAN = () => {};
+
 class ProfilerServiceClass {
 
 	constructor() {
@@ -30,7 +38,7 @@ class ProfilerServiceClass {
 		this.cursors = new Map();
 		/** @type {Map<string, number>} */
 		this.counts = new Map();
-		/** @type {Map<string, Array<{ startTime: number, startMark: string, traced: boolean }>>} */
+		/** @type {Map<string, Array<{ startTime: number, startMark: string }>>} */
 		this.marks = new Map();
 		/** @type {ChromeTraceEvent[]} */
 		this.traceEvents = [];
@@ -56,6 +64,8 @@ class ProfilerServiceClass {
 			this.traceStartTime = performance.now();
 			this.begin = this._beginImpl.bind( this );
 			this.end = this._endImpl.bind( this );
+			this.beginSpan = this._beginSpanImpl.bind( this );
+			this.endSpan = this._endSpanImpl.bind( this );
 			this._exposeGlobal();
 			console.log( `[ProfilerService] auto-started from env (profile: ${this._profile})` );
 
@@ -63,6 +73,8 @@ class ProfilerServiceClass {
 
 			this.begin = NOOP;
 			this.end = NOOP;
+			this.beginSpan = NOOP_BEGIN_SPAN;
+			this.endSpan = NOOP_END_SPAN;
 
 		}
 
@@ -94,6 +106,8 @@ class ProfilerServiceClass {
 		this._enabled = true;
 		this.begin = this._beginImpl.bind( this );
 		this.end = this._endImpl.bind( this );
+		this.beginSpan = this._beginSpanImpl.bind( this );
+		this.endSpan = this._endSpanImpl.bind( this );
 		this._exposeGlobal();
 		console.log( `[ProfilerService] enabled (profile: ${this._profile}) — call __gnsx_profiler.report() or downloadTrace() from the console` );
 
@@ -105,6 +119,8 @@ class ProfilerServiceClass {
 		this._enabled = false;
 		this.begin = NOOP;
 		this.end = NOOP;
+		this.beginSpan = NOOP_BEGIN_SPAN;
+		this.endSpan = NOOP_END_SPAN;
 		console.log( '[ProfilerService] disabled' );
 
 	}
@@ -140,22 +156,8 @@ class ProfilerServiceClass {
 
 		}
 
-		const traced = this._profile === 'full' && this.traceEvents.length < MAX_TRACE_EVENTS;
-		if ( traced ) {
-
-			this.traceEvents.push( {
-				name: label,
-				ph: 'B',
-				ts: this._getTraceTimestamp( startTime ),
-				pid: 1,
-				tid: 1,
-				cat: 'gnsx',
-			} );
-
-		}
-
 		performance.mark( startMark );
-		stack.push( { startTime, startMark, traced } );
+		stack.push( { startTime, startMark } );
 
 		// Push onto the global call stack for exclusive-time tracking.
 		this.callStack.push( { label, childTime: 0 } );
@@ -173,13 +175,61 @@ class ProfilerServiceClass {
 		if ( stack.length === 0 ) this.marks.delete( label );
 
 		const now = performance.now();
-		const { startTime, startMark, traced } = mark;
+		const { startTime, startMark } = mark;
 		const duration = now - startTime;
 		const endMark = `gnsx:${label}:end:${++ this._markId}`;
 
 		performance.mark( endMark );
 		performance.measure( `gnsx:${label}`, startMark, endMark );
 
+		this._commitDurationSample( label, startTime, duration, TRACE_TID_MAIN );
+
+	}
+
+	/**
+	 * Per-invocation span start (pair with {@link ProfilerServiceClass#endSpan}).
+	 * Safe for concurrent async with the same label.
+	 *
+	 * @param {string} label
+	 * @return {import('./ProfilerService.js').SpanHandle}
+	 */
+	_beginSpanImpl( label ) {
+
+		const seq = ++ this._markId;
+		const t0 = performance.now();
+		const startMark = `gnsx:${label}:s${seq}:start`;
+		performance.mark( startMark );
+		return { label, t0, _seq: seq, _startMark: startMark };
+
+	}
+
+	/**
+	 * @param {import('./ProfilerService.js').SpanHandle} handle
+	 * @param {import('./ProfilerService.js').EndSpanOptions} [opts]
+	 */
+	_endSpanImpl( handle, opts ) {
+
+		if ( handle._seq === 0 ) return;
+
+		const now = performance.now();
+		const duration = now - handle.t0;
+		const endMark = `gnsx:${handle.label}:s${handle._seq}:end`;
+		performance.mark( endMark );
+		performance.measure( `gnsx:${handle.label}#${handle._seq}`, handle._startMark, endMark );
+
+		const traceTid = opts?.asyncTimeline === true ? TRACE_TID_ASYNC : TRACE_TID_MAIN;
+		this._commitDurationSample( handle.label, handle.t0, duration, traceTid );
+
+	}
+
+	/**
+	 * @param {string} label
+	 * @param {number} startTime
+	 * @param {number} durationMs
+	 * @param {typeof TRACE_TID_MAIN|typeof TRACE_TID_ASYNC} traceTid
+	 */
+	_commitDurationSample( label, startTime, durationMs, traceTid ) {
+
 		let buffer = this.buffers.get( label );
 		if ( ! buffer ) {
 
@@ -191,7 +241,7 @@ class ProfilerServiceClass {
 		}
 
 		const cursor = this.cursors.get( label );
-		buffer[ cursor ] = duration;
+		buffer[ cursor ] = durationMs;
 		this.cursors.set( label, ( cursor + 1 ) % RING_SIZE );
 		this.counts.set( label, Math.min( ( this.counts.get( label ) + 1 ), RING_SIZE ) );
 
@@ -203,7 +253,7 @@ class ProfilerServiceClass {
 		if ( top !== undefined && top.label === label ) {
 
 			this.callStack.pop();
-			const selfTime = Math.max( 0, duration - top.childTime );
+			const selfTime = Math.max( 0, durationMs - top.childTime );
 
 			let selfBuffer = this.selfBuffers.get( label );
 			if ( ! selfBuffer ) {
@@ -222,7 +272,7 @@ class ProfilerServiceClass {
 
 			// Propagate inclusive duration to the parent scope's child accumulator.
 			const parent = this.callStack.length > 0 ? this.callStack[ this.callStack.length - 1 ] : undefined;
-			if ( parent !== undefined ) parent.childTime += duration;
+			if ( parent !== undefined ) parent.childTime += durationMs;
 
 		} else {
 
@@ -231,14 +281,16 @@ class ProfilerServiceClass {
 
 		}
 
-		if ( traced ) {
+		if ( traceTid ) {
 
+			const traceName = traceTid === TRACE_TID_ASYNC ? `${label} (promise)` : label;
 			this.traceEvents.push( {
-				name: label,
-				ph: 'E',
-				ts: this._getTraceTimestamp( now ),
+				name: traceName,
+				ph: 'X',
+				ts: Math.round( this._getTraceTimestamp( startTime ) ),
+				dur: Math.max( 1, Math.round( durationMs * 1000 ) ),
 				pid: 1,
-				tid: 1,
+				tid: traceTid,
 				cat: 'gnsx',
 			} );
 
@@ -349,13 +401,53 @@ class ProfilerServiceClass {
 	 */
 	exportChromeTrace() {
 
+		const slices = [ ...this.traceEvents ];
+		slices.sort( ( a, b ) => {
+
+			if ( a.ts !== b.ts ) return a.ts - b.ts;
+			if ( a.tid !== b.tid ) return a.tid - b.tid;
+			return a.name.localeCompare( b.name );
+
+		} );
+		const hasAsync = slices.some( e => e.tid === TRACE_TID_ASYNC );
+		/** @type {import('./ProfilerService.js').ChromeTraceMetadataEvent[]} */
+		const prefix = [
+			{
+				cat: '__metadata',
+				name: 'process_name',
+				ph: 'M',
+				pid: 1,
+				tid: 0,
+				ts: 0,
+				args: { name: 'Genesys Profiler' },
+			},
+			{
+				cat: '__metadata',
+				name: 'thread_name',
+				ph: 'M',
+				pid: 1,
+				tid: TRACE_TID_MAIN,
+				ts: 0,
+				args: { name: 'Main thread' },
+			},
+		];
+		if ( hasAsync ) {
+
+			prefix.push( {
+				cat: '__metadata',
+				name: 'thread_name',
+				ph: 'M',
+				pid: 1,
+				tid: TRACE_TID_ASYNC,
+				ts: 0,
+				args: { name: 'Async (promise lifetime)' },
+			} );
+
+		}
+
 		return {
 			displayTimeUnit: 'ms',
-			traceEvents: [
-				{ name: 'process_name', ph: 'M', pid: 1, args: { name: 'Genesys Profiler' } },
-				{ name: 'thread_name', ph: 'M', pid: 1, tid: 1, args: { name: 'Main Thread' } },
-				...this.traceEvents,
-			],
+			traceEvents: [ ...prefix, ...slices ],
 		};
 
 	}
@@ -460,22 +552,38 @@ class ProfilerServiceClass {
  * @property {number|undefined} selfFrameBudget Exclusive time as percentage of a 60 fps frame budget.
  */
 
+/**
+ * @typedef {Object} SpanHandle
+ * @property {string} label
+ * @property {number} t0
+ * @property {number} _seq
+ * @property {string} _startMark
+ */
+
+/**
+ * @typedef {Object} EndSpanOptions
+ * @property {boolean} [asyncTimeline] When true, trace slice uses `tid=2` (virtual async row).
+ */
+
 /**
  * @typedef {Object} ChromeTraceEvent
  * @property {string} name
- * @property {'B'|'E'} ph
+ * @property {'X'} ph
  * @property {number} ts
+ * @property {number} dur
  * @property {1} pid
- * @property {1} tid
+ * @property {number} tid
  * @property {'gnsx'} cat
  */
 
 /**
  * @typedef {Object} ChromeTraceMetadataEvent
+ * @property {'__metadata'} cat
  * @property {'process_name'|'thread_name'} name
  * @property {'M'} ph
  * @property {1} pid
- * @property {1} [tid]
+ * @property {number} [tid]
+ * @property {0} ts
  * @property {{ name: string }} args
  */
 
@@ -491,28 +599,38 @@ class ProfilerServiceClass {
 
 const ProfilerService = new ProfilerServiceClass();
 
+function isThenable( x ) {
+
+	return (
+		( typeof x === 'object' || typeof x === 'function' ) &&
+		x !== null &&
+		typeof x.then === 'function'
+	);
+
+}
+
 function applyProfileToMethod( label, descriptor ) {
 
 	const original = descriptor.value;
 
 	function profiled( ...args ) {
 
-		ProfilerService.begin( label );
+		const span = ProfilerService.beginSpan( label );
 		try {
 
 			const result = original.apply( this, args );
-			if ( result instanceof Promise ) {
+			if ( isThenable( result ) ) {
 
-				return result.finally( () => ProfilerService.end( label ) );
+				return Promise.resolve( result ).finally( () => ProfilerService.endSpan( span, { asyncTimeline: true } ) );
 
 			}
 
-			ProfilerService.end( label );
+			ProfilerService.endSpan( span );
 			return result;
 
 		} catch ( error ) {
 
-			ProfilerService.end( label );
+			ProfilerService.endSpan( span );
 			throw error;
 
 		}
@@ -526,14 +644,39 @@ function applyProfileToMethod( label, descriptor ) {
 
 /**
  * Method decorator that profiles the decorated method.
- * The label is automatically set to `ClassName.methodName`.
+ * Default label: `ClassName.methodName`. Pass a custom tag via `@profile('My tag')`.
  *
+ * @param {Object|string} [targetOrTag]
+ * @param {string|symbol} [propertyKey]
+ * @param {PropertyDescriptor} [descriptor]
+ * @return {PropertyDescriptor|function(Object, string|symbol, PropertyDescriptor): PropertyDescriptor}
+ */
+function profile( targetOrTag, propertyKey, descriptor ) {
+
+	if ( arguments.length === 0 ) {
+
+		return defaultProfileDecorator;
+
+	}
+
+	if ( arguments.length === 1 && typeof targetOrTag === 'string' ) {
+
+		const customTag = targetOrTag;
+		return ( target, key, desc ) => applyProfileToMethod( customTag, desc );
+
+	}
+
+	return defaultProfileDecorator( targetOrTag, propertyKey, descriptor );
+
+}
+
+/**
  * @param {Object} target
  * @param {string|symbol} propertyKey
  * @param {PropertyDescriptor} descriptor
  * @return {PropertyDescriptor}
  */
-function profile( target, propertyKey, descriptor ) {
+function defaultProfileDecorator( target, propertyKey, descriptor ) {
 
 	const className = target.constructor?.name ?? 'Unknown';
 	return applyProfileToMethod( `${className}.${String( propertyKey )}`, descriptor );

package/src/renderers/WebGLRenderer.js

@@ -298,6 +298,10 @@ class WebGLRenderer {
 		let _isContextLost = false;
 		let _nodesHandler = null;
 
+		let _scratchFramebuffer = null;
+		let _srcFramebuffer = null;
+		let _dstFramebuffer = null;
+
 		// internal state cache
 
 		this._outputColorSpace = SRGBColorSpace;
@@ -397,11 +401,11 @@ class WebGLRenderer {
 
 					if ( getContext( contextName ) ) {
 
-						throw new Error( 'Error creating WebGL context with your selected attributes.' );
+						throw new Error( 'THREE.WebGLRenderer: Error creating WebGL context with your selected attributes.' );
 
 					} else {
 
-						throw new Error( 'Error creating WebGL context.' );
+						throw new Error( 'THREE.WebGLRenderer: Error creating WebGL context.' );
 
 					}
 
@@ -441,6 +445,10 @@ class WebGLRenderer {
 
 			}
 
+			_scratchFramebuffer = _gl.createFramebuffer();
+			_srcFramebuffer = _gl.createFramebuffer();
+			_dstFramebuffer = _gl.createFramebuffer();
+
 			info = new WebGLInfo( _gl );
 			properties = new WebGLProperties();
 			textures = new WebGLTextures( _gl, extensions, state, properties, capabilities, utils, info );
@@ -547,7 +555,7 @@ class WebGLRenderer {
 
 		if ( _outputBufferType !== UnsignedByteType ) {
 
-			output = new WebGLOutput( _outputBufferType, canvas.width, canvas.height, depth, stencil );
+			output = new WebGLOutput( _outputBufferType, canvas.width, canvas.height, antialias, depth, stencil );
 
 		}
 
@@ -731,7 +739,7 @@ class WebGLRenderer {
 
 			if ( _outputBufferType === UnsignedByteType ) {
 
-				error( 'THREE.WebGLRenderer: setEffects() requires outputBufferType set to HalfFloatType or FloatType.' );
+				error( 'WebGLRenderer: setEffects() requires outputBufferType set to HalfFloatType or FloatType.' );
 				return;
 
 			}
@@ -742,7 +750,7 @@ class WebGLRenderer {
 
 					if ( effects[ i ].isOutputPass === true ) {
 
-						warn( 'THREE.WebGLRenderer: OutputPass is not needed in setEffects(). Tone mapping and color space conversion are applied automatically.' );
+						warn( 'WebGLRenderer: OutputPass is not needed in setEffects(). Tone mapping and color space conversion are applied automatically.' );
 						break;
 
 					}
@@ -1180,7 +1188,7 @@ class WebGLRenderer {
 
 			if ( scene === null ) scene = _emptyScene; // renderBufferDirect second parameter used to be fog (could be null)
 
-			const frontFaceCW = ( object.isMesh && object.matrixWorld.determinant() < 0 );
+			const frontFaceCW = ( object.isMesh && object.matrixWorld.determinantAffine() < 0 );
 
 			const program = setProgram( camera, scene, geometry, material, object );
 
@@ -1714,7 +1722,9 @@ class WebGLRenderer {
 				// WITH_GENESYS
 				ProfilerService.begin( 'sortRenderList' );
 				// !WITH_GENESYS
-				currentRenderList.sort( _opaqueSort, _transparentSort );
+
+				currentRenderList.sort( _opaqueSort, _transparentSort, camera.reversedDepth );
+
 				// WITH_GENESYS
 				ProfilerService.end( 'sortRenderList' );
 				// !WITH_GENESYS
@@ -1736,6 +1746,8 @@ class WebGLRenderer {
 
 			this.info.render.frame ++;
 
+			if ( this.info.autoReset === true ) this.info.reset();
+
 			if ( _clippingEnabled === true ) clipping.beginShadows();
 
 			const shadowsArray = currentRenderState.state.shadowsArray;
@@ -1752,8 +1764,6 @@ class WebGLRenderer {
 
 			//
 
-			if ( this.info.autoReset === true ) this.info.reset();
-
 			// render scene (skip if first effect is a render pass - it will render the scene itself)
 
 			const skipSceneRender = useOutput && output.hasRenderPass();
@@ -2959,8 +2969,6 @@ class WebGLRenderer {
 
 		};
 
-		const _scratchFrameBuffer = _gl.createFramebuffer();
-
 		/**
 		 * Sets the active rendertarget.
 		 *
@@ -3024,7 +3032,7 @@ class WebGLRenderer {
 							( renderTarget.width !== depthTexture.image.width || renderTarget.height !== depthTexture.image.height )
 						) {
 
-							throw new Error( 'WebGLRenderTarget: Attached DepthTexture is initialized to the incorrect size.' );
+							throw new Error( 'THREE.WebGLRenderer: Attached DepthTexture is initialized to the incorrect size.' );
 
 						}
 
@@ -3093,7 +3101,7 @@ class WebGLRenderer {
 			// being bound that are different sizes.
 			if ( activeMipmapLevel !== 0 ) {
 
-				framebuffer = _scratchFrameBuffer;
+				framebuffer = _scratchFramebuffer;
 
 			}
 
@@ -3336,8 +3344,6 @@ class WebGLRenderer {
 
 		};
 
-		const _srcFramebuffer = _gl.createFramebuffer();
-		const _dstFramebuffer = _gl.createFramebuffer();
 
 		/**
 		 * Copies data of the given source texture into a destination texture.

package/src/renderers/common/Backend.js

@@ -16,7 +16,6 @@ import { REVISION, TimestampQuery } from '../../constants.js';
  * implement the interface.
  *
  * @abstract
- * @private
  */
 class Backend {
 
@@ -124,6 +123,15 @@ class Backend {
 	 */
 	finishRender( /*renderContext*/ ) {}
 
+	/**
+	 * Sets the XR rendering destination.
+	 *
+	 * Backends that render directly into XR framebuffers can override this hook.
+	 *
+	 * @param {?Object} xrTarget - The XR rendering destination.
+	 */
+	setXRTarget( /*xrTarget*/ ) {}
+
 	/**
 	 * This method is executed at the beginning of a compute call and
 	 * can be used by the backend to prepare the state for upcoming
@@ -276,10 +284,18 @@ class Backend {
 	 * Updates a GPU sampler for the given texture.
 	 *
 	 * @abstract
-	 * @param {Texture} texture - The texture to update the sampler for.
+	 * @param {Sampler} binding - The sampler binding to update.
 	 * @return {string} The current sampler key.
 	 */
-	updateSampler( /*texture*/ ) { }
+	updateSampler( /*binding*/ ) { }
+
+	/**
+	 * Frees the GPU sampler for the given sampler binding.
+	 *
+	 * @abstract
+	 * @param {Sampler} binding - The sampler binding to free.
+	 */
+	destroySampler( /*binding*/ ) { }
 
 	/**
 	 * Creates a default texture for the given texture that can be used
@@ -389,6 +405,22 @@ class Backend {
 	 */
 	createStorageAttribute( /*attribute*/ ) { }
 
+	/**
+	 * Creates a uniform buffer.
+	 *
+	 * @abstract
+	 * @param {Buffer} uniformBuffer - The uniform buffer.
+	 */
+	createUniformBuffer( /*uniformBuffer*/ ) { }
+
+	/**
+	 * Destroys a uniform buffer.
+	 *
+	 * @abstract
+	 * @param {Buffer} uniformBuffer - The uniform buffer.
+	 */
+	destroyUniformBuffer( /*uniformBuffer*/ ) { }
+
 	/**
 	 * Updates the GPU buffer of a shader attribute.
 	 *
@@ -516,17 +548,29 @@ class Backend {
 
 	}
 
+	/**
+	 * Whether the backend supports query timestamps or not.
+	 *
+	 * @type {boolean}
+	 * @readonly
+	 */
+	get hasTimestamp() {
+
+		return false;
+
+	}
+
 	/**
 	 * Returns `true` if a timestamp for the given uid is available.
 	 *
 	 * @param {string} uid - The unique identifier.
 	 * @return {boolean} Whether the timestamp is available or not.
 	 */
-	hasTimestamp( uid ) {
+	hasTimestampQuery( uid ) {
 
 		const queryPool = this._getQueryPool( uid );
 
-		return queryPool.hasTimestamp( uid );
+		return queryPool.hasTimestampQuery( uid );
 
 	}