@forgeax/engine-render 0.1.21 → 0.1.23

package/src/prepare/extended-lighting/spot-modifiers.ts

@@ -0,0 +1,194 @@
+import type { TextureAsset } from '@forgeax/engine-types';
+import { COOKIE_SLICE_SIZE } from './resources';
+
+export interface SpotModifierFactors {
+  readonly brdf: number;
+  readonly range: number;
+  readonly cone: number;
+  readonly ies?: number | undefined;
+  readonly cookie?: number | undefined;
+  readonly shadow: number;
+}
+
+export interface IesCoordinates {
+  readonly azimuth: number;
+  readonly elevation: number;
+}
+
+export interface CookieUv {
+  readonly u: number;
+  readonly v: number;
+}
+
+/**
+ * The fixed GPU representation consumed by the extended-lighting Cookie
+ * array. The matrix is deliberately keyed by Cookie slice rather than by
+ * light: it carries only the source texture aspect correction. The shader
+ * still owns the light-local basis, roll, and outer-cone projection, so one
+ * Cookie can be shared by Spots with different directions or cone angles.
+ */
+export interface CookieProjection {
+  readonly data: Uint8Array;
+  readonly matrix: Float32Array;
+  readonly aspect: number;
+}
+
+const DEG_TO_RAD = Math.PI / 180;
+
+const COOKIE_PROJECTION_CACHE = new WeakMap<TextureAsset, CookieProjection | null>();
+
+function srgbToLinear(value: number): number {
+  return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+}
+
+function clamp01(value: number): number {
+  return Math.min(1, Math.max(0, value));
+}
+
+function sourceChannel(asset: TextureAsset, x: number, y: number, channel: number): number {
+  const offset = (y * asset.shape.extent.width + x) * 4 + channel;
+  const encoded = (asset.data[offset] ?? 0) / 255;
+  return channel < 3 && asset.colorSpace === 'srgb' ? srgbToLinear(encoded) : encoded;
+}
+
+function sampleSourceChannel(asset: TextureAsset, x: number, y: number, channel: number): number {
+  const sourceX = clamp01((x + 0.5) / COOKIE_SLICE_SIZE) * (asset.shape.extent.width - 1);
+  const sourceY = clamp01((y + 0.5) / COOKIE_SLICE_SIZE) * (asset.shape.extent.height - 1);
+  const x0 = Math.floor(sourceX);
+  const y0 = Math.floor(sourceY);
+  const x1 = Math.min(asset.shape.extent.width - 1, x0 + 1);
+  const y1 = Math.min(asset.shape.extent.height - 1, y0 + 1);
+  const tx = sourceX - x0;
+  const ty = sourceY - y0;
+  const top =
+    sourceChannel(asset, x0, y0, channel) * (1 - tx) + sourceChannel(asset, x1, y0, channel) * tx;
+  const bottom =
+    sourceChannel(asset, x0, y1, channel) * (1 - tx) + sourceChannel(asset, x1, y1, channel) * tx;
+  return top * (1 - ty) + bottom * ty;
+}
+
+/**
+ * Project a filterable 2D RGBA Cookie into the renderer's fixed linear
+ * 256x256 array slice. This is a producer-boundary operation and is cached by
+ * the immutable TextureAsset object, so the frame path never decodes or
+ * resamples the source repeatedly.
+ */
+export function prepareCookieProjection(asset: TextureAsset): CookieProjection | undefined {
+  if (COOKIE_PROJECTION_CACHE.has(asset)) {
+    return COOKIE_PROJECTION_CACHE.get(asset) ?? undefined;
+  }
+  const supportedFormat = asset.format === 'rgba8unorm' || asset.format === 'rgba8unorm-srgb';
+  const validDimensions =
+    Number.isSafeInteger(asset.shape.extent.width) &&
+    Number.isSafeInteger(asset.shape.extent.height) &&
+    asset.shape.extent.width > 0 &&
+    asset.shape.extent.height > 0;
+  const validFormatPair =
+    (asset.format === 'rgba8unorm-srgb' && asset.colorSpace === 'srgb') ||
+    (asset.format === 'rgba8unorm' && asset.colorSpace === 'linear');
+  const validPayload =
+    asset.data.byteLength >= asset.shape.extent.width * asset.shape.extent.height * 4;
+  if (!supportedFormat || !validDimensions || !validFormatPair || !validPayload) {
+    COOKIE_PROJECTION_CACHE.set(asset, null);
+    return undefined;
+  }
+
+  const data = new Uint8Array(COOKIE_SLICE_SIZE * COOKIE_SLICE_SIZE * 4);
+  for (let y = 0; y < COOKIE_SLICE_SIZE; y += 1) {
+    for (let x = 0; x < COOKIE_SLICE_SIZE; x += 1) {
+      const target = (y * COOKIE_SLICE_SIZE + x) * 4;
+      data[target] = Math.round(clamp01(sampleSourceChannel(asset, x, y, 0)) * 255);
+      data[target + 1] = Math.round(clamp01(sampleSourceChannel(asset, x, y, 1)) * 255);
+      data[target + 2] = Math.round(clamp01(sampleSourceChannel(asset, x, y, 2)) * 255);
+      // Alpha stays linear and is intentionally preserved: the shader
+      // multiplies sampled RGB by this lane as part of Cookie semantics.
+      data[target + 3] = Math.round(clamp01(sampleSourceChannel(asset, x, y, 3)) * 255);
+    }
+  }
+
+  // Column-major mat4. The shader multiplies the unprojected local
+  // (x/depth, y/depth) pair by this aspect-only matrix, then applies the
+  // Spot's outer-cone tangent and the [0,1] translation. Keeping outerCone
+  // out of this slice-keyed matrix allows one Cookie to be shared by lights.
+  const matrix = new Float32Array(16);
+  matrix[0] = asset.shape.extent.height / asset.shape.extent.width;
+  matrix[5] = 1;
+  matrix[10] = 1;
+  matrix[15] = 1;
+  const projection = {
+    data,
+    matrix,
+    aspect: asset.shape.extent.width / asset.shape.extent.height,
+  };
+  COOKIE_PROJECTION_CACHE.set(asset, projection);
+  return projection;
+}
+
+/** Create the deterministic identity payload used for unused Cookie slices. */
+export function createCookieProjectionMatrixData(count: number): Float32Array {
+  const data = new Float32Array(count * 16);
+  for (let index = 0; index < count; index += 1) {
+    const base = index * 16;
+    data[base] = 1;
+    data[base + 5] = 1;
+    data[base + 10] = 1;
+    data[base + 15] = 1;
+  }
+  return data;
+}
+
+function normalized(vector: ArrayLike<number>): [number, number, number] | undefined {
+  const x = vector[0] ?? 0;
+  const y = vector[1] ?? 0;
+  const z = vector[2] ?? 0;
+  const length = Math.hypot(x, y, z);
+  return length > 0 && Number.isFinite(length) ? [x / length, y / length, z / length] : undefined;
+}
+
+export function spotModifierProduct(factors: SpotModifierFactors): number {
+  return (
+    factors.brdf *
+    factors.range *
+    factors.cone *
+    (factors.ies ?? 1) *
+    (factors.cookie ?? 1) *
+    factors.shadow
+  );
+}
+
+export function projectIesCoordinates(
+  toPoint: ArrayLike<number>,
+  rollDeg: number,
+): IesCoordinates | undefined {
+  const direction = normalized(toPoint);
+  if (direction === undefined || direction[2] >= 0) return undefined;
+  const roll = rollDeg * DEG_TO_RAD;
+  const rolledX = direction[0] * Math.cos(roll) - direction[1] * Math.sin(roll);
+  const rolledY = direction[0] * Math.sin(roll) + direction[1] * Math.cos(roll);
+  return {
+    azimuth: (Math.atan2(rolledY, rolledX) + Math.PI * 2) % (Math.PI * 2),
+    elevation: Math.acos(Math.min(1, Math.max(-1, -direction[2]))) / Math.PI,
+  };
+}
+
+export function projectCookieUv(
+  toPoint: ArrayLike<number>,
+  rollDeg: number,
+  aspect: number,
+  outerConeDeg = 45,
+): CookieUv | undefined {
+  const direction = normalized(toPoint);
+  if (direction === undefined || direction[2] >= 0 || !Number.isFinite(aspect) || aspect <= 0)
+    return undefined;
+  const cone = Math.atan2(Math.hypot(direction[0], direction[1]), -direction[2]);
+  const outerCone = outerConeDeg * DEG_TO_RAD;
+  if (cone > outerCone) return undefined;
+  const roll = rollDeg * DEG_TO_RAD;
+  const x = direction[0] * Math.cos(roll) - direction[1] * Math.sin(roll);
+  const y = direction[0] * Math.sin(roll) + direction[1] * Math.cos(roll);
+  const scale = Math.tan(outerCone);
+  return {
+    u: 0.5 + (x / -direction[2] / scale / aspect) * 0.5,
+    v: 0.5 + (y / -direction[2] / scale) * 0.5,
+  };
+}

