@aura3d/rendering 1.4.0 → 1.4.2

package/src/Raycaster.ts

@@ -1,21 +0,0 @@
-import { Box3, Ray } from "@aura3d/math";
-
-export interface RaycastTarget<T = unknown> {
-  readonly id: string;
-  readonly bounds: Box3;
-  readonly payload?: T;
-}
-
-export interface RaycastHit<T = unknown> {
-  readonly target: RaycastTarget<T>;
-  readonly distance: number;
-}
-
-export class Raycaster<T = unknown> {
-  intersectBounds(ray: Ray, targets: readonly RaycastTarget<T>[]): readonly RaycastHit<T>[] {
-    return targets
-      .map((target) => ({ target, distance: ray.intersectBox(target.bounds)?.distanceTo(ray.origin) ?? Number.POSITIVE_INFINITY }))
-      .filter((hit) => Number.isFinite(hit.distance))
-      .sort((left, right) => left.distance - right.distance);
-  }
-}

package/src/ReflectionProbe.ts

@@ -1,13 +0,0 @@
-export interface ReflectionProbe {
-  readonly id: string;
-  readonly position: readonly [number, number, number];
-  readonly radius: number;
-  readonly intensity: number;
-}
-
-export function createReflectionProbe(probe: ReflectionProbe): ReflectionProbe {
-  if (!probe.id.trim()) throw new Error("ReflectionProbe id is required.");
-  if (!Number.isFinite(probe.radius) || probe.radius <= 0) throw new Error("ReflectionProbe radius must be positive.");
-  if (!Number.isFinite(probe.intensity) || probe.intensity < 0) throw new Error("ReflectionProbe intensity must be non-negative.");
-  return probe;
-}

package/src/ReflectionSurfaces.ts

