@forgeax/engine-render 0.1.28 → 0.1.29

package/src/scene/shadow-visibility.ts

@@ -0,0 +1,21 @@
+import { frustum } from '@forgeax/engine-math';
+import type { ExtractedLights } from '../render-system-extract';
+
+/** Light visibility is independent of camera visibility, including across Worlds. */
+export function buildShadowFrusta(lights: ExtractedLights): frustum.Frustum[] {
+  const result: frustum.Frustum[] = [];
+  const add = (matrix: Float32Array): void => {
+    result.push(frustum.fromViewProjection(frustum.create(), matrix));
+  };
+  for (const matrix of lights.lightViewProj?.slice(0, lights.cascadeCount) ?? []) add(matrix);
+  for (const snapshot of lights.pointShadow) {
+    if (snapshot.shadowAtlasLayer < 0) continue;
+    for (let face = 0; face < 6; face += 1)
+      add(snapshot.shadowMatrices.subarray(face * 16, (face + 1) * 16));
+  }
+  for (const snapshot of lights.spot) {
+    if (snapshot.shadowAtlasTile >= 0 && snapshot.lightViewProj !== undefined)
+      add(snapshot.lightViewProj);
+  }
+  return result;
+}

package/src/ssr/admission.ts

@@ -10,8 +10,17 @@ import {
   type RhiTextureFormatCapabilityReceipt,
   validateR32FloatReceipt,
 } from '@forgeax/engine-rhi';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import type { ScreenSpaceReflectionData } from '../components/screen-space-reflection';
 import type { ReflectionFallbackReceipt } from '../inspection-types';
-import type { SsrOwnerRecoveryAction } from './errors';
+import type {
+  SsrConfigField,
+  SsrConfigInvalidError,
+  SsrConfigRange,
+  SsrOwnerRecoveryAction,
+  SsrSpatialUnavailableReason,
+  SsrUnavailableError,
+} from './errors';
 import type { SsrAdmissionIdentity } from './identity';
 
 export const SSR_FORMAT_PROFILE = 'r32float-mip-sampled-storage' as const;
@@ -319,20 +328,12 @@ export function admitSsrM0(input: SsrAdmissionInput): SsrAdmissionResult {
       input.reflectionFallback.projectionGeneration,
     );
   }
-  if (input.temporal === undefined) {
-    return blocked(
-      input.identity,
-      failure(
-        'ssr-temporal-unavailable',
-        'temporal',
-        'submit the matching temporal producer receipt',
-      ),
-      input.reflectionFallback.projectionGeneration,
-    );
-  }
-  const temporalIdentityFailure = receiptFailure(input, input.temporal, 'temporal');
+  // Prior submitted history is optional for fresh spatial SSR. If supplied,
+  // its identity and validity still obey the temporal owner's contract.
+  const temporalIdentityFailure =
+    input.temporal === undefined ? undefined : receiptFailure(input, input.temporal, 'temporal');
   if (temporalIdentityFailure !== undefined) return temporalIdentityFailure;
