@aura3d/rendering 1.0.6

package/src/production-runtime/ProductionRuntimeRenderer.ts

@@ -0,0 +1,172 @@
+import { ProductionWebGL2Renderer, type ProductionWebGL2RendererOptions } from './ProductionWebGL2Renderer';
+import { ProductionWebGPURenderer } from './ProductionWebGPURenderer';
+import type { RenderDeviceDiagnostics } from "../RenderDevice";
+import type {
+  ProductionRendererBackend,
+  ProductionProductionRenderer,
+  ProductionRenderProof,
+  ProductionRendererFeature,
+  ProductionRendererInput,
+  CurrentRoutesProductionRenderer,
+  RuntimeParityFrameRenderResult
+} from './ProductionRendererTypes';
+
+export interface ProductionRuntimeRendererOptions extends ProductionWebGL2RendererOptions {
+  readonly backend?: ProductionRuntimeRendererBackendPreference;
+}
+
+export type ProductionRuntimeRendererBackendPreference = "webgl2" | "webgpu" | "auto";
+
+export interface ProductionRuntimeRendererBackendSelection {
+  readonly requestedBackend: ProductionRuntimeRendererBackendPreference;
+  readonly selectedBackend: ProductionRendererBackend;
+  readonly asyncRequired: boolean;
+  readonly fallback: boolean;
+  readonly reason: string;
+}
+
+type ProductionRuntimeRendererWebGPURuntime = NonNullable<ProductionRuntimeRendererOptions["webgpu"]>;
+
+export class ProductionRuntimeRenderer implements CurrentRoutesProductionRenderer {
+  readonly backend: ProductionRendererBackend;
+  readonly backendSelection: ProductionRuntimeRendererBackendSelection;
+
+  private constructor(
+    private readonly renderer: ProductionProductionRenderer,
+    backend: ProductionRendererBackend,
+    backendSelection: ProductionRuntimeRendererBackendSelection
+  ) {
+    this.backend = backend;
+    this.backendSelection = backendSelection;
+  }
+
+  static async create(options: ProductionRuntimeRendererOptions): Promise<ProductionRuntimeRenderer> {
+    const selection = resolveProductionRuntimeRendererBackend(options);
+    if (selection.selectedBackend === "webgpu") {
+      return new ProductionRuntimeRenderer(await ProductionWebGPURenderer.create(options), "webgpu", selection);
+    }
+    const { backend: _backend, ...webgl2Options } = options;
+    return new ProductionRuntimeRenderer(await ProductionWebGL2Renderer.create(webgl2Options), "webgl2", selection);
+  }
+
+  renderInteractiveFrame(input: ProductionRendererInput): RuntimeParityFrameRenderResult {
+    const renderer = this.renderer as ProductionProductionRenderer & Partial<CurrentRoutesProductionRenderer>;
+    const result = renderer.renderInteractiveFrame ? renderer.renderInteractiveFrame(input) : renderer.renderFrame(input);
+    return withoutReadbackFeatures(result);
+  }
+
+  renderFrame(input: ProductionRendererInput): RuntimeParityFrameRenderResult {
+    return this.renderInteractiveFrame(input);
+  }
+
+  resize(width: number, height: number): void {
+    const renderer = this.renderer as ProductionProductionRenderer & { resize?: (width: number, height: number) => void };
+    if (typeof renderer.resize !== "function") {
+      throw new Error(`Renderer backend ${this.backend} does not support interactive resizing.`);
+    }
+    renderer.resize(width, height);
+  }
+
+  captureProof(input: ProductionRendererInput): ProductionRenderProof {
+    const renderer = this.renderer as ProductionProductionRenderer & Partial<CurrentRoutesProductionRenderer>;
+    return renderer.captureProof ? renderer.captureProof(input) : renderer.renderImportedAsset(input);
+  }
+
+  renderImportedAsset(input: ProductionRendererInput): ProductionRenderProof {
+    return this.captureProof(input);
+  }
+
+  async renderInteractiveFrameAsync(input: ProductionRendererInput): Promise<RuntimeParityFrameRenderResult> {
+    const result = this.renderer instanceof ProductionWebGPURenderer
+      ? await this.renderer.renderFrameAsync(input)
+      : this.renderInteractiveFrame(input);
+    return withoutReadbackFeatures(result);
+  }
+
+  async renderFrameAsync(input: ProductionRendererInput): Promise<RuntimeParityFrameRenderResult> {
+    return this.renderInteractiveFrameAsync(input);
+  }
+
+  async captureProofAsync(input: ProductionRendererInput): Promise<ProductionRenderProof> {
+    if (this.renderer instanceof ProductionWebGPURenderer) {
+      return this.renderer.renderImportedAssetAsync(input);
+    }
+    return this.captureProof(input);
+  }
+
+  async renderImportedAssetAsync(input: ProductionRendererInput): Promise<ProductionRenderProof> {
+    return this.captureProofAsync(input);
+  }
+
+  getFeatures(): readonly ProductionRendererFeature[] {
+    return this.renderer.getFeatures();
+  }
+
+  getDiagnostics(): RenderDeviceDiagnostics {
+    return this.renderer.getDiagnostics();
+  }
+
+  dispose(): void {
+    this.renderer.dispose();
+  }
+}
+
+export function createProductionRuntimeRenderer(options: ProductionRuntimeRendererOptions): Promise<ProductionRuntimeRenderer> {
+  return ProductionRuntimeRenderer.create(options);
+}
+
+export function resolveProductionRuntimeRendererBackend(options: Pick<ProductionRuntimeRendererOptions, "backend" | "webgpu">): ProductionRuntimeRendererBackendSelection {
+  const browserWebGPU = readBrowserWebGPU();
+  const hasWebGPU = Boolean(options.webgpu ?? browserWebGPU);
+  const requestedBackend = options.backend ?? (hasWebGPU ? "auto" : "webgl2");
+  if (requestedBackend === "webgpu") {
+    return {
+      requestedBackend,
+      selectedBackend: "webgpu",
+      asyncRequired: true,
+      fallback: false,
+      reason: "Explicit backend='webgpu' uses ProductionWebGPURenderer and fails if native WebGPU capabilities are missing."
+    };
+  }
+  if (requestedBackend === "auto") {
+    if (hasWebGPU) {
+      return {
+        requestedBackend,
+        selectedBackend: "webgpu",
+        asyncRequired: true,
+        fallback: false,
+        reason: options.webgpu
+          ? "backend='auto' selected WebGPU because a WebGPU runtime object was provided."
+          : "backend='auto' selected WebGPU because navigator.gpu is available in the current browser runtime."
+      };
+    }
+    return {
+      requestedBackend,
+      selectedBackend: "webgl2",
+      asyncRequired: false,
+      fallback: true,
+      reason: "backend='auto' selected WebGL2 because no WebGPU runtime object was provided to the SDK."
+    };
+  }
+  return {
+    requestedBackend,
+    selectedBackend: "webgl2",
+    asyncRequired: false,
+    fallback: false,
+    reason: "WebGL2 is selected when no WebGPU runtime is supplied, or when the app explicitly requests backend='webgl2'."
+  };
+}
+
+function readBrowserWebGPU(): ProductionRuntimeRendererWebGPURuntime | undefined {
+  const navigatorWithGpu = (globalThis as typeof globalThis & {
+    readonly navigator?: Navigator & { readonly gpu?: ProductionRuntimeRendererWebGPURuntime };
+  }).navigator;
+  return navigatorWithGpu?.gpu;
+}
+
+function withoutReadbackFeatures(result: RuntimeParityFrameRenderResult): RuntimeParityFrameRenderResult {
+  return {
+    ...result,
+    features: result.features.filter((feature) => feature.id !== "pixel-readback" && feature.id !== "scene-color-transmission-capture")
+  };
+}

