@forgeax/engine-render 0.1.19 → 0.1.21

package/src/assets/asset-decoders.ts

@@ -76,7 +76,7 @@ function resolveMaterialWireRefs(
     value.parameters === undefined
       ? MATERIAL_TEXTURE_SLOTS
       : value.parameters
-          .filter((parameter) => parameter.type === 'texture')
+          .filter((parameter) => parameter.type === 'texture' || parameter.type === 'texture_cube')
           .map((parameter) => parameter.name),
   );
   const values = { ...value.values };

package/src/assets/render-asset-port.ts

@@ -31,7 +31,13 @@ export function createRenderAssetPort(
       const artifact = shaderRegistry.findMaterialArtifact(shaderId);
       if (!artifact.ok) return [];
       return artifact.value.paramSchema
-        .filter((parameter) => parameter.type === 'texture2d')
+        .filter(
+          (parameter) =>
+            parameter.type === 'texture2d' ||
+            parameter.type === 'texture_cube' ||
+            parameter.type === 'texture_depth_2d' ||
+            parameter.type === 'texture_cube_array',
+        )
         .map((parameter) => parameter.name);
     },
   };

package/src/capture/cube-views.ts

@@ -0,0 +1,69 @@
+import { type Mat4, mat4, type Vec3Like } from '@forgeax/engine-math';
+import { CUBE_CAMERA_FACE_ORDER, type CubeCameraFace } from '../components/cube-camera';
+
+export interface CubeCameraFaceView {
+  readonly position: Vec3Like;
+  readonly face: CubeCameraFace;
+  readonly direction: readonly [number, number, number];
+  readonly up: readonly [number, number, number];
+  readonly near: number;
+  readonly far: number;
+  readonly view: Mat4;
+  readonly projection: Mat4;
+  readonly viewProjection: Mat4;
+}
+
+export interface CubeCameraFaceViewInput {
+  readonly position: Vec3Like;
+  readonly near: number;
+  readonly far: number;
+}
+
+const FACE_ORIENTATION: ReadonlyArray<{
+  readonly direction: readonly [number, number, number];
+  readonly up: readonly [number, number, number];
+}> = [
+  { direction: [1, 0, 0], up: [0, 1, 0] },
+  { direction: [-1, 0, 0], up: [0, 1, 0] },
+  { direction: [0, 1, 0], up: [0, 0, -1] },
+  { direction: [0, -1, 0], up: [0, 0, 1] },
+  { direction: [0, 0, 1], up: [0, 1, 0] },
+  { direction: [0, 0, -1], up: [0, 1, 0] },
+];
+
+function assertRange(near: number, far: number): void {
+  if (!Number.isFinite(near) || near <= 0 || !Number.isFinite(far) || far <= near) {
+    throw new RangeError('CubeCamera requires finite near > 0 and far > near.');
+  }
+}
+
+/** Build the only supported +X,-X,+Y,-Y,+Z,-Z cube orientation. */
+export function buildCubeCameraFaceViews(input: CubeCameraFaceViewInput): CubeCameraFaceView[] {
+  assertRange(input.near, input.far);
+  const views: CubeCameraFaceView[] = [];
+  for (const [index, face] of CUBE_CAMERA_FACE_ORDER.entries()) {
+    const orientation = FACE_ORIENTATION[index];
+    if (orientation === undefined)
+      throw new Error(`CubeCamera face orientation missing at ${index}`);
+    const target: Vec3Like = [
+      (input.position[0] ?? 0) + orientation.direction[0],
+      (input.position[1] ?? 0) + orientation.direction[1],
+      (input.position[2] ?? 0) + orientation.direction[2],
+    ];
+    const view = mat4.lookAt(mat4.create(), input.position, target, orientation.up);
+    const projection = mat4.perspective(mat4.create(), Math.PI / 2, 1, input.near, input.far);
+    const viewProjection = mat4.multiply(mat4.create(), projection, view);
+    views.push({
+      position: input.position,
+      face,
+      direction: orientation.direction,
+      up: orientation.up,
+      near: input.near,
+      far: input.far,
+      view,
+      projection,
+      viewProjection,
+    });
+  }
+  return views;
+}

