@forgeax/engine-render 0.1.33 → 0.1.34

package/src/index.ts

@@ -11,6 +11,18 @@ export {
   renderPipelineContribution,
   samplerContribution,
 } from './assets/asset-decoders.js';
+export {
+  attachBarrelDistortionCameraFrame,
+  type BarrelDistortionCameraFrame,
+  type BarrelDistortionMapping,
+  createBarrelDistortionMapping,
+  type DisplayPoint,
+  freezeBarrelDistortionMapping,
+  mapDisplayToScene,
+  mapDisplayUvToSceneUv,
+  mapSceneToDisplay,
+  mapSceneUvToDisplayUv,
+} from './barrel-distortion.js';
 // Runtime contract: leases, frame receipts, detached inspection, profile,
 // lifecycle state, and the single renderer event stream.
 export type {
@@ -18,7 +30,107 @@ export type {
   CubeCameraFaceViewInput,
 } from './capture/cube-views.js';
 export { buildCubeCameraFaceViews } from './capture/cube-views.js';
+export {
+  buildCloudDensityCache,
+  type CloudDensityCache,
+  type CloudDensityCacheSnapshot,
+  type CloudDensitySample,
+  evaluateCloudDensity,
+  reconstructCloudDensityCache,
+  sampleCloudDensity,
+  snapshotCloudDensityCache,
+} from './cloud/density.js';
+export {
+  type CloudLayerCandidate,
+  type ExtractedCloudLayer,
+  extractCloudLayer,
+  selectCloudLayerFrame,
+} from './cloud/extract.js';
+export {
+  CLOUD_DENSITY_COMPUTE_WGSL,
+  CLOUD_HISTORY_FULLSCREEN_WGSL,
+  CLOUD_LAYER_DENSITY_BINDINGS,
+  CLOUD_LAYER_DENSITY_CACHE,
+  CLOUD_LAYER_DENSITY_OUTPUT,
+  CLOUD_LAYER_DENSITY_PROGRAM,
+  CLOUD_LAYER_FEATURE_IDENTITY,
+  CLOUD_VIEW_FULLSCREEN_WGSL,
+  CLOUD_VIEW_PARAMS_BYTES,
+  type CloudLayerFeatureFrame,
+  type CloudLayerFeatureOptions,
+  createCloudLayerFeature,
+} from './cloud/feature.js';
+export {
+  type CloudLayerBudgetObservation,
+  type CloudLayerInspection,
+  type CloudLayerInspectionInput,
+  type CloudLayerInspectionStatus,
+  type CloudLayerResourceStage,
+  type CloudPhysicalGpuEvidence,
+  cloudCapabilitiesFromRhi,
+  inspectCloudLayer,
+} from './cloud/inspection.js';
+export {
+  applyCloudSolarTransmittance,
+  type CloudInteriorLighting,
+  type CloudOpticalPath,
+  type CloudOpticalResult,
+  type CloudOpticsInput,
+  type CloudRay,
+  compositeCloudRadiance,
+  integrateCloudCameraPath,
+  integrateCloudInterior,
+  integrateCloudPath,
+  integrateCloudSolarColumn,
+  intersectCloudLayer,
+} from './cloud/optics.js';
+export {
+  CLOUD_QUALITY_PROFILES,
+  type CloudLayerAuthoring,
+  type CloudQualityProfile,
+  cloudLayerSourceKey,
+  DEFAULT_CLOUD_LAYER,
+  type ValidatedCloudLayer,
+  validateCloudLayer,
+} from './cloud/parameters.js';
+export {
+  acceptCloudLayerGeneration,
+  CLOUD_HISTORY_SURFACE_COUNT,
+  CLOUD_RGBA16FLOAT_BYTES_PER_TEXEL,
+  type CloudGpuResourceEvidence,
+  type CloudLayerGeneration,
+  type CloudLayerResourceFacts,
+  type CloudLayerResourceInputs,
+  inspectCloudLayerResources,
+  retainCloudLayerAfterFailure,
+} from './cloud/resources.js';
+export {
+  type CloudShadowProjection,
+  type CloudShadowSample,
+  createCloudShadowProjection,
+  projectCloudShadowUv,
+  sampleCloudShadow,
+} from './cloud/shadow.js';
+export {
+  type CloudHistory,
+  type CloudHistoryReprojection,
+  type CloudHistoryReprojectionInput,
+  CloudHistoryStore,
+  type CloudTemporalDecision,
+  type CloudTemporalFrame,
+  type CloudTemporalResetReason,
+  type CloudTemporalSignature,
+  cloudTemporalResetReasons,
+  cloudTemporalSignature,
+  createCloudHistory,
+  reprojectCloudHistory,
+} from './cloud/temporal.js';
 export { Atmosphere } from './components/atmosphere.js';
+export {
+  BarrelDistortion,
+  type BarrelDistortionData,
+  validateBarrelDistortionParameters,
+} from './components/barrel-distortion.js';
 // ECS render vocabulary and grouped closed values.
 export type {
   Antialias,
@@ -71,6 +183,13 @@ export {
   validateCameraColorGrading,
   validateCameraExposure,
 } from './components/camera.js';
+export {
+  CloudLayer,
+  type CloudLayerData,
+  type CloudQuality,
+  CloudQualityValue,
+  cloudQualityFromF32,
+} from './components/cloud-layer.js';
 export {
   CUBE_CAMERA_FACE_ORDER,
   CUBE_CAMERA_UPDATE_CONTINUOUS,
@@ -174,6 +293,22 @@ export type {
   EnvironmentInspectionGeneration,
   EnvironmentInspectionStatus,
 } from './environment/inspection.js';
+export type {
+  CloudLayerCacheInvalidDetail,
+  CloudLayerCapabilityMissingDetail,
+  CloudLayerError,
+  CloudLayerErrorCode,
+  CloudLayerInvalidParameterDetail,
+  CloudLayerOwnerConflictDetail,
+  CloudLayerResourceFailureDetail,
+} from './errors/cloud.js';
+export {
+  CloudLayerCacheInvalidError,
+  CloudLayerCapabilityMissingError,
+  CloudLayerInvalidParameterError,
+  CloudLayerOwnerConflictError,
+  CloudLayerResourceFailureError,
+} from './errors/cloud.js';
 // Public structured operation failure union. Concrete error classes stay
 // behind the Renderer Result/event boundary.
 export type {
@@ -184,6 +319,7 @@ export type {
 } from './errors/gpu-driven';
 export { GpuDrivenPreparationError } from './errors/gpu-driven';
 export type {
+  BarrelDistortionInvalidParameterDetail,
   DynamicResolutionError,
   ReflectionProbeBudgetExceededDetail,
   RenderError,
@@ -198,6 +334,7 @@ export type {
 } from './errors/render.js';
 export {
   AtmosphereInvalidParameterError,
+  BarrelDistortionInvalidParameterError,
   DynamicResolutionInvalidParameterError,
   DynamicResolutionRequiresTaaError,
   DynamicResolutionTimingUnavailableError,
@@ -205,9 +342,14 @@ export {
   EnvironmentSourceConflictError,
   FogCardinalityError,
   OwnerStageFailedError,
+  RendererOperationError,
   SceneDataUnavailableError,
   TaaCapsInsufficientError,
 } from './errors/render.js';
+export {
+  SINGLE_LAYER_MEDIUM_SURFACE_EXAMPLE,
+  SINGLE_LAYER_MEDIUM_SURFACE_EXAMPLES,
+} from './examples/single-layer-medium-surface.js';
 export type {
   EnvironmentFrame,
   EnvironmentSource,
@@ -219,6 +361,14 @@ export {
   type VisibilityResolution,
   type VisibilitySnapshot,
 } from './extract/visibility.js';
+export {
+  BARREL_DISTORTION_FEATURE_IDENTITY,
+  BARREL_DISTORTION_POST_PROCESS_ID,
+  BARREL_DISTORTION_WGSL,
+  BARREL_DISTORTION_WGSL_COORDINATE,
+  type BarrelDistortionFeatureFrame,
+  createBarrelDistortionRenderFeature,
+} from './features/barrel-distortion.js';
 export {
   DEFAULT_DEPTH_OF_FIELD_PARAMS,
   DEPTH_OF_FIELD_PARAMS_BYTE_SIZE,
@@ -271,10 +421,13 @@ export type {
   RenderFeatureDiagnostics,
   RenderFeatureErrorDescriptor,
   RenderFeatureExtractContext,
+  RenderFeatureFrameContext,
   RenderFeatureHiddenEntityReport,
+  RenderFeaturePlacement,
   RenderFeatureShaderModuleMode,
   RenderFeatureStatus,
   RenderFeatureSubmission,
+  RenderFeatureViewContext,
   RenderFeatureWorldVisibilitySnapshot,
 } from './features/types.js';
 export {
@@ -290,6 +443,7 @@ export {
   resetIblKernelCaches,
 } from './ibl/kernel-cache.js';
 export type {
+  BarrelDistortionInspection,
   BloomInspection,
   DepthOfFieldInspection,
   DepthOfFieldInspectionStatus,
@@ -320,22 +474,14 @@ export type {
 } from './inspection-types.js';
 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,
+  InstanceTransformsError,
 } from './instances';
 export {
   MaterialAuthoringContractError,
@@ -483,6 +629,7 @@ export type {
   FrameCamera,
   FrameEnvironment,
   FrameObservationRequest,
+  FramePresentation,
   FrameReceipt,
   FrameReceiptObservation,
   Renderer,
@@ -592,6 +739,31 @@ export {
   projectSsrSpatialInspection,
   serializeSsrSpatialInspection,
 } from './ssr/inspection.js';
+export {
+  type DynamicInputConsumptionReceipt,
+  type DynamicInputDirtyRange,
+  DynamicInputError,
+  type DynamicInputErrorCode,
+  type DynamicInputErrorDetail,
+  type DynamicInputRange,
+  type DynamicInputResult,
+  type DynamicInputUploadReceipt,
+  type DynamicInputValue,
+  ReadonlyDynamicInputPage,
+  type SurfaceDynamicInputFrame,
+  type SurfaceDynamicInputMemberIdentity,
+} from './surface/dynamic-input.js';
+export {
+  admitSingleLayerMediumSubmission,
+  type SurfaceGpuCapability,
+  type SurfaceGpuFallbackReason,
+  type SurfaceGpuPassAdmission,
+  type SurfaceGpuSubmissionAdmission,
+  type SurfaceGpuSubmissionError,
+  type SurfaceGpuSubmissionErrorCode,
+  type SurfaceGpuSubmissionInput,
+} from './surface/gpu-driven.js';
+export type { SurfaceGpuIndirectParameters } from './surface/submission-observation.js';
 export { getActiveCamera, setActiveCamera } from './systems/active-camera.js';
 export type {
   RenderTarget,
@@ -626,6 +798,19 @@ export {
   type SceneDataInspection,
 } from './temporal/scene-data-catalog.js';
 export type { TemporalView } from './temporal/view.js';
+export {
+  composeSingleLayerMediumColor,
+  estimateSingleLayerPathLength,
+  integrateSingleLayerMedium,
+  type MediumVector3,
+  resolveSingleLayerMediumBackground,
+  type SingleLayerMediumBackgroundCandidate,
+  type SingleLayerMediumBackgroundInput,
+  type SingleLayerMediumBackgroundReason,
+  type SingleLayerMediumBackgroundResolution,
+  type SingleLayerMediumCoefficients,
+  type SingleLayerMediumOptics,
+} from './transmission/single-layer-medium.js';
 export {
   hasVolumetricFogCapability,
   type IntegratedVolumeResource,
@@ -638,12 +823,14 @@ export {
   type VolumetricFogLightResolution,
 } from './volume/capability.js';
 export {
+  MAX_VOLUMETRIC_FOG_OWNERS,
   type ValidatedVolumetricFog,
   type VolumeBounds,
   type VolumeDensityBinding,
   VolumetricFog,
   type VolumetricFogAuthoring,
   type VolumetricFogLightSelection,
+  VolumetricFogSamplingValue,
   validateVolumetricFog,
 } from './volume/component.js';
 export { extractVolumetricFog, type VolumetricFogExtract } from './volume/extract.js';

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,
@@ -144,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;
 }
 
 /**
@@ -203,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;
@@ -299,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'
@@ -354,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. */
@@ -408,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 =
@@ -698,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;
 }