@gnsx/three 0.184.10 → 0.184.12

package/examples/jsm/helpers/LightProbeGridCubeMapHelper.js

@@ -7,9 +7,14 @@ import {
 } from 'three';
 import { NodeMaterial } from 'three/webgpu';
 import {
+	abs,
 	cubeTexture,
 	Fn,
-	normalWorld,
+	max,
+	normalLocal,
+	positionLocal,
+	select,
+	vec3,
 	vec4
 } from 'three/tsl';
 
@@ -17,7 +22,41 @@ function createNodeMaterial( texture ) {
 
 	const fragmentNode = Fn( () => {
 
-		return vec4( cubeTexture( texture, normalWorld ).rgb, 1.0 );
+		// Get local position and normal
+		const localPos = positionLocal;
+		const localNormal = normalLocal;
+
+		// Get absolute normal components to determine dominant axis
+		const absNormal = abs( localNormal );
+		const maxComp = max( max( absNormal.x, absNormal.y ), absNormal.z );
+
+		// Determine which face we're on and compute sample direction
+		const isX = maxComp.equal( absNormal.x );
+		const isY = maxComp.equal( absNormal.y ).and( isX.not() );
+
+		// Match LightProbeGrid / WebGL cubemap face conventions (see LightProbeGrid.js SH projection).
+		const xPositive = localNormal.x.greaterThan( 0.0 );
+		const xDir = select( xPositive,
+			vec3( 1.0, localPos.y, localPos.z.negate() ).normalize(),
+			vec3( - 1.0, localPos.y, localPos.z ).normalize()
+		);
+
+		const yPositive = localNormal.y.greaterThan( 0.0 );
+		const yDir = select( yPositive,
+			vec3( localPos.x, 1.0, localPos.z.negate() ).normalize(),
+			vec3( localPos.x, - 1.0, localPos.z ).normalize()
+		);
+
+		const zPositive = localNormal.z.greaterThan( 0.0 );
+		const zDir = select( zPositive,
+			vec3( localPos.x, localPos.y, 1.0 ).normalize(),
+			vec3( localPos.x, localPos.y, - 1.0 ).normalize()
+		);
+
+		// Select the appropriate direction based on which axis is dominant
+		const sampleDir = select( isX, xDir, select( isY, yDir, zDir ) );
+
+		return vec4( cubeTexture( texture, sampleDir ).rgb, 1.0 );
 
 	} )();
 
@@ -40,11 +79,13 @@ function createShaderMaterial( texture ) {
 
 		vertexShader: /* glsl */`
 
-			varying vec3 vWorldNormal;
+			varying vec3 vLocalPosition;
+			varying vec3 vNormal;
 
 			void main() {
 
-				vWorldNormal = normalize( mat3( modelMatrix ) * normal );
+				vLocalPosition = position;
+				vNormal = normal;
 				gl_Position = projectionMatrix * modelViewMatrix * vec4( position, 1.0 );
 
 			}
@@ -57,12 +98,56 @@ function createShaderMaterial( texture ) {
 
 			uniform samplerCube cubeTexture;
 
-			varying vec3 vWorldNormal;
+			varying vec3 vLocalPosition;
+			varying vec3 vNormal;
 
 			void main() {
+				// Get the dominant axis from the normal to determine which face we're on
+				vec3 absNormal = abs( vNormal );
+				float maxComp = max( max( absNormal.x, absNormal.y ), absNormal.z );
+
+				vec3 sampleDir;
+
+				// Match LightProbeGrid / WebGL cubemap face conventions (see LightProbeGrid.js SH projection).
+				if ( maxComp == absNormal.x ) {
+
+					if ( vNormal.x > 0.0 ) {
+
+						sampleDir = normalize( vec3( 1.0, vLocalPosition.y, -vLocalPosition.z ) );
+
+					} else {
+
+						sampleDir = normalize( vec3( -1.0, vLocalPosition.y, vLocalPosition.z ) );
+
+					}
+
+				} else if ( maxComp == absNormal.y ) {
+
+					if ( vNormal.y > 0.0 ) {
+
+						sampleDir = normalize( vec3( vLocalPosition.x, 1.0, -vLocalPosition.z ) );
+
+					} else {
+
+						sampleDir = normalize( vec3( vLocalPosition.x, -1.0, vLocalPosition.z ) );
+
+					}
+
+				} else {
+
+					if ( vNormal.z > 0.0 ) {
+
+						sampleDir = normalize( vec3( vLocalPosition.x, vLocalPosition.y, 1.0 ) );
+
+					} else {
+
+						sampleDir = normalize( vec3( vLocalPosition.x, vLocalPosition.y, -1.0 ) );
+
+					}
+
+				}
 
-				vec3 direction = normalize( vWorldNormal );
-				vec3 color = textureCube( cubeTexture, direction ).rgb;
+				vec3 color = textureCube( cubeTexture, sampleDir ).rgb;
 
 				gl_FragColor = vec4( color, 1.0 );
 

package/examples/jsm/lighting/LightProbeGrid.js

@@ -238,7 +238,11 @@ class LightProbeGrid extends Object3D {
 	 */
 	getProbePosition( ix, iy, iz, target ) {
 
-		const pos = this.position;
+		// const pos = this.position;
+		// WITH_GENESYS
+		const pos = _position;
+		this.getWorldPosition( pos );
+		// !WITH_GENESYS
 		const res = this.resolution;
 		const w = this.width, h = this.height, d = this.depth;
 
@@ -257,8 +261,15 @@ class LightProbeGrid extends Object3D {
 	 */
 	updateBoundingBox() {
 
+		// WITH_GENESYS
+		this.getWorldPosition( _position );
+		_size.set( this.width, this.height, this.depth );
+		this.boundingBox.setFromCenterAndSize( _position, _size );
+		// !WITH_GENESYS
+		/*
 		_size.set( this.width, this.height, this.depth );
 		this.boundingBox.setFromCenterAndSize( this.position, _size );
+		*/
 
 	}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gnsx/three",
-  "version": "0.184.10",
+  "version": "0.184.12",
   "description": "JavaScript 3D library",
   "type": "module",
   "main": "./build/three.cjs",

package/src/Three.js

@@ -8,3 +8,6 @@ export { UniformsUtils } from './renderers/shaders/UniformsUtils.js';
 export { ShaderChunk } from './renderers/shaders/ShaderChunk.js';
 export { PMREMGenerator } from './extras/PMREMGenerator.js';
 export { WebGLUtils } from './renderers/webgl/WebGLUtils.js';
+// WITH_GENESYS
+export { ProfilerService, profile, profileClass } from './profiler/ProfilerService.js';
+// !WITH_GENESYS

package/src/profiler/ProfilerService.js

@@ -0,0 +1,431 @@
+// WITH_GENESYS
+/**
+ * ProfilerService — per-label CPU timing with ring-buffer aggregation and DevTools integration.
+ *
+ * Activate via environment variable:
+ *   PROFILING=1       stats + trace (full profile)
+ *   PROFILING=stats   stats only, no trace accumulation (lower overhead)
+ *
+ * Quick start (browser console):
+ *   __gnsx_profiler.enable()
+ *   // play for a few seconds
+ *   __gnsx_profiler.report()         // sorted console.table (aggregated stats)
+ *   __gnsx_profiler.downloadTrace()  // download gnsx-trace.json for Speedscope / Perfetto
+ *   __gnsx_profiler.reset()          // clear samples and trace
+ *   __gnsx_profiler.disable()
+ */
+
+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 NOOP = () => {};
+
+function _readProfilingEnv() {
+
+	const raw =
+		( typeof process !== 'undefined' ? process.env?.[ 'PROFILING' ] : undefined ) ??
+		( typeof globalThis !== 'undefined' ? globalThis[ '__gnsx_env__' ]?.[ 'PROFILING' ] : undefined ) ??
+		( typeof globalThis !== 'undefined' ? globalThis[ '__GNSX_PROFILING__' ] : undefined );
+
+	if ( ! raw || raw === '0' || raw === 'false' ) return false;
+	if ( raw === 'stats' ) return 'stats';
+	return 'full';
+
+}
+
+class ProfilerServiceClass {
+
+	constructor() {
+
+		const envProfile = _readProfilingEnv();
+		this._profile = envProfile !== false ? envProfile : 'full';
+		this._enabled = envProfile !== false;
+
+		/** @type {Map<string, Float64Array>} */
+		this.buffers = new Map();
+		/** @type {Map<string, number>} */
+		this.cursors = new Map();
+		/** @type {Map<string, number>} */
+		this.counts = new Map();
+		/** @type {Map<string, number>} */
+		this.marks = new Map();
+		/** @type {Array<{ name: string, ph: 'X', ts: number, dur: number, pid: 1, tid: 1, cat: 'gnsx' }>} */
+		this.traceEvents = [];
+		this.traceStartTime = 0;
+
+		if ( this._enabled ) {
+
+			this.traceStartTime = performance.now();
+			this.begin = this._beginImpl.bind( this );
+			this.end = this._endImpl.bind( this );
+			this._exposeGlobal();
+			console.log( `[ProfilerService] auto-started from env (profile: ${this._profile})` );
+
+		} else {
+
+			this.begin = NOOP;
+			this.end = NOOP;
+
+		}
+
+	}
+
+	/**
+	 * Set the active profile. Must be called before enable() to take effect on the current session.
+	 *
+	 * @param {'full'|'stats'} profile
+	 */
+	setProfile( profile ) {
+
+		this._profile = profile;
+
+	}
+
+	/**
+	 * @return {'full'|'stats'}
+	 */
+	getProfile() {
+
+		return this._profile;
+
+	}
+
+	enable() {
+
+		this._clearState();
+		this._enabled = true;
+		this.begin = this._beginImpl.bind( this );
+		this.end = this._endImpl.bind( this );
+		this._exposeGlobal();
+		console.log( `[ProfilerService] enabled (profile: ${this._profile}) — call __gnsx_profiler.report() or downloadTrace() from the console` );
+
+	}
+
+	disable() {
+
+		this._clearState();
+		this._enabled = false;
+		this.begin = NOOP;
+		this.end = NOOP;
+		console.log( '[ProfilerService] disabled' );
+
+	}
+
+	isEnabled() {
+
+		return this._enabled;
+
+	}
+
+	_exposeGlobal() {
+
+		if ( typeof window !== 'undefined' ) {
+
+			window.__gnsx_profiler = this;
+
+		}
+
+	}
+
+	/**
+	 * @param {string} label
+	 */
+	_beginImpl( label ) {
+
+		performance.mark( `gnsx:${label}:start` );
+		this.marks.set( label, performance.now() );
+
+	}
+
+	/**
+	 * @param {string} label
+	 */
+	_endImpl( label ) {
+
+		const startTime = this.marks.get( label );
+		if ( startTime === undefined ) return;
+		this.marks.delete( label );
+
+		const now = performance.now();
+		const duration = now - startTime;
+
+		performance.mark( `gnsx:${label}:end` );
+		performance.measure( `gnsx:${label}`, `gnsx:${label}:start`, `gnsx:${label}:end` );
+
+		let buffer = this.buffers.get( label );
+		if ( ! buffer ) {
+
+			buffer = new Float64Array( RING_SIZE );
+			this.buffers.set( label, buffer );
+			this.cursors.set( label, 0 );
+			this.counts.set( label, 0 );
+
+		}
+
+		const cursor = this.cursors.get( label );
+		buffer[ cursor ] = duration;
+		this.cursors.set( label, ( cursor + 1 ) % RING_SIZE );
+		this.counts.set( label, Math.min( ( this.counts.get( label ) + 1 ), RING_SIZE ) );
+
+		if ( this._profile === 'full' && this.traceEvents.length < MAX_TRACE_EVENTS ) {
+
+			this.traceEvents.push( {
+				name: label,
+				ph: 'X',
+				ts: Math.round( ( startTime - this.traceStartTime ) * 1000 ),
+				dur: Math.max( 1, Math.round( duration * 1000 ) ),
+				pid: 1,
+				tid: 1,
+				cat: 'gnsx',
+			} );
+
+		}
+
+	}
+
+	/**
+	 * @param {string} label
+	 * @return {number[]}
+	 */
+	getValidSamples( label ) {
+
+		const buffer = this.buffers.get( label );
+		const count = this.counts.get( label ) ?? 0;
+		if ( ! buffer || count === 0 ) return [];
+		return count < RING_SIZE
+			? Array.from( buffer.subarray( 0, count ) )
+			: Array.from( buffer );
+
+	}
+
+	/**
+	 * @param {string} label
+	 * @return {import('./ProfilerService.js').ProfilerStats|null}
+	 */
+	getStats( label ) {
+
+		const samples = this.getValidSamples( label );
+		if ( samples.length === 0 ) return null;
+
+		const sorted = [ ...samples ].sort( ( a, b ) => a - b );
+		const avg = sorted.reduce( ( a, b ) => a + b, 0 ) / sorted.length;
+
+		return {
+			label,
+			samples: samples.length,
+			avg,
+			min: sorted[ 0 ],
+			max: sorted[ sorted.length - 1 ],
+			p95: sorted[ Math.floor( sorted.length * 0.95 ) ],
+			frameBudget: ( avg / FRAME_BUDGET_MS ) * 100,
+		};
+
+	}
+
+	/**
+	 * @return {import('./ProfilerService.js').ProfilerStats[]}
+	 */
+	getAllStats() {
+
+		return [ ...this.buffers.keys() ]
+			.map( label => this.getStats( label ) )
+			.filter( s => s !== null );
+
+	}
+
+	report() {
+
+		const stats = this.getAllStats();
+		if ( stats.length === 0 ) {
+
+			console.log( '[ProfilerService] No data. Enable profiling first and wait a few frames.' );
+			return;
+
+		}
+
+		stats.sort( ( a, b ) => b.avg - a.avg );
+		console.table(
+			stats.map( s => ( {
+				label: s.label,
+				'avg ms': s.avg.toFixed( 3 ),
+				'min ms': s.min.toFixed( 3 ),
+				'max ms': s.max.toFixed( 3 ),
+				'p95 ms': s.p95.toFixed( 3 ),
+				'budget %': s.frameBudget.toFixed( 1 ) + '%',
+				samples: s.samples,
+			} ) )
+		);
+
+	}
+
+	/**
+	 * @return {import('./ProfilerService.js').ChromeTrace}
+	 */
+	exportChromeTrace() {
+
+		return { traceEvents: [ ...this.traceEvents ] };
+
+	}
+
+	/**
+	 * @param {string} [filename='gnsx-trace.json']
+	 */
+	downloadTrace( filename = 'gnsx-trace.json' ) {
+
+		if ( typeof document === 'undefined' ) {
+
+			console.log( '[ProfilerService] downloadTrace() only works in the browser. Use exportChromeTrace() in Node.js.' );
+			return;
+
+		}
+
+		if ( this._profile !== 'full' ) {
+
+			console.log( `[ProfilerService] No trace — current profile is '${this._profile}'. Use setProfile('full') before enabling.` );
+			return;
+
+		}
+
+		if ( this.traceEvents.length === 0 ) {
+
+			console.log( '[ProfilerService] No trace events. Enable the profiler and play for a few seconds first.' );
+			return;
+
+		}
+
+		const json = JSON.stringify( this.exportChromeTrace() );
+		const blob = new Blob( [ json ], { type: 'application/json' } );
+		const url = URL.createObjectURL( blob );
+		const a = document.createElement( 'a' );
+		a.href = url;
+		a.download = filename;
+		a.click();
+		URL.revokeObjectURL( url );
+		console.log( `[ProfilerService] Trace downloaded: ${filename} (${this.traceEvents.length} events)` );
+
+	}
+
+	/**
+	 * @return {import('./ProfilerService.js').ProfilerStats[]}
+	 */
+	exportJSON() {
+
+		return this.getAllStats();
+
+	}
+
+	_clearState() {
+
+		this.buffers.clear();
+		this.cursors.clear();
+		this.counts.clear();
+		this.marks.clear();
+		this.traceEvents = [];
+		this.traceStartTime = performance.now();
+
+	}
+
+	reset() {
+
+		this._clearState();
+		console.log( '[ProfilerService] data reset' );
+
+	}
+
+}
+
+/**
+ * @typedef {Object} ProfilerStats
+ * @property {string} label
+ * @property {number} samples
+ * @property {number} avg
+ * @property {number} min
+ * @property {number} max
+ * @property {number} p95
+ * @property {number} frameBudget Percentage of a 60 fps frame budget (16.67 ms)
+ */
+
+/**
+ * @typedef {Object} ChromeTrace
+ * @property {Array<{ name: string, ph: 'X', ts: number, dur: number, pid: 1, tid: 1, cat: 'gnsx' }>} traceEvents
+ * @property {{ 'clock-offset-since-epoch-ns'?: number }|undefined} [metadata]
+ */
+
+/**
+ * @typedef {'full'|'stats'} ProfilingProfile
+ */
+
+const ProfilerService = new ProfilerServiceClass();
+
+function applyProfileToMethod( label, descriptor ) {
+
+	if ( _readProfilingEnv() === false ) return descriptor;
+
+	const original = descriptor.value;
+
+	function profiled( ...args ) {
+
+		ProfilerService.begin( label );
+		const result = original.apply( this, args );
+		if ( result instanceof Promise ) {
+
+			return result.finally( () => ProfilerService.end( label ) );
+
+		}
+
+		ProfilerService.end( label );
+		return result;
+
+	}
+
+	descriptor.value = profiled;
+	return descriptor;
+
+}
+
+/**
+ * Method decorator that profiles the decorated method.
+ * The label is automatically set to `ClassName.methodName`.
+ *
+ * @param {Object} target
+ * @param {string|symbol} propertyKey
+ * @param {PropertyDescriptor} descriptor
+ * @return {PropertyDescriptor}
+ */
+function profile( target, propertyKey, descriptor ) {
+
+	const className = target.constructor?.name ?? 'Unknown';
+	return applyProfileToMethod( `${className}.${String( propertyKey )}`, descriptor );
+
+}
+
+/**
+ * Class decorator that profiles every method of the decorated class.
+ *
+ * @template T
+ * @param {T} constructor
+ * @return {T}
+ */
+function profileClass( constructor ) {
+
+	const proto = constructor.prototype;
+	for ( const key of Object.getOwnPropertyNames( proto ) ) {
+
+		if ( key === 'constructor' ) continue;
+		const descriptor = Object.getOwnPropertyDescriptor( proto, key );
+		if ( ! descriptor || typeof descriptor.value !== 'function' ) continue;
+		Object.defineProperty(
+			proto,
+			key,
+			applyProfileToMethod( `${constructor.name}.${key}`, { ...descriptor } )
+		);
+
+	}
+
+	return constructor;
+
+}
+
+export { ProfilerService, profile, profileClass };
+// !WITH_GENESYS