@forgeax/engine-render 0.1.7 → 0.1.20

package/src/transmission/inspection.ts

@@ -0,0 +1,190 @@
+import type {
+  TransmissionBackdropExtent,
+  TransmissionBackdropTopology,
+  TransmissionCandidateAdmissionInspection,
+  TransmissionCapabilityFact,
+  TransmissionCapabilityVerdict,
+  TransmissionLifecycleState,
+  TransmissionRecoveryState,
+} from './backdrop';
+import type { TransmissionDemand } from './projection';
+
+export type {
+  TransmissionBackdropExtent,
+  TransmissionCandidateAdmissionInspection,
+  TransmissionLifecycleState,
+  TransmissionRecoveryState,
+} from './backdrop';
+
+export interface TransmissionInspection {
+  readonly activeCount: number;
+  readonly needsRoughMips: boolean;
+  readonly extent: TransmissionBackdropExtent;
+  readonly format: string;
+  /** Total resident mip levels, including level zero. */
+  readonly mipCount: number;
+  readonly bytes: number;
+  readonly copyCount: number;
+  readonly transmissionDrawCount: number;
+  readonly fallbackCount: number;
+  readonly generation: number;
+  readonly singleLayer: true;
+  readonly lifecycle: TransmissionLifecycleState;
+  readonly lastKnownGood: boolean;
+  readonly recovery: TransmissionRecoveryState;
+  readonly capability: TransmissionCapabilityVerdict;
+}
+
+export interface TransmissionInspectionInput {
+  readonly demand: TransmissionDemand;
+  readonly topology: Pick<TransmissionBackdropTopology, 'active' | 'copyCount' | 'mipCount'>;
+  readonly extent: TransmissionBackdropExtent;
+  readonly generation: number;
+  readonly lastKnownGood: boolean;
+  readonly recovery: TransmissionRecoveryState;
+  readonly lifecycle?: TransmissionLifecycleState;
+  /** Whether a committed physical backdrop is resident on the active device. */
+  readonly resourcePresent?: boolean;
+  readonly format?: string;
+  /** Override only when the resource receipt reports the actual total. */
+  readonly mipCount?: number;
+  /** Override only when the resource receipt reports the actual allocation. */
+  readonly bytes?: number;
+  readonly transmissionDrawCount?: number;
+  readonly fallbackCount?: number;
+  readonly capability?: TransmissionCapabilityVerdict;
+}
+
+export interface TransmissionInspectionFromAdmissionInput {
+  readonly admission: TransmissionCandidateAdmissionInspection;
+  readonly topology: TransmissionInspectionInput['topology'];
+  readonly extent: TransmissionBackdropExtent;
+  readonly transmissionDrawCount?: number;
+  readonly fallbackCount?: number;
+}
+
+const RGBA16FLOAT_BYTES_PER_PIXEL = 8;
+
+function assertNonNegativeInteger(name: string, value: number): void {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error(`${name} must be a non-negative integer`);
+  }
+}
+
+function assertExtent(extent: TransmissionBackdropExtent): void {
+  if (!Number.isInteger(extent.width) || extent.width <= 0) {
+    throw new Error('transmission inspection extent.width must be a positive integer');
+  }
+  if (!Number.isInteger(extent.height) || extent.height <= 0) {
+    throw new Error('transmission inspection extent.height must be a positive integer');
+  }
+}
+
+function mipExtent(value: number, level: number): number {
+  return Math.max(1, Math.floor(value / 2 ** level));
+}
+
+export function estimateTransmissionBackdropBytes(
+  extent: TransmissionBackdropExtent,
+  mipCount: number,
+  format = 'rgba16float',
+): number {
+  assertExtent(extent);
+  assertNonNegativeInteger('transmission inspection mipCount', mipCount);
+  if (format !== 'rgba16float' || mipCount === 0) return 0;
+
+  let bytes = 0;
+  for (let level = 0; level < mipCount; level += 1) {
+    bytes += mipExtent(extent.width, level) * mipExtent(extent.height, level);
+  }
+  return bytes * RGBA16FLOAT_BYTES_PER_PIXEL;
+}
+
+function copyCapability(capability: TransmissionCapabilityVerdict): TransmissionCapabilityVerdict {
+  return capability.ok
+    ? { ok: true, missing: [] }
+    : { ok: false, missing: [...capability.missing] as TransmissionCapabilityFact[] };
+}
+
+function defaultLifecycle(active: boolean, lastKnownGood: boolean): TransmissionLifecycleState {
+  if (!active) return 'inactive';
+  return lastKnownGood ? 'resident' : 'failed';
+}
+
+/**
+ * Project the last completed backdrop facts into a detached, stable POD.
+ * Demand and copy/mip topology are read from their existing owners; this
+ * function never accepts a texture, view, encoder, queue, or graph handle.
+ */
+export function inspectTransmission(input: TransmissionInspectionInput): TransmissionInspection {
+  const active = input.demand.activeCount > 0;
+  if (input.topology.active !== active) {
+    throw new Error('transmission inspection demand and topology are inconsistent');
+  }
+  assertNonNegativeInteger('transmission inspection generation', input.generation);
+  assertNonNegativeInteger(
+    'transmission inspection transmissionDrawCount',
+    input.transmissionDrawCount ?? 0,
+  );
+  assertNonNegativeInteger('transmission inspection fallbackCount', input.fallbackCount ?? 0);
+  assertExtent(input.extent);
+
+  const format = input.format ?? 'rgba16float';
+  const resourcePresent = input.resourcePresent ?? input.lastKnownGood;
+  const mipCount = resourcePresent ? (input.mipCount ?? input.topology.mipCount + 1) : 0;
+  assertNonNegativeInteger('transmission inspection mipCount', mipCount);
+  const bytes = resourcePresent
+    ? (input.bytes ?? estimateTransmissionBackdropBytes(input.extent, mipCount, format))
+    : 0;
+  assertNonNegativeInteger('transmission inspection bytes', bytes);
+  const copyCount = resourcePresent ? input.topology.copyCount : 0;
+  if (copyCount !== (resourcePresent ? 1 : 0)) {
+    throw new Error('transmission inspection copy count does not match backdrop topology');
+  }
+
+  return Object.freeze({
+    activeCount: input.demand.activeCount,
+    needsRoughMips: active && input.demand.needsRoughMips,
+    extent: Object.freeze({ ...input.extent }),
+    format,
+    mipCount,
+    bytes,
+    copyCount,
+    transmissionDrawCount: input.transmissionDrawCount ?? 0,
+    fallbackCount: input.fallbackCount ?? 0,
+    generation: input.generation,
+    singleLayer: true,
+    lifecycle: input.lifecycle ?? defaultLifecycle(active, input.lastKnownGood),
+    lastKnownGood: input.lastKnownGood,
+    recovery: input.recovery,
+    capability: copyCapability(input.capability ?? { ok: true, missing: [] }),
+  });
+}
+
+export function inspectTransmissionFromAdmission(
+  input: TransmissionInspectionFromAdmissionInput,
+): TransmissionInspection {
+  const resource = input.admission.resource;
+  return inspectTransmission({
+    demand: input.admission.demand,
+    topology: input.topology,
+    extent: resource?.extent ?? input.extent,
+    ...(resource === undefined
+      ? {}
+      : { format: resource.format, mipCount: resource.mipCount, bytes: resource.bytes }),
+    resourcePresent: resource !== undefined,
+    generation: input.admission.generation,
+    lifecycle: input.admission.lifecycle,
+    lastKnownGood: input.admission.lastKnownGood,
+    recovery: input.admission.recovery,
+    capability: input.admission.capability,
+    ...(input.transmissionDrawCount === undefined
+      ? {}
+      : { transmissionDrawCount: input.transmissionDrawCount }),
+    ...(input.fallbackCount === undefined ? {} : { fallbackCount: input.fallbackCount }),
+  });
+}
+
+export function transmissionInspectionToJson(inspection: TransmissionInspection): string {
+  return JSON.stringify(inspection);
+}

