@aura3d/rendering 1.4.0 → 1.4.2

package/src/ShadowMap.ts

@@ -1,237 +0,0 @@
-import { Texture } from "./Texture";
-
-export type ShadowFilterMode = "none" | "pcf";
-export type ShadowFilterDistribution = "grid" | "poisson";
-
-export interface ShadowFilterSample {
-  readonly x: number;
-  readonly y: number;
-  readonly weight: number;
-}
-
-export interface ShadowFilterKernel {
-  readonly mode: ShadowFilterMode;
-  readonly distribution: ShadowFilterDistribution;
-  readonly radius: number;
-  readonly samples: readonly ShadowFilterSample[];
-}
-
-export interface ShadowMapOptions {
-  readonly size?: number;
-  readonly bias?: number;
-  readonly filter?: ShadowFilterMode;
-  readonly pcfRadius?: number;
-  readonly pcfSamples?: number;
-  readonly pcfDistribution?: ShadowFilterDistribution;
-  readonly label?: string;
-}
-
-export interface ShadowAtlasRequest {
-  readonly id: string;
-  readonly size: number;
-  readonly cascadeIndex?: number;
-}
-
-export interface ShadowAtlasAllocation extends ShadowAtlasRequest {
-  readonly x: number;
-  readonly y: number;
-  readonly width: number;
-  readonly height: number;
-}
-
-export interface ShadowAtlasLayout {
-  readonly atlasSize: number;
-  readonly allocations: readonly ShadowAtlasAllocation[];
-  readonly utilization: number;
-}
-
-export class ShadowMap {
-  public readonly texture: Texture;
-  public readonly bias: number;
-  public readonly filterKernel: ShadowFilterKernel;
-
-  constructor(options: ShadowMapOptions = {}) {
-    const size = options.size ?? 1024;
-    if (!Number.isInteger(size) || size <= 0) {
-      throw new RangeError("ShadowMap size must be a positive integer");
-    }
-    const bias = options.bias ?? 0.001;
-    if (!Number.isFinite(bias) || bias < 0) {
-      throw new RangeError("ShadowMap bias must be finite and non-negative");
-    }
-    this.bias = bias;
-    this.filterKernel = createShadowFilterKernel(options);
-    this.texture = new Texture({ width: size, height: size, format: "depth24", label: options.label ?? "shadow-map" });
-  }
-
-  get size(): number {
-    return this.texture.width;
-  }
-
-  resize(size: number): ShadowMap {
-    this.dispose();
-    return new ShadowMap({
-      size,
-      bias: this.bias,
-      filter: this.filterKernel.mode,
-      pcfRadius: this.filterKernel.radius,
-      pcfSamples: this.filterKernel.samples.length,
-      pcfDistribution: this.filterKernel.distribution,
-      label: this.texture.label
-    });
-  }
-
-  dispose(): void {
-    this.texture.dispose();
-  }
-}
-
-export function createShadowAtlasLayout(requests: readonly ShadowAtlasRequest[], atlasSize: number): ShadowAtlasLayout {
-  if (!Number.isInteger(atlasSize) || atlasSize <= 0) {
-    throw new RangeError("Shadow atlas size must be a positive integer");
-  }
-  const normalized = requests.map((request) => {
-    if (!request.id.trim()) throw new Error("Shadow atlas request id is required");
-    if (!Number.isInteger(request.size) || request.size <= 0) throw new RangeError("Shadow atlas request size must be a positive integer");
-    if (request.size > atlasSize) throw new RangeError("Shadow atlas request size cannot exceed atlas size");
-    if (request.cascadeIndex !== undefined && (!Number.isInteger(request.cascadeIndex) || request.cascadeIndex < 0)) {
-      throw new RangeError("Shadow atlas cascadeIndex must be a non-negative integer when provided");
-    }
-    return request;
-  }).sort((left, right) => {
-    const leftCascade = left.cascadeIndex ?? Number.MAX_SAFE_INTEGER;
-    const rightCascade = right.cascadeIndex ?? Number.MAX_SAFE_INTEGER;
-    if (leftCascade !== rightCascade) return leftCascade - rightCascade;
-    if (left.size !== right.size) return right.size - left.size;
-    return left.id.localeCompare(right.id);
-  });
-
-  const allocations: ShadowAtlasAllocation[] = [];
-  let cursorX = 0;
-  let cursorY = 0;
-  let rowHeight = 0;
-  for (const request of normalized) {
-    if (cursorX + request.size > atlasSize) {
-      cursorX = 0;
-      cursorY += rowHeight;
-      rowHeight = 0;
-    }
-    if (cursorY + request.size > atlasSize) {
-      throw new RangeError("Shadow atlas requests do not fit in the atlas");
-    }
-    allocations.push({
-      ...request,
-      x: cursorX,
-      y: cursorY,
-      width: request.size,
-      height: request.size
-    });
-    cursorX += request.size;
-    rowHeight = Math.max(rowHeight, request.size);
-  }
-  const usedArea = allocations.reduce((sum, allocation) => sum + allocation.width * allocation.height, 0);
-  return {
-    atlasSize,
-    allocations,
-    utilization: Number((usedArea / (atlasSize * atlasSize)).toFixed(6))
-  };
-}
-
-export function createShadowFilterKernel(options: Pick<ShadowMapOptions, "filter" | "pcfRadius" | "pcfSamples" | "pcfDistribution"> = {}): ShadowFilterKernel {
-  const mode = options.filter ?? "none";
-  if (mode !== "none" && mode !== "pcf") {
-    throw new RangeError(`Unsupported shadow filter mode: ${String(mode)}`);
-  }
-  if (mode === "none") {
-    return {
-      mode,
-      distribution: "grid",
-      radius: 0,
-      samples: [{ x: 0, y: 0, weight: 1 }]
-    };
-  }
-
-  const radius = options.pcfRadius ?? 1;
-  if (!Number.isFinite(radius) || radius <= 0 || radius > 8) {
-    throw new RangeError("ShadowMap pcfRadius must be finite and greater than zero up to 8 texels");
-  }
-
-  const sampleCount = options.pcfSamples ?? 9;
-  const distribution = options.pcfDistribution ?? "grid";
-  if (distribution !== "grid" && distribution !== "poisson") {
-    throw new RangeError(`Unsupported shadow filter distribution: ${String(distribution)}`);
-  }
-  if (distribution === "poisson") {
-    return {
-      mode,
-      distribution,
-      radius,
-      samples: createPoissonDiskShadowKernel(sampleCount, radius)
-    };
-  }
-  const gridSize = Math.sqrt(sampleCount);
-  if (!Number.isInteger(sampleCount) || sampleCount <= 0 || !Number.isInteger(gridSize) || gridSize < 2 || gridSize > 5) {
-    throw new RangeError("ShadowMap pcfSamples must be a square grid sample count between 4 and 25");
-  }
-
-  const half = (gridSize - 1) / 2;
-  const unweighted: ShadowFilterSample[] = [];
-  for (let y = 0; y < gridSize; y += 1) {
-    for (let x = 0; x < gridSize; x += 1) {
-      unweighted.push({
-        x: (x - half) * radius,
-        y: (y - half) * radius,
-        weight: 1 / sampleCount
-      });
-    }
-  }
-  return {
-    mode,
-    distribution,
-    radius,
-    samples: unweighted
-  };
-}
-
-export function createPoissonDiskShadowKernel(sampleCount = 16, radius = 1): readonly ShadowFilterSample[] {
-  if (!Number.isInteger(sampleCount) || sampleCount < 4 || sampleCount > 32) {
-    throw new RangeError("Poisson shadow sample count must be an integer from 4 to 32");
-  }
-  if (!Number.isFinite(radius) || radius <= 0 || radius > 8) {
-    throw new RangeError("Poisson shadow radius must be finite and greater than zero up to 8 texels");
-  }
-  const poisson16 = [
-    [-0.94201624, -0.39906216], [0.94558609, -0.76890725], [-0.0941841, -0.9293887], [0.34495938, 0.2938776],
-    [-0.91588581, 0.45771432], [-0.81544232, -0.87912464], [-0.38277543, 0.27676845], [0.97484398, 0.75648379],
-    [0.44323325, -0.97511554], [0.53742981, -0.4737342], [-0.26496911, -0.41893023], [0.79197514, 0.19090188],
-    [-0.2418884, 0.99706507], [-0.81409955, 0.9143759], [0.19984126, 0.78641367], [0.14383161, -0.1410079]
-  ] as const;
-  const poisson32 = [
-    [-0.975402, -0.0711386], [-0.920347, -0.441282], [-0.883908, 0.217872], [-0.884518, 0.568041],
-    [-0.811945, -0.790709], [-0.792474, 0.0130608], [-0.644704, -0.569165], [-0.634888, 0.682157],
-    [-0.624807, -0.238616], [-0.590539, 0.327366], [-0.504396, -0.863621], [-0.454499, 0.875562],
-    [-0.416458, -0.0370163], [-0.345554, -0.670523], [-0.272745, 0.535116], [-0.238006, -0.369068],
-    [-0.190885, 0.918882], [-0.149278, 0.0543955], [0.00910668, -0.869337], [0.0293372, 0.358103],
-    [0.0968844, -0.0888426], [0.185344, -0.536082], [0.239055, 0.717623], [0.301938, -0.281269],
-    [0.392248, 0.0857121], [0.487048, -0.733963], [0.549342, 0.478623], [0.625366, -0.0596615],
-    [0.688151, -0.462789], [0.736279, 0.253616], [0.816755, 0.604563], [0.897866, -0.192168]
-  ] as const;
-  const base = sampleCount <= 16 ? poisson16 : poisson32;
-  const weight = 1 / sampleCount;
-  return base.slice(0, sampleCount).map(([x, y]) => ({ x: Number((x * radius).toFixed(6)), y: Number((y * radius).toFixed(6)), weight }));
-}
-
-export function computeShadowDepthBias(options: {
-  readonly baseBias: number;
-  readonly slopeScale?: number;
-  readonly normalDotLight: number;
-  readonly texelSize?: number;
-}): number {
-  const slopeScale = options.slopeScale ?? 1;
-  const texelSize = options.texelSize ?? 1;
-  if (!Number.isFinite(options.baseBias) || options.baseBias < 0) throw new RangeError("Shadow baseBias must be finite and non-negative");
-  if (!Number.isFinite(slopeScale) || slopeScale < 0) throw new RangeError("Shadow slopeScale must be finite and non-negative");
-  if (!Number.isFinite(texelSize) || texelSize <= 0) throw new RangeError("Shadow texelSize must be finite and positive");
-  const grazing = 1 - Math.max(0, Math.min(1, options.normalDotLight));
-  return Number((options.baseBias + grazing * slopeScale * texelSize).toFixed(8));
-}

