@forgeax/engine-render 0.1.27 → 0.1.29

package/src/render-system-projections.ts

@@ -0,0 +1,241 @@
+import type { World } from '@forgeax/engine-ecs';
+import type { RenderReadLease } from '@forgeax/engine-ecs/projection';
+import { RenderQueue } from '@forgeax/engine-types';
+import type {
+  LodOcclusionInspection,
+  LodOcclusionInspectionRow,
+  LodOcclusionWorldInspection,
+} from './inspection-types';
+import { worldEntityKey } from './record/frame-snapshot';
+import type { CameraSnapshot, DrawOwnerOptions } from './render-contract';
+import type { DispatchEntry, RenderableSnapshot } from './render-system-extract';
+import {
+  getTransparentSortConfig,
+  TRANSPARENT_SORT_MODE_DISTANCE,
+  TRANSPARENT_SORT_MODE_LAYER_Y,
+  TRANSPARENT_SORT_MODE_LAYER_YZ,
+  TRANSPARENT_SORT_MODE_LAYER_Z,
+} from './systems/transparent-sort-config';
+
+export function canonicalizeWorldComposition(
+  worlds: readonly World[],
+  owners: Pick<DrawOwnerOptions, 'cameraOwner' | 'resourceOwner' | 'cameraEntityKey'>,
+  leases: readonly RenderReadLease[] | undefined,
+): {
+  readonly worlds: readonly World[];
+  readonly owners: Pick<DrawOwnerOptions, 'cameraOwner' | 'resourceOwner' | 'cameraEntityKey'>;
+  readonly leases: readonly RenderReadLease[] | undefined;
+} {
+  const order = worlds
+    .map((world, index) => ({ world, index }))
+    .sort((left, right) => left.world.identity.localeCompare(right.world.identity));
+  const indexByOriginal = new Map(order.map((entry, index) => [entry.index, index]));
+  return {
+    worlds: Object.freeze(order.map((entry) => entry.world)),
+    owners: {
+      cameraOwner: indexByOriginal.get(owners.cameraOwner) ?? owners.cameraOwner,
+      resourceOwner: indexByOriginal.get(owners.resourceOwner) ?? owners.resourceOwner,
+      ...(owners.cameraEntityKey === undefined ? {} : { cameraEntityKey: owners.cameraEntityKey }),
+    },
+    leases:
+      leases === undefined
+        ? undefined
+        : Object.freeze(
+            order.map((entry) => leases[entry.index]).filter((lease) => lease !== undefined),
+          ),
+  };
+}
+
+interface LodInspectionQuerySummary {
+  readonly used: number;
+  readonly capacity: number;
+}
+
+export function createLodWorldInspections(
+  worlds: readonly World[],
+  renderables: readonly RenderableSnapshot[],
+  submittedRenderables: readonly RenderableSnapshot[],
+  camera: CameraSnapshot,
+  frameId: number,
+  worldKeys: readonly number[],
+  slots: ReadonlyMap<number, { readonly slot: number; readonly generation: number }>,
+  query: LodInspectionQuerySummary,
+  fallback: LodOcclusionInspection['fallback'],
+  degradation: LodOcclusionInspection['degradation'],
+): readonly LodOcclusionWorldInspection[] {
+  // The CPU projection knows which renderables belong to each World, but it
+  // does not receive the GPU selector/query counters split by World from the
+  // same submit. Keep these rows available for diagnostics while explicitly
+  // marking their attribution unavailable; producers must not promote them
+  // to World-reorder evidence by inferring facts from array order.
+  const attribution = Object.freeze({
+    status: 'unavailable' as const,
+    reason: 'projection-only' as const,
+  });
+  const submitted = new Set(submittedRenderables);
+  const sampleLimit = 64;
+  const accumulators = worlds.map(() => ({
+    allCount: 0,
+    allVisible: 0,
+    allSamples: [] as RenderableSnapshot[],
+    lodCount: 0,
+    lodVisible: 0,
+    lodSamples: [] as RenderableSnapshot[],
+  }));
+  // Keep this projection bounded: the old implementation filtered the full
+  // 100k renderable list twice per World on every frame and retained another
+  // Set-backed traversal just to derive the six counters below. One pass is
+  // enough because the inspection only needs counts, the first row identity,
+  // and at most 64 detached samples.
+  for (const renderable of renderables) {
+    const accumulator = accumulators[renderable.worldId];
+    if (accumulator === undefined) continue;
+    const visible = submitted.has(renderable);
+    accumulator.allCount += 1;
+    if (visible) accumulator.allVisible += 1;
+    if (accumulator.allSamples.length < sampleLimit) accumulator.allSamples.push(renderable);
+    if ((renderable.lods?.length ?? 0) > 0) {
+      accumulator.lodCount += 1;
+      if (visible) accumulator.lodVisible += 1;
+      if (accumulator.lodSamples.length < sampleLimit) accumulator.lodSamples.push(renderable);
+    }
+  }
+  const result: LodOcclusionWorldInspection[] = [];
+  for (let worldId = 0; worldId < worlds.length; worldId += 1) {
+    const world = worlds[worldId];
+    if (world === undefined) continue;
+    const accumulator = accumulators[worldId];
+    if (accumulator === undefined || accumulator.allCount === 0) {
+      result.push(
+        Object.freeze({ attachmentId: world.identity, rows: Object.freeze([]), attribution }),
+      );
+      continue;
+    }
+    const usesLod = accumulator.lodCount > 0;
+    const candidateCount = usesLod ? accumulator.lodCount : accumulator.allCount;
+    const visible = usesLod ? accumulator.lodVisible : accumulator.allVisible;
+    const samples = usesLod ? accumulator.lodSamples : accumulator.allSamples;
+    const first = samples[0];
+    const slot =
+      first === undefined
+        ? undefined
+        : slots.get(worldEntityKey(worldKeys[first.worldId] ?? first.worldId, first.entityKey));
+    const row: LodOcclusionInspectionRow = {
+      root: {
+        guid: first === undefined ? 'none' : `asset-handle:${first.assetHandle}`,
+        sourceKey: `render-world:${world.identity}`,
+      },
+      view: {
+        attachmentId: world.identity,
+        cameraEntity: world === worlds[camera.worldId ?? 0] ? (camera.entityKey ?? 0) : 0,
+        viewRole: 'main',
+        viewGeneration: camera.historyVersion ?? 0,
+      },
+      slot: { primitiveSlot: slot?.slot ?? 0, slotGeneration: slot?.generation ?? 0 },
+      generation: frameId,
+      count: { candidates: candidateCount, visible, occluded: candidateCount - visible },
+      lodHistogram: [{ level: 0, count: candidateCount }],
+      queryLatencyUs: { median: 0, p95: 0, last: 0 },
+      pagePressure: query,
+      fallback,
+      degradation,
+      samples: samples.map((candidate, index) => ({
+        primitiveSlot:
+          slots.get(
+            worldEntityKey(worldKeys[candidate.worldId] ?? candidate.worldId, candidate.entityKey),
+          )?.slot ?? index,
+        level: 0,
+        visible: submitted.has(candidate),
+      })),
+    };
+    result.push(
+      Object.freeze({
+        attachmentId: world.identity,
+        rows: Object.freeze([row]),
+        attribution,
+      }),
+    );
+  }
+  return Object.freeze(
+    result.sort((left, right) => left.attachmentId.localeCompare(right.attachmentId)),
+  );
+}
+
+/** Apply the configured stable sub-sort to transparent dispatch entries. */
+export function sortTransparentDispatch(
+  dispatch: DispatchEntry[],
+  world: World,
+  cameras: readonly CameraSnapshot[],
+  renderables: readonly RenderableSnapshot[],
+): DispatchEntry[] {
+  const cfg = getTransparentSortConfig(world);
+  const mode = cfg.mode;
+
+  const transparentSlots: number[] = [];
+  for (let i = 0; i < dispatch.length; i++) {
+    if (dispatch[i]?.queue === RenderQueue.Transparent) transparentSlots.push(i);
+  }
+  if (transparentSlots.length <= 1) return dispatch;
+
+  let sortedSlotOrder: number[];
+  if (mode === TRANSPARENT_SORT_MODE_DISTANCE) {
+    const camera = cameras[0];
+    if (camera === undefined) return dispatch;
+    const camPos = camera.position;
+    const negDistSq = (entry: DispatchEntry): number => {
+      const tx = renderables[entry.renderableIndex]?.transform;
+      if (tx === undefined) return 0;
+      const w = tx.world;
+      const dx = (w[12] ?? 0) - (camPos[0] ?? 0);
+      const dy = (w[13] ?? 0) - (camPos[1] ?? 0);
+      const dz = (w[14] ?? 0) - (camPos[2] ?? 0);
+      return -(dx * dx + dy * dy + dz * dz);
+    };
+    sortedSlotOrder = transparentSlots.slice().sort((a, b) => {
+      const da = negDistSq(dispatch[a] as DispatchEntry);
+      const db = negDistSq(dispatch[b] as DispatchEntry);
+      if (da < db) return -1;
+      if (da > db) return 1;
+      return 0;
+    });
+  } else {
+    const sortVal = (entry: DispatchEntry): number => {
+      const tx = renderables[entry.renderableIndex]?.transform;
+      const w = tx?.world;
+      const posY = (w?.[13] ?? 0) as number;
+      const posZ = (w?.[14] ?? 0) as number;
+      if (mode === TRANSPARENT_SORT_MODE_LAYER_Z) return posZ;
+      const mat = renderables[entry.renderableIndex]?.material;
+      const pivotAndSize = mat?.paramSnapshot?.pivotAndSize as readonly number[] | undefined;
+      const pivotY = (pivotAndSize?.[1] ?? 0.5) as number;
+      const wy4 = (w?.[4] ?? 0) as number;
+      const wy5 = (w?.[5] ?? 1) as number;
+      const wy6 = (w?.[6] ?? 0) as number;
+      const sizeY = Math.sqrt(wy4 * wy4 + wy5 * wy5 + wy6 * wy6);
+      const footY = posY - pivotY * sizeY;
+      if (mode === TRANSPARENT_SORT_MODE_LAYER_Y) return -footY;
+      if (mode === TRANSPARENT_SORT_MODE_LAYER_YZ) return footY + cfg.yzAlpha * posZ;
+      return posZ;
+    };
+    sortedSlotOrder = transparentSlots.slice().sort((a, b) => {
+      const da = dispatch[a] as DispatchEntry;
+      const db = dispatch[b] as DispatchEntry;
+      const la = da.layer;
+      const lb = db.layer;
+      if (la !== lb) return la - lb;
+      const va = sortVal(da);
+      const vb = sortVal(db);
+      if (va < vb) return -1;
+      if (va > vb) return 1;
+      return da.materialHandle - db.materialHandle;
+    });
+  }
+
+  const result = dispatch.slice();
+  for (let k = 0; k < transparentSlots.length; k++) {
+    const targetSlot = transparentSlots[k] as number;
+    const sourceSlot = sortedSlotOrder[k] as number;
+    result[targetSlot] = dispatch[sourceSlot] as DispatchEntry;
+  }
+  return result;
+}