rayzee 9.4.2 → 9.5.0

package/src/Storage/CDFCache.js

@@ -1,8 +1,8 @@
-import { ENGINE_AREAS } from './StorageManager.js';
+import { ENGINE_AREAS } from './areas.js';
 import { sharedStorage } from './shared.js';
 import { getAssetConfig } from '../AssetConfig.js';
 
-const FORMAT = 1;
+const FORMAT = 5;
 
 /**
  * Where an environment texture came from, recorded by the loader so its sampling tables can be
@@ -25,7 +25,10 @@ function keyFor( texture ) {
 
 const area = () => sharedStorage( getAssetConfig().cacheNamespace )?.area( ENGINE_AREAS.CDF ) ?? null;
 
-/** @returns {Promise<?{marginalData: Float32Array, conditionalData: Float32Array, totalSum: number, compensationDelta: number, width: number, height: number}>} */
+const ARRAYS = [ 'exactConditional', 'exactMarginal', 'exactRowGuide', 'exactMarginalGuide' ];
+const FILES = ARRAYS.map( name => `${name}.f32` );
+
+/** @returns {Promise<?Object>} the fields of an EquirectHDRInfo build */
 export async function loadCDF( texture ) {
 
 	const key = keyFor( texture );
@@ -34,14 +37,11 @@ export async function loadCDF( texture ) {
 
 	try {
 
-		const [ marginal, conditional ] = await Promise.all( [ entry.file( 'marginal.f32' ), entry.file( 'conditional.f32' ) ] );
-		if ( ! marginal || ! conditional ) return null;
-		const { totalSum, compensationDelta, width, height } = entry.extra;
-		return {
-			marginalData: new Float32Array( await marginal.arrayBuffer() ),
-			conditionalData: new Float32Array( await conditional.arrayBuffer() ),
-			totalSum, compensationDelta, width, height,
-		};
+		const files = await Promise.all( FILES.map( name => entry.file( name ) ) );
+		if ( files.some( f => ! f ) ) return null;
+		const arrays = await Promise.all( files.map( async f => new Float32Array( await f.arrayBuffer() ) ) );
+		const { totalSum, width, height, exactWidth, exactHeight, radianceIntegral } = entry.extra;
+		return { ...Object.fromEntries( ARRAYS.map( ( name, i ) => [ name, arrays[ i ] ] ) ), totalSum, width, height, exactWidth, exactHeight, radianceIntegral };
 
 	} finally {
 
@@ -51,20 +51,21 @@ export async function loadCDF( texture ) {
 
 }
 
-export async function saveCDF( texture, { marginalData, conditionalData, totalSum, compensationDelta, width, height } ) {
+export async function saveCDF( texture, info ) {
 
+	const { totalSum, width, height, exactWidth, exactHeight, radianceIntegral } = info;
+	const arrays = ARRAYS.map( name => info[ name ] );
 	const key = keyFor( texture );
 	const target = key ? area() : null;
-	if ( ! target || ! marginalData || ! conditionalData ) return false;
+	if ( ! target || arrays.some( a => ! a ) ) return false;
 
-	const writer = await target.create( key, { label: texture.name || 'environment', expectedBytes: marginalData.byteLength + conditionalData.byteLength } );
+	const writer = await target.create( key, { label: texture.name || 'environment', expectedBytes: arrays.reduce( ( n, a ) => n + a.byteLength, 0 ) } );
 	if ( ! writer ) return false;
 
 	try {
 
-		await writer.write( 'marginal.f32', marginalData );
-		await writer.write( 'conditional.f32', conditionalData );
-		await writer.commit( { totalSum, compensationDelta, width, height } );
+		for ( let i = 0; i < FILES.length; i ++ ) await writer.write( FILES[ i ], arrays[ i ] );
+		await writer.commit( { totalSum, width, height, exactWidth, exactHeight, radianceIntegral } );
 		return true;
 
 	} catch {

package/src/Storage/DownloadCache.js

@@ -1,4 +1,4 @@
-import { ENGINE_AREAS } from './StorageManager.js';
+import { ENGINE_AREAS } from './areas.js';
 import { sharedStorage } from './shared.js';
 import { getAssetConfig } from '../AssetConfig.js';
 

package/src/Storage/SceneGraphCodec.js

@@ -9,11 +9,13 @@
  */
 
 import {
-	AnimationClip, BufferAttribute, BufferGeometry, DataTexture, Group, InstancedBufferAttribute, InstancedMesh,
-	MaterialLoader, Mesh, Object3D, OrthographicCamera, PerspectiveCamera,
+	AnimationClip, BufferAttribute, BufferGeometry, Color, DataTexture, Group, InstancedBufferAttribute, InstancedMesh,
+	MaterialLoader, Mesh, Object3D, OrthographicCamera, PerspectiveCamera, DirectionalLight, PointLight, SpotLight,
 } from 'three';
 
 export const SCENE_GRAPH_FORMAT = 2;
+// Texture slots the engine reads off a material that three.js does not serialise.
+const ENGINE_TEXTURES = [ 'diffuseTransmissionMap', 'diffuseTransmissionColorMap' ];
 export const ARCHIVE_PATH = '__rayzeeArchivePath';
 export const ARCHIVE_LOADER = '__rayzeeArchiveLoader';
 
@@ -28,6 +30,7 @@ const TEXTURE_PROPS = [
 	'flipY', 'generateMipmaps', 'premultiplyAlpha', 'unpackAlignment', 'colorSpace',
 ];
 
+const LIGHT_PROPS = [ 'intensity', 'distance', 'decay', 'angle', 'penumbra' ];
 const OBJECT_PROPS = [ 'name', 'visible', 'castShadow', 'receiveShadow', 'frustumCulled', 'renderOrder', 'matrixAutoUpdate' ];
 
 export class SceneGraphUnsupported extends Error {
@@ -48,6 +51,9 @@ function kindOf( object ) {
 	if ( object.isMesh ) return 'Mesh';
 	if ( object.isPerspectiveCamera ) return 'PerspectiveCamera';
 	if ( object.isOrthographicCamera ) return 'OrthographicCamera';
+	if ( object.isDirectionalLight ) return 'DirectionalLight';
+	if ( object.isPointLight ) return 'PointLight';
+	if ( object.isSpotLight ) return 'SpotLight';
 	if ( object.isLight || object.isPoints || object.isLine || object.isSprite || object.isLOD ) return null;
 	if ( object.isGroup ) return 'Group';
 	return object.constructor === Object3D ? 'Object3D' : null;
@@ -163,6 +169,9 @@ function encodeMaterial( material, meta ) {
 	for ( const [ key, value ] of Object.entries( material ) ) if ( value?.isColor ) json.exactColors[ key ] = [ value.r, value.g, value.b ];
 	// MaterialLoader sets `reflectivity` after `ior`, and that setter rewrites ior with rounding.
 	if ( material.ior !== undefined ) json.exactIor = material.ior;
+	// Engine properties three.js does not know, so toJSON drops them.
+	if ( material.diffuseTransmission !== undefined ) json.diffuseTransmission = material.diffuseTransmission;
+	for ( const key of ENGINE_TEXTURES ) if ( material[ key ]?.isTexture ) ( json.engineTextures ??= {} )[ key ] = material[ key ].uuid;
 	return json;
 
 }
@@ -234,6 +243,14 @@ export function encodeSceneGraph( root, { environment = null, animations = [], s
 
 		}
 
+		if ( object.isLight ) {
+
+			node.color = object.color.toArray();
+			for ( const prop of LIGHT_PROPS ) if ( object[ prop ] !== undefined ) node[ prop ] = object[ prop ];
+			if ( object.target ) node.target = object.target.uuid;
+
+		}
+
 		const index = nodes.push( node ) - 1;
 		for ( const child of object.children ) visit( child, index );
 
@@ -419,8 +436,16 @@ export async function decodeSceneGraph( manifest, data, { loadTexture } ) {
 	for ( const json of manifest.materials ) {
 
 		const material = materialLoader.parse( json );
-		for ( const [ key, rgb ] of Object.entries( json.exactColors ?? {} ) ) material[ key ]?.setRGB( rgb[ 0 ], rgb[ 1 ], rgb[ 2 ] );
+		for ( const [ key, rgb ] of Object.entries( json.exactColors ?? {} ) ) {
+
+			if ( key === 'diffuseTransmissionColor' ) material[ key ] = new Color();
+			material[ key ]?.setRGB( rgb[ 0 ], rgb[ 1 ], rgb[ 2 ] );
+
+		}
+
 		if ( json.exactIor !== undefined ) material.ior = json.exactIor;
+		if ( json.diffuseTransmission !== undefined ) material.diffuseTransmission = json.diffuseTransmission;
+		for ( const [ key, uuid ] of Object.entries( json.engineTextures ?? {} ) ) if ( textures[ uuid ] ) material[ key ] = textures[ uuid ];
 		materials[ json.uuid ] = material;
 
 	}
@@ -462,6 +487,9 @@ export async function decodeSceneGraph( manifest, data, { loadTexture } ) {
 			case 'PerspectiveCamera': object = new PerspectiveCamera(); break;
 			case 'OrthographicCamera': object = new OrthographicCamera(); break;
 			case 'Group': object = new Group(); break;
+			case 'DirectionalLight': object = new DirectionalLight(); break;
+			case 'PointLight': object = new PointLight(); break;
+			case 'SpotLight': object = new SpotLight(); break;
 			default: object = new Object3D();
 
 		}
@@ -487,11 +515,26 @@ export async function decodeSceneGraph( manifest, data, { loadTexture } ) {
 
 		}
 
+		if ( object.isLight ) {
+
+			object.color.fromArray( node.color );
+			for ( const prop of LIGHT_PROPS ) if ( node[ prop ] !== undefined ) object[ prop ] = node[ prop ];
+
+		}
+
 		built.push( object );
 		if ( node.parent >= 0 ) built[ node.parent ].add( object );
 
 	}
 
+	// A light aims at its target, which is stored as an object of its own.
+	const byUuid = new Map( built.map( ( object ) => [ object.uuid, object ] ) );
+	manifest.nodes.forEach( ( node, i ) => {
+
+		if ( node.target && byUuid.has( node.target ) ) built[ i ].target = byUuid.get( node.target );
+
+	} );
+
 	return {
 		root: built[ 0 ],
 		environment: manifest.environment ? textures[ manifest.environment ] : null,

package/src/Storage/SpillStore.js

@@ -1,4 +1,4 @@
-import { ENGINE_AREAS } from './StorageManager.js';
+import { ENGINE_AREAS } from './areas.js';
 
 const WRITE_PIECE_BYTES = 32 * 1024 * 1024;
 const FILE = 'chunks.bin';

package/src/Storage/StorageManager.js

@@ -3,11 +3,9 @@ import { acquireLock, heldLockNames } from './locks.js';
 import { entryIdFor } from './identity.js';
 import { Emitter } from './events.js';
 import { InlineTransport } from './inlineTransport.js';
+import { STORAGE_KIND, ENGINE_AREAS } from './areas.js';
 
-export const STORAGE_KIND = Object.freeze( { CACHE: 'cache', USER: 'user', SCRATCH: 'scratch' } );
-
-/** Areas the engine itself writes; hosts define their own with `defineArea`. */
-export const ENGINE_AREAS = Object.freeze( { DOWNLOADS: 'downloads', ARCHIVES: 'archives', SCENES: 'scenes', CDF: 'cdf', SPILL: 'spill' } );
+export { STORAGE_KIND, ENGINE_AREAS };
 
 const META = 'meta.json';
 const META_VERSION = 1;

package/src/Storage/areas.js

@@ -0,0 +1,4 @@
+export const STORAGE_KIND = Object.freeze( { CACHE: 'cache', USER: 'user', SCRATCH: 'scratch' } );
+
+/** Areas the engine itself writes; hosts define their own with `defineArea`. */
+export const ENGINE_AREAS = Object.freeze( { DOWNLOADS: 'downloads', ARCHIVES: 'archives', SCENES: 'scenes', CDF: 'cdf', SPILL: 'spill' } );

package/src/TSL/BVHTraversal.js

@@ -1,3 +1,4 @@
+import { sceneResources } from './SceneResources.js';
 import {
 	Fn,
 	wgslFn,
@@ -88,8 +89,10 @@ const toObjectDir = ( rows, d ) => vec3(
 // at shared triangle edges that Möller-Trumbore exhibits under FP32. Per-ray shears
 // are precomputed once via computeWoopFromInvDir; per-triangle test is FMA-friendly
 // and uses sign-aware depth comparison so it works for any det orientation.
-const RayTriangleGeometry = wgslFn( `
-	fn RayTriangleGeometry( rayOrigin: vec3f, rayDir: vec3f, pA: vec3f, pB: vec3f, pC: vec3f, closestHitDst: f32, woopParams: vec4f ) -> vec4f {
+// guardT: reject t within its own rounding error. Closest-hit rays need it to leave a large triangle; shadow rays
+// start lifted off their surface and skip it — its registers cost Shade's shadow traversal ~4 %.
+const rayTriangle = ( name, guardT ) => wgslFn( `
+	fn ${ name }( rayOrigin: vec3f, rayDir: vec3f, pA: vec3f, pB: vec3f, pC: vec3f, closestHitDst: f32, woopParams: vec4f ) -> vec4f {
 
 		// Returns vec4(t, u, v, hit) where hit > 0.5 means intersection.
 		// woopParams: (Sx, Sy, Sz, bitcast<f32>(packed kx|ky<<2|kz<<4))
@@ -138,7 +141,19 @@ const RayTriangleGeometry = wgslFn( `
 				let tSigned = T * detSign;
 				let detAbs = abs( det );
 
-				if ( tSigned > 0.0f && tSigned < closestHitDst * detAbs ) {
+${ guardT ? `
+				// t must clear its own rounding error (pbrt-v4 Triangle::Intersect, γn = n·2⁻²⁴ / (1 − n·2⁻²⁴)), or a
+				// ray leaving a large triangle can hit it again: its error grows with the distance to the vertices.
+				let maxZ = max( max( abs( Sz * Akz ), abs( Sz * Bkz ) ), abs( Sz * Ckz ) );
+				let maxX = max( max( abs( Ax ), abs( Bx ) ), abs( Cx ) );
+				let maxY = max( max( abs( Ay ), abs( By ) ), abs( Cy ) );
+				let maxE = max( max( abs( U ), abs( V ) ), abs( W ) );
+				let deltaX = 2.98023e-7f * ( maxX + maxZ );
+				let deltaY = 2.98023e-7f * ( maxY + maxZ );
+				let deltaE = 2.0f * ( 1.19209e-7f * maxX * maxY + deltaY * maxX + deltaX * maxY );
+				let errT = 3.0f * maxZ * ( 3.57628e-7f * maxE + deltaE );
+` : '' }
+				if ( tSigned > ${ guardT ? 'errT' : '0.0f' } && tSigned < closestHitDst * detAbs ) {
 
 					// Match Möller-Trumbore convention: u = weight of B, v = weight of C.
 					// In Woop's edge functions, U → weight of A, V → weight of B, W → weight of C.
@@ -156,6 +171,9 @@ const RayTriangleGeometry = wgslFn( `
 	}
 ` );
 
+const RayTriangleGeometry = rayTriangle( 'RayTriangleGeometry', true );
+const RayTriangleGeometryShadow = rayTriangle( 'RayTriangleGeometryShadow', false );
+
 // Compute Woop ray-space transform (Woop 2013, §3.1) — runs once per ray and
 // amortizes across hundreds of triangle tests. Returns Sx/Sy/Sz shears plus the
 // permuted axis indices packed via bitcast into the .w slot.
@@ -517,12 +535,15 @@ export const traverseBVHDebug = /*@__PURE__*/ makeTraverseBVH( true );
 // SHADOW RAY TRAVERSAL (OPTIMIZED - early exit on any hit)
 // ================================================================================
 
-export const traverseBVHShadow = Fn( ( [
+// cameraCulled: skip the faces a camera ray along −direction would cull, for a ray standing in for one.
+const makeTraverseBVHShadow = ( cameraCulled ) => Fn( ( [
 	ray,
 	bvhBuffer,
 	triangleBuffer,
 	maxShadowDist,
-] ) => {
+], builder ) => {
+
+	const { alphaShadows } = sceneResources( builder );
 
 	const folded = bvhBuffer.value?.foldedLeaves === true;
 	const isLeafTag = leafTagTest( folded );
@@ -572,36 +593,50 @@ export const traverseBVHShadow = Fn( ( [
 			const pB = uintBitsToFloat( triangleRow( triangleBuffer, triIndex, 1 ).xyz );
 			const pC = uintBitsToFloat( triangleRow( triangleBuffer, triIndex, 2 ).xyz );
 
-			const triResult = RayTriangleGeometry( { rayOrigin, rayDir: rayDirection, pA, pB, pC, closestHitDst: closestHit.dst, woopParams } );
+			const triResult = RayTriangleGeometryShadow( { rayOrigin, rayDir: rayDirection, pA, pB, pC, closestHitDst: closestHit.dst, woopParams } );
 
 			If( triResult.w.greaterThan( 0.5 ), () => {
 
 				// Per-mesh visibility is handled at the BLAS-pointer level.
 				const uvData2 = triangleRow( triangleBuffer, triIndex, 4 ).toVar();
 
-				closestHit.didHit.assign( true );
-				closestHit.dst.assign( triResult.x );
-				closestHit.materialIndex.assign( int( uvData2.z.bitAnd( uint( TRI_MATERIAL_MASK ) ) ) );
-				closestHit.meshIndex.assign( int( uvData2.w ) );
-				closestHit.instanceLeaf.assign( instLeaf );
+				const record = () => {
 
-				// Hit point is cheap (origin + dir*t). Geometric normal is deferred
-				// to traceShadowRay — only the transmission branch needs it, so we
-				// skip the cross+normalize for the (much more common) opaque-blocker
-				// and alpha-cutout paths. Normal stays vec3(0) from struct init.
-				closestHit.hitPoint.assign( worldOrigin.add( worldDirection.mul( triResult.x ) ) );
+					closestHit.didHit.assign( true );
+					closestHit.dst.assign( triResult.x );
+					closestHit.materialIndex.assign( int( uvData2.z.bitAnd( uint( TRI_MATERIAL_MASK ) ) ) );
+					closestHit.meshIndex.assign( int( uvData2.w ) );
+					closestHit.instanceLeaf.assign( instLeaf );
 
-				closestHit.uv.assign( vec2( triResult.y, triResult.z ) );
-				closestHit.triangleIndex.assign( triIndex );
+					// Hit point is cheap (origin + dir*t). Geometric normal is deferred
+					// to traceShadowRay — only the transmission branch needs it, so we
+					// skip the cross+normalize for the (much more common) opaque-blocker
+					// and alpha-cutout paths. Normal stays vec3(0) from struct init.
+					closestHit.hitPoint.assign( worldOrigin.add( worldDirection.mul( triResult.x ) ) );
 
-				// An opaque blocker settles the ray. A surface light passes through has to be
-				// the nearest one, or the layers behind the first find are never counted.
-				If( shadowFlagsSettle( uvData2.z ), () => {
+					closestHit.uv.assign( vec2( triResult.y, triResult.z ) );
+					closestHit.triangleIndex.assign( triIndex );
 
-					blocked.assign( true );
-					Break();
+					// An opaque blocker settles the ray. A surface light passes through has to be
+					// the nearest one, or the layers behind the first find are never counted.
+					If( shadowFlagsSettle( uvData2.z, alphaShadows ), () => {
 
-				} );
+						blocked.assign( true );
+						Break();
+
+					} );
+
+				};
+
+				if ( cameraCulled ) {
+
+					const w = float( 1.0 ).sub( triResult.y ).sub( triResult.z );
+					const n = normalize( unpackTriangleNormal( triangleRow( triangleBuffer, triIndex, 0 ).w ).mul( w )
+						.add( unpackTriangleNormal( triangleRow( triangleBuffer, triIndex, 1 ).w ).mul( triResult.y ) )
+						.add( unpackTriangleNormal( triangleRow( triangleBuffer, triIndex, 2 ).w ).mul( triResult.z ) ) );
+					If( sideAccepts( triangleSide( uvData2.z ), rayDirection.dot( n ).negate() ), record );
+
+				} else record();
 
 			} );
 
@@ -726,3 +761,6 @@ export const traverseBVHShadow = Fn( ( [
 	return closestHit;
 
 } );
+
+export const traverseBVHShadow = /*@__PURE__*/ makeTraverseBVHShadow( false );
+export const traverseBVHShadowCameraCulled = /*@__PURE__*/ makeTraverseBVHShadow( true );

package/src/TSL/Bidirectional.js

@@ -0,0 +1,204 @@
+/**
+ * Bidirectional path tracing — shared by the light pass, ConnectKernel and LightSplatKernel.
+ * MIS is Georgiev 2012's dVCM/dVC recursion; every density comes from calculateMaterialPDF, both ways
+ * round, so every strategy evaluates the same weights. With vertex merging (integrator 'vcm') a state also
+ * carries `vm`, η² at its vertex (η = πr² · light paths, r that vertex's merge radius): Georgiev's dVM there is
+ * dVC / η², so it is never stored.
+ */
+
+import {
+	float, vec2, vec4, int, uint, If, max, select, abs, dot, length,
+} from 'three/tsl';
+
+import { getMaterial, MIN_ROUGHNESS, REC709_LUMINANCE_COEFFICIENTS } from './Common.js';
+import { RayTracingMaterial, MaterialSamples, ExtMapResult } from './Struct.js';
+import { sampleAllMaterialTextures, processAnisotropyMap, applyExtensionMaps, getTransformedUV } from './TextureSampling.js';
+import { SAMPLER_DIM_AUX_BASE } from './Random.js';
+
+// 1D dimensions of a camera vertex's bounce block (Random.js budget) picking its connection.
+export const DIM_CONNECT_PATH = 16;
+export const DIM_CONNECT_VERTEX = 17;
+// Emission: 1D triangle pick, 2D point, 2D direction, 1D side, 1D sun or emitter, 2D sun direction, 2D disc point.
+export const DIM_EMIT = SAMPLER_DIM_AUX_BASE + 2048;
+
+// Light paths draw at pixels far below the image, so their sequences never repeat a camera path's.
+export const LIGHT_PIXEL_ROW_OFFSET = 65536;
+
+// Light tracing adds into u32 per channel: value · SPLAT_SCALE, rounded stochastically.
+export const SPLAT_SCALE = 16384;
+export const SPLAT_MAX = 4096;
+
+// Pending-connection tags set the high bit: a light path's data in that lane is a positive float's bits.
+export const PASS_TAG_BIT = 0x80000000;
+
+const MIS_MAX = 1e30;
+
+const finite = ( x ) => select( x.equal( x ), x, float( 0.0 ) ).clamp( 0.0, MIS_MAX );
+
+export const lightPathPixel = ( index, resolution ) => {
+
+	const w = uint( resolution.x );
+	return vec2( float( uint( index ).mod( w ) ).add( 0.5 ), float( uint( index ).div( w ).add( uint( LIGHT_PIXEL_ROW_OFFSET ) ) ).add( 0.5 ) );
+
+};
+
+// The power heuristic (β = 2). The recursion stores every density ratio already raised to it.
+export const mis = ( x ) => x.mul( x );
+
+// MIS recursion: `state` holds two .toVar()s, { dVCM, dVC }, updated in place, and `vm` when merging.
+
+/** Arriving at a vertex `dist` from the last one, at |cos| `cosIn` to its facet. */
+export const misOnHit = ( state, dist, cosIn ) => {
+
+	const c = max( cosIn, 1e-6 );
+	state.dVCM.assign( finite( state.dVCM.mul( mis( dist.mul( dist ).div( c ) ) ) ) );
+	state.dVC.assign( finite( state.dVC.div( mis( c ) ) ) );
+
+};
+
+/** Leaving through a delta lobe, a refraction or a subsurface boundary: nothing can connect here. */
+export const misOnSpecular = ( state, cosOut ) => {
+
+	state.dVC.assign( finite( state.dVC.mul( mis( cosOut ) ) ) );
+	state.dVCM.assign( 0.0 );
+
+};
+
+/** Leaving by a BSDF sample; densities are solid angle, forward the sampler's and reverse its partner's. */
+export const misOnScatter = ( state, cosOut, pdfForward, pdfReverse ) => {
+
+	const p = max( pdfForward, 1e-12 );
+	const partial = state.dVC.mul( mis( pdfReverse ) ).add( state.dVCM );
+	state.dVC.assign( finite( mis( cosOut.div( p ) ).mul( finite( state.vm ? partial.add( state.vm ) : partial ) ) ) );
+	state.dVCM.assign( finite( mis( float( 1.0 ).div( p ) ) ) );
+
+};
+
+// Georgiev (40)-(46): `lead` is the other side's density of reaching this end, `reverse` this end's density back.
+export const misPartial = ( lead, state, reverse ) => {
+
+	const partial = state.dVCM.add( state.dVC.mul( mis( reverse ) ) );
+	return finite( finite( mis( lead ) ).mul( finite( state.vm ? partial.add( state.vm ) : partial ) ) );
+
+};
+
+// Vertex merging's radius at p: a few pixels' footprint seen from the camera (`mergeConst` + `mergeSlope` · distance),
+// at least `mergeMin`. A function of position alone, so both subpaths weigh a merge at any vertex alike.
+export const mergeRadiusAt = ( bdpt, p ) =>
+	max( bdpt.mergeConst.add( bdpt.mergeSlope.mul( length( p.sub( bdpt.cameraPosition ) ) ) ), bdpt.mergeMin );
+
+// η = πr² · light paths: a merge's density over a connection's, there.
+export const mergeEta = ( bdpt, radius ) => radius.mul( radius ).mul( Math.PI ).mul( float( bdpt.lightPaths ) );
+
+/**
+ * η² at p as the weights take it, a state's `vm` (Georgiev's vmFactor, per vertex): η scaled by `mergeTrust`. Any
+ * density the strategies agree on still sums their weights to one; trust below 1 hands light other strategies can
+ * also reach back to them, unblurred, and leaves light only a merge reaches (a caustic in a mirror) all to merging.
+ */
+export const mergeVmAt = ( bdpt, p ) => {
+
+	const eta = mergeEta( bdpt, mergeRadiusAt( bdpt, p ) ).mul( bdpt.mergeTrust );
+	return eta.mul( eta );
+
+};
+
+// Georgiev (38)-(39), a merge at a camera vertex: each side's sum, `density` the camera vertex's BSDF density
+// (of the light's arrival direction for the light side, back along its own for the camera side); `vc` = 1 / η².
+export const misMergePartial = ( state, density, vc ) => finite( finite( state.dVCM.add( state.dVC.mul( mis( density ) ) ) ).mul( vc ) );
+
+export const misWeight = ( wLight, wCamera ) => float( 1.0 ).div( float( 1.0 ).add( finite( wLight ) ).add( finite( wCamera ) ) );
+
+// Verification: a view keeps one strategy, MIS-weighted, or alone at full weight (+ STRATEGY_ALONE).
+export const STRATEGY = { ALL: 0, HIT: 1, NEE: 2, CONNECT: 3, LIGHT_TRACE: 4, MERGE: 5 };
+export const STRATEGY_ALONE = 8;
+
+export const strategyWeight = ( view, strategy, weight, alone = float( 1.0 ) ) =>
+	select( view.equal( uint( STRATEGY.ALL ) ).or( view.equal( uint( strategy ) ) ), weight,
+		select( view.equal( uint( strategy + STRATEGY_ALONE ) ), alone, float( 0.0 ) ) );
+
+// Chance a light path leaves this side of a triangle toward `cosToward` (cosine to the winding normal).
+export const emitterSideProbability = ( side, cosToward ) => select( side.equal( int( 2 ) ), float( 0.5 ),
+	select( side.equal( int( 1 ) ), select( cosToward.lessThan( 0.0 ), float( 1.0 ), float( 0.0 ) ),
+		select( cosToward.greaterThan( 0.0 ), float( 1.0 ), float( 0.0 ) ) ) );
+
+/** Area density of a light path's start on a triangle with this emission — power over total, per area. */
+export const emitterAreaPdf = ( emission, totalPower, share = 1 ) =>
+	max( dot( emission, REC709_LUMINANCE_COEFFICIENTS ), 0.0 ).div( max( totalPower, 1e-10 ) ).mul( share );
+
+// The sun as a light subpath start: a direction over its disc, then a point on the scene's bounding disc at `discPdf`
+// (LightGuide.js guidedDiscPdf).
+export const sunEmissionPdf = ( bdpt, sunParams, discPdf ) => bdpt.sunPick.mul( discPdf ).div( max( sunParams.y, 1e-30 ) );
+
+// Where a light subpath starts, in its pick table's order (`sourceCdf`, a running sum); each lamp list follows
+// at `sourceOffsets[ type ]`, by LIGHT_TYPE. A light path's origin code is its triangle, or −1 − its source.
+export const SOURCE = { SUN: 0, EMITTERS: 1, ENVIRONMENT: 2, LAMPS: 3 };
+
+export const sourcePick = ( bdpt, source ) => {
+
+	const s = int( source );
+	return bdpt.sourceCdf.element( s ).sub( select( s.greaterThan( int( 0 ) ), bdpt.sourceCdf.element( max( s.sub( int( 1 ) ), int( 0 ) ) ), float( 0.0 ) ) );
+
+};
+
+export const lampSource = ( bdpt, type, index ) => select( type.equal( int( 0 ) ), int( bdpt.sourceOffsets[ 0 ] ),
+	select( type.equal( int( 1 ) ), int( bdpt.sourceOffsets[ 1 ] ), select( type.equal( int( 2 ) ), int( bdpt.sourceOffsets[ 2 ] ), int( bdpt.sourceOffsets[ 3 ] ) ) ) ).add( index );
+
+export const sourceLampType = ( bdpt, source ) => select( source.lessThan( int( bdpt.sourceOffsets[ 1 ] ) ), int( 0 ),
+	select( source.lessThan( int( bdpt.sourceOffsets[ 2 ] ) ), int( 1 ), select( source.lessThan( int( bdpt.sourceOffsets[ 3 ] ) ), int( 2 ), int( 3 ) ) ) );
+
+export const sourceLampIndex = ( bdpt, source, type ) => source.sub( select( type.equal( int( 0 ) ), int( bdpt.sourceOffsets[ 0 ] ),
+	select( type.equal( int( 1 ) ), int( bdpt.sourceOffsets[ 1 ] ), select( type.equal( int( 2 ) ), int( bdpt.sourceOffsets[ 2 ] ), int( bdpt.sourceOffsets[ 3 ] ) ) ) ) );
+
+// The material at a stored vertex, folded as ShadeKernel folds it; its shading normal is already stored.
+export function resolveSurfaceMaterial( materialIndex, uv, N, materialBuffer ) {
+
+	const material = RayTracingMaterial.wrap( getMaterial( int( materialIndex ), materialBuffer ) ).toVar();
+	material.normalMapIndex.assign( int( - 1 ) );
+	material.bumpMapIndex.assign( int( - 1 ) );
+	material.displacementMapIndex.assign( int( - 1 ) );
+	// Shade leaves diffuse transmission out in this integrator (its strategies do not cross surfaces yet).
+	material.diffuseTransmission.assign( 0.0 );
+
+	const samples = MaterialSamples.wrap( sampleAllMaterialTextures( material, uv, N, vec4( 0.0 ) ) ).toVar();
+	const rawRough = samples.roughness.toVar();
+
+	material.color.assign( samples.albedo );
+	material.metalness.assign( samples.metalness.clamp( 0.0, 1.0 ) );
+	material.roughness.assign( samples.roughness.clamp( MIN_ROUGHNESS, 1.0 ) );
+	material.sheenRoughness.assign( material.sheenRoughness.clamp( 0.05, 1.0 ) );
+
+	const extUV = getTransformedUV( { uv, transform: material.albedoTransform } ).toVar();
+
+	If( material.anisotropyMapIndex.greaterThanEqual( int( 0 ) ), () => {
+
+		const aniso = processAnisotropyMap( material, extUV ).toVar();
+		material.anisotropy.assign( aniso.x );
+		material.anisotropyRotation.assign( aniso.y );
+
+	} );
+
+	const ext = ExtMapResult.wrap( applyExtensionMaps( material, extUV ) ).toVar();
+	material.transmission.assign( ext.transmission );
+	material.clearcoat.assign( ext.clearcoat );
+	material.clearcoatRoughness.assign( ext.clearcoatRoughness );
+	material.sheenColor.assign( ext.sheenColor );
+	material.sheenRoughness.assign( ext.sheenRoughness );
+	material.iridescence.assign( ext.iridescence );
+	material.iridescenceThicknessRange.assign( vec2( material.iridescenceThicknessRange.x, ext.iridescenceThickness ) );
+	material.specularIntensity.assign( ext.specularIntensity );
+	material.specularColor.assign( ext.specularColor );
+
+	If( rawRough.lessThan( MIN_ROUGHNESS ).and( material.anisotropy.equal( 0.0 ) ).and( material.clearcoat.equal( 0.0 ) )
+		.and( material.transmission.equal( 0.0 ) ).and( material.subsurface.equal( 0.0 ) ), () => {
+
+		material.roughness.assign( 0.0 );
+
+	} );
+
+	return material;
+
+}
+
+// The light end's cosine with the shading-normal correction (Veach 5.3.2): |V·N| |d·Ng| / |V·Ng|.
+export const lightEndCosine = ( V, N, facetN, toOther ) =>
+	abs( dot( V, N ) ).mul( abs( dot( toOther, facetN ) ) ).div( max( abs( dot( V, facetN ) ), 1e-4 ) );