package/src/ShadowPass.ts

@@ -1,198 +0,0 @@
-import { Light } from "@aura3d/scene";
-import { DepthPass } from "./DepthPass";
-import { type ForwardShadowMapOptions, type RenderItem } from "./ForwardPass";
-import { Material } from "./Material";
-import { MaterialInstance } from "./MaterialInstance";
-import { type RenderDeviceDiagnostics, type RenderTarget } from "./RenderDevice";
-import { type RenderPassContext } from "./RenderPass";
-import { Sampler } from "./Sampler";
-import { ShadowMap } from "./ShadowMap";
-import { type ShaderLibrary } from "./ShaderLibrary";
-import { TextureBinding } from "./TextureBinding";
-
-export interface ShadowPassOptions {
-  readonly light: Light | null;
-  readonly casters: readonly RenderItem[];
-  readonly shadowMap?: ShadowMap;
-  readonly shaderLibrary?: ShaderLibrary;
-  readonly viewProjectionMatrix?: Float32Array | readonly number[];
-}
-
-export interface ShadowPassResult {
-  readonly rendered: boolean;
-  readonly reason: ShadowPassReason;
-  readonly casterCount: number;
-  readonly skippedTransparentCasters: number;
-  readonly targetBacked: boolean;
-  readonly shadowTextureLabel?: string;
-  readonly shadowTextureKind?: ShadowTextureKind;
-  readonly diagnostics: RenderDeviceDiagnostics;
-}
-
-export type ShadowPassReason = "rendered" | "no-light" | "light-disabled" | "not-shadow-casting" | "no-casters" | "no-opaque-casters";
-export type ShadowTextureKind = "depth-texture" | "encoded-color-depth";
-
-export class ShadowPass {
-  public readonly shadowMap: ShadowMap;
-  private lastResult: ShadowPassResult | null = null;
-  private renderTarget: RenderTarget | null = null;
-
-  constructor(private readonly options: ShadowPassOptions) {
-    this.shadowMap = options.shadowMap ?? new ShadowMap();
-  }
-
-  execute(context: RenderPassContext): ShadowPassResult {
-    const skipReason = this.getSkipReason();
-    if (skipReason) {
-      this.lastResult = {
-        rendered: false,
-        reason: skipReason,
-        casterCount: 0,
-        skippedTransparentCasters: 0,
-        targetBacked: false,
-        diagnostics: context.device.getDiagnostics()
-      };
-      return this.lastResult;
-    }
-
-    const opaqueCasters = this.options.casters.filter((caster) => !isTransparentCaster(caster));
-    const skippedTransparentCasters = this.options.casters.length - opaqueCasters.length;
-    if (opaqueCasters.length === 0) {
-      this.lastResult = {
-        rendered: false,
-        reason: "no-opaque-casters",
-        casterCount: 0,
-        skippedTransparentCasters,
-        targetBacked: false,
-        diagnostics: context.device.getDiagnostics()
-      };
-      return this.lastResult;
-    }
-
-    const ownsFrame = context.device.captureState().get("frameActive") === false;
-    if (ownsFrame) {
-      context.device.beginFrame(context.width, context.height);
-    }
-    try {
-      return this.executeWithinFrame(context, opaqueCasters, skippedTransparentCasters);
-    } finally {
-      if (ownsFrame) {
-        context.device.endFrame();
-      }
-    }
-  }
-
-  private executeWithinFrame(context: RenderPassContext, opaqueCasters: readonly RenderItem[], skippedTransparentCasters: number): ShadowPassResult {
-    const target = this.ensureRenderTarget(context);
-    context.device.setRenderTarget(target);
-    initializeShadowTarget(context, target);
-    const depthOptions = this.options.shaderLibrary
-      ? { casters: opaqueCasters, shaderLibrary: this.options.shaderLibrary, viewProjectionMatrix: this.options.viewProjectionMatrix }
-      : { casters: opaqueCasters, viewProjectionMatrix: this.options.viewProjectionMatrix };
-    const pass = new DepthPass(depthOptions);
-    pass.execute(context);
-    context.device.setRenderTarget(null);
-    this.lastResult = {
-      rendered: true,
-      reason: "rendered",
-      casterCount: opaqueCasters.length,
-      skippedTransparentCasters,
-      targetBacked: true,
-      shadowTextureLabel: shadowTextureForTarget(target).label,
-      shadowTextureKind: target.depthTexture ? "depth-texture" : "encoded-color-depth",
-      diagnostics: context.device.getDiagnostics()
-    };
-    return this.lastResult;
-  }
-
-  getLastResult(): ShadowPassResult | null {
-    return this.lastResult;
-  }
-
-  getRenderTarget(): RenderTarget | null {
-    return this.renderTarget;
-  }
-
-  getForwardShadowMap(options: Omit<ForwardShadowMapOptions, "texture" | "bias" | "filterKernel"> & {
-    readonly bias?: number;
-    readonly filterKernel?: ForwardShadowMapOptions["filterKernel"];
-  }): ForwardShadowMapOptions | null {
-    if (!this.renderTarget || !this.lastResult?.rendered) {
-      return null;
-    }
-    return {
-      ...options,
-      bias: options.bias ?? this.shadowMap.bias,
-      filterKernel: options.filterKernel ?? this.shadowMap.filterKernel,
-      texture: new TextureBinding({
-        name: "u_shadowMapTexture",
-        texture: shadowTextureForTarget(this.renderTarget),
-        sampler: new Sampler({ minFilter: "nearest", magFilter: "nearest", addressU: "clamp-to-edge", addressV: "clamp-to-edge" }),
-        required: true
-      })
-    };
-  }
-
-  dispose(): void {
-    this.renderTarget?.dispose();
-    this.renderTarget = null;
-    this.shadowMap.dispose();
-  }
-
-  private ensureRenderTarget(context: RenderPassContext): RenderTarget {
-    if (this.renderTarget && !this.renderTarget.disposed && this.renderTarget.width === this.shadowMap.size && this.renderTarget.height === this.shadowMap.size) {
-      return this.renderTarget;
-    }
-    this.renderTarget?.dispose();
-    this.renderTarget = context.device.createRenderTarget({
-      width: this.shadowMap.size,
-      height: this.shadowMap.size,
-      label: `${this.shadowMap.texture.label}-depth-color`,
-      format: "rgba8",
-      depth: context.device.info.capabilities?.includes("depth-textures") ? "texture" : true
-    });
-    return this.renderTarget;
-  }
-
-  private getSkipReason(): ShadowPassResult["reason"] | null {
-    const light = this.options.light;
-    if (!light) {
-      return "no-light";
-    }
-    if (!light.visible) {
-      return "light-disabled";
-    }
-    if (!light.castsShadow) {
-      return "not-shadow-casting";
-    }
-    if (this.options.casters.length === 0) {
-      return "no-casters";
-    }
-    return null;
-  }
-}
-
-function shadowTextureForTarget(target: RenderTarget) {
-  return target.depthTexture ?? target.colorTexture;
-}
-
-function initializeShadowTarget(context: RenderPassContext, target: RenderTarget): void {
-  context.device.setRenderTarget(target);
-  if (context.device.clearRenderTarget) {
-    context.device.clearRenderTarget([1, 1, 1, 1]);
-  } else {
-    context.device.clear([1, 1, 1, 1]);
-  }
-}
-
-function isTransparentCaster(caster: RenderItem): boolean {
-  if (!caster.material) {
-    return false;
-  }
-  const material = getBaseMaterial(caster.material);
-  return material.renderState.blend;
-}
-
-function getBaseMaterial(material: Material | MaterialInstance): Material {
-  return material instanceof MaterialInstance ? material.baseMaterial : material;
-}

