rayzee 5.10.2 → 5.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rayzee",
-  "version": "5.10.2",
+  "version": "5.11.0",
   "type": "module",
   "description": "Real-time WebGPU path tracing engine built on Three.js",
   "main": "dist/rayzee.umd.js",

package/src/PathTracerApp.js

@@ -65,7 +65,10 @@ export class PathTracerApp extends EventDispatcher {
 	 * @param {Object} [options] - Engine options
 	 * @param {boolean} [options.autoResize=true] - Automatically listen for window resize events
 	 * @param {boolean} [options.showStats=true] - Show the performance stats panel
-	 * @param {HTMLElement} [options.statsContainer] - DOM element to append the stats panel to (defaults to document.body)
+	 * @param {HTMLElement} [options.container] - Single DOM parent the engine mounts all auxiliary
+	 *   elements into (HUD overlay, denoiser canvas, stats). Defaults to `canvas.parentNode`.
+	 * @param {HTMLElement} [options.statsContainer] - Override mount target for the stats panel only.
+	 *   Defaults to `options.container`.
 	 */
 	constructor( canvas, options = {} ) {
 
@@ -86,6 +89,7 @@ export class PathTracerApp extends EventDispatcher {
 		this.canvas = canvas;
 		this._autoResize = options.autoResize !== false;
 		this._showStats = options.showStats !== false;
+		this._container = options.container || null;
 		this._statsContainer = options.statsContainer || null;
 
 		// ── Settings (single source of truth for all render parameters) ──
@@ -1550,7 +1554,7 @@ export class PathTracerApp extends EventDispatcher {
 
 	_initStats() {
 
-		const container = this._statsContainer || this.canvas.parentElement || document.body;
+		const container = this._statsContainer || this._container || this.canvas.parentElement || document.body;
 		this._stats = createStats( this.renderer, container );
 
 	}
@@ -1592,6 +1596,9 @@ export class PathTracerApp extends EventDispatcher {
 			renderHeight: this.denoisingManager?._lastRenderHeight || this.canvas.clientHeight || 1,
 		} );
 
+		this._container = this._container || this.canvas.parentNode || null;
+		this.overlayManager.mount( this._container );
+
 	}
 
 

package/src/Processor/TextureCreator.js

@@ -351,7 +351,8 @@ class TextureCache {
 				const width = texture.image.width || 0;
 				const height = texture.image.height || 0;
 				const src = texture.image.src || texture.uuid || '';
-				hash += `${width}x${height}_${src.slice( - 8 )}_`;
+				const flipFlag = texture.flipY === false ? 'n' : 'f';
+				hash += `${width}x${height}_${src.slice( - 8 )}_${flipFlag}_`;
 
 			}
 
@@ -681,12 +682,16 @@ export class TextureCreator {
 
 			if ( ! texture?.image ) continue;
 
+			const flipY = texture.flipY !== false;
+
 			try {
 
 				// Option 1: Direct ImageBitmap transfer (when supported)
 				if ( typeof createImageBitmap !== 'undefined' && texture.image instanceof HTMLImageElement ) {
 
-					const bitmap = await createImageBitmap( texture.image );
+					const bitmap = await createImageBitmap( texture.image, {
+						imageOrientation: flipY ? 'flipY' : 'none',
+					} );
 					texturesData.push( {
 						bitmap: bitmap,
 						width: texture.image.width,
@@ -696,16 +701,22 @@ export class TextureCreator {
 
 				} else { // Option 2: Efficient canvas-based transfer
 
-					const pair = this.canvasPool.getCanvasWithContext( texture.image.width, texture.image.height );
+					const w = texture.image.width;
+					const h = texture.image.height;
+					const bitmap = await createImageBitmap( texture.image, {
+						imageOrientation: flipY ? 'flipY' : 'none',
+					} );
+					const pair = this.canvasPool.getCanvasWithContext( w, h );
 
-					pair.context.drawImage( texture.image, 0, 0 );
-					const imageData = pair.context.getImageData( 0, 0, texture.image.width, texture.image.height );
+					pair.context.drawImage( bitmap, 0, 0 );
+					bitmap.close();
+					const imageData = pair.context.getImageData( 0, 0, w, h );
 
 					// Transfer the underlying ArrayBuffer directly
 					texturesData.push( {
 						data: imageData.data.buffer, // Direct buffer transfer
-						width: texture.image.width,
-						height: texture.image.height,
+						width: w,
+						height: h,
 						isImageData: true
 					} );
 
@@ -759,11 +770,13 @@ export class TextureCreator {
 			for ( let i = batchStart; i < batchEnd; i ++ ) {
 
 				const texture = validTextures[ i ];
+				const flipY = texture.flipY !== false;
 
 				const bitmapPromise = createImageBitmap( texture.image, {
 					resizeWidth: maxWidth,
 					resizeHeight: maxHeight,
-					resizeQuality: 'high'
+					resizeQuality: 'high',
+					imageOrientation: flipY ? 'flipY' : 'none',
 				} );
 
 				batchPromises.push(
@@ -815,9 +828,16 @@ export class TextureCreator {
 		for ( let i = 0; i < validTextures.length; i ++ ) {
 
 			const texture = validTextures[ i ];
+			const bitmap = await createImageBitmap( texture.image, {
+				resizeWidth: maxWidth,
+				resizeHeight: maxHeight,
+				resizeQuality: 'high',
+				imageOrientation: texture.flipY !== false ? 'flipY' : 'none',
+			} );
 
 			pair.context.clearRect( 0, 0, maxWidth, maxHeight );
-			pair.context.drawImage( texture.image, 0, 0, maxWidth, maxHeight );
+			pair.context.drawImage( bitmap, 0, 0 );
+			bitmap.close();
 
 			const imageData = pair.context.getImageData( 0, 0, maxWidth, maxHeight );
 			const offset = maxWidth * maxHeight * 4 * i;
@@ -853,9 +873,16 @@ export class TextureCreator {
 		for ( let i = 0; i < validTextures.length; i ++ ) {
 
 			const texture = validTextures[ i ];
+			const bitmap = await createImageBitmap( texture.image, {
+				resizeWidth: maxWidth,
+				resizeHeight: maxHeight,
+				resizeQuality: 'high',
+				imageOrientation: texture.flipY !== false ? 'flipY' : 'none',
+			} );
 
 			pair.context.clearRect( 0, 0, maxWidth, maxHeight );
-			pair.context.drawImage( texture.image, 0, 0, maxWidth, maxHeight );
+			pair.context.drawImage( bitmap, 0, 0 );
+			bitmap.close();
 
 			const imageData = pair.context.getImageData( 0, 0, maxWidth, maxHeight );
 			const offset = maxWidth * maxHeight * 4 * i;
@@ -1301,7 +1328,7 @@ export class TextureCreator {
 				const mip = tex.mipmaps[ 0 ];
 				const idx = normalized.length;
 				normalized.push( null ); // placeholder — filled after Promise.all
-				bitmapJobs.push( { index: idx, promise: _rawPixelsToBitmap( mip.data, mip.width, mip.height ) } );
+				bitmapJobs.push( { index: idx, flipY: tex.flipY, promise: _rawPixelsToBitmap( mip.data, mip.width, mip.height ) } );
 				continue;
 
 			}
@@ -1323,7 +1350,7 @@ export class TextureCreator {
 
 				const idx = normalized.length;
 				normalized.push( null );
-				bitmapJobs.push( { index: idx, promise: _rawPixelsToBitmap( tex.image.data, tex.image.width, tex.image.height ) } );
+				bitmapJobs.push( { index: idx, flipY: tex.flipY, promise: _rawPixelsToBitmap( tex.image.data, tex.image.width, tex.image.height ) } );
 				continue;
 
 			}
@@ -1339,14 +1366,14 @@ export class TextureCreator {
 
 			for ( let i = 0; i < bitmapJobs.length; i ++ ) {
 
-				const { index } = bitmapJobs[ i ];
+				const { index, flipY } = bitmapJobs[ i ];
 				const result = results[ i ];
 
 				if ( result.status === 'fulfilled' ) {
 
 					const bitmap = result.value;
 					bitmapsToClose.push( bitmap );
-					normalized[ index ] = { image: bitmap };
+					normalized[ index ] = { image: bitmap, flipY };
 
 				} else {
 
@@ -1367,7 +1394,7 @@ export class TextureCreator {
 				const placeholder = new Uint8ClampedArray( [ 255, 255, 255, 255 ] );
 				const bitmap = await createImageBitmap( new ImageData( placeholder, 1, 1 ) );
 				bitmapsToClose.push( bitmap );
-				normalized[ i ] = { image: bitmap };
+				normalized[ i ] = { image: bitmap, flipY: false };
 
 			}
 

package/src/managers/OverlayManager.js

@@ -57,8 +57,8 @@ export class OverlayManager {
 	}
 
 	/**
-	 * Returns the HUD canvas element. The app should mount this on top of the
-	 * WebGPU canvas (absolute-positioned, pointer-events: none).
+	 * Returns the HUD canvas element. Normally mounted automatically by
+	 * {@link PathTracerApp}; exposed for advanced clients that mount it manually.
 	 * @returns {HTMLCanvasElement}
 	 */
 	getHUDCanvas() {
@@ -67,6 +67,18 @@ export class OverlayManager {
 
 	}
 
+	/**
+	 * Mounts the HUD canvas into the given container. Idempotent — safe to call
+	 * multiple times; re-mounts only when the parent differs.
+	 * @param {HTMLElement} container
+	 */
+	mount( container ) {
+
+		if ( ! container || this._hudCanvas.parentElement === container ) return;
+		container.appendChild( this._hudCanvas );
+
+	}
+
 	// ═══════════════════════════════════════════════════════════════
 	// Default helpers setup
 	// ═══════════════════════════════════════════════════════════════