package/src/capture/scheduler.ts

@@ -0,0 +1,265 @@
+import {
+  CUBE_CAMERA_FACE_ORDER,
+  type CubeCameraFace,
+  type CubeCameraUpdateIntent,
+} from '../components/cube-camera';
+import type { RenderError } from '../errors/render';
+import { RenderTargetOperationFailedError, RenderTargetStateInvalidError } from '../errors/render';
+import type { RenderResult } from '../render-contract';
+import type { RenderTarget } from '../targets/contracts';
+import { buildCubeCameraFaceViews, type CubeCameraFaceView } from './cube-views';
+
+export interface CubeCaptureRequest {
+  readonly target: RenderTarget;
+  readonly position: readonly [number, number, number];
+  readonly near: number;
+  readonly far: number;
+  readonly updateIntent: CubeCameraUpdateIntent;
+  readonly requestVersion: number;
+  readonly faceBudget: number;
+}
+
+export interface CubeCaptureWork extends CubeCameraFaceView {
+  readonly target: RenderTarget;
+  readonly requestVersion: number;
+  readonly candidateGeneration: number;
+}
+
+export interface CubeCaptureInspection {
+  readonly target: RenderTarget;
+  readonly activeGeneration: number;
+  readonly candidateGeneration?: number;
+  readonly completedVersion: number;
+  readonly pendingFaces: readonly CubeCameraFace[];
+  readonly fallback: 'neutral' | 'previous-active';
+  readonly nestedRejections: number;
+}
+
+export interface CubeCaptureSchedulerOptions {
+  readonly maxFacesPerFrame?: number;
+}
+
+export type CubeCaptureRenderableKind = 'opaque' | 'transparent' | 'environment' | 'debug' | 'ui';
+
+export interface CubeCaptureRenderable {
+  readonly kind: CubeCaptureRenderableKind;
+  readonly target?: RenderTarget;
+}
+
+/** Apply the Standard capture visibility boundary to one extracted scene. */
+export function selectCubeCaptureRenderables(
+  renderables: readonly CubeCaptureRenderable[],
+  candidateTarget: RenderTarget,
+): readonly CubeCaptureRenderable[] {
+  return renderables.filter(
+    (renderable) =>
+      renderable.kind !== 'debug' &&
+      renderable.kind !== 'ui' &&
+      renderable.target !== candidateTarget,
+  );
+}
+
+export interface CubeCaptureScheduler {
+  beginFrame(): void;
+  request(request: CubeCaptureRequest): RenderResult<{ readonly scheduled: boolean }, RenderError>;
+  nextWork(): readonly CubeCaptureWork[];
+  completeSubmission(
+    submitted: boolean,
+    completed?: Promise<unknown>,
+  ): RenderResult<void, RenderError>;
+  inspect(target: RenderTarget): CubeCaptureInspection;
+}
+
+interface PendingCapture {
+  readonly request: CubeCaptureRequest;
+  readonly views: readonly CubeCameraFaceView[];
+  readonly candidateGeneration: number;
+  readonly written: Set<CubeCameraFace>;
+  inFlight: readonly CubeCaptureWork[];
+}
+
+interface CaptureState {
+  readonly target: RenderTarget;
+  activeGeneration: number;
+  completedVersion: number;
+  pending: PendingCapture | undefined;
+  nestedRejections: number;
+}
+
+function invalid(
+  reason: 'generation-mismatch' | 'uninitialized',
+): RenderResult<never, RenderError> {
+  return {
+    ok: false,
+    error: new RenderTargetStateInvalidError({
+      operation: 'source',
+      reason,
+      state: reason === 'uninitialized' ? 'uninitialized' : 'candidate',
+      generation: 0,
+    }),
+  };
+}
+
+function failed(generation: number, cause: unknown): RenderResult<never, RenderError> {
+  return {
+    ok: false,
+    error: new RenderTargetOperationFailedError({
+      operation: 'source',
+      stage: 'submit',
+      generation,
+      cause,
+      recovery: 'retain-last-known-good',
+    }),
+  };
+}
+
+function validateRequest(request: CubeCaptureRequest): RenderResult<void, RenderError> {
+  if (!Number.isInteger(request.requestVersion) || request.requestVersion < 0) {
+    return invalid('generation-mismatch');
+  }
+  if (!Number.isInteger(request.faceBudget) || request.faceBudget < 1 || request.faceBudget > 6) {
+    return invalid('uninitialized');
+  }
+  if (request.updateIntent === 'once' && request.requestVersion > 1) {
+    return invalid('generation-mismatch');
+  }
+  return { ok: true, value: undefined };
+}
+
+/**
+ * Schedules CubeCamera views inside the existing display frame. The scheduler
+ * never owns a World, encoder, or queue; callers contribute the returned work
+ * to the frame graph and report the one matching submission result.
+ */
+export function createCubeCaptureScheduler(
+  options: CubeCaptureSchedulerOptions = {},
+): CubeCaptureScheduler {
+  const maxFacesPerFrame = Math.max(1, Math.min(6, Math.floor(options.maxFacesPerFrame ?? 1)));
+  const states = new WeakMap<object, CaptureState>();
+  let activeCapture: CaptureState | undefined;
+  let frameOpen = false;
+
+  const stateFor = (target: RenderTarget): CaptureState => {
+    const existing = states.get(target as object);
+    if (existing !== undefined) return existing;
+    const created: CaptureState = {
+      target,
+      activeGeneration: 0,
+      completedVersion: 0,
+      pending: undefined,
+      nestedRejections: 0,
+    };
+    states.set(target as object, created);
+    return created;
+  };
+
+  return {
+    beginFrame() {
+      frameOpen = true;
+      if (activeCapture?.pending !== undefined) activeCapture.pending.inFlight = [];
+    },
+
+    request(request) {
+      const valid = validateRequest(request);
+      if (!valid.ok) return valid;
+      const state = stateFor(request.target);
+      if (activeCapture?.pending !== undefined) {
+        state.nestedRejections += 1;
+        return invalid('generation-mismatch');
+      }
+      const shouldSchedule =
+        request.updateIntent === 'continuous' ||
+        state.activeGeneration === 0 ||
+        request.requestVersion > state.completedVersion;
+      if (!shouldSchedule) return { ok: true, value: { scheduled: false } };
+      const views = buildCubeCameraFaceViews({
+        position: request.position,
+        near: request.near,
+        far: request.far,
+      });
+      const pending: PendingCapture = {
+        request,
+        views,
+        candidateGeneration: state.activeGeneration + 1,
+        written: new Set(),
+        inFlight: [],
+      };
+      state.pending = pending;
+      activeCapture = state;
+      return { ok: true, value: { scheduled: true } };
+    },
+
+    nextWork() {
+      if (!frameOpen || activeCapture?.pending === undefined) return [];
+      const pending = activeCapture.pending;
+      if (pending.inFlight.length > 0) return pending.inFlight;
+      const remaining = pending.views.filter((view) => !pending.written.has(view.face));
+      const count = Math.min(maxFacesPerFrame, pending.request.faceBudget, remaining.length);
+      const work = remaining.slice(0, count).map((view) => ({
+        ...view,
+        target: pending.request.target,
+        requestVersion: pending.request.requestVersion,
+        candidateGeneration: pending.candidateGeneration,
+      }));
+      pending.inFlight = work;
+      return work;
+    },
+
+    completeSubmission(submitted, completed) {
+      const state = activeCapture;
+      const pending = state?.pending;
+      if (state === undefined || pending === undefined) return invalid('uninitialized');
+      if (!submitted) {
+        state.pending = undefined;
+        activeCapture = undefined;
+        return failed(pending.candidateGeneration, new Error('cube capture submission failed'));
+      }
+      const commit = (): void => {
+        if (activeCapture !== state || state.pending !== pending) return;
+        for (const work of pending.inFlight) pending.written.add(work.face);
+        pending.inFlight = [];
+        if (pending.written.size === CUBE_CAMERA_FACE_ORDER.length) {
+          state.activeGeneration = pending.candidateGeneration;
+          state.completedVersion = pending.request.requestVersion;
+          state.pending = undefined;
+          activeCapture = undefined;
+        }
+      };
+      if (completed === undefined) commit();
+      else
+        void completed.then(commit, () => {
+          if (activeCapture === state && state.pending === pending) {
+            state.pending = undefined;
+            activeCapture = undefined;
+          }
+        });
+      return { ok: true, value: undefined };
+    },
+
+    inspect(target) {
+      const state = stateFor(target);
+      const pending = state.pending;
+      const pendingFaces =
+        pending === undefined
+          ? []
+          : pending.views
+              .filter(
+                (view) =>
+                  !pending.written.has(view.face) &&
+                  !pending.inFlight.some((work) => work.face === view.face),
+              )
+              .map((view) => view.face);
+      return Object.freeze({
+        target: state.target,
+        activeGeneration: state.activeGeneration,
+        ...(state.pending === undefined
+          ? {}
+          : { candidateGeneration: state.pending.candidateGeneration }),
+        completedVersion: state.completedVersion,
+        pendingFaces,
+        fallback: state.activeGeneration === 0 ? 'neutral' : 'previous-active',
+        nestedRejections: state.nestedRejections,
+      });
+    },
+  };
+}

