@forgeax/engine-render 0.1.7 → 0.1.20

package/src/record/gpu-timing.ts

@@ -0,0 +1,224 @@
+import type { Buffer, QuerySet, RhiCommandEncoder, RhiDevice, RhiError } from '@forgeax/engine-rhi';
+import { ok, type Result } from '@forgeax/engine-types';
+import {
+  GPU_BUFFER_USAGE_COPY_DST,
+  GPU_BUFFER_USAGE_COPY_SRC,
+  GPU_BUFFER_USAGE_MAP_READ,
+  GPU_BUFFER_USAGE_QUERY_RESOLVE,
+} from '../gpu-usage';
+
+const MAX_VOLUME_PASSES = 4;
+const QUERY_COUNT = MAX_VOLUME_PASSES * 2;
+const QUERY_RESULT_BYTES = 8;
+const READBACK_BYTES = QUERY_COUNT * QUERY_RESULT_BYTES;
+const PASS_NAMES = [
+  'volume-inject',
+  'volume-integrate',
+  'volume-temporal',
+  'volume-composite',
+] as const;
+
+export type VolumeTimingObservation =
+  | {
+      readonly status: 'ready';
+      readonly unit: 'ms';
+      readonly totalMs: number;
+      readonly passes: readonly { readonly name: string; readonly milliseconds: number }[];
+    }
+  | {
+      readonly status: 'unavailable';
+      readonly reason: string;
+    };
+
+function unavailable(reason: string): VolumeTimingObservation {
+  return Object.freeze({ status: 'unavailable', reason });
+}
+
+/**
+ * Renderer-owned timestamp capture for the authored volume graph. Query
+ * resources are private to one accepted submit and never cross the receipt
+ * boundary. This publishes raw renderer timings; a benchmark runner owns
+ * runner class, frame-count, and threshold qualification.
+ */
+export class GpuTimingCapture {
+  readonly #device: RhiDevice;
+  readonly #querySet: QuerySet;
+  readonly #resolveBuffer: Buffer;
+  readonly #readbackBuffer: Buffer;
+  readonly #periodNanoseconds: number;
+  readonly #started = new Map<string, number>();
+  readonly #finished = new Map<string, number>();
+  #resolved = false;
+  #submitted = false;
+  #discarded = false;
+  #disposed = false;
+  #observation: Promise<VolumeTimingObservation> | undefined;
+
+  private constructor(
+    device: RhiDevice,
+    querySet: QuerySet,
+    resolveBuffer: Buffer,
+    readbackBuffer: Buffer,
+    periodNanoseconds: number,
+  ) {
+    this.#device = device;
+    this.#querySet = querySet;
+    this.#resolveBuffer = resolveBuffer;
+    this.#readbackBuffer = readbackBuffer;
+    this.#periodNanoseconds = periodNanoseconds;
+  }
+
+  static create(device: RhiDevice): Result<GpuTimingCapture | undefined, RhiError> {
+    const period = device.caps.timestampPeriodNanoseconds;
+    if (!device.caps.timestampQuery || period === null || !Number.isFinite(period) || period <= 0) {
+      return ok(undefined);
+    }
+    const querySet = device.createQuerySet({
+      label: 'volume-timing',
+      type: 'timestamp',
+      count: QUERY_COUNT,
+    });
+    if (!querySet.ok) return querySet;
+    const resolveBuffer = device.createBuffer({
+      label: 'volume-timing.resolve',
+      size: READBACK_BYTES,
+      usage: GPU_BUFFER_USAGE_QUERY_RESOLVE | GPU_BUFFER_USAGE_COPY_SRC,
+    });
+    if (!resolveBuffer.ok) {
+      device.destroyQuerySet(querySet.value);
+      return resolveBuffer;
+    }
+    const readbackBuffer = device.createBuffer({
+      label: 'volume-timing.readback',
+      size: READBACK_BYTES,
+      usage: GPU_BUFFER_USAGE_MAP_READ | GPU_BUFFER_USAGE_COPY_DST,
+    });
+    if (!readbackBuffer.ok) {
+      device.destroyBuffer(resolveBuffer.value);
+      device.destroyQuerySet(querySet.value);
+      return readbackBuffer;
+    }
+    return ok(
+      new GpuTimingCapture(
+        device,
+        querySet.value,
+        resolveBuffer.value,
+        readbackBuffer.value,
+        period,
+      ),
+    );
+  }
+
+  beforePass(name: string, encoder: RhiCommandEncoder): void {
+    const index = PASS_NAMES.indexOf(name as (typeof PASS_NAMES)[number]);
+    if (index < 0 || this.#started.has(name)) return;
+    this.#started.set(name, index);
+    encoder.writeTimestamp(this.#querySet, index * 2);
+  }
+
+  afterPass(name: string, encoder: RhiCommandEncoder): void {
+    const index = this.#started.get(name);
+    if (index === undefined || this.#finished.has(name)) return;
+    this.#finished.set(name, index);
+    encoder.writeTimestamp(this.#querySet, index * 2 + 1);
+  }
+
+  resolve(encoder: RhiCommandEncoder): Result<void, RhiError> {
+    if (this.#started.size === 0) {
+      this.#resolved = true;
+      return ok(undefined);
+    }
+    const resolved = encoder.resolveQuerySet(
+      this.#querySet,
+      0,
+      QUERY_COUNT,
+      this.#resolveBuffer,
+      0,
+    );
+    if (!resolved.ok) return resolved;
+    encoder.copyBufferToBuffer(this.#resolveBuffer, this.#readbackBuffer, READBACK_BYTES);
+    this.#resolved = true;
+    return ok(undefined);
+  }
+
+  markSubmitted(): void {
+    if (!this.#discarded) this.#submitted = true;
+  }
+
+  discard(): void {
+    if (this.#discarded) return;
+    this.#discarded = true;
+    this.#resolved = true;
+    this.#submitted = false;
+    this.#dispose();
+  }
+
+  observation(): Promise<VolumeTimingObservation> {
+    if (this.#observation !== undefined) return this.#observation;
+    if (this.#discarded || !this.#resolved || !this.#submitted || this.#started.size === 0) {
+      this.#observation = Promise.resolve(
+        unavailable('timestamp capture did not reach an accepted volume submit'),
+      );
+      this.#dispose();
+      return this.#observation;
+    }
+    this.#observation = this.#readbackBuffer
+      .mapAsync(GPU_BUFFER_USAGE_MAP_READ)
+      .then((mapped) => {
+        if (!mapped.ok) return unavailable(`timestamp readback failed: ${mapped.error.code}`);
+        const range = mapped.value.getMappedRange();
+        if (!range.ok) {
+          mapped.value.unmap();
+          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_RESULT_BYTES, true),
+            end: values.getBigUint64((index * 2 + 1) * QUERY_RESULT_BYTES, true),
+          }));
+        if (decoded.some(({ end, begin }) => end < begin)) {
+          mapped.value.unmap();
+          this.#dispose();
+          return unavailable('timestamp query returned an end before its begin');
+        }
+        const passes = decoded.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;
+        mapped.value.unmap();
+        this.#dispose();
+        if (
+          !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 });
+      })
+      .catch((cause: unknown) => {
+        this.#dispose();
+        return unavailable(`timestamp readback failed: ${String(cause)}`);
+      });
+    return this.#observation;
+  }
+
+  #dispose(): void {
+    if (this.#disposed) return;
+    this.#disposed = true;
+    this.#device.destroyBuffer(this.#resolveBuffer);
+    this.#device.destroyBuffer(this.#readbackBuffer);
+    this.#device.destroyQuerySet(this.#querySet);
+  }
+}

package/src/record/main-pass-geometry.ts

@@ -57,7 +57,7 @@ type GeometryBindingState = {
 
 type MaterialPipelineLookup = {
   readonly materialShaderId: string;
-  readonly tonemapActive: boolean;
+  readonly isHdrTarget: boolean;
   readonly renderStateKey: string;
   readonly topology: PrimitiveTopology;
   readonly indexFormat: 'uint16' | 'uint32';
@@ -71,6 +71,27 @@ type MaterialPipelineLookup = {
 
 type GeometryRecordProfileSegment = 'material-bind-groups' | 'pipeline-selection' | 'draw-submit';
 
+type GeometryRenderState = ReturnType<typeof geometryRenderStateForTopology>;
+
+/**
+ * Resolve the depth contract for a geometry pass without changing the base
+ * material state. Temporal scene-data shares the main pass depth attachment:
+ * it is read-only and accepts the equal depth produced by the unjittered
+ * temporal projection, while still rejecting fragments behind the visible
+ * surface.
+ */
+export function geometryRenderStateForPass(
+  base: GeometryRenderState,
+  passKind: PassKind,
+): GeometryRenderState {
+  if (passKind !== 'temporal') return base;
+  return {
+    ...base,
+    depthWriteEnabled: false,
+    depthCompare: 'less-equal' as const,
+  };
+}
+
 function geometryRecordPhase(
   passKind: PassKind,
   segment: GeometryRecordProfileSegment,
@@ -178,6 +199,12 @@ export function recordGeometryDraws(
     viewBindGroup,
   } = c;
   const colorFormatOverride = c.transparentColorFormat as GPUTextureFormat | undefined;
+  // A no-tone frame may still render into the graph-owned rgba16float target
+  // (the linear-LDR route). Shader variants must follow the attachment's
+  // numeric domain rather than the camera's tone-map switch, otherwise the
+  // LDR/OETF fragment entry point is encoded once here and again by the
+  // output transform.
+  const isHdrTarget = tonemapActive || colorFormatOverride === 'rgba16float';
   let lastVertexBuffer: GpuBuffer | null = null;
   let lastIndexBuffer: GpuBuffer | null = null;
   const bindingState: GeometryBindingState = {
@@ -226,7 +253,7 @@ export function recordGeometryDraws(
     if (cachedLookups !== undefined) {
       for (const cached of cachedLookups) {
         if (
-          cached.tonemapActive === tonemapActive &&
+          cached.isHdrTarget === isHdrTarget &&
           cached.renderStateKey === renderStateKey &&
           cached.topology === topology &&
           cached.indexFormat === indexFormat &&
@@ -240,10 +267,11 @@ export function recordGeometryDraws(
         }
       }
     }
-    const resolvedVariantSetResult = variantSetFromVertexLayoutProjection(
-      layoutProjection,
-      variantSet,
-    );
+    const resolvedVariantSetResult =
+      variantSet === undefined &&
+      (materialShaderId === 'forgeax::sprite' || materialShaderId === 'forgeax::sprite-lit')
+        ? ({ ok: true, value: undefined } as const)
+        : variantSetFromVertexLayoutProjection(layoutProjection, variantSet);
     if (!resolvedVariantSetResult.ok) {
       runtime.errorRegistry.fire(resolvedVariantSetResult.error);
       return null;
@@ -252,7 +280,7 @@ export function recordGeometryDraws(
     const resolvePipeline = () =>
       runtime.getMaterialShaderPipeline?.(
         materialShaderId,
-        tonemapActive,
+        isHdrTarget,
         renderState,
         topology,
         indexFormat,
@@ -270,25 +298,37 @@ export function recordGeometryDraws(
       profilePhase === undefined
         ? resolvePipeline()
         : profileGeometrySegment(c, passKind, 'pipeline-selection', resolvePipeline);
-    const nextLookup: MaterialPipelineLookup = {
-      materialShaderId,
-      tonemapActive,
-      renderStateKey,
-      topology,
-      indexFormat,
-      variantSet,
-      passKind,
-      layoutProjection,
-      sampleCount,
-      colorFormatOverride: colorFormat,
-      handle,
-    };
-    if (shaderLookupCache === undefined) {
-      materialPipelineLookupCache.set(materialShaderId, new Map([[renderStateKey, [nextLookup]]]));
-    } else if (cachedLookups === undefined) {
-      shaderLookupCache.set(renderStateKey, [nextLookup]);
-    } else {
-      cachedLookups.push(nextLookup);
+    // A null handle is a transient async-build signal (`rhi-not-available`),
+    // not a stable pipeline result. Do not memoize it in this frame's lookup:
+    // caching the first pending lookup would turn a one-frame shader warm-up
+    // into a permanent skip for every later frame in a tight smoke loop. The
+    // owning runtime cache remains the SSOT; retrying here is bounded by the
+    // existing per-frame draw path and preserves the explicit skip-draw
+    // recovery while the pipeline becomes ready.
+    if (handle !== null) {
+      const nextLookup: MaterialPipelineLookup = {
+        materialShaderId,
+        isHdrTarget,
+        renderStateKey,
+        topology,
+        indexFormat,
+        variantSet,
+        passKind,
+        layoutProjection,
+        sampleCount,
+        colorFormatOverride: colorFormat,
+        handle,
+      };
+      if (shaderLookupCache === undefined) {
+        materialPipelineLookupCache.set(
+          materialShaderId,
+          new Map([[renderStateKey, [nextLookup]]]),
+        );
+      } else if (cachedLookups === undefined) {
+        shaderLookupCache.set(renderStateKey, [nextLookup]);
+      } else {
+        cachedLookups.push(nextLookup);
+      }
     }
     return handle;
   };
@@ -506,7 +546,7 @@ export function recordGeometryDraws(
       skinResources !== null && skinVariantSetResult.ok
         ? (runtime.getMaterialShaderPipeline?.(
             SKIN_MATERIAL_SHADER_ID,
-            tonemapActive,
+            isHdrTarget,
             entry.source.material.renderState,
             entry.mesh.submeshes[0]?.topology ?? 'triangle-list',
             entry.mesh.indexFormat,
@@ -727,7 +767,7 @@ export function recordGeometryDraws(
       // Preserve the dedicated sprite-pass state when the linear-LDR graph
       // routes a sprite through this generic geometry path. Negative scale
       // flips winding, so back-face culling would erase the quad.
-      const pipelineRenderState = isSpriteShader
+      const basePipelineRenderState = isSpriteShader
         ? {
             ...submeshMaterial.renderState,
             depthWriteEnabled: false,
@@ -736,6 +776,7 @@ export function recordGeometryDraws(
             blend: submeshMaterial.renderState?.blend ?? SPRITE_PREMULTIPLIED_ALPHA_BLEND,
           }
         : geometryRenderStateForTopology(smTopology, submeshMaterial.renderState);
+      const pipelineRenderState = geometryRenderStateForPass(basePipelineRenderState, passKind);
       let smPipelineHandle: typeof pipelineState.unlitPipeline;
       if (smMaterialShaderId === undefined || smMaterialShaderId === 'forgeax::default-unlit') {
         const unlitShaderId = smMaterialShaderId ?? 'forgeax::default-unlit';
@@ -763,7 +804,7 @@ export function recordGeometryDraws(
         smPipelineHandle =
           unlitRsp ??
           (colorFormatOverride === undefined
-            ? selectGeometryPipeline(pipelineState, tonemapActive, msaaActive)
+            ? selectGeometryPipeline(pipelineState, isHdrTarget, msaaActive)
             : null);
       } else if (smMaterialShaderId !== undefined) {
         // feat-20260609 M4.5 / w38 (D-11): the variantSet handed to
@@ -793,18 +834,23 @@ export function recordGeometryDraws(
             ? ''
             : 'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true'
           : 'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true';
-        const authoredVariantSet =
-          isSpriteShader && entry.source.spriteInstances !== undefined ? '' : entry.variantSet;
-        const variantSet =
-          authoredVariantSet === undefined
+        // Sprite's base request must retain the boot-selected artifact. Only
+        // SpriteInstances uses the explicit empty key for the
+        // PER_INSTANCE_REGION=true variant; synthesizing the generic PBR
+        // capability axes for a base sprite would invent a lazy module label
+        // that has no boot seed and skip the first HDR draw.
+        const variantSet = isSpriteShader
+          ? smMaterialShaderId === 'forgeax::sprite' && entry.source.spriteInstances !== undefined
+            ? ''
+            : undefined
+          : entry.variantSet === undefined
             ? capabilityVariantSet
             : capabilityVariantSet === ''
-              ? authoredVariantSet
-              : `${capabilityVariantSet}+${authoredVariantSet}`;
-        const projectionVariantSetResult = variantSetFromVertexLayoutProjection(
-          entry.mesh.layoutProjection,
-          variantSet,
-        );
+              ? entry.variantSet
+              : `${capabilityVariantSet}+${entry.variantSet}`;
+        const projectionVariantSetResult = isSpriteShader
+          ? ({ ok: true, value: variantSet } as const)
+          : variantSetFromVertexLayoutProjection(entry.mesh.layoutProjection, variantSet);
         if (!projectionVariantSetResult.ok) {
           runtime.errorRegistry.fire(projectionVariantSetResult.error);
           continue;
@@ -833,7 +879,7 @@ export function recordGeometryDraws(
         // fires on per-submesh topology variance miss.
         smPipelineHandle = cachedPipeline ?? null;
       } else {
-        smPipelineHandle = selectGeometryPipeline(pipelineState, tonemapActive, msaaActive);
+        smPipelineHandle = selectGeometryPipeline(pipelineState, isHdrTarget, msaaActive);
       }
 
       if (smPipelineHandle === null) {