rayzee 6.3.0 → 6.5.0

package/src/Processor/PBRT/index.js

@@ -0,0 +1,179 @@
+/**
+ * PBRT-v4 scene loader.
+ *
+ * Orchestrates: virtual filesystem (from a zip) → tokenize/parse the entry
+ * .pbrt (following Include/Import) → build a THREE scene graph. Geometry,
+ * image, and HDR decoding are injected by the host (AssetLoader owns the
+ * three/examples loaders) so this module stays dependency-light.
+ *
+ * Usage (from AssetLoader):
+ *   const { group, environment, warnings } = await loadPBRTScene({
+ *     vfs, entryPath, plyParser, imageFromBytes, envFromBytes
+ *   });
+ *   scene.environment = environment?.texture ?? scene.environment;
+ *   await loadObject3D(group);
+ */
+
+import { PBRTParser } from './PBRTParser.js';
+import { PBRTSceneBuilder } from './PBRTSceneBuilder.js';
+
+export { PBRTParser } from './PBRTParser.js';
+export { PBRTSceneBuilder } from './PBRTSceneBuilder.js';
+export { tokenize } from './PBRTTokenizer.js';
+
+const decoder = new TextDecoder();
+
+/** Normalize a path: forward slashes, collapse "./" and "../". */
+function normalizePath( p ) {
+
+	const parts = p.replace( /\\/g, '/' ).split( '/' );
+	const out = [];
+	for ( const part of parts ) {
+
+		if ( part === '' || part === '.' ) continue;
+		if ( part === '..' ) out.pop();
+		else out.push( part );
+
+	}
+
+	return out.join( '/' );
+
+}
+
+/** Join a base directory with a relative path. */
+function joinPath( dir, rel ) {
+
+	if ( ! dir ) return normalizePath( rel );
+	if ( rel.startsWith( '/' ) ) return normalizePath( rel );
+	return normalizePath( `${dir}/${rel}` );
+
+}
+
+/**
+ * Wraps the zip contents with tolerant, case-insensitive lookup that falls back
+ * to a basename match — pbrt scenes are inconsistent about path roots.
+ */
+class VirtualFS {
+
+	constructor( entries ) {
+
+		// entries: { path: Uint8Array }
+		this.byPath = new Map(); // normalized lowercase -> { norm, bytes }
+		this.byBase = new Map(); // basename lowercase -> [ { norm, bytes } ] (insertion order)
+		for ( const key in entries ) {
+
+			const norm = normalizePath( key ).toLowerCase();
+			const rec = { norm, bytes: entries[ key ] };
+			this.byPath.set( norm, rec );
+			const base = norm.split( '/' ).pop();
+			const bucket = this.byBase.get( base );
+			if ( bucket ) bucket.push( rec );
+			else this.byBase.set( base, [ rec ] );
+
+		}
+
+	}
+
+	find( path ) {
+
+		const norm = normalizePath( path ).toLowerCase();
+		if ( this.byPath.has( norm ) ) return this.byPath.get( norm ).bytes;
+
+		// Resolve by basename (O(1)); among collisions prefer a path-suffix match,
+		// else fall back to the first entry with that name. pbrt scenes are
+		// inconsistent about path roots, so this tolerates relative/absolute drift.
+		const bucket = this.byBase.get( norm.split( '/' ).pop() );
+		if ( ! bucket ) return null;
+		const suffixHit = bucket.find( rec => rec.norm.endsWith( '/' + norm ) );
+		return ( suffixHit || bucket[ 0 ] ).bytes;
+
+	}
+
+}
+
+/** Pick the top-level .pbrt entry: shallowest path, preferring scene/main names. */
+export function pickEntryPath( entries ) {
+
+	const pbrts = Object.keys( entries ).filter( k => k.toLowerCase().endsWith( '.pbrt' ) );
+	if ( pbrts.length === 0 ) return null;
+
+	const preferred = pbrts.filter( k => /(^|\/)(scene|main)\.pbrt$/i.test( k ) );
+	const pool = preferred.length ? preferred : pbrts;
+
+	// Shallowest (fewest path segments), then shortest name.
+	pool.sort( ( a, b ) => {
+
+		const da = a.split( '/' ).length, db = b.split( '/' ).length;
+		return da !== db ? da - db : a.length - b.length;
+
+	} );
+
+	return pool[ 0 ];
+
+}
+
+/**
+ * @param {object} args
+ * @param {Object<string,Uint8Array>} args.vfs - zip entries (path → bytes)
+ * @param {string} [args.entryPath] - top .pbrt; auto-detected if omitted
+ * @param {(buf:ArrayBuffer)=>import('three').BufferGeometry} args.plyParser
+ * @param {(bytes:Uint8Array, filename:string)=>Promise<import('three').Texture>} args.imageFromBytes
+ * @param {(bytes:Uint8Array, filename:string)=>Promise<import('three').Texture>} [args.envFromBytes]
+ * @param {boolean} [args.convertHandedness=true]
+ * @returns {Promise<{group, camera, environment, warnings, entryPath}>}
+ */
+export async function loadPBRTScene( args ) {
+
+	const { vfs: rawEntries, plyParser, imageFromBytes, envFromBytes, convertHandedness } = args;
+	const vfs = new VirtualFS( rawEntries );
+
+	const entryPath = args.entryPath || pickEntryPath( rawEntries );
+	if ( ! entryPath ) throw new Error( 'PBRT loader: no .pbrt file found in archive' );
+
+	const entryBytes = vfs.find( entryPath );
+	if ( ! entryBytes ) throw new Error( `PBRT loader: entry "${entryPath}" not readable` );
+
+	const baseDir = entryPath.includes( '/' ) ? entryPath.slice( 0, entryPath.lastIndexOf( '/' ) ) : '';
+
+	// Parse (with Include resolution)
+	const parser = new PBRTParser( {
+		resolveInclude: ( path, currentDir ) => {
+
+			const bytes = vfs.find( joinPath( currentDir, path ) ) || vfs.find( path );
+			return bytes ? decoder.decode( bytes ) : null;
+
+		}
+	} );
+	const ir = parser.parse( decoder.decode( entryBytes ), baseDir );
+
+	// Build scene graph
+	const sliceBuf = ( bytes ) => bytes.buffer.slice( bytes.byteOffset, bytes.byteOffset + bytes.byteLength );
+	const builder = new PBRTSceneBuilder( {
+		convertHandedness,
+		resolvePLY: async ( filename ) => {
+
+			const bytes = vfs.find( filename );
+			if ( ! bytes ) return null;
+			return plyParser( sliceBuf( bytes ) );
+
+		},
+		resolveImage: async ( filename ) => {
+
+			const bytes = vfs.find( filename );
+			if ( ! bytes ) return null;
+			return imageFromBytes( bytes, filename );
+
+		},
+		resolveEnvironment: async ( filename ) => {
+
+			const bytes = vfs.find( filename );
+			if ( ! bytes ) return null;
+			return ( envFromBytes || imageFromBytes )( bytes, filename );
+
+		}
+	} );
+
+	const result = await builder.build( ir );
+	return { ...result, entryPath };
+
+}