package/src/production-runtime/ProductionWebGL2Renderer.ts

@@ -0,0 +1,313 @@
+import { Renderer, type RendererOptions } from "../Renderer";
+import type { RenderDeviceDiagnostics } from "../RenderDevice";
+import { Texture } from "../Texture";
+import {
+  bindTransmissionBackdropCapture,
+  createSceneColorMipLevels,
+  normalizeTransmissionBackdropCapture
+} from "./TransmissionBackdropCapture";
+import {
+  PRODUCTION_WEBGL2_REQUIRED_FEATURES,
+  RUNTIME_PARITY_WEBGPU_REQUIRED_FEATURES,
+  type ProductionPixelMetrics,
+  type ProductionRenderProof,
+  type ProductionRendererFeature,
+  type ProductionRendererInput,
+  type CurrentRoutesProductionRenderer,
+  type CurrentRoutesRendererTimingDiagnostics,
+  type RuntimeParityFrameRenderResult,
+  type RuntimeParityTransmissionBackdropCaptureProof
+} from "./ProductionRendererTypes";
+
+export interface ProductionWebGL2RendererOptions extends Omit<RendererOptions, "backend"> {
+  readonly canvas: HTMLCanvasElement | OffscreenCanvas;
+  readonly width: number;
+  readonly height: number;
+}
+
+export class ProductionWebGL2Renderer implements CurrentRoutesProductionRenderer {
+  readonly backend = "webgl2" as const;
+
+  private constructor(private readonly renderer: Renderer, private width: number, private height: number) {}
+
+  static async create(options: ProductionWebGL2RendererOptions): Promise<ProductionWebGL2Renderer> {
+    const renderer = await Renderer.create({
+      ...options,
+      backend: "webgl2",
+      requiredFeatures: ["basic-rendering", "pixel-readback", "render-targets", "hdr-image-based-lighting"]
+    });
+    if (renderer.device.kind !== "webgl2") {
+      renderer.dispose();
+      throw new Error(`Production production renderer requires a real WebGL2 device, got ${renderer.device.kind}.`);
+    }
+    return new ProductionWebGL2Renderer(renderer, options.width, options.height);
+  }
+
+  renderInteractiveFrame(input: ProductionRendererInput): RuntimeParityFrameRenderResult {
+    this.validateImportedAsset(input);
+    const timing = createCurrentRoutesTimingAccumulator();
+    const renderStart = timing.now();
+    const diagnostics = this.renderer.render(input.source, input.camera);
+    timing.addRender(renderStart);
+    return {
+      backend: "webgl2",
+      diagnostics,
+      features: this.getInteractiveFeatures(diagnostics, input),
+      timing: timing.snapshot()
+    };
+  }
+
+  renderFrame(input: ProductionRendererInput): RuntimeParityFrameRenderResult {
+    return this.renderInteractiveFrame(input);
+  }
+
+  resize(width: number, height: number): void {
+    this.width = width;
+    this.height = height;
+    this.renderer.resize(width, height);
+  }
+
+  captureProof(input: ProductionRendererInput): ProductionRenderProof {
+    this.validateImportedAsset(input);
+    const timing = createCurrentRoutesTimingAccumulator();
+    let transmissionBackdropCapture: RuntimeParityTransmissionBackdropCaptureProof | undefined;
+    let transmissionBackdropTexture: Texture | undefined;
+    const captureOptions = normalizeTransmissionBackdropCapture(input.transmissionBackdropCapture);
+    if (captureOptions) {
+      const captureStart = timing.now();
+      const captureRenderStart = timing.now();
+      this.renderer.render(input.source, input.camera);
+      timing.addRender(captureRenderStart);
+      const captureReadbackStart = timing.now();
+      const scenePixels = this.renderer.device.readPixels(0, 0, this.width, this.height);
+      timing.addReadback(captureReadbackStart);
+      const mipLevels = createSceneColorMipLevels(scenePixels, this.width, this.height);
+      transmissionBackdropTexture = new Texture({
+        width: this.width,
+        height: this.height,
+        colorSpace: "srgb",
+        mipLevels,
+        label: "a3d-renderer-owned-scene-color-transmission-backdrop"
+      });
+      const materialBindings = bindTransmissionBackdropCapture(input.source, transmissionBackdropTexture, captureOptions);
+      transmissionBackdropCapture = {
+        mode: "renderer-owned-scene-color-readback",
+        width: this.width,
+        height: this.height,
+        byteLength: scenePixels.byteLength,
+        mipCount: mipLevels.length,
+        strength: captureOptions.strength,
+        refractionScale: captureOptions.refractionScale,
+        materialBindings
+      };
+      timing.addTransmissionBackdropCapture(captureStart);
+    }
+    const renderStart = timing.now();
+    const diagnostics = this.renderer.render(input.source, input.camera);
+    timing.addRender(renderStart);
+    const readbackStart = timing.now();
+    const pixelBytes = this.renderer.device.readPixels(0, 0, this.width, this.height);
+    timing.addReadback(readbackStart);
+    const analysisStart = timing.now();
+    const pixels = analyzePixels(pixelBytes, this.width, this.height);
+    timing.addPixelAnalysis(analysisStart);
+    transmissionBackdropTexture?.dispose();
+    const features = this.getFeatures(diagnostics, input, pixels);
+    return {
+      backend: "webgl2",
+      realWebGL2: this.renderer.device.kind === "webgl2",
+      mockDevice: this.renderer.device.kind === "mock",
+      canvas2dProof: false,
+      importedAsset: input.metadata,
+      diagnostics,
+      features,
+      pixels,
+      timing: timing.snapshot(),
+      ...(transmissionBackdropCapture ? { transmissionBackdropCapture } : {})
+    };
+  }
+
+  renderImportedAsset(input: ProductionRendererInput): ProductionRenderProof {
+    return this.captureProof(input);
+  }
+
+  getFeatures(diagnostics = this.getDiagnostics(), input?: ProductionRendererInput, pixels?: ProductionPixelMetrics): readonly ProductionRendererFeature[] {
+    const capabilities = new Set(this.renderer.device.info.capabilities ?? []);
+    const feature = (id: string, state: ProductionRendererFeature["state"], detail: string): ProductionRendererFeature => ({ id, state, detail });
+    return [
+      feature("real-webgl2-context", this.renderer.device.kind === "webgl2" ? "supported" : "blocked", `backend=${this.renderer.device.kind}`),
+      feature("no-canvas2d-proof", "supported", "Render proof is produced by Renderer/WebGL2 and readPixels, not Canvas 2D drawing."),
+      feature("no-mock-device", this.renderer.device.kind === "mock" ? "blocked" : "supported", "ProductionWebGL2Renderer refuses mock backend creation."),
+      feature("imported-gltf-render-source", input && input.metadata.primitiveCount > 0 ? "supported" : "partial", input ? `${input.metadata.assetId}: ${input.metadata.primitiveCount} primitives` : "Awaiting imported asset render input."),
+      feature("pbr-materials", input && input.metadata.materialCount > 0 ? "supported" : "partial", input ? `${input.metadata.materialCount} glTF materials in render metadata` : "Awaiting imported asset metadata."),
+      feature("texture-upload-diagnostics", (diagnostics.textures ?? 0) > 0 ? "supported" : "partial", `${diagnostics.textures ?? 0} live textures, ${diagnostics.textureBytes ?? 0} bytes`),
+      feature("render-target-diagnostics", diagnostics.renderTargets !== undefined ? "supported" : "partial", `${diagnostics.renderTargets ?? 0} live render targets`),
+      feature("draw-call-diagnostics", diagnostics.drawCalls > 0 ? "supported" : "partial", `${diagnostics.drawCalls} draw calls in last frame`),
+      feature("pixel-readback", pixels && pixels.nonBlackPixels > 0 ? "supported" : "partial", pixels ? `${pixels.nonBlackPixels} non-black pixels` : "Awaiting frame readback."),
+      feature("hdr-ibl-ready", capabilities.has("hdr-image-based-lighting") ? "supported" : "partial", `capabilities=${[...capabilities].join(",")}`),
+      feature("anisotropic-texture-filtering", capabilities.has("anisotropic-texture-filtering") ? "supported" : "partial", "WebGL EXT_texture_filter_anisotropic for sharper angled PBR texture sampling."),
+      feature(
+        "scene-color-transmission-capture",
+        input?.transmissionBackdropCapture ? "supported" : "partial",
+        input?.transmissionBackdropCapture
+          ? "Renderer-owned first-pass scene-color readback is rebound as u_transmissionBackdropTexture for the final A3D transmission pass."
+          : "Transmission backdrop capture was not requested for this proof."
+      )
+    ];
+  }
+
+  getDiagnostics(): RenderDeviceDiagnostics {
+    return this.renderer.getDiagnostics();
+  }
+
+  dispose(): void {
+    this.renderer.dispose();
+  }
+
+  private validateImportedAsset(input: ProductionRendererInput): void {
+    if (input.metadata.primitiveCount <= 0 || input.metadata.meshCount <= 0) {
+      throw new Error("Production imported-asset render path requires real glTF mesh primitives.");
+    }
+    if (input.metadata.materialCount <= 0) {
+      throw new Error("Production imported-asset render path requires real material data.");
+    }
+  }
+
+  private getInteractiveFeatures(diagnostics: RenderDeviceDiagnostics, input: ProductionRendererInput): readonly ProductionRendererFeature[] {
+    return this.getFeatures(diagnostics, input).filter((feature) => feature.id !== "pixel-readback" && feature.id !== "scene-color-transmission-capture");
+  }
+}
+
+export function summarizeProductionWebGL2Proof(proof: ProductionRenderProof) {
+  const missing = PRODUCTION_WEBGL2_REQUIRED_FEATURES.filter((feature) => {
+    const state = proof.features.find((item) => item.id === feature)?.state;
+    return state !== "supported";
+  });
+  return {
+    pass: missing.length === 0 && proof.realWebGL2 && !proof.mockDevice && !proof.canvas2dProof && proof.diagnostics.drawCalls > 0 && proof.pixels.nonBlackPixels > 0,
+    missing,
+    drawCalls: proof.diagnostics.drawCalls,
+    liveTextures: proof.diagnostics.textures ?? 0,
+    textureBytes: proof.diagnostics.textureBytes ?? 0,
+    nonBlackPixels: proof.pixels.nonBlackPixels,
+    averageLuma: proof.pixels.averageLuma,
+    maxLuma: proof.pixels.maxLuma,
+    uniqueColorBuckets: proof.pixels.uniqueColorBuckets
+  };
+}
+
+export function summarizeProductionProductionProof(proof: ProductionRenderProof) {
+  const requiredFeatures = proof.backend === "webgpu"
+    ? RUNTIME_PARITY_WEBGPU_REQUIRED_FEATURES
+    : PRODUCTION_WEBGL2_REQUIRED_FEATURES;
+  const missing = requiredFeatures.filter((feature) => {
+    const state = proof.features.find((item) => item.id === feature)?.state;
+    return state !== "supported";
+  });
+  return {
+    pass: missing.length === 0 && !proof.mockDevice && !proof.canvas2dProof && proof.diagnostics.drawCalls > 0 && proof.pixels.nonBlackPixels > 0,
+    backend: proof.backend,
+    missing,
+    drawCalls: proof.diagnostics.drawCalls,
+    liveTextures: proof.diagnostics.textures ?? 0,
+    textureBytes: proof.diagnostics.textureBytes ?? 0,
+    nonBlackPixels: proof.pixels.nonBlackPixels,
+    averageLuma: proof.pixels.averageLuma,
+    maxLuma: proof.pixels.maxLuma,
+    uniqueColorBuckets: proof.pixels.uniqueColorBuckets
+  };
+}
+
+export function analyzePixels(pixels: Uint8Array, width: number, height: number): ProductionPixelMetrics {
+  let nonTransparentPixels = 0;
+  let nonBlackPixels = 0;
+  let lumaTotal = 0;
+  let maxLuma = 0;
+  const buckets = new Set<number>();
+  for (let offset = 0; offset + 3 < pixels.length; offset += 4) {
+    const r = pixels[offset] ?? 0;
+    const g = pixels[offset + 1] ?? 0;
+    const b = pixels[offset + 2] ?? 0;
+    const a = pixels[offset + 3] ?? 0;
+    if (a > 0) nonTransparentPixels += 1;
+    if (r + g + b > 12) nonBlackPixels += 1;
+    const luma = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+    lumaTotal += luma;
+    maxLuma = Math.max(maxLuma, luma);
+    buckets.add(((r >> 4) << 8) | ((g >> 4) << 4) | (b >> 4));
+  }
+  const centerOffset = ((Math.floor(height / 2) * width) + Math.floor(width / 2)) * 4;
+  return {
+    width,
+    height,
+    nonTransparentPixels,
+    nonBlackPixels,
+    averageLuma: pixels.length > 0 ? lumaTotal / (pixels.length / 4) : 0,
+    maxLuma,
+    uniqueColorBuckets: buckets.size,
+    centerPixel: [
+      pixels[centerOffset] ?? 0,
+      pixels[centerOffset + 1] ?? 0,
+      pixels[centerOffset + 2] ?? 0,
+      pixels[centerOffset + 3] ?? 0
+    ]
+  };
+}
+
+interface CurrentRoutesTimingAccumulator {
+  now(): number;
+  addRender(start: number): void;
+  addReadback(start: number): void;
+  addPixelAnalysis(start: number): void;
+  addTransmissionBackdropCapture(start: number): void;
+  snapshot(): CurrentRoutesRendererTimingDiagnostics;
+}
+
+function createCurrentRoutesTimingAccumulator(): CurrentRoutesTimingAccumulator {
+  const source = hasPerformanceNow() ? "performance-now" : "date-now";
+  const startedAt = readCurrentRoutesNow(source);
+  let renderMs = 0;
+  let readbackMs = 0;
+  let pixelAnalysisMs = 0;
+  let transmissionBackdropCaptureMs = 0;
+  let hasReadback = false;
+  let hasPixelAnalysis = false;
+  let hasTransmissionBackdropCapture = false;
+  const elapsed = (start: number) => Math.max(0, readCurrentRoutesNow(source) - start);
+  return {
+    now: () => readCurrentRoutesNow(source),
+    addRender(start) {
+      renderMs += elapsed(start);
+    },
+    addReadback(start) {
+      hasReadback = true;
+      readbackMs += elapsed(start);
+    },
+    addPixelAnalysis(start) {
+      hasPixelAnalysis = true;
+      pixelAnalysisMs += elapsed(start);
+    },
+    addTransmissionBackdropCapture(start) {
+      hasTransmissionBackdropCapture = true;
+      transmissionBackdropCaptureMs += elapsed(start);
+    },
+    snapshot() {
+      return {
+        source,
+        totalMs: elapsed(startedAt),
+        renderMs,
+        ...(hasReadback ? { readbackMs } : {}),
+        ...(hasPixelAnalysis ? { pixelAnalysisMs } : {}),
+        ...(hasTransmissionBackdropCapture ? { transmissionBackdropCaptureMs } : {})
+      };
+    }
+  };
+}
+
+function hasPerformanceNow(): boolean {
+  return typeof globalThis.performance?.now === "function";
+}
+
+function readCurrentRoutesNow(source: CurrentRoutesRendererTimingDiagnostics["source"]): number {
+  return source === "performance-now" ? globalThis.performance.now() : Date.now();
+}