@forgeax/engine-render 0.1.20 → 0.1.21

package/src/ibl/kernel-cache.ts

@@ -0,0 +1,88 @@
+export const REFLECTION_PROBE_IBL_STAGES = ['raw', 'filtered', 'publish'] as const;
+export type ReflectionProbeIblStage = (typeof REFLECTION_PROBE_IBL_STAGES)[number];
+
+export interface IblKernelCache {
+  readonly generation: number;
+  readonly pipelineIdentity: object;
+  readonly samplerIdentity: object;
+  readonly brdfLutIdentity: object;
+}
+
+const kernelCaches = new Map<number, IblKernelCache>();
+
+export function createIblKernelCache(generation: number): IblKernelCache {
+  const existing = kernelCaches.get(generation);
+  if (existing !== undefined) return existing;
+  const created: IblKernelCache = {
+    generation,
+    pipelineIdentity: {},
+    samplerIdentity: {},
+    brdfLutIdentity: {},
+  };
+  kernelCaches.set(generation, created);
+  return created;
+}
+
+export interface ProbeIblOutput {
+  readonly entityKey: number;
+  readonly resolution: number;
+  readonly deviceGeneration: number;
+  readonly raw: object;
+  readonly filtered: object;
+  readonly rawGeneration: number;
+  readonly filteredGeneration: number;
+  readonly lkg: boolean;
+}
+
+export interface ProbeIblUpdate extends ProbeIblOutput {
+  readonly stages: typeof REFLECTION_PROBE_IBL_STAGES;
+  readonly nextStage: ReflectionProbeIblStage;
+  readonly candidateGeneration: number;
+}
+
+export function createProbeIblOutput(input: {
+  readonly entityKey: number;
+  readonly resolution: number;
+  readonly deviceGeneration: number;
+}): ProbeIblOutput {
+  return {
+    ...input,
+    raw: {},
+    filtered: {},
+    rawGeneration: 0,
+    filteredGeneration: 0,
+    lkg: true,
+  };
+}
+
+export function beginProbeIblUpdate(output: ProbeIblOutput): ProbeIblUpdate {
+  return {
+    ...output,
+    stages: REFLECTION_PROBE_IBL_STAGES,
+    nextStage: 'raw',
+    candidateGeneration: output.filteredGeneration + 1,
+  };
+}
+
+export function publishProbeIblOutput(
+  update: ProbeIblUpdate,
+  result: { readonly stage: ReflectionProbeIblStage; readonly ok: boolean },
+): ProbeIblOutput {
+  if (!result.ok || result.stage !== update.nextStage) return update;
+  if (result.stage === 'raw') {
+    return {
+      ...update,
+      rawGeneration: update.candidateGeneration,
+    };
+  }
+  if (result.stage === 'filtered') return update;
+  return {
+    ...update,
+    filteredGeneration: update.candidateGeneration,
+    lkg: true,
+  };
+}
+
+export function resetIblKernelCaches(): void {
+  kernelCaches.clear();
+}

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,
@@ -84,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';
@@ -131,13 +166,43 @@ 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 {
@@ -146,6 +211,10 @@ export {
   type StandardVolumetricFogQuality,
 } from './pipeline/standard-profile';
 export { renderComponentsPlugin } from './plugin';
+export {
+  inspectPointShadow,
+  type PointShadowInspection,
+} from './point-shadow-inspection';
 export {
   admitPointsLines,
   type LinesStyleInput,
@@ -156,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,
@@ -179,6 +306,27 @@ 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,

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 }) }));
+    }
+  }
+}

package/src/light-buffer-layout.ts

@@ -156,6 +156,15 @@ export const SPOT_LIGHT_STD430_BYTES = 80;
 export const SPOT_LIGHT_SHADOW_TILE_SENTINEL = -1;
 /** Sentinel for a projector-only SpotLight with no shadow atlas tile. */
 export const SPOT_LIGHT_PROJECTOR_ONLY_SENTINEL = -2;
+/**
+ * High-bit marker carried by the shared LightSlot identity lane when this
+ * SpotLight is the one projector selected for the frame. The lower 30 bits
+ * retain the shadow-atlas tile (0..3), or zero for projector-only lights, so
+ * one 64-byte slot carries both shadow and projector identity without growing
+ * the cluster UBO or inventing a second light list.
+ */
+export const SPOT_LIGHT_PROJECTOR_FLAG = 0x40000000;
+export const SPOT_LIGHT_TILE_MASK = SPOT_LIGHT_PROJECTOR_FLAG - 1;
 /** Byte size of the array header (count u32 + 12 B pad to 16 B stride). */
 export const LIGHT_ARRAY_HEADER_BYTES = 16;
 /** Maximum number of slots packed in the first-slice cap layout (D-S3). */
@@ -310,6 +319,7 @@ export interface PointShadowSlotInfo {
 export function packLightSlot(
   snap: PointLightSnapshot | SpotLightSnapshot,
   shadow?: PointShadowSlotInfo,
+  projectorSelected?: boolean,
 ): Float32Array {
   const out = new Float32Array(16);
   // position (vec3<f32> + invRangeSquared at lane .w)
@@ -340,12 +350,17 @@ export function packLightSlot(
     out[14] = shadow.near;
     out[15] = shadow.far;
   } else if (snap.kind === 'spot') {
-    i32[13] =
-      snap.shadowAtlasTile >= 0
+    // The optional argument is explicit at the record owner. Keeping the
+    // source-derived fallback preserves standalone packing fixtures while the
+    // production path marks only the accepted projector identity.
+    const hasProjector =
+      projectorSelected ?? (snap.projectorAsset !== undefined && snap.lightViewProj !== undefined);
+    const tile = snap.shadowAtlasTile >= 0 ? snap.shadowAtlasTile : 0;
+    i32[13] = hasProjector
+      ? SPOT_LIGHT_PROJECTOR_FLAG | (tile & SPOT_LIGHT_TILE_MASK)
+      : snap.shadowAtlasTile >= 0
         ? snap.shadowAtlasTile
-        : snap.projectorAsset !== undefined && snap.lightViewProj !== undefined
-          ? SPOT_LIGHT_PROJECTOR_ONLY_SENTINEL
-          : SPOT_LIGHT_SHADOW_TILE_SENTINEL;
+        : SPOT_LIGHT_SHADOW_TILE_SENTINEL;
     out[14] = snap.shadowIntensity ?? 1;
     // HDRP has no separate 80-byte SpotLight payload. Reuse the otherwise
     // unused spot `.w` lane so the cluster path consumes the same authored PCF