package/src/transmission/oracle.ts

@@ -0,0 +1,141 @@
+/** Pure CPU expectations for transmission math; this module has no GPU ownership. */
+
+export type Color3 = readonly [number, number, number];
+export type Uv2 = readonly [number, number];
+
+export const DEFAULT_IOR = 1.5;
+export const DEFAULT_GUARD_BAND = 0.02;
+
+export interface TransmissionEnergy {
+  readonly reflection: number;
+  readonly transmission: number;
+  readonly diffuse: number;
+  readonly metallicResidual: number;
+}
+
+export interface BackdropResolution {
+  readonly source: 'refracted' | 'environment' | 'unrefracted';
+  readonly color: Color3;
+}
+
+export interface BackdropInputs {
+  readonly uv: Uv2;
+  readonly refracted?: Color3;
+  readonly environment?: Color3;
+  readonly unrefracted: Color3;
+  readonly guardBand?: number;
+}
+
+const clamp01 = (value: number): number => Math.min(Math.max(value, 0), 1);
+
+const finiteOr = (value: number, fallback: number): number =>
+  Number.isFinite(value) ? value : fallback;
+
+const safeIor = (ior: number): number => {
+  const candidate = finiteOr(ior, DEFAULT_IOR);
+  return candidate >= 1 ? candidate : DEFAULT_IOR;
+};
+
+/** Returns dielectric F0 for air to a material with the supplied IOR. */
+export function fresnelF0(ior: number): number {
+  const ratio = (safeIor(ior) - 1) / (safeIor(ior) + 1);
+  return ratio * ratio;
+}
+
+/**
+ * Returns unpolarized dielectric reflectance. `eta` is incident IOR divided
+ * by transmitted IOR, so values above one can produce total internal
+ * reflection. This is a CPU oracle only; it does not sample a GPU resource.
+ */
+export function fresnelReflectance(cosTheta: number, eta: number): number {
+  if (!Number.isFinite(cosTheta) || !Number.isFinite(eta) || eta <= 0) return 1;
+
+  const cosIncident = clamp01(cosTheta);
+  const sinTransmittedSquared = eta * eta * (1 - cosIncident * cosIncident);
+  if (sinTransmittedSquared >= 1) return 1;
+
+  const cosTransmitted = Math.sqrt(Math.max(0, 1 - sinTransmittedSquared));
+  const perpendicularDenominator = cosIncident + eta * cosTransmitted;
+  const parallelDenominator = eta * cosIncident + cosTransmitted;
+  if (perpendicularDenominator === 0 || parallelDenominator === 0) return 1;
+
+  const perpendicular = (cosIncident - eta * cosTransmitted) / perpendicularDenominator;
+  const parallel = (eta * cosIncident - cosTransmitted) / parallelDenominator;
+  return clamp01((perpendicular * perpendicular + parallel * parallel) / 2);
+}
+
+export function splitTransmissionEnergy(input: {
+  readonly transmission: number;
+  readonly metallic: number;
+  readonly cosTheta: number;
+  readonly ior: number;
+}): TransmissionEnergy {
+  const transmission = clamp01(finiteOr(input.transmission, 0));
+  const metallic = clamp01(finiteOr(input.metallic, 0));
+  const reflectance = fresnelReflectance(input.cosTheta, 1 / safeIor(input.ior));
+  const nonMetal = 1 - metallic;
+  const refracted = (1 - reflectance) * nonMetal;
+
+  return {
+    reflection: reflectance,
+    transmission: refracted * transmission,
+    diffuse: refracted * (1 - transmission),
+    metallicResidual: (1 - reflectance) * metallic,
+  };
+}
+
+export function beerLambertAttenuation(
+  color: Color3,
+  thickness: number,
+  distance?: number,
+): Color3 {
+  if (
+    !Number.isFinite(thickness) ||
+    thickness <= 0 ||
+    distance === undefined ||
+    !Number.isFinite(distance) ||
+    distance <= 0
+  ) {
+    return [1, 1, 1];
+  }
+
+  const exponent = thickness / distance;
+  const attenuate = (component: number): number => {
+    const safeComponent = clamp01(finiteOr(component, 0));
+    return Math.min(Math.max(safeComponent ** exponent, 0), 1);
+  };
+  return [attenuate(color[0]), attenuate(color[1]), attenuate(color[2])];
+}
+
+export function roughnessToLod(roughness: number, maxLod: number): number {
+  const safeRoughness = clamp01(finiteOr(roughness, 0));
+  const safeMaxLod = Math.max(finiteOr(maxLod, 0), 0);
+  return safeRoughness * safeRoughness * safeMaxLod;
+}
+
+export function isWithinGuardBand(uv: Uv2, guardBand = DEFAULT_GUARD_BAND): boolean {
+  if (!uv.every(Number.isFinite) || !Number.isFinite(guardBand)) return false;
+  const band = clamp01(guardBand);
+  return uv.every((coordinate) => coordinate >= band && coordinate <= 1 - band);
+}
+
+export function resolveRefractionBackdrop(input: BackdropInputs): BackdropResolution {
+  if (
+    isWithinGuardBand(input.uv, input.guardBand) &&
+    input.refracted !== undefined &&
+    isFiniteColor(input.refracted)
+  ) {
+    return { source: 'refracted', color: input.refracted };
+  }
+  if (input.environment !== undefined && isFiniteColor(input.environment)) {
+    return { source: 'environment', color: input.environment };
+  }
+  if (isFiniteColor(input.unrefracted)) {
+    return { source: 'unrefracted', color: input.unrefracted };
+  }
+  return { source: 'unrefracted', color: [0, 0, 0] };
+}
+
+export function isFiniteColor(color: Color3): boolean {
+  return color.length === 3 && color.every(Number.isFinite);
+}

