@forgeax/engine-render 0.1.19 → 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-material.ts

@@ -414,10 +414,14 @@ const DEFAULT_STANDARD_TEXTURE_COORDINATES = new Float32Array([
 
 /** Derives the logical-content UV scale for an uploaded material texture. */
 export function materialTextureUvScale(
-  texture: Pick<TextureAsset, 'width' | 'height' | 'format'> | undefined,
+  texture: Pick<TextureAsset, 'shape' | 'format'> | undefined,
 ): readonly [number, number] {
   if (texture === undefined) return [1, 1];
-  return deriveTextureExtent(texture.format, texture.width, texture.height).uvScale;
+  return deriveTextureExtent(
+    texture.format,
+    texture.shape.extent.width,
+    texture.shape.extent.height,
+  ).uvScale;
 }
 
 function materialTextureForField(

package/src/record/render-context.ts

@@ -57,6 +57,7 @@ import type {
   RenderDebugOverlay,
   RenderPipelineContext,
   RenderRecordPhase,
+  VolumetricFogShaderSources,
 } from '../render-contract';
 import type {
   DispatchEntry,
@@ -236,6 +237,8 @@ export interface PipelineState {
   /** Surface route committed by configureSurface for inspection provenance. */
   readonly surfaceProfile?: 'dual-view' | 'raw-only';
   readonly viewBindGroupLayout: BindGroupLayout;
+  /** Device capability gate for the optional SpotLight projector binding. */
+  readonly projectorAvailable?: boolean;
   readonly materialBindGroupLayout: BindGroupLayout;
   readonly meshBindGroupLayout: BindGroupLayout;
   readonly viewUniformBuffer: Buffer;
@@ -302,6 +305,8 @@ export interface RenderSystemInternals extends RenderSystemRuntime {
         label: string,
       ) => RhiRenderPipeline | null)
     | undefined;
+  /** Composed renderer utility sources installed atomically at build-ready. */
+  volumetricFogShaders?: VolumetricFogShaderSources | undefined;
 }
 
 export interface _StandardForwardSceneView {

package/src/record/shadow-pass.ts

@@ -7,7 +7,7 @@ import {
   type RhiQueue,
   type RhiRenderPassEncoder,
 } from '@forgeax/engine-rhi';
-import type { PassSelector } from '@forgeax/engine-types';
+import type { MaterialRenderState, PassSelector } from '@forgeax/engine-types';
 import { GpuBuffer } from '../gpu-resource';
 import {
   GPU_BUFFER_USAGE_COPY_DST,
@@ -81,6 +81,7 @@ function ensureTypedShadowViewBg(
   const { runtime, frameState, pipelineState } = c;
   const shadowSampler = pipelineState.perPassResources.shadowSampler;
   if (shadowSampler === null) return null;
+  const projectorAvailable = pipelineState.projectorAvailable !== false;
   try {
     return getOrCreateFromChain(
       frameState.viewBindGroupCache,
@@ -94,6 +95,9 @@ function ensureTypedShadowViewBg(
         pipelineState.shadowParamsBuffer,
         pipelineState.shadowCasterCascadeBuffer,
         pipelineState.shadowFallbackTextureView,
+        ...(projectorAvailable
+          ? [pipelineState.defaultWhiteTextureView, pipelineState.defaultSampler]
+          : []),
         pipelineState.pointsLinesViewBuffer ?? pipelineState.viewUniformBuffer,
       ],
       variant,
@@ -165,6 +169,21 @@ function ensureTypedShadowViewBg(
                 },
               },
             },
+            ...(projectorAvailable
+              ? [
+                  {
+                    binding: 11,
+                    resource: {
+                      kind: 'textureView' as const,
+                      value: pipelineState.defaultWhiteTextureView,
+                    },
+                  },
+                  {
+                    binding: 12,
+                    resource: { kind: 'sampler' as const, value: pipelineState.defaultSampler },
+                  },
+                ]
+              : []),
           ],
         });
         if (!created.ok) throw created.error;
@@ -181,11 +200,26 @@ function ensureTypedShadowViewBg(
   }
 }
 
-function shadowShaderMap(c: _InternalRenderPipelineContext): ReadonlyMap<number, string> {
-  const shaders = new Map<number, string>();
+interface ShadowDispatch {
+  readonly materialShaderId: string;
+  readonly renderState: MaterialRenderState | undefined;
+}
+
+type ShadowDispatchMap = ReadonlyMap<number, ReadonlyMap<number, ShadowDispatch>>;
+
+function shadowShaderMap(c: _InternalRenderPipelineContext): ShadowDispatchMap {
+  const shaders = new Map<number, Map<number, ShadowDispatch>>();
   for (const entry of c.dispatch) {
     if (entry.tags.LightMode === 'ShadowCaster' && entry.materialShaderId !== undefined) {
-      shaders.set(entry.renderableIndex, entry.materialShaderId);
+      let byMaterial = shaders.get(entry.renderableIndex);
+      if (byMaterial === undefined) {
+        byMaterial = new Map<number, ShadowDispatch>();
+        shaders.set(entry.renderableIndex, byMaterial);
+      }
+      byMaterial.set(entry.materialHandle, {
+        materialShaderId: entry.materialShaderId,
+        renderState: entry.renderState,
+      });
     }
   }
   return shaders;
@@ -488,8 +522,8 @@ export function buildMatchedMaterialHandlesByRenderable(
  * groups (@group 0/1) are already set by the caller; this loop owns @group
  * 2/3 + the vertex/index/pipeline de-dup state. Receives the explicit
  * `_InternalRenderPipelineContext` (`c`) plus the caller-resolved shadow
- * pipeline, mesh bind group, pass-selector match set, and per-renderable
- * custom-caster shader map so no cross-function mutable state is introduced.
+ * pipeline, mesh bind group, pass-selector match set, and per-material
+ * ShadowCaster dispatch map so no cross-function mutable state is introduced.
  */
 function recordShadowCasterDraws(
   c: _InternalRenderPipelineContext,
@@ -497,7 +531,7 @@ function recordShadowCasterDraws(
   shadowPipeline: RenderPipeline,
   shadowMeshBindGroup: BindGroup,
   matchedIndices: Set<number> | null,
-  shadowShaderByRenderableIdx: ReadonlyMap<number, string>,
+  shadowDispatchByRenderableIdx: ShadowDispatchMap,
 ): void {
   const { runtime, pipelineState, validatedOrdered } = c;
   // M-3 / w12: vertexBuffer/indexBuffer state locals migrate to GpuBuffer
@@ -520,41 +554,14 @@ function recordShadowCasterDraws(
     // feat-20260609 M2: skip entities that don't match the pass selector.
     if (matchedIndices !== null && !matchedIndices.has(entry.renderableIndex)) continue;
 
-    // bug-20260619-csm RC-3 (AC-10, D-3): resolve the per-entity shadow
-    // PSO from its ShadowCaster shader id. Default casters keep the
-    // vertex-only `forgeax::default-shadow-caster` PSO bound above; a
-    // material with a custom ShadowCaster shader (cutout alpha-test) gets
-    // its own fragment-carrying PSO so `discard` runs in the depth pass.
-    const entryShadowShaderId = shadowShaderByRenderableIdx.get(entry.renderableIndex);
-    let entryShadowPipeline = shadowPipeline;
     if (entry.source.skin !== undefined) {
       const skinPipeline = skinnedShadowPipeline(c, entry);
       if (skinPipeline === null) continue;
-      entryShadowPipeline = skinPipeline;
-    } else if (
-      entryShadowShaderId !== undefined &&
-      entryShadowShaderId !== SHADOW_CASTER_SHADER_ID
-    ) {
-      // Custom ShadowCaster PSO; same cache path as the default above
-      // (passKind 'shadow-caster'). On a cache miss (async build in
-      // flight / build failure) fall back to the default PSO so the
-      // caster still writes depth rather than dropping its draw.
-      entryShadowPipeline =
-        runtime.getMaterialShaderPipeline?.(
-          entryShadowShaderId,
-          false, // isHdr — shadow depth pass is always LDR
-          undefined, // renderState
-          'triangle-list', // topology — shadow PSO targets triangle-list
-          undefined, // indexFormat
-          undefined, // variantSet — shadow caster has no variant axes
-          'shadow-caster', // passKind
-        ) ?? shadowPipeline;
-    }
-    if (entryShadowPipeline !== shadowLastPipeline && entryShadowPipeline !== null) {
-      shadowPass.setPipeline(entryShadowPipeline);
-      shadowLastPipeline = entryShadowPipeline;
+      if (skinPipeline !== shadowLastPipeline) {
+        shadowPass.setPipeline(skinPipeline);
+        shadowLastPipeline = skinPipeline;
+      }
     }
-
     // feat-20260604-mesh-topology-debug-draw M5 / w14 (AC-09, D-A6): the
     // shadow caster PSO is triangle-list; it only projects triangle faces.
     // line-list / line-strip / point-list meshes have no surface to cast a
@@ -708,6 +715,48 @@ function recordShadowCasterDraws(
       if (sm.topology !== 'triangle-list' && sm.topology !== 'triangle-strip') {
         continue;
       }
+
+      // Resolve the ShadowCaster PSO for the material bound to this submesh.
+      // Built-in materials normally use the shared vertex-only caster, but an
+      // authored `cullMode:'none'`/`frontFace` must still reach that PSO so
+      // two-sided casters (such as the Three.js teapot) populate the atlas
+      // from both faces. Custom ShadowCaster shaders retain their own path.
+      const submeshMaterial = entry.source.materials[sm.materialSlot] ?? entry.source.material;
+      const shadowDispatch = shadowDispatchByRenderableIdx
+        .get(entry.renderableIndex)
+        ?.get(submeshMaterial.materialHandle ?? 0);
+      const entryShadowShaderId = shadowDispatch?.materialShaderId;
+      const entryShadowRenderState = shadowDispatch?.renderState;
+      // A skinned caster's pipeline was selected above together with its
+      // two-binding mesh/palette group. Keep that pairing for every submesh;
+      // resetting to the static shadow pipeline here would bind the skin
+      // group against `pbr-pl` and Dawn rejects the draw at submit time.
+      let entryShadowPipeline =
+        entry.source.skin !== undefined ? shadowLastPipeline : shadowPipeline;
+      if (
+        entry.source.skin === undefined &&
+        entryShadowShaderId !== undefined &&
+        (entryShadowShaderId !== 'forgeax::default-shadow-caster' ||
+          entryShadowRenderState !== undefined)
+      ) {
+        // On a cache miss (async build in flight / build failure), fall back
+        // to the default PSO so the caster still writes depth rather than
+        // dropping its draw.
+        entryShadowPipeline =
+          runtime.getMaterialShaderPipeline?.(
+            entryShadowShaderId,
+            false, // isHdr — shadow depth pass is always LDR
+            entryShadowRenderState,
+            'triangle-list', // topology — shadow PSO targets triangle-list
+            undefined, // indexFormat
+            undefined, // variantSet — shadow caster has no variant axes
+            'shadow-caster', // passKind
+          ) ?? shadowPipeline;
+      }
+      if (entryShadowPipeline !== shadowLastPipeline && entryShadowPipeline !== null) {
+        shadowPass.setPipeline(entryShadowPipeline);
+        shadowLastPipeline = entryShadowPipeline;
+      }
       if (entry.mesh.indexed) {
         shadowPass.drawIndexed(sm.indexCount, shadowInstanceCount, sm.indexOffset, 0, 0);
       } else {