package/src/prepare/extended-lighting/state.ts

@@ -0,0 +1,92 @@
+import type { LightResourceUnavailableError } from '../../errors/render';
+import {
+  type LightInspection,
+  lightInspectionIdentity,
+  projectLightInspection,
+} from '../../inspection-types';
+import type { ExtendedLightingResourceCandidate } from './resources';
+
+export type ExtendedLightingResourceStatus = 'empty' | 'candidate' | 'accepted';
+
+export interface ExtendedLightingState {
+  readonly enabled: boolean;
+  readonly generation: number;
+  readonly status: ExtendedLightingResourceStatus;
+  readonly candidate: ExtendedLightingResourceCandidate | undefined;
+  readonly accepted: ExtendedLightingResourceCandidate | undefined;
+  readonly lastKnownGood: ExtendedLightingResourceCandidate | undefined;
+  readonly resourceCount: number;
+  readonly descriptorBytes: number;
+  readonly uploadCount: number;
+  readonly passCount: number;
+  readonly bindGroupCount: number;
+  readonly failure: LightResourceUnavailableError | undefined;
+  readonly failureKeys: readonly string[];
+}
+
+export function createExtendedLightingState(generation: number): ExtendedLightingState {
+  return {
+    enabled: false,
+    generation,
+    status: 'empty',
+    candidate: undefined,
+    accepted: undefined,
+    lastKnownGood: undefined,
+    resourceCount: 0,
+    descriptorBytes: 0,
+    uploadCount: 0,
+    passCount: 0,
+    bindGroupCount: 0,
+    failure: undefined,
+    failureKeys: [],
+  };
+}
+
+export function promoteExtendedLightingCandidate(
+  state: ExtendedLightingState,
+  candidate: ExtendedLightingResourceCandidate | undefined,
+): ExtendedLightingState {
+  if (candidate === undefined) return state;
+  return {
+    ...state,
+    enabled: true,
+    generation: candidate.generation,
+    status: 'accepted',
+    candidate: undefined,
+    accepted: candidate,
+    lastKnownGood: candidate,
+    resourceCount: 4,
+    descriptorBytes: candidate.descriptorBytes,
+    uploadCount: candidate.uploadCount,
+  };
+}
+
+export function recordExtendedLightingFailure(
+  state: ExtendedLightingState,
+  failure: LightResourceUnavailableError,
+): ExtendedLightingState {
+  const key = `${failure.detail.entity}:${failure.detail.feature}:${failure.detail.generation}`;
+  if (state.failureKeys.includes(key)) return state;
+  return {
+    ...state,
+    failure,
+    failureKeys: [...state.failureKeys, key],
+  };
+}
+
+export function projectExtendedLightingInspection(state: ExtendedLightingState): LightInspection {
+  const identity = (candidate: ExtendedLightingResourceCandidate | undefined) =>
+    candidate === undefined
+      ? undefined
+      : lightInspectionIdentity(candidate.topology, candidate.generation);
+  return projectLightInspection({
+    generation: state.generation,
+    candidate: identity(state.candidate),
+    accepted: identity(state.accepted),
+    lastKnownGood: identity(state.lastKnownGood),
+    failure: state.failure?.code,
+    failureKeys: state.failureKeys,
+    resourceCount: state.resourceCount,
+    uploadBytes: state.descriptorBytes,
+  });
+}