@@ -1,219 +0,0 @@
-import { Geometry } from "./Geometry";
-import { PBRMaterial } from "./PBRMaterial";
-import type { RenderItem } from "./ForwardPass";
-import { createReflectionProbe, type ReflectionProbe } from "./ReflectionProbe";
-
-export type ReflectionSurfaceKind =
-  | "planar-reflector"
-  | "reflective-floor"
-  | "refractor-glass"
-  | "water-refraction"
-  | "cube-probe"
-  | "screen-space-reflection";
-
-export type ReflectionSurfaceSupportStatus = "helper" | "unsupported";
-
-export interface ReflectionSurfaceOptions {
-  readonly id: string;
-  readonly kind: ReflectionSurfaceKind;
-  readonly size?: readonly [number, number];
-  readonly y?: number;
-  readonly roughness?: number;
-  readonly metallic?: number;
-  readonly intensity?: number;
-  readonly probe?: ReflectionProbe;
-}
-
-export interface ReflectionSurfaceReport {
-  readonly id: string;
-  readonly kind: ReflectionSurfaceKind;
-  readonly status: ReflectionSurfaceSupportStatus;
-  readonly helper: string;
-  readonly trueReflection: boolean;
-  readonly requiresRendererPath: readonly string[];
-  readonly unsupportedRequests: readonly string[];
-  readonly claimBoundary: string;
-}
-
-export interface ReflectionSurface {
-  readonly id: string;
-  readonly kind: ReflectionSurfaceKind;
-  readonly item?: RenderItem;
-  readonly probe?: ReflectionProbe;
-  readonly report: ReflectionSurfaceReport;
-}
-
-export function createReflectionSurface(options: ReflectionSurfaceOptions): ReflectionSurface {
-  if (!options.id.trim()) throw new Error("Reflection surface id is required.");
-  const kind = options.kind;
-  if (!isReflectionSurfaceKind(kind)) throw new Error(`Unsupported reflection surface kind: ${String(kind)}`);
-
-  if (kind === "reflective-floor") {
-    const size = validateSize(options.size ?? [12, 12]);
-    const y = finite(options.y ?? -0.02, "reflection surface y");
-    const roughness = unit(options.roughness ?? 0.22, "reflection surface roughness");
-    const metallic = unit(options.metallic ?? 0.08, "reflection surface metallic");
-    const intensity = nonNegative(options.intensity ?? 0.42, "reflection surface intensity");
-    return {
-      id: options.id,
-      kind,
-      item: {
-        geometry: Geometry.litCube(1),
-        material: new PBRMaterial({
-          name: `${options.id} staged reflective floor`,
-          baseColor: [0.78, 0.84, 0.9, 1],
-          roughness,
-          metallic,
-          environmentIntensity: intensity
-        }),
-        modelMatrix: scaleTranslate([0, y, 0], [size[0], 0.035, size[1]]),
-        includeInAutoFrame: false,
-        label: `${options.id} staged reflective floor`
-      },
-      report: report(options.id, kind, "helper", "PBR floor material with environment response", false, [
-        "planar-reflector-render-target",
-        "live-cube-probe-capture",
-        "screen-space-reflection-pass"
-      ], [
-        "Reflective floor helper is not a planar reflector and does not render mirrored scene geometry."
-      ])
-    };
-  }
-
-  if (kind === "cube-probe") {
-    const probe = createReflectionProbe(options.probe ?? {
-      id: `${options.id}-probe`,
-      position: [0, 1, 0],
-      radius: 6,
-      intensity: options.intensity ?? 1
-    });
-    return {
-      id: options.id,
-      kind,
-      probe,
-      report: report(options.id, kind, "unsupported", "static probe descriptor only", false, [
-        "six-face-cube-camera-capture",
-        "probe-to-material-binding",
-        "probe-refresh-scheduling"
-      ], [
-        "Live cube-camera probes are unsupported; cube-probe descriptors validate metadata only and do not capture six scene faces."
-      ])
-    };
-  }
-
-  return {
-    id: options.id,
-    kind,
-    report: report(options.id, kind, "unsupported", "claim-boundary descriptor", false, rendererRequirements(kind), unsupportedReflectionRequests(kind))
-  };
-}
-
-export function createReflectiveFloorSurface(
-  id: string,
-  options: Omit<ReflectionSurfaceOptions, "id" | "kind"> = {}
-): ReflectionSurface {
-  return createReflectionSurface({ ...options, id, kind: "reflective-floor" });
-}
-
-export function listReflectionSurfaceKinds(): readonly ReflectionSurfaceKind[] {
-  return ["planar-reflector", "reflective-floor", "refractor-glass", "water-refraction", "cube-probe", "screen-space-reflection"];
-}
-
-function report(
-  id: string,
-  kind: ReflectionSurfaceKind,
-  status: ReflectionSurfaceSupportStatus,
-  helper: string,
-  trueReflection: boolean,
-  requiresRendererPath: readonly string[],
-  unsupportedRequests: readonly string[]
-): ReflectionSurfaceReport {
-  return {
-    id,
-    kind,
-    status,
-    helper,
-    trueReflection,
-    requiresRendererPath,
-    unsupportedRequests,
-    claimBoundary: trueReflection
-      ? "True reflection support must be backed by renderer-owned render targets and route pixel evidence."
-      : "Reusable reflection surface contract only; staged materials, alpha, dark floors, or environment highlights are not proof of planar reflection, SSR, live probes, or scene-space refraction."
-  };
-}
-
-function rendererRequirements(kind: ReflectionSurfaceKind): readonly string[] {
-  switch (kind) {
-    case "planar-reflector":
-      return ["mirror-camera-render-target", "clip-plane-support", "reflector-material-binding"];
-    case "refractor-glass":
-      return ["scene-color-refraction-source", "depth-aware-thickness", "transmission-material-binding"];
-    case "water-refraction":
-      return ["water-reflection-target", "water-refraction-target", "caustic-or-absorption-model"];
-    case "screen-space-reflection":
-      return ["depth-normal-history-inputs", "ssr-ray-march-pass", "temporal-denoise"];
-    case "cube-probe":
-      return ["six-face-cube-camera-capture", "probe-refresh-scheduling"];
-    case "reflective-floor":
-      return ["planar-reflector-render-target"];
-  }
-}
-
-function unsupportedReflectionRequests(kind: ReflectionSurfaceKind): readonly string[] {
-  switch (kind) {
-    case "planar-reflector":
-      return ["Planar reflector helper is not implemented; no mirror render target or clip-plane path exists in this contract."];
-    case "refractor-glass":
-      return ["Glass/refractor helper is not implemented; material alpha/transmission must not be claimed as scene-space refraction."];
-    case "water-refraction":
-      return ["Water reflection/refraction helper is not implemented; procedural water remains separate and must disclose no true refraction."];
-    case "screen-space-reflection":
-      return ["SSR is unsupported; no depth/normal ray-march pass is created."];
-    case "cube-probe":
-      return ["Live cube-camera probes are unsupported; only static probe descriptors are validated."];
-    case "reflective-floor":
-      return ["Reflective floor is staged PBR material only, not true mirror/reflection rendering."];
-  }
-}
-
-function isReflectionSurfaceKind(value: string): value is ReflectionSurfaceKind {
-  return (listReflectionSurfaceKinds() as readonly string[]).includes(value);
-}
-
-function validateSize(value: readonly [number, number]): readonly [number, number] {
-  const width = positive(value[0], "reflection surface width");
-  const depth = positive(value[1], "reflection surface depth");
-  return [width, depth];
-}
-
-function scaleTranslate(
-  translation: readonly [number, number, number],
-  scale: readonly [number, number, number]
-): Float32Array {
-  return new Float32Array([
-    scale[0], 0, 0, 0,
-    0, scale[1], 0, 0,
-    0, 0, scale[2], 0,
-    translation[0], translation[1], translation[2], 1
-  ]);
-}
-
-function positive(value: number, label: string): number {
-  if (!Number.isFinite(value) || value <= 0) throw new RangeError(`${label} must be finite and positive.`);
-  return value;
-}
-
-function nonNegative(value: number, label: string): number {
-  if (!Number.isFinite(value) || value < 0) throw new RangeError(`${label} must be finite and non-negative.`);
-  return value;
-}
-
-function finite(value: number, label: string): number {
-  if (!Number.isFinite(value)) throw new RangeError(`${label} must be finite.`);
-  return value;
-}
-
-function unit(value: number, label: string): number {
-  if (!Number.isFinite(value) || value < 0 || value > 1) throw new RangeError(`${label} must be in [0, 1].`);
-  return value;
-}

