@forgeax/engine-render 0.1.27 → 0.1.29

package/src/extract/gpu-driven.ts

@@ -1,12 +1,17 @@
+import { deriveVertexLayoutProjection } from '@forgeax/engine-geometry';
 import type { MaterialShaderArtifact } from '@forgeax/engine-shader';
 import type { MeshAsset } from '@forgeax/engine-types';
+import { GpuDrivenPreparationError } from '../errors/gpu-driven';
 import {
   type GpuDrivenDrawRange,
+  type GpuDrivenGeometryReceipt,
+  type GpuDrivenSkinReceipt,
   type PreparedGpuDrivenDraw,
   type PrepareGpuDrivenDrawInput,
   prepareGpuDrivenDraw,
 } from '../gpu-driven/prepared-draw';
-import type { MaterialSnapshot } from '../render-system-extract';
+import { isStandardPbrMaterialShader } from '../pbr-pipeline';
+import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
 
 export {
   GpuDrivenPreparationError,
@@ -24,6 +29,8 @@ export {
 } from '../gpu-driven/prepared-draw';
 
 export interface GpuDrivenDrawSnapshot {
+  /** Stable source submesh identity; compact draw arrays must not renumber it. */
+  readonly drawItemIndex?: number;
   readonly kind: GpuDrivenDrawRange['kind'];
   readonly first: GpuDrivenDrawRange['first'];
   readonly count: GpuDrivenDrawRange['count'];
@@ -34,6 +41,43 @@ export interface GpuDrivenDrawSnapshot {
   readonly materialResourceClass: string;
   /** Producer-owned prepared ABI facts used by the PBR GPU lane. */
   readonly prepared?: PreparedGpuDrivenDraw;
+  /** Structured producer failure; record never interprets an incomplete draw. */
+  readonly preparationError?: GpuDrivenPreparationError;
+  /** Optional lower-detail ranges aligned with the snapshot's LOD levels. */
+  readonly lodRanges?: readonly {
+    readonly first: number;
+    readonly count: number;
+    readonly baseVertex: number;
+  }[];
+  /** Optional camera-projected height supplied by direct GPU-view evidence. */
+  readonly projectedHeight?: number;
+}
+
+/** Stable ownership key for one entity/material/concrete GPU draw item. */
+export function gpuDrivenDrawKey(
+  worldEntity: number,
+  materialHandle: number,
+  drawItemIndex: number,
+): string {
+  return `${worldEntity}:${materialHandle}:${drawItemIndex}`;
+}
+
+/** Stable ShadowCaster ownership key: entity, concrete GPU draw item, and pass. */
+export function gpuDrivenShadowDrawKey(
+  worldEntity: number,
+  materialHandle: number,
+  drawItemIndex: number,
+  passIndex: number,
+): string {
+  return `${gpuDrivenDrawKey(worldEntity, materialHandle, drawItemIndex)}:${passIndex}`;
+}
+
+/** Resolve the producer-owned source identity for one compact draw snapshot. */
+export function gpuDrivenSourceDrawItemIndex(
+  draw: GpuDrivenDrawSnapshot,
+  compactIndex: number,
+): number {
+  return draw.drawItemIndex ?? compactIndex;
 }
 
 /**
@@ -68,15 +112,37 @@ export function gpuDrivenMaterialResourceClass(material: MaterialSnapshot): stri
   return JSON.stringify({
     textures,
     samplers,
-    video: [...(material.videoTextureFields?.keys() ?? [])].sort(),
   });
 }
 
+/**
+ * Dynamic renderer-local targets and video frames are owned by their host
+ * producers and do not have a stable scene-index binding in this feature.
+ * Keep them on the explicit CPU semantic lane instead of inventing a
+ * per-instance resource table or grouping opaque source objects by shape.
+ */
+function hasCpuOnlyMaterialResources(material: MaterialSnapshot): boolean {
+  return (material.textureSources?.size ?? 0) > 0 || (material.videoTextureFields?.size ?? 0) > 0;
+}
+
 /**
  * Projects already-resolved mesh facts into the existing GPU-driven draw
  * snapshot. No World or AssetRegistry access is permitted at this boundary.
  */
-export function buildGpuDrivenDraws(input: {
+interface BuildGpuDrivenDrawsInput {
+  readonly mesh: MeshAsset | undefined;
+  readonly materials: readonly MaterialSnapshot[];
+  readonly fallbackMaterial: MaterialSnapshot;
+  readonly baseSnapshot: RenderableSnapshot;
+  readonly getMaterialShaderArtifact?: (
+    materialShaderId: string,
+    vertexColorAvailable?: boolean,
+  ) => MaterialShaderArtifact | undefined;
+  /** Resolved lower-detail meshes, in the same order as baseSnapshot.lods. */
+  readonly lodMeshes?: readonly (MeshAsset | undefined)[];
+}
+
+interface LegacyBuildGpuDrivenDrawsInput {
   readonly submeshes: readonly MeshAsset['submeshes'][number][];
   readonly indexed: boolean;
   readonly materials: readonly MaterialSnapshot[];
@@ -85,24 +151,133 @@ export function buildGpuDrivenDraws(input: {
     draw: GpuDrivenDrawSnapshot,
     material: MaterialSnapshot,
   ) => PreparedGpuDrivenDraw | undefined;
-}): GpuDrivenDrawSnapshot[] {
+}
+
+export function buildGpuDrivenDraws(input: BuildGpuDrivenDrawsInput): GpuDrivenDrawSnapshot[];
+export function buildGpuDrivenDraws(input: LegacyBuildGpuDrivenDrawsInput): GpuDrivenDrawSnapshot[];
+export function buildGpuDrivenDraws(
+  input: BuildGpuDrivenDrawsInput | LegacyBuildGpuDrivenDrawsInput,
+): GpuDrivenDrawSnapshot[] {
+  const legacy = 'submeshes' in input;
+  if (!legacy && input.mesh === undefined) return [];
+  const parsedMesh = legacy ? undefined : input.mesh;
+  if (!legacy && parsedMesh === undefined) return [];
+  const indexed = legacy ? input.indexed : parsedMesh?.indices !== undefined;
+  const submeshes = legacy ? input.submeshes : (parsedMesh?.submeshes ?? []);
+  const layoutProjection =
+    parsedMesh === undefined ? undefined : deriveVertexLayoutProjection(parsedMesh.attributes);
+  const geometry: GpuDrivenGeometryReceipt = {
+    identity:
+      parsedMesh === undefined
+        ? '<no-mesh>'
+        : `${(parsedMesh as { guid?: string }).guid ?? '<no-guid>'}:${layoutProjection?.digest ?? ''}`,
+    vertexInputs: (layoutProjection?.attributes ?? []).map((attribute) => ({
+      semantic: attribute.key,
+      location: attribute.shaderLocation,
+      format: attribute.format,
+    })),
+    topology: submeshes[0]?.topology ?? 'triangle-list',
+    indexed,
+  };
   let nonIndexedFirst = 0;
-  return input.submeshes.flatMap((submesh) => {
+  return submeshes.flatMap((submesh, drawItemIndex) => {
     const drawMaterial = input.materials[submesh.materialSlot] ?? input.fallbackMaterial;
-    const first = input.indexed ? submesh.indexOffset : nonIndexedFirst;
+    const first = indexed ? submesh.indexOffset : nonIndexedFirst;
     nonIndexedFirst += submesh.vertexCount;
     if (drawMaterial.transparent === true) return [];
     const draw: GpuDrivenDrawSnapshot = {
-      kind: input.indexed ? ('indexed' as const) : ('non-indexed' as const),
+      drawItemIndex,
+      kind: indexed ? ('indexed' as const) : ('non-indexed' as const),
       first,
-      count: input.indexed ? submesh.indexCount : submesh.vertexCount,
+      count: indexed ? submesh.indexCount : submesh.vertexCount,
       baseVertex: 0,
       materialSlot: submesh.materialSlot,
       topology: submesh.topology,
       pipelineClass: `${drawMaterial.materialShaderId ?? 'forgeax::default-unlit'}|${submesh.topology}|${JSON.stringify(drawMaterial.renderState ?? null)}`,
       materialResourceClass: gpuDrivenMaterialResourceClass(drawMaterial),
     };
-    const prepared = input.prepare?.(draw, drawMaterial);
-    return [prepared === undefined ? draw : { ...draw, prepared }];
+    const lodRanges = !legacy
+      ? input.lodMeshes?.map((lodMesh) => {
+          if (lodMesh === undefined) return undefined;
+          const lower = lodMesh.submeshes[drawItemIndex];
+          if (lower === undefined) return undefined;
+          const lowerIndexed = lodMesh.indices !== undefined;
+          const lowerFirst = lowerIndexed
+            ? lower.indexOffset
+            : lodMesh.submeshes
+                .slice(0, drawItemIndex)
+                .reduce((offset, entry) => offset + entry.vertexCount, 0);
+          return {
+            first: lowerFirst,
+            count: lowerIndexed ? lower.indexCount : lower.vertexCount,
+            baseVertex: 0,
+          };
+        })
+      : undefined;
+    const withLodRanges =
+      lodRanges?.length !== 0 && lodRanges?.every((range) => range !== undefined)
+        ? { lodRanges: lodRanges as { first: number; count: number; baseVertex: number }[] }
+        : {};
+    const prepared = legacy
+      ? input.prepare?.(draw, drawMaterial)
+      : hasCpuOnlyMaterialResources(drawMaterial)
+        ? undefined
+        : (() => {
+            const materialShaderId = drawMaterial.materialShaderId;
+            const artifact =
+              materialShaderId === undefined
+                ? undefined
+                : input.getMaterialShaderArtifact?.(
+                    materialShaderId,
+                    geometry.vertexInputs.some((attribute) => attribute.semantic === 'color'),
+                  );
+            const standardPbr = isStandardPbrMaterialShader(materialShaderId);
+            if (artifact === undefined) {
+              return input.getMaterialShaderArtifact !== undefined && standardPbr
+                ? new GpuDrivenPreparationError('missing-material-receipt', {
+                    reason: 'material-receipt-missing',
+                    owner: 'material',
+                    expected: `artifact for ${materialShaderId}`,
+                  })
+                : undefined;
+            }
+            const receipt = artifact.receipt;
+            if (receipt === undefined) {
+              return standardPbr
+                ? new GpuDrivenPreparationError('missing-material-receipt', {
+                    reason: 'material-receipt-missing',
+                    owner: 'material',
+                    expected: `receipt for ${materialShaderId}`,
+                  })
+                : undefined;
+            }
+            const skinReceipt: GpuDrivenSkinReceipt | undefined =
+              input.baseSnapshot.skin !== undefined && receipt.skinPaletteAddress !== undefined
+                ? {
+                    identity: input.baseSnapshot.skin.identity,
+                    generation: input.baseSnapshot.skin.generation,
+                    group: receipt.skinPaletteAddress.group,
+                    binding: receipt.skinPaletteAddress.binding,
+                    byteOffset: input.baseSnapshot.skin.byteOffset,
+                  }
+                : undefined;
+            const result = resolvePreparedGpuDrivenDraw({
+              snapshot: { ...input.baseSnapshot, material: drawMaterial },
+              artifact,
+              geometry: { ...geometry, topology: draw.topology, indexed: draw.kind === 'indexed' },
+              generation: receipt.generation,
+              draw,
+              ...(skinReceipt === undefined ? {} : { skinReceipt }),
+            });
+            return result.ok ? result.value : standardPbr ? result.error : undefined;
+          })();
+    if (prepared instanceof GpuDrivenPreparationError) {
+      return [{ ...draw, preparationError: prepared, ...withLodRanges }];
+    }
+    return [
+      prepared === undefined
+        ? { ...draw, ...withLodRanges }
+        : { ...draw, prepared, ...withLodRanges },
+    ];
   });
 }