package/src/record/__tests__/gpu-timing.unit.test.ts

@@ -0,0 +1,177 @@
+import type { Buffer, QuerySet, RhiCommandEncoder, RhiDevice } from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import { GPU_BUFFER_USAGE_MAP_READ } from '../../gpu-usage';
+import { GpuTimingCapture } from '../gpu-timing';
+
+function timestampDevice(readbackBytes: ArrayBuffer): {
+  readonly device: RhiDevice;
+  readonly encoder: RhiCommandEncoder;
+  readonly resolveQuerySet: ReturnType<typeof vi.fn>;
+  readonly readbackBuffer: Buffer;
+  readonly getMappedRange: ReturnType<typeof vi.fn>;
+  readonly destroyBuffer: ReturnType<typeof vi.fn>;
+  readonly destroyQuerySet: ReturnType<typeof vi.fn>;
+} {
+  const querySet = {} as QuerySet;
+  const resolveBuffer = {} as Buffer;
+  const getMappedRange = vi.fn(() => ok(readbackBytes));
+  const unmap = vi.fn();
+  const readbackBuffer = {
+    mapAsync: vi.fn(async (mode: number) => {
+      expect(mode).toBe(GPU_BUFFER_USAGE_MAP_READ);
+      return ok({
+        getMappedRange,
+        unmap,
+      } as never);
+    }),
+  } as unknown as Buffer;
+  let bufferIndex = 0;
+  const resolveQuerySet = vi.fn(() => ok(undefined));
+  const destroyBuffer = vi.fn(() => ok(undefined));
+  const destroyQuerySet = vi.fn(() => ok(undefined));
+  const encoder = {
+    resolveQuerySet,
+    copyBufferToBuffer: vi.fn(),
+  } as unknown as RhiCommandEncoder;
+  const device = {
+    caps: {
+      backendKind: 'webgpu',
+      compute: true,
+      storageBuffer: true,
+      storageTexture: true,
+      timestampQuery: true,
+      timestampPeriodNanoseconds: 1,
+      indirectDrawing: true,
+      textureCompressionBc: false,
+      textureCompressionEtc2: false,
+      textureCompressionAstc: false,
+      multiDrawIndirect: false,
+      pushConstants: false,
+      textureBindingArray: false,
+      samplerAliasing: true,
+      firstInstanceIndirect: true,
+      rgba16floatRenderable: true,
+      rg11b10ufloatRenderable: true,
+      float32Filterable: true,
+      maxColorAttachments: 8,
+    },
+    createQuerySet: vi.fn(() => ok(querySet)),
+    createBuffer: vi.fn(() => {
+      bufferIndex += 1;
+      return ok(bufferIndex === 1 ? resolveBuffer : readbackBuffer);
+    }),
+    destroyQuerySet,
+    destroyBuffer,
+    queue: { onSubmittedWorkDone: vi.fn(async () => undefined) },
+  } as unknown as RhiDevice;
+  return {
+    device,
+    encoder,
+    resolveQuerySet,
+    readbackBuffer,
+    getMappedRange,
+    destroyBuffer,
+    destroyQuerySet,
+  };
+}
+
+function writeTimestampPair(bytes: ArrayBuffer, index: number, begin: bigint, end: bigint): void {
+  const view = new DataView(bytes);
+  view.setBigUint64(index * 16, begin, true);
+  view.setBigUint64(index * 16 + 8, end, true);
+}
+
+describe('GpuTimingCapture pass descriptor contract', () => {
+  it('resolves real pass pairs without calling command-encoder writeTimestamp', async () => {
+    const bytes = new ArrayBuffer(64 * 8);
+    writeTimestampPair(bytes, 0, 100n, 200n);
+    writeTimestampPair(bytes, 1, 210n, 450n);
+    const { device, encoder, resolveQuerySet } = timestampDevice(bytes);
+    const created = GpuTimingCapture.create(device);
+    expect(created.ok).toBe(true);
+    if (!created.ok || created.value === undefined) return;
+
+    const first = created.value.beginPass('volume-inject', 'compute', 3);
+    const second = created.value.beginPass('volume-integrate', 'raster', 9);
+    expect(first).toMatchObject({ beginningOfPassWriteIndex: 0, endOfPassWriteIndex: 1 });
+    expect(second).toMatchObject({ beginningOfPassWriteIndex: 2, endOfPassWriteIndex: 3 });
+    expect((encoder as unknown as { writeTimestamp?: unknown }).writeTimestamp).toBeUndefined();
+
+    expect(created.value.resolve(encoder).ok).toBe(true);
+    expect(resolveQuerySet).toHaveBeenCalledWith(expect.anything(), 0, 4, expect.anything(), 0);
+    created.value.markSubmitted();
+    await expect(created.value.observation()).resolves.toEqual({
+      status: 'ready',
+      unit: 'ms',
+      frameMs: 0.00035,
+      totalMs: 0.00035,
+      passes: [
+        { name: 'volume-inject', milliseconds: 0.0001 },
+        { name: 'volume-integrate', milliseconds: 0.00024 },
+      ],
+    });
+  });
+
+  it('fails closed when a producer already owns the pass timestamp pair', async () => {
+    const { device, encoder } = timestampDevice(new ArrayBuffer(64 * 8));
+    const created = GpuTimingCapture.create(device);
+    expect(created.ok).toBe(true);
+    if (!created.ok || created.value === undefined) return;
+    expect(created.value.beginPass('volume-inject', 'compute', 0)).toBeDefined();
+    created.value.markOwnerConflict('volume-inject');
+    expect(created.value.resolve(encoder).ok).toBe(true);
+    created.value.markSubmitted();
+    await expect(created.value.observation()).resolves.toEqual({
+      status: 'unavailable',
+      reason: "timestamp pass 'volume-inject' already has producer-owned timestampWrites",
+    });
+  });
+
+  it('disposes query and buffer resources when readback mapping fails', async () => {
+    const { device, encoder, readbackBuffer, destroyBuffer, destroyQuerySet } = timestampDevice(
+      new ArrayBuffer(64 * 8),
+    );
+    const mapAsync = readbackBuffer.mapAsync as unknown as ReturnType<typeof vi.fn>;
+    mapAsync.mockResolvedValue({
+      ok: false,
+      error: { code: 'webgpu-runtime-error' },
+    });
+    const created = GpuTimingCapture.create(device);
+    expect(created.ok).toBe(true);
+    if (!created.ok || created.value === undefined) return;
+
+    expect(created.value.beginPass('volume-inject', 'compute', 0)).toBeDefined();
+    expect(created.value.resolve(encoder).ok).toBe(true);
+    created.value.markSubmitted();
+    await expect(created.value.observation()).resolves.toEqual({
+      status: 'unavailable',
+      reason: 'timestamp readback failed: webgpu-runtime-error',
+    });
+    expect(destroyBuffer).toHaveBeenCalledTimes(2);
+    expect(destroyQuerySet).toHaveBeenCalledTimes(1);
+  });
+
+  it('disposes query and buffer resources when mapped range access fails', async () => {
+    const { device, encoder, getMappedRange, destroyBuffer, destroyQuerySet } = timestampDevice(
+      new ArrayBuffer(64 * 8),
+    );
+    getMappedRange.mockReturnValue({
+      ok: false,
+      error: { code: 'webgpu-runtime-error' },
+    });
+    const created = GpuTimingCapture.create(device);
+    expect(created.ok).toBe(true);
+    if (!created.ok || created.value === undefined) return;
+
+    expect(created.value.beginPass('volume-inject', 'compute', 0)).toBeDefined();
+    expect(created.value.resolve(encoder).ok).toBe(true);
+    created.value.markSubmitted();
+    await expect(created.value.observation()).resolves.toEqual({
+      status: 'unavailable',
+      reason: 'timestamp mapping failed: webgpu-runtime-error',
+    });
+    expect(destroyBuffer).toHaveBeenCalledTimes(2);
+    expect(destroyQuerySet).toHaveBeenCalledTimes(1);
+  });
+});