package/src/RenderBackend.ts

@@ -1,43 +0,0 @@
-import { type RenderBackendKind, type RenderDevice, MockRenderDevice, RenderDeviceError } from "./RenderDevice";
-import { WebGL2Device, type WebGL2DeviceOptions, type WebGL2ErrorCheckMode } from "./WebGL2Device";
-import { WebGPUDevice, type WebGPULike } from "./WebGPUDevice";
-
-export interface RenderBackendOptions {
-  readonly backend?: RenderBackendKind;
-  readonly canvas?: HTMLCanvasElement | OffscreenCanvas;
-  readonly antialias?: boolean;
-  readonly alpha?: boolean;
-  readonly preserveDrawingBuffer?: boolean;
-  readonly errorCheckMode?: WebGL2ErrorCheckMode;
-  readonly webgpu?: WebGPULike;
-}
-
-export async function createRenderDevice(options: RenderBackendOptions = {}): Promise<RenderDevice> {
-  const backend = options.backend ?? "webgl2";
-  if (backend === "mock") {
-    return new MockRenderDevice();
-  }
-  if (backend === "webgl2") {
-    if (!options.canvas) {
-      throw new RenderDeviceError("WebGL2 backend requires a canvas", "MISSING_CANVAS");
-    }
-    const webglOptions: WebGL2DeviceOptions = { canvas: options.canvas };
-    if (options.antialias !== undefined) {
-      Object.assign(webglOptions, { antialias: options.antialias });
-    }
-    if (options.alpha !== undefined) {
-      Object.assign(webglOptions, { alpha: options.alpha });
-    }
-    if (options.preserveDrawingBuffer !== undefined) {
-      Object.assign(webglOptions, { preserveDrawingBuffer: options.preserveDrawingBuffer });
-    }
-    if (options.errorCheckMode !== undefined) {
-      Object.assign(webglOptions, { errorCheckMode: options.errorCheckMode });
-    }
-    return WebGL2Device.create(webglOptions);
-  }
-  if (backend === "webgpu") {
-    return WebGPUDevice.create({ gpu: options.webgpu, canvas: options.canvas });
-  }
-  throw new RenderDeviceError("Unknown render backend", "UNKNOWN_BACKEND", { backend });
-}

package/src/RenderDebugViews.ts

