@forgeax/engine-render 0.1.31 → 0.1.33

package/src/index.ts

@@ -37,6 +37,14 @@ export {
   ANTIALIAS_TAA,
   BLOOM_DISABLED,
   BLOOM_ENABLED,
+  CAMERA_BLOOM_INTENSITY_MAX,
+  CAMERA_BLOOM_INTENSITY_MIN,
+  CAMERA_BLOOM_SCATTER_MAX,
+  CAMERA_BLOOM_SCATTER_MIN,
+  CAMERA_BLOOM_SOFT_KNEE_MAX,
+  CAMERA_BLOOM_SOFT_KNEE_MIN,
+  CAMERA_BLOOM_THRESHOLD_MAX,
+  CAMERA_BLOOM_THRESHOLD_MIN,
   CAMERA_EXPOSURE_MODE_AUTO,
   CAMERA_EXPOSURE_MODE_MANUAL,
   CAMERA_PROJECTION_ORTHOGRAPHIC,
@@ -59,6 +67,7 @@ export {
   TONEMAP_NONE,
   TONEMAP_REINHARD,
   TONEMAP_REINHARD_EXTENDED,
+  validateCameraBloom,
   validateCameraColorGrading,
   validateCameraExposure,
 } from './components/camera.js';
@@ -74,6 +83,16 @@ export {
   cubeCameraUpdateIntentFromF32,
   cubeCameraUpdateIntentToF32,
 } from './components/cube-camera.js';
+export {
+  DepthOfField,
+  type DepthOfFieldData,
+  type DepthOfFieldQuality,
+  DepthOfFieldQualityValue,
+  type DepthOfFieldSide,
+  DepthOfFieldSideValue,
+  depthOfFieldQualityFromF32,
+  depthOfFieldSideFromF32,
+} from './components/depth-of-field.js';
 export * from './components/directional-light.js';
 export {
   DynamicResolution,
@@ -145,6 +164,10 @@ export {
   createDynamicGeometryLifecycle,
   DynamicGeometryError,
 } from './dynamic-geometry.js';
+// The environment selector owns this structured recovery error. Keep the
+// class on the public environment path so consumers can branch by `code` and
+// inspect its typed `detail` without importing an owner-private module.
+export { SunCardinalityError } from './environment/frame.js';
 export type {
   EnvironmentInspection,
   EnvironmentInspectionFailure,
@@ -196,6 +219,41 @@ export {
   type VisibilityResolution,
   type VisibilitySnapshot,
 } from './extract/visibility.js';
+export {
+  DEFAULT_DEPTH_OF_FIELD_PARAMS,
+  DEPTH_OF_FIELD_PARAMS_BYTE_SIZE,
+  type DepthOfFieldCameraInput,
+  type DepthOfFieldErrorCode,
+  type DepthOfFieldErrorDetail,
+  type DepthOfFieldParams,
+  type DepthOfFieldRequestFailure,
+  DepthOfFieldValidationError,
+  depthOfFieldQualityCode,
+  depthOfFieldRequestFailure,
+  depthOfFieldSideCode,
+  depthOfFieldTapCount,
+  packDepthOfFieldParams,
+  resolveDepthOfFieldParams,
+  signedDepthOfFieldCoC,
+  validateDepthOfFieldFrameParams,
+  validateDepthOfFieldParams,
+} from './features/depth-of-field/depth-of-field-params.js';
+export type {
+  MotionBlurInvalidParamsDetail,
+  MotionBlurParams,
+  MotionBlurSampleTier,
+} from './features/motion-blur/motion-blur-params.js';
+export {
+  DEFAULT_MOTION_BLUR_PARAMS,
+  effectiveMotionBlurSampleCount,
+  isMotionBlurIntervalValid,
+  MotionBlurValidationError,
+  motionBlurExposureScale,
+  motionBlurSampleDelta,
+  motionBlurTemporalDemand,
+  resolveMotionBlurParams,
+  validateMotionBlurParams,
+} from './features/motion-blur/motion-blur-params.js';
 export type {
   RenderFeatureLogicalTarget,
   RenderFeatureMaterialShaderBindingContract,
@@ -216,6 +274,7 @@ export type {
   RenderFeatureHiddenEntityReport,
   RenderFeatureShaderModuleMode,
   RenderFeatureStatus,
+  RenderFeatureSubmission,
   RenderFeatureWorldVisibilitySnapshot,
 } from './features/types.js';
 export {
@@ -232,6 +291,8 @@ export {
 } from './ibl/kernel-cache.js';
 export type {
   BloomInspection,
+  DepthOfFieldInspection,
+  DepthOfFieldInspectionStatus,
   GpuDrivenLane,
   GpuDrivenLaneReason,
   GpuDrivenLaneSummary,
@@ -241,7 +302,10 @@ export type {
   LightInspection,
   LodOcclusionInspection,
   MaterialTextureSourceInspection,
+  MotionBlurExecutionPass,
+  MotionBlurExecutionReceipt,
   MotionBlurInspection,
+  MotionBlurInspectionLane,
   MotionBlurInspectionStatus,
   ReflectionFallbackFailureStage,
   ReflectionFallbackInspection,

package/src/inspection-types.ts

@@ -9,6 +9,7 @@ import type {
   GpuDrivenPreparationErrorCode,
   GpuDrivenPreparationErrorDetail,
 } from './errors/gpu-driven';
+import type { DepthOfFieldRequestFailure } from './features/depth-of-field/depth-of-field-params';
 import type { PointsLinesInspection } from './points-lines/inspection';
 import type { LodOcclusionInspection } from './scene/visibility/inspection';
 import type { SsrAdmissionIdentity } from './ssr/identity';
@@ -91,6 +92,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;
@@ -98,10 +103,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 {
@@ -554,18 +579,89 @@ 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';
+
+export interface DepthOfFieldInspection {
+  readonly enabled: boolean;
+  readonly status: DepthOfFieldInspectionStatus;
+  readonly requested: {
+    readonly focusDistance: number;
+    readonly fStop: number;
+    readonly sensorHeight: number;
+    readonly maxRadiusPixels: number;
+    readonly quality: 'low' | 'medium' | 'high';
+    readonly blurSide: 'both' | 'near' | 'far';
+  };
+  readonly effective?: DepthOfFieldInspection['requested'];
+  readonly focalLength: number;
+  readonly outputExtent: { readonly width: number; readonly height: number };
+  readonly workExtent: { readonly width: number; readonly height: number };
+  readonly tapCount: 0 | 16 | 32 | 64;
+  readonly passCount: number;
+  readonly textureBytes: number;
+  readonly transparentPolicy: 'opaque-depth-approximation';
+  readonly graphGeneration: number;
+  readonly deviceGeneration: number;
+  readonly lastKnownGood: boolean;
+  /** Structured authoring validation facts, when admission rejected the request. */
+  readonly error?: DepthOfFieldRequestFailure;
+  readonly fallbackReason?:
+    | 'zero-radius'
+    | 'orthographic-unsupported'
+    | 'invalid-params'
+    | 'shader-not-ready'
+    | 'candidate-failed'
+    | 'capability-unavailable'
+    | undefined;
+}
 
 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 =

package/src/instances.ts

@@ -41,6 +41,8 @@ export function instanceUploadRangesForResident(
 
 export interface InstanceCollectionSnapshot extends InstanceCollectionInfo {
   readonly transforms: Float32Array;
+  /** Unique identity generations that travel with an instance through reorder. */
+  readonly generations: Uint32Array;
   readonly dirtyRanges: readonly InstanceDirtyRange[];
 }
 
@@ -171,6 +173,7 @@ export type InstanceCollectionResult<T> = Result<T, InstanceCollectionError>;
 interface CollectionRecord {
   readonly id: InstanceCollectionId;
   transforms: Float32Array;
+  generations: Uint32Array;
   count: number;
   capacity: number;
   revision: number;
@@ -307,6 +310,7 @@ function missing(
  */
 export class InstanceCollectionStore {
   private nextId = 1;
+  private nextInstanceGeneration = 1;
   private epochValue = 0;
   private disposed = false;
   private readonly records = new Map<InstanceCollectionId, CollectionRecord>();
@@ -330,9 +334,11 @@ export class InstanceCollectionStore {
     if (invalidPayload !== undefined) return err(invalidPayload);
     const id = this.nextId++ as InstanceCollectionId;
     const count = input.transforms.length / MATRIX_STRIDE;
+    const generations = this.allocateGenerations(count);
     const record: CollectionRecord = {
       id,
       transforms: new Float32Array(input.transforms),
+      generations,
       count,
       capacity: nextCapacity(Math.max(INITIAL_CAPACITY, count)),
       revision: 1,
@@ -348,13 +354,26 @@ export class InstanceCollectionStore {
   replace(
     id: InstanceCollectionId,
     transforms: Float32Array,
+    /** Prior identity generations in the replacement order; omitted rows are new. */
+    generations?: Uint32Array,
   ): InstanceCollectionResult<InstanceCollectionInfo> {
     const record = this.live('replace', id);
     if (!record.ok) return record;
     const invalidPayload = validateTransforms('replace', transforms, id);
     if (invalidPayload !== undefined) return err(invalidPayload);
     const count = transforms.length / MATRIX_STRIDE;
+    const generationResult =
+      generations === undefined
+        ? ok(this.allocateGenerations(count))
+        : this.validateReplacementGenerations(generations, count, id);
+    if (!generationResult.ok) return generationResult;
+    // Replacement is a topology boundary by default. A producer that keeps
+    // logical instance identity through compaction/reorder may pass the prior
+    // generation tokens in their new order; the record stage then maps the
+    // real previous transform by token instead of by draw ordinal.
+    const replacementGenerations = generationResult.value;
     record.value.transforms = new Float32Array(transforms);
+    record.value.generations = replacementGenerations;
     record.value.count = count;
     record.value.capacity = Math.max(record.value.capacity, nextCapacity(Math.max(1, count)));
     record.value.revision += 1;
@@ -402,6 +421,11 @@ export class InstanceCollectionStore {
       record.value.dirtyRanges = [];
     }
     record.value.transforms.set(input.transforms, input.start * MATRIX_STRIDE);
+    // An update changes a pose while retaining the same ordinal identity.
+    // Keep its generation stable so the record stage can pair this current
+    // transform with the last submitted transform and expose real velocity.
+    // `replace` is the explicit topology boundary that advances generations
+    // for compaction, reorder, retirement, and newly occupied ordinals.
     record.value.revision += 1;
     appendDirtyRange(record.value, input.start, input.start + span);
     this.epochValue += 1;
@@ -505,6 +529,7 @@ export class InstanceCollectionStore {
     const result = {
       ...this.info(value),
       transforms: new Float32Array(value.transforms),
+      generations: new Uint32Array(value.generations),
       dirtyRanges: value.dirtyRanges.map((range) => ({ ...range })),
     };
     // Keep the current ranges stable for repeated reads by entities sharing
@@ -513,6 +538,16 @@ export class InstanceCollectionStore {
     return ok(result);
   }
 
+  /**
+   * Read a detached matrix view without advancing the render-consumption
+   * cursor. Inspection and picking may call this between authoring updates;
+   * the next renderer snapshot must still receive the complete dirty union.
+   */
+  peek(id: InstanceCollectionId): InstanceCollectionResult<InstanceCollectionSnapshot> {
+    const record = this.live('inspect', id);
+    return record.ok ? ok(this.detachedSnapshot(record.value)) : record;
+  }
+
   release(id: InstanceCollectionId): InstanceCollectionResult<void> {
     const record = this.records.get(id);
     if (record === undefined) return err(missing('release', id));
@@ -569,6 +604,15 @@ export class InstanceCollectionStore {
     return record === undefined ? err(missing(operation, id)) : ok(record);
   }
 
+  private detachedSnapshot(record: CollectionRecord): InstanceCollectionSnapshot {
+    return {
+      ...this.info(record),
+      transforms: new Float32Array(record.transforms),
+      generations: new Uint32Array(record.generations),
+      dirtyRanges: record.dirtyRanges.map((range) => ({ ...range })),
+    };
+  }
+
   private info(record: CollectionRecord): InstanceCollectionInfo {
     return Object.freeze({
       collectionId: record.id,
@@ -578,6 +622,55 @@ export class InstanceCollectionStore {
     });
   }
 
+  private allocateGenerations(count: number): Uint32Array {
+    const generations = new Uint32Array(count);
+    for (let index = 0; index < count; index += 1) {
+      generations[index] = this.nextInstanceGeneration;
+      this.nextInstanceGeneration = (this.nextInstanceGeneration + 1) >>> 0 || 1;
+    }
+    return generations;
+  }
+
+  private validateReplacementGenerations(
+    generations: Uint32Array,
+    count: number,
+    collectionId: InstanceCollectionId,
+  ): InstanceCollectionResult<Uint32Array> {
+    if (!(generations instanceof Uint32Array) || generations.length !== count) {
+      return err(
+        invalid(
+          'replace',
+          `generations is a Uint32Array with ${count} entries`,
+          generations instanceof Uint32Array ? generations.length : typeof generations,
+          collectionId,
+          { requestedBytes: generations?.byteLength ?? 0, cause: 'invalid-generation-shape' },
+        ),
+      );
+    }
+    const seen = new Set<number>();
+    for (const generation of generations) {
+      if (generation === 0 || seen.has(generation)) {
+        return err(
+          invalid(
+            'replace',
+            'generations contain unique non-zero identity tokens',
+            generation,
+            collectionId,
+            {
+              requestedBytes: generations.byteLength,
+              cause: 'invalid-generation-identity',
+            },
+          ),
+        );
+      }
+      seen.add(generation);
+      if (generation >= this.nextInstanceGeneration) {
+        this.nextInstanceGeneration = (generation + 1) >>> 0 || 1;
+      }
+    }
+    return ok(new Uint32Array(generations));
+  }
+
   private projectInspection(record: CollectionRecord): InstanceCollectionInspection {
     const residency = this.residency.get(record.id);
     return Object.freeze({

package/src/mesh-material-bindings.ts

@@ -112,6 +112,8 @@ export interface MeshMaterialBindingResidency {
 /** Public read-only observation of the bindings used by the last frame. */
 export interface MeshMaterialBindingObservation {
   readonly worldId: number;
+  /** Stable World identity for cross-world inspection; worldId is only a frame slot. */
+  readonly worldIdentity?: string;
   readonly entityKey: number;
   readonly bindings: readonly ResolvedMeshMaterialBinding[];
   readonly diagnostics: readonly MeshMaterialBindingDiagnostic[];
@@ -143,6 +145,7 @@ const EMPTY_RESIDENCY: MeshMaterialBindingResidency = Object.freeze({
  */
 export function projectMeshMaterialBindingObservation(input: {
   readonly worldId: number;
+  readonly worldIdentity?: string;
   readonly entityKey: number;
   readonly bindings: readonly ResolvedMeshMaterialBinding[];
   readonly diagnostics: readonly MeshMaterialBindingDiagnostic[];
@@ -168,6 +171,7 @@ export function projectMeshMaterialBindingObservation(input: {
   });
   return {
     worldId: input.worldId,
+    ...(input.worldIdentity === undefined ? {} : { worldIdentity: input.worldIdentity }),
     entityKey: input.entityKey,
     bindings: Object.freeze([...input.bindings]),
     diagnostics: Object.freeze([...input.diagnostics]),

package/src/pipeline/standard-output/graph.ts

@@ -26,6 +26,7 @@ function requestedStages(input: StandardOutputRequest): StandardOutputLogicalSta
   const stages: StandardOutputLogicalStage[] = [];
   if (input.temporal) stages.push('temporal');
   if (input.meter) stages.push('meter');
+  if (input.dof === true) stages.push('dof');
   if (input.bloom) stages.push('bloom');
   if (input.exposure || input.whiteBalance) stages.push('exposure-white-balance');
   stages.push('tone');
@@ -43,6 +44,7 @@ function physicalStages(
       case 'temporal':
       case 'meter':
       case 'bloom':
+      case 'dof':
       case 'exposure-white-balance':
         return { name, input: LINEAR_HDR_DOMAIN, output: LINEAR_HDR_DOMAIN };
       case 'tone':
@@ -68,6 +70,7 @@ export function createStandardOutputPlan(input: StandardOutputRequest): Standard
       temporal: input.temporal,
       meter: input.meter,
       bloom: input.bloom,
+      dof: input.dof === true,
       exposure: input.exposure,
       whiteBalance: input.whiteBalance,
       lut: input.lut,

package/src/pipeline/standard-output/types.ts

@@ -3,6 +3,7 @@ import type { ColorValueDomain } from '@forgeax/engine-render-graph';
 export const STANDARD_OUTPUT_LOGICAL_STAGES = [
   'temporal',
   'meter',
+  'dof',
   'bloom',
   'exposure-white-balance',
   'tone',
@@ -26,6 +27,8 @@ export interface StandardOutputRequest {
   readonly temporal: boolean;
   readonly meter: boolean;
   readonly bloom: boolean;
+  /** Built-in spatial DoF stage; false keeps the path exact-zero. */
+  readonly dof?: boolean;
   readonly exposure: boolean;
   readonly whiteBalance: boolean;
   readonly lut: boolean;
@@ -44,7 +47,7 @@ export interface StandardOutputPlan {
   readonly features: Readonly<
     Pick<
       StandardOutputRequest,
-      'temporal' | 'meter' | 'bloom' | 'exposure' | 'whiteBalance' | 'lut' | 'fxaa'
+      'temporal' | 'meter' | 'bloom' | 'dof' | 'exposure' | 'whiteBalance' | 'lut' | 'fxaa'
     >
   >;
   readonly outputEncoding: StandardOutputEncoding;