package/src/ShadowProjection.ts

@@ -1,115 +0,0 @@
-import { type Bounds3 } from "./Geometry";
-
-export type Vec3Tuple = readonly [number, number, number];
-
-export interface ShadowProjectionOptions {
-  readonly casterBounds: Bounds3;
-  readonly lightDirection: Vec3Tuple;
-  readonly receiverPlaneY?: number;
-}
-
-export interface ShadowProjection {
-  readonly points: readonly Vec3Tuple[];
-  readonly bounds: Bounds3;
-}
-
-const epsilon = 1e-6;
-
-export class ShadowProjectionBuilder {
-  projectBounds(options: ShadowProjectionOptions): ShadowProjection {
-    const receiverPlaneY = options.receiverPlaneY ?? 0;
-    const direction = normalize(options.lightDirection);
-    if (Math.abs(direction[1]) < epsilon) {
-      throw new Error("Shadow projection requires a light direction that intersects the receiver plane.");
-    }
-
-    const projected = corners(options.casterBounds)
-      .map((point) => projectPointToPlane(point, direction, receiverPlaneY))
-      .filter((point) => isFiniteVec3(point));
-    if (projected.length === 0) {
-      throw new Error("Shadow projection produced no finite points.");
-    }
-
-    const hull2d = convexHull(projected.map((point) => [point[0], point[2]] as const));
-    const points = hull2d.map(([x, z]) => [x, receiverPlaneY, z] as const);
-    return {
-      points,
-      bounds: boundsFromPoints(points)
-    };
-  }
-}
-
-function projectPointToPlane(point: Vec3Tuple, direction: Vec3Tuple, receiverPlaneY: number): Vec3Tuple {
-  const t = (receiverPlaneY - point[1]) / direction[1];
-  return [point[0] + direction[0] * t, receiverPlaneY, point[2] + direction[2] * t];
-}
-
-function corners(bounds: Bounds3): readonly Vec3Tuple[] {
-  const min = bounds.min;
-  const max = bounds.max;
-  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 boundsFromPoints(points: readonly Vec3Tuple[]): Bounds3 {
-  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) {
-    min[0] = Math.min(min[0], point[0]);
-    min[1] = Math.min(min[1], point[1]);
-    min[2] = Math.min(min[2], point[2]);
-    max[0] = Math.max(max[0], point[0]);
-    max[1] = Math.max(max[1], point[1]);
-    max[2] = Math.max(max[2], point[2]);
-  }
-  return { min, max };
-}
-
-function convexHull(points: readonly (readonly [number, number])[]): readonly (readonly [number, number])[] {
-  const sorted = [...new Map(points.map((point) => [`${point[0]},${point[1]}`, point] as const)).values()].sort(
-    (a, b) => a[0] - b[0] || a[1] - b[1]
-  );
-  if (sorted.length <= 1) {
-    return sorted;
-  }
-  const lower: (readonly [number, number])[] = [];
-  for (const point of sorted) {
-    while (lower.length >= 2 && cross(lower[lower.length - 2]!, lower[lower.length - 1]!, point) <= 0) {
-      lower.pop();
-    }
-    lower.push(point);
-  }
-  const upper: (readonly [number, number])[] = [];
-  for (let index = sorted.length - 1; index >= 0; index -= 1) {
-    const point = sorted[index]!;
-    while (upper.length >= 2 && cross(upper[upper.length - 2]!, upper[upper.length - 1]!, point) <= 0) {
-      upper.pop();
-    }
-    upper.push(point);
-  }
-  return [...lower.slice(0, -1), ...upper.slice(0, -1)];
-}
-
-function cross(origin: readonly [number, number], a: readonly [number, number], b: readonly [number, number]): number {
-  return (a[0] - origin[0]) * (b[1] - origin[1]) - (a[1] - origin[1]) * (b[0] - origin[0]);
-}
-
-function normalize(value: Vec3Tuple): Vec3Tuple {
-  const length = Math.hypot(value[0], value[1], value[2]);
-  if (length <= epsilon) {
-    throw new Error("Shadow projection light direction cannot be zero.");
-  }
-  return [value[0] / length, value[1] / length, value[2] / length];
-}
-
-function isFiniteVec3(value: Vec3Tuple): boolean {
-  return Number.isFinite(value[0]) && Number.isFinite(value[1]) && Number.isFinite(value[2]);
-}