@aura3d/rendering 1.0.6

package/src/Raycaster.ts

@@ -0,0 +1,21 @@
+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

@@ -0,0 +1,13 @@
+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

@@ -0,0 +1,219 @@
+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

@@ -0,0 +1,43 @@
+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

@@ -0,0 +1,138 @@
+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)));
+}