package/src/record/__tests__/temporal-payload.unit.test.ts

@@ -132,7 +132,6 @@ describe('temporal GPU payloads', () => {
       { point: [], spot: [projector] } as never,
       [projector],
       undefined,
-      undefined,
       0,
     );
     const payload = new Float32Array(uploads[0]?.buffer ?? new ArrayBuffer(0));
@@ -165,6 +164,29 @@ describe('temporal GPU payloads', () => {
     expect(payload[230]).toBe(0);
   });
 
+  it('keeps the accepted previous camera in the temporal ABI', () => {
+    const { queue, uploads } = recordingQueue();
+    const acceptedCamera = [7, 8, 9] as const;
+    const temporal = { ...temporalView(), previousCameraPosition: acceptedCamera };
+    writeViewUbo(
+      queue,
+      {} as Buffer,
+      camera(),
+      {
+        kind: 'directional',
+        direction: vec3.create(0, -1, 0),
+        color: vec3.create(1, 1, 1),
+        intensity: 1,
+      },
+      { point: [], spot: [] } as never,
+      [],
+      temporal as never,
+    );
+
+    const payload = new Float32Array(uploads[0]?.buffer ?? new ArrayBuffer(0));
+    expect(Array.from(payload.slice(232, 236))).toEqual([...acceptedCamera, 1]);
+  });
+
   it('seeds previousWorld on the first frame and uses the submitted snapshot later', () => {
     const first = translatedMatrix(4);
     const previous = translatedMatrix(2);

package/src/record/__tests__/typed-frame-graph-plan.unit.test.ts

@@ -19,6 +19,7 @@ const captureDescriptor = {
 
 type CaptureOverrides = {
   readonly target?: boolean;
+  readonly onSubmitted?: () => void;
   readonly descriptor?: {
     readonly format?: 'rgba16float' | 'rgba8unorm';
     readonly size?: { readonly width: number; readonly height: number };
@@ -74,7 +75,14 @@ function executeCapture(overrides: CaptureOverrides = {}) {
     errorRegistry: { fire: (error: unknown) => errors.push(error) },
     device: { queue: { submit: () => ok(undefined) } },
   } as never;
-  const submitted = executeCompiledFrameGraph(internals, frameState, {} as never, encoder);
+  const submitted = executeCompiledFrameGraph(
+    internals,
+    frameState,
+    {} as never,
+    encoder,
+    undefined,
+    overrides.onSubmitted === undefined ? undefined : { onSubmitted: overrides.onSubmitted },
+  );
   return { submitted, errors, copies };
 }
 
@@ -142,6 +150,17 @@ describe('typed frame graph feature plan authority', () => {
     expect(result.copies).toHaveLength(1);
   });
 
+  it('keeps the submit hook on the successful commit path', () => {
+    let calls = 0;
+    const result = executeCapture({
+      onSubmitted: () => {
+        calls += 1;
+      },
+    });
+    expect(result.submitted).toBe(true);
+    expect(calls).toBe(1);
+  });
+
   it.each([
     [
       'missing same-submit copy / untouched sentinel',