@aura3d/rendering 1.3.3 → 1.4.1

package/src/RendererDebugOverlay.ts

@@ -1,80 +0,0 @@
-import { RenderDeviceError } from "./RenderDevice";
-
-export type RenderDebugIssueKind = "render-pass-error" | "shader-error";
-
-export interface RenderDebugIssue {
-  readonly kind: RenderDebugIssueKind;
-  readonly label: string;
-  readonly message: string;
-  readonly code?: string;
-  readonly details?: Readonly<Record<string, unknown>>;
-}
-
-export interface RenderDebugOverlaySnapshot {
-  readonly visible: boolean;
-  readonly issueCount: number;
-  readonly renderPassErrors: number;
-  readonly shaderErrors: number;
-  readonly issues: readonly RenderDebugIssue[];
-  readonly lines: readonly string[];
-}
-
-export function captureRenderDebugIssue(
-  kind: RenderDebugIssueKind,
-  label: string,
-  error: unknown
-): RenderDebugIssue {
-  const trimmedLabel = requireNonEmptyLabel(label);
-  if (error instanceof RenderDeviceError) {
-    return {
-      kind,
-      label: trimmedLabel,
-      message: error.message,
-      code: error.code,
-      details: error.details
-    };
-  }
-  if (error instanceof Error) {
-    return {
-      kind,
-      label: trimmedLabel,
-      message: error.message
-    };
-  }
-  return {
-    kind,
-    label: trimmedLabel,
-    message: String(error)
-  };
-}
-
-export function buildRenderDebugOverlaySnapshot(issues: readonly RenderDebugIssue[]): RenderDebugOverlaySnapshot {
-  const normalized = issues.map((issue) => ({
-    ...issue,
-    label: requireNonEmptyLabel(issue.label),
-    message: issue.message.trim() || "Unknown render debug issue"
-  }));
-  const renderPassErrors = normalized.filter((issue) => issue.kind === "render-pass-error").length;
-  const shaderErrors = normalized.filter((issue) => issue.kind === "shader-error").length;
-  return {
-    visible: normalized.length > 0,
-    issueCount: normalized.length,
-    renderPassErrors,
-    shaderErrors,
-    issues: normalized,
-    lines: normalized.map(formatRenderDebugIssue)
-  };
-}
-
-export function formatRenderDebugIssue(issue: RenderDebugIssue): string {
-  const code = issue.code ? ` ${issue.code}` : "";
-  return `[${issue.kind}${code}] ${issue.label}: ${issue.message}`;
-}
-
-function requireNonEmptyLabel(label: string): string {
-  const trimmed = label.trim();
-  if (!trimmed) {
-    throw new Error("Render debug issue label is required");
-  }
-  return trimmed;
-}

package/src/RendererFeatureGates.ts

