@forgeax/engine-render 0.1.28 → 0.1.30

package/src/assembly/webgpu-renderer-contract.ts

@@ -0,0 +1,69 @@
+import type { RhiCanvasContext, RhiDevice, RhiError } from '@forgeax/engine-rhi';
+import type { ImportTransport } from '@forgeax/engine-types';
+import type { RenderFeatureHost } from '../features/host';
+import type {
+  HealthListenerRegistry,
+  LostListenerRegistry,
+  RhiErrorListenerRegistry,
+} from '../lifecycle';
+import type { GpuPassTimingReason } from '../record/gpu-pass-timing/errors.js';
+import type {
+  GpuPassTimingCapture,
+  GpuPassTimingFrameIdentity,
+} from '../record/gpu-pass-timing/index.js';
+import type {
+  AtmosphereShaderSources,
+  FrameObservationDomain,
+  RenderDebugOverlay,
+  RendererOptions,
+  SsrShaderSources,
+  VolumetricFogShaderSources,
+} from '../render-contract';
+import type { TypedFrameObservationCapture } from '../typed-render-graph-primitives';
+import type { RhiBackendPack } from './backend-contract';
+import type { BundlerOptions } from './bundler-contract';
+import type { RendererAssemblyImplementation } from './host-contract';
+import type { MeshSsboGrowResult, MeshSsboState } from './mesh-ssbo-grow';
+
+export type WebGPUOutcome =
+  | { kind: 'ok'; renderer: RendererAssemblyImplementation }
+  | { kind: 'rhi-err'; error: RhiError }
+  | { kind: 'throw'; error: Error };
+
+export interface WebGPURendererInternals {
+  canvas: HTMLCanvasElement | OffscreenCanvas;
+  device: RhiDevice;
+  context: RhiCanvasContext;
+  options: RendererOptions | undefined;
+  bundler: BundlerOptions | undefined;
+  lostRegistry: LostListenerRegistry;
+  errorRegistry: RhiErrorListenerRegistry;
+  healthRegistry: HealthListenerRegistry;
+  pack: RhiBackendPack;
+  importTransport?: ImportTransport | undefined;
+  growMeshSsbo?: (neededSlots: number) => MeshSsboGrowResult;
+  meshSsboState?: MeshSsboState;
+  featureHost?: RenderFeatureHost;
+  debugOverlay?: RenderDebugOverlay;
+  volumetricFogShaders?: VolumetricFogShaderSources | undefined;
+  ssrShaders?: SsrShaderSources | undefined;
+  atmosphereShaders?: AtmosphereShaderSources | undefined;
+  gpuPassTimingSubmittedWork?: Promise<void> | undefined;
+  lossObserver: { current?: (detail: string) => void };
+  generationState: {
+    current: number;
+    onStaleLoss?: () => void;
+  };
+  getMaterialShaderUvSetCount?: (materialShaderId: string) => number | undefined;
+  gpuPassTimingFrameIdentity?: GpuPassTimingFrameIdentity | undefined;
+  gpuPassTimingCapture?: GpuPassTimingCapture | undefined;
+  gpuPassTimingBeginReason?: GpuPassTimingReason | undefined;
+  observationCaptureOwner?: {
+    register(capture: TypedFrameObservationCapture): void;
+    consume(frameNumber: number): readonly TypedFrameObservationCapture[];
+    drain(): readonly TypedFrameObservationCapture[];
+  };
+  observationCaptureDomains?: readonly FrameObservationDomain[] | undefined;
+  observationFrameId?: number | undefined;
+  observationGraphGeneration?: number | undefined;
+}

package/src/assembly/webgpu-renderer-guards.ts

@@ -0,0 +1,32 @@
+import type { World } from '@forgeax/engine-ecs';
+import { RendererContractFailureError, RendererOperationError } from '../errors/render';
+
+/**
+ * Derived geometry and voxel physics publish together. A draw is rejected
+ * until that pair has completed its fixed-step writeback, so the renderer
+ * never consumes a half-published World snapshot.
+ */
+export function derivedPhysicsFrameError(
+  worlds: readonly World[],
+): RendererOperationError<'frame-input-invalid'> | undefined {
+  for (const world of worlds) {
+    if (!world.hasResource('PhysicsWorld')) continue;
+    const physics = world.getResource<{
+      readonly getDerivedAdmission?: () => unknown;
+      readonly getDerivedRecoveryState?: () => string;
+    }>('PhysicsWorld');
+    if (
+      physics?.getDerivedAdmission?.() !== undefined ||
+      physics?.getDerivedRecoveryState?.() === 'rebuild-required'
+    ) {
+      return new RendererOperationError('frame-input-invalid', {
+        operation: 'draw',
+        cause: new RendererContractFailureError(
+          'draw',
+          'paired geometry admission must finish physics step and writeback in a healthy World before draw',
+        ),
+      });
+    }
+  }
+  return undefined;
+}

