@forgeax/engine-render 0.1.23 → 0.1.24

package/src/features/host.ts

@@ -1,6 +1,7 @@
 import type { EntityHandle } from '@forgeax/engine-ecs';
 import type { RhiCaps, TextureFormat } from '@forgeax/engine-rhi';
 import { err, ok, type Result } from '@forgeax/engine-types';
+import type { DeviceScope, LifecycleResourceSpec } from '../device/device-scope';
 import {
   type RenderError,
   RenderFeatureCapabilityMissingError,
@@ -175,6 +176,7 @@ export interface RenderFeatureHost {
     batches: readonly RenderFeaturePreparedResourceBatch[],
   ): Result<void, RenderError>;
   recover(input: RenderFeatureRecoverInput): Result<void, RenderError>;
+  createRecoveryRoot(scope: DeviceScope): LifecycleResourceSpec<unknown>;
   diagnostics(): readonly RenderFeatureDiagnostics[];
   /** Subscribe to lifecycle projection changes; unchanged active frames are silent. */
   subscribeDiagnostics(listener: () => void): () => void;
@@ -915,6 +917,20 @@ class FeatureHostImpl implements RenderFeatureHost {
     return this.slots.map((slot) => slot.feature);
   }
 
+  createRecoveryRoot(scope: DeviceScope): LifecycleResourceSpec<unknown> {
+    return {
+      kind: 'feature',
+      create: () => {
+        if (!scope.isAlive()) throw new Error('Feature candidate scope is not active.');
+        // The root carries the detached host owner itself. A scalar marker is
+        // not evidence that feature planning/preparation actually ran; the
+        // candidate graph and host own the prepared resources.
+        return this;
+      },
+      cleanup: () => undefined,
+    };
+  }
+
   private publishDiagnosticsChanged(): void {
     for (const listener of this.diagnosticsListeners) {
       try {

package/src/features/prepared-gpu-work.ts

@@ -11,6 +11,7 @@ import type {
   ShaderModule,
 } from '@forgeax/engine-rhi';
 import { type BindGroupLayoutDescriptor, err, ok, type Result } from '@forgeax/engine-types';
+import type { DeviceScope, LifecycleResourceSpec } from '../device/device-scope';
 import { type RenderError, RenderFeaturePreparationFailedError } from '../errors/render';
 import type { PipelineBuilderShaderModuleFactory } from '../pipeline-builder';
 import type { RenderFeatureShaderModuleMode } from './types';
@@ -910,6 +911,8 @@ function createRenderFeatureGpuWorkSession(input: {
  * retains the per-feature prepared GPU state and recreates it after recovery.
  */
 export interface RenderFeatureGpuWorkOwner {
+  /** Candidate root carries this detached GPU-work owner itself. */
+  createRecoveryRoot(scope: DeviceScope): LifecycleResourceSpec<unknown>;
   beginFeature(
     featureIdentity: string,
     generation: number,
@@ -935,9 +938,21 @@ export function createRenderFeatureGpuWorkOwner(input: {
       session: RenderFeatureGpuPrepareSession;
     }
   >();
-
-  return {
+  let disposed = false;
+
+  const owner: RenderFeatureGpuWorkOwner = {
+    createRecoveryRoot: (scope) => ({
+      kind: 'feature',
+      create: () => {
+        if (!scope.isAlive()) throw new Error('Feature GPU candidate scope is not active.');
+        return owner;
+      },
+      cleanup: () => undefined,
+    }),
     beginFeature: (featureIdentity, generation, requestedShaderModuleMode = 'validated') => {
+      if (disposed) {
+        throw new Error('Render feature GPU work owner is disposed.');
+      }
       const shaderModuleMode = requestedShaderModuleMode;
       const existing = sessions.get(featureIdentity);
       if (existing?.generation === generation && existing.shaderModuleMode === shaderModuleMode) {
@@ -962,6 +977,8 @@ export function createRenderFeatureGpuWorkOwner(input: {
     resolveBuffer: (featureIdentity, reference) =>
       sessions.get(featureIdentity)?.session.resolveBuffer(reference),
     dispose: () => {
+      if (disposed) return ok(undefined);
+      disposed = true;
       let first: RenderError | undefined;
       for (const { session } of sessions.values()) {
         const disposed = session.dispose();
@@ -971,4 +988,5 @@ export function createRenderFeatureGpuWorkOwner(input: {
       return first === undefined ? ok(undefined) : err(first);
     },
   };
+  return owner;
 }

package/src/features/prepared-graphics-store.ts

@@ -1,5 +1,6 @@
 import type { TextureFormat } from '@forgeax/engine-rhi';
 import { err, ok, type Result } from '@forgeax/engine-types';
+import type { DeviceScope, LifecycleResourceSpec } from '../device/device-scope';
 import { type RenderError, RenderFeaturePreparationFailedError } from '../errors/render';
 import type {
   PreparedKind,
@@ -81,6 +82,7 @@ export interface PreparedGraphicsStore {
   beginFrame(featureIdentity: string, generation: number): PreparedGraphicsTransaction;
   snapshot(featureIdentity: string): PreparedGraphicsStoreSnapshot;
   invalidate(featureIdentity: string, generation: number): void;
+  createRecoveryRoot(scope: DeviceScope): LifecycleResourceSpec<unknown>;
 }
 
 interface Slot {
@@ -418,6 +420,21 @@ class PreparedGraphicsStoreImpl implements PreparedGraphicsStore {
     }
   }
 
+  createRecoveryRoot(scope: DeviceScope): LifecycleResourceSpec<unknown> {
+    return {
+      kind: 'buffer',
+      create: () => {
+        if (!scope.isAlive()) throw new Error('Prepared graphics candidate scope is not active.');
+        const itemCount = [...this.slots.values()].reduce(
+          (count, slot) => count + slot.items.size,
+          0,
+        );
+        return Object.freeze({ generation: scope.generation, itemCount });
+      },
+      cleanup: () => undefined,
+    };
+  }
+
   registerReference(reference: object, item: PreparedGraphicsItem): void {
     this.references.set(reference, item);
   }

package/src/gpu-driven/production-raster.ts

@@ -20,6 +20,7 @@ import type {
 import { err, ok, RhiError } from '@forgeax/engine-rhi';
 import type { MaterialShaderArtifact } from '@forgeax/engine-shader';
 import type { MaterialRenderState } from '@forgeax/engine-types';
+import type { DeviceScope, LifecycleResourceSpec } from '../device/device-scope';
 import type { MeshGpuHandles } from '../device/gpu-residency';
 import { GPU_SCENE_WGSL } from '../gpu-scene-schema';
 import {
@@ -261,8 +262,8 @@ function activeFrustum(camera: CameraSnapshot): Float32Array {
       projection,
       camera.orthoLeft,
       camera.orthoRight,
-      camera.orthoBottom,
       camera.orthoTop,
+      camera.orthoBottom,
       camera.near,
       camera.far,
     );
@@ -297,6 +298,9 @@ function productionEligible(snapshot: RenderableSnapshot, batch: GpuDrivenBatch)
   const shader = material.materialShaderId ?? 'forgeax::default-unlit';
   return (
     shader === 'forgeax::default-unlit' &&
+    // The production rigid shader owns triangle-list raster only. Lines and
+    // points stay with their CPU/specialized topology owners.
+    batch.key.topology === 'triangle-list' &&
     batch.key.materialResourceClass === EMPTY_RESOURCE_CLASS &&
     material.baseColorTexture === undefined &&
     material.transparent !== true
@@ -928,7 +932,62 @@ export interface PreparedGpuDrivenFrame {
   ): Result<RenderPipelineGpuDrivenProjection, RenderGraphError | RhiError>;
 }
 
+export interface RecoveryCapabilityFacts {
+  readonly generation: number;
+  readonly shaderCompilation: boolean;
+  readonly compute: boolean;
+  readonly storageBuffer: boolean;
+  readonly indirectDrawing: boolean;
+  readonly multisample: boolean;
+}
+
+export type RecoveryCapabilityOutcome =
+  | {
+      readonly status: 'ready' | 'fallback';
+      readonly generation: number;
+      readonly disabled: readonly string[];
+    }
+  | {
+      readonly status: 'disabled';
+      readonly generation: number;
+      readonly disabled: readonly string[];
+      readonly allocations: 0;
+    }
+  | {
+      readonly status: 'refused';
+      readonly generation: number;
+      readonly failedOwner: 'shader-material-pipeline';
+      readonly resourceKind: 'pipeline';
+    };
+
+export function classifyRecoveryCapability(
+  facts: RecoveryCapabilityFacts,
+): RecoveryCapabilityOutcome {
+  if (!facts.shaderCompilation) {
+    return {
+      status: 'refused',
+      generation: facts.generation,
+      failedOwner: 'shader-material-pipeline',
+      resourceKind: 'pipeline',
+    };
+  }
+  if (!facts.compute || !facts.storageBuffer || !facts.indirectDrawing) {
+    return {
+      status: 'disabled',
+      generation: facts.generation,
+      disabled: ['gpu-driven'],
+      allocations: 0,
+    };
+  }
+  return {
+    status: facts.multisample ? 'ready' : 'fallback',
+    generation: facts.generation,
+    disabled: [],
+  };
+}
+
 export class GpuDrivenProduction {
+  private disposed = false;
   private view: GpuDrivenView | undefined;
   private raster: GpuDrivenRigidRaster | undefined;
   private standardRaster: StandardPbrRasterAdapter | undefined;
@@ -972,6 +1031,27 @@ export class GpuDrivenProduction {
     private readonly shaderModuleFactory: PipelineBuilderShaderModuleFactory,
   ) {}
 
+  static forDevice(
+    device: RhiDevice,
+    shaderModuleFactory: PipelineBuilderShaderModuleFactory,
+  ): GpuDrivenProduction {
+    return new GpuDrivenProduction(device, shaderModuleFactory);
+  }
+
+  createRecoveryRoot(scope: DeviceScope): LifecycleResourceSpec<unknown> {
+    return {
+      kind: 'scene-table',
+      create: () => {
+        if (!scope.isAlive()) throw new Error('GPU-driven candidate scope is not active.');
+        // Keep the actual detached production owner in the generation
+        // aggregate. The recovery transaction, not a marker object, is the
+        // owner that is published or discarded exactly once.
+        return this;
+      },
+      cleanup: () => undefined,
+    };
+  }
+
   prepare(input: {
     readonly scene: PersistentGpuDrivenState | undefined;
     readonly camera: CameraSnapshot;
@@ -1000,7 +1080,20 @@ export class GpuDrivenProduction {
     this.telemetryGeometryWork = 0;
     this.telemetryRootGeometryWork = 0;
     this.indirectDrawCount = 0;
-    if (input.hdrp || input.scene === undefined || selectGpuLodLane(this.device.caps) === 'cpu') {
+    const capability = classifyRecoveryCapability({
+      generation: 0,
+      shaderCompilation: true,
+      compute: this.device.caps.compute,
+      storageBuffer: this.device.caps.storageBuffer,
+      indirectDrawing: this.device.caps.indirectDrawing,
+      multisample: true,
+    });
+    if (
+      input.hdrp ||
+      input.scene === undefined ||
+      capability.status === 'disabled' ||
+      selectGpuLodLane(this.device.caps) === 'cpu'
+    ) {
       this.gpuOwnedEntityCount = 0;
       this.sceneRowsRequired = false;
       return ok(undefined);
@@ -1457,6 +1550,8 @@ export class GpuDrivenProduction {
   }
 
   dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
     this.view?.dispose();
     this.view = undefined;
     this.raster = undefined;

package/src/gpu-scene.ts

@@ -201,6 +201,7 @@ function coalesceSlots(
 
 /** Persistent GPU tables derived only from renderer projection slots. */
 export class GpuScene {
+  private disposed = false;
   private tableBytes: Record<GpuSceneTableName, ArrayBuffer>;
   private transformBytes: Uint8Array;
   private transformView: DataView;
@@ -432,6 +433,8 @@ export class GpuScene {
   }
 
   dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
     for (const buffer of Object.values(this.buffers)) this.device.destroyBuffer(buffer);
   }
 
@@ -583,8 +586,6 @@ export class GpuScene {
       writeVec4(material, materialOffset + offset(MATERIAL, 'params1'), [
         snapshot.metallic ?? 0,
         snapshot.roughness ?? 1,
-        snapshot.clearcoat ?? 0,
-        snapshot.clearcoatRoughness ?? 0,
       ]);
       writeVec4(material, materialOffset + offset(MATERIAL, 'params2'), [
         snapshot.emissive?.[0] ?? 0,