@@ -1,150 +0,0 @@
-import { type RenderDevice, RenderDeviceError, type RenderDeviceInfo } from "./RenderDevice";
-
-export type RendererFeature =
-  | "basic-rendering"
-  | "render-targets"
-  | "pixel-readback"
-  | "postprocess-ldr"
-  | "bounded-pbr-materials"
-  | "shadow-maps"
-  | "contact-shadows"
-  | "spot-shadow-maps"
-  | "point-shadow-maps"
-  | "depth-textures"
-  | "hdr-render-targets"
-  | "hdr-image-based-lighting"
-  | "production-pbr-parity"
-  | "gpu-timing"
-  | "webgpu-compute";
-
-export interface RendererFeatureStatus {
-  readonly feature: RendererFeature;
-  readonly supported: boolean;
-  readonly reason?: string;
-}
-
-export interface RendererFeatureReport {
-  readonly backend: RenderDeviceInfo["backend"];
-  readonly supported: readonly RendererFeature[];
-  readonly blocked: readonly RendererFeatureStatus[];
-  readonly statuses: readonly RendererFeatureStatus[];
-}
-
-export function createRendererFeatureReport(device: Pick<RenderDevice, "info">): RendererFeatureReport {
-  const capabilities = new Set<string>(device.info.capabilities ?? []);
-  const statuses: RendererFeatureStatus[] = rendererFeatureCatalog().map((feature) => resolveFeatureStatus(feature, device.info, capabilities));
-  return {
-    backend: device.info.backend,
-    supported: statuses.filter((status) => status.supported).map((status) => status.feature),
-    blocked: statuses.filter((status) => !status.supported),
-    statuses
-  };
-}
-
-export function assertRendererFeatures(device: Pick<RenderDevice, "info">, requiredFeatures: readonly RendererFeature[]): RendererFeatureReport {
-  const report = createRendererFeatureReport(device);
-  const required = new Set(requiredFeatures);
-  const missing = report.blocked.filter((status) => required.has(status.feature));
-  if (missing.length > 0) {
-    throw new RenderDeviceError("Renderer required features are unsupported", "UNSUPPORTED_RENDER_FEATURE", {
-      backend: report.backend,
-      missing: missing.map((status) => status.feature),
-      reasons: Object.fromEntries(missing.map((status) => [status.feature, status.reason ?? "Unsupported by renderer backend."]))
-    });
-  }
-  return report;
-}
-
-export function rendererFeatureCatalog(): readonly RendererFeature[] {
-  return [
-    "basic-rendering",
-    "render-targets",
-    "pixel-readback",
-    "postprocess-ldr",
-    "bounded-pbr-materials",
-    "shadow-maps",
-    "contact-shadows",
-    "spot-shadow-maps",
-    "point-shadow-maps",
-    "depth-textures",
-    "hdr-render-targets",
-    "hdr-image-based-lighting",
-    "production-pbr-parity",
-    "gpu-timing",
-    "webgpu-compute"
-  ];
-}
-
-function resolveFeatureStatus(
-  feature: RendererFeature,
-  info: RenderDeviceInfo,
-  capabilities: ReadonlySet<string>
-): RendererFeatureStatus {
-  if (feature === "basic-rendering") {
-    return supportedIf(feature, capabilities.has("buffers") && capabilities.has("draw-validation"), "Backend lacks the buffer/draw contract required for visible rendering.");
-  }
-  if (feature === "render-targets") {
-    return supportedIf(feature, capabilities.has("render-targets"), "Backend does not expose render targets.");
-  }
-  if (feature === "pixel-readback") {
-    return supportedIf(feature, capabilities.has("pixel-readback"), "Backend does not expose pixel readback for visual tests.");
-  }
-  if (feature === "postprocess-ldr") {
-    return supportedIf(
-      feature,
-      capabilities.has("render-targets") && capabilities.has("pixel-readback") && capabilities.has("postprocess-presentation"),
-      "LDR postprocess requires render targets, pixel readback, and a backend presentation path."
-    );
-  }
-  if (feature === "bounded-pbr-materials") {
-    return supportedIf(
-      feature,
-      info.backend === "webgl2" || info.backend === "webgpu" || info.backend === "mock",
-      "Backend does not support the bounded material shader path."
-    );
-  }
-  if (feature === "shadow-maps") {
-    return supportedIf(feature, capabilities.has("render-targets"), "Shadow maps require render-target-backed shadow passes.");
-  }
-  if (feature === "contact-shadows") {
-    return supportedIf(feature, capabilities.has("contact-shadows"), "This backend does not expose renderer-owned contact-shadow support; callers must use shadow-map features or publish a visible no-contact-shadow limit.");
-  }
-  if (feature === "spot-shadow-maps") {
-    return supportedIf(feature, capabilities.has("spot-shadow-maps"), "Projected spot shadow maps require renderer-owned shadow-map support.");
-  }
-  if (feature === "point-shadow-maps") {
-    return supportedIf(feature, capabilities.has("point-shadow-maps"), "This backend does not expose point-light cubemap or atlas shadow-map support.");
-  }
-  if (feature === "depth-textures") {
-    return supportedIf(
-      feature,
-      capabilities.has("depth-textures"),
-      "Sampleable depth texture plumbing is not exposed by this backend; depth renderbuffers alone are insufficient for depth-aware postprocess."
-    );
-  }
-  if (feature === "hdr-render-targets") {
-    return supportedIf(feature, capabilities.has("hdr-render-targets"), "This backend does not expose HDR render targets; callers must use LDR targets or request a backend with float color-buffer support.");
-  }
-  if (feature === "hdr-image-based-lighting") {
-    return supportedIf(feature, capabilities.has("hdr-image-based-lighting"), "This backend does not expose production HDR image-based-lighting resources, irradiance convolution, and specular prefiltering.");
-  }
-  if (feature === "production-pbr-parity") {
-    return supportedIf(
-      feature,
-      capabilities.has("production-pbr-parity"),
-      "Production PBR parity requires an explicit backend/report capability after external reference-scene comparisons pass; local HDR targets, color management, and IBL support alone are not enough."
-    );
-  }
-  if (feature === "gpu-timing") {
-    return supportedIf(feature, capabilities.has("gpu-timing"), "GPU timing is unavailable; callers must use CPU timing diagnostics.");
-  }
-  return supportedIf(
-    feature,
-    info.backend === "webgpu" && capabilities.has("webgpu-compute"),
-    "WebGPU compute is unavailable on this backend or adapter."
-  );
-}
-
-function supportedIf(feature: RendererFeature, supported: boolean, reason: string): RendererFeatureStatus {
-  return supported ? { feature, supported: true } : { feature, supported: false, reason };
-}