package/src/components/__tests__/schema-contract.unit.test.ts

@@ -5,6 +5,18 @@ describe('canonical render schema owners', () => {
   it('keeps mesh, light, and camera facts on their component owners', () => {
     expect(MeshFilter.fields.assetHandle.type).toBe('shared<MeshAsset>');
     expect(DirectionalLight.fields.direction.type).toBe('array<f32, 3>');
+    expect(DirectionalLight.fields.shadowFilter.type).toBe('enum');
+    expect(DirectionalLight.fields.shadowFilter.default).toBe(2);
+    expect(DirectionalLight.fields.shadowFilter.labels).toEqual({
+      pcf1: 1,
+      pcf3: 2,
+      pcf5: 3,
+      pcssMedium: 4,
+      pcssHigh: 5,
+    });
+    expect(DirectionalLight.fields.shadowAngularRadius.default).toBeCloseTo(0.00465, 8);
+    expect(DirectionalLight.fields.maxPenumbraTexels.default).toBe(32);
+    expect('pcfKernelSize' in DirectionalLight.fields).toBe(false);
     expect(Camera.fields.projection.default).toBe(0);
     expect(Camera.fields.antialias.default).toBe(0);
     expect(Camera.fields.historyVersion.default).toBe(0);

package/src/components/__tests__/schema-parity.unit.test.ts

@@ -13,6 +13,15 @@ describe('render schema parity', () => {
     expect(MeshFilter.fields.assetHandle.type).toBe('shared<MeshAsset>');
     expect(DirectionalLight.fields.direction.type).toBe('array<f32, 3>');
     expect(DirectionalLight.fields.castShadow.default).toBe(true);
+    expect(DirectionalLight.fields.shadowFilter.labels).toEqual({
+      pcf1: 1,
+      pcf3: 2,
+      pcf5: 3,
+      pcssMedium: 4,
+      pcssHigh: 5,
+    });
+    expect(DirectionalLight.fields.shadowFilter.default).toBe(2);
+    expect('pcfKernelSize' in DirectionalLight.fields).toBe(false);
     expect(MeshRenderer.fields.materials.type).toBe('array<shared<MaterialAsset>>');
   });
 

package/src/components/camera.ts

@@ -320,6 +320,10 @@ export const Camera = defineComponent('Camera', {
   bloomThreshold: { type: 'f32', default: 1.0 },
   bloomIntensity: { type: 'f32', default: 1.0 },
   bloomBlurRadius: { type: 'f32', default: 4.0 },
+  // M1 target camera role: zero means this camera is eligible for display;
+  // non-zero shared targets are auxiliary producers whose views and receipt
+  // promotion remain owned by Renderer.
+  target: { type: 'shared<RenderTarget>', simulationTransient: true },
   // feat-20260709 M3 / D-3: clear-color is one inline `array<f32,4>` column.
   // The earlier 4-scalar form (clearR/G/B/A) was chosen when this was believed
   // to be the only SoA-safe shape; the Transform (pos/quat/scale) and light

package/src/components/cube-camera.ts

@@ -0,0 +1,52 @@
+// @forgeax/engine-render - CubeCamera capture vocabulary.
+//
+// CubeCamera is an ECS capture intent paired with Transform. GPU resources,
+// face views, completed-receipt promotion, and publication remain renderer-owned.
+
+import { defineComponent, type SchemaOf, type ShapeOf } from '@forgeax/engine-ecs';
+import { RenderIntentInvalidError } from '../errors/render';
+
+export const CUBE_CAMERA_UPDATE_ONCE = 0;
+export const CUBE_CAMERA_UPDATE_ON_DEMAND = 1;
+export const CUBE_CAMERA_UPDATE_CONTINUOUS = 2;
+
+export type CubeCameraUpdateIntent = 'once' | 'on-demand' | 'continuous';
+
+export const CUBE_CAMERA_FACE_ORDER = ['+X', '-X', '+Y', '-Y', '+Z', '-Z'] as const;
+export type CubeCameraFace = (typeof CUBE_CAMERA_FACE_ORDER)[number];
+
+export function cubeCameraUpdateIntentFromF32(value: number): CubeCameraUpdateIntent {
+  switch (value) {
+    case CUBE_CAMERA_UPDATE_ONCE:
+      return 'once';
+    case CUBE_CAMERA_UPDATE_ON_DEMAND:
+      return 'on-demand';
+    case CUBE_CAMERA_UPDATE_CONTINUOUS:
+      return 'continuous';
+    default:
+      throw new RenderIntentInvalidError('CubeCamera', value);
+  }
+}
+
+export function cubeCameraUpdateIntentToF32(intent: CubeCameraUpdateIntent): number {
+  switch (intent) {
+    case 'once':
+      return CUBE_CAMERA_UPDATE_ONCE;
+    case 'on-demand':
+      return CUBE_CAMERA_UPDATE_ON_DEMAND;
+    case 'continuous':
+      return CUBE_CAMERA_UPDATE_CONTINUOUS;
+  }
+}
+
+/** ECS declaration for a bounded, transient six-face capture request. */
+export const CubeCamera = defineComponent('CubeCamera', {
+  target: { type: 'shared<RenderTarget>', simulationTransient: true },
+  near: { type: 'f32', default: 0.1 },
+  far: { type: 'f32', default: 100 },
+  updateIntent: { type: 'f32', default: CUBE_CAMERA_UPDATE_ONCE },
+  requestVersion: { type: 'u32', default: 0 },
+  faceBudget: { type: 'u32', default: 1 },
+});
+
+export type CubeCameraData = ShapeOf<SchemaOf<typeof CubeCamera>>;

package/src/components/directional-light.ts

@@ -31,6 +31,14 @@
 // with the shadow atlas owner.
 
 import { defineComponent } from '@forgeax/engine-ecs';
+import { DirectionalShadowFilterValue } from './directional-shadow-filter';
+
+export {
+  type DirectionalShadowFilterLabel,
+  DirectionalShadowFilterValue,
+  type DirectionalShadowQuality,
+  directionalShadowQualityFromF32,
+} from './directional-shadow-filter';
 
 /**
  * Directional light (sun-like infinite light source) with merged shadow
@@ -64,7 +72,9 @@ import { defineComponent } from '@forgeax/engine-ecs';
  *                                  plane (no separate near knob — any value other
  *                                  than the camera near either drops near shadows
  *                                  or wastes cascade-0 resolution).
- *   pcfKernelSize  odd >= 1     — PCF kernel width (default 3)
+ *   shadowFilter   ∈ {pcf1, pcf3, pcf5, pcssMedium, pcssHigh} — closed filter profile (default pcf3)
+ *   shadowAngularRadius ∈ [0.0001, 0.05] radians — PCSS angular light radius (default 0.00465)
+ *   maxPenumbraTexels ∈ [1, 64], finite integer — PCSS search/filter cap (default 32)
  *
  * @example Spawn a single directional light with default shadows:
  *   world.spawn({ component: DirectionalLight, data: {
@@ -85,7 +95,11 @@ import { defineComponent } from '@forgeax/engine-ecs';
  *     color: [1, 1, 1], intensity: 1, // color is [r, g, b]
  *     cascadeCount: 4, splitLambda: 0.75, cascadeBlend: 0.2,
  *     mapSize: 2048, shadowDistance: 200,
+ *     shadowFilter: DirectionalShadowFilterValue.pcssHigh,
+ *     shadowAngularRadius: 0.00465, maxPenumbraTexels: 32,
  *   } });
+ *   // shadowFilter uses the numeric DirectionalShadowFilterValue constant,
+ *   // not the serialized label string 'pcssHigh'.
  *
  * @example 0-light scene must use an unlit shader (standard 0 light = physically correct black):
  *   const world = new World();
@@ -116,5 +130,11 @@ export const DirectionalLight = defineComponent('DirectionalLight', {
   // reach. Default 200 world units (matches UE-style "dynamic shadow
   // distance"; the old farPlane default was 50).
   shadowDistance: { type: 'f32', default: 200 },
-  pcfKernelSize: { type: 'f32', default: 3 },
+  shadowFilter: {
+    type: 'enum',
+    default: DirectionalShadowFilterValue.pcf3,
+    labels: DirectionalShadowFilterValue,
+  },
+  shadowAngularRadius: { type: 'f32', default: 0.00465 },
+  maxPenumbraTexels: { type: 'f32', default: 32 },
 });

package/src/components/directional-shadow-filter.ts

@@ -0,0 +1,57 @@
+// @forgeax/engine-render - closed Directional shadow filter vocabulary.
+
+/** Stable serialized labels for Directional shadow filtering. */
+export const DirectionalShadowFilterValue = Object.freeze({
+  pcf1: 1,
+  pcf3: 2,
+  pcf5: 3,
+  pcssMedium: 4,
+  pcssHigh: 5,
+} as const);
+
+export type DirectionalShadowFilterLabel = keyof typeof DirectionalShadowFilterValue;
+
+/**
+ * Extract-side semantic projection of the serialized Directional filter.
+ * `shadowAngularRadius` is radians and `maxPenumbraTexels` is a finite integer.
+ */
+export type DirectionalShadowQuality =
+  | { readonly kind: 'pcf'; readonly kernel: 1 | 3 | 5 }
+  | {
+      readonly kind: 'pcss';
+      readonly preset: 'medium' | 'high';
+      readonly angularRadiusRadians: number;
+      readonly maxPenumbraTexels: number;
+    };
+
+/** Resolve the closed serialized label to the receiver-facing semantic union. */
+export function directionalShadowQualityFromF32(
+  value: number,
+  angularRadiusRadians: number,
+  maxPenumbraTexels: number,
+): DirectionalShadowQuality | undefined {
+  switch (value) {
+    case DirectionalShadowFilterValue.pcf1:
+      return { kind: 'pcf', kernel: 1 };
+    case DirectionalShadowFilterValue.pcf3:
+      return { kind: 'pcf', kernel: 3 };
+    case DirectionalShadowFilterValue.pcf5:
+      return { kind: 'pcf', kernel: 5 };
+    case DirectionalShadowFilterValue.pcssMedium:
+      return {
+        kind: 'pcss',
+        preset: 'medium',
+        angularRadiusRadians,
+        maxPenumbraTexels,
+      };
+    case DirectionalShadowFilterValue.pcssHigh:
+      return {
+        kind: 'pcss',
+        preset: 'high',
+        angularRadiusRadians,
+        maxPenumbraTexels,
+      };
+    default:
+      return undefined;
+  }
+}

package/src/components/index.ts

@@ -1,5 +1,6 @@
 export * from './atmosphere';
 export * from './camera';
+export * from './cube-camera';
 export * from './directional-light';
 export * from './fog';
 export { Instances, type InstancesData } from './instances';
@@ -17,6 +18,7 @@ export {
   pointShapeFromU32,
 } from './points';
 export { PostProcessParams } from './post-process-params';
+export * from './reflection-probe';
 export {
   SceneInstance,
   type SceneInstanceOverrideRecord,