@forgeax/engine-render 0.1.23 → 0.1.25

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 {
@@ -48,7 +49,12 @@ import {
   projectedHeightForCandidate,
   type SubmissionPlan,
 } from './batch-topology';
-import { type GpuDrivenLodSelectionInspection, GpuDrivenView, selectGpuLodLane } from './view-gpu';
+import {
+  GPU_DRIVEN_VIEW_WGSL,
+  type GpuDrivenLodSelectionInspection,
+  GpuDrivenView,
+  selectGpuLodLane,
+} from './view-gpu';
 
 const VERTEX_STAGE = 0x1;
 const FRAGMENT_STAGE = 0x2;
@@ -261,8 +267,8 @@ function activeFrustum(camera: CameraSnapshot): Float32Array {
       projection,
       camera.orthoLeft,
       camera.orthoRight,
-      camera.orthoBottom,
       camera.orthoTop,
+      camera.orthoBottom,
       camera.near,
       camera.far,
     );
@@ -297,6 +303,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 +937,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 +1036,55 @@ export class GpuDrivenProduction {
     private readonly shaderModuleFactory: PipelineBuilderShaderModuleFactory,
   ) {}
 
+  static forDevice(
+    device: RhiDevice,
+    shaderModuleFactory: PipelineBuilderShaderModuleFactory,
+  ): GpuDrivenProduction {
+    return new GpuDrivenProduction(device, shaderModuleFactory);
+  }
+
+  /** Recovery has no frame retry: await generated programs before preparing the graph. */
+  static async forRecoveryDevice(
+    device: RhiDevice,
+    factory: PipelineBuilderShaderModuleFactory,
+    createShaderModule: (descriptor: {
+      code: string;
+      label?: string;
+    }) => Promise<Result<ShaderModule, RhiError>>,
+  ): Promise<Result<GpuDrivenProduction, RhiError>> {
+    const modules = new Map<string, ShaderModule>();
+    for (const descriptor of [
+      { label: 'gpu-driven-view', code: GPU_DRIVEN_VIEW_WGSL },
+      { label: 'gpu-driven-rigid-unlit', code: GPU_DRIVEN_RIGID_UNLIT_WGSL },
+    ]) {
+      const module = await createShaderModule(descriptor);
+      if (!module.ok) return module;
+      modules.set(descriptor.code, module.value);
+    }
+    return ok(
+      new GpuDrivenProduction(device, {
+        createShaderModule: (descriptor) => {
+          const module = modules.get(descriptor.code);
+          return module === undefined ? factory.createShaderModule(descriptor) : ok(module);
+        },
+      }),
+    );
+  }
+
+  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 +1113,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 +1583,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;
@@ -224,6 +225,10 @@ export class GpuScene {
     drawTemplate: [],
     material: [],
   };
+  /** Transform rows whose previous value advances only after submit. */
+  private readonly pendingTemporalTransforms = new Set<number>();
+  /** Previous rows whose post-submit upload must be retried before the next draw. */
+  private readonly pendingTemporalUploads = new Set<number>();
 
   private constructor(
     private readonly device: RhiDevice,
@@ -272,31 +277,47 @@ export class GpuScene {
   }
 
   sync(delta: RenderSceneApplyResult): Result<GpuSceneSyncResult, RhiError> {
+    for (const transformIndex of this.pendingTemporalUploads) {
+      this.writesByTable.transform.push(transformIndex);
+    }
+    const pendingWrites = TABLE_NAMES.some((name) => this.writesByTable[name].length > 0);
     if (
       delta.createdSlots.length === 0 &&
       delta.updatedSlots.length === 0 &&
       delta.recreatedSlots.length === 0 &&
-      delta.removedSlots.length === 0
+      delta.removedSlots.length === 0 &&
+      !pendingWrites
     ) {
       this.noChangeFrames += 1;
       return ok({ ranges: 0, bytes: 0, grew: false, cleared: 0 });
     }
     const writesByTable = this.writesByTable;
-    for (const name of TABLE_NAMES) writesByTable[name].length = 0;
-    if (!this.identityUploaded) writesByTable.transform.push(0);
+    if (!this.identityUploaded && !writesByTable.transform.includes(0)) {
+      writesByTable.transform.push(0);
+    }
     let highestChangedSlot = -1;
-    for (const records of [delta.createdSlots, delta.recreatedSlots]) {
+    const contentUpdatedSlots = delta.contentUpdatedSlots ?? [];
+    const contentUpdatedSlotIds = new Set(contentUpdatedSlots.map((record) => record.slot));
+    const allocationResets = new Set<number>();
+    // RenderScene may recycle a released CPU slot for a different identity in
+    // the same delta. Clear the old GPU allocation before ensuring the new
+    // record; otherwise the later removal pass clears the newly allocated
+    // record and the next transform-only update sees no allocation.
+    for (const record of delta.removedSlots) {
+      if (record.slot > highestChangedSlot) highestChangedSlot = record.slot;
+      this.clearSlot(record.slot, writesByTable);
+    }
+    for (const records of [delta.createdSlots, contentUpdatedSlots, delta.recreatedSlots]) {
       for (const record of records) {
+        const previous = this.allocations[record.slot];
         this.ensureAllocation(record, writesByTable);
+        if (previous !== this.allocations[record.slot]) allocationResets.add(record.slot);
         if (record.slot > highestChangedSlot) highestChangedSlot = record.slot;
       }
     }
     for (const record of delta.updatedSlots) {
       if (record.slot > highestChangedSlot) highestChangedSlot = record.slot;
     }
-    for (const record of delta.removedSlots) {
-      if (record.slot > highestChangedSlot) highestChangedSlot = record.slot;
-    }
     const requiredCapacity = Math.max(
       highestChangedSlot + 1,
       this.instances.requiredCapacity(),
@@ -311,11 +332,18 @@ export class GpuScene {
     }
 
     for (const record of delta.createdSlots) this.writeSlot(record, true, writesByTable);
-    for (const record of delta.updatedSlots) this.writeRootTransform(record, false, writesByTable);
+    for (const record of contentUpdatedSlots) {
+      this.writeSlot(record, allocationResets.has(record.slot), writesByTable);
+    }
+    for (const record of delta.updatedSlots) {
+      if (contentUpdatedSlotIds.has(record.slot)) continue;
+      this.writeRootTransform(record, false, writesByTable);
+    }
     for (const record of delta.recreatedSlots) this.writeSlot(record, true, writesByTable);
-    for (const record of delta.removedSlots) this.clearSlot(record.slot, writesByTable);
     const uploaded = this.uploadRows(writesByTable);
     if (!uploaded.ok) return uploaded;
+    this.pendingTemporalUploads.clear();
+    for (const name of TABLE_NAMES) writesByTable[name].length = 0;
     this.identityUploaded = true;
     this.clearedSlots += delta.removedSlots.length;
     return ok({
@@ -328,27 +356,47 @@ export class GpuScene {
 
   /** Publish current transforms as previous only after a successful submit. */
   commitTemporalFrame(enabled = true): Result<void, RhiError> {
-    if (!enabled) return ok(undefined);
-    const nextTransform = this.tableBytes.transform.slice(0);
-    const next = new Uint8Array(nextTransform);
-    const current = this.transformBytes;
+    if (!enabled) {
+      this.pendingTemporalTransforms.clear();
+      this.pendingTemporalUploads.clear();
+      return ok(undefined);
+    }
+    if (this.pendingTemporalTransforms.size === 0) return ok(undefined);
     const currentOffset = offset(TRANSFORM, 'currentWorld');
     const previousOffset = offset(TRANSFORM, 'previousWorld');
-    for (let index = 0; index < this.capacity; index += 1) {
-      next.set(
-        current.subarray(
+    const ranges = coalesceSlots([...this.pendingTemporalTransforms]);
+    for (const range of ranges) {
+      for (let index = range.start; index < range.end; index += 1) {
+        this.pendingTemporalUploads.add(index);
+      }
+    }
+    for (const range of ranges) {
+      for (let index = range.start; index < range.end; index += 1) {
+        this.transformBytes.copyWithin(
+          index * TRANSFORM.stride + previousOffset,
           index * TRANSFORM.stride + currentOffset,
           index * TRANSFORM.stride + currentOffset + 64,
-        ),
-        index * TRANSFORM.stride + previousOffset,
+        );
+      }
+    }
+    for (const range of ranges) {
+      const firstOffset = range.start * TRANSFORM.stride;
+      const lastOffset = range.end * TRANSFORM.stride;
+      const uploaded = this.device.queue.writeBuffer(
+        this.buffers.transform,
+        firstOffset,
+        this.transformBytes.subarray(firstOffset, lastOffset),
       );
+      if (!uploaded.ok) return uploaded;
     }
-    const uploaded = this.device.queue.writeBuffer(this.buffers.transform, 0, next);
-    if (!uploaded.ok) return uploaded;
-    this.tableBytes.transform = nextTransform;
-    this.refreshTransformViews();
-    this.uploadRanges += 1;
-    this.uploadBytes += next.byteLength;
+    this.pendingTemporalTransforms.clear();
+    this.pendingTemporalUploads.clear();
+    const bytes = ranges.reduce(
+      (total, range) => total + (range.end - range.start) * TRANSFORM.stride,
+      0,
+    );
+    this.uploadRanges += ranges.length;
+    this.uploadBytes += bytes;
     return ok(undefined);
   }
 
@@ -358,6 +406,9 @@ export class GpuScene {
     this.transforms.reset(1);
     this.draws.reset();
     this.materials.reset();
+    this.pendingTemporalTransforms.clear();
+    this.pendingTemporalUploads.clear();
+    for (const name of TABLE_NAMES) this.writesByTable[name].length = 0;
     const writesByTable: Record<GpuSceneTableName, number[]> = {
       primitive: [],
       instance: [],
@@ -432,6 +483,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);
   }
 
@@ -517,7 +570,8 @@ export class GpuScene {
         const localCurrentOffset = localOffset + offset(TRANSFORM, 'currentWorld');
         const localPreviousOffset = localOffset + offset(TRANSFORM, 'previousWorld');
         writeMat4(transform, localCurrentOffset, localWorld);
-        writeMat4(transform, localPreviousOffset, localWorld);
+        if (resetPrevious) writeMat4(transform, localPreviousOffset, localWorld);
+        else this.pendingTemporalTransforms.add(transformIndex);
         writes.transform.push(transformIndex);
       }
       writes.instance.push(instanceIndex);
@@ -583,8 +637,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,
@@ -630,14 +682,16 @@ export class GpuScene {
     const allocation = this.allocations[record.slot];
     if (allocation === undefined) throw new RangeError('GPU Scene allocation unavailable');
     const transformOffset = allocation.transformStart * TRANSFORM.stride;
-    const currentOffset = transformOffset + offset(TRANSFORM, 'currentWorld');
     const previousOffset = transformOffset + offset(TRANSFORM, 'previousWorld');
     if (resetPrevious) {
       writeMat4(this.transformView, previousOffset, record.snapshot.transform.world);
-    } else {
-      this.transformBytes.copyWithin(previousOffset, currentOffset, currentOffset + 64);
     }
-    writeMat4(this.transformView, currentOffset, record.snapshot.transform.world);
+    writeMat4(
+      this.transformView,
+      transformOffset + offset(TRANSFORM, 'currentWorld'),
+      record.snapshot.transform.world,
+    );
+    if (!resetPrevious) this.pendingTemporalTransforms.add(allocation.transformStart);
     writes.transform.push(allocation.transformStart);
   }
 
@@ -742,6 +796,8 @@ export class GpuScene {
         TRANSFORM.stride,
       ).fill(0);
       writes.transform.push(transformIndex);
+      this.pendingTemporalTransforms.delete(transformIndex);
+      this.pendingTemporalUploads.delete(transformIndex);
     }
     for (let ordinal = 0; ordinal < allocation.drawCount; ordinal += 1) {
       const drawIndex = allocation.drawStart + ordinal;