@forgeax/engine-render 0.1.21 → 0.1.23

package/src/record/gpu-timing.ts

@@ -7,10 +7,13 @@ import {
   GPU_BUFFER_USAGE_QUERY_RESOLVE,
 } from '../gpu-usage';
 
-const MAX_VOLUME_PASSES = 4;
-const QUERY_COUNT = MAX_VOLUME_PASSES * 2;
-const QUERY_STRIDE_BYTES = 256;
-const READBACK_BYTES = QUERY_COUNT * QUERY_STRIDE_BYTES;
+// The pass descriptor timestampWrites API needs one pair per actual raster or
+// compute pass. Keep the capture bounded so enabling timing cannot turn into an
+// unbounded query allocation on a pathological graph.
+const MAX_CAPTURE_PASSES = 64;
+const QUERY_COUNT = MAX_CAPTURE_PASSES * 2;
+const QUERY_RESULT_BYTES = 8;
+const READBACK_BYTES = QUERY_COUNT * QUERY_RESULT_BYTES;
 const PASS_NAMES = [
   'volume-inject',
   'volume-integrate',
@@ -18,11 +21,29 @@ const PASS_NAMES = [
   'volume-composite',
 ] as const;
 
+type TimedPassKind = 'raster' | 'compute';
+
+interface TimedPass {
+  readonly name: string;
+  readonly kind: TimedPassKind;
+  readonly executionIndex: number;
+  readonly queryIndex: number;
+}
+
+export interface GpuTimingPassTimestampWrites {
+  readonly querySet: QuerySet;
+  readonly beginningOfPassWriteIndex: number;
+  readonly endOfPassWriteIndex: number;
+}
+
 export type VolumeTimingObservation =
   | {
       readonly status: 'ready';
       readonly unit: 'ms';
+      /** Time covered by authored volumetric passes only. */
       readonly totalMs: number;
+      /** Time from the first graph pass marker to the final graph marker. */
+      readonly frameMs: number;
       readonly passes: readonly { readonly name: string; readonly milliseconds: number }[];
     }
   | {
@@ -34,11 +55,7 @@ function unavailable(reason: string): VolumeTimingObservation {
   return Object.freeze({ status: 'unavailable', reason });
 }
 
-export interface VolumeTimingTimestampWrites {
-  readonly querySet: QuerySet;
-  readonly beginningOfPassWriteIndex: number;
-  readonly endOfPassWriteIndex: number;
-}
+export type VolumeTimingTimestampWrites = GpuTimingPassTimestampWrites;
 
 /**
  * Renderer-owned timestamp capture for the authored volume graph. Query
@@ -52,12 +69,13 @@ export class GpuTimingCapture {
   readonly #resolveBuffer: Buffer;
   readonly #readbackBuffer: Buffer;
   readonly #periodNanoseconds: number;
-  readonly #started = new Map<string, number>();
-  readonly #finished = new Map<string, number>();
+  readonly #passes: TimedPass[] = [];
   #resolved = false;
   #submitted = false;
   #discarded = false;
   #disposed = false;
+  #frameStarted = false;
+  #unavailableReason: string | undefined;
   #observation: Promise<VolumeTimingObservation> | undefined;
 
   private constructor(
@@ -115,11 +133,32 @@ export class GpuTimingCapture {
     );
   }
 
-  recordPass(name: string): VolumeTimingTimestampWrites | undefined {
-    const index = PASS_NAMES.indexOf(name as (typeof PASS_NAMES)[number]);
-    if (index < 0 || this.#started.has(name) || this.#discarded) return undefined;
-    this.#started.set(name, index);
-    this.#finished.set(name, index);
+  /**
+   * Reserve a query pair for a real render/compute pass. The pair is later
+   * attached to that pass's descriptor by the render-graph instrumentation
+   * seam; no command-encoder timestamp method is used.
+   */
+  beginPass(
+    name: string,
+    kind: TimedPassKind,
+    executionIndex: number,
+  ): GpuTimingPassTimestampWrites | undefined {
+    if (this.#unavailableReason !== undefined || this.#resolved || this.#discarded) return;
+    const existing = this.#passes.find((pass) => pass.executionIndex === executionIndex);
+    if (existing !== undefined) {
+      return {
+        querySet: this.#querySet,
+        beginningOfPassWriteIndex: existing.queryIndex * 2,
+        endOfPassWriteIndex: existing.queryIndex * 2 + 1,
+      };
+    }
+    if (this.#passes.length >= MAX_CAPTURE_PASSES) {
+      this.#unavailableReason = `timestamp capture exceeded ${MAX_CAPTURE_PASSES} pass pairs`;
+      return;
+    }
+    const index = this.#passes.length;
+    this.#passes.push({ name, kind, executionIndex, queryIndex: index });
+    this.#frameStarted = true;
     return {
       querySet: this.#querySet,
       beginningOfPassWriteIndex: index * 2,
@@ -127,20 +166,22 @@ export class GpuTimingCapture {
     };
   }
 
-  skipPass(name: string): void {
-    this.#started.delete(name);
-    this.#finished.delete(name);
+  /** An existing producer-owned timestamp pair cannot be overwritten. */
+  markOwnerConflict(name: string): void {
+    if (this.#unavailableReason === undefined) {
+      this.#unavailableReason = `timestamp pass '${name}' already has producer-owned timestampWrites`;
+    }
   }
 
   resolve(encoder: RhiCommandEncoder): Result<void, RhiError> {
-    if (this.#started.size === 0) {
+    if (!this.#frameStarted || this.#unavailableReason !== undefined || this.#passes.length === 0) {
       this.#resolved = true;
       return ok(undefined);
     }
     const resolved = encoder.resolveQuerySet(
       this.#querySet,
       0,
-      QUERY_COUNT,
+      this.#passes.length * 2,
       this.#resolveBuffer,
       0,
     );
@@ -164,9 +205,20 @@ export class GpuTimingCapture {
 
   observation(): Promise<VolumeTimingObservation> {
     if (this.#observation !== undefined) return this.#observation;
-    if (this.#discarded || !this.#resolved || !this.#submitted || this.#started.size === 0) {
+    // Frame markers are the generic renderer timing lane. The optional volume
+    // markers enrich that same observation when authored fog passes exist, but
+    // a Standard graph without fog must still publish frame timing.
+    if (
+      this.#discarded ||
+      !this.#resolved ||
+      !this.#submitted ||
+      !this.#frameStarted ||
+      this.#unavailableReason !== undefined
+    ) {
       this.#observation = Promise.resolve(
-        unavailable('timestamp capture did not reach an accepted volume submit'),
+        unavailable(
+          this.#unavailableReason ?? 'timestamp capture did not reach an accepted render submit',
+        ),
       );
       this.#dispose();
       return this.#observation;
@@ -174,47 +226,59 @@ export class GpuTimingCapture {
     this.#observation = this.#readbackBuffer
       .mapAsync(GPU_BUFFER_USAGE_MAP_READ)
       .then((mapped) => {
-        if (!mapped.ok) return unavailable(`timestamp readback failed: ${mapped.error.code}`);
+        if (!mapped.ok) {
+          this.#dispose();
+          return unavailable(`timestamp readback failed: ${mapped.error.code}`);
+        }
         const range = mapped.value.getMappedRange();
         if (!range.ok) {
           mapped.value.unmap();
+          this.#dispose();
           return unavailable(`timestamp mapping failed: ${range.error.code}`);
         }
         const values = new DataView(range.value);
-        const decoded = [...this.#finished.entries()]
-          .sort((a, b) => a[1] - b[1])
-          .map(([name, index]) => ({
-            name,
-            begin: values.getBigUint64(index * 2 * QUERY_STRIDE_BYTES, true),
-            end: values.getBigUint64((index * 2 + 1) * QUERY_STRIDE_BYTES, true),
-          }));
-        if (decoded.some(({ end, begin }) => end < begin)) {
+        const decoded = this.#passes.map((pass, index) => ({
+          name: pass.name,
+          kind: pass.kind,
+          begin: values.getBigUint64(index * 2 * QUERY_RESULT_BYTES, true),
+          end: values.getBigUint64((index * 2 + 1) * QUERY_RESULT_BYTES, true),
+        }));
+        const frameBegin = decoded[0]?.begin;
+        const frameEnd = decoded[decoded.length - 1]?.end;
+        if (
+          frameBegin === undefined ||
+          frameEnd === undefined ||
+          frameEnd <= frameBegin ||
+          decoded.some(({ end, begin }) => end < begin)
+        ) {
           mapped.value.unmap();
           this.#dispose();
-          return unavailable('timestamp query returned an end before its begin');
+          return unavailable('timestamp query returned a non-positive frame interval');
         }
-        const passes = decoded.map(({ name, begin, end }) => ({
+        const volumeDecoded = decoded.filter(({ name }) =>
+          PASS_NAMES.includes(name as (typeof PASS_NAMES)[number]),
+        );
+        const passes = volumeDecoded.map(({ name, begin, end }) => ({
           name,
           milliseconds: (Number(end - begin) * this.#periodNanoseconds) / 1_000_000,
         }));
-        const firstBegin = decoded.reduce(
-          (first, sample) => (sample.begin < first ? sample.begin : first),
-          decoded[0]?.begin ?? 0n,
-        );
-        const lastEnd = decoded.reduce(
-          (last, sample) => (sample.end > last ? sample.end : last),
-          decoded[0]?.end ?? 0n,
-        );
-        const totalMs = (Number(lastEnd - firstBegin) * this.#periodNanoseconds) / 1_000_000;
+        const frameMs = (Number(frameEnd - frameBegin) * this.#periodNanoseconds) / 1_000_000;
+        const firstBegin = volumeDecoded[0]?.begin;
+        const lastEnd = volumeDecoded[volumeDecoded.length - 1]?.end;
+        const totalMs =
+          firstBegin === undefined || lastEnd === undefined
+            ? 0
+            : (Number(lastEnd - firstBegin) * this.#periodNanoseconds) / 1_000_000;
         mapped.value.unmap();
         this.#dispose();
         if (
+          !Number.isFinite(frameMs) ||
           !Number.isFinite(totalMs) ||
           passes.some((pass) => !Number.isFinite(pass.milliseconds))
         ) {
           return unavailable('timestamp query returned a non-finite duration');
         }
-        return Object.freeze({ status: 'ready', unit: 'ms', totalMs, passes });
+        return Object.freeze({ status: 'ready', unit: 'ms', totalMs, frameMs, passes });
       })
       .catch((cause: unknown) => {
         this.#dispose();

package/src/record/helpers.ts

@@ -71,64 +71,6 @@ export function warnMultiLightDirectional(
   }
 }
 
-/**
- * feat-20260608-multi-light-warn-once M3: warn-once latch for point light
- * N>4 overrun (first-slice cap). Fires at most once per RenderSystem
- * lifetime.
- */
-export function warnMultiLightPoint(
-  frameState: Pick<RenderFrameState, 'warnedMultiLightPoint'>,
-  pointCount: number,
-  envOverride?: { env?: { NODE_ENV?: string } },
-): void {
-  if (!frameState.warnedMultiLightPoint && pointCount > 4) {
-    frameState.warnedMultiLightPoint = true;
-    const env =
-      envOverride ?? (globalThis as { process?: { env?: { NODE_ENV?: string } } }).process;
-    if (env?.env?.NODE_ENV !== 'production') {
-      console.warn(
-        '[forgeax] render-system-multi-light point: at most 4 entities (got N=' +
-          pointCount +
-          '). First 4 used; rest dropped.',
-        {
-          code: 'render-system-multi-light',
-          expected: 'at most 4 point',
-          detail: { type: 'point', got: pointCount },
-        },
-      );
-    }
-  }
-}
-
-/**
- * feat-20260608-multi-light-warn-once M3: warn-once latch for spot light
- * N>4 overrun (first-slice cap). Fires at most once per RenderSystem
- * lifetime.
- */
-export function warnMultiLightSpot(
-  frameState: Pick<RenderFrameState, 'warnedMultiLightSpot'>,
-  spotCount: number,
-  envOverride?: { env?: { NODE_ENV?: string } },
-): void {
-  if (!frameState.warnedMultiLightSpot && spotCount > 4) {
-    frameState.warnedMultiLightSpot = true;
-    const env =
-      envOverride ?? (globalThis as { process?: { env?: { NODE_ENV?: string } } }).process;
-    if (env?.env?.NODE_ENV !== 'production') {
-      console.warn(
-        '[forgeax] render-system-multi-light spot: at most 4 entities (got N=' +
-          spotCount +
-          '). First 4 used; rest dropped.',
-        {
-          code: 'render-system-multi-light',
-          expected: 'at most 4 spot',
-          detail: { type: 'spot', got: spotCount },
-        },
-      );
-    }
-  }
-}
-
 /**
  * feat-20260630-equirect-kind-internalized-ibl-declarative-skyligh M3 / w19:
  * once-warn for >1 Skylight entity (first archetype hit wins). Fires at most