rayzee 9.2.1 → 9.3.0

package/package.json

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

package/src/Processor/QueueManager.js

@@ -51,6 +51,7 @@ export const RAY_FLAG = {
 	AUX_LOCKED: 1 << 17, // bit 17: OIDN aux (normal/albedo) locked onto first non-specular hit (megakernel auxLocked)
 	REDIRECTED: 1 << 18, // bit 18: ray has been redirected (refraction/reflection/SSS/opaque scatter) since the camera, so env it reaches is transported light (sharp), NOT the direct backdrop. NOT set by pure alpha/transparent passthrough (direction unchanged) → env through cutout holes is still the backdrop (blur/intensity/show/color/ground-projection). Set via bitOr only (positive mask) so it never disturbs ACTIVE/bounce bits.
 	SUN_NEE: 1 << 19, // bit 19: the last opaque scatter's sun NEE could have drawn this direction (MIS partner for a sun hit on miss)
+	UNDER_SURFACE: 1 << 20, // bit 20: the last opaque scatter left below its own facet (shading normal allowed it), so the ray culls back faces to leave that shell
 };
 
 export class QueueManager {

package/src/TSL/BVHTraversal.js

@@ -212,8 +212,14 @@ const fastRayAABBDst = wgslFn( `
 // ================================================================================
 // MAIN BVH TRAVERSAL
 // ================================================================================
-// Side culling is performed inline inside traverseBVH/traverseBVHShadow using
-// the per-triangle side flag stored in normalCData.w (slot 5, .w channel).
+
+// Side from a triangle's flags word (row 4 .z): 0 front, 1 back, 2 double.
+export const triangleSide = ( flags ) => int( flags.shiftRight( uint( TRI_SIDE_SHIFT ) ).bitAnd( uint( 3 ) ) );
+
+// Whether a face of this side is seen by a ray; rayDotNormal < 0 is a front hit.
+export const sideAccepts = ( side, rayDotNormal ) => side.equal( int( 2 ) )
+	.or( side.equal( int( 0 ) ).and( rayDotNormal.lessThan( - 0.0001 ) ) )
+	.or( side.equal( int( 1 ) ).and( rayDotNormal.greaterThan( 0.0001 ) ) );
 
 // Factory: the boxTests/triTests debug counters are compiled OUT of the hot closest-hit
 // path (extend/normalDepth use traverseBVH = trackStats false) — only the debug viz reads
@@ -223,11 +229,11 @@ const makeTraverseBVH = ( trackStats ) => Fn( ( [
 	bvhBuffer,
 	triangleBuffer,
 	insideMedium, // optional: when true (ray inside a medium), bypass front/back culling
+	cullBackFaces, // optional, default true: false hits either side, as shadow rays do
 ] ) => {
 
-	// Interior medium rays (SSS/transmission) must be able to hit boundary faces from
-	// either side to find the exit; exterior rays honor the authored side as before.
-	const inMedium = insideMedium ?? tslBool( false );
+	// Culling is for what the camera sees through; a bounce culling it leaks light through hollow models.
+	const eitherSide = ( insideMedium ?? tslBool( false ) ).or( ( cullBackFaces ?? tslBool( true ) ).not() ).toVar();
 
 	// Folded leaves cost up to 4 % of traversal, so only a BVH built with them gets that code.
 	const folded = bvhBuffer.value?.foldedLeaves === true;
@@ -308,8 +314,7 @@ const makeTraverseBVH = ( trackStats ) => Fn( ( [
 				const nA = unpackTriangleNormal( recA.w );
 				const nB = unpackTriangleNormal( recB.w );
 				const nC = unpackTriangleNormal( recC.w );
-				const flags = triangleRow( triangleBuffer, triIndex, 4 ).z;
-				const side = int( flags.shiftRight( uint( TRI_SIDE_SHIFT ) ).bitAnd( uint( 3 ) ) ).toVar();
+				const side = triangleSide( triangleRow( triangleBuffer, triIndex, 4 ).z ).toVar();
 
 				// Interpolate normal for the side-culling dot product (kept local,
 				// not stored on closestHit — re-derived post-loop from closestTriIdx).
@@ -319,11 +324,7 @@ const makeTraverseBVH = ( trackStats ) => Fn( ( [
 				);
 
 				// Side culling (inline; per-mesh visibility is at the BLAS-pointer level).
-				// 0=front (reject back-facing), 1=back (reject front-facing), 2=double (pass).
-				const sidePass = inMedium.or( side.equal( int( 2 ) ) )
-					.or( side.equal( int( 0 ) ).and( rayDotNormal.lessThan( - 0.0001 ) ) )
-					.or( side.equal( int( 1 ) ).and( rayDotNormal.greaterThan( 0.0001 ) ) );
-				If( sidePass, () => {
+				If( eitherSide.or( sideAccepts( side, rayDotNormal ) ), () => {
 
 					closestHit.didHit.assign( true );
 					closestHit.dst.assign( t );

package/src/TSL/Debugger.js

@@ -18,6 +18,7 @@ import {
 	If,
 	select,
 	sampler,
+	bool as tslBool,
 } from 'three/tsl';
 
 import { Ray, HitInfo, RayTracingMaterial, MaterialSamples } from './Struct.js';
@@ -343,6 +344,8 @@ export const TraceDebugMode = Fn( ( [
 				bounceRay,
 				bvhBuffer,
 				triangleBuffer,
+				tslBool( false ),
+				tslBool( false ),
 			).toVar() );
 
 			const incoming = vec3( 0.0 ).toVar();

package/src/TSL/ExtendKernel.js

@@ -49,7 +49,8 @@ export function buildExtendKernel( params ) {
 
 		// Parity with Shade's guard. Free — the flags share DIR_FLAGS.w with the direction read below.
 		// Only culls work on the pinned-dispatch path, whose identity list still holds dead rays.
-		If( readRayBounceFlags( rayBufferRO, rayID ).bitAnd( uint( RAY_FLAG.ACTIVE ) ).equal( uint( 0 ) ), () => {
+		const flags = readRayBounceFlags( rayBufferRO, rayID ).toVar();
+		If( flags.bitAnd( uint( RAY_FLAG.ACTIVE ) ).equal( uint( 0 ) ), () => {
 
 			Return();
 
@@ -62,8 +63,11 @@ export function buildExtendKernel( params ) {
 
 		// insideMedium bypasses front/back culling so the ray can hit a glass/SSS back-facing boundary.
 		const insideMedium = readMediumStack( rayBufferRO, rayID ).stackDepth.greaterThan( uint( 0 ) );
+		// Only the camera's own view culls back faces, and a bounce that dipped under its surface.
+		const cull = flags.bitAnd( uint( RAY_FLAG.REDIRECTED ) ).equal( uint( 0 ) )
+			.or( flags.bitAnd( uint( RAY_FLAG.UNDER_SURFACE ) ).notEqual( uint( 0 ) ) );
 		const hitInfo = HitInfo.wrap( traverseBVH(
-			ray, bvhBuffer, triangleBuffer, insideMedium,
+			ray, bvhBuffer, triangleBuffer, insideMedium, cull,
 		) ).toVar();
 
 		const facet = hitFacet( {

package/src/TSL/MaterialEvaluation.js

@@ -24,7 +24,9 @@ import { evalIridescence } from './MaterialProperties.js';
 // Body of evaluateMaterialResponse taking precomputed dot products. Callers
 // that also need calculateMaterialPDF for the same (V, L, N) should share dots
 // to save one computeDotProducts call.
-export const evaluateMaterialResponseFromDots = Fn( ( [ material, dots ] ) => {
+// Roughness 0 marks an exact mirror (ShadeKernel): its delta lobe is left out of this BSDF, and
+// deltaOnly returns that lobe's reflectance instead, under the same sheen and coat attenuation.
+const makeEvaluateMaterialResponse = ( deltaOnly ) => Fn( ( [ material, dots ] ) => {
 
 	const result = vec3( 0.0 ).toVar();
 
@@ -92,7 +94,7 @@ export const evaluateMaterialResponseFromDots = Fn( ( [ material, dots ] ) => {
 			const Va = VisibilityGGXAniso( a.x, a.y, dots.ToV, dots.BoV, dots.ToL, dots.BoL, dots.NoV, dots.NoL );
 			specularSS.assign( F.mul( Da.mul( Va ) ) );
 
-		} ).Else( () => {
+		} ).ElseIf( material.roughness.greaterThan( 0.0 ), () => {
 
 			const D = DistributionGGX( dots.NoH, material.roughness );
 			const Vis = VisibilityGGXSmithCorrelated( dots.NoV, dots.NoL, material.roughness );
@@ -105,7 +107,7 @@ export const evaluateMaterialResponseFromDots = Fn( ( [ material, dots ] ) => {
 			bf.f0, bf.f90, bf.eta, bf.F0m, material.metalness, iridF, material.iridescence, F0,
 			dots.NoV, material.roughness,
 		) );
-		const specular = specularSS.mul( dfg.compensation );
+		const specular = ( deltaOnly ? F : specularSS ).mul( dfg.compensation );
 
 		// Diffuse energy budget from hemisphere-integrated specular albedo (includes multiscatter)
 		// Transmission removes energy from diffuse just as metalness does — KHR_materials_transmission
@@ -113,7 +115,7 @@ export const evaluateMaterialResponseFromDots = Fn( ( [ material, dots ] ) => {
 		const kD = vec3( 1.0 ).sub( dfg.E_total )
 			.mul( float( 1.0 ).sub( material.metalness ) )
 			.mul( float( 1.0 ).sub( material.transmission ) );
-		const diffuse = kD.mul( materialColor ).mul( PI_INV );
+		const diffuse = deltaOnly ? vec3( 0.0 ) : kD.mul( materialColor ).mul( PI_INV );
 
 		const baseLayer = diffuse.add( specular ).toVar();
 
@@ -131,7 +133,7 @@ export const evaluateMaterialResponseFromDots = Fn( ( [ material, dots ] ) => {
 			const sheenReflectance = clamp( material.sheenColor.mul( material.sheen ).mul( sheenE ), vec3( 0.0 ), vec3( 1.0 ) );
 			const sheenAttenuation = vec3( 1.0 ).sub( sheenReflectance );
 
-			result.assign( baseLayer.mul( sheenAttenuation ).add( sheenTerm ) );
+			result.assign( deltaOnly ? baseLayer.mul( sheenAttenuation ) : baseLayer.mul( sheenAttenuation ).add( sheenTerm ) );
 
 		} ).Else( () => {
 
@@ -161,7 +163,7 @@ export const evaluateMaterialResponseFromDots = Fn( ( [ material, dots ] ) => {
 
 			const ccAttenuation = vec3( 1.0 ).sub( ccDfg.E_total.mul( material.clearcoat ) );
 
-			result.assign( result.mul( ccAttenuation ).add( ccLobe.mul( material.clearcoat ) ) );
+			result.assign( deltaOnly ? result.mul( ccAttenuation ) : result.mul( ccAttenuation ).add( ccLobe.mul( material.clearcoat ) ) );
 
 		} );
 
@@ -171,6 +173,9 @@ export const evaluateMaterialResponseFromDots = Fn( ( [ material, dots ] ) => {
 
 } );
 
+export const evaluateMaterialResponseFromDots = /*@__PURE__*/ makeEvaluateMaterialResponse( false );
+export const evaluateSpecularDeltaFromDots = /*@__PURE__*/ makeEvaluateMaterialResponse( true );
+
 // Wrapper that computes dot products internally. Use this when you don't already
 // have dots; otherwise prefer evaluateMaterialResponseFromDots to share the work.
 export const evaluateMaterialResponse = Fn( ( [ V, L, N, material ] ) => {

package/src/TSL/PathTracerCore.js

@@ -46,7 +46,7 @@ import {
 	calculateBRDFWeights,
 	sheenSamplingRoughness,
 } from './MaterialProperties.js';
-import { evaluateMaterialResponseFromDots } from './MaterialEvaluation.js';
+import { evaluateMaterialResponseFromDots, evaluateSpecularDeltaFromDots } from './MaterialEvaluation.js';
 
 import {
 	ImportanceSampleCosine,
@@ -59,6 +59,9 @@ import {
 // BRDF Direction Sampling
 // =============================================================================
 
+// Stand-in density for a delta (exact mirror) sample; squared in the power heuristic, so it stays f32-safe.
+export const DELTA_PDF = 1e6;
+
 export const generateSampledDirection = Fn( ( [
 	V, N, material, xi, lobeXi, rngState,
 	pixelCoord, resolution, frame, dimBase,
@@ -75,6 +78,7 @@ export const generateSampledDirection = Fn( ( [
 	const resultPdf = float( 0.0 ).toVar();
 	const resultIsTransmission = tslBool( false ).toVar();
 	const resultColorWeight = vec3( 1.0 ).toVar();
+	const resultIsDelta = tslBool( false ).toVar();
 
 	// Compute BRDF weights
 	const weights = cachedBrdfWeights.toVar();
@@ -134,7 +138,7 @@ export const generateSampledDirection = Fn( ( [
 
 			resultDirection.assign( reflect( V.negate(), H ) );
 
-		} ).Else( () => {
+		} ).ElseIf( material.roughness.greaterThan( 0.0 ), () => {
 
 			const TBN = constructTBN( { N } );
 			const localV = TBN.transpose().mul( V );
@@ -145,6 +149,11 @@ export const generateSampledDirection = Fn( ( [
 
 			resultDirection.assign( reflect( V.negate(), H ) );
 
+		} ).Else( () => {
+
+			resultDirection.assign( reflect( V.negate(), N ) );
+			resultIsDelta.assign( true );
+
 		} );
 
 	} ).ElseIf( rand.lessThan( cumulativeSheen ), () => {
@@ -189,8 +198,20 @@ export const generateSampledDirection = Fn( ( [
 	If( resultIsTransmission.not(), () => {
 
 		const dotsOut = DotProducts.wrap( computeDotProductsAniso( N, V, resultDirection, material ) );
-		resultValue.assign( evaluateMaterialResponseFromDots( material, dotsOut ) );
-		resultPdf.assign( calculateBSDFSamplingPDF( material, weights, dotsOut ) );
+		If( resultIsDelta, () => {
+
+			// A delta lobe has no density to share, so report one large enough that every MIS weight
+			// against it is 1, and scale the value so value·NoL/pdf is reflectance / selection chance.
+			resultPdf.assign( DELTA_PDF );
+			resultValue.assign( evaluateSpecularDeltaFromDots( material, dotsOut )
+				.mul( DELTA_PDF ).div( max( weights.specular.mul( dotsOut.NoL ), 1e-6 ) ) );
+
+		} ).Else( () => {
+
+			resultValue.assign( evaluateMaterialResponseFromDots( material, dotsOut ) );
+			resultPdf.assign( calculateBSDFSamplingPDF( material, weights, dotsOut ) );
+
+		} );
 
 	} );
 

package/src/TSL/ShadeKernel.js

@@ -15,7 +15,7 @@ import {
 } from 'three/tsl';
 
 import { sampleEnvironment, sampleEquirect, groundProjectedEnvDir } from './Environment.js';
-import { getMaterial, powerHeuristic, balanceHeuristic, classifyMaterial, REC709_LUMINANCE_COEFFICIENTS, PI_INV, EPSILON, diffuseGroundMaterial, offsetRayOrigin, SHADOW_END } from './Common.js';
+import { getMaterial, powerHeuristic, balanceHeuristic, classifyMaterial, REC709_LUMINANCE_COEFFICIENTS, PI_INV, EPSILON, diffuseGroundMaterial, offsetRayOrigin, SHADOW_END, triangleRow, MIN_ROUGHNESS } from './Common.js';
 import { cosineWeightedSample } from './MaterialSampling.js';
 import { sampleAllMaterialTextures, processAnisotropyMap, applyExtensionMaps, getTransformedUV, triangleUVTangent } from './TextureSampling.js';
 import { evaluateMaterialResponse } from './MaterialEvaluation.js';
@@ -23,7 +23,7 @@ import { calculateDirectLightingUnified, calculateMaterialPDF } from './LightsSa
 import { traceShadowRay } from './LightsDirect.js';
 import { shadowTerminatorOrigin } from './ShadowTerminator.js';
 import { unpackHitFacet } from './HitFacet.js';
-import { traverseBVHShadow } from './BVHTraversal.js';
+import { traverseBVHShadow, triangleSide, sideAccepts } from './BVHTraversal.js';
 import { handleMaterialTransparency, MaterialInteractionResult } from './MaterialTransmission.js';
 import { sampleChromaticCollision, sampleHenyeyGreenstein, subsurfaceCoefficients, CollisionSample, MediumCoeffs } from './Subsurface.js';
 import { calculateIndirectLighting } from './LightsIndirect.js';
@@ -637,7 +637,7 @@ export function buildShadeKernel( params ) {
 
 					// free-bounce continuation: ray stays in the same medium, so medium stack + coeffs persist
 					// SSS scatter changes direction → no longer the direct backdrop view.
-					flags.assign( flags.bitOr( uint( RAY_FLAG.REDIRECTED ) ) );
+					flags.assign( flags.sub( flags.bitAnd( uint( RAY_FLAG.UNDER_SURFACE ) ) ).bitOr( uint( RAY_FLAG.REDIRECTED ) ) );
 					writeRayOriginMeta( rayBufferRW, rayID, scatterPoint, cameraDepth, sssSteps, transparentCount );
 					writeRayDirFlags( rayBufferRW, rayID, newDir, flags );
 					// Free bounce: preserve prevBouncePdf (megakernel leaves it untouched across SSS scatter,
@@ -705,7 +705,7 @@ export function buildShadeKernel( params ) {
 		// BRDF functions read material.color/metalness/roughness, so apply samples here
 		material.color.assign( matSamples.albedo );
 		material.metalness.assign( matSamples.metalness.clamp( 0.0, 1.0 ) );
-		material.roughness.assign( matSamples.roughness.clamp( 0.05, 1.0 ) );
+		material.roughness.assign( matSamples.roughness.clamp( MIN_ROUGHNESS, 1.0 ) );
 		material.sheenRoughness.assign( material.sheenRoughness.clamp( 0.05, 1.0 ) ); // megakernel parity (PathTracerCore.js:1060): sample/PDF mismatch at sheenRoughness~0
 
 		// Anisotropy + extension maps carry no per-slot transform of their own, so reuse the material's
@@ -737,6 +737,15 @@ export function buildShadeKernel( params ) {
 		material.specularIntensity.assign( extMaps.specularIntensity );
 		material.specularColor.assign( extMaps.specularColor );
 
+		// Below the floor the GGX peak is past f32, so a plain reflector reflects exactly: roughness 0
+		// is the delta-lobe marker the sampler and evaluator read. The other lobes keep the floor.
+		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 );
+
+		} );
+
 		const albedo = matSamples.albedo.toVar();
 		If(
 			material.displacementMapIndex.greaterThanEqual( int( 0 ) )
@@ -987,7 +996,8 @@ export function buildShadeKernel( params ) {
 
 			// Off the side of the facet the new ray leaves on: reflection stays, transmission and alpha skip cross.
 			const Ng = unpackHitFacet( readHitFacet( hitBufferRW, rayID ) ).faceN;
-			const newOrigin = offsetRayOrigin( hitPoint, select( dot( Ng, interaction.direction ).lessThan( 0.0 ), Ng.negate(), Ng ) );
+			const crossesFacet = dot( Ng, interaction.direction ).lessThan( 0.0 ).toVar();
+			const newOrigin = offsetRayOrigin( hitPoint, select( crossesFacet, Ng.negate(), Ng ) );
 
 			// SSS = free bounce (depth unchanged); transmission advances camera-bounce depth.
 			// Transmissive / alpha-skip / SSS-boundary are all FREE bounces — they do NOT advance camera depth (megakernel parity, gap #4). cameraDepth advances only on opaque scatter (below).
@@ -996,7 +1006,9 @@ export function buildShadeKernel( params ) {
 			// backdrop while env through glass becomes sharp redirected light.
 			If( interaction.isAlphaSkip.not(), () => {
 
-				flags.assign( flags.bitOr( uint( RAY_FLAG.REDIRECTED ) ) );
+				const underSurface = interaction.didReflect.and( crossesFacet );
+				flags.assign( flags.sub( flags.bitAnd( uint( RAY_FLAG.UNDER_SURFACE ) ) ).bitOr( uint( RAY_FLAG.REDIRECTED ) )
+					.bitOr( select( underSurface, uint( RAY_FLAG.UNDER_SURFACE ), uint( 0 ) ) ) );
 
 			} ).Else( () => {
 
@@ -1044,6 +1056,16 @@ export function buildShadeKernel( params ) {
 		flags.assign( flags.bitOr( uint( RAY_FLAG.HAS_HIT_OPAQUE | RAY_FLAG.REDIRECTED ) ) );
 
 		const emissive = matSamples.emissive.toVar();
+		// NEE samples only a single-sided emitter's lit side, so from behind (bounce rays) it is a dark occluder.
+		If( isBackdropView.not().and( length( emissive ).greaterThan( 0.0 ) ), () => {
+
+			If( sideAccepts( triangleSide( triangleRow( triangleBuffer, int( hitTriIdx ), 4 ).z ), dot( direction, hitNormal ) ).not(), () => {
+
+				emissive.assign( vec3( 0.0 ) );
+
+			} );
+
+		} );
 		If( length( emissive ).greaterThan( 0.0 ), () => {
 
 			// Key on backdrop-view (not bounceIndex>0) so an emitter seen DIRECTLY through an alpha-cutout hole
@@ -1417,11 +1439,15 @@ export function buildShadeKernel( params ) {
 
 		} );
 
-		const newOrigin = offsetRayOrigin( hitPoint, select( dot( facetN, bounceDir ).lessThan( 0.0 ), facetN.negate(), facetN ) );
+		const underFacet = dot( facetN, bounceDir ).lessThan( 0.0 ).toVar();
+		const newOrigin = offsetRayOrigin( hitPoint, select( underFacet, 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 ) ) ) );
+		const underSurface = brdfIsTransmission.not().and( underFacet );
+		flags.assign( flags.sub( flags.bitAnd( uint( RAY_FLAG.SUN_NEE | RAY_FLAG.UNDER_SURFACE ) ) )
+			.bitOr( select( sunNEE, uint( RAY_FLAG.SUN_NEE ), uint( 0 ) ) )
+			.bitOr( select( underSurface, uint( RAY_FLAG.UNDER_SURFACE ), uint( 0 ) ) ) );
 
 		// Opaque scatter: the only bounce that advances camera depth.
 		writeRayOriginMeta( rayBufferRW, rayID, newOrigin, cameraDepth.add( 1 ), sssSteps, transparentCount );