@forgeax/engine-render 0.1.27 → 0.1.29

package/src/index.ts

@@ -24,6 +24,9 @@ export type {
   Antialias,
   BloomEnabled,
   CameraData,
+  CameraErrorCode,
+  CameraErrorDetail,
+  CameraExposure,
   CameraProjection,
   Tonemap,
 } from './components/camera';
@@ -34,9 +37,17 @@ export {
   ANTIALIAS_TAA,
   BLOOM_DISABLED,
   BLOOM_ENABLED,
+  CAMERA_EXPOSURE_MODE_AUTO,
+  CAMERA_EXPOSURE_MODE_MANUAL,
   CAMERA_PROJECTION_ORTHOGRAPHIC,
   CAMERA_PROJECTION_PERSPECTIVE,
+  CAMERA_TEMPERATURE_MAX,
+  CAMERA_TEMPERATURE_MIN,
+  CAMERA_TINT_MAX,
+  CAMERA_TINT_MIN,
   Camera,
+  CameraError,
+  cameraExposureFromColumns,
   cameraProjectionFromF32,
   orthographic,
   perspective,
@@ -48,6 +59,8 @@ export {
   TONEMAP_NONE,
   TONEMAP_REINHARD,
   TONEMAP_REINHARD_EXTENDED,
+  validateCameraColorGrading,
+  validateCameraExposure,
 } from './components/camera';
 export {
   CUBE_CAMERA_FACE_ORDER,
@@ -92,6 +105,10 @@ export {
   reflectionProbeUpdateIntentToF32,
 } from './components/reflection-probe';
 export { SceneInstance } from './components/scene-instance';
+export {
+  ScreenSpaceReflection,
+  type ScreenSpaceReflectionData,
+} from './components/screen-space-reflection';
 export {
   SKYBOX_MODE_CUBEMAP,
   SkyboxBackground,
@@ -107,6 +124,21 @@ export {
   VisibilityStateValue,
   visibilityStateFromU32,
 } from './components/visibility';
+export type {
+  DynamicGeometryCandidate,
+  DynamicGeometryCandidateState,
+  DynamicGeometryErrorCode,
+  DynamicGeometryErrorDetail,
+  DynamicGeometryInspection,
+  DynamicGeometryLifecycle,
+  DynamicGeometryOrdering,
+  DynamicGeometryPrepareInput,
+  DynamicGeometryReceipt,
+} from './dynamic-geometry';
+export {
+  createDynamicGeometryLifecycle,
+  DynamicGeometryError,
+} from './dynamic-geometry';
 export type {
   EnvironmentInspection,
   EnvironmentInspectionFailure,
@@ -115,6 +147,13 @@ export type {
 } from './environment/inspection';
 // Public structured operation failure union. Concrete error classes stay
 // behind the Renderer Result/event boundary.
+export type {
+  GpuDrivenPreparationErrorCode,
+  GpuDrivenPreparationErrorDetail,
+  GpuDrivenPreparationReason,
+  GpuDrivenRecoveryAction,
+} from './errors/gpu-driven';
+export { GpuDrivenPreparationError } from './errors/gpu-driven';
 export type {
   ReflectionProbeBudgetExceededDetail,
   RenderError,
@@ -183,8 +222,15 @@ export {
 } from './ibl/kernel-cache';
 export type {
   BloomInspection,
+  GpuDrivenLane,
+  GpuDrivenLaneReason,
+  GpuDrivenLaneSummary,
+  GpuDrivenPreparationFailureInspection,
+  GpuDrivenProductionInspection,
+  GpuDrivenStructureMetrics,
   LightInspection,
   LodOcclusionInspection,
+  MaterialTextureSourceInspection,
   MotionBlurInspection,
   MotionBlurInspectionStatus,
   ReflectionFallbackFailureStage,
@@ -194,10 +240,31 @@ export type {
   ReflectionFallbackRecoveryAction,
   ReflectionProbeInspection,
   ReflectionProbeSelectionInspection,
+  RenderFeatureGraphInspection,
+  RenderFeatureHostInspection,
   TransmissionInspection,
 } from './inspection-types';
-export type { InstanceCollectionInspection } from './instances';
 export {
+  type InstanceBackendKind,
+  type InstanceCollectionCreateInput,
+  type InstanceCollectionData,
+  InstanceCollectionError,
+  type InstanceCollectionErrorCode,
+  type InstanceCollectionFailureCode,
+  type InstanceCollectionFailureFacts,
+  type InstanceCollectionId,
+  type InstanceCollectionInfo,
+  type InstanceCollectionInspection,
+  type InstanceCollectionInvalidDetail,
+  type InstanceCollectionResult,
+  type InstanceCollectionSnapshot,
+  InstanceCollectionStore,
+  type InstanceCollectionUpdateInput,
+  type InstanceDirtyRange,
+  type InstanceSubmissionLane,
+} from './instances';
+export {
+  MaterialAuthoringContractError,
   type MaterialColorInput3,
   type MaterialColorInput4,
   type MaterialColorTuple3,
@@ -222,6 +289,34 @@ export type {
   StandardLightingInspection,
   StandardNoLocalLightingInspection,
 } from './pipeline/standard-lighting/inspection';
+export type {
+  AutoExposureCapabilityUnavailableDetail,
+  AutoExposureError,
+  AutoExposureErrorCode,
+  AutoExposureErrorDetail,
+  AutoExposureErrorDetailByCode,
+  AutoExposureErrorRecord,
+  AutoExposureInspection,
+  AutoExposureInspectionInput,
+  AutoExposureInvalidParameterDetail,
+  AutoExposureReceipt,
+  AutoExposureResetReason,
+  AutoExposureStageFailedDetail,
+  AutoExposureStaleGenerationDetail,
+} from './pipeline/standard-output/auto-exposure/inspection';
+export {
+  AutoExposureCapabilityUnavailableError,
+  AutoExposureInvalidParameterError,
+  AutoExposureStageFailedError,
+  AutoExposureStaleGenerationError,
+  createAutoExposureError,
+  createAutoExposureInspection,
+} from './pipeline/standard-output/auto-exposure/inspection';
+export type {
+  StandardLutFailure,
+  StandardLutInspection,
+  StandardLutState,
+} from './pipeline/standard-output/lut-state';
 // The host-facing default is a stable profile value; implementation-only
 // pipeline helpers remain behind the package boundary.
 export {
@@ -308,6 +403,7 @@ export {
   validateReflectionProbeInput,
 } from './reflection/projection';
 export type {
+  CameraOutputSnapshot,
   CubeCameraSnapshot,
   FrameCamera,
   FrameEnvironment,
@@ -329,6 +425,7 @@ export type {
   TemporalInspectionInput,
   TemporalInspectionStatus,
 } from './renderer-inspect';
+export type { RenderSceneBounds } from './scene/render-scene-types';
 export type {
   GpuFrameTiming,
   GpuFrameTimingProtocol,
@@ -377,14 +474,23 @@ export type {
   SsrDependenciesInspection,
   SsrFormatReceipt,
   SsrReflectionFallbackReceipt,
+  SsrSpatialAdmission,
+  SsrSpatialCamera,
+  SsrSpatialCapabilities,
+  SsrSpatialEnvironment,
+  SsrSpatialLane,
+  SsrSpatialStatus,
+  SsrSpatialWork,
   SsrTemporalReceipt,
 } from './ssr/admission';
 export {
   admitSsrM0,
+  admitSsrSpatial,
   projectSsrDependencies,
   resolveSsrAdmissionGeneration,
   SSR_FORMAT_PROFILE,
   SSR_FORMAT_STAGES,
+  validateScreenSpaceReflection,
   zeroSsrAdmissionWork,
 } from './ssr/admission';
 export {
@@ -394,6 +500,24 @@ export {
   type SsrCompositionResult,
   type SsrReflectionColor,
 } from './ssr/composition';
+export type {
+  SsrConfigField,
+  SsrConfigInvalidError,
+  SsrConfigRange,
+  SsrSpatialUnavailableReason,
+  SsrUnavailableError,
+} from './ssr/errors';
+export type {
+  SsrSpatialHistoryInspection,
+  SsrSpatialInspection,
+  SsrSpatialInspectionFailure,
+  SsrSpatialInspectionProjection,
+} from './ssr/inspection';
+export {
+  projectSsrSpatialInspection,
+  serializeSsrSpatialInspection,
+} from './ssr/inspection';
+export { getActiveCamera, setActiveCamera } from './systems/active-camera';
 export type {
   RenderTarget,
   RenderTargetAdmissionLimits,

package/src/inspection-types.ts

@@ -5,6 +5,10 @@
  */
 
 import type { DirectionalShadowFilterLabel } from './components/directional-shadow-filter';
+import type {
+  GpuDrivenPreparationErrorCode,
+  GpuDrivenPreparationErrorDetail,
+} from './errors/gpu-driven';
 import type { PointsLinesInspection } from './points-lines/inspection';
 import type { LodOcclusionInspection } from './scene/visibility/inspection';
 import type { SsrAdmissionIdentity } from './ssr/identity';
@@ -45,6 +49,12 @@ export type {
   SsrOwnerRecoveryAction,
 } from './ssr/errors';
 export type { SsrAdmissionIdentity } from './ssr/identity';
+export type {
+  SsrSpatialHistoryInspection,
+  SsrSpatialInspection,
+  SsrSpatialInspectionFailure,
+  SsrSpatialInspectionProjection,
+} from './ssr/inspection';
 
 export interface LightInspectionInput {
   readonly generation: number;
@@ -101,6 +111,80 @@ export interface BatchTopologyInspection {
   readonly rebuilds: number;
   readonly patches: number;
   readonly ineligible: number;
+  /** Payload-only candidate updates that preserved batch topology. */
+  readonly payloadPatches?: number;
+  /** Number of retained-slot descriptor comparisons. */
+  readonly membershipChecks?: number;
+  /** Candidate membership records materialized by the owner. */
+  readonly membershipAllocations?: number;
+  readonly candidateAdds?: number;
+  readonly candidateRemoves?: number;
+}
+
+/**
+ * Detached evidence for the declarative feature host and typed graph. These
+ * counters are diagnostic projections only; they do not alter graph admission
+ * or prepared-resource retirement semantics.
+ */
+export interface RenderFeatureHostInspection {
+  readonly signatures: readonly {
+    readonly featureIdentity: string;
+    readonly calls: number;
+    readonly typedArrayBytes: number;
+    readonly outputChars: number;
+    readonly cpuMs: number;
+    /** Number of exact structural comparisons that reused a detached snapshot. */
+    readonly cacheHits: number;
+    /** Number of structural changes that allocated a new signature revision. */
+    readonly cacheMisses: number;
+  }[];
+  readonly prepared: {
+    readonly retained: number;
+    readonly submitted: number;
+    readonly released: number;
+    readonly releaseFailures: number;
+  };
+}
+
+export interface RenderFeatureGraphInspection {
+  /** Monotonic revision of the last completely validated feature plan set. */
+  readonly planRevision: number;
+  readonly signatureValidationCalls: number;
+  readonly signatureValidationBytes: number;
+  readonly signatureValidationChars: number;
+  readonly signatureValidationCpuMs: number;
+  /** Number of plan validations satisfied by detached structural evidence. */
+  readonly signatureValidationCacheHits: number;
+  /** Number of plan validations that fell back to canonical serialization. */
+  readonly signatureValidationCacheMisses: number;
+  readonly ensureCalls: number;
+  readonly reuseHits: number;
+  readonly rebuildAttempts: number;
+  readonly compileAttempts: number;
+  readonly compileSuccesses: number;
+  readonly compileFailures: number;
+  readonly validationFailures: number;
+  readonly buildFailures: number;
+  readonly compileCpuMs: number;
+  readonly candidatesWithPreparedBatches: number;
+  readonly preparedKeyChanges: number;
+  readonly accepted: number;
+  readonly rejected: number;
+  readonly abandoned: number;
+  readonly last: {
+    readonly planSignature: string;
+    readonly topologyKey: string | undefined;
+    readonly preparedResourceKey: string | undefined;
+  };
+}
+
+/** Detached material texture-source probe accounting for the last extract. */
+export interface MaterialTextureSourceInspection {
+  readonly sourceFieldsVisited: number;
+  readonly numericSharedRefProbes: number;
+  readonly sourceCacheHits: number;
+  readonly sourceCacheMisses: number;
+  readonly producerRoutes: Readonly<Record<string, number>>;
 }
 
 export interface ProbeBlendRecordInspection {
@@ -177,7 +261,88 @@ export interface GpuSceneInspection {
   readonly noChangeFrames: number;
 }
 
+/**
+ * Closed GPU-driven execution lanes exposed by the detached inspection
+ * surface.  `cpu-semantic` keeps the existing material/authoring semantics,
+ * while `cpu-deformation` is reserved for skin data that cannot be safely
+ * represented by the GPU palette contract.  `blocked` means the renderer
+ * refused to promote an incomplete candidate instead of silently changing
+ * its meaning.
+ */
+export type GpuDrivenLane = 'gpu' | 'cpu-semantic' | 'cpu-deformation' | 'blocked';
+
+/** Closed, machine-readable reasons for a lane decision or recovery state. */
+export type GpuDrivenLaneReason =
+  | 'none'
+  | 'capability'
+  | 'unsupported'
+  | 'resource-not-ready'
+  | 'shadow-ownership'
+  | 'capacity'
+  | 'overflow'
+  | 'stale-generation'
+  | 'device-recovery'
+  | 'skin-bounds-missing'
+  | 'skin-address-missing';
+
+/**
+ * Detached producer failure facts carried by a blocked GPU lane. This keeps
+ * owner and recovery machine-readable at the same boundary as the lane
+ * decision; callers never need to parse an RhiError hint or shader name.
+ */
+export interface GpuDrivenPreparationFailureInspection {
+  readonly code: GpuDrivenPreparationErrorCode;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: GpuDrivenPreparationErrorDetail;
+}
+
+/**
+ * One bounded aggregate; never includes a per-draw/live renderer object.
+ * Every count uses the same concrete `(drawItem, view-pass)` key unit. `drawCount`
+ * is the count for this lane; the remaining fields make conservation explicit
+ * when a view mixes GPU-owned and CPU-residual work.
+ */
+export interface GpuDrivenLaneSummary {
+  readonly viewPass: 'main' | 'directional-shadow' | 'point-shadow' | 'spot-shadow';
+  readonly viewIndex: number;
+  readonly face?: number;
+  readonly lane: GpuDrivenLane;
+  readonly reason: GpuDrivenLaneReason;
+  readonly drawCount: number;
+  readonly totalDrawCount: number;
+  readonly claimedDrawCount: number;
+  readonly residualDrawCount: number;
+  /** First bounded producer failure for a blocked lane, when available. */
+  readonly failure?: GpuDrivenPreparationFailureInspection;
+}
+
+/**
+ * Per-submission structural work projected by the existing RenderScene/GPU
+ * Scene/palette owners. These are frame deltas, not lifetime totals, so a
+ * stable GPU-only frame is expected to report zero for every field.
+ */
+export interface GpuDrivenStructureMetrics {
+  readonly worldEntitiesScanned: number;
+  readonly sceneTableUploadBytes: number;
+  readonly paletteUploadBytes: number;
+}
+
 export interface GpuDrivenProductionInspection {
+  /** Lifetime count of successful producer-side residency validation scans. */
+  readonly residencyValidationScans: number;
+  /** Lifetime count of validation rows reused without a CPU residency walk. */
+  readonly residencyValidationCacheHits: number;
+  /** Lifetime count of CPU fallback telemetry traversals. */
+  readonly cpuValidationScans: number;
+  /** Lifetime count of CPU fallback telemetry cache hits. */
+  readonly cpuValidationCacheHits: number;
+  /** RenderScene candidate traversal performed for the last prepared frame. */
+  readonly worldEntitiesScanned: number;
+  /** GPU Scene table bytes uploaded for the last prepared frame. */
+  readonly sceneTableUploadBytes: number;
+  /** Skin palette bytes uploaded for the last prepared frame. */
+  readonly paletteUploadBytes: number;
   readonly gpuOwnedSnapshotsMaterialized: number;
   readonly filteredPlanBuilds: number;
   readonly gpuOwnedEntityCount: number;
@@ -199,6 +364,25 @@ export interface GpuDrivenProductionInspection {
   readonly batchCount: number;
   /** Number of non-zero-capacity indirect raster commands actually encoded. */
   readonly indirectDrawCount: number;
+  /** Legacy name retained for existing GPU-driven evidence consumers. */
+  readonly encodedIndirectDraws: number;
+  /** Bounded view-pass lane aggregates for AI-readable recovery. */
+  readonly channels: readonly GpuDrivenLaneSummary[];
+  /** GPU resource generation used by the last prepared view, when resident. */
+  readonly resourceGeneration: number | undefined;
+  readonly candidateCapacity: number;
+  readonly batchCapacity: number;
+  readonly indirectCapacity: number;
+  /** True when the last selector readback reported an incomplete result. */
+  readonly overflow: boolean;
+  /** Submission state for the current prepared candidate. */
+  readonly submitted: boolean;
+  /** Number of renderer-device recovery boundaries observed by this owner. */
+  readonly recoveryCount: number;
+  /** Number of staged candidates aborted before submit. */
+  readonly retryCount: number;
+  /** Generation of the last fully submitted GPU candidate, if any. */
+  readonly lastKnownGoodGeneration: number | undefined;
 }
 
 export type DirectionalShadowEffectiveProfile =
@@ -385,6 +569,13 @@ export interface PersistentRenderSceneInspection {
   readonly transformUpdates: number;
   readonly lastResyncReason: RenderSceneResyncReason | undefined;
   readonly projectionRecords: number;
+  /** Allocation/cache evidence for instance bounds derivation. */
+  readonly instanceBoundsCache?: {
+    readonly hits: number;
+    readonly misses: number;
+    readonly derives: number;
+    readonly invalidations: number;
+  };
   /** Numeric probe ownership facts; no GPU handles or object graph references. */
   readonly probeBlend?: ProbeBlendInspection;
   readonly topology: BatchTopologyInspection;