@aura3d/rendering 1.0.6

package/src/CascadedShadowMaps.ts

@@ -0,0 +1,449 @@
+import { DirectionalLight, Light } from "@aura3d/scene";
+import { type Bounds3 } from "./Geometry";
+import { type RenderItem } from "./ForwardPass";
+import { type RenderDeviceDiagnostics } from "./RenderDevice";
+import { type RenderPassContext } from "./RenderPass";
+import { ShadowMap } from "./ShadowMap";
+import { ShadowPass, type ShadowPassReason } from "./ShadowPass";
+import { type ShaderLibrary } from "./ShaderLibrary";
+
+export interface CascadeSplitOptions {
+  readonly cascadeCount: number;
+  readonly near: number;
+  readonly far: number;
+  readonly lambda?: number;
+}
+
+export interface CascadeSplit {
+  readonly index: number;
+  readonly near: number;
+  readonly far: number;
+}
+
+export interface CascadedShadowMapsOptions extends CascadeSplitOptions {
+  readonly size?: number;
+  readonly bias?: number;
+  readonly filter?: ShadowMap["filterKernel"]["mode"];
+  readonly pcfRadius?: number;
+  readonly pcfSamples?: number;
+  readonly label?: string;
+}
+
+export interface ShadowCascade {
+  readonly index: number;
+  readonly split: CascadeSplit;
+  readonly shadowMap: ShadowMap;
+}
+
+export type ShadowCameraVec3 = readonly [number, number, number];
+
+export interface ShadowCameraFrustumOptions {
+  readonly position: ShadowCameraVec3;
+  readonly target: ShadowCameraVec3;
+  readonly up?: ShadowCameraVec3;
+  readonly fovYRadians: number;
+  readonly aspect: number;
+}
+
+export interface ShadowCameraFitOptions {
+  readonly camera: ShadowCameraFrustumOptions;
+  readonly lightDirection: ShadowCameraVec3;
+  readonly casters: readonly RenderItem[];
+  readonly receivers?: readonly RenderItem[];
+  readonly padding?: number;
+  readonly stabilize?: boolean;
+}
+
+export interface LightSpaceBounds {
+  readonly min: ShadowCameraVec3;
+  readonly max: ShadowCameraVec3;
+}
+
+export interface ShadowCameraFit {
+  readonly cascadeIndex: number;
+  readonly split: CascadeSplit;
+  readonly mapSize: number;
+  readonly texelSize: number;
+  readonly lightDirection: ShadowCameraVec3;
+  readonly basis: {
+    readonly right: ShadowCameraVec3;
+    readonly up: ShadowCameraVec3;
+    readonly forward: ShadowCameraVec3;
+  };
+  readonly frustumCornersWorld: readonly ShadowCameraVec3[];
+  readonly casterBoundsWorld: Bounds3 | null;
+  readonly receiverBoundsWorld: Bounds3 | null;
+  readonly combinedBoundsWorld: Bounds3;
+  readonly lightSpaceBounds: LightSpaceBounds;
+  readonly centerLightSpace: ShadowCameraVec3;
+  readonly snappedCenterLightSpace: ShadowCameraVec3;
+  readonly stableOffsetLightSpace: ShadowCameraVec3;
+  readonly orthographic: {
+    readonly left: number;
+    readonly right: number;
+    readonly bottom: number;
+    readonly top: number;
+    readonly near: number;
+    readonly far: number;
+  };
+  readonly casterCount: number;
+  readonly receiverCount: number;
+}
+
+export class CascadedShadowMaps {
+  private readonly cascades: readonly ShadowCascade[];
+
+  constructor(options: CascadedShadowMapsOptions) {
+    const size = options.size ?? 1024;
+    const bias = options.bias ?? 0.001;
+    const label = options.label ?? "csm";
+    this.cascades = CascadedShadowMaps.computeSplits(options).map((split) => ({
+      index: split.index,
+      split,
+      shadowMap: new ShadowMap({
+        size,
+        bias,
+        filter: options.filter,
+        pcfRadius: options.pcfRadius,
+        pcfSamples: options.pcfSamples,
+        label: `${label}-cascade-${split.index}`
+      })
+    }));
+  }
+
+  static computeSplits(options: CascadeSplitOptions): readonly CascadeSplit[] {
+    const { cascadeCount, near, far, lambda = 0.5 } = options;
+    if (!Number.isInteger(cascadeCount) || cascadeCount <= 0) {
+      throw new Error("Cascade count must be a positive integer");
+    }
+    if (near <= 0 || far <= near) {
+      throw new Error("Cascade near/far range is invalid");
+    }
+    if (lambda < 0 || lambda > 1) {
+      throw new Error("Cascade lambda must be between 0 and 1");
+    }
+
+    const splits: CascadeSplit[] = [];
+    let previous = near;
+    for (let index = 1; index <= cascadeCount; index += 1) {
+      const ratio = index / cascadeCount;
+      const logarithmic = near * (far / near) ** ratio;
+      const uniform = near + (far - near) * ratio;
+      const cascadeFar = index === cascadeCount ? far : lambda * logarithmic + (1 - lambda) * uniform;
+      splits.push({
+        index: index - 1,
+        near: previous,
+        far: cascadeFar
+      });
+      previous = cascadeFar;
+    }
+    return splits;
+  }
+
+  get cascadeCount(): number {
+    return this.cascades.length;
+  }
+
+  getCascades(): readonly ShadowCascade[] {
+    return this.cascades;
+  }
+
+  computeStableCameraFits(options: ShadowCameraFitOptions): readonly ShadowCameraFit[] {
+    return this.cascades.map((cascade) => computeShadowCameraFit(cascade, options));
+  }
+
+  resize(size: number): CascadedShadowMaps {
+    const first = this.cascades[0];
+    if (!first) {
+      throw new Error("Cannot resize cascaded shadow maps without cascades");
+    }
+    const resized = Object.create(CascadedShadowMaps.prototype) as CascadedShadowMaps;
+    Object.assign(resized, {
+      cascades: this.cascades.map((cascade) => ({
+        index: cascade.index,
+        split: cascade.split,
+        shadowMap: cascade.shadowMap.resize(size)
+      }))
+    });
+    return resized;
+  }
+
+  dispose(): void {
+    for (const cascade of this.cascades) {
+      cascade.shadowMap.dispose();
+    }
+  }
+}
+
+function computeShadowCameraFit(cascade: ShadowCascade, options: ShadowCameraFitOptions): ShadowCameraFit {
+  const padding = options.padding ?? 0.25;
+  if (!Number.isFinite(padding) || padding < 0) {
+    throw new Error("Shadow camera fit padding must be finite and non-negative");
+  }
+  const basis = lightBasis(options.lightDirection);
+  const frustumCornersWorld = cameraFrustumCorners(options.camera, cascade.split);
+  const casterBoundsWorld = mergeItemBounds(options.casters);
+  const receiverBoundsWorld = mergeItemBounds(options.receivers ?? []);
+  const combinedBoundsWorld = expandBounds(mergeBounds([boundsFromPoints(frustumCornersWorld), casterBoundsWorld, receiverBoundsWorld]), padding);
+  const lightSpacePoints = corners(combinedBoundsWorld).map((point) => projectToLightSpace(point, basis));
+  const lightSpaceBounds = boundsFromPoints(lightSpacePoints);
+  const centerLightSpace: ShadowCameraVec3 = [
+    (lightSpaceBounds.min[0] + lightSpaceBounds.max[0]) / 2,
+    (lightSpaceBounds.min[1] + lightSpaceBounds.max[1]) / 2,
+    (lightSpaceBounds.min[2] + lightSpaceBounds.max[2]) / 2
+  ];
+  const width = Math.max(1e-6, lightSpaceBounds.max[0] - lightSpaceBounds.min[0]);
+  const height = Math.max(1e-6, lightSpaceBounds.max[1] - lightSpaceBounds.min[1]);
+  const extent = Math.max(width, height);
+  const texelSize = extent / cascade.shadowMap.size;
+  const snappedCenterLightSpace = options.stabilize === false ? centerLightSpace : [
+    snap(centerLightSpace[0], texelSize),
+    snap(centerLightSpace[1], texelSize),
+    centerLightSpace[2]
+  ] as const;
+  const halfExtent = extent / 2;
+  const depthPadding = Math.max(padding, extent * 0.05);
+  return {
+    cascadeIndex: cascade.index,
+    split: cascade.split,
+    mapSize: cascade.shadowMap.size,
+    texelSize,
+    lightDirection: normalize(options.lightDirection),
+    basis,
+    frustumCornersWorld,
+    casterBoundsWorld,
+    receiverBoundsWorld,
+    combinedBoundsWorld,
+    lightSpaceBounds,
+    centerLightSpace,
+    snappedCenterLightSpace,
+    stableOffsetLightSpace: [
+      snappedCenterLightSpace[0] - centerLightSpace[0],
+      snappedCenterLightSpace[1] - centerLightSpace[1],
+      snappedCenterLightSpace[2] - centerLightSpace[2]
+    ],
+    orthographic: {
+      left: snappedCenterLightSpace[0] - halfExtent,
+      right: snappedCenterLightSpace[0] + halfExtent,
+      bottom: snappedCenterLightSpace[1] - halfExtent,
+      top: snappedCenterLightSpace[1] + halfExtent,
+      near: lightSpaceBounds.min[2] - depthPadding,
+      far: lightSpaceBounds.max[2] + depthPadding
+    },
+    casterCount: options.casters.length,
+    receiverCount: options.receivers?.length ?? 0
+  };
+}
+
+function cameraFrustumCorners(camera: ShadowCameraFrustumOptions, split: CascadeSplit): readonly ShadowCameraVec3[] {
+  if (!Number.isFinite(camera.fovYRadians) || camera.fovYRadians <= 0 || camera.fovYRadians >= Math.PI) {
+    throw new Error("Shadow camera fit requires a finite perspective fov in radians");
+  }
+  if (!Number.isFinite(camera.aspect) || camera.aspect <= 0) {
+    throw new Error("Shadow camera fit requires a finite positive aspect ratio");
+  }
+  const forward = normalize(sub(camera.target, camera.position));
+  const right = normalize(cross(forward, camera.up ?? [0, 1, 0]));
+  const up = normalize(cross(right, forward));
+  return [split.near, split.far].flatMap((distance) => {
+    const halfHeight = Math.tan(camera.fovYRadians / 2) * distance;
+    const halfWidth = halfHeight * camera.aspect;
+    const center = add(camera.position, scale(forward, distance));
+    return [
+      add(add(center, scale(right, -halfWidth)), scale(up, -halfHeight)),
+      add(add(center, scale(right, halfWidth)), scale(up, -halfHeight)),
+      add(add(center, scale(right, halfWidth)), scale(up, halfHeight)),
+      add(add(center, scale(right, -halfWidth)), scale(up, halfHeight))
+    ];
+  });
+}
+
+function mergeItemBounds(items: readonly RenderItem[]): Bounds3 | null {
+  const bounds = items.map(worldBoundsForItem);
+  return bounds.length > 0 ? mergeBounds(bounds) : null;
+}
+
+function worldBoundsForItem(item: RenderItem): Bounds3 {
+  return boundsFromPoints(corners(item.geometry.bounds).map((point) => transformPoint(point, item.modelMatrix)));
+}
+
+function transformPoint(point: ShadowCameraVec3, matrix: Float32Array | readonly number[] | undefined): ShadowCameraVec3 {
+  if (!matrix) {
+    return point;
+  }
+  if (matrix.length < 16) {
+    throw new Error("RenderItem modelMatrix must contain 16 numbers for shadow camera fitting");
+  }
+  return [
+    matrix[0]! * point[0] + matrix[4]! * point[1] + matrix[8]! * point[2] + matrix[12]!,
+    matrix[1]! * point[0] + matrix[5]! * point[1] + matrix[9]! * point[2] + matrix[13]!,
+    matrix[2]! * point[0] + matrix[6]! * point[1] + matrix[10]! * point[2] + matrix[14]!
+  ];
+}
+
+function lightBasis(lightDirection: ShadowCameraVec3): ShadowCameraFit["basis"] {
+  const forward = normalize(scale(normalize(lightDirection), -1));
+  const fallbackUp: ShadowCameraVec3 = Math.abs(forward[1]) > 0.94 ? [0, 0, 1] : [0, 1, 0];
+  const right = normalize(cross(fallbackUp, forward));
+  const up = normalize(cross(forward, right));
+  return { right, up, forward };
+}
+
+function projectToLightSpace(point: ShadowCameraVec3, basis: ShadowCameraFit["basis"]): ShadowCameraVec3 {
+  return [dot(point, basis.right), dot(point, basis.up), dot(point, basis.forward)];
+}
+
+function mergeBounds(bounds: readonly (Bounds3 | null)[]): Bounds3 {
+  const filtered = bounds.filter((value): value is Bounds3 => value !== null);
+  if (filtered.length === 0) {
+    throw new Error("Cannot merge empty shadow fitting bounds");
+  }
+  const min: [number, number, number] = [Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY];
+  const max: [number, number, number] = [Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY];
+  for (const bound of filtered) {
+    for (let axis = 0; axis < 3; axis += 1) {
+      min[axis] = Math.min(min[axis]!, bound.min[axis]!);
+      max[axis] = Math.max(max[axis]!, bound.max[axis]!);
+    }
+  }
+  return { min, max };
+}
+
+function expandBounds(bounds: Bounds3, padding: number): Bounds3 {
+  return {
+    min: [bounds.min[0] - padding, bounds.min[1] - padding, bounds.min[2] - padding],
+    max: [bounds.max[0] + padding, bounds.max[1] + padding, bounds.max[2] + padding]
+  };
+}
+
+function boundsFromPoints(points: readonly ShadowCameraVec3[]): Bounds3 {
+  if (points.length === 0) {
+    throw new Error("Cannot compute shadow bounds from no points");
+  }
+  const min: [number, number, number] = [Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY];
+  const max: [number, number, number] = [Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY];
+  for (const point of points) {
+    for (let axis = 0; axis < 3; axis += 1) {
+      min[axis] = Math.min(min[axis]!, point[axis]!);
+      max[axis] = Math.max(max[axis]!, point[axis]!);
+    }
+  }
+  return { min, max };
+}
+
+function corners(bounds: Bounds3): readonly ShadowCameraVec3[] {
+  const { min, max } = bounds;
+  return [
+    [min[0], min[1], min[2]],
+    [max[0], min[1], min[2]],
+    [max[0], max[1], min[2]],
+    [min[0], max[1], min[2]],
+    [min[0], min[1], max[2]],
+    [max[0], min[1], max[2]],
+    [max[0], max[1], max[2]],
+    [min[0], max[1], max[2]]
+  ];
+}
+
+function snap(value: number, increment: number): number {
+  if (!Number.isFinite(increment) || increment <= 0) {
+    return value;
+  }
+  return Math.round(value / increment) * increment;
+}
+
+function add(a: ShadowCameraVec3, b: ShadowCameraVec3): ShadowCameraVec3 {
+  return [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+}
+
+function sub(a: ShadowCameraVec3, b: ShadowCameraVec3): ShadowCameraVec3 {
+  return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+}
+
+function scale(value: ShadowCameraVec3, amount: number): ShadowCameraVec3 {
+  return [value[0] * amount, value[1] * amount, value[2] * amount];
+}
+
+function dot(a: ShadowCameraVec3, b: ShadowCameraVec3): number {
+  return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}
+
+function cross(a: ShadowCameraVec3, b: ShadowCameraVec3): ShadowCameraVec3 {
+  return [
+    a[1] * b[2] - a[2] * b[1],
+    a[2] * b[0] - a[0] * b[2],
+    a[0] * b[1] - a[1] * b[0]
+  ];
+}
+
+function normalize(value: ShadowCameraVec3): ShadowCameraVec3 {
+  const length = Math.hypot(value[0], value[1], value[2]);
+  if (!Number.isFinite(length) || length <= 1e-8) {
+    throw new Error("Shadow camera fitting vector cannot be zero");
+  }
+  return [value[0] / length, value[1] / length, value[2] / length];
+}
+
+export interface CascadedShadowPassOptions {
+  readonly light: Light | null;
+  readonly casters: readonly RenderItem[];
+  readonly cascades: CascadedShadowMaps;
+  readonly shaderLibrary?: ShaderLibrary;
+}
+
+export interface CascadeShadowPassResult {
+  readonly index: number;
+  readonly split: CascadeSplit;
+  readonly rendered: boolean;
+  readonly reason: ShadowPassReason;
+  readonly casterCount: number;
+  readonly skippedTransparentCasters: number;
+  readonly diagnostics: RenderDeviceDiagnostics;
+  readonly shadowMap: ShadowMap;
+}
+
+export interface CascadedShadowPassResult {
+  readonly rendered: boolean;
+  readonly cascades: readonly CascadeShadowPassResult[];
+}
+
+export class CascadedShadowPass {
+  private lastResult: CascadedShadowPassResult | null = null;
+
+  constructor(private readonly options: CascadedShadowPassOptions) {}
+
+  execute(context: RenderPassContext): CascadedShadowPassResult {
+    const cascadeResults = this.options.cascades.getCascades().map((cascade) => {
+      const shadowPass = new ShadowPass({
+        light: this.options.light,
+        casters: this.options.casters,
+        shadowMap: cascade.shadowMap,
+        ...(this.options.shaderLibrary ? { shaderLibrary: this.options.shaderLibrary } : {})
+      });
+      const result = shadowPass.execute(context);
+      return {
+        index: cascade.index,
+        split: cascade.split,
+        rendered: result.rendered,
+        reason: result.reason,
+        casterCount: result.casterCount,
+        skippedTransparentCasters: result.skippedTransparentCasters,
+        diagnostics: result.diagnostics,
+        shadowMap: cascade.shadowMap
+      };
+    });
+    this.lastResult = {
+      rendered: cascadeResults.length > 0 && cascadeResults.every((cascade) => cascade.rendered),
+      cascades: cascadeResults
+    };
+    return this.lastResult;
+  }
+
+  getLastResult(): CascadedShadowPassResult | null {
+    return this.lastResult;
+  }
+}
+
+export function supportsCascadedShadowLight(light: Light | null): light is DirectionalLight {
+  return light instanceof DirectionalLight && light.visible && light.castsShadow;
+}

package/src/ColorManagement.ts

@@ -0,0 +1,127 @@
+export type A3DColorSpace = "linear" | "srgb";
+export type A3DTextureSemantic =
+  | "base-color"
+  | "emissive"
+  | "normal"
+  | "metallic-roughness"
+  | "roughness"
+  | "metallic"
+  | "occlusion"
+  | "height"
+  | "transmission"
+  | "specular"
+  | "sheen"
+  | "anisotropy"
+  | "iridescence"
+  | "environment";
+
+export interface A3DColorManagementPolicy {
+  readonly lightingColorSpace: "linear";
+  readonly outputColorSpace: A3DColorSpace;
+  readonly texturePolicy: Readonly<Record<A3DTextureSemantic, A3DColorSpace>>;
+  readonly allowLdrFallback: boolean;
+  readonly fallbackBehavior: string;
+}
+
+export interface A3DColorConversionSample {
+  readonly input: number;
+  readonly linear: number;
+  readonly srgb: number;
+  readonly roundTripError: number;
+}
+
+export interface A3DTextureColorSpaceValidation {
+  readonly semantic: A3DTextureSemantic;
+  readonly expected: A3DColorSpace;
+  readonly actual: A3DColorSpace;
+  readonly pass: boolean;
+  readonly warning?: string;
+}
+
+export const EXTERNAL_PARITY_TEXTURE_COLOR_POLICY: Readonly<Record<A3DTextureSemantic, A3DColorSpace>> = {
+  "base-color": "srgb",
+  emissive: "srgb",
+  normal: "linear",
+  "metallic-roughness": "linear",
+  roughness: "linear",
+  metallic: "linear",
+  occlusion: "linear",
+  height: "linear",
+  transmission: "linear",
+  specular: "linear",
+  sheen: "srgb",
+  anisotropy: "linear",
+  iridescence: "linear",
+  environment: "linear"
+};
+
+export function createExternalParityColorManagementPolicy(options: {
+  readonly outputColorSpace?: A3DColorSpace;
+  readonly allowLdrFallback?: boolean;
+} = {}): A3DColorManagementPolicy {
+  return {
+    lightingColorSpace: "linear",
+    outputColorSpace: options.outputColorSpace ?? "srgb",
+    texturePolicy: EXTERNAL_PARITY_TEXTURE_COLOR_POLICY,
+    allowLdrFallback: options.allowLdrFallback ?? true,
+    fallbackBehavior: "HDR render targets are preferred. LDR fallback must keep linear lighting and tone-map to the configured output color space."
+  };
+}
+
+export function srgbToLinearChannel(value: number): number {
+  const channel = clamp01(value);
+  return channel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4;
+}
+
+export function linearToSrgbChannel(value: number): number {
+  const channel = clamp01(value);
+  return channel <= 0.0031308 ? channel * 12.92 : 1.055 * channel ** (1 / 2.4) - 0.055;
+}
+
+export function convertColorSpace(
+  color: readonly [number, number, number, number],
+  from: A3DColorSpace,
+  to: A3DColorSpace
+): [number, number, number, number] {
+  if (from === to) return [clamp01(color[0]), clamp01(color[1]), clamp01(color[2]), clamp01(color[3])];
+  const convert = from === "srgb" && to === "linear" ? srgbToLinearChannel : linearToSrgbChannel;
+  return [convert(color[0]), convert(color[1]), convert(color[2]), clamp01(color[3])];
+}
+
+export function validateTextureColorSpace(
+  semantic: A3DTextureSemantic,
+  actual: A3DColorSpace,
+  policy: A3DColorManagementPolicy = createExternalParityColorManagementPolicy()
+): A3DTextureColorSpaceValidation {
+  const expected = policy.texturePolicy[semantic];
+  const pass = expected === actual;
+  return {
+    semantic,
+    expected,
+    actual,
+    pass,
+    ...(pass ? {} : { warning: `${semantic} texture must be tagged ${expected}; received ${actual}.` })
+  };
+}
+
+export function createColorConversionSamples(samples: readonly number[] = [0, 0.0031308, 0.18, 0.5, 1]): readonly A3DColorConversionSample[] {
+  return samples.map((input) => {
+    const linear = srgbToLinearChannel(input);
+    const srgb = linearToSrgbChannel(linear);
+    return {
+      input,
+      linear: round(linear),
+      srgb: round(srgb),
+      roundTripError: round(Math.abs(clamp01(input) - srgb))
+    };
+  });
+}
+
+function clamp01(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.min(1, Math.max(0, value));
+}
+
+function round(value: number): number {
+  return Number(value.toFixed(6));
+}