rayzee 8.8.2 → 9.1.0

package/src/TSL/LightsSampling.js

@@ -88,6 +88,7 @@ import {
 	sampleEquirectProbability,
 } from './Environment.js';
 import { shadowTerminatorOrigin } from './ShadowTerminator.js';
+import { sunRadianceToward, sampleSunDisc } from './Sun.js';
 
 const TWO_PI = 2.0 * PI;
 
@@ -798,6 +799,8 @@ export const calculateDirectLightingUnified = Fn( ( [
 	// The facet on the viewer's side, which shadow rays are offset off, and the shadow terminator lift
 	// (ShadowTerminator.js) for the light and environment ones
 	terminatorLift, facetNormal, terminatorCutoff,
+	// The physical sky's sun (Sun.js); its BSDF-sampled partner is the miss branch in ShadeKernel.
+	hasSun, sunDirection, sunRadiance, sunParams,
 ] ) => {
 
 	const totalContribution = vec3( 0.0 ).toVar();
@@ -987,55 +990,71 @@ export const calculateDirectLightingUnified = Fn( ( [
 
 	} );
 	// =====================================================================
-	// DETERMINISTIC ENVIRONMENT NEE
-	// Always runs (not stochastic) — forms a two-strategy Veach MIS
-	// estimator together with the implicit miss check in the main loop.
+	// DETERMINISTIC ENVIRONMENT NEE — the map, then the physical sky's sun, each MIS'd with its
+	// partner at the miss. One loop, so the shadow ray and BSDF evaluation are emitted once.
 	// =====================================================================
 
 	If( enableEnvironmentLight, () => {
 
-		const envRandom = getRandomSample2D( pixelCoord, int( 0 ), dimBase.add( int( 1 ) ), rngState, resolution, frame ).toVar();
-		const envColor = vec3( 0.0 ).toVar();
+		const passes = select( hasSun.greaterThan( int( 0 ) ), int( 2 ), int( 1 ) );
+		Loop( { start: int( 0 ), end: passes, type: 'int', condition: '<', name: 'envPass' }, ( { envPass } ) => {
 
-		// Sample direction + PDF + color from importance-sampled environment
-		const envSampleResult = sampleEquirectProbability(
-			envTexture, envCDFTexture,
-			envMatrix, environmentIntensity, envTotalSum, envCompensationDelta, envResolution, envRandom, envColor
-		).toVar();
+			const isSun = envPass.equal( int( 1 ) ).toVar();
+			const radiance = vec3( 0.0 ).toVar();
+			const direction = vec3( 0.0, 1.0, 0.0 ).toVar();
+			const lightPdf = float( 0.0 ).toVar();
 
-		const envDirection = envSampleResult.xyz.toVar();
-		const envPdf = envSampleResult.w.toVar();
+			If( isSun, () => {
 
-		If( envPdf.greaterThan( 0.0 ), () => {
+				const sunXi = getRandomSample2D( pixelCoord, int( 0 ), dimBase.add( int( 9 ) ), rngState, resolution, frame );
+				direction.assign( sampleSunDisc( sunDirection, sunParams, sunXi ) );
+				radiance.assign( sunRadianceToward( direction, sunDirection, sunRadiance, sunParams ).mul( environmentIntensity ) );
+				lightPdf.assign( select( radiance.x.add( radiance.y ).add( radiance.z ).greaterThan( 0.0 ), float( 1.0 ).div( sunParams.y ), float( 0.0 ) ) );
 
-			const NoL = max( float( 0.0 ), dot( hitNormal, envDirection ) ).toVar();
+			} ).Else( () => {
 
-			If( NoL.greaterThan( 0.0 ).and( isDirectionValid( { direction: envDirection, surfaceNormal: geomNormal } ) ), () => {
+				const envRandom = getRandomSample2D( pixelCoord, int( 0 ), dimBase.add( int( 1 ) ), rngState, resolution, frame ).toVar();
+				const envColor = vec3( 0.0 ).toVar();
+				const envSampleResult = sampleEquirectProbability(
+					envTexture, envCDFTexture,
+					envMatrix, environmentIntensity, envTotalSum, envCompensationDelta, envResolution, envRandom, envColor
+				).toVar();
+				direction.assign( envSampleResult.xyz );
+				radiance.assign( envColor );
+				lightPdf.assign( envSampleResult.w );
 
-				const visibility = shadow( lightShadowOrigin( envDirection ), envDirection, float( 1e20 ) );
+			} );
 
-				If( visibility.greaterThan( 0.0 ).or( wantUnoccluded ), () => {
+			If( lightPdf.greaterThan( 0.0 ), () => {
 
-					// Share H + dots between env BRDF/PDF — same redundancy fix as the
-					// discrete-light path above.
-					const envDots = DotProducts.wrap( computeDotProductsAniso( hitNormal, viewDir, envDirection, material ) );
-					const brdfValue = evaluateMaterialResponseFromDots( material, envDots );
-					const bPdf = calculateMaterialPDFFromDots( material, envDots ).toVar();
-
-					// Balance heuristic for env MIS — optimal for MIS-compensated PDFs (Karlík et al. 2019).
-					// The implicit path uses material combinedPdf as prevBouncePdf at the miss check.
-					const misW = select(
-						bPdf.greaterThan( 0.0 ),
-						balanceHeuristic( { pdf1: envPdf, pdf2: bPdf } ),
-						float( 1.0 )
-					).toVar();
-
-					// Base contribution WITHOUT visibility (deterministic estimator; no stochastic scaling).
-					const baseContribution = envColor.mul( brdfValue ).mul( NoL ).mul( misW ).div( max( envPdf, 1e-10 ) );
-					totalContribution.addAssign( baseContribution.mul( visibility ) );
-					If( wantUnoccluded, () => {
+				const NoL = max( float( 0.0 ), dot( hitNormal, direction ) ).toVar();
 
-						unoccludedContribution.addAssign( baseContribution );
+				If( NoL.greaterThan( 0.0 ).and( isDirectionValid( { direction, surfaceNormal: geomNormal } ) ), () => {
+
+					const visibility = shadow( lightShadowOrigin( direction ), direction, float( 1e20 ) );
+
+					If( visibility.greaterThan( 0.0 ).or( wantUnoccluded ), () => {
+
+						const envDots = DotProducts.wrap( computeDotProductsAniso( hitNormal, viewDir, direction, material ) );
+						const brdfValue = evaluateMaterialResponseFromDots( material, envDots );
+						const bPdf = calculateMaterialPDFFromDots( material, envDots ).toVar();
+
+						// The map pairs with the balance heuristic — optimal for its MIS-compensated pdf
+						// (Karlík et al. 2019); the sun, a small bright source, with the power heuristic.
+						const misW = select(
+							bPdf.greaterThan( 0.0 ),
+							select( isSun, powerHeuristic( { pdf1: lightPdf, pdf2: bPdf } ), balanceHeuristic( { pdf1: lightPdf, pdf2: bPdf } ) ),
+							float( 1.0 )
+						).toVar();
+
+						// Base contribution WITHOUT visibility (deterministic estimator; no stochastic scaling).
+						const baseContribution = radiance.mul( brdfValue ).mul( NoL ).mul( misW ).div( max( lightPdf, 1e-10 ) );
+						totalContribution.addAssign( baseContribution.mul( visibility ) );
+						If( wantUnoccluded, () => {
+
+							unoccludedContribution.addAssign( baseContribution );
+
+						} );
 
 					} );
 
@@ -1047,7 +1066,6 @@ export const calculateDirectLightingUnified = Fn( ( [
 
 	} );
 
-
 	// EMISSIVE TRIANGLE DIRECT LIGHTING
 	// NOTE: Emissive triangle sampling is handled separately in pathtracer_core.fs
 	// to bypass firefly suppression. Do not add it here to avoid double-counting.

package/src/TSL/Random.js

@@ -132,6 +132,7 @@ export const RandomPointInCircle = ( rngState ) => {
 //       +6  subsurface HG scatter dir    (ShadeKernel)
 //       +7  ground-catcher cosine BSDF   (ShadeKernel)
 //       +8  indirect-strategy direction  (LightsIndirect)
+//       +9  physical-sky sun disc        (LightsSampling)
 //   1D  +0  (free — was the {lights,BRDF} stochastic strategy pick)
 //       +1  emissive-triangle pick       (EmissiveSampling / LightBVHSampling)
 //       +2  BSDF lobe selection          (ShadeKernel)

package/src/TSL/ShadeKernel.js

@@ -1,13 +1,13 @@
 /**
  * ShadeKernel.js — wavefront material eval + bounce generation. 256×1 workgroup, 1D dispatch.
- * 10 storage-buffer bindings: bvh, tri, mat, light, ray, rng, hit, gBuffer, counters, activeIndices
- * (at the device per-stage limit of 10; envCDF is a texture, not a storage buffer).
+ * 10 storage-buffer bindings: bvh, triGeo, triShade, mat, light, ray, hit (+ RNG state), gBuffer,
+ * counters, activeIndices (at the device per-stage limit of 10; envCDF is a texture, not a storage buffer).
  */
 
 import {
 	Fn, float, vec2, vec3, vec4, int, uint,
 	bool as tslBool,
-	If, Loop, normalize, max, min, exp, log, clamp, dot, length, select, smoothstep,
+	If, Loop, normalize, max, min, exp, log, clamp, dot, length, select, smoothstep, acos,
 	instanceIndex,
 	sampler,
 	atomicAdd, atomicLoad, atomicStore, uintBitsToFloat,
@@ -28,6 +28,7 @@ import { handleMaterialTransparency, MaterialInteractionResult } from './Materia
 import { sampleChromaticCollision, sampleHenyeyGreenstein, subsurfaceCoefficients, CollisionSample, MediumCoeffs } from './Subsurface.js';
 import { calculateIndirectLighting } from './LightsIndirect.js';
 import { IndirectLightingResult, sampleCone } from './LightsCore.js';
+import { sunRadianceToward } from './Sun.js';
 import { regularizePathContribution, generateSampledDirection, computeNDCDepth, handleRussianRoulette } from './PathTracerCore.js';
 import { evaluateSpecularDFG, baseFresnelParams } from './MaterialProperties.js';
 import { NRD_HIT_DIST_A, NRD_HIT_DIST_B } from '../EngineDefaults.js';
@@ -63,6 +64,7 @@ import {
 	writeGBuffer, writeGBufferHitDist, readGBuffer, gbDecodeNormalDepth,
 	readRayRadiance,
 	readFeatureThroughput, writeFeatureThroughput,
+	readRngState, writeRngState,
 } from '../Processor/PackedRayBuffer.js';
 
 const WG_SIZE = 256;
@@ -79,7 +81,7 @@ export function buildShadeKernel( params ) {
 		bvhBuffer, triangleBuffer, materialBuffer,
 		envCDFTexture,
 		lightBuffer,
-		rayBufferRW, rngBufferRW, hitBufferRO, gBufferRW,
+		rayBufferRW, hitBufferRW, gBufferRW,
 		counters,
 		activeIndicesRO,
 		envTexture, environmentIntensity, envMatrix,
@@ -111,6 +113,7 @@ export function buildShadeKernel( params ) {
 		// Aux G-buffer (normal/depth/albedo + surface ID) feeds only the denoiser/OIDN MRT. Gated by a
 		// live uniform (1 = denoiser on) so the wavefront skips these writes when nothing consumes them.
 		auxGBufferEnabled,
+		hasSun, sunDirection, sunRadiance, sunParams,
 	} = params;
 
 	const auxOn = auxGBufferEnabled.greaterThan( uint( 0 ) );
@@ -196,7 +199,7 @@ export function buildShadeKernel( params ) {
 		const currentRadiance = readRayRadiance( rayBufferRW, rayID ).toVar();
 		// One ray per pixel: rayID is the pixel index.
 		const pixelIndex = rayID;
-		const rngState = rngBufferRW.element( rayID ).toVar();
+		const rngState = readRngState( hitBufferRW, rayID ).toVar();
 
 		// STBN keyed on (GLOBAL pixel, dimension, frame). pixelIndex is the LOCAL path slot; the global pixel
 		// = chunkRowBase·W + localSlot, so the blue-noise pattern stays spatially aligned across row-band chunks
@@ -216,13 +219,13 @@ export function buildShadeKernel( params ) {
 		// deferring continue (a missed persist = stale tint). 1 = untinted (direct hit → today's albedo).
 		const featCarry = readFeatureThroughput( rayBufferRW, rayID ).toVar();
 
-		const hitDist = readHitDistance( hitBufferRO, rayID ).toVar();
-		const hitNormal = readHitNormal( hitBufferRO, rayID ).toVar();
+		const hitDist = readHitDistance( hitBufferRW, rayID ).toVar();
+		const hitNormal = readHitNormal( hitBufferRW, rayID ).toVar();
 		// hitInfo.uv is the interpolated texture UV (not barycentrics)
-		const hitUV = readHitBarycentrics( hitBufferRO, rayID ).toVar();
-		const hitMatIdx = readHitMaterialIndex( hitBufferRO, rayID ).toVar();
-		const hitTriIdx = readHitTriangleIndex( hitBufferRO, rayID ).toVar();
-		const hitInstance = readHitInstanceLeaf( hitBufferRO, rayID ).toVar();
+		const hitUV = readHitBarycentrics( hitBufferRW, rayID ).toVar();
+		const hitMatIdx = readHitMaterialIndex( hitBufferRW, rayID ).toVar();
+		const hitTriIdx = readHitTriangleIndex( hitBufferRW, rayID ).toVar();
+		const hitInstance = readHitInstanceLeaf( hitBufferRW, rayID ).toVar();
 
 		// per-ray camera-bounce depth — advances ONLY on opaque scatter (free bounces don't); drives termination (maxBounces). Megakernel: effectiveBounces.
 		const cameraDepth = readPathBounces( rayBufferRW, rayID ).toVar();
@@ -287,6 +290,7 @@ export function buildShadeKernel( params ) {
 						enableEnvironmentLight,
 						tslBool( true ), // wantUnoccluded
 						vec3( 0.0 ), planeN, float( 0.0 ),
+						hasSun, sunDirection, sunRadiance, sunParams,
 					) ).toVar();
 
 					const lumShad = max( dot( dual.shadowed, REC709_LUMINANCE_COEFFICIENTS ), float( 0.0 ) );
@@ -357,7 +361,7 @@ export function buildShadeKernel( params ) {
 					writeRayRadiance( rayBufferRW, rayID, vec4( outRgb, outAlpha ) );
 					// DDFA: the plane's aux (written above) is a committed surface — lock it (cosmetic; ray dies here).
 					writeRayDirFlags( rayBufferRW, rayID, direction, flags.bitOr( uint( RAY_FLAG.AUX_LOCKED ) ).bitAnd( uint( ~ RAY_FLAG.ACTIVE ) ) );
-					rngBufferRW.element( rayID ).assign( rngState );
+					writeRngState( hitBufferRW, rayID, rngState );
 					Return();
 
 				} );
@@ -469,6 +473,53 @@ export function buildShadeKernel( params ) {
 					currentRadiance.w
 				) );
 
+				// The sun disc; on a redirected ray, the partner of the sending vertex's sun NEE. A blurred
+				// backdrop gets a smooth falloff: a hard-edged cone reads as a white coin.
+				If( hasSun, () => {
+
+					const sunL = vec3( 0.0 ).toVar();
+					If( isBackdropView.and( backgroundBlurriness.greaterThan( 0.0 ) ), () => {
+
+						const blurAngle = backgroundBlurriness.mul( 1.3 ).toVar();
+						const angle = acos( clamp( dot( normalize( envDir ), sunDirection ), - 1.0, 1.0 ) );
+						If( angle.lessThan( blurAngle ), () => {
+
+							const falloff = float( 1.0 ).sub( angle.div( blurAngle ).pow( 2 ) ).pow( 2 );
+							// ∫ falloff dΩ = π θb² / 3 for a small cone.
+							sunL.assign( sunRadiance.mul( environmentIntensity ).mul( sunParams.y ).mul( falloff ).mul( 3 / Math.PI ).div( blurAngle.mul( blurAngle ) ) );
+
+						} );
+
+					} ).Else( () => {
+
+						sunL.assign( sunRadianceToward( normalize( envDir ), sunDirection, sunRadiance, sunParams ).mul( environmentIntensity ) );
+
+					} );
+					If( sunL.x.add( sunL.y ).add( sunL.z ).greaterThan( 0.0 ), () => {
+
+						const sunW = float( 1.0 ).toVar();
+						If( isBackdropView.not().and( flags.bitAnd( uint( RAY_FLAG.SUN_NEE ) ).notEqual( uint( 0 ) ) ), () => {
+
+							sunW.assign( powerHeuristic( { pdf1: readRayPdf( rayBufferRW, rayID ), pdf2: float( 1.0 ).div( sunParams.y ) } ) );
+
+						} );
+						const vertex = max( bounceIndex.sub( 1 ), int( 0 ) );
+						const sunScale = select( isBackdropView, backgroundIntensity,
+							sunW.mul( select( vertex.greaterThan( int( 0 ) ), globalIlluminationIntensity, float( 1.0 ) ) ) );
+						currentRadiance.assign( vec4(
+							currentRadiance.xyz.add(
+								regularizePathContribution(
+									throughput.mul( sunL ).mul( sunScale ),
+									select( isBackdropView, float( 0.0 ), float( vertex ) ), fireflyThreshold, int( accumFrame ),
+								),
+							),
+							currentRadiance.w
+						) );
+
+					} );
+
+				} );
+
 			} );
 
 			// Solid-color backdrop ('color' mode): a primary ray that doesn't show the env image and isn't
@@ -577,7 +628,7 @@ export function buildShadeKernel( params ) {
 
 						writeRayRadiance( rayBufferRW, rayID, currentRadiance );
 						writeRayDirFlags( rayBufferRW, rayID, direction, flags.bitAnd( uint( ~ RAY_FLAG.ACTIVE ) ) );
-						rngBufferRW.element( rayID ).assign( rngState );
+						writeRngState( hitBufferRW, rayID, rngState );
 						Return();
 
 					} );
@@ -594,7 +645,7 @@ export function buildShadeKernel( params ) {
 					// fires the next hit's env/emissive MIS, down-weighting SSS-then-env/emitter views.
 					writeRayThroughputPdf( rayBufferRW, rayID, throughput, readRayPdf( rayBufferRW, rayID ) );
 					writeRayRadiance( rayBufferRW, rayID, currentRadiance );
-					rngBufferRW.element( rayID ).assign( rngState );
+					writeRngState( hitBufferRW, rayID, rngState );
 					Return();
 
 				} );
@@ -735,7 +786,7 @@ export function buildShadeKernel( params ) {
 
 			writeRayRadiance( rayBufferRW, rayID, currentRadiance );
 			writeRayDirFlags( rayBufferRW, rayID, direction, flags.bitAnd( uint( ~ RAY_FLAG.ACTIVE ) ) );
-			rngBufferRW.element( rayID ).assign( rngState );
+			writeRngState( hitBufferRW, rayID, rngState );
 
 		};
 
@@ -935,7 +986,7 @@ export function buildShadeKernel( params ) {
 			throughput.mulAssign( interaction.throughput );
 
 			// Off the side of the facet the new ray leaves on: reflection stays, transmission and alpha skip cross.
-			const Ng = unpackHitFacet( readHitFacet( hitBufferRO, rayID ) ).faceN;
+			const Ng = unpackHitFacet( readHitFacet( hitBufferRW, rayID ) ).faceN;
 			const newOrigin = offsetRayOrigin( hitPoint, select( dot( Ng, interaction.direction ).lessThan( 0.0 ), Ng.negate(), Ng ) );
 
 			// SSS = free bounce (depth unchanged); transmission advances camera-bounce depth.
@@ -979,7 +1030,7 @@ export function buildShadeKernel( params ) {
 				writeFeatureThroughput( rayBufferRW, rayID, featCarry );
 
 			} );
-			rngBufferRW.element( rayID ).assign( rngState );
+			writeRngState( hitBufferRW, rayID, rngState );
 			Return();
 
 		} );
@@ -1066,7 +1117,7 @@ export function buildShadeKernel( params ) {
 		const Ngeo = normalize( hitNormal );
 		const NgeoFF = select( dot( Ngeo, V ).lessThan( 0.0 ), Ngeo.negate(), Ngeo ).toVar();
 		// The facet on the viewer's side: every ray spawned from here is offset off it (HitFacet.js).
-		const facet = unpackHitFacet( readHitFacet( hitBufferRO, rayID ) );
+		const facet = unpackHitFacet( readHitFacet( hitBufferRW, rayID ) );
 		const facetN = facet.faceN.toVar();
 		const terminatorLift = Ngeo.mul( facet.liftScale );
 		const lightShadowOrigin = L => shadowTerminatorOrigin( {
@@ -1188,6 +1239,7 @@ export function buildShadeKernel( params ) {
 			enableEnvironmentLight,
 			tslBool( false ), // wantUnoccluded: false on real surfaces — dead-codes the unoccluded sum
 			terminatorLift, facetN, shadowTerminatorOffset,
+			hasSun, sunDirection, sunRadiance, sunParams,
 		) ).shadowed.toVar();
 
 		const giScale = select( bounceIndex.greaterThan( 0 ), globalIlluminationIntensity, float( 1.0 ) );
@@ -1367,6 +1419,10 @@ export function buildShadeKernel( params ) {
 
 		const newOrigin = offsetRayOrigin( hitPoint, select( dot( facetN, bounceDir ).lessThan( 0.0 ), facetN.negate(), facetN ) );
 
+		// Whether this vertex's sun NEE could have drawn bounceDir, so a sun hit at the miss knows its MIS partner.
+		const sunNEE = brdfIsTransmission.not().and( dot( N, bounceDir ).greaterThan( 0.0 ) );
+		flags.assign( flags.sub( flags.bitAnd( uint( RAY_FLAG.SUN_NEE ) ) ).bitOr( select( sunNEE, uint( RAY_FLAG.SUN_NEE ), uint( 0 ) ) ) );
+
 		// Opaque scatter: the only bounce that advances camera depth.
 		writeRayOriginMeta( rayBufferRW, rayID, newOrigin, cameraDepth.add( 1 ), sssSteps, transparentCount );
 		writeRayDirFlags( rayBufferRW, rayID, bounceDir, flags );
@@ -1379,7 +1435,7 @@ export function buildShadeKernel( params ) {
 			writeFeatureThroughput( rayBufferRW, rayID, featCarry );
 
 		} );
-		rngBufferRW.element( rayID ).assign( rngState );
+		writeRngState( hitBufferRW, rayID, rngState );
 
 	} );
 

package/src/TSL/Sun.js

@@ -0,0 +1,40 @@
+import { Fn, float, vec3, sqrt, max, dot, cross, pow, cos, sin, abs, normalize, select, If } from 'three/tsl';
+
+import { LIMB_DARKENING_EXPONENT } from '../Processor/AtmosphereModel.js';
+
+const LIMB_EXPONENT = vec3( ...LIMB_DARKENING_EXPONENT );
+// µ^α averages to 2 / (α + 2) over the disc, so this keeps the mean at `sunRadiance`.
+const LIMB_NORM = vec3( ...LIMB_DARKENING_EXPONENT.map( a => ( a + 2 ) / 2 ) );
+
+/**
+ * Radiance the physical sky's sun sends along `dir`: limb darkened, and nothing below the sky's
+ * horizon. `sunParams` = ( cos half-angle, solid angle, 1 / sin² half-angle, horizon dip sin ).
+ */
+export const sunRadianceToward = /*@__PURE__*/ Fn( ( [ dir, sunDirection, sunRadiance, sunParams ] ) => {
+
+	const out = vec3( 0 ).toVar();
+	If( dot( dir, sunDirection ).greaterThanEqual( sunParams.x ).and( dir.y.greaterThanEqual( sunParams.w.negate() ) ), () => {
+
+		const c = cross( dir, sunDirection );
+		const mu = sqrt( max( float( 1 ).sub( dot( c, c ).mul( sunParams.z ) ), 1e-8 ) );
+		out.assign( sunRadiance.mul( pow( vec3( mu ), LIMB_EXPONENT ) ).mul( LIMB_NORM ) );
+
+	} );
+	return out;
+
+} );
+
+/** A direction uniform in solid angle over the sun disc. */
+export const sampleSunDisc = /*@__PURE__*/ Fn( ( [ sunDirection, sunParams, xi ] ) => {
+
+	// 1 − cosθ straight from the solid angle: 1 − cos(half-angle) cancels to nothing in f32.
+	const oneMinusCos = xi.x.mul( sunParams.y.mul( 1 / ( 2 * Math.PI ) ) );
+	const cosT = float( 1 ).sub( oneMinusCos );
+	const sinT = sqrt( max( oneMinusCos.mul( float( 2 ).sub( oneMinusCos ) ), 0 ) );
+	const phi = xi.y.mul( 2 * Math.PI );
+	const w = sunDirection;
+	const u = normalize( cross( select( abs( w.x ).greaterThan( 0.9 ), vec3( 0, 1, 0 ), vec3( 1, 0, 0 ) ), w ) );
+	const v = cross( w, u );
+	return normalize( w.mul( cosT ).add( u.mul( cos( phi ) ).add( v.mul( sin( phi ) ) ).mul( sinT ) ) );
+
+} );

package/src/TSL/TextureSampling.js

@@ -6,7 +6,7 @@ import {
 	MaterialSamples,
 	ExtMapResult,
 } from './Struct.js';
-import { getDatafromStorageBuffer, instanceRows, instanceDirToWorld, TRI_STRIDE } from './Common.js';
+import { instanceRows, instanceDirToWorld, triangleRow } from './Common.js';
 import { TEXTURE_CONSTANTS } from '../EngineDefaults.js';
 
 // ================================================================================
@@ -414,13 +414,12 @@ const uvTransformJacobian = /*@__PURE__*/ wgslFn( `
  */
 export const triangleUVTangent = Fn( ( [ triangleBuffer, triIndex, geometryNormal, transform, bvhBuffer, instanceLeaf ] ) => {
 
-	const S = int( TRI_STRIDE );
-	const pA = uintBitsToFloat( getDatafromStorageBuffer( triangleBuffer, triIndex, int( 0 ), S ).xyz );
-	const e1 = uintBitsToFloat( getDatafromStorageBuffer( triangleBuffer, triIndex, int( 1 ), S ).xyz ).sub( pA );
-	const e2 = uintBitsToFloat( getDatafromStorageBuffer( triangleBuffer, triIndex, int( 2 ), S ).xyz ).sub( pA );
+	const pA = uintBitsToFloat( triangleRow( triangleBuffer, triIndex, 0 ).xyz );
+	const e1 = uintBitsToFloat( triangleRow( triangleBuffer, triIndex, 1 ).xyz ).sub( pA );
+	const e2 = uintBitsToFloat( triangleRow( triangleBuffer, triIndex, 2 ).xyz ).sub( pA );
 
-	const uvAB = uintBitsToFloat( getDatafromStorageBuffer( triangleBuffer, triIndex, int( 3 ), S ) );
-	const uvC = uintBitsToFloat( getDatafromStorageBuffer( triangleBuffer, triIndex, int( 4 ), S ).xy );
+	const uvAB = uintBitsToFloat( triangleRow( triangleBuffer, triIndex, 3 ) );
+	const uvC = uintBitsToFloat( triangleRow( triangleBuffer, triIndex, 4 ).xy );
 	const d1 = uvAB.zw.sub( uvAB.xy );
 	const d2 = uvC.sub( uvAB.xy );
 

package/src/index.js

@@ -26,6 +26,22 @@ export { SETTING_SOURCE } from './RenderSettings.js';
 // Asset URL / cache namespace overrides (call before constructing PathTracerApp)
 export { configureAssets, getAssetConfig } from './AssetConfig.js';
 
+// On-disk storage (origin private file system): caches, and areas a host defines for its own data
+export {
+	openStorage, StorageManager, STORAGE_KIND, ENGINE_AREAS, fileIdentity, identityKey, sameIdentity,
+	DownloadCache, DOWNLOAD_POLICY, fetchFile, nameFromUrl, cachedObjectURL, acquireLock, heldLockNames,
+} from './Storage/index.js';
+
+// Archives read in place: one entry at a time, never the whole file in memory
+export { openZip, readZipDirectory } from './Processor/ZipReader.js';
+
+// Engine package version, as built
+export { VERSION } from './version.js';
+
+// A loaded scene's edits as plain data (app.exportSceneState / importSceneState)
+export { SCENE_STATE_VERSION } from './SceneState/SceneState.js';
+export { toPortable, fromPortable } from './SceneState/portable.js';
+
 // glTF alphaMode derivation — the one definition, shared with hosts that edit materials
 export { deriveAlphaMode, MATERIAL_VALUE_SOURCE } from './Processor/GeometryExtractor.js';
 
@@ -47,6 +63,7 @@ export {
 	CAMERA_PRESETS,
 	CAMERA_RANGES,
 	SKY_PRESETS,
+	DEFAULT_SUN_PATH,
 	AUTO_FOCUS_MODES,
 	AF_DEFAULTS,
 	TRIANGLE_DATA_LAYOUT,
@@ -61,6 +78,7 @@ export {
 	RENDER_PROFILES,
 	getRenderProfile,
 } from './EngineDefaults.js';
+export { sunPosition, timeForSunElevation, dayOfYearForMonth } from './Processor/SunPosition.js';
 
 // Settings & managers (for advanced consumers)
 export { RenderSettings } from './RenderSettings.js';
@@ -96,6 +114,10 @@ export { TransformManager } from './managers/TransformManager.js';
 // Video rendering
 export { VideoRenderManager } from './managers/VideoRenderManager.js';
 
+// Authored animation: keyframed tracks on one timeline (engine.timeline)
+export { TimelineManager } from './managers/timeline/TimelineManager.js';
+export { CameraTrack } from './managers/timeline/CameraTrack.js';
+
 // Interaction
 export { InteractionManager } from './managers/InteractionManager.js';