package/src/assembly/webgpu-renderer-observation.ts

@@ -0,0 +1,43 @@
+import type { Buffer } from '@forgeax/engine-rhi';
+import { RendererContractFailureError } from '../errors/render';
+import type { TypedFrameObservationCapture } from '../typed-render-graph-primitives';
+
+/** Dispose receipt-bound readback buffers while retaining failed ownership. */
+export function disposeObservationCaptureSet(
+  captures: readonly TypedFrameObservationCapture[],
+  destroyed: WeakSet<Buffer>,
+  failures: WeakMap<Buffer, RendererContractFailureError>,
+  fire: (failure: RendererContractFailureError) => void,
+): RendererContractFailureError | undefined {
+  let firstFailure: RendererContractFailureError | undefined;
+  for (const capture of captures) {
+    if (destroyed.has(capture.buffer)) continue;
+    const previousFailure = failures.get(capture.buffer);
+    try {
+      const result = capture.device.destroyBuffer(capture.buffer);
+      if (result.ok) {
+        destroyed.add(capture.buffer);
+        failures.delete(capture.buffer);
+        continue;
+      }
+      const failure = new RendererContractFailureError(
+        'observe',
+        `destroying ${capture.domain} receipt-bound readback failed: ${result.error.code}`,
+      );
+      failures.set(capture.buffer, failure);
+      if (previousFailure === undefined) fire(failure);
+      firstFailure ??= failure;
+    } catch (cause) {
+      const failure = new RendererContractFailureError(
+        'observe',
+        `destroying ${capture.domain} receipt-bound readback threw: ${
+          cause instanceof Error ? cause.message : String(cause)
+        }`,
+      );
+      failures.set(capture.buffer, failure);
+      if (previousFailure === undefined) fire(failure);
+      firstFailure ??= failure;
+    }
+  }
+  return firstFailure;
+}

package/src/assembly/webgpu-renderer-recovery-failure.ts

@@ -0,0 +1,62 @@
+import type { DeviceResourceKind } from '../device/resource-types';
+import type { RecoveryGuidance, RecoveryPhase } from './renderer-lifecycle';
+
+export interface RecoveryFailureLocation {
+  readonly phase: RecoveryPhase;
+  readonly retryable: boolean;
+  readonly guidance: RecoveryGuidance;
+  readonly owner: string;
+  readonly resourceKind: DeviceResourceKind;
+  readonly cause: unknown;
+}
+
+function recoveryCauseCode(cause: unknown): string | undefined {
+  if (typeof cause !== 'object' || cause === null) return undefined;
+  const directCode = (cause as { readonly code?: unknown }).code;
+  if (typeof directCode === 'string') return directCode;
+  const detail = (cause as { readonly detail?: unknown }).detail;
+  if (typeof detail !== 'object' || detail === null) return undefined;
+  const detailCode = (detail as { readonly code?: unknown }).code;
+  if (typeof detailCode === 'string') return detailCode;
+  return recoveryCauseCode((detail as { readonly cause?: unknown }).cause);
+}
+
+export function createRecoveryFailureLocation(
+  phase: RecoveryPhase,
+  cause: unknown,
+  overrides: Partial<Omit<RecoveryFailureLocation, 'phase' | 'cause'>> = {},
+): RecoveryFailureLocation {
+  const code = recoveryCauseCode(cause) ?? '';
+  const resourceKind: DeviceResourceKind = code.includes('shader')
+    ? 'shader'
+    : code.includes('buffer')
+      ? 'buffer'
+      : code.includes('texture')
+        ? 'texture'
+        : code.includes('binding')
+          ? 'binding'
+          : phase === 'rehydrate'
+            ? 'shader'
+            : phase === 'acquire-adapter' || phase === 'acquire-device'
+              ? 'surface'
+              : phase === 'publish' || phase === 'cleanup'
+                ? 'surface'
+                : 'pipeline';
+  const owner =
+    code.includes('shader') || phase === 'rehydrate'
+      ? 'shader'
+      : phase === 'acquire-adapter' || phase === 'acquire-device'
+        ? 'backend'
+        : phase === 'compile-graph'
+          ? 'pipeline'
+          : 'renderer';
+  return {
+    phase,
+    retryable: false,
+    guidance: 'repair-owner',
+    owner,
+    resourceKind,
+    cause,
+    ...overrides,
+  };
+}