@forgeax/engine-render 0.1.19 → 0.1.21

package/src/index.ts

@@ -11,6 +11,13 @@ export {
   renderPipelineContribution,
   samplerContribution,
 } from './assets/asset-decoders';
+// Runtime contract: leases, frame receipts, detached inspection, profile,
+// lifecycle state, and the single renderer event stream.
+export type {
+  CubeCameraFaceView,
+  CubeCameraFaceViewInput,
+} from './capture/cube-views';
+export { buildCubeCameraFaceViews } from './capture/cube-views';
 export { Atmosphere } from './components/atmosphere';
 // ECS render vocabulary and grouped closed values.
 export type {
@@ -42,6 +49,18 @@ export {
   TONEMAP_REINHARD,
   TONEMAP_REINHARD_EXTENDED,
 } from './components/camera';
+export {
+  CUBE_CAMERA_FACE_ORDER,
+  CUBE_CAMERA_UPDATE_CONTINUOUS,
+  CUBE_CAMERA_UPDATE_ON_DEMAND,
+  CUBE_CAMERA_UPDATE_ONCE,
+  CubeCamera,
+  type CubeCameraData,
+  type CubeCameraFace,
+  type CubeCameraUpdateIntent,
+  cubeCameraUpdateIntentFromF32,
+  cubeCameraUpdateIntentToF32,
+} from './components/cube-camera';
 export * from './components/directional-light';
 export { Fog } from './components/fog';
 export { Instances, type InstancesData } from './components/instances';
@@ -59,6 +78,16 @@ export {
   pointShapeFromU32,
 } from './components/points';
 export { PostProcessParams } from './components/post-process-params';
+export {
+  REFLECTION_PROBE_UPDATE_CONTINUOUS,
+  REFLECTION_PROBE_UPDATE_ON_CHANGE,
+  REFLECTION_PROBE_UPDATE_ONCE,
+  ReflectionProbe,
+  type ReflectionProbeData,
+  type ReflectionProbeUpdateIntent,
+  reflectionProbeUpdateIntentFromF32,
+  reflectionProbeUpdateIntentToF32,
+} from './components/reflection-probe';
 export { SceneInstance } from './components/scene-instance';
 export {
   SKYBOX_MODE_CUBEMAP,
@@ -67,6 +96,7 @@ export {
 } from './components/skybox-background';
 export { Skylight } from './components/skylight';
 export { SortKey } from './components/sort-key';
+export type { SpotLightAuthoring, SpotLightProjector } from './components/spot-light';
 export { SpotLight } from './components/spot-light';
 export {
   Visibility,
@@ -83,8 +113,14 @@ export type {
 // Public structured operation failure union. Concrete error classes stay
 // behind the Renderer Result/event boundary.
 export type {
+  ReflectionProbeBudgetExceededDetail,
   RenderError,
   RenderErrorCode,
+  RenderIntentInvalidDetail,
+  RenderTargetCapabilityMissingDetail,
+  RenderTargetDescriptorInvalidDetail,
+  RenderTargetOperationFailedDetail,
+  RenderTargetStateInvalidDetail,
   SceneDataUnavailableDetail,
   SceneDataUnavailableReason,
 } from './errors/render';
@@ -130,17 +166,55 @@ export type {
   RenderFeatureStatus,
   RenderFeatureWorldVisibilitySnapshot,
 } from './features/types';
+export {
+  beginProbeIblUpdate,
+  createIblKernelCache,
+  createProbeIblOutput,
+  type IblKernelCache,
+  type ProbeIblOutput,
+  type ProbeIblUpdate,
+  publishProbeIblOutput,
+  REFLECTION_PROBE_IBL_STAGES,
+  type ReflectionProbeIblStage,
+  resetIblKernelCaches,
+} from './ibl/kernel-cache';
 export type {
   BloomInspection,
   MotionBlurInspection,
   MotionBlurInspectionStatus,
+  ReflectionProbeInspection,
+  ReflectionProbeSelectionInspection,
   TransmissionInspection,
 } from './inspection-types';
 export { Materials, MaterialTransmissionContractError } from './materials';
+export {
+  type MeshMaterialBindingObservation,
+  type MeshMaterialBindingPreparationFailure,
+  type MeshMaterialBindingReadiness,
+  type MeshMaterialBindingResidency,
+  type MeshMaterialBindingSamplerObservation,
+  type MeshMaterialBindingSummary,
+  type MeshMaterialBindingTextureObservation,
+  projectMeshMaterialBindingObservation,
+  summarizeMeshMaterialBindings,
+} from './mesh-material-bindings';
+export type {
+  StandardClusterTransportInspection,
+  StandardLightingInspection,
+  StandardNoLocalLightingInspection,
+} from './pipeline/standard-lighting/inspection';
 // The host-facing default is a stable profile value; implementation-only
 // pipeline helpers remain behind the package boundary.
-export { DEFAULT_STANDARD_PROFILE } from './pipeline/standard-profile';
+export {
+  DEFAULT_STANDARD_PROFILE,
+  type StandardVolumetricFogProfile,
+  type StandardVolumetricFogQuality,
+} from './pipeline/standard-profile';
 export { renderComponentsPlugin } from './plugin';
+export {
+  inspectPointShadow,
+  type PointShadowInspection,
+} from './point-shadow-inspection';
 export {
   admitPointsLines,
   type LinesStyleInput,
@@ -151,9 +225,67 @@ export {
   type PointsStyleInput,
 } from './points-lines/admission';
 export type { PointsLinesInspection } from './points-lines/inspection';
+/**
+ * Public bounded GPU pass facts. Use the single `gpuPassTiming` opt-in,
+ * `draw()` receipt, and `observe(receipt, { include: ['timings'] })` route.
+ * Branch on the closed statuses `complete`, `partial`, `unavailable`, and
+ * `failed`; each reason/error exposes `code`, `expected`, `hint`, and `detail`.
+ * `latestKnownGood` is separate from current status and completeness. These
+ * facts describe pass durations, never frame latency. The bounded contract is
+ * in `record/gpu-pass-timing/contract.ts`; benchmark acceptance is fail-closed
+ * in `bench/gpu-pass-timing/validator.ts`, and recovery follows the producer's
+ * structured hint rather than a second timing API.
+ */
+export type {
+  GpuPassTimingCapability,
+  GpuPassTimingEntry,
+  GpuPassTimingError,
+  GpuPassTimingErrorCode,
+  GpuPassTimingFrame,
+  GpuPassTimingMeasuredEntry,
+  GpuPassTimingMeasurementSource,
+  GpuPassTimingObservation,
+  GpuPassTimingOptions,
+  GpuPassTimingPassIdentity,
+  GpuPassTimingReason,
+  GpuPassTimingReasonCode,
+  GpuPassTimingRef,
+  GpuPassTimingUnmeasuredEntry,
+} from './record/gpu-pass-timing/index.js';
 // Runtime contract: leases, frame receipts, detached inspection, profile,
 // lifecycle state, and the single renderer event stream.
+export {
+  advanceProbeFilter,
+  boxProjectReflectionDirection,
+  commitProbeFilterStep,
+  createProbeFilterState,
+  type ProbeFilterState,
+  probeFilterIsSteady,
+} from './reflection/filter';
+export {
+  buildReflectionProbeTable,
+  type ReflectionProbeTable,
+  type ReflectionProbeTableRow,
+  reflectionProbeTableBytes,
+} from './reflection/gpu-table';
+export {
+  admitReflectionProbe,
+  DEFAULT_REFLECTION_PROBE_LIMITS,
+  estimateReflectionProbeBytes,
+  type ReflectionProbeAdmission,
+  type ReflectionProbeAdmissionLimits,
+  type ReflectionProbeFact,
+  type ReflectionProbeInput,
+  ReflectionProbeProjection,
+  type ReflectionProbeProjectionSnapshot,
+  type ReflectionProbeSelection,
+  type ReflectionProbeSelectionResult,
+  type SkylightSelection,
+  selectReflectionProbe,
+  validateReflectionProbeInput,
+} from './reflection/projection';
 export type {
+  CubeCameraSnapshot,
   FrameCamera,
   FrameEnvironment,
   FrameObservationRequest,
@@ -170,6 +302,31 @@ export type {
   RenderWorldLease,
 } from './render-contract';
 export { RENDER_PHASE_CATALOG } from './render-contract';
+export type {
+  TemporalInspectionInput,
+  TemporalInspectionStatus,
+} from './renderer-inspect';
+export {
+  SHADOW_ATLAS_DEFAULT_FACE_SIZE,
+  SHADOW_ATLAS_DEFAULT_LAYERS,
+  ShadowAtlas,
+} from './shadow-atlas';
+export type {
+  RenderTarget,
+  RenderTargetAdmissionLimits,
+  RenderTargetDepthFormat,
+  RenderTargetDescriptor,
+  RenderTargetFormat,
+  RenderTargetMipLevels,
+  RenderTargetReadbackData,
+  RenderTargetReadbackRequest,
+  RenderTargetReadbackTicket,
+  RenderTargetSampleCount,
+  RenderTargetShape,
+  RenderTargetTextureAspect,
+  RenderTargetTextureSource,
+  RenderTargetTextureSourceOptions,
+} from './targets/contracts';
 export type { TemporalInspection, TemporalResourceInspection } from './temporal/inspection';
 export {
   SCENE_DATA_TEMPORAL_V1_DESCRIPTOR,
@@ -187,3 +344,31 @@ export {
   type SceneDataInspection,
 } from './temporal/scene-data-catalog';
 export type { TemporalView } from './temporal/view';
+export {
+  hasVolumetricFogCapability,
+  type IntegratedVolumeResource,
+  resolveIntegratedVolumeConsumer,
+  resolveSelectedVolumetricLight,
+  resolveVolumetricFogLightPair,
+  type VolumeConsumer,
+  type VolumetricFogLightKind,
+  type VolumetricFogLightPairResolution,
+  type VolumetricFogLightResolution,
+} from './volume/capability';
+export {
+  type ValidatedVolumetricFog,
+  type VolumeBounds,
+  type VolumeDensityBinding,
+  VolumetricFog,
+  type VolumetricFogAuthoring,
+  type VolumetricFogLightSelection,
+  validateVolumetricFog,
+} from './volume/component';
+export { extractVolumetricFog, type VolumetricFogExtract } from './volume/extract';
+export {
+  inspectVolumetricFog,
+  type VolumetricFogInspection,
+  type VolumetricFogInspectionInput,
+  type VolumetricFogInspectionStatus,
+  type VolumetricFogResourceStage,
+} from './volume/inspection';

package/src/inspection-types.ts

@@ -4,6 +4,7 @@
  * extract/record dependency graph.
  */
 
+import type { DirectionalShadowFilterLabel } from './components/directional-shadow-filter';
 import type { PointsLinesInspection } from './points-lines/inspection';
 
 export type BloomGraphStatus = 'empty' | 'valid' | 'invalid';
@@ -65,6 +66,61 @@ export interface GpuDrivenProductionInspection {
   readonly cpuFallbackDrawItems: number;
 }
 
+export type DirectionalShadowEffectiveProfile =
+  | 'off'
+  | DirectionalShadowFilterLabel
+  | 'rhi-null-structural';
+
+export type DirectionalShadowProfile = 'off' | DirectionalShadowFilterLabel;
+
+export interface DirectionalShadowInspectionError {
+  readonly code: string;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail?: unknown;
+}
+
+/** Bounded, detached Directional shadow facts for AI-readable inspection. */
+export interface DirectionalShadowInspection {
+  readonly requested: DirectionalShadowProfile;
+  readonly effective: DirectionalShadowEffectiveProfile;
+  readonly status: 'accepted' | 'fallback' | 'rejected';
+  readonly fallbackReason?: 'webgl2-unsupported' | 'rhi-null-structural' | 'candidate-failed';
+  readonly lastKnownGood: boolean;
+  readonly pixelEvidence: 'available' | 'not-available';
+  readonly cascadeCount: number;
+  readonly mapSize: number;
+  readonly atlasBytes: number;
+  readonly writerPasses: number;
+  readonly blockerTaps: number;
+  readonly filterTapUpperBound: number;
+  readonly seamTapUpperBound: number;
+  readonly shadowAngularRadius: number | undefined;
+  readonly maxPenumbraTexels: number | undefined;
+  readonly deviceGeneration: number;
+  readonly graphGeneration: number;
+  readonly error?: DirectionalShadowInspectionError;
+}
+
+export type ReflectionProbeSelectionInspection =
+  | { readonly kind: 'probe'; readonly worldId: number; readonly entityKey: number }
+  | { readonly kind: 'skylight' };
+
+export interface ReflectionProbeInspection {
+  readonly selection: ReflectionProbeSelectionInspection;
+  readonly factCount: number;
+  readonly acceptedCount: number;
+  readonly activeCount: number;
+  readonly rawFacesCaptured: number;
+  readonly filteredStepsCompleted: number;
+  readonly filteredMipLevels: readonly number[];
+  readonly scheduledRawFaces: number;
+  readonly scheduledFilteredSteps: number;
+  readonly pipelineReady: boolean;
+  readonly pipelineWarmupAttempts: number;
+  readonly pipelineWarmupFailure?: string;
+}
+
 /** Detached semantic descriptor for the Standard scene-temporal producer. */
 export interface TemporalTargetInspection {
   readonly identity: 'standard-scene-temporal';

package/src/instances-derived-bounds.ts

@@ -0,0 +1,171 @@
+import { box3, type Mat4Like, mat4 } from '@forgeax/engine-math';
+
+/**
+ * Inputs owned by the render extract/persistent-scene boundary. Bounds are
+ * deliberately derived here instead of being added to the author-facing
+ * `Instances` component or written back to a Pack asset.
+ */
+export interface DerivedInstancesUnionBoundsInput {
+  readonly meshAabb: ArrayLike<number> | undefined;
+  readonly entityWorld: ArrayLike<number>;
+  readonly transforms: ArrayLike<number> | undefined;
+}
+
+/**
+ * Renderer-owned cache key. Each generation is supplied by the owner that can
+ * observe that mutation: mesh/AABB publication, entity world transform, and
+ * the packed instance matrix array respectively.
+ */
+export interface InstanceBoundsCacheKey {
+  /** Optional scene/world scope for composite scenes; omitted for standalone tests. */
+  readonly worldId?: number;
+  readonly entityKey: number;
+  readonly meshGeneration: number;
+  readonly transformGeneration: number;
+  readonly matrixGeneration: number;
+}
+
+export type InstanceBoundsCacheInput = InstanceBoundsCacheKey & DerivedInstancesUnionBoundsInput;
+
+/**
+ * Stable bitwise fingerprint for detached numeric facts used by the cache.
+ * Float32 bits are hashed rather than decimal text so a real matrix/AABB
+ * change invalidates the projection without keeping another mutable ledger.
+ */
+export function fingerprintNumericArray(values: ArrayLike<number>): number {
+  let hash = 0x811c9dc5;
+  const scalar = new Float32Array(1);
+  const bits = new Uint32Array(scalar.buffer);
+  for (let index = 0; index < values.length; index += 1) {
+    scalar[0] = Number(values[index]);
+    hash = Math.imul(hash ^ (bits[0] ?? 0), 0x01000193) >>> 0;
+  }
+  return hash >>> 0;
+}
+
+function finiteAabb(aabb: ArrayLike<number> | undefined): aabb is ArrayLike<number> {
+  if (aabb === undefined || aabb.length < 6) return false;
+  const minX = aabb[0] as number;
+  const minY = aabb[1] as number;
+  const minZ = aabb[2] as number;
+  const maxX = aabb[3] as number;
+  const maxY = aabb[4] as number;
+  const maxZ = aabb[5] as number;
+  return (
+    Number.isFinite(minX) &&
+    Number.isFinite(minY) &&
+    Number.isFinite(minZ) &&
+    Number.isFinite(maxX) &&
+    Number.isFinite(maxY) &&
+    Number.isFinite(maxZ) &&
+    minX <= maxX &&
+    minY <= maxY &&
+    minZ <= maxZ
+  );
+}
+
+function finiteMatrix(matrix: ArrayLike<number>): matrix is Mat4Like {
+  if (matrix.length < 16) return false;
+  for (let index = 0; index < 16; index += 1) {
+    if (!Number.isFinite(matrix[index] as number)) return false;
+  }
+  return true;
+}
+
+function includeBox(out: box3.Box3, candidate: box3.Box3Like): void {
+  for (const x of [candidate[0] as number, candidate[3] as number]) {
+    for (const y of [candidate[1] as number, candidate[4] as number]) {
+      for (const z of [candidate[2] as number, candidate[5] as number]) {
+        box3.expandByPoint(out, [x, y, z]);
+      }
+    }
+  }
+}
+
+/**
+ * Derive the world-space AABB enclosing every instance of a mesh.
+ *
+ * `undefined` is a conservative signal: the caller must skip CPU culling
+ * when an input is missing, malformed, or empty. This prevents an empty
+ * `Instances` row from becoming a synthetic identity draw/bounds candidate.
+ */
+export function deriveInstancesUnionBounds(
+  input: DerivedInstancesUnionBoundsInput,
+): Float32Array | undefined {
+  const { meshAabb, entityWorld, transforms } = input;
+  if (!finiteAabb(meshAabb) || !finiteMatrix(entityWorld) || transforms === undefined) {
+    return undefined;
+  }
+  if (transforms.length === 0 || transforms.length % 16 !== 0) return undefined;
+
+  const local = box3.create(
+    meshAabb[0] as number,
+    meshAabb[1] as number,
+    meshAabb[2] as number,
+    meshAabb[3] as number,
+    meshAabb[4] as number,
+    meshAabb[5] as number,
+  );
+  const union = box3.create();
+  const composed = mat4.create();
+  const transformed = box3.create();
+  for (let offset = 0; offset < transforms.length; offset += 16) {
+    const instance = new Float32Array(16);
+    for (let lane = 0; lane < 16; lane += 1) {
+      instance[lane] = transforms[offset + lane] as number;
+    }
+    if (!finiteMatrix(instance)) return undefined;
+    mat4.multiply(composed, entityWorld, instance);
+    box3.transformBox3(transformed, local, composed);
+    if (!finiteAabb(transformed)) return undefined;
+    includeBox(union, transformed);
+  }
+  return new Float32Array(union);
+}
+
+interface InstanceBoundsCacheEntry extends InstanceBoundsCacheKey {
+  readonly bounds: Float32Array | undefined;
+}
+
+/**
+ * Small renderer-owned per-entity cache. A changed generation replaces the
+ * entry atomically; packed-id reuse is safe when its owner supplies a new
+ * generation (the normal RenderScene slot generation contract).
+ */
+export class InstanceBoundsCache {
+  private readonly entries = new Map<string, InstanceBoundsCacheEntry>();
+
+  private key(input: Pick<InstanceBoundsCacheKey, 'worldId' | 'entityKey'>): string {
+    return `${input.worldId === undefined ? '' : `${input.worldId}:`}${input.entityKey}`;
+  }
+
+  get(input: InstanceBoundsCacheInput): Float32Array | undefined {
+    const previous = this.entries.get(this.key(input));
+    if (
+      previous !== undefined &&
+      previous.meshGeneration === input.meshGeneration &&
+      previous.transformGeneration === input.transformGeneration &&
+      previous.matrixGeneration === input.matrixGeneration
+    ) {
+      return previous.bounds;
+    }
+    const bounds = deriveInstancesUnionBounds(input);
+    this.entries.set(this.key(input), {
+      ...(input.worldId === undefined ? {} : { worldId: input.worldId }),
+      entityKey: input.entityKey,
+      meshGeneration: input.meshGeneration,
+      transformGeneration: input.transformGeneration,
+      matrixGeneration: input.matrixGeneration,
+      bounds,
+    });
+    return bounds;
+  }
+
+  invalidate(entityKey?: number, worldId?: number): void {
+    if (entityKey === undefined) {
+      this.entries.clear();
+    } else {
+      this.entries.delete(this.key({ entityKey, ...(worldId === undefined ? {} : { worldId }) }));
+    }
+  }
+}