@@ -1,138 +0,0 @@
-import { linearToSrgbChannel } from "./ColorManagement";
-
-export type ExternalParityRenderDebugView =
-  | "base-color"
-  | "normal"
-  | "roughness"
-  | "metallic"
-  | "emissive"
-  | "lighting-only"
-  | "diffuse-ibl"
-  | "specular-ibl"
-  | "tone-mapped-output";
-
-export interface ExternalParityDebugViewInput {
-  readonly width: number;
-  readonly height: number;
-  readonly baseColor?: Uint8Array;
-  readonly normal?: Uint8Array;
-  readonly roughness?: Uint8Array;
-  readonly metallic?: Uint8Array;
-  readonly emissive?: Uint8Array;
-  readonly lightingOnly?: Uint8Array;
-  readonly diffuseIbl?: Uint8Array;
-  readonly specularIbl?: Uint8Array;
-  readonly toneMappedOutput?: Uint8Array;
-}
-
-export interface ExternalParityDebugViewResult {
-  readonly view: ExternalParityRenderDebugView;
-  readonly width: number;
-  readonly height: number;
-  readonly pixels: Uint8Array;
-  readonly source: string;
-}
-
-export const EXTERNAL_PARITY_REQUIRED_DEBUG_VIEWS: readonly ExternalParityRenderDebugView[] = [
-  "base-color",
-  "normal",
-  "roughness",
-  "metallic",
-  "emissive",
-  "lighting-only",
-  "diffuse-ibl",
-  "specular-ibl",
-  "tone-mapped-output"
-];
-
-export function createExternalParityDebugView(input: ExternalParityDebugViewInput, view: ExternalParityRenderDebugView): ExternalParityDebugViewResult {
-  validateInput(input);
-  const pixels = sourcePixels(input, view);
-  if (pixels) {
-    return { view, width: input.width, height: input.height, pixels: new Uint8Array(pixels), source: "provided-buffer" };
-  }
-
-  const fallback = new Uint8Array(input.width * input.height * 4);
-  const color = fallbackColor(view);
-  for (let index = 0; index < fallback.length; index += 4) {
-    fallback[index] = color[0];
-    fallback[index + 1] = color[1];
-    fallback[index + 2] = color[2];
-    fallback[index + 3] = 255;
-  }
-  return { view, width: input.width, height: input.height, pixels: fallback, source: "diagnostic-fallback" };
-}
-
-export function createExternalParityDebugViewSet(input: ExternalParityDebugViewInput): readonly ExternalParityDebugViewResult[] {
-  return EXTERNAL_PARITY_REQUIRED_DEBUG_VIEWS.map((view) => createExternalParityDebugView(input, view));
-}
-
-export function encodeLinearDebugColor(color: readonly [number, number, number, number]): [number, number, number, number] {
-  return [
-    byte(linearToSrgbChannel(color[0])),
-    byte(linearToSrgbChannel(color[1])),
-    byte(linearToSrgbChannel(color[2])),
-    byte(color[3])
-  ];
-}
-
-function sourcePixels(input: ExternalParityDebugViewInput, view: ExternalParityRenderDebugView): Uint8Array | undefined {
-  switch (view) {
-    case "base-color":
-      return input.baseColor;
-    case "normal":
-      return input.normal;
-    case "roughness":
-      return input.roughness;
-    case "metallic":
-      return input.metallic;
-    case "emissive":
-      return input.emissive;
-    case "lighting-only":
-      return input.lightingOnly;
-    case "diffuse-ibl":
-      return input.diffuseIbl;
-    case "specular-ibl":
-      return input.specularIbl;
-    case "tone-mapped-output":
-      return input.toneMappedOutput;
-  }
-}
-
-function fallbackColor(view: ExternalParityRenderDebugView): readonly [number, number, number] {
-  switch (view) {
-    case "base-color":
-      return [180, 180, 180];
-    case "normal":
-      return [128, 128, 255];
-    case "roughness":
-      return [96, 96, 96];
-    case "metallic":
-      return [16, 16, 16];
-    case "emissive":
-      return [0, 0, 0];
-    case "lighting-only":
-      return [210, 210, 210];
-    case "diffuse-ibl":
-      return [120, 150, 190];
-    case "specular-ibl":
-      return [220, 230, 245];
-    case "tone-mapped-output":
-      return [180, 190, 205];
-  }
-}
-
-function validateInput(input: ExternalParityDebugViewInput): void {
-  if (!Number.isInteger(input.width) || !Number.isInteger(input.height) || input.width <= 0 || input.height <= 0) {
-    throw new Error("ExternalParity debug view dimensions must be positive integers.");
-  }
-  for (const [name, pixels] of Object.entries(input)) {
-    if (pixels instanceof Uint8Array && pixels.length !== input.width * input.height * 4) {
-      throw new Error(`ExternalParity debug view buffer ${name} must contain width * height * 4 RGBA bytes.`);
-    }
-  }
-}
-
-function byte(value: number): number {
-  return Math.min(255, Math.max(0, Math.round(value * 255)));
-}