package/src/Processor/ShaderBuilder.js

@@ -411,6 +411,7 @@ export class ShaderBuilder {
 					groundProjectionHeight: stage.groundProjectionHeight,
 					maxBounceCount: stage.maxBounces,
 					transmissiveBounces: stage.transmissiveBounces,
+					maxSubsurfaceSteps: stage.maxSubsurfaceSteps,
 					showBackground: stage.showBackground,
 					transparentBackground: stage.transparentBackground,
 					backgroundIntensity: stage.backgroundIntensity,

package/src/Processor/TextureCreator.js

@@ -965,6 +965,12 @@ export class TextureCreator {
 				bumpMapMatrices[ 4 ], 		bumpMapMatrices[ 5 ],	 	bumpMapMatrices[ 6 ], 		1,
 				displacementMapMatrices[ 0 ], displacementMapMatrices[ 1 ], displacementMapMatrices[ 2 ], displacementMapMatrices[ 3 ],
 				displacementMapMatrices[ 4 ], displacementMapMatrices[ 5 ], displacementMapMatrices[ 6 ], 1,
+				// Slot 27: subsurface (subsurfaceColor.rgb, subsurface weight)
+				mat.subsurfaceColor?.r ?? 1,	mat.subsurfaceColor?.g ?? 1,	mat.subsurfaceColor?.b ?? 1,	mat.subsurface ?? 0,
+				// Slot 28: subsurface (subsurfaceRadius.rgb, subsurfaceRadiusScale)
+				mat.subsurfaceRadius?.[ 0 ] ?? 1, mat.subsurfaceRadius?.[ 1 ] ?? 0.2, mat.subsurfaceRadius?.[ 2 ] ?? 0.1, mat.subsurfaceRadiusScale ?? 1,
+				// Slot 29: subsurface (anisotropy g, reserved)
+				mat.subsurfaceAnisotropy ?? 0,	0,	0,	0,
 			];
 
 			data.set( materialData, stride );

package/src/RenderSettings.js

@@ -18,6 +18,7 @@ const SETTING_ROUTES = {
 	maxBounces: { uniform: 'maxBounces', reset: true },
 	samplesPerPixel: { uniform: 'samplesPerPixel', reset: true },
 	transmissiveBounces: { uniform: 'transmissiveBounces', reset: true },
+	maxSubsurfaceSteps: { uniform: 'maxSubsurfaceSteps', reset: true },
 	environmentIntensity: { uniform: 'environmentIntensity', reset: true },
 	backgroundIntensity: { uniform: 'backgroundIntensity', reset: true },
 	showBackground: { uniform: 'showBackground', reset: true },

package/src/TSL/BVHTraversal.js

@@ -19,6 +19,7 @@ import {
 	lessThan,
 	mat3,
 	array,
+	bool as tslBool,
 } from 'three/tsl';
 
 import { Ray, HitInfo } from './Struct.js';
@@ -178,8 +179,13 @@ export const traverseBVH = Fn( ( [
 	ray,
 	bvhBuffer,
 	triangleBuffer,
+	insideMedium, // optional: when true (ray inside a medium), bypass front/back culling
 ] ) => {
 
+	// 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 );
+
 	const closestHit = HitInfo( {
 		didHit: false,
 		dst: float( 1e20 ),
@@ -280,7 +286,7 @@ export const traverseBVH = 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 = side.equal( int( 2 ) )
+						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, () => {

package/src/TSL/Common.js

@@ -201,13 +201,14 @@ export const applySoftSuppressionRGB = wgslFn( `
 `, [ applySoftSuppression ] );
 
 // Pre-computed material classification for faster branching
-export const classifyMaterial = Fn( ( [ metalness, roughness, transmission, clearcoat, emissive ] ) => {
+export const classifyMaterial = Fn( ( [ metalness, roughness, transmission, clearcoat, emissive, subsurface ] ) => {
 
 	const isMetallic = metalness.greaterThan( 0.7 ).toVar();
 	const isRough = roughness.greaterThan( 0.8 );
 	const isSmooth = roughness.lessThan( 0.3 ).toVar();
 	const isTransmissive = transmission.greaterThan( 0.5 ).toVar();
 	const hasClearcoat = clearcoat.greaterThan( 0.5 ).toVar();
+	const isSubsurface = subsurface.greaterThan( 0.0 ); // only feeds complexityScore below
 
 	// Fast emissive check using sum
 	const emissiveMag = emissive.x.add( emissive.y ).add( emissive.z );
@@ -218,7 +219,8 @@ export const classifyMaterial = Fn( ( [ metalness, roughness, transmission, clea
 		.add( float( 0.25 ).mul( float( isSmooth ) ) )
 		.add( float( 0.45 ).mul( float( isTransmissive ) ) )
 		.add( float( 0.35 ).mul( float( hasClearcoat ) ) )
-		.add( float( 0.3 ).mul( float( isEmissive ) ) );
+		.add( float( 0.3 ).mul( float( isEmissive ) ) )
+		.add( float( 0.4 ).mul( float( isSubsurface ) ) ); // SSS walks are deep + high-value → keep alive in RR
 
 	// Add material interaction complexity
 	const interactionComplexity = float( 0.0 ).toVar();
@@ -340,6 +342,9 @@ export const getMaterial = Fn( ( [ materialIndex, materialBuffer ] ) => {
 	const data24 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.BUMP_TRANSFORM_B ), int( MATERIAL_SLOTS ) ).toVar();
 	const data25 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.DISPLACEMENT_TRANSFORM_A ), int( MATERIAL_SLOTS ) ).toVar();
 	const data26 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.DISPLACEMENT_TRANSFORM_B ), int( MATERIAL_SLOTS ) ).toVar();
+	const data27 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.SUBSURFACE_A ), int( MATERIAL_SLOTS ) ).toVar();
+	const data28 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.SUBSURFACE_B ), int( MATERIAL_SLOTS ) ).toVar();
+	const data29 = getDatafromStorageBuffer( materialBuffer, materialIndex, int( S.SUBSURFACE_C ), int( MATERIAL_SLOTS ) ).toVar();
 
 	return RayTracingMaterial( {
 		color: vec4( data0.rgb, 1.0 ),
@@ -361,6 +366,11 @@ export const getMaterial = Fn( ( [ materialIndex, materialBuffer ] ) => {
 		iridescence: data7.r,
 		iridescenceIOR: data7.g,
 		iridescenceThicknessRange: data7.ba,
+		subsurfaceColor: data27.rgb,
+		subsurface: data27.a,
+		subsurfaceRadius: data28.rgb,
+		subsurfaceRadiusScale: data28.a,
+		subsurfaceAnisotropy: data29.r,
 		albedoMapIndex: int( data8.r ),
 		normalMapIndex: int( data8.g ),
 		roughnessMapIndex: int( data8.b ),

package/src/TSL/MaterialTransmission.js

@@ -27,6 +27,7 @@ import { iorToFresnel0, fresnelSchlickFloat } from './Fresnel.js';
 import { DistributionGGX } from './MaterialProperties.js';
 import { ImportanceSampleGGX } from './MaterialSampling.js';
 import { RandomValue, pcgHash } from './Random.js';
+import { handleSubsurfaceEntry, SubsurfaceEntryResult } from './Subsurface.js';
 
 // ================================================================================
 // STRUCTS (local to transmission)
@@ -43,6 +44,7 @@ export const MaterialInteractionResult = struct( {
 	continueRay: 'bool', // Whether the ray should continue without further BRDF evaluation
 	isTransmissive: 'bool', // Flag to indicate this was a transmissive interaction
 	isAlphaSkip: 'bool', // Flag to indicate this was an alpha skip
+	isSubsurface: 'bool', // Flag to indicate this entered/exited a subsurface medium
 	didReflect: 'bool', // Whether TIR/reflection occurred (for medium stack update)
 	entering: 'bool', // Whether ray is entering or exiting medium
 	direction: 'vec3', // New ray direction if continuing
@@ -493,6 +495,7 @@ export const handleMaterialTransparency = Fn( ( [
 		continueRay: false,
 		isTransmissive: false,
 		isAlphaSkip: false,
+		isSubsurface: false,
 		didReflect: false,
 		entering: false,
 		direction: ray.direction,
@@ -501,8 +504,9 @@ export const handleMaterialTransparency = Fn( ( [
 		pathWavelength: pathWavelength,
 	} ).toVar();
 
-	// Fast path for fully opaque materials (most common case)
-	If( material.alphaMode.equal( int( 0 ) ).and( material.transmission.lessThanEqual( 0.0 ) ), () => {
+	// Fast path for fully opaque, non-scattering materials (most common case).
+	// Subsurface materials are opaque (transmission==0) but must NOT take this path.
+	If( material.alphaMode.equal( int( 0 ) ).and( material.transmission.lessThanEqual( 0.0 ) ).and( material.subsurface.lessThanEqual( 0.0 ) ), () => {
 
 		// no interaction needed
 
@@ -584,6 +588,32 @@ export const handleMaterialTransparency = Fn( ( [
 
 		} );
 
+		// Subsurface (independent of transmission; works at transmission==0). Entry is a lottery
+		// (prob = weight) so 1-weight falls through to the opaque BRDF; exit is deterministic.
+		If( handled.not().and( material.subsurface.greaterThan( 0.0 ) ), () => {
+
+			const entering = dot( ray.direction, normal ).lessThan( 0.0 );
+			const doEnter = entering.not().or( RandomValue( rngState ).lessThan( material.subsurface ) );
+
+			If( doEnter, () => {
+
+				const ssResult = SubsurfaceEntryResult.wrap( handleSubsurfaceEntry(
+					ray.direction, normal, material, entering, rngState,
+					currentMediumIOR, previousMediumIOR,
+				) ).toVar();
+
+				result.direction.assign( ssResult.direction );
+				result.throughput.assign( ssResult.throughput );
+				result.continueRay.assign( true );
+				result.isSubsurface.assign( true );
+				result.didReflect.assign( ssResult.didReflect );
+				result.entering.assign( entering );
+				result.alpha.assign( 1.0 );
+
+			} );
+
+		} );
+
 	} );
 
 	return result;

package/src/TSL/PathTracer.js

@@ -151,7 +151,7 @@ export const pathTracerMain = ( params ) => {
 		envTotalSum, envCompensationDelta, envResolution,
 		enableEnvironmentLight, useEnvMapIS,
 		groundProjectionEnabled, groundProjectionRadius, groundProjectionHeight,
-		maxBounceCount, transmissiveBounces,
+		maxBounceCount, transmissiveBounces, maxSubsurfaceSteps,
 		showBackground, transparentBackground, backgroundIntensity,
 		fireflyThreshold, globalIlluminationIntensity,
 		enableEmissiveTriangleSampling,
@@ -299,7 +299,7 @@ export const pathTracerMain = ( params ) => {
 				envTotalSum, envCompensationDelta, envResolution,
 				enableEnvironmentLight, useEnvMapIS,
 				groundProjectionEnabled, groundProjectionRadius, groundProjectionHeight,
-				maxBounceCount, transmissiveBounces,
+				maxBounceCount, transmissiveBounces, maxSubsurfaceSteps,
 				backgroundIntensity, showBackground, transparentBackground,
 				fireflyThreshold, globalIlluminationIntensity,
 				enableEmissiveTriangleSampling,

package/src/TSL/PathTracerCore.js

@@ -77,6 +77,7 @@ import { sampleEnvironment, sampleEquirect, getGroundProjectedDirection } from '
 import { sampleAllMaterialTextures } from './TextureSampling.js';
 import { refineDisplacedIntersection, DisplacementResult } from './Displacement.js';
 import { handleMaterialTransparency, MaterialInteractionResult, sampleMicrofacetTransmission, MicrofacetTransmissionResult } from './MaterialTransmission.js';
+import { subsurfaceCoefficients, sampleChromaticCollision, sampleHenyeyGreenstein, MediumCoeffs, CollisionSample } from './Subsurface.js';
 import {
 	SheenDistribution,
 	calculateVNDFPDF,
@@ -140,7 +141,7 @@ export const getOrCreateMaterialClassification = Fn( ( [
 		result.assign( classifyMaterial(
 			material.metalness, material.roughness,
 			material.transmission, material.clearcoat,
-			material.emissive,
+			material.emissive, material.subsurface,
 		) );
 
 	} );
@@ -538,7 +539,7 @@ export const Trace = Fn( ( [
 	enableEnvironmentLight, useEnvMapIS,
 	groundProjectionEnabled, groundProjectionRadius, groundProjectionHeight,
 	// Rendering parameters
-	maxBounceCount, transmissiveBounces,
+	maxBounceCount, transmissiveBounces, maxSubsurfaceSteps,
 	backgroundIntensity, showBackground, transparentBackground,
 	fireflyThreshold, globalIlluminationIntensity,
 	enableEmissiveTriangleSampling,
@@ -584,6 +585,18 @@ export const Trace = Fn( ( [
 	const mediumStack_sigmaA_1 = vec3( 0.0 ).toVar();
 	const mediumStack_sigmaA_2 = vec3( 0.0 ).toVar();
 	const mediumStack_sigmaA_3 = vec3( 0.0 ).toVar();
+	// Subsurface: sigma_s>0 makes the medium scatter (random walk) rather than absorb straight.
+	const mediumStack_sigmaS_1 = vec3( 0.0 ).toVar();
+	const mediumStack_sigmaS_2 = vec3( 0.0 ).toVar();
+	const mediumStack_sigmaS_3 = vec3( 0.0 ).toVar();
+	const mediumStack_sigmaT_1 = vec3( 0.0 ).toVar();
+	const mediumStack_sigmaT_2 = vec3( 0.0 ).toVar();
+	const mediumStack_sigmaT_3 = vec3( 0.0 ).toVar();
+	const mediumStack_g_1 = float( 0.0 ).toVar();
+	const mediumStack_g_2 = float( 0.0 ).toVar();
+	const mediumStack_g_3 = float( 0.0 ).toVar();
+	// Walk-step budget for the whole path (bounded per render mode + RR).
+	const sssSteps = int( 0 ).toVar();
 
 	// Locked at the first dispersive transmission; reused for subsequent transmissions on
 	// the path so multi-bounce dispersion doesn't collapse under repeated colorWeight ×.
@@ -633,7 +646,7 @@ export const Trace = Fn( ( [
 	const rayDirection = ray.direction.toVar();
 
 	// Main bounce loop
-	Loop( { start: int( 0 ), end: maxBounceCount.add( transmissiveBounces ).add( 1 ), type: 'int', condition: '<' }, ( { i: bounceIndex } ) => {
+	Loop( { start: int( 0 ), end: maxBounceCount.add( transmissiveBounces ).add( maxSubsurfaceSteps ).add( 1 ), type: 'int', condition: '<' }, ( { i: bounceIndex } ) => {
 
 		// Update state
 		stateTraversals.assign( maxBounceCount.sub( effectiveBounces ) );
@@ -656,30 +669,82 @@ export const Trace = Fn( ( [
 			currentRay,
 			bvhBuffer,
 			triangleBuffer,
+			mediumStackDepth.greaterThan( int( 0 ) ), // inside a medium → bypass front/back culling
 		) ).toVar();
 
-		// KHR_materials_volume: apply Beer's law over the actual distance the ray
-		// traveled inside the current medium. Top-of-stack holds the medium the ray
-		// is currently in — depth==0 means air (no absorption). sigma_a was
-		// precomputed at push time, so this collapses to a single exp().
+		// In-medium transport: glass (sigma_s==0) absorbs along a straight line; subsurface
+		// (sigma_s>0) random-walks and may scatter mid-flight.
 		If( hitInfo.didHit.and( mediumStackDepth.greaterThan( int( 0 ) ) ), () => {
 
+			// Load current-medium coefficients (chained branch — divergence-safe).
 			const mSigmaA = vec3( 0.0 ).toVar();
+			const mSigmaS = vec3( 0.0 ).toVar();
+			const mSigmaT = vec3( 0.0 ).toVar();
+			const mG = float( 0.0 ).toVar();
 			If( mediumStackDepth.equal( int( 1 ) ), () => {
 
-				mSigmaA.assign( mediumStack_sigmaA_1 );
+				mSigmaA.assign( mediumStack_sigmaA_1 ); mSigmaS.assign( mediumStack_sigmaS_1 );
+				mSigmaT.assign( mediumStack_sigmaT_1 ); mG.assign( mediumStack_g_1 );
 
 			} ).ElseIf( mediumStackDepth.equal( int( 2 ) ), () => {
 
-				mSigmaA.assign( mediumStack_sigmaA_2 );
+				mSigmaA.assign( mediumStack_sigmaA_2 ); mSigmaS.assign( mediumStack_sigmaS_2 );
+				mSigmaT.assign( mediumStack_sigmaT_2 ); mG.assign( mediumStack_g_2 );
 
 			} ).ElseIf( mediumStackDepth.equal( int( 3 ) ), () => {
 
-				mSigmaA.assign( mediumStack_sigmaA_3 );
+				mSigmaA.assign( mediumStack_sigmaA_3 ); mSigmaS.assign( mediumStack_sigmaS_3 );
+				mSigmaT.assign( mediumStack_sigmaT_3 ); mG.assign( mediumStack_g_3 );
 
 			} );
 
-			throughput.mulAssign( exp( mSigmaA.mul( hitInfo.dst ).negate() ) );
+			If( maxComponent( { v: mSigmaS } ).lessThanEqual( 0.0 ), () => {
+
+				// Non-scattering medium (glass): straight-line Beer-Lambert absorption.
+				throughput.mulAssign( exp( mSigmaA.mul( hitInfo.dst ).negate() ) );
+
+			} ).Else( () => {
+
+				// Scattering medium (subsurface): chromatic distance sampling for this segment.
+				const coll = CollisionSample.wrap( sampleChromaticCollision(
+					mSigmaT, mSigmaS, throughput, hitInfo.dst, rngState,
+				) ).toVar();
+				throughput.mulAssign( coll.weight );
+
+				If( coll.didScatter, () => {
+
+					// Scatter: move to the collision point, redirect via the HG phase function,
+					// continue as a free bounce (no camera-bounce cost).
+					const xi2 = vec2( RandomValue( rngState ), RandomValue( rngState ) );
+					const scatterPoint = rayOrigin.add( rayDirection.mul( coll.t ) );
+					rayOrigin.assign( scatterPoint );
+					rayDirection.assign( sampleHenyeyGreenstein( rayDirection, mG, xi2 ) );
+					sssSteps.addAssign( 1 );
+					stateIsPrimaryRay.assign( tslBool( false ) );
+
+					// Per-mode step cap: bounded walk (terminate — energy-loss-only bias).
+					If( sssSteps.greaterThanEqual( maxSubsurfaceSteps ), () => {
+
+						Break();
+
+					} );
+
+					// Russian roulette so the walk self-terminates before the cap.
+					const rrP = clamp( maxComponent( { v: throughput } ), 0.02, 1.0 ).toVar();
+					If( RandomValue( rngState ).greaterThan( rrP ), () => {
+
+						Break();
+
+					} );
+					throughput.divAssign( rrP );
+
+					Continue();
+
+				} );
+
+				// No scatter: reached the boundary (weight applied); fall through to surface handling.
+
+			} );
 
 		} );
 
@@ -732,7 +797,7 @@ export const Trace = Fn( ( [
 
 		} );
 
-		// Get full material (27 reads). Lazy transform loading was tested but regressed
+		// Get full material (30 reads). Lazy transform loading was tested but regressed
 		// textured scenes due to identity-construct + conditional-assign overhead.
 		// Shadow rays use getShadowMaterial() (7 reads) — the real bandwidth win.
 		const material = RayTracingMaterial.wrap( getMaterial( hitInfo.materialIndex, materialBuffer ) ).toVar();
@@ -833,6 +898,7 @@ export const Trace = Fn( ( [
 								mediumStack_attColor_1.assign( material.attenuationColor );
 								mediumStack_attDist_1.assign( material.attenuationDistance );
 								mediumStack_sigmaA_1.assign( mSigmaA );
+								mediumStack_sigmaS_1.assign( vec3( 0.0 ) ); // glass: no scattering
 
 							} ).ElseIf( mediumStackDepth.equal( int( 2 ) ), () => {
 
@@ -840,6 +906,7 @@ export const Trace = Fn( ( [
 								mediumStack_attColor_2.assign( material.attenuationColor );
 								mediumStack_attDist_2.assign( material.attenuationDistance );
 								mediumStack_sigmaA_2.assign( mSigmaA );
+								mediumStack_sigmaS_2.assign( vec3( 0.0 ) ); // glass: no scattering
 
 							} ).ElseIf( mediumStackDepth.equal( int( 3 ) ), () => {
 
@@ -847,6 +914,7 @@ export const Trace = Fn( ( [
 								mediumStack_attColor_3.assign( material.attenuationColor );
 								mediumStack_attDist_3.assign( material.attenuationDistance );
 								mediumStack_sigmaA_3.assign( mSigmaA );
+								mediumStack_sigmaS_3.assign( vec3( 0.0 ) ); // glass: no scattering
 
 							} );
 
@@ -865,6 +933,65 @@ export const Trace = Fn( ( [
 
 				} );
 
+			} ).ElseIf( interaction.isSubsurface, () => {
+
+				// Subsurface boundary: free bounce (SSS step budget, not camera bounces). Push on enter, pop on exit.
+				isFreeBounce.assign( tslBool( true ) );
+				stateRayType.assign( int( RAY_TYPE_DIFFUSE ) );
+
+				If( interaction.didReflect.not(), () => {
+
+					If( interaction.entering, () => {
+
+						If( mediumStackDepth.lessThan( int( 3 ) ), () => {
+
+							mediumStackDepth.addAssign( 1 );
+
+							const ssCoeffs = MediumCoeffs.wrap( subsurfaceCoefficients(
+								material.subsurfaceColor, material.subsurfaceRadius, material.subsurfaceRadiusScale,
+							) ).toVar();
+							const ssG = clamp( material.subsurfaceAnisotropy, - 0.99, 0.99 ).toVar();
+
+							If( mediumStackDepth.equal( int( 1 ) ), () => {
+
+								mediumStack_ior_1.assign( material.ior );
+								mediumStack_sigmaA_1.assign( ssCoeffs.sigmaA );
+								mediumStack_sigmaS_1.assign( ssCoeffs.sigmaS );
+								mediumStack_sigmaT_1.assign( ssCoeffs.sigmaT );
+								mediumStack_g_1.assign( ssG );
+
+							} ).ElseIf( mediumStackDepth.equal( int( 2 ) ), () => {
+
+								mediumStack_ior_2.assign( material.ior );
+								mediumStack_sigmaA_2.assign( ssCoeffs.sigmaA );
+								mediumStack_sigmaS_2.assign( ssCoeffs.sigmaS );
+								mediumStack_sigmaT_2.assign( ssCoeffs.sigmaT );
+								mediumStack_g_2.assign( ssG );
+
+							} ).ElseIf( mediumStackDepth.equal( int( 3 ) ), () => {
+
+								mediumStack_ior_3.assign( material.ior );
+								mediumStack_sigmaA_3.assign( ssCoeffs.sigmaA );
+								mediumStack_sigmaS_3.assign( ssCoeffs.sigmaS );
+								mediumStack_sigmaT_3.assign( ssCoeffs.sigmaT );
+								mediumStack_g_3.assign( ssG );
+
+							} );
+
+						} );
+
+					} ).Else( () => {
+
+						If( mediumStackDepth.greaterThan( int( 0 ) ), () => {
+
+							mediumStackDepth.subAssign( 1 );
+
+						} );
+
+					} );
+
+				} );
+
 			} ).ElseIf( interaction.isAlphaSkip, () => {
 
 				isFreeBounce.assign( tslBool( true ) );
@@ -918,6 +1045,18 @@ export const Trace = Fn( ( [
 		const randomSample = getRandomSample( pixelCoord, rayIndex, bounceIndex, rngState, int( - 1 ), resolution, frame ).toVar();
 
 		const V = rayDirection.negate().toVar();
+
+		// Two-sided shading: flip the shading normal into the viewer's hemisphere.
+		// This is the opaque reflection path (transmissive rays already Continue'd),
+		// so it never disturbs dielectric entering/exiting. No-op when N already
+		// faces V; rescues meshes with inward-facing normals (common in imported
+		// scenes, e.g. pbrt PLY assets) that would otherwise shade black.
+		If( dot( N, V ).lessThan( 0.0 ), () => {
+
+			N.assign( N.negate() );
+
+		} );
+
 		material.sheenRoughness.assign( clamp( material.sheenRoughness, MIN_ROUGHNESS, MAX_ROUGHNESS ) );
 
 		// Sync material classification cache up front — the materialCache, BRDF

package/src/TSL/Struct.js

@@ -50,6 +50,11 @@ export const RayTracingMaterial = struct( {
 	iridescence: 'float',
 	iridescenceIOR: 'float',
 	iridescenceThicknessRange: 'vec2',
+	subsurface: 'float', // 0 = off, blends opaque BRDF → random-walk SSS
+	subsurfaceColor: 'vec3', // single-scatter albedo (tint light picks up inside)
+	subsurfaceRadius: 'vec3', // per-channel mean free path
+	subsurfaceRadiusScale: 'float', // scalar multiplier on radius
+	subsurfaceAnisotropy: 'float', // Henyey-Greenstein g (-1..1)
 } );
 
 // Lightweight material for shadow ray evaluation — only the fields needed