@plasius/gpu-lighting 0.2.6 → 0.2.8

package/dist/index.js

@@ -1066,6 +1066,15 @@ var lightingWavefrontHitTypes = Object.freeze([
   "transparent",
   "miss"
 ]);
+var lightingWavefrontRayKinds = Object.freeze([
+  "path",
+  "visibility-probe"
+]);
+var lightingWavefrontVisibilityProbeModes = Object.freeze([
+  "disabled",
+  "mis-balanced",
+  "exclusive-emissive"
+]);
 var lightingWavefrontTerminalHitTypes = Object.freeze([
   "emissive",
   "environment",
@@ -1110,11 +1119,35 @@ var lightingWavefrontBufferContracts = Object.freeze({
       createLightingWavefrontField("sourcePixelId", "u32", "Source pixel/sample owner."),
       createLightingWavefrontField("sampleId", "u32", "Per-pixel sample slot."),
       createLightingWavefrontField("bounce", "u32", "Current bounce depth."),
+      createLightingWavefrontField("mediumRefId", "u32", "Current medium reference."),
+      createLightingWavefrontField(
+        "mediumStackDepth",
+        "u32",
+        "Depth of the bounded nested medium stack."
+      ),
+      createLightingWavefrontField(
+        "flags",
+        "u32",
+        "Renderer-owned ray flags. Low bits may encode ray kind metadata."
+      ),
+      createLightingWavefrontField(
+        "mediumStack0",
+        "vec4<u32>",
+        "Lower half of the bounded nested medium stack."
+      ),
+      createLightingWavefrontField(
+        "mediumStack1",
+        "vec4<u32>",
+        "Upper half of the bounded nested medium stack."
+      ),
+      createLightingWavefrontField(
+        "spectralState",
+        "vec4<f32>",
+        "Spectral transport payload for wavelength-driven reference validation."
+      ),
       createLightingWavefrontField("origin", "vec3<f32>", "Ray origin."),
       createLightingWavefrontField("direction", "vec3<f32>", "Normalized ray direction."),
-      createLightingWavefrontField("throughput", "vec3<f32>", "Accumulated path throughput."),
-      createLightingWavefrontField("mediumRefId", "u32", "Current medium reference."),
-      createLightingWavefrontField("flags", "u32", "Renderer-owned ray flags.")
+      createLightingWavefrontField("throughput", "vec3<f32>", "Accumulated path throughput.")
     ]
   ),
   hit: createLightingWavefrontRecordContract(
@@ -1203,6 +1236,17 @@ var wavefrontEventKinds = Object.freeze([
   "transparency",
   "terminate"
 ]);
+var wavefrontRayKindFlagMask = 3;
+var wavefrontRayKindFlagValues = Object.freeze({
+  path: 0,
+  "visibility-probe": 1
+});
+function normalizeWavefrontRayKind(value) {
+  return lightingWavefrontRayKinds.includes(value) ? value : "path";
+}
+function normalizeWavefrontVisibilityProbeMode(value) {
+  return lightingWavefrontVisibilityProbeModes.includes(value) ? value : "disabled";
+}
 function normalizeWavefrontHitType(value) {
   return lightingWavefrontHitTypes.includes(value) ? value : "surface";
 }
@@ -1275,6 +1319,118 @@ function refractDirection(direction, normal, etaRatio) {
   const rOutParallel = scaleVec3(normal, -Math.sqrt(parallelFactor));
   return normalizeDirection(addVec3(rOutPerp, rOutParallel), direction);
 }
+function normalizeMediumRefId(value) {
+  const mediumRefId = Math.max(0, Math.trunc(readFinite(value, 0)));
+  return Number.isFinite(mediumRefId) ? mediumRefId : 0;
+}
+function normalizeMediumStack(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.map((entry) => normalizeMediumRefId(entry)).filter((entry, index, stack) => entry > 0 && stack.indexOf(entry) === index).slice(0, 4);
+}
+function createWavefrontMediumStatePayload(currentMediumRefId, stack) {
+  const normalizedStack = normalizeMediumStack(stack);
+  const stackSlots = [0, 0, 0, 0];
+  normalizedStack.forEach((entry, index) => {
+    stackSlots[index] = entry;
+  });
+  return Object.freeze({
+    currentMediumRefId,
+    stackDepth: normalizedStack.length,
+    stack: Object.freeze(normalizedStack),
+    stackSlots: Object.freeze(stackSlots)
+  });
+}
+function evaluateWavefrontMediumState(options = {}) {
+  const currentMediumRefId = normalizeMediumRefId(
+    options.currentMediumRefId ?? options.mediumRefId
+  );
+  const surfaceMediumRefId = normalizeMediumRefId(options.surfaceMediumRefId);
+  const stack = normalizeMediumStack(options.mediumStack);
+  const frontFace = options.frontFace !== false;
+  const eventKind = normalizeWavefrontEventKind(options.eventKind) ?? "transparency";
+  if (surfaceMediumRefId === 0 || eventKind !== "refraction" && eventKind !== "transparency") {
+    return Object.freeze({
+      ...createWavefrontMediumStatePayload(currentMediumRefId, stack),
+      enteredMediumRefId: 0,
+      exitedMediumRefId: 0
+    });
+  }
+  let nextStack = [...stack];
+  let nextMediumRefId = currentMediumRefId;
+  let enteredMediumRefId = 0;
+  let exitedMediumRefId = 0;
+  const stackTop = nextStack.at(-1) ?? 0;
+  if (frontFace) {
+    if (stackTop !== surfaceMediumRefId) {
+      nextStack.push(surfaceMediumRefId);
+      nextStack = nextStack.slice(-4);
+    }
+    nextMediumRefId = surfaceMediumRefId;
+    enteredMediumRefId = surfaceMediumRefId;
+  } else if (stackTop === surfaceMediumRefId) {
+    nextStack.pop();
+    nextMediumRefId = nextStack.at(-1) ?? 0;
+    exitedMediumRefId = surfaceMediumRefId;
+  }
+  return Object.freeze({
+    ...createWavefrontMediumStatePayload(nextMediumRefId, nextStack),
+    enteredMediumRefId,
+    exitedMediumRefId
+  });
+}
+function encodeWavefrontRayFlags(flags, rayKind) {
+  const normalizedFlags = Math.max(0, Math.trunc(readFinite(flags, 0)));
+  const rayKindValue = wavefrontRayKindFlagValues[rayKind];
+  return normalizedFlags & ~wavefrontRayKindFlagMask | rayKindValue;
+}
+function createWavefrontRayPayload(options = {}) {
+  const rayKind = normalizeWavefrontRayKind(options.rayKind);
+  const mediumState = evaluateWavefrontMediumState({
+    currentMediumRefId: options.mediumRefId,
+    mediumStack: options.mediumStack
+  });
+  const spectralState = Object.freeze(
+    normalizeVec3(options.spectralState, [550, 1, 0]).concat(
+      readFinite(options.spectralWeight, 0)
+    )
+  );
+  const mediumStack0 = Object.freeze([
+    mediumState.stackSlots[0],
+    mediumState.stackSlots[1],
+    mediumState.stackSlots[2],
+    mediumState.stackSlots[3]
+  ]);
+  const mediumStack1 = Object.freeze([0, 0, 0, 0]);
+  return Object.freeze({
+    rayId: Math.max(0, Math.trunc(readFinite(options.rayId, 0))),
+    parentRayId: Math.max(0, Math.trunc(readFinite(options.parentRayId, 0))),
+    sourcePixelId: Math.max(0, Math.trunc(readFinite(options.sourcePixelId, 0))),
+    sampleId: Math.max(0, Math.trunc(readFinite(options.sampleId, 0))),
+    bounce: Math.max(0, Math.trunc(readFinite(options.bounce, 0))),
+    origin: Object.freeze(normalizeVec3(options.origin, [0, 0, 0])),
+    direction: Object.freeze(normalizeDirection(options.direction, [0, 0, -1])),
+    throughput: Object.freeze(
+      saturateVec3(normalizeVec3(options.throughput, [1, 1, 1]))
+    ),
+    mediumRefId: mediumState.currentMediumRefId,
+    mediumStackDepth: mediumState.stackDepth,
+    mediumStack: mediumState.stack,
+    mediumStackSlots: mediumState.stackSlots,
+    mediumStack0,
+    mediumStack1,
+    spectralState,
+    rayKind,
+    flags: encodeWavefrontRayFlags(options.flags, rayKind)
+  });
+}
+function createWavefrontVisibilityProbeRay(options = {}) {
+  return createWavefrontRayPayload({
+    ...options,
+    rayKind: "visibility-probe"
+  });
+}
 function createWavefrontLightingPlan(options = {}) {
   const maxDepth = Math.max(1, Math.trunc(readFinite(options.maxDepth, 4)));
   const queueCapacity = Math.max(
@@ -1282,6 +1438,9 @@ function createWavefrontLightingPlan(options = {}) {
     Math.trunc(readFinite(options.queueCapacity, 4096))
   );
   const explicitLightSampling = Boolean(options.explicitLightSampling);
+  const visibilityProbeMode = normalizeWavefrontVisibilityProbeMode(
+    options.visibilityProbeMode ?? (explicitLightSampling ? "mis-balanced" : "disabled")
+  );
   const accumulationResetEpoch = Math.max(
     0,
     Math.trunc(readFinite(options.accumulationResetEpoch, 0))
@@ -1291,6 +1450,8 @@ function createWavefrontLightingPlan(options = {}) {
     maxDepth,
     queueCapacity,
     explicitLightSampling,
+    visibilityProbeMode,
+    rayKinds: lightingWavefrontRayKinds,
     accumulationResetEpoch,
     queueLayout: Object.freeze({
       strategy: lightingWavefrontQueuePairStrategy,
@@ -1329,7 +1490,8 @@ function createWavefrontLightingPlan(options = {}) {
         ]),
         writes: Object.freeze(["ray"]),
         continuationHitTypes: lightingWavefrontContinuationHitTypes,
-        explicitLightSampling
+        explicitLightSampling,
+        visibilityProbeMode
       })
     ])
   });
@@ -1389,7 +1551,9 @@ function evaluateWavefrontContinuationEvent(options = {}) {
   const opacity = clampUnit(options.opacity, 1);
   const refractiveIndex = Math.max(1, readFinite(options.refractiveIndex ?? options.ior, 1.45));
   const transmissionStrength = Math.max(...transmission);
-  let eventKind = normalizeWavefrontEventKind(options.eventKind) ?? (hitType === "transparent" || opacity < 0.999 ? "transparency" : transmissionStrength > 1e-3 ? "refraction" : metalness >= 0.5 || roughness <= 0.2 ? "reflection" : "diffuse");
+  const requestedEventKind = normalizeWavefrontEventKind(options.eventKind) ?? (hitType === "transparent" || opacity < 0.999 ? "transparency" : transmissionStrength > 1e-3 ? "refraction" : metalness >= 0.5 || roughness <= 0.2 ? "reflection" : "diffuse");
+  let eventKind = requestedEventKind;
+  let totalInternalReflection = false;
   let nextDirection = incomingDirection;
   let attenuation;
   if (!lightingWavefrontContinuationHitTypes.includes(hitType) || bounceIndex >= maxDepth - 1) {
@@ -1400,8 +1564,20 @@ function evaluateWavefrontContinuationEvent(options = {}) {
     attenuation = mixVec3([0.04, 0.04, 0.04], albedo, metalness);
   } else if (eventKind === "refraction") {
     const etaRatio = frontFace ? 1 / refractiveIndex : refractiveIndex;
-    nextDirection = refractDirection(incomingDirection, orientedNormal, etaRatio) ?? reflectDirection(incomingDirection, orientedNormal);
-    attenuation = transmissionStrength > 1e-3 ? transmission : [1, 1, 1];
+    const refractedDirection = refractDirection(
+      incomingDirection,
+      orientedNormal,
+      etaRatio
+    );
+    if (refractedDirection) {
+      nextDirection = refractedDirection;
+      attenuation = transmissionStrength > 1e-3 ? transmission : [1, 1, 1];
+    } else {
+      totalInternalReflection = true;
+      eventKind = "reflection";
+      nextDirection = reflectDirection(incomingDirection, orientedNormal);
+      attenuation = mixVec3([0.04, 0.04, 0.04], albedo, metalness);
+    }
   } else if (eventKind === "transparency") {
     nextDirection = incomingDirection;
     const transparencyWeight = Math.max(1 - opacity, transmissionStrength, 0.05);
@@ -1415,16 +1591,150 @@ function evaluateWavefrontContinuationEvent(options = {}) {
   }
   const nextThroughput = multiplyVec3(throughput, saturateVec3(attenuation));
   const continueTracing = eventKind !== "terminate" && colorLuminance(nextThroughput) > 1e-4;
+  const mediumState = evaluateWavefrontMediumState({
+    currentMediumRefId: options.currentMediumRefId ?? options.mediumRefId,
+    surfaceMediumRefId: options.surfaceMediumRefId,
+    mediumStack: options.mediumStack,
+    frontFace,
+    eventKind
+  });
   return Object.freeze({
     hitType,
+    requestedEventKind,
     eventKind,
     continueTracing,
+    totalInternalReflection,
     nextDirection: Object.freeze(nextDirection),
     attenuation: Object.freeze(saturateVec3(attenuation)),
     nextThroughput: Object.freeze(nextThroughput),
+    mediumState,
     explicitLightSamplingEnabled: Boolean(options.explicitLightSampling)
   });
 }
+function evaluateWavefrontVisibilityProbe(options = {}) {
+  const probeMode = normalizeWavefrontVisibilityProbeMode(
+    options.probeMode ?? (options.explicitLightSampling ? "mis-balanced" : "disabled")
+  );
+  const probeRay = createWavefrontVisibilityProbeRay({
+    ...options.probeRay,
+    throughput: options.throughput ?? options.probeRay?.throughput,
+    direction: options.direction ?? options.probeRay?.direction,
+    mediumRefId: options.currentMediumRefId ?? options.probeRay?.mediumRefId,
+    mediumStack: options.mediumStack ?? options.probeRay?.mediumStack
+  });
+  const transparentSegments = Array.isArray(options.transparentSegments) ? options.transparentSegments : [];
+  const transmittance = transparentSegments.reduce(
+    (current, segment) => multiplyVec3(current, saturateVec3(normalizeVec3(segment, [1, 1, 1]))),
+    [1, 1, 1]
+  );
+  const emissiveRadiance = saturateVec3(
+    normalizeVec3(options.emissiveRadiance, [0, 0, 0])
+  );
+  const environmentRadiance = saturateVec3(
+    normalizeVec3(options.environmentRadiance, [0, 0, 0])
+  );
+  const activeEmissiveRadiance = saturateVec3(
+    normalizeVec3(options.activeEmissiveRadiance, [0, 0, 0])
+  );
+  const prefersEnvironment = Boolean(options.prefersEnvironment);
+  const sourceRadiance = prefersEnvironment || colorLuminance(emissiveRadiance) <= 1e-6 ? environmentRadiance : emissiveRadiance;
+  const rawContribution = multiplyVec3(
+    probeRay.throughput,
+    multiplyVec3(sourceRadiance, transmittance)
+  );
+  const activeEmissiveVisible = colorLuminance(activeEmissiveRadiance) > 1e-6;
+  const misWeight = probeMode === "mis-balanced" && activeEmissiveVisible ? 0.5 : 1;
+  const contribution = probeMode === "exclusive-emissive" && activeEmissiveVisible ? [0, 0, 0] : scaleVec3(rawContribution, misWeight);
+  return Object.freeze({
+    probeMode,
+    probeRay,
+    transmittance: Object.freeze(transmittance),
+    misWeight,
+    doubleCountPrevented: activeEmissiveVisible && probeMode !== "disabled",
+    contribution: Object.freeze(contribution)
+  });
+}
+function evaluateWavefrontMaterialReference(options = {}) {
+  const material = Object.freeze({
+    albedo: Object.freeze(
+      saturateVec3(normalizeVec3(options.albedo, [0.8, 0.8, 0.8]))
+    ),
+    emission: Object.freeze(
+      saturateVec3(normalizeVec3(options.emission, [0, 0, 0]))
+    ),
+    roughness: clampUnit(options.roughness, 0.5),
+    metalness: clampUnit(options.metalness, 0),
+    opacity: clampUnit(options.opacity, 1),
+    transmission: Object.freeze(
+      saturateVec3(normalizeVec3(options.transmission, [0, 0, 0]))
+    ),
+    refractiveIndex: Math.max(
+      1,
+      readFinite(options.refractiveIndex ?? options.ior, 1.45)
+    )
+  });
+  const continuation = evaluateWavefrontContinuationEvent({
+    ...options,
+    albedo: material.albedo,
+    roughness: material.roughness,
+    metalness: material.metalness,
+    opacity: material.opacity,
+    transmission: material.transmission,
+    refractiveIndex: material.refractiveIndex
+  });
+  const terminal = evaluateWavefrontTerminalRadiance({
+    ...options,
+    emission: material.emission
+  });
+  return Object.freeze({
+    material,
+    terminal,
+    continuation,
+    throughputUpdate: continuation.nextThroughput
+  });
+}
+function createWavefrontReferenceFixture(options = {}) {
+  const tolerance = Math.max(1e-4, readFinite(options.tolerance, 5e-4));
+  const ray = createWavefrontRayPayload({
+    rayId: options.rayId,
+    parentRayId: options.parentRayId,
+    sourcePixelId: options.sourcePixelId,
+    sampleId: options.sampleId,
+    bounce: options.bounceIndex ?? options.bounce,
+    origin: options.origin,
+    direction: options.direction ?? scaleVec3(options.viewDirection ?? [0, 0, 1], -1),
+    throughput: options.throughput,
+    mediumRefId: options.currentMediumRefId ?? options.mediumRefId,
+    mediumStack: options.mediumStack
+  });
+  const reference = evaluateWavefrontMaterialReference(options);
+  const visibilityProbe = options.visibilityProbe === void 0 ? null : evaluateWavefrontVisibilityProbe({
+    ...options.visibilityProbe,
+    throughput: options.visibilityProbe.throughput ?? ray.throughput
+  });
+  const accumulationRadiance = addVec3(
+    reference.terminal.radiance,
+    visibilityProbe?.contribution ?? [0, 0, 0]
+  );
+  return Object.freeze({
+    tolerance,
+    ray,
+    material: reference.material,
+    continuation: reference.continuation,
+    terminal: reference.terminal,
+    visibilityProbe,
+    accumulation: Object.freeze({
+      sourcePixelId: ray.sourcePixelId,
+      sampleCount: reference.terminal.terminated ? 1 : 0,
+      radiance: Object.freeze(accumulationRadiance),
+      throughput: reference.continuation.nextThroughput,
+      resetEpoch: Math.max(
+        0,
+        Math.trunc(readFinite(options.accumulationResetEpoch, 0))
+      )
+    })
+  });
+}
 var lightingImportanceLevels = Object.freeze([
   "low",
   "medium",
@@ -2657,11 +2967,17 @@ export {
   createLightingProfileModeLadder,
   createWavefrontEnvironmentLightingOptions,
   createWavefrontLightingPlan,
+  createWavefrontRayPayload,
+  createWavefrontReferenceFixture,
+  createWavefrontVisibilityProbeRay,
   defaultAdaptiveLightingProfilePolicy,
   defaultLightingProfile,
   defaultLightingTechnique,
   evaluateWavefrontContinuationEvent,
+  evaluateWavefrontMaterialReference,
+  evaluateWavefrontMediumState,
   evaluateWavefrontTerminalRadiance,
+  evaluateWavefrontVisibilityProbe,
   getLightingProfile,
   getLightingProfileWorkerManifest,
   getLightingTechnique,
@@ -2688,9 +3004,11 @@ export {
   lightingWavefrontHitTypes,
   lightingWavefrontPassOrder,
   lightingWavefrontQueuePairStrategy,
+  lightingWavefrontRayKinds,
   lightingWavefrontSchemaVersion,
   lightingWavefrontTerminalHitTypes,
   lightingWavefrontTerminationPolicy,
+  lightingWavefrontVisibilityProbeModes,
   lightingWorkerManifests,
   lightingWorkerQueueClass,
   loadLightingJobs,