rayzee 7.30.0 → 7.30.2

package/package.json

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

package/src/EngineDefaults.js

@@ -666,11 +666,11 @@ export const TEXTURE_CONSTANTS = {
 	MAX_TEXTURE_SIZE: 8192,
 	// Default cap applied when no maxTextureSize is supplied (engine standalone use).
 	DEFAULT_MAX_TEXTURE_SIZE: 4096,
-	// Max layers (textures) per bucket array. Also the packing stride for (bucket, layer).
-	MAX_TEXTURES_LIMIT: 128,
-	// Size buckets per colorSpace pool. Material maps are grouped into this many
-	// longest-edge size classes so a small map no longer pays a large neighbour's
-	// footprint. 4 → ~8 bound material arrays (4 sRGB + 4 linear).
+	// Per-map-type ceiling before bucketing; the real cap is per (pool, bucket) in _bucketTextures.
+	MAX_TEXTURES_LIMIT: 4 * 256,
+	// Array shapes per colorSpace pool. Material maps are grouped into this many
+	// (width, height) classes so a small or oddly-shaped map no longer pays a large
+	// neighbour's footprint. 4 → ~8 bound material arrays (4 sRGB + 4 linear).
 	MATERIAL_BUCKET_COUNT: 4,
 	// Packing stride: a map's stored index encodes bucketId * BUCKET_LAYER_STRIDE + layer.
 	// Also the per-bucket layer cap. Kept at the WebGPU portable maxTextureArrayLayers floor (256)
@@ -678,30 +678,208 @@ export const TEXTURE_CONSTANTS = {
 	BUCKET_LAYER_STRIDE: 256,
 };
 
-// Longest-edge size ladder for a given cap, ascending.
-// cap=4096, count=4 → [512, 1024, 2048, 4096].
-export function getTextureBucketSizes( maxTextureSize, count = TEXTURE_CONSTANTS.MATERIAL_BUCKET_COUNT ) {
+// An RGBA8 row upload must be a multiple of 256 bytes, so bucket widths land on 64 texels.
+const BUCKET_WIDTH_ALIGN = 64;
 
-	const sizes = [];
+export function alignBucketWidth( width, maxTextureSize ) {
+
+	const aligned = Math.ceil( Math.max( 1, width ) / BUCKET_WIDTH_ALIGN ) * BUCKET_WIDTH_ALIGN;
+	return Math.min( maxTextureSize, Math.max( TEXTURE_CONSTANTS.MIN_TEXTURE_WIDTH, aligned ) );
+
+}
+
+function bucketOf( units ) {
+
+	let width = 0, height = 0, count = 0;
+	for ( const unit of units ) {
+
+		width = Math.max( width, unit.width );
+		height = Math.max( height, unit.height );
+		count += unit.count;
+
+	}
+
+	return { units, width, height, count };
+
+}
+
+// Footprint times layer count.
+function bucketCost( bucket, maxTextureSize ) {
+
+	return alignBucketWidth( bucket.width, maxTextureSize ) * bucket.height * bucket.count * 4;
+
+}
+
+function totalCost( buckets, maxTextureSize ) {
+
+	return buckets.reduce( ( sum, b ) => sum + bucketCost( b, maxTextureSize ), 0 );
+
+}
+
+// Repeatedly fuse the pair of buckets whose union wastes least, until `count` remain.
+function mergeDown( buckets, count, maxTextureSize ) {
+
+	let current = buckets.slice();
+
+	while ( current.length > count ) {
+
+		let best = null;
+
+		for ( let i = 0; i < current.length; i ++ ) {
+
+			for ( let j = i + 1; j < current.length; j ++ ) {
+
+				const fused = bucketOf( current[ i ].units.concat( current[ j ].units ) );
+				const delta = bucketCost( fused, maxTextureSize )
+					- bucketCost( current[ i ], maxTextureSize ) - bucketCost( current[ j ], maxTextureSize );
+				if ( ! best || delta < best.delta ) best = { i, j, delta, fused };
+
+			}
+
+		}
+
+		current = current.filter( ( _, k ) => k !== best.i && k !== best.j ).concat( [ best.fused ] );
+
+	}
+
+	return current;
+
+}
+
+// The pre-shape-aware layout, kept as a rival opening: square scenes still do well on it.
+function ladderBuckets( units, count, maxTextureSize ) {
+
+	const ladder = [];
 	for ( let i = count - 1; i >= 0; i -- ) {
 
-		sizes.push( Math.max( TEXTURE_CONSTANTS.MIN_TEXTURE_WIDTH, Math.round( maxTextureSize / Math.pow( 2, i ) ) ) );
+		ladder.push( Math.max( TEXTURE_CONSTANTS.MIN_TEXTURE_WIDTH, Math.round( maxTextureSize / Math.pow( 2, i ) ) ) );
+
+	}
+
+	const bins = ladder.map( () => [] );
+
+	for ( const unit of units ) {
+
+		const longest = Math.pow( 2, Math.ceil( Math.log2( Math.max( unit.width, unit.height ) ) ) );
+		let slot = ladder.findIndex( size => longest <= size );
+		if ( slot < 0 ) slot = ladder.length - 1;
+		bins[ slot ].push( unit );
 
 	}
 
-	return sizes;
+	return bins.filter( bin => bin.length ).map( bucketOf );
 
 }
 
-// Bucket index for a texture, by its power-of-2 longest edge vs the cap's ladder.
-// Larger-than-cap maps land in the top bucket (downscaled to cap, as before).
-export function getTextureBucketId( width, height, maxTextureSize, count = TEXTURE_CONSTANTS.MATERIAL_BUCKET_COUNT ) {
+// Both openings above are greedy and stop short on mixed aspects; moving one shape at a time
+// to whichever bucket makes the pool cheapest recovers the difference.
+function refine( buckets, maxTextureSize ) {
+
+	let current = buckets;
+
+	for ( let pass = 0; pass < 8; pass ++ ) {
+
+		let improved = false;
+
+		for ( const unit of current.flatMap( b => b.units ) ) {
+
+			const from = current.findIndex( b => b.units.includes( unit ) );
+			if ( from < 0 ) continue;
+
+			for ( let to = 0; to < current.length; to ++ ) {
+
+				if ( to === from ) continue;
+
+				const moved = [];
+				for ( let i = 0; i < current.length; i ++ ) {
+
+					if ( i === from ) {
+
+						const rest = current[ i ].units.filter( u => u !== unit );
+						if ( rest.length ) moved.push( bucketOf( rest ) );
+
+					} else if ( i === to ) moved.push( bucketOf( current[ i ].units.concat( [ unit ] ) ) );
+					else moved.push( current[ i ] );
+
+				}
+
+				if ( totalCost( moved, maxTextureSize ) < totalCost( current, maxTextureSize ) ) {
+
+					current = moved;
+					improved = true;
+					break;
+
+				}
+
+			}
+
+		}
+
+		if ( ! improved ) break;
+
+	}
+
+	return current;
+
+}
+
+/**
+ * Choose up to `count` array shapes for one colorSpace pool. Grouping by longest edge alone
+ * forces a 2000x453 banner into a 2048x2048 array; grouping on both axes does not.
+ *
+ * @param {Array<{width: number, height: number}>} sizes - every texture in the pool
+ * @param {number} maxTextureSize
+ * @param {number} [count]
+ * @returns {Array<{width: number, height: number}>} ascending by footprint
+ */
+export function planTextureBuckets( sizes, maxTextureSize, count = TEXTURE_CONSTANTS.MATERIAL_BUCKET_COUNT ) {
+
+	const distinct = new Map();
+
+	for ( const { width, height } of sizes ) {
+
+		const w = Math.min( maxTextureSize, Math.max( 1, width || 1 ) );
+		const h = Math.min( maxTextureSize, Math.max( 1, height || 1 ) );
+		const key = `${w}x${h}`;
+		const seen = distinct.get( key );
+		if ( seen ) seen.count ++;
+		else distinct.set( key, { width: w, height: h, count: 1 } );
+
+	}
+
+	const units = [ ...distinct.values() ];
+	let buckets = units.map( unit => bucketOf( [ unit ] ) );
+
+	if ( buckets.length > count ) {
+
+		const ladder = ladderBuckets( units, count, maxTextureSize );
+		const merged = mergeDown( buckets, count, maxTextureSize );
+		buckets = totalCost( ladder, maxTextureSize ) < totalCost( merged, maxTextureSize ) ? ladder : merged;
+		buckets = refine( buckets, maxTextureSize );
+
+	}
+
+	return buckets
+		.map( b => ( { width: alignBucketWidth( b.width, maxTextureSize ), height: b.height } ) )
+		.sort( ( a, b ) => a.width * a.height - b.width * b.height );
+
+}
+
+/**
+ * Index of the cheapest planned bucket that can hold a texture at its native size.
+ * A texture larger than every bucket lands in the largest and is downscaled there.
+ *
+ * @param {number} width
+ * @param {number} height
+ * @param {Array<{width: number, height: number}>} shapes - from {@link planTextureBuckets}
+ * @returns {number}
+ */
+export function getTextureBucketId( width, height, shapes ) {
 
-	const longest = Math.max( width || 1, height || 1 );
-	const pot = Math.pow( 2, Math.ceil( Math.log2( longest ) ) );
-	const sizes = getTextureBucketSizes( maxTextureSize, count );
-	for ( let i = 0; i < sizes.length; i ++ ) if ( pot <= sizes[ i ] ) return i;
-	return sizes.length - 1;
+	const w = Math.max( 1, width || 1 );
+	const h = Math.max( 1, height || 1 );
+	for ( let i = 0; i < shapes.length; i ++ ) if ( shapes[ i ].width >= w && shapes[ i ].height >= h ) return i;
+	return Math.max( 0, shapes.length - 1 );
 
 }
 

package/src/EngineIssues.js

@@ -9,6 +9,7 @@ export const ISSUE_CODES = Object.freeze( {
 	ASSET_UNREACHABLE: 'asset.unreachable',
 	TEXTURE_BUILD_FAILED: 'texture.build_failed',
 	TEXTURE_PROCESSING_FALLBACK: 'texture.processing_fallback',
+	TEXTURE_LIMIT_EXCEEDED: 'texture.limit_exceeded',
 	ENVIRONMENT_LOAD_FAILED: 'environment.load_failed',
 	SETTING_UNKNOWN_KEY: 'setting.unknown_key',
 	RENDER_SIZE_DECLINED: 'render.size_declined',

package/src/Processor/GeometryExtractor.js

@@ -1,10 +1,11 @@
 import { Vector3, Vector2, Color, Matrix3, Matrix4, FrontSide, BackSide, DoubleSide, RGBAFormat } from "three";
-import { TRIANGLE_DATA_LAYOUT } from '../EngineDefaults.js';
+import { TEXTURE_CONSTANTS, TRIANGLE_DATA_LAYOUT } from '../EngineDefaults.js';
+import { ISSUE_CODES } from '../EngineIssues.js';
 import { createLogger, fmt, warnOnce } from '../utils/Logger.js';
 
 const log = createLogger( 'geometry' );
 
-const MAX_TEXTURES_LIMIT = 128;
+const MAX_TEXTURES_LIMIT = TEXTURE_CONSTANTS.MAX_TEXTURES_LIMIT;
 
 /**
  * glTF 2.0 alphaMode for a three.js material: 0 OPAQUE, 1 MASK, 2 BLEND.
@@ -55,7 +56,11 @@ export function deriveAlphaMode( material ) {
 
 export class GeometryExtractor {
 
-	constructor() {
+	/** @param {{issues?: import('../EngineIssues.js').IssueLog}} [options] */
+	constructor( { issues = null } = {} ) {
+
+		this._issues = issues;
+		this._droppedTextures = 0;
 
 		// Object pools for reusing objects
 		this._vectorPool = {
@@ -528,6 +533,17 @@ export class GeometryExtractor {
 
 		}
 
+		this._droppedTextures ++;
+		if ( this._droppedTextures === 1 ) {
+
+			this._issues?.record(
+				ISSUE_CODES.TEXTURE_LIMIT_EXCEEDED,
+				`scene needs more than ${MAX_TEXTURES_LIMIT} distinct textures for one map type; the rest render untextured`,
+				{ limit: MAX_TEXTURES_LIMIT, firstDropped: texture.name || texture.source?.uuid }
+			);
+
+		}
+
 		return - 1;
 
 	}
@@ -800,6 +816,8 @@ export class GeometryExtractor {
 
 	resetArrays() {
 
+		this._droppedTextures = 0;
+
 		// Reset triangle data
 		this.triangleData = null;
 		this.triangleCount = 0;

package/src/Processor/SceneProcessor.js

@@ -11,7 +11,8 @@ import { updateLoading } from '../Processor/utils.js';
 import { BuildTimer } from './BuildTimer.js';
 import { createLogger, fmt, workerLogLevel } from '../utils/Logger.js';
 import { SRGBColorSpace } from 'three';
-import { TRIANGLE_DATA_LAYOUT, TEXTURE_CONSTANTS, getTextureBucketId, packTextureIndex } from '../EngineDefaults.js';
+import { TRIANGLE_DATA_LAYOUT, TEXTURE_CONSTANTS, getTextureBucketId, packTextureIndex, planTextureBuckets } from '../EngineDefaults.js';
+import { ISSUE_CODES } from '../EngineIssues.js';
 import BVHWorker from './Workers/BVHWorker.js?worker&inline';
 import BVHRefitWorker from './Workers/BVHRefitWorker.js?worker&inline';
 
@@ -145,7 +146,7 @@ export class SceneProcessor {
 	_initProcessors() {
 
 		// Create and configure geometry extractor
-		this.geometryExtractor = new GeometryExtractor();
+		this.geometryExtractor = new GeometryExtractor( { issues: this.config.issues } );
 
 		// Create and configure BVH builder
 		this.bvhBuilder = new BVHBuilder();
@@ -869,8 +870,9 @@ export class SceneProcessor {
 	/**
 	 * Group the extractor's seven per-type texture arrays into two consolidated colorSpace
 	 * pools (sRGB: albedo+emissive; linear: normal/bump/roughness/metalness/displacement),
-	 * each split into MATERIAL_BUCKET_COUNT longest-edge size buckets. Textures are deduped
-	 * across types within a (pool, bucket) so a shared image (e.g. ORM) costs one layer.
+	 * each split into at most MATERIAL_BUCKET_COUNT buckets whose shapes are planned from the
+	 * pool's own texture dimensions. Textures are deduped across types within a (pool, bucket)
+	 * so a shared image (e.g. ORM) costs one layer.
 	 * @returns {{ srgbLists: Array<Array>, linearLists: Array<Array>, remap: Object }}
 	 *          bucket lists + per-type remap arrays (old per-type layer → packed bucket index).
 	 * @private
@@ -881,6 +883,43 @@ export class SceneProcessor {
 		const K = TEXTURE_CONSTANTS.MATERIAL_BUCKET_COUNT;
 		const STRIDE = TEXTURE_CONSTANTS.BUCKET_LAYER_STRIDE;
 
+		const poolSizes = ( types ) => {
+
+			const seen = new Set();
+			const sizes = [];
+
+			for ( const arr of types ) {
+
+				for ( const tex of arr || [] ) {
+
+					if ( ! tex?.image ) continue;
+					const uuid = tex.source?.uuid ?? tex.uuid;
+					if ( seen.has( uuid ) ) continue;
+					seen.add( uuid );
+					sizes.push( { width: tex.image.width, height: tex.image.height } );
+
+				}
+
+			}
+
+			return sizes;
+
+		};
+
+		const srgbTypes = [ this.maps, this.emissiveMaps, this.sheenColorMaps, this.specularColorMaps ];
+		const linearTypes = [
+			this.normalMaps, this.bumpMaps, this.roughnessMaps, this.metalnessMaps, this.displacementMaps,
+			this.anisotropyMaps, this.transmissionMaps, this.clearcoatMaps, this.clearcoatRoughnessMaps,
+			this.sheenRoughnessMaps, this.iridescenceMaps, this.iridescenceThicknessMaps, this.specularIntensityMaps,
+		];
+
+		const srgbShapes = planTextureBuckets( poolSizes( srgbTypes ), cap, K );
+		const linearShapes = planTextureBuckets( poolSizes( linearTypes ), cap, K );
+		this._srgbBucketShapes = srgbShapes;
+		this._linearBucketShapes = linearShapes;
+
+		// Always K-length even when the plan needs fewer shapes: downstream nodes are built
+		// per MATERIAL_BUCKET_COUNT and a short array would leave stale bindings behind.
 		const srgbLists = Array.from( { length: K }, () => [] );
 		const linearLists = Array.from( { length: K }, () => [] );
 		const srgbDedup = Array.from( { length: K }, () => new Map() );
@@ -891,17 +930,25 @@ export class SceneProcessor {
 		this._srgbTexPacked = new Map();
 		this._linearTexPacked = new Map();
 
+		let bucketOverflowReported = false;
+
 		// Assign one texture to its (bucket, layer) within a pool; dedup by source uuid.
-		const assign = ( tex, lists, dedup, flat ) => {
+		const assign = ( tex, lists, dedup, flat, shapes ) => {
 
 			if ( ! tex || ! tex.image ) return - 1;
-			const bucket = getTextureBucketId( tex.image.width, tex.image.height, cap, K );
+			const bucket = getTextureBucketId( tex.image.width, tex.image.height, shapes );
 			const uuid = tex.source?.uuid ?? tex.uuid;
 			const seen = dedup[ bucket ].get( uuid );
 			if ( seen !== undefined ) return packTextureIndex( bucket, seen );
 			if ( lists[ bucket ].length >= STRIDE ) {
 
 				log.warn( `texture bucket ${bucket} full (${STRIDE}); dropping a map` );
+				if ( ! bucketOverflowReported ) this.config.issues?.record(
+					ISSUE_CODES.TEXTURE_LIMIT_EXCEEDED,
+					`texture bucket ${bucket} full (${STRIDE} layers); the rest render untextured`,
+					{ bucket, limit: STRIDE }
+				);
+				bucketOverflowReported = true;
 				return - 1;
 
 			}
@@ -917,27 +964,27 @@ export class SceneProcessor {
 
 		// Per-type arrays hold unique textures indexed by the layer the extractor assigned
 		// (= array position), so remap[type][oldLayer] = packed index.
-		const remapType = ( arr, lists, dedup, flat ) => ( arr || [] ).map( tex => assign( tex, lists, dedup, flat ) );
+		const remapType = ( arr, lists, dedup, flat, shapes ) => ( arr || [] ).map( tex => assign( tex, lists, dedup, flat, shapes ) );
 
 		const remap = {
-			albedo: remapType( this.maps, srgbLists, srgbDedup, this._srgbTexPacked ),
-			emissive: remapType( this.emissiveMaps, srgbLists, srgbDedup, this._srgbTexPacked ),
-			normal: remapType( this.normalMaps, linearLists, linearDedup, this._linearTexPacked ),
-			bump: remapType( this.bumpMaps, linearLists, linearDedup, this._linearTexPacked ),
-			roughness: remapType( this.roughnessMaps, linearLists, linearDedup, this._linearTexPacked ),
-			metalness: remapType( this.metalnessMaps, linearLists, linearDedup, this._linearTexPacked ),
-			displacement: remapType( this.displacementMaps, linearLists, linearDedup, this._linearTexPacked ),
-			anisotropy: remapType( this.anisotropyMaps, linearLists, linearDedup, this._linearTexPacked ),
+			albedo: remapType( this.maps, srgbLists, srgbDedup, this._srgbTexPacked, srgbShapes ),
+			emissive: remapType( this.emissiveMaps, srgbLists, srgbDedup, this._srgbTexPacked, srgbShapes ),
+			normal: remapType( this.normalMaps, linearLists, linearDedup, this._linearTexPacked, linearShapes ),
+			bump: remapType( this.bumpMaps, linearLists, linearDedup, this._linearTexPacked, linearShapes ),
+			roughness: remapType( this.roughnessMaps, linearLists, linearDedup, this._linearTexPacked, linearShapes ),
+			metalness: remapType( this.metalnessMaps, linearLists, linearDedup, this._linearTexPacked, linearShapes ),
+			displacement: remapType( this.displacementMaps, linearLists, linearDedup, this._linearTexPacked, linearShapes ),
+			anisotropy: remapType( this.anisotropyMaps, linearLists, linearDedup, this._linearTexPacked, linearShapes ),
 			// Extension maps — data maps → linear pool; color maps (sheenColor, specularColor) → sRGB pool.
-			transmission: remapType( this.transmissionMaps, linearLists, linearDedup, this._linearTexPacked ),
-			clearcoat: remapType( this.clearcoatMaps, linearLists, linearDedup, this._linearTexPacked ),
-			clearcoatRoughness: remapType( this.clearcoatRoughnessMaps, linearLists, linearDedup, this._linearTexPacked ),
-			sheenColor: remapType( this.sheenColorMaps, srgbLists, srgbDedup, this._srgbTexPacked ),
-			sheenRoughness: remapType( this.sheenRoughnessMaps, linearLists, linearDedup, this._linearTexPacked ),
-			iridescence: remapType( this.iridescenceMaps, linearLists, linearDedup, this._linearTexPacked ),
-			iridescenceThickness: remapType( this.iridescenceThicknessMaps, linearLists, linearDedup, this._linearTexPacked ),
-			specularIntensity: remapType( this.specularIntensityMaps, linearLists, linearDedup, this._linearTexPacked ),
-			specularColor: remapType( this.specularColorMaps, srgbLists, srgbDedup, this._srgbTexPacked ),
+			transmission: remapType( this.transmissionMaps, linearLists, linearDedup, this._linearTexPacked, linearShapes ),
+			clearcoat: remapType( this.clearcoatMaps, linearLists, linearDedup, this._linearTexPacked, linearShapes ),
+			clearcoatRoughness: remapType( this.clearcoatRoughnessMaps, linearLists, linearDedup, this._linearTexPacked, linearShapes ),
+			sheenColor: remapType( this.sheenColorMaps, srgbLists, srgbDedup, this._srgbTexPacked, srgbShapes ),
+			sheenRoughness: remapType( this.sheenRoughnessMaps, linearLists, linearDedup, this._linearTexPacked, linearShapes ),
+			iridescence: remapType( this.iridescenceMaps, linearLists, linearDedup, this._linearTexPacked, linearShapes ),
+			iridescenceThickness: remapType( this.iridescenceThicknessMaps, linearLists, linearDedup, this._linearTexPacked, linearShapes ),
+			specularIntensity: remapType( this.specularIntensityMaps, linearLists, linearDedup, this._linearTexPacked, linearShapes ),
+			specularColor: remapType( this.specularColorMaps, srgbLists, srgbDedup, this._srgbTexPacked, srgbShapes ),
 		};
 
 		return { srgbLists, linearLists, remap };

package/src/Processor/TextureCreator.js

@@ -1,5 +1,5 @@
 import { DataArrayTexture, RGBAFormat, LinearFilter, UnsignedByteType, SRGBColorSpace, LinearSRGBColorSpace, RepeatWrapping } from "three";
-import { TEXTURE_CONSTANTS, MEMORY_CONSTANTS, DEFAULT_TEXTURE_MATRIX, MATERIAL_DATA_LAYOUT, normalizeAttenuationDistance } from '../EngineDefaults.js';
+import { alignBucketWidth, TEXTURE_CONSTANTS, MEMORY_CONSTANTS, DEFAULT_TEXTURE_MATRIX, MATERIAL_DATA_LAYOUT, normalizeAttenuationDistance } from '../EngineDefaults.js';
 import TexturesWorker from './Workers/TexturesWorker.js?worker&inline';
 import { ISSUE_CODES } from '../EngineIssues.js';
 import { linearToSRGB } from './ToneMapCPU.js';
@@ -1318,18 +1318,17 @@ export class TextureCreator {
 
 		}
 
-		maxWidth = Math.pow( 2, Math.ceil( Math.log2( maxWidth ) ) );
-		maxHeight = Math.pow( 2, Math.ceil( Math.log2( maxHeight ) ) );
+		// Scale down proportionally only when the cap is exceeded; native res is kept below it.
+		const longest = Math.max( maxWidth, maxHeight );
+		if ( longest > this.maxTextureSize ) {
 
-		// Halve only while a dimension exceeds the cap (preserves native res up to the cap).
-		while ( maxWidth > this.maxTextureSize || maxHeight > this.maxTextureSize ) {
-
-			maxWidth = Math.max( 1, Math.floor( maxWidth / 2 ) );
-			maxHeight = Math.max( 1, Math.floor( maxHeight / 2 ) );
+			const scale = this.maxTextureSize / longest;
+			maxWidth = Math.round( maxWidth * scale );
+			maxHeight = Math.round( maxHeight * scale );
 
 		}
 
-		return { maxWidth, maxHeight };
+		return { maxWidth: alignBucketWidth( maxWidth, this.maxTextureSize ), maxHeight: Math.max( 1, maxHeight ) };
 
 	}
 

package/src/Processor/Workers/TexturesWorker.js

@@ -619,23 +619,22 @@ function calculateOptimalDimensions( textures, maxTextureSize ) {
 
 	}
 
-	// Round to power of 2 for optimal GPU performance
-	maxWidth = Math.pow( 2, Math.ceil( Math.log2( maxWidth ) ) );
-	maxHeight = Math.pow( 2, Math.ceil( Math.log2( maxHeight ) ) );
+	// Scale down proportionally only when the cap is exceeded; native res is kept below it.
+	const cap = Math.min( maxTextureSize, MEMORY_LIMITS.MAX_TEXTURE_DIMENSION );
+	const longest = Math.max( maxWidth, maxHeight );
+	if ( longest > cap ) {
 
-	// Respect texture size limits
-	maxWidth = Math.min( maxWidth, maxTextureSize, MEMORY_LIMITS.MAX_TEXTURE_DIMENSION );
-	maxHeight = Math.min( maxHeight, maxTextureSize, MEMORY_LIMITS.MAX_TEXTURE_DIMENSION );
-
-	// Halve only while a dimension exceeds the cap (preserves native res up to the cap).
-	while ( maxWidth > maxTextureSize || maxHeight > maxTextureSize ) {
-
-		maxWidth = Math.max( 1, Math.floor( maxWidth / 2 ) );
-		maxHeight = Math.max( 1, Math.floor( maxHeight / 2 ) );
+		const scale = cap / longest;
+		maxWidth = Math.round( maxWidth * scale );
+		maxHeight = Math.round( maxHeight * scale );
 
 	}
 
-	return { maxWidth, maxHeight };
+	// An RGBA8 row upload must be a multiple of 256 bytes, so widths land on 64 texels.
+	// Mirrors alignBucketWidth in EngineDefaults (not importable from worker context).
+	maxWidth = Math.min( cap, Math.max( 4, Math.ceil( Math.max( 1, maxWidth ) / 64 ) * 64 ) );
+
+	return { maxWidth, maxHeight: Math.max( 1, maxHeight ) };
 
 }
 
@@ -645,7 +644,7 @@ function calculateReducedDimensions( textures, maxTextureSize ) {
 	const original = calculateOptimalDimensions( textures, maxTextureSize );
 
 	return {
-		maxWidth: Math.max( 1, Math.floor( original.maxWidth / 2 ) ),
+		maxWidth: Math.max( 64, Math.ceil( original.maxWidth / 128 ) * 64 ),
 		maxHeight: Math.max( 1, Math.floor( original.maxHeight / 2 ) )
 	};
 

package/src/Processor/utils.js

@@ -38,12 +38,6 @@ export function getDisplaySamples( pathTracerStage ) {
 
 }
 
-export function getNearestPowerOf2( size ) {
-
-	return Math.pow( 2, Math.ceil( Math.log2( size ) ) );
-
-}
-
 export function disposeMaterial( material ) {
 
 	if ( Array.isArray( material ) ) {

package/src/TSL/BVHTraversal.js

@@ -24,7 +24,9 @@ import { HitInfo } from './Struct.js';
 import { getDatafromStorageBuffer } from './Common.js';
 
 const MAX_STACK_DEPTH = 32;
-const MAX_BVH_ITERATIONS = 512;
+// Hang guard only — tripping it reports a MISS, which the shade kernel pays out as
+// full-intensity environment. San Miguel needs ~1024; cost is flat from 1024 up.
+const MAX_BVH_ITERATIONS = 4096;
 const BVH_STRIDE = 4;
 const TRI_STRIDE = 8;
 const HUGE_VAL = 1e8;

package/src/TSL/TextureSampling.js

@@ -10,11 +10,12 @@ import { getDatafromStorageBuffer } from './Common.js';
 import { TEXTURE_CONSTANTS } from '../EngineDefaults.js';
 
 // ================================================================================
-// CONSOLIDATED SIZE-BUCKETED MATERIAL TEXTURES
+// CONSOLIDATED SHAPE-BUCKETED MATERIAL TEXTURES
 // ================================================================================
 // Material maps are packed into two colorSpace pools (sRGB: albedo+emissive; linear:
 // normal/bump/roughness/metalness/displacement), each split into MATERIAL_BUCKET_COUNT
-// longest-edge size buckets so a small map no longer pays a large neighbour's footprint.
+// (width, height) buckets so a small or oddly-shaped map no longer pays a large neighbour's
+// footprint. Bucket shapes are planned per scene (planTextureBuckets) — not powers of two.
 // A map's stored index encodes (bucket, layer) as bucket * BUCKET_LAYER_STRIDE + layer.
 //
 // The bucket texture nodes live at module level (same pattern as gobo/IES/shadowAlbedo):