package/src/RendererPostprocessPlan.ts

@@ -1,279 +0,0 @@
-import type {
-  BloomOptions,
-  ChromaticAberrationOptions,
-  ColorGradeOptions,
-  ContactShadowPostProcessOptions,
-  DepthOfFieldOptions,
-  FXAAOptions,
-  FilmGrainOptions,
-  MotionBlurOptions,
-  OutlineOptions,
-  SSAOOptions,
-  SSROptions,
-  TAAOptions,
-  ToneMappingOptions
-} from "./PostProcessPass";
-
-export type RendererPostprocessTargetFormat = "rgba8" | "rgba16f" | "rgba32f";
-
-export interface RendererPostprocessPlanOptions {
-  readonly toneMapping?: ToneMappingOptions | false;
-  readonly colorGrade?: ColorGradeOptions | boolean;
-  readonly bloom?: BloomOptions | boolean;
-  readonly chromaticAberration?: ChromaticAberrationOptions | boolean;
-  readonly filmGrain?: FilmGrainOptions | boolean;
-  readonly depthOfField?: DepthOfFieldOptions | false;
-  readonly motionBlur?: MotionBlurOptions | false;
-  readonly contactShadow?: ContactShadowPostProcessOptions | false;
-  readonly ssao?: SSAOOptions | false;
-  readonly ssr?: SSROptions | false;
-  readonly taa?: TAAOptions | false;
-  readonly outline?: OutlineOptions | boolean;
-  readonly fxaa?: FXAAOptions | boolean;
-}
-
-export type RendererPostProcessPassName =
-  | "tone-mapping"
-  | "color-grade"
-  | "bloom"
-  | "chromatic-aberration"
-  | "film-grain"
-  | "depth-of-field"
-  | "motion-blur"
-  | "contact-shadow"
-  | "ssao"
-  | "ssr"
-  | "taa"
-  | "outline"
-  | "fxaa";
-
-export interface RendererPostProcessPassPlan {
-  readonly name: RendererPostProcessPassName;
-  readonly options:
-    | ToneMappingOptions
-    | ColorGradeOptions
-    | BloomOptions
-    | ChromaticAberrationOptions
-    | FilmGrainOptions
-    | DepthOfFieldOptions
-    | MotionBlurOptions
-    | ContactShadowPostProcessOptions
-    | SSAOOptions
-    | SSROptions
-    | TAAOptions
-    | OutlineOptions
-    | FXAAOptions;
-}
-
-export type RendererPostprocessExecutionMode =
-  | "none"
-  | "renderer-owned-fused-ldr-native"
-  | "renderer-owned-fused-ldr-readback"
-  | "renderer-owned-pass-chain-readback";
-
-export interface RendererPostprocessPlanContext {
-  readonly sourceTargetFormat?: RendererPostprocessTargetFormat;
-  readonly targetFormat?: RendererPostprocessTargetFormat;
-  readonly rendererDepthAvailable?: boolean;
-  readonly nativeLdrPostprocess?: boolean;
-}
-
-export interface RendererPostprocessPassDiagnostics {
-  readonly name: RendererPostProcessPassName;
-  readonly rendererOwned: true;
-  readonly publicPixelKernel: boolean;
-  readonly requiresDepth: boolean;
-  readonly hasDepthInput: boolean;
-  readonly usesRendererOwnedDepth: boolean;
-  readonly requiresVelocity: boolean;
-  readonly hasVelocityInput: boolean;
-  readonly usesReadback: boolean;
-}
-
-export interface RendererPostprocessPlanDiagnostics {
-  readonly source: "Renderer.postprocessPlan";
-  readonly passCount: number;
-  readonly passNames: readonly RendererPostProcessPassName[];
-  readonly targetFormat: RendererPostprocessTargetFormat;
-  readonly sourceTargetFormat: RendererPostprocessTargetFormat;
-  readonly executionMode: RendererPostprocessExecutionMode;
-  readonly canFuseLdr: boolean;
-  readonly requiresDepthTexture: boolean;
-  readonly missingInputs: readonly string[];
-  readonly readbackPassNames: readonly RendererPostProcessPassName[];
-  readonly rendererOwnedPassNames: readonly RendererPostProcessPassName[];
-  readonly clarityWarnings: readonly string[];
-  readonly passes: readonly RendererPostprocessPassDiagnostics[];
-  readonly claimBoundary: string;
-}
-
-export function createRendererPostprocessPasses(postprocess: RendererPostprocessPlanOptions): readonly RendererPostProcessPassPlan[] {
-  const passes: RendererPostProcessPassPlan[] = [];
-  if (postprocess.bloom) {
-    passes.push({ name: "bloom", options: postprocess.bloom === true ? {} : postprocess.bloom });
-  }
-  if (postprocess.toneMapping !== false) {
-    passes.push({ name: "tone-mapping", options: postprocess.toneMapping ?? {} });
-  }
-  if (postprocess.colorGrade) {
-    passes.push({ name: "color-grade", options: postprocess.colorGrade === true ? {} : postprocess.colorGrade });
-  }
-  if (postprocess.chromaticAberration) {
-    passes.push({ name: "chromatic-aberration", options: postprocess.chromaticAberration === true ? {} : postprocess.chromaticAberration });
-  }
-  if (postprocess.filmGrain) {
-    passes.push({ name: "film-grain", options: postprocess.filmGrain === true ? {} : postprocess.filmGrain });
-  }
-  if (postprocess.depthOfField) {
-    passes.push({ name: "depth-of-field", options: postprocess.depthOfField });
-  }
-  if (postprocess.motionBlur) {
-    passes.push({ name: "motion-blur", options: postprocess.motionBlur });
-  }
-  if (postprocess.contactShadow) {
-    passes.push({ name: "contact-shadow", options: postprocess.contactShadow });
-  }
-  if (postprocess.ssao) {
-    passes.push({ name: "ssao", options: postprocess.ssao });
-  }
-  if (postprocess.ssr) {
-    passes.push({ name: "ssr", options: postprocess.ssr });
-  }
-  if (postprocess.taa) {
-    passes.push({ name: "taa", options: postprocess.taa });
-  }
-  if (postprocess.outline) {
-    passes.push({ name: "outline", options: postprocess.outline === true ? {} : postprocess.outline });
-  }
-  if (postprocess.fxaa) {
-    passes.push({ name: "fxaa", options: postprocess.fxaa === true ? {} : postprocess.fxaa });
-  }
-  return passes;
-}
-
-export function createRendererPostprocessPlanDiagnostics(
-  postprocess: RendererPostprocessPlanOptions,
-  context: RendererPostprocessPlanContext = {}
-): RendererPostprocessPlanDiagnostics {
-  const passes = createRendererPostprocessPasses(postprocess);
-  const sourceTargetFormat = context.sourceTargetFormat ?? context.targetFormat ?? "rgba8";
-  const targetFormat = context.targetFormat ?? sourceTargetFormat;
-  const canFuseLdr = canFuseLdrPostprocessPlan(sourceTargetFormat, passes);
-  const executionMode = passes.length === 0
-    ? "none"
-    : canFuseLdr
-      ? context.nativeLdrPostprocess
-        ? "renderer-owned-fused-ldr-native"
-        : "renderer-owned-fused-ldr-readback"
-      : "renderer-owned-pass-chain-readback";
-  const missingInputs = missingPostprocessInputs(passes, context);
-  const clarityWarnings = postprocessClarityWarnings(postprocess, passes, executionMode);
-  const passDiagnostics = passes.map((pass): RendererPostprocessPassDiagnostics => {
-    const requiresDepth = isDepthPostprocessPassName(pass.name);
-    const hasDepthInput = requiresDepth && postprocessPassHasDepth(pass.options);
-    const usesRendererOwnedDepth = requiresDepth && !hasDepthInput && context.rendererDepthAvailable === true;
-    const requiresVelocity = pass.name === "motion-blur";
-    const hasVelocityInput = requiresVelocity && postprocessPassHasVelocity(pass.options);
-    return {
-      name: pass.name,
-      rendererOwned: true,
-      publicPixelKernel: true,
-      requiresDepth,
-      hasDepthInput,
-      usesRendererOwnedDepth,
-      requiresVelocity,
-      hasVelocityInput,
-      usesReadback: executionMode !== "renderer-owned-fused-ldr-native"
-    };
-  });
-  return {
-    source: "Renderer.postprocessPlan",
-    passCount: passes.length,
-    passNames: passes.map((pass) => pass.name),
-    targetFormat,
-    sourceTargetFormat,
-    executionMode,
-    canFuseLdr,
-    requiresDepthTexture: passes.some((pass) => isDepthPostprocessPassName(pass.name) && !postprocessPassHasDepth(pass.options)),
-    missingInputs,
-    readbackPassNames: executionMode === "renderer-owned-fused-ldr-native" ? [] : passes.map((pass) => pass.name),
-    rendererOwnedPassNames: passes.map((pass) => pass.name),
-    clarityWarnings,
-    passes: passDiagnostics,
-    claimBoundary: "This plan describes the renderer-owned postprocess pass chain for the current frame. It does not prove EffectComposer parity, LUT/AOV layers, temporal accumulation, or missing depth/velocity inputs unless the report explicitly shows those inputs."
-  };
-}
-
-function canFuseLdrPostprocessPlan(sourceTargetFormat: RendererPostprocessTargetFormat, passes: readonly RendererPostProcessPassPlan[]): boolean {
-  return passes.length > 1
-    && (sourceTargetFormat === "rgba8" || passes[0]?.name === "tone-mapping")
-    && passes.every((pass) => pass.name === "tone-mapping" || pass.name === "color-grade" || pass.name === "fxaa")
-    && passes.every((pass, index) => {
-      const previousRank = index === 0 ? -1 : ldrFusionPassRank(passes[index - 1]!.name);
-      return ldrFusionPassRank(pass.name) >= previousRank;
-    });
-}
-
-function ldrFusionPassRank(name: RendererPostProcessPassName): number {
-  if (name === "tone-mapping") return 0;
-  if (name === "color-grade") return 1;
-  if (name === "fxaa") return 2;
-  return Number.POSITIVE_INFINITY;
-}
-
-function isDepthPostprocessPassName(name: RendererPostProcessPassName): boolean {
-  return name === "depth-of-field" || name === "contact-shadow" || name === "ssao" || name === "ssr";
-}
-
-function postprocessPassHasDepth(options: RendererPostProcessPassPlan["options"]): boolean {
-  return typeof options === "object" && options !== null && "depth" in options && Boolean((options as { readonly depth?: unknown }).depth);
-}
-
-function postprocessPassHasVelocity(options: RendererPostProcessPassPlan["options"]): boolean {
-  return typeof options === "object" && options !== null && "velocity" in options && Boolean((options as { readonly velocity?: unknown }).velocity);
-}
-
-function missingPostprocessInputs(
-  passes: readonly RendererPostProcessPassPlan[],
-  context: RendererPostprocessPlanContext
-): string[] {
-  const missing: string[] = [];
-  for (const pass of passes) {
-    if (isDepthPostprocessPassName(pass.name) && !postprocessPassHasDepth(pass.options) && context.rendererDepthAvailable !== true) {
-      missing.push(`${pass.name}:depth`);
-    }
-    if (pass.name === "motion-blur" && !postprocessPassHasVelocity(pass.options)) {
-      missing.push("motion-blur:velocity");
-    }
-  }
-  return missing;
-}
-
-function postprocessClarityWarnings(
-  postprocess: RendererPostprocessPlanOptions,
-  passes: readonly RendererPostProcessPassPlan[],
-  executionMode: RendererPostprocessExecutionMode
-): string[] {
-  const warnings: string[] = [];
-  const bloom = typeof postprocess.bloom === "object" && postprocess.bloom !== null ? postprocess.bloom : undefined;
-  if (bloom) {
-    const threshold = bloom.threshold ?? 0.75;
-    const intensity = bloom.intensity ?? 0.35;
-    const radius = bloom.radius ?? 1;
-    if (threshold < 0.48 || intensity > 0.62 || radius > 3) {
-      warnings.push(`bloom-noise-risk threshold=${round3(threshold)} intensity=${round3(intensity)} radius=${round3(radius)}`);
-    }
-  }
-  const filmGrain = typeof postprocess.filmGrain === "object" && postprocess.filmGrain !== null ? postprocess.filmGrain : undefined;
-  if (filmGrain && (filmGrain.intensity ?? 0.08) >= 0.06) {
-    warnings.push(`film-grain-noise-risk intensity=${round3(filmGrain.intensity ?? 0.08)}`);
-  }
-  if (executionMode === "renderer-owned-pass-chain-readback" && passes.length > 2) {
-    warnings.push("multi-pass-readback-cost");
-  }
-  return warnings;
-}
-
-function round3(value: number): number {
-  return Math.round(value * 1000) / 1000;
-}