-  if (!validTemporal(input.temporal)) {
+  if (input.temporal !== undefined && !validTemporal(input.temporal)) {
     return blocked(
       input.identity,
       failure('ssr-temporal-unavailable', 'temporal', 'inspect and rebuild the temporal receipt'),
@@ -449,3 +450,368 @@ export function resolveSsrAdmissionGeneration(
     generation: nextGeneration,
   };
 }
+
+/** Standard spatial lanes that may consume an SSR candidate. */
+export type SsrSpatialLane = 'clustered' | 'deferred' | 'direct' | 'cpu-webgl2' | 'forward';
+
+/** Capability facts required by the M1 spatial path. */
+export interface SsrSpatialCapabilities {
+  readonly compute: boolean;
+  readonly storageTexture: boolean;
+  readonly rgba16floatRenderable: boolean;
+  readonly r32floatSampledStorage: boolean;
+}
+
+/** Detached owner facts consumed by spatial admission. */
+export interface SsrSpatialEnvironment {
+  readonly lane: SsrSpatialLane;
+  readonly m0: Pick<SsrAdmissionResult, 'status'>;
+  readonly sceneInputs: boolean;
+  /** Current-frame motion/coverage producer, not reusable previous-frame history. */
+  readonly temporal: boolean;
+  readonly reflectionFallback: boolean;
+  readonly capabilities: SsrSpatialCapabilities;
+  /** Recovery readiness is optional for callers that have no recovery fault. */
+  readonly recovery?: boolean;
+}
+
+/** The only camera fields used by the spatial admission owner. */
+export interface SsrSpatialCamera {
+  readonly projection: 'perspective' | 'orthographic';
+  readonly near: number;
+  readonly far: number;
+  readonly screenSpaceReflection?: ScreenSpaceReflectionData;
+}
+
+export interface SsrSpatialWork {
+  readonly attachmentCount: number;
+  readonly passCount: number;
+  readonly bindingCount: number;
+  readonly resourceCount: number;
+  readonly historyCount: 0;
+  readonly temporalDemand: 0;
+}
+
+export type SsrSpatialStatus =
+  | 'not-requested'
+  | 'requested'
+  | 'admitted'
+  | 'fallback-only'
+  | 'structural-only';
+
+export interface SsrSpatialAdmissionBase {
+  readonly status: SsrSpatialStatus;
+  readonly lane: SsrSpatialLane;
+  readonly config: ScreenSpaceReflectionData | undefined;
+  readonly viewRange: number;
+  readonly work: SsrSpatialWork;
+}
+
+export type SsrSpatialAdmission =
+  | (SsrSpatialAdmissionBase & {
+      readonly status: 'not-requested' | 'requested';
+      readonly failure?: undefined;
+    })
+  | (SsrSpatialAdmissionBase & {
+      readonly status: 'admitted';
+      readonly config: ScreenSpaceReflectionData;
+      readonly failure?: undefined;
+    })
+  | (SsrSpatialAdmissionBase & {
+      readonly status: 'fallback-only' | 'structural-only';
+      readonly failure: SsrConfigInvalidError | SsrUnavailableError;
+    });
+
+const ZERO_SPATIAL_WORK: SsrSpatialWork = Object.freeze({
+  attachmentCount: 0,
+  passCount: 0,
+  bindingCount: 0,
+  resourceCount: 0,
+  historyCount: 0,
+  temporalDemand: 0,
+});
+
+const ADMITTED_SPATIAL_WORK: SsrSpatialWork = Object.freeze({
+  attachmentCount: 3,
+  passCount: 4,
+  bindingCount: 4,
+  resourceCount: 3,
+  historyCount: 0,
+  temporalDemand: 0,
+});
+
+function configRange(
+  field: SsrConfigField,
+  viewRange: number,
+  maxDistance: number,
+): SsrConfigRange {
+  switch (field) {
+    case 'maxDistance':
+      return { min: 0, minInclusive: false, max: viewRange, maxInclusive: true };
+    case 'thickness':
+      return { min: 0, minInclusive: false, max: maxDistance, maxInclusive: true };
+    case 'maxRoughness':
+      return { min: 0, minInclusive: true, max: 1, maxInclusive: true };
+  }
+}
+
+function configError(
+  field: SsrConfigField,
+  value: number,
+  range: SsrConfigRange,
+): SsrConfigInvalidError {
+  const left = range.minInclusive ? '[' : '(';
+  const right = range.maxInclusive ? ']' : ')';
+  return Object.freeze({
+    code: 'ssr-config-invalid',
+    expected: `finite ${field} in ${left}${range.min}, ${range.max}${right}`,
+    hint: `set ${field} to a finite value inside the reported range before retrying`,
+    detail: Object.freeze({ field, value, range: Object.freeze(range) }),
+  });
+}
+
+/** Validate one schema-derived component value against the active view. */
+export function validateScreenSpaceReflection(
+  config: ScreenSpaceReflectionData,
+  input: { readonly viewRange: number },
+): Result<ScreenSpaceReflectionData, SsrConfigInvalidError> {
+  const viewRange = input.viewRange;
+  if (!Number.isFinite(viewRange) || viewRange <= 0) {
+    return err(
+      configError('maxDistance', config.maxDistance, configRange('maxDistance', viewRange, 0)),
+    );
+  }
+  if (
+    !Number.isFinite(config.maxDistance) ||
+    config.maxDistance <= 0 ||
+    config.maxDistance > viewRange
+  ) {
+    return err(
+      configError(
+        'maxDistance',
+        config.maxDistance,
+        configRange('maxDistance', viewRange, config.maxDistance),
+      ),
+    );
+  }
+  if (
+    !Number.isFinite(config.thickness) ||
+    config.thickness <= 0 ||
+    config.thickness > config.maxDistance
+  ) {
+    return err(
+      configError(
+        'thickness',
+        config.thickness,
+        configRange('thickness', viewRange, config.maxDistance),
+      ),
+    );
+  }
+  if (!Number.isFinite(config.maxRoughness) || config.maxRoughness < 0 || config.maxRoughness > 1) {
+    return err(
+      configError(
+        'maxRoughness',
+        config.maxRoughness,
+        configRange('maxRoughness', viewRange, config.maxDistance),
+      ),
+    );
+  }
+  return ok(
+    Object.freeze({
+      maxDistance: config.maxDistance,
+      thickness: config.thickness,
+      maxRoughness: config.maxRoughness,
+    }),
+  );
+}
+
+function unavailable(
+  lane: SsrSpatialLane,
+  reason: SsrSpatialUnavailableReason,
+  required: readonly string[],
+  actual: Readonly<Record<string, boolean | number | string>>,
+): SsrUnavailableError {
+  const recovery =
+    reason === 'lane-unsupported' || reason === 'projection-unsupported'
+      ? 'select a perspective clustered or deferred Standard lane'
+      : reason === 'reflection-fallback-unavailable'
+        ? 'repair the submitted reflection fallback owner receipt'
+        : reason === 'temporal-unavailable'
+          ? 'submit the matching temporal-v1 producer receipt'
+          : reason === 'recovery-unavailable'
+            ? 'complete device and producer recovery before retrying'
+            : 'restore the required scene, capability, or format input before retrying';
+  return Object.freeze({
+    code: 'ssr-unavailable',
+    expected: 'SSR spatial admission has a complete Standard input and capability set',
+    hint: recovery,
+    detail: Object.freeze({
+      lane,
+      reason,
+      required: Object.freeze([...required]),
+      actual: Object.freeze({ ...actual }),
+      recovery,
+    }),
+  });
+}
+
+function unavailableResult(
+  lane: SsrSpatialLane,
+  viewRange: number,
+  failure: SsrUnavailableError,
+): SsrSpatialAdmission {
+  return Object.freeze({
+    status: 'fallback-only',
+    lane,
+    config: undefined,
+    viewRange,
+    work: ZERO_SPATIAL_WORK,
+    failure,
+  });
+}
+
+/**
+ * Admit the active camera's schema-derived component into the M1 spatial
+ * path. No graph/resource handle crosses this boundary.
+ */
+export function admitSsrSpatial(input: {
+  readonly camera: SsrSpatialCamera;
+  readonly environment: SsrSpatialEnvironment;
+}): SsrSpatialAdmission {
+  const camera = input.camera;
+  const environment = input.environment;
+  const viewRange = camera.far - camera.near;
+  const config = camera.screenSpaceReflection;
+  if (config === undefined) {
+    return Object.freeze({
+      status: 'not-requested',
+      lane: environment.lane,
+      config: undefined,
+      viewRange,
+      work: ZERO_SPATIAL_WORK,
+    });
+  }
+
+  const valid = validateScreenSpaceReflection(config, { viewRange });
+  if (!valid.ok) {
+    return Object.freeze({
+      status: 'fallback-only',
+      lane: environment.lane,
+      config,
+      viewRange,
+      work: ZERO_SPATIAL_WORK,
+      failure: valid.error,
+    });
+  }
+
+  if (environment.m0.status !== 'admitted') {
+    return unavailableResult(
+      environment.lane,
+      viewRange,
+      unavailable(
+        environment.lane,
+        'reflection-fallback-unavailable',
+        ['admitted M0 dependency receipt'],
+        { m0: false },
+      ),
+    );
+  }
+  if (environment.lane !== 'clustered' && environment.lane !== 'deferred') {
+    return unavailableResult(
+      environment.lane,
+      viewRange,
+      unavailable(environment.lane, 'lane-unsupported', ['clustered or deferred Standard lane'], {
+        lane: environment.lane,
+      }),
+    );
+  }
+  if (camera.projection !== 'perspective') {
+    return unavailableResult(
+      environment.lane,
+      viewRange,
+      unavailable(environment.lane, 'projection-unsupported', ['perspective camera'], {
+        projection: camera.projection,
+      }),
+    );
+  }
+  if (!environment.sceneInputs) {
+    return unavailableResult(
+      environment.lane,
+      viewRange,
+      unavailable(
+        environment.lane,
+        'scene-input-unavailable',
+        ['deferred Standard scene/material/fallback inputs'],
+        { sceneInputs: false },
+      ),
+    );
+  }
+  if (!environment.temporal) {
+    return unavailableResult(
+      environment.lane,
+      viewRange,
+      unavailable(environment.lane, 'temporal-unavailable', ['temporal-v1'], { temporal: false }),
+    );
+  }
+  if (!environment.reflectionFallback) {
+    return unavailableResult(
+      environment.lane,
+      viewRange,
+      unavailable(
+        environment.lane,
+        'reflection-fallback-unavailable',
+        ['submitted BRDF-projected fallback'],
+        { reflectionFallback: false },
+      ),
+    );
+  }
+  if (environment.recovery === false) {
+    return unavailableResult(
+      environment.lane,
+      viewRange,
+      unavailable(environment.lane, 'recovery-unavailable', ['ready device and owners'], {
+        recovery: false,
+      }),
+    );
+  }
+  const capabilities = environment.capabilities;
+  if (
+    !capabilities.compute ||
+    !capabilities.storageTexture ||
+    !capabilities.rgba16floatRenderable
+  ) {
+    return unavailableResult(
+      environment.lane,
+      viewRange,
+      unavailable(
+        environment.lane,
+        'capability-unavailable',
+        ['compute', 'storageTexture', 'rgba16floatRenderable'],
+        {
+          compute: capabilities.compute,
+          storageTexture: capabilities.storageTexture,
+          rgba16floatRenderable: capabilities.rgba16floatRenderable,
+        },
+      ),
+    );
+  }
+  if (!capabilities.r32floatSampledStorage) {
+    return unavailableResult(
+      environment.lane,
+      viewRange,
+      unavailable(
+        environment.lane,
+        'format-unavailable',
+        ['r32float sampled and storage mip chain'],
+        { r32floatSampledStorage: false },
+      ),
+    );
+  }
+  return Object.freeze({
+    status: 'admitted',
+    lane: environment.lane,
+    config: valid.value,
+    viewRange,
+    work: ADMITTED_SPATIAL_WORK,
+  });
+}

package/src/ssr/compose.ts

@@ -0,0 +1,144 @@
+import type {
+  GraphBuffer,
+  GraphTextureView,
+  RenderGraphBuilder,
+} from '@forgeax/engine-render-graph';
+import type { BindGroup, BindGroupLayout, RenderPipeline, Sampler } from '@forgeax/engine-rhi';
+import { RhiError } from '@forgeax/engine-rhi';
+import { GPU_SHADER_STAGE_FRAGMENT } from '../gpu-stage';
+import { getOrCreateFromChain } from '../record/mesh-ssbo';
+import type { _InternalRenderPipelineContext } from '../record/render-context';
+import type { RenderPipelineFrame, RenderPipelineTarget } from '../render-pipeline';
+
+/** Material response is produced with the visible surface; composition never
+ * redraws that surface, so equal-depth overlaps cannot apply the delta twice. */
+export function addSsrCompositionPass(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  input: {
+    readonly scene: RenderPipelineTarget;
+    readonly radiance: GraphTextureView;
+    readonly fallback: GraphTextureView;
+    readonly response: GraphTextureView;
+    readonly normal: GraphTextureView;
+    readonly view: GraphBuffer;
+  },
+) {
+  let state:
+    | {
+        pipeline: RenderPipeline;
+        layout: BindGroupLayout;
+        sampler: Sampler;
+        groups: WeakMap<object, unknown>;
+      }
+    | undefined;
+  const views = [input.radiance, input.fallback, input.response, input.normal];
+  return graph.addRasterPass('ssr-compose', {
+    accesses: [
+      ...views.map((resource) => ({ resource, usage: 'sampled-read' as const })),
+      { resource: input.view, usage: 'uniform-read' },
+      { resource: input.scene.view, usage: 'color-attachment' },
+    ],
+    colorAttachments: [{ view: input.scene.view, loadOp: 'load', storeOp: 'store' }],
+    encode: ({ pass, frame, resources }) => {
+      const source = frame.ssrShaders?.compose;
+      if (source === undefined) return;
+      const device = frame.runtime.device;
+      if (state === undefined) {
+        const factory = frame.runtime.shaderModuleFactory;
+        if (factory === undefined)
+          throw new RhiError({
+            code: 'rhi-not-available',
+            expected: 'SSR composition shader module factory',
+            hint: 'construct the renderer through a backend pack with shader module support',
+          });
+        const module = factory.createShaderModule({ code: source, label: 'ssr_compose' }).unwrap();
+        const layout = device
+          .createBindGroupLayout({
+            entries: [
+              ...views.map((_, binding) => ({
+                binding,
+                visibility: GPU_SHADER_STAGE_FRAGMENT,
+                texture: {
+                  sampleType: binding === 0 ? ('float' as const) : ('unfilterable-float' as const),
+                  viewDimension: '2d' as const,
+                },
+              })),
+              {
+                binding: 4,
+                visibility: GPU_SHADER_STAGE_FRAGMENT,
+                sampler: { type: 'filtering' as const },
+              },
+              {
+                binding: 5,
+                visibility: GPU_SHADER_STAGE_FRAGMENT,
+                buffer: { type: 'uniform' as const },
+              },
+            ],
+          })
+          .unwrap();
+        const pipelineLayout = device.createPipelineLayout({ bindGroupLayouts: [layout] }).unwrap();
+        const pipeline = device
+          .createRenderPipeline({
+            label: 'ssr_compose',
+            layout: pipelineLayout,
+            vertex: { module, entryPoint: 'vs_ssr_compose', buffers: [] },
+            fragment: {
+              module,
+              entryPoint: 'fs_ssr_compose',
+              targets: [
+                {
+                  format: 'rgba16float',
+                  blend: {
+                    color: { operation: 'add', srcFactor: 'one', dstFactor: 'one' },
+                    alpha: { operation: 'add', srcFactor: 'zero', dstFactor: 'one' },
+                  },
+                },
+              ],
+            },
+            primitive: { topology: 'triangle-list' },
+          })
+          .unwrap();
+        const sampler = device
+          .createSampler({
+            addressModeU: 'clamp-to-edge',
+            addressModeV: 'clamp-to-edge',
+            minFilter: 'linear',
+            magFilter: 'linear',
+            mipmapFilter: 'linear',
+          })
+          .unwrap();
+        state = { pipeline, layout, sampler, groups: new WeakMap() };
+      }
+      const textures = views.map((view) => resources.textureView(view).unwrap());
+      const viewBuffer = resources.buffer(input.view).unwrap();
+      const layout = state.layout;
+      const sampler = state.sampler;
+      const group = getOrCreateFromChain(
+        state.groups,
+        [...textures, sampler, viewBuffer],
+        'ssr-compose',
+        () =>
+          device
+            .createBindGroup({
+              layout,
+              entries: [
+                ...textures.map((value, binding) => ({
+                  binding,
+                  resource: { kind: 'textureView' as const, value },
+                })),
+                { binding: 4, resource: { kind: 'sampler' as const, value: sampler } },
+                {
+                  binding: 5,
+                  resource: { kind: 'buffer' as const, value: { buffer: viewBuffer } },
+                },
+              ],
+            })
+            .unwrap(),
+        (frame as _InternalRenderPipelineContext).bindGroupCounts,
+      ) as BindGroup;
+      pass.setPipeline(state.pipeline);
+      pass.setBindGroup(0, group);
+      pass.draw(3);
+    },
+  });
+}

package/src/ssr/errors.ts

@@ -57,6 +57,54 @@ export interface SsrAdmissionError {
   readonly detail: SsrAdmissionErrorDetail;
 }
 
+/** Closed authoring fields accepted by the ScreenSpaceReflection schema. */
+export type SsrConfigField = 'maxDistance' | 'thickness' | 'maxRoughness';
+
+/** Dynamic finite range returned by ScreenSpaceReflection validation. */
+export interface SsrConfigRange {
+  readonly min: number;
+  readonly minInclusive: boolean;
+  readonly max: number;
+  readonly maxInclusive: boolean;
+}
+
+/** Structured invalid-authoring failure; callers branch on code and detail. */
+export interface SsrConfigInvalidError {
+  readonly code: 'ssr-config-invalid';
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: {
+    readonly field: SsrConfigField;
+    readonly value: number;
+    readonly range: SsrConfigRange;
+  };
+}
+
+/** Closed spatial admission reasons. */
+export type SsrSpatialUnavailableReason =
+  | 'lane-unsupported'
+  | 'projection-unsupported'
+  | 'scene-input-unavailable'
+  | 'capability-unavailable'
+  | 'format-unavailable'
+  | 'temporal-unavailable'
+  | 'reflection-fallback-unavailable'
+  | 'recovery-unavailable';
+
+/** Structured spatial admission failure with bounded actual facts. */
+export interface SsrUnavailableError {
+  readonly code: 'ssr-unavailable';
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: {
+    readonly lane: string;
+    readonly reason: SsrSpatialUnavailableReason;
+    readonly required: readonly string[];
+    readonly actual: Readonly<Record<string, boolean | number | string>>;
+    readonly recovery: string;
+  };
+}
+
 const EXPECTED = 'all detached SSR dependency receipts share one admitted identity';
 
 export function createSsrAdmissionError(detail: SsrAdmissionErrorDetail): SsrAdmissionError {