@forgeax/engine-render 0.1.32 → 0.1.34

package/src/inspection-types.ts

@@ -4,6 +4,7 @@
  * extract/record dependency graph.
  */
 
+import { type BarrelDistortionMapping, freezeBarrelDistortionMapping } from './barrel-distortion';
 import type { DirectionalShadowFilterLabel } from './components/directional-shadow-filter';
 import type {
   GpuDrivenPreparationErrorCode,
@@ -13,6 +14,7 @@ import type { DepthOfFieldRequestFailure } from './features/depth-of-field/depth
 import type { PointsLinesInspection } from './points-lines/inspection';
 import type { LodOcclusionInspection } from './scene/visibility/inspection';
 import type { SsrAdmissionIdentity } from './ssr/identity';
+import type { SurfaceGpuIndirectParameters } from './surface/submission-observation';
 
 export type {
   LodOcclusionInspection,
@@ -92,6 +94,10 @@ export type BloomGraphStatus = 'empty' | 'valid' | 'invalid';
 export interface BloomInspection {
   readonly graphStatus: BloomGraphStatus;
   readonly enabled: boolean;
+  readonly levelCount: number;
+  readonly levelDimensions: readonly { readonly width: number; readonly height: number }[];
+  readonly downsamplePassCount: number;
+  readonly upsamplePassCount: number;
   readonly targetCount: number;
   readonly targetBytes: number;
   readonly resourceCount: number;
@@ -99,10 +105,30 @@ export interface BloomInspection {
   readonly encodeCount: number;
   readonly bindGroupCount: number;
   readonly uploadCount: number;
+  /** Descriptor-derived bytes for the active Bloom target child in the compiled graph. */
   readonly residentChildBytes: number;
   readonly generation: number;
   readonly state: 'off' | 'active' | 'retiring';
 }
+
+export const emptyBloomInspection = (): BloomInspection => ({
+  graphStatus: 'empty',
+  enabled: false,
+  levelCount: 0,
+  levelDimensions: [],
+  downsamplePassCount: 0,
+  upsamplePassCount: 0,
+  targetCount: 0,
+  targetBytes: 0,
+  resourceCount: 0,
+  passCount: 0,
+  encodeCount: 0,
+  bindGroupCount: 0,
+  uploadCount: 0,
+  residentChildBytes: 0,
+  generation: 0,
+  state: 'off',
+});
 export type { TransmissionInspection } from './transmission/inspection';
 
 export interface BatchTopologyInspection {
@@ -120,6 +146,31 @@ export interface BatchTopologyInspection {
   readonly membershipAllocations?: number;
   readonly candidateAdds?: number;
   readonly candidateRemoves?: number;
+  /** Distinct resource classes represented by this topology. */
+  readonly resourceClassCount?: number;
+  /** Resource-class groups; range/page changes do not create a new class. */
+  readonly resourceClassSplits?: readonly {
+    readonly resourceIdentity: string;
+    readonly batchIds: readonly number[];
+    readonly candidateCount: number;
+  }[];
+  /** Reasons emitted only when more than one resource class is present. */
+  readonly resourceClassSplitReasons?: readonly string[];
+}
+
+/** Logical Engine allocation facts; physical VRAM residency is intentionally unknown. */
+export interface GpuResourceAllocationInspection {
+  readonly unit: 'engine-allocation-bytes';
+  readonly physicalResidency: 'unknown';
+  readonly liveBytes: number;
+  readonly pendingRetirementBytes: number;
+  readonly peakBytes: number;
+  readonly successfulAllocationCount: number;
+  readonly successfulAllocationBytes: number;
+  readonly pendingRetirementCount: number;
+  readonly retiredBytes: number;
+  readonly failedAllocationRollbacks: number;
+  readonly failedAllocationRollbackBytes: number;
 }
 
 /**
@@ -179,6 +230,49 @@ export interface RenderFeatureGraphInspection {
   };
 }
 
+/**
+ * Detached output-space barrel facts for the most recently accepted picture.
+ * The mapping, extent, and generation fields are one context; consumers must
+ * discard the whole projection when its device or frame is retired.
+ */
+export interface BarrelDistortionInspection {
+  readonly effectiveMapping: BarrelDistortionMapping | undefined;
+  readonly extent: { readonly width: number; readonly height: number } | undefined;
+  readonly frameId: number;
+  readonly deviceGeneration: number;
+  readonly graphGeneration: number;
+  readonly lastKnownGood: boolean;
+}
+
+export interface BarrelDistortionInspectionInput {
+  readonly effectiveMapping: BarrelDistortionMapping | undefined;
+  readonly frameId: number;
+  readonly deviceGeneration: number;
+  readonly graphGeneration: number;
+  readonly lastKnownGood: boolean;
+}
+
+/** Project one immutable, public barrel frame context. */
+export function projectBarrelDistortionInspection(
+  input: BarrelDistortionInspectionInput,
+): BarrelDistortionInspection {
+  const effectiveMapping =
+    input.effectiveMapping === undefined
+      ? undefined
+      : freezeBarrelDistortionMapping(input.effectiveMapping);
+  return Object.freeze({
+    effectiveMapping,
+    extent:
+      effectiveMapping === undefined
+        ? undefined
+        : Object.freeze({ width: effectiveMapping.width, height: effectiveMapping.height }),
+    frameId: input.frameId,
+    deviceGeneration: input.deviceGeneration,
+    graphGeneration: input.graphGeneration,
+    lastKnownGood: input.lastKnownGood,
+  });
+}
+
 /** Detached material texture-source probe accounting for the last extract. */
 export interface MaterialTextureSourceInspection {
   readonly sourceFieldsVisited: number;
@@ -275,6 +369,7 @@ export type GpuDrivenLane = 'gpu' | 'cpu-semantic' | 'cpu-deformation' | 'blocke
 /** Closed, machine-readable reasons for a lane decision or recovery state. */
 export type GpuDrivenLaneReason =
   | 'none'
+  | 'reflection-fallback-mrt'
   | 'capability'
   | 'unsupported'
   | 'resource-not-ready'
@@ -330,6 +425,25 @@ export interface GpuDrivenStructureMetrics {
 }
 
 export interface GpuDrivenProductionInspection {
+  /** Exact producer-selected Surface artifact prepared for the last candidate. */
+  readonly surfaceArtifact?: {
+    readonly material: string;
+    readonly specializationKey: string | undefined;
+    readonly variantSet: string | undefined;
+    readonly layoutIdentity: string;
+    readonly receiptIdentity: string;
+    readonly receiptGeneration: number;
+    readonly directEntry: string;
+    readonly sceneIndexEntry: string;
+  };
+  /** Lifetime count of Surface member-to-frame projections rebuilt after a topology change. */
+  readonly surfaceFrameRangeBuilds: number;
+  /** Lifetime count of admitted Surface members visited while rebuilding that projection. */
+  readonly surfaceFrameMemberScans: number;
+  /** Lifetime count of 48-byte Surface frame rows materialized for an actual GPU write. */
+  readonly surfaceFrameRowAllocations: number;
+  /** Lifetime count of writes to the one renderer-owned shared Surface frame-time value. */
+  readonly surfaceFrameTimeWrites: number;
   /** Lifetime count of successful producer-side residency validation scans. */
   readonly residencyValidationScans: number;
   /** Lifetime count of validation rows reused without a CPU residency walk. */
@@ -384,6 +498,22 @@ export interface GpuDrivenProductionInspection {
   readonly retryCount: number;
   /** Generation of the last fully submitted GPU candidate, if any. */
   readonly lastKnownGoodGeneration: number | undefined;
+  /** Aggregate logical allocation facts from available GPU-driven owners. */
+  readonly resourceAllocation?: GpuResourceAllocationInspection;
+  /** Per-owner facts; absent owners remain unavailable rather than zero-filled. */
+  readonly resourceAllocationOwners?: {
+    readonly gpuDrivenView?: GpuResourceAllocationInspection;
+    readonly materialRaster?: GpuResourceAllocationInspection;
+    readonly skinRaster?: GpuResourceAllocationInspection;
+  };
+  /** Resource-class split facts derived from batch.key.resourceIdentity. */
+  readonly resourceClassCount?: number;
+  readonly resourceClassSplitReasons?: readonly string[];
+  readonly resourceClassSplits?: readonly {
+    readonly resourceIdentity: string;
+    readonly batchIds: readonly number[];
+    readonly candidateCount: number;
+  }[];
 }
 
 export type DirectionalShadowEffectiveProfile =
@@ -555,7 +685,29 @@ export interface TemporalTargetInspection {
 }
 
 /** Detached, bounded Motion Blur facts; no graph, device, target, or history handle. */
-export type MotionBlurInspectionStatus = 'off' | 'active' | 'reset' | 'invalid';
+export type MotionBlurInspectionStatus = 'off' | 'active' | 'reset' | 'limited' | 'invalid';
+export type MotionBlurInspectionLane = 'compute' | 'raster-limited';
+
+/**
+ * Submission receipt for the admitted compute lane. This is derived from the
+ * compiled graph and the resolved feature dispatches after a successful
+ * queue submit; capability intent alone never produces this receipt.
+ */
+export interface MotionBlurExecutionPass {
+  readonly name: 'motion-blur-tile-summary' | 'motion-blur';
+  readonly kind: 'compute';
+  readonly entryPoint: 'tile_summary' | 'reconstruct';
+  readonly workgroups: readonly [number, number, number];
+}
+
+export interface MotionBlurExecutionReceipt {
+  readonly frameId: number;
+  readonly deviceGeneration: number;
+  readonly graphGeneration: number;
+  readonly program: 'motion-blur-compute';
+  readonly outputFormat: 'rgba16float';
+  readonly passes: readonly [MotionBlurExecutionPass, MotionBlurExecutionPass];
+}
 
 /** Bounded renderer-owned Depth of Field facts; no graph or GPU handles. */
 export type DepthOfFieldInspectionStatus = 'off' | 'active' | 'reset' | 'invalid' | 'unsupported';
@@ -597,13 +749,25 @@ export interface DepthOfFieldInspection {
 export interface MotionBlurInspection {
   readonly enabled: boolean;
   readonly status: MotionBlurInspectionStatus;
+  /** Capability-selected implementation lane; raster is explicitly limited. */
+  readonly lane: MotionBlurInspectionLane;
   readonly shutterAngle: number;
   readonly maxRadiusPixels: number;
   readonly sampleCount: number;
+  /** Target presentation rate used by the accepted exposure calculation. */
+  readonly targetFps: number;
+  /** Bounded tier selected from the authored sample budget. */
+  readonly effectiveSampleCount: 0 | 4 | 8 | 16;
   readonly temporalDemand: 'none' | 'scene-data-temporal-v1';
   readonly passName: 'motion-blur';
   readonly historyWrites: 0;
-  readonly lastFailure?: 'invalid-params' | 'scene-data-unavailable';
+  /** Zero when demand is disabled; compute uses one summary plus one fused pass. */
+  readonly passCount: 0 | 1 | 2;
+  readonly tapBudget: 0 | 4 | 8 | 16;
+  /** Present only when the current accepted frame executed both compute passes. */
+  readonly execution?: MotionBlurExecutionReceipt;
+  readonly resetReason?: import('./temporal/view').TemporalResetReason;
+  readonly lastFailure?: 'invalid-params' | 'scene-data-unavailable' | 'submit-failure';
 }
 
 export type RenderSceneResyncReason =
@@ -640,6 +804,62 @@ export interface PersistentRenderSceneInspection {
     | { readonly status: 'error' };
   /** Bounded retained authoring observations; no graph or backend handles. */
   readonly pointsLines: readonly PointsLinesInspection[];
+  /** Last actually encoded Surface work, fenced by the renderer submission owner. */
+  readonly submission?: {
+    readonly sequence: number;
+    readonly frameId: number;
+    readonly requestedLane: 'direct' | 'gpu-driven';
+    readonly actualLane: 'direct' | 'gpu-driven';
+    /** Current-frame topology fact when a normal GPU lane was intentionally bypassed. */
+    readonly actualLaneReason?: GpuDrivenLaneReason;
+    readonly deviceGeneration: number;
+    readonly graphGeneration: number;
+    readonly viewIdentity: 'main:0';
+    readonly resourceGeneration: number | undefined;
+    readonly status: 'submitted' | 'completed';
+    readonly passes: readonly {
+      readonly pass: 'nearest-layer' | 'color';
+      /** Total commands actually encoded, including rows beyond the bounded sample. */
+      readonly commandCount: number;
+      readonly totalCommandCount: number;
+      readonly savedCommandCount: number;
+      readonly droppedCommandCount: number;
+      readonly truncated: boolean;
+      readonly memberEvidence:
+        | 'direct-command-members'
+        | 'direct-command-members-truncated'
+        | 'indirect-readback-required'
+        | 'indirect-visible-readback'
+        | 'indirect-visible-readback-truncated';
+      readonly memberIds?: readonly string[];
+      /** Decoded GPU command words bound to this submission/readback fence. */
+      readonly indirectParameters?: readonly SurfaceGpuIndirectParameters[];
+      readonly commands: readonly (
+        | {
+            readonly kind: 'draw' | 'draw-indexed';
+            readonly count: number;
+            readonly first: number;
+            readonly instanceCount: number;
+            readonly firstInstance: number;
+            readonly surfaceFrameBase: number;
+            readonly memberIds: readonly string[];
+            readonly pipelineIdentity: number;
+            readonly programEvidence: 'producer-receipt' | 'missing';
+            readonly receiptIdentity?: string;
+            readonly receiptGeneration?: number;
+          }
+        | {
+            readonly kind: 'draw-indirect' | 'draw-indexed-indirect';
+            readonly indirectBufferIdentity: number;
+            readonly indirectOffset: number;
+            readonly pipelineIdentity: number;
+            readonly programEvidence: 'producer-receipt' | 'missing';
+            readonly receiptIdentity?: string;
+            readonly receiptGeneration?: number;
+          }
+      )[];
+    }[];
+  };
 }
 
 export type RenderSceneInspection = PersistentRenderSceneInspection & {

package/src/instance-buffer-cache.ts

@@ -23,15 +23,15 @@ import type { GpuBuffer } from './gpu-resource';
  * and routes dispose through the RHI shim's destroy bookkeeping SSOT. The
  * two `uploaded*` fields are the cache invalidation fingerprint -- when the
  * archetype version bumps or the byte length changes, the record stage
- * allocates a fresh GpuBuffer and replaces the entry. Explicit collection
- * entries are keyed by renderer-owned collection id at the outer map; the
- * legacy entity key remains only for sprite/fold snapshots.
+ * allocates a fresh GpuBuffer and replaces the entry. World-authored Instances
+ * use renderer-private projection identity; sprite/fold snapshots use entity
+ * identity. Neither cache key is an authoring handle.
  */
 export interface InstanceBufferCacheEntry {
   readonly buffer: GpuBuffer;
   readonly uploadedByteLength: number;
   readonly uploadedArchVersion: number;
-  /** Renderer-owned collection revision uploaded into this buffer. */
+  /** Accepted instance-projection revision uploaded into this buffer. */
   readonly uploadedRevision?: number;
 }