@forgeax/engine-render 0.1.4 → 0.1.7

package/src/record/frame-snapshot.ts

@@ -2,19 +2,19 @@
 // Extracted from render-system-record.ts (feat-20260704 M3/w17, pure move).
 
 import type { World } from '@forgeax/engine-ecs';
-import type { WorldProjection } from '@forgeax/engine-ecs/projection';
 import { vec3 } from '@forgeax/engine-math';
+import type { ResolvedColorTargetDescriptor } from '@forgeax/engine-render-graph';
+import type { Texture } from '@forgeax/engine-rhi';
 import type { ClusterBinScratch } from '../cluster-binner';
-import type { EnvironmentGenerationState } from '../environment/generation';
+import type { GpuBuffer } from '../gpu-resource';
 
 /**
  * feat-20260708-composited-multi-world-rendering M1 / D-1 / D-9:
  * worldId-entityKey composite key helper. Formula: `worldId * 2^32 + entityKey`.
  *
- * worldId is the renderer-local stable WorldRenderId assigned for one World
- * attachment generation. entityKey is the packed Entity u32
- * (encodeEntity(indexSlot, generation)) surfaced through
- * `RenderableSnapshot.entityKey`.
+ * worldId is the index into `worlds[]` (the `draw` call argument). entityKey
+ * is the packed Entity u32 (encodeEntity(indexSlot, generation)) surfaced
+ * through `RenderableSnapshot.entityKey`.
  *
  * Key properties:
  *   - worldId=0 identity: `worldEntityKey(0, k) === k` — single-world path
@@ -31,25 +31,6 @@ export function worldEntityKey(worldId: number, entityKey: number): number {
   return worldId * 4294967296 + entityKey; // 2^32 = 4294967296
 }
 
-declare const RASTER_ITEM_KEY: unique symbol;
-
-/** Stable identity for one renderable/submesh/pass draw item. */
-export type RasterItemKey = string & { readonly [RASTER_ITEM_KEY]: true };
-
-/**
- * Build the value identity shared by GPU-driven ownership and CPU recording.
- * The string form keeps the four numeric dimensions lossless without relying
- * on a process-wide allocation table.
- */
-export function rasterItemKey(
-  worldId: number,
-  entityKey: number,
-  submeshIndex: number,
-  passIndex: number,
-): RasterItemKey {
-  return `${worldId}:${entityKey}:${submeshIndex}:${passIndex}` as RasterItemKey;
-}
-
 /**
  * Cross-frame cache entry for a material bind group whose source material and
  * all resolved GPU resources are stable. The material snapshot identity is
@@ -58,7 +39,7 @@ export function rasterItemKey(
  */
 export interface MaterialBgAssemblyCacheEntry {
   readonly material: MaterialSnapshot;
-  /** Invalidates when any texture/sampler residency identity changes. */
+  /** Invalidates when a texture/sampler residency identity changes. */
   readonly materialResourceEpoch: number;
   readonly materialBgl: BindGroupLayout;
   /** Buffer identity changes when the shared material capacity grows. */
@@ -68,20 +49,14 @@ export interface MaterialBgAssemblyCacheEntry {
 }
 
 import type { CompiledRenderGraph } from '@forgeax/engine-render-graph';
-import type {
-  BindGroup,
-  BindGroupLayout,
-  Buffer,
-  CommandBuffer,
-  TextureView,
-} from '@forgeax/engine-rhi';
+import type { BindGroup, BindGroupLayout, Buffer, TextureView } from '@forgeax/engine-rhi';
 import type { MaterialRenderState, RenderPipelineAsset } from '@forgeax/engine-types';
+import type { MeshGpuHandles } from '../device/gpu-residency';
 import type { SkylightBindGroupResources } from '../ibl/skylight-bind-group';
 import type { InstanceBufferCacheEntry } from '../instance-buffer-cache';
+import type { CameraSnapshot } from '../render-contract';
 import type { RenderPipeline as RenderPipelineDef, RenderPipelineFrame } from '../render-pipeline';
-import type { MeshGpuHandles } from '../render-system';
 import type {
-  CameraSnapshot,
   DispatchEntry,
   MaterialSnapshot,
   PointShadowSnapshot,
@@ -89,8 +64,6 @@ import type {
   SpotLightSnapshot,
 } from '../render-system-extract';
 import type { ShadowAtlas } from '../shadow-atlas';
-import type { FrameObservationSource } from './frame-observation';
-import type { ShadowSubmitModeState } from './shadow-submit-mode';
 
 /**
  * feat-20260608-create-app-param-surface-trim / M1 / D-8 (q8 user lock):
@@ -103,6 +76,14 @@ import type { ShadowSubmitModeState } from './shadow-submit-mode';
  */
 export const ZERO_CAMERA_CLEAR_FALLBACK: readonly [number, number, number, number] = [0, 0, 0, 1];
 
+export interface FrameObservationSource {
+  readonly texture: Texture;
+  readonly descriptor: ResolvedColorTargetDescriptor;
+  readonly frameId: number;
+  readonly pipelineId: 'forgeax::standard';
+  readonly backendId: string;
+}
+
 /**
  * Build a synthetic CameraSnapshot the record stage uses when the world
  * carries no Camera entity. Identity-shaped projection / view inputs
@@ -120,8 +101,6 @@ export function makeZeroCameraFallbackSnapshot(): CameraSnapshot {
   identityWorld[10] = 1;
   identityWorld[15] = 1;
   return {
-    worldId: 0,
-    entityKey: 0,
     position: vec3.create(0, 0, 0),
     world: identityWorld,
     fov: Math.PI / 4,
@@ -140,7 +119,6 @@ export function makeZeroCameraFallbackSnapshot(): CameraSnapshot {
     exposure: 1.0,
     whitePoint: 4.0,
     antialias: 'none',
-    historyVersion: 0,
     bloom: 'off',
     bloomThreshold: 1.0,
     bloomIntensity: 1.0,
@@ -182,10 +160,12 @@ export function clampPcfKernelSize(value: number | undefined): number {
  */
 export interface RenderFrameState {
   frameNumber: number;
-  /** Renderer-owned analytic environment generation; no parallel ledger. */
-  environmentGeneration: EnvironmentGenerationState;
-  shadowSubmitModeState: ShadowSubmitModeState;
-  pendingShadowCommandBuffers: CommandBuffer[];
+  /** Optional graph resource lookup used by low-level record helpers and tests. */
+  readonly perFrameGraph?: {
+    readonly getColorTargetDescriptor: (key: string) => ResolvedColorTargetDescriptor | undefined;
+    readonly getColorTargetView: (key: string) => TextureView | undefined;
+    readonly getColorTargetTexture: (key: string) => Texture | undefined;
+  } | null;
   /** Last successfully rendered static directional shadow atlas token. */
   directionalShadowCache: DirectionalShadowCache | null;
   /** Set by a directional shadow pass when this frame refreshed the atlas. */
@@ -199,6 +179,8 @@ export interface RenderFrameState {
   currentDirectionalShadowView: TextureView | null;
   currentSpotShadowView: TextureView | null;
   readonly instanceBuffers: Map<number, InstanceBufferCacheEntry>;
+  /** Per-entity vertex buffers for the Standard CPU morph lane. */
+  readonly morphBuffers?: Map<number, MorphBufferCacheEntry>;
   readonly hdrpClusterBinScratch: ClusterBinScratch;
   /** Reusable HDRP cluster output buffers; sized once and grown only if the grid/cap changes. */
   hdrpClusterGridScratch: Uint32Array | null;
@@ -252,8 +234,6 @@ export interface RenderFrameState {
    * bound).
    */
   readonly warnedMissingBaseColorTextureHandles: Set<number>;
-  /** Once-per-material diagnostic dedupe for failed production readiness. */
-  readonly reportedMaterialDiagnosticKeys: Set<string>;
   /**
    * feat-20260527-sprite-nineslice M2 / w11 + M4 / w16 (AC-16): once-per-
    * renderable guard for the `nineslice.scale-too-small` metric increment.
@@ -322,7 +302,7 @@ export interface RenderFrameState {
    */
   readonly materialBgShared: Map<string, WeakMap<object, unknown>>;
   /** Cross-frame fast path for fully-resident, immutable material snapshots. */
-  readonly materialBgAssemblyCache: Map<number, MaterialBgAssemblyCacheEntry>;
+  readonly materialBgAssemblyCache: Map<string, MaterialBgAssemblyCacheEntry>;
   /**
    * feat-20260622-handle-to-id-allocator-elimination M1 / w2: singleton
    * material bind group cache (D-6). Single flat Map<variant, BindGroup>
@@ -353,7 +333,6 @@ export interface RenderFrameState {
    * remains last-known-good until the candidate compiles successfully.
    */
   installedPipelineHandle: number;
-  activePipelineId: string;
   /**
    * Active topology declaration resolved from the pipeline registry.
    */
@@ -408,7 +387,7 @@ export interface RenderFrameState {
   lastFoldBucketCount: number;
   /**
    * feat-20260625-spot-light-shadow-mapping M2 / w9 (D-2): per-frame projection
-   * of `lights.spot` from the extract stage. The URP `addSpotShadowPass` graph
+   * of `lights.spot` from the extract stage. The typed spot-shadow graph
    * pass reads this list to render each
    * castShadow spot's perspective depth into its `spotShadowDepth` atlas tile
    * (viewport keyed on `shadowAtlasTile`). `recordFrame` writes it before
@@ -419,6 +398,11 @@ export interface RenderFrameState {
   spotShadowSnapshots: readonly SpotLightSnapshot[];
 }
 
+export interface MorphBufferCacheEntry {
+  readonly buffer: GpuBuffer;
+  readonly byteLength: number;
+}
+
 /**
  * feat-20260518-pbr-direct-lighting-mvp M5 / w22.11 (D-2 + D-10 + AC-06):
  * mutable per-frame dispatch counter object owned by `createRenderSystem`
@@ -454,10 +438,12 @@ export interface BindGroupCounts {
  * transparent-sort output back to this entry, and an optional per-material
  * renderState override (bug-20260527-renderstate-pipeline-dispatch-gap D-4).
  * Module-scoped so RenderPipelineContext can type `validated` / `validatedOrdered`
- * without `any` (was a recordFrame-local interface before F-4).
+ * without a dynamic type escape (was a recordFrame-local interface before F-4).
  */
 export interface ValidatedRenderable {
   readonly source: RenderableSnapshot;
+  /** World that owns the renderable's asset handles and material snapshots. */
+  readonly world?: World;
   readonly mesh: MeshGpuHandles;
   readonly renderableIndex: number;
   readonly renderState: MaterialRenderState | undefined;
@@ -483,8 +469,8 @@ export interface ValidatedRenderable {
  * token beside the other RenderFrameState caches lets recordFrame skip a
  * static caster submission without teaching the public render-pipeline
  * contract about caching. Every source that can change caster depth is part
- * of the evidence: world change projection, asset catalogue, graph/target
- * identity, CSM matrices, and the GPU mesh-residency epoch.
+ * of the token: world mutation, asset catalogue, graph/target identity, CSM
+ * matrices, and the GPU mesh-residency epoch.
  *
  * @internal
  */
@@ -496,20 +482,19 @@ export interface DirectionalShadowCache {
   readonly graphTopologyKey: string | null;
   readonly shadowMapSize: number;
   readonly cascadeCount: number;
+  readonly lightViewProj: readonly Float32Array[];
   readonly meshResidencyEpoch: number;
-  /** Bounded cascade-local hashes of volume, space, Scene Fact, batch, and resource inputs. */
-  readonly cascadeTokens: readonly string[];
-  /** True when Scene Fact + four-view visibility, rather than ECS fallback clocks, own the token. */
-  readonly productionSceneToken: boolean;
 }
 
 /**
  * ECS state that can change the contents of a directional shadow map.
  *
- * The projection is evidence only; render snapshots remain owned by extract
- * and persistent scene state. A rebuild or any change conservatively misses.
+ * The ECS-owned RenderReadLease is the only render-facing mutation boundary.
+ * Its cursor is intentionally conservative: any published World change
+ * invalidates the cached atlas, while render never reaches through World for
+ * component-clock storage.
  */
 export interface DirectionalShadowWorldState {
-  /** Narrow change evidence; the projection never carries render snapshots. */
-  readonly projection: WorldProjection;
+  readonly worldIdentity: string;
+  readonly changeCursor: number;
 }

package/src/record/frame-targets.ts

@@ -1,19 +1,7 @@
 import type { RhiCanvasContext, Texture, TextureView } from '@forgeax/engine-rhi';
-import { err, ok, type Result } from '@forgeax/engine-types';
-import { type RenderError, RenderFeatureStageFailedError } from '../errors/render';
-import {
-  type RenderFeatureGraphicsPassDescriptor,
-  type RenderFeaturePreparedGraphicsState,
-  type RenderFeaturePreparedRef,
-  validateRenderFeatureGraphicsPass,
-} from '../features/prepared-graphics';
-import type {
-  PreparedGraphicsResolvedResource,
-  PreparedGraphicsResolvedSnapshot,
-} from '../prepare/prepared-graphics-resolver';
-import { configureSurface, type PipelineState, type RenderSystemInternals } from '../render-system';
+import type { RenderGraphExecutionPhase } from '../render-contract';
 import type { ExtractedLights } from '../render-system-extract';
-import type { RenderGraphExecutionPhase } from '../renderer';
+import { configureSurface, type PipelineState, type RenderSystemInternals } from './render-context';
 
 export function graphExecutionPhase(passName: string): RenderGraphExecutionPhase {
   if (passName.startsWith('shadowCascade')) return 'record/graph-execute/shadow';
@@ -33,8 +21,6 @@ export function graphExecutionPhase(passName: string): RenderGraphExecutionPhase
       return 'record/graph-execute/lighting';
     case 'forward':
       return 'record/graph-execute/forward';
-    case 'scene-temporal':
-      return 'record/graph-execute/scene-temporal';
     case 'tonemap':
       return 'record/graph-execute/tonemap';
     case 'debug-overlay':
@@ -98,241 +84,20 @@ export function acquireSwapChainTarget(
   const viewDescriptor =
     pipelineState.colorAttachmentFormat === pipelineState.format
       ? {}
-      : { format: pipelineState.colorAttachmentFormat as unknown as GPUTextureFormat };
+      : { format: pipelineState.colorAttachmentFormat as GPUTextureFormat };
   const viewResult = internals.device.createTextureView(currentTextureResult.value, viewDescriptor);
   if (!viewResult.ok) {
     internals.errorRegistry.fire(viewResult.error);
     return null;
   }
-  const textureSize = currentTextureResult.value as unknown as {
-    readonly width: number;
-    readonly height: number;
-  };
   return {
     currentTexture: currentTextureResult.value,
     view: viewResult.value,
-    targetW: textureSize.width | 0,
-    targetH: textureSize.height | 0,
+    targetW: internals.canvas.width | 0,
+    targetH: internals.canvas.height | 0,
   };
 }
 
-export interface RenderFeatureGraphicsRecordingLedger {
-  pipeline: number;
-  binding: number;
-  vertex: number;
-  index: number;
-  draw: number;
-  setPipeline?: (handle: unknown) => void;
-  setBindGroup?: (handle: unknown) => void;
-  setBindGroupAt?: (index: number, handle: unknown, dynamicOffsets?: readonly number[]) => void;
-  resolveTargetBindings?: (
-    resource: Extract<PreparedGraphicsResolvedResource, { readonly kind: 'bindings' }>,
-  ) => unknown;
-  setVertexBuffer?: (slot: number, handle: unknown) => void;
-  setIndexBuffer?: (handle: unknown, format: 'uint16' | 'uint32') => void;
-  recordDraw?: (
-    command: Extract<
-      RenderFeatureGraphicsPassDescriptor['draws'][number],
-      { kind: 'draw' }
-    >['command'],
-  ) => void;
-  recordDrawIndexed?: (
-    command: Extract<
-      RenderFeatureGraphicsPassDescriptor['draws'][number],
-      { kind: 'draw-indexed' }
-    >['command'],
-  ) => void;
-  recordDrawIndirect?: (buffer: unknown, offset: number) => void;
-  recordDrawIndexedIndirect?: (buffer: unknown, offset: number) => void;
-}
-
-function resolvedResource(
-  snapshot: PreparedGraphicsResolvedSnapshot,
-  reference: RenderFeaturePreparedRef,
-  kind: PreparedGraphicsResolvedResource['kind'],
-): PreparedGraphicsResolvedResource | undefined {
-  const resource = snapshot.resolve(reference);
-  return resource?.kind === kind ? resource : undefined;
-}
-
-export function recordResolvedRenderFeatureGraphicsPass(
-  featureIdentity: string,
-  descriptor: RenderFeatureGraphicsPassDescriptor,
-  state: RenderFeaturePreparedGraphicsState,
-  resolved: PreparedGraphicsResolvedSnapshot,
-  ledger: RenderFeatureGraphicsRecordingLedger,
-  featureOrder = -1,
-): Result<{ readonly acceptedDrawCount: number }, RenderError> {
-  const validated = validateRenderFeatureGraphicsPass(featureIdentity, descriptor, state);
-  if (!validated.ok) return validated;
-  const resolvedDraws: Array<{
-    readonly pipeline: PreparedGraphicsResolvedResource;
-    readonly bindings: readonly Extract<
-      PreparedGraphicsResolvedResource,
-      { readonly kind: 'bindings' }
-    >[];
-    readonly vertexData: readonly {
-      readonly slot: number;
-      readonly resource: PreparedGraphicsResolvedResource;
-    }[];
-    readonly indexData: PreparedGraphicsResolvedResource | undefined;
-    readonly draw: (typeof descriptor.draws)[number];
-  }> = [];
-  for (const draw of descriptor.draws) {
-    const pipeline = resolvedResource(resolved, draw.pipeline, 'pipeline');
-    const bindings = draw.bindings.map((binding) =>
-      resolvedResource(resolved, binding, 'bindings'),
-    );
-    const vertexData = draw.vertexData.map((vertex) => ({
-      slot: vertex.slot,
-      resource: resolvedResource(resolved, vertex.resource, 'vertex-data'),
-    }));
-    const indexData =
-      draw.indexData === undefined
-        ? undefined
-        : resolvedResource(resolved, draw.indexData.resource, 'index-data');
-    if (
-      pipeline === undefined ||
-      bindings.some((binding) => binding === undefined) ||
-      vertexData.some((vertex) => vertex.resource === undefined) ||
-      (draw.indexData !== undefined && indexData === undefined)
-    ) {
-      return err(
-        new RenderFeatureStageFailedError(featureIdentity, featureOrder, 'record', 'next-frame'),
-      );
-    }
-    resolvedDraws.push({
-      pipeline,
-      bindings: bindings as Extract<
-        PreparedGraphicsResolvedResource,
-        { readonly kind: 'bindings' }
-      >[],
-      vertexData: vertexData as {
-        readonly slot: number;
-        readonly resource: PreparedGraphicsResolvedResource;
-      }[],
-      indexData,
-      draw,
-    });
-  }
-
-  for (const resolvedDraw of resolvedDraws) {
-    ledger.pipeline += 1;
-    ledger.setPipeline?.(resolvedDraw.pipeline.handle);
-    for (const [index, binding] of resolvedDraw.bindings.entries()) {
-      ledger.binding += 1;
-      const handle = binding.handle ?? ledger.resolveTargetBindings?.(binding);
-      if (handle === undefined) {
-        return err(
-          new RenderFeatureStageFailedError(featureIdentity, featureOrder, 'record', 'next-frame'),
-        );
-      }
-      if (ledger.setBindGroupAt !== undefined) {
-        ledger.setBindGroupAt(index, handle, binding.dynamicOffsets);
-      } else {
-        ledger.setBindGroup?.(handle);
-      }
-    }
-    for (const vertex of resolvedDraw.vertexData) {
-      ledger.vertex += 1;
-      ledger.setVertexBuffer?.(vertex.slot, vertex.resource.handle);
-    }
-    if (
-      resolvedDraw.draw.kind === 'draw-indexed' ||
-      resolvedDraw.draw.kind === 'draw-indexed-indirect'
-    ) {
-      const indexData = resolvedDraw.draw.indexData;
-      const indexHandle = resolvedDraw.indexData?.handle;
-      if (indexData === undefined || indexHandle === undefined) {
-        return err(
-          new RenderFeatureStageFailedError(featureIdentity, featureOrder, 'record', 'next-frame'),
-        );
-      }
-      ledger.index += 1;
-      ledger.setIndexBuffer?.(indexHandle, indexData.format);
-      ledger.draw += 1;
-      if (resolvedDraw.draw.kind === 'draw-indexed-indirect') {
-        const indirect = resolved.resolveGpuBuffer?.(resolvedDraw.draw.command.buffer)?.buffer;
-        if (indirect === undefined) {
-          return err(
-            new RenderFeatureStageFailedError(
-              featureIdentity,
-              featureOrder,
-              'record',
-              'renderer-recover',
-            ),
-          );
-        }
-        ledger.recordDrawIndexedIndirect?.(indirect, resolvedDraw.draw.command.offset ?? 0);
-      } else {
-        ledger.recordDrawIndexed?.(resolvedDraw.draw.command);
-      }
-    } else {
-      ledger.draw += 1;
-      if (resolvedDraw.draw.kind === 'draw-indirect') {
-        const indirect = resolved.resolveGpuBuffer?.(resolvedDraw.draw.command.buffer)?.buffer;
-        if (indirect === undefined) {
-          return err(
-            new RenderFeatureStageFailedError(
-              featureIdentity,
-              featureOrder,
-              'record',
-              'renderer-recover',
-            ),
-          );
-        }
-        ledger.recordDrawIndirect?.(indirect, resolvedDraw.draw.command.offset ?? 0);
-      } else {
-        ledger.recordDraw?.(resolvedDraw.draw.command);
-      }
-    }
-  }
-  return ok(validated.value);
-}
-
-export function recordRenderFeatureGraphicsPass(
-  featureIdentity: string,
-  descriptor: RenderFeatureGraphicsPassDescriptor,
-  state: RenderFeaturePreparedGraphicsState,
-  ledger: RenderFeatureGraphicsRecordingLedger,
-): Result<{ readonly acceptedDrawCount: number }, RenderError> {
-  const validated = validateRenderFeatureGraphicsPass(featureIdentity, descriptor, state);
-  if (!validated.ok) return validated;
-  for (const draw of descriptor.draws) {
-    ledger.pipeline += 1;
-    ledger.setPipeline?.(draw.pipeline);
-    for (const binding of draw.bindings) {
-      ledger.binding += 1;
-      ledger.setBindGroup?.(binding);
-    }
-    for (const vertex of draw.vertexData) {
-      ledger.vertex += 1;
-      ledger.setVertexBuffer?.(vertex.slot, vertex.resource);
-    }
-    if (draw.kind === 'draw-indexed' || draw.kind === 'draw-indexed-indirect') {
-      if (draw.indexData === undefined) {
-        return err(new RenderFeatureStageFailedError(featureIdentity, -1, 'record', 'next-frame'));
-      }
-      ledger.index += 1;
-      ledger.setIndexBuffer?.(draw.indexData.resource, draw.indexData.format);
-      ledger.draw += 1;
-      if (draw.kind === 'draw-indexed-indirect') {
-        ledger.recordDrawIndexedIndirect?.(draw.command.buffer, draw.command.offset ?? 0);
-      } else {
-        ledger.recordDrawIndexed?.(draw.command);
-      }
-    } else {
-      ledger.draw += 1;
-      if (draw.kind === 'draw-indirect') {
-        ledger.recordDrawIndirect?.(draw.command.buffer, draw.command.offset ?? 0);
-      } else {
-        ledger.recordDraw?.(draw.command);
-      }
-    }
-  }
-  return ok(validated.value);
-}
-
 export function resolveShadowMapSize(
   internals: RenderSystemInternals,
   lights: ExtractedLights,
@@ -353,9 +118,9 @@ export function resolveShadowMapSize(
 
 /**
  * Resolve the per-tile size for the graph-owned spot atlas when a frame has
- * no directional shadow map.  The typed spot pass still needs a non-zero
- * viewport even in a spot-only world; reusing the directional resolver would
- * incorrectly leave the shared `shadowMapSize` lane at zero.
+ * no directional shadow map. The typed spot pass still needs a non-zero
+ * viewport in a spot-only world; the directional resolver cannot provide
+ * that because it intentionally follows only the directional shadow lane.
  */
 export function resolveSpotShadowMapSize(
   internals: RenderSystemInternals,