package/src/transmission/projection.ts

@@ -0,0 +1,83 @@
+/** The two CPU facts that are allowed to influence transmission topology. */
+export interface TransmissionDemand {
+  readonly activeCount: number;
+  readonly needsRoughMips: boolean;
+}
+
+/** Detached material facts supplied by the persistent render-scene owner. */
+export interface TransmissionDemandCandidate {
+  readonly attached: boolean;
+  readonly ready: boolean;
+  readonly transmission: number;
+  readonly roughness: number;
+}
+
+export type TransmissionDemandOperation =
+  | {
+      readonly kind: 'upsert';
+      readonly key: string;
+      readonly candidate: TransmissionDemandCandidate;
+    }
+  | { readonly kind: 'remove'; readonly key: string };
+
+interface CandidateRecord {
+  readonly active: boolean;
+  readonly rough: boolean;
+}
+
+function candidateRecord(candidate: TransmissionDemandCandidate): CandidateRecord {
+  const active =
+    candidate.attached &&
+    candidate.ready &&
+    Number.isFinite(candidate.transmission) &&
+    candidate.transmission > 0;
+  return {
+    active,
+    rough: active && Number.isFinite(candidate.roughness) && candidate.roughness > 0,
+  };
+}
+
+/**
+ * Incremental CPU projection for transmission topology.
+ *
+ * The projection stores no material, visibility, camera, or GPU object. Each
+ * operation updates the two counters directly; an empty operation list is a
+ * no-scan steady-state frame.
+ */
+export class PersistentTransmissionDemandProjection {
+  private readonly records = new Map<string, CandidateRecord>();
+  private activeCount = 0;
+  private roughCount = 0;
+
+  apply(operations: readonly TransmissionDemandOperation[]): TransmissionDemand {
+    for (const operation of operations) {
+      const previous = this.records.get(operation.key);
+      if (previous !== undefined) this.removeCounts(previous);
+      if (operation.kind === 'remove') {
+        this.records.delete(operation.key);
+        continue;
+      }
+      const next = candidateRecord(operation.candidate);
+      this.records.set(operation.key, next);
+      this.addCounts(next);
+    }
+    return this.inspect();
+  }
+
+  inspect(): TransmissionDemand {
+    return {
+      activeCount: this.activeCount,
+      needsRoughMips: this.roughCount > 0,
+    };
+  }
+
+  private addCounts(record: CandidateRecord): void {
+    if (record.active) this.activeCount += 1;
+    if (record.rough) this.roughCount += 1;
+  }
+
+  private removeCounts(record: CandidateRecord): void {
+    if (record.active) this.activeCount -= 1;
+    if (record.rough) this.roughCount -= 1;
+  }
+}