@forgeax/engine-render 0.1.21 → 0.1.23

package/src/scene/visibility/bounds.ts

@@ -0,0 +1,57 @@
+export interface ConservativeBounds {
+  readonly min: readonly [number, number, number];
+  readonly max: readonly [number, number, number];
+}
+
+export interface BoundsCandidate {
+  readonly bounds: ConservativeBounds | undefined;
+  readonly transparent: boolean;
+  readonly deformed: boolean;
+}
+
+export function conservativeBounds(
+  localMin: readonly [number, number, number],
+  localMax: readonly [number, number, number],
+): ConservativeBounds {
+  return {
+    min: [
+      Math.min(localMin[0], localMax[0]),
+      Math.min(localMin[1], localMax[1]),
+      Math.min(localMin[2], localMax[2]),
+    ],
+    max: [
+      Math.max(localMin[0], localMax[0]),
+      Math.max(localMin[1], localMax[1]),
+      Math.max(localMin[2], localMax[2]),
+    ],
+  };
+}
+
+export function encloseBounds(
+  boundsList: readonly (ConservativeBounds | undefined)[],
+): ConservativeBounds | undefined {
+  const present = boundsList.filter((bounds): bounds is ConservativeBounds => bounds !== undefined);
+  if (present.length === 0) return undefined;
+  const min: [number, number, number] = [Infinity, Infinity, Infinity];
+  const max: [number, number, number] = [-Infinity, -Infinity, -Infinity];
+  for (const bounds of present) {
+    for (let axis = 0; axis < 3; axis += 1) {
+      const lower = axis === 0 ? bounds.min[0] : axis === 1 ? bounds.min[1] : bounds.min[2];
+      const upper = axis === 0 ? bounds.max[0] : axis === 1 ? bounds.max[1] : bounds.max[2];
+      min[axis] = Math.min(min[axis] ?? Infinity, lower ?? 0);
+      max[axis] = Math.max(max[axis] ?? -Infinity, upper ?? 0);
+    }
+  }
+  return { min, max };
+}
+
+export function conservativeVisibleCandidate(
+  candidate: BoundsCandidate,
+):
+  | { readonly visible: true; readonly queryable: false }
+  | { readonly visible: false; readonly queryable: true; readonly bounds: ConservativeBounds } {
+  if (candidate.bounds === undefined || candidate.transparent || candidate.deformed) {
+    return { visible: true, queryable: false };
+  }
+  return { visible: false, queryable: true, bounds: candidate.bounds };
+}

package/src/scene/visibility/budget.ts

@@ -0,0 +1,40 @@
+export const DEFAULT_CONFIGURED_QUERY_BUDGET = 2048;
+export const MAX_QUERY_BUDGET = 4096;
+export const VISIBILITY_CANDIDATE_COUNT = 100_000;
+export const VISIBILITY_OCCLUDED_COUNT = 90_000;
+
+export interface VisibilityBudget {
+  readonly configuredQueryBudget: number;
+  readonly effectiveQueryBudget: number;
+  readonly oneSweepCandidates: number;
+  readonly oneSweepOccluded: number;
+  readonly settleSubmits: number;
+  readonly retestSubmits: number;
+  readonly expirySubmits: number;
+}
+
+/** Derive every renderer visibility window from one bounded query budget. */
+export function createVisibilityBudget(
+  configuredQueryBudget = DEFAULT_CONFIGURED_QUERY_BUDGET,
+): VisibilityBudget {
+  if (!Number.isSafeInteger(configuredQueryBudget) || configuredQueryBudget <= 0) {
+    throw new RangeError('configuredQueryBudget must be a positive safe integer');
+  }
+  const effectiveQueryBudget = Math.min(configuredQueryBudget, MAX_QUERY_BUDGET);
+  const oneSweepCandidates = oneSweep(VISIBILITY_CANDIDATE_COUNT, effectiveQueryBudget);
+  const oneSweepOccluded = oneSweep(VISIBILITY_OCCLUDED_COUNT, effectiveQueryBudget);
+  const retestSubmits = Math.max(6, oneSweepOccluded);
+  return Object.freeze({
+    configuredQueryBudget,
+    effectiveQueryBudget,
+    oneSweepCandidates,
+    oneSweepOccluded,
+    settleSubmits: 2 * oneSweepCandidates,
+    retestSubmits,
+    expirySubmits: Math.max(8, retestSubmits + oneSweepOccluded),
+  });
+}
+
+function oneSweep(candidateCount: number, effectiveQueryBudget: number): number {
+  return Math.ceil(candidateCount / effectiveQueryBudget);
+}

package/src/scene/visibility/facet.ts

@@ -0,0 +1,400 @@
+import { createVisibilityBudget, type VisibilityBudget } from './budget';
+import {
+  type ConfidenceEvent,
+  type ConfidenceState,
+  OcclusionConfidenceScheduler,
+  shouldIssueRetest,
+} from './occlusion-confidence';
+import {
+  type PrimitiveKey,
+  primitiveKeyId,
+  type ViewKey,
+  type VisibilityCandidate,
+  type VisibilityFacetInspection,
+  viewKeyId,
+} from './types';
+
+interface ViewState {
+  readonly key: ViewKey;
+  epoch: number;
+  readonly rows: Map<string, VisibilityCandidate>;
+}
+
+interface QueryEntry {
+  readonly view: ViewKey;
+  readonly primitive: PrimitiveKey;
+}
+
+interface QueryNode {
+  readonly viewId: string;
+  readonly key: string;
+  previous: string | undefined;
+  next: string | undefined;
+}
+
+interface QueryQueue {
+  head: string | undefined;
+  tail: string | undefined;
+}
+
+/**
+ * Renderer-owned CPU visibility state indexed by ViewKey x PrimitiveKey.
+ *
+ * Attachment order is intentionally not part of the key. This keeps world
+ * reorder, detach, and slot ABA recovery generation-safe without a second
+ * lane-specific visibility map.
+ */
+export class VisibilityFacetStore {
+  private readonly views = new Map<string, ViewState>();
+  private readonly confidence: OcclusionConfidenceScheduler;
+  private visibilityRevision = 0;
+  private drawRevision = 0;
+  private queryRevision = 0;
+  private readonly queryEntries = new Map<string, QueryEntry>();
+  private readonly readyQueryKeys = new Set<string>();
+  private readonly inFlightQueryKeys = new Set<string>();
+  private readonly queryQueues = new Map<string, QueryQueue>();
+  /** Intrusive FIFO nodes make removal/requeue O(1), so dequeue never walks stale rows. */
+  private readonly queryNodes = new Map<string, QueryNode>();
+
+  constructor(private readonly budget: VisibilityBudget = createVisibilityBudget()) {
+    this.confidence = new OcclusionConfidenceScheduler(budget);
+  }
+
+  visibilityBudget(): VisibilityBudget {
+    return this.budget;
+  }
+
+  /** Monotonic token for confidence changes that can alter draw admission. */
+  get revision(): number {
+    return this.visibilityRevision;
+  }
+
+  /** Revision for the bounded query-candidate admission set only. */
+  get queryRevisionValue(): number {
+    return this.queryRevision;
+  }
+
+  /** Revision for the active draw admission set (status/queryable identity). */
+  get drawRevisionValue(): number {
+    return this.drawRevision;
+  }
+
+  activateView(key: ViewKey): void {
+    const id = viewKeyId(key);
+    const existing = this.views.get(id);
+    if (existing !== undefined) return;
+    this.views.set(id, { key, epoch: 0, rows: new Map() });
+  }
+
+  retireView(key: ViewKey): void {
+    const id = viewKeyId(key);
+    const state = this.views.get(id);
+    this.views.delete(id);
+    if (state !== undefined) {
+      this.visibilityRevision += 1;
+      this.drawRevision += 1;
+      this.queryRevision += 1;
+      for (const primitive of state.rows.keys()) {
+        this.removeQueryKey(`${id}|${primitive}`);
+      }
+    }
+  }
+
+  detachAttachment(attachmentId: string): void {
+    let detached = false;
+    for (const [id, state] of this.views) {
+      if (state.key.attachmentId === attachmentId) {
+        this.views.delete(id);
+        for (const primitive of state.rows.keys()) {
+          this.removeQueryKey(`${id}|${primitive}`);
+        }
+        detached = true;
+      }
+    }
+    if (detached) {
+      this.visibilityRevision += 1;
+      this.drawRevision += 1;
+      this.queryRevision += 1;
+    }
+  }
+
+  /** Drop every view/row when a composition owner is detached. */
+  clear(): void {
+    if (this.views.size > 0 || this.visibilityRevision > 0) {
+      this.visibilityRevision += 1;
+      this.drawRevision += 1;
+      this.queryRevision += 1;
+    }
+    this.views.clear();
+    this.confidence.clear();
+    this.queryEntries.clear();
+    this.readyQueryKeys.clear();
+    this.inFlightQueryKeys.clear();
+    this.queryQueues.clear();
+    this.queryNodes.clear();
+  }
+
+  reorderAttachments(_attachmentIds: readonly string[]): void {
+    // Attachment order is deliberately not stored. Keys remain stable when
+    // the caller changes the order of its world list.
+  }
+
+  setCandidate(view: ViewKey, primitive: PrimitiveKey, candidate: VisibilityCandidate): boolean {
+    const state = this.views.get(viewKeyId(view));
+    if (state === undefined || primitive.attachmentId !== view.attachmentId) return false;
+    const primitiveId = primitiveKeyId(primitive);
+    const key = `${viewKeyId(view)}|${primitiveId}`;
+    const previous = state.rows.get(primitiveId);
+    if (
+      previous === undefined ||
+      previous.level !== candidate.level ||
+      previous.confidence !== candidate.confidence
+    ) {
+      this.visibilityRevision += 1;
+      this.drawRevision += 1;
+    }
+    state.rows.set(primitiveId, { ...candidate });
+    this.queryEntries.set(key, { view, primitive });
+    this.syncQueryKey(key, this.confidence.ensure(key));
+    return true;
+  }
+
+  /** Remove rows that are no longer queryable in the extracted frame. */
+  pruneCandidates(view: ViewKey, activePrimitives: ReadonlySet<string>): void {
+    const state = this.views.get(viewKeyId(view));
+    if (state === undefined) return;
+    for (const primitiveId of [...state.rows.keys()]) {
+      if (activePrimitives.has(primitiveId)) continue;
+      state.rows.delete(primitiveId);
+      this.removeQueryKey(`${viewKeyId(view)}|${primitiveId}`);
+      this.visibilityRevision += 1;
+      this.drawRevision += 1;
+      this.queryRevision += 1;
+    }
+  }
+
+  applyConfidence(view: ViewKey, primitive: PrimitiveKey, event: ConfidenceEvent): ConfidenceState {
+    const key = `${viewKeyId(view)}|${primitiveKeyId(primitive)}`;
+    const before = this.confidence.ensure(key);
+    const after =
+      event.type === 'submit' && this.inFlightQueryKeys.has(key)
+        ? this.confidence.applyInFlightSubmit(key, event)
+        : this.confidence.apply(key, event);
+    if (event.type === 'failure') this.inFlightQueryKeys.delete(key);
+    if (
+      before.status !== after.status ||
+      before.zeroStreak !== after.zeroStreak ||
+      before.successfulSubmits !== after.successfulSubmits ||
+      before.queryable !== after.queryable ||
+      before.dirty !== after.dirty ||
+      before.lastResultGeneration !== after.lastResultGeneration
+    ) {
+      this.visibilityRevision += 1;
+    }
+    if (before.status !== after.status || before.queryable !== after.queryable) {
+      this.drawRevision += 1;
+    }
+    const beforeNeedsQuery =
+      (before.dirty && before.successfulSubmits === 0) || shouldIssueRetest(before, this.budget);
+    const afterNeedsQuery =
+      (after.dirty && after.successfulSubmits === 0) || shouldIssueRetest(after, this.budget);
+    if (beforeNeedsQuery !== afterNeedsQuery) this.queryRevision += 1;
+    this.syncQueryKey(key, after);
+    return after;
+  }
+
+  /** Advance hidden rows on a successful frame, excluding rows queried now. */
+  advanceSuccessfulSubmits(
+    submissionGeneration: number,
+    excluded?: readonly { readonly view: ViewKey; readonly primitive: PrimitiveKey }[],
+  ): void {
+    let excludedKeys: ReadonlySet<string> | undefined;
+    if (excluded !== undefined && excluded.length > 0) {
+      const keys = new Set<string>();
+      for (const { view, primitive } of excluded) {
+        keys.add(`${viewKeyId(view)}|${primitiveKeyId(primitive)}`);
+      }
+      excludedKeys = keys;
+    }
+    const result = this.confidence.advanceSuccessfulSubmits(submissionGeneration, excludedKeys);
+    if (result.changed) {
+      this.visibilityRevision += 1;
+    }
+    if (result.drawChangedKeys.length > 0) this.drawRevision += 1;
+    if (result.queryChangedKeys.length > 0) this.queryRevision += 1;
+    for (const key of [...result.drawChangedKeys, ...result.queryChangedKeys]) {
+      this.syncQueryKey(key, this.confidence.get(key));
+    }
+  }
+
+  getConfidence(view: ViewKey, primitive: PrimitiveKey): ConfidenceState {
+    return this.confidence.ensure(`${viewKeyId(view)}|${primitiveKeyId(primitive)}`);
+  }
+
+  /** Whether this candidate needs a bounded query this frame. */
+  shouldQuery(view: ViewKey, primitive: PrimitiveKey): boolean {
+    const state = this.getConfidence(view, primitive);
+    return (state.dirty && state.successfulSubmits === 0) || shouldIssueRetest(state, this.budget);
+  }
+
+  drainConfidenceRetests(limit: number): string[] {
+    return this.confidence.drainRetests(limit);
+  }
+
+  /**
+   * Remove a bounded page of ready query work for one view. Queue entries are
+   * identity keyed, so confidence completion and resource failure can safely
+   * requeue the same primitive without scanning the scene.
+   */
+  dequeueQueryCandidates(view: ViewKey, limit: number): readonly QueryEntry[] {
+    if (!Number.isSafeInteger(limit) || limit <= 0) return [];
+    const viewId = viewKeyId(view);
+    const queue = this.queryQueues.get(viewId);
+    if (queue === undefined) return [];
+    const result: QueryEntry[] = [];
+    while (queue.head !== undefined && result.length < limit) {
+      const key = queue.head;
+      this.removeQueuedKey(key);
+      if (!this.readyQueryKeys.delete(key)) continue;
+      const entry = this.queryEntries.get(key);
+      if (entry === undefined || viewKeyId(entry.view) !== viewId) continue;
+      this.inFlightQueryKeys.add(key);
+      result.push(entry);
+    }
+    return result;
+  }
+
+  /** Put a candidate back after a query page could not be reserved. */
+  requeueQueryCandidate(view: ViewKey, primitive: PrimitiveKey): void {
+    const key = `${viewKeyId(view)}|${primitiveKeyId(primitive)}`;
+    this.inFlightQueryKeys.delete(key);
+    this.syncQueryKey(key, this.confidence.get(key));
+  }
+
+  getCandidate(view: ViewKey, primitive: PrimitiveKey): VisibilityCandidate | undefined {
+    const state = this.views.get(viewKeyId(view));
+    if (state === undefined || primitive.attachmentId !== view.attachmentId) return undefined;
+    const candidate = state.rows.get(primitiveKeyId(primitive));
+    return candidate === undefined ? undefined : { ...candidate };
+  }
+
+  beginViewEpoch(view: ViewKey): number {
+    const state = this.views.get(viewKeyId(view));
+    if (state === undefined) return -1;
+    for (const primitive of state.rows.keys()) {
+      this.removeQueryKey(`${viewKeyId(view)}|${primitive}`);
+    }
+    state.epoch += 1;
+    state.rows.clear();
+    this.visibilityRevision += 1;
+    this.drawRevision += 1;
+    this.queryRevision += 1;
+    return state.epoch;
+  }
+
+  applyCompletion(
+    view: ViewKey,
+    primitive: PrimitiveKey,
+    epoch: number,
+    candidate: VisibilityCandidate,
+  ): boolean {
+    const state = this.views.get(viewKeyId(view));
+    if (
+      state === undefined ||
+      state.epoch !== epoch ||
+      primitive.attachmentId !== view.attachmentId
+    ) {
+      return false;
+    }
+    const primitiveId = primitiveKeyId(primitive);
+    const previous = state.rows.get(primitiveId);
+    if (
+      previous === undefined ||
+      previous.level !== candidate.level ||
+      previous.confidence !== candidate.confidence
+    ) {
+      this.visibilityRevision += 1;
+      this.drawRevision += 1;
+    }
+    state.rows.set(primitiveId, { ...candidate });
+    const key = `${viewKeyId(view)}|${primitiveId}`;
+    this.queryEntries.set(key, { view, primitive });
+    this.syncQueryKey(key, this.confidence.ensure(key));
+    return true;
+  }
+
+  inspect(): VisibilityFacetInspection {
+    let facetRows = 0;
+    for (const state of this.views.values()) facetRows += state.rows.size;
+    return { owner: 'persistent-render-scene', activeViews: this.views.size, facetRows };
+  }
+
+  private syncQueryKey(key: string, state: ConfidenceState | undefined): void {
+    if (state === undefined) return;
+    const shouldQuery =
+      (state.dirty && state.successfulSubmits === 0) || shouldIssueRetest(state, this.budget);
+    if (!shouldQuery) {
+      this.removeQueuedKey(key);
+      this.readyQueryKeys.delete(key);
+      this.inFlightQueryKeys.delete(key);
+      return;
+    }
+    if (this.readyQueryKeys.has(key) || this.inFlightQueryKeys.has(key)) return;
+    const entry = this.queryEntries.get(key);
+    if (entry === undefined) return;
+    this.readyQueryKeys.add(key);
+    const viewId = viewKeyId(entry.view);
+    const queue = this.queryQueues.get(viewId) ?? { head: undefined, tail: undefined };
+    const node: QueryNode = {
+      viewId,
+      key,
+      previous: queue.tail,
+      next: undefined,
+    };
+    if (queue.tail !== undefined) {
+      const tail = this.queryNodes.get(queue.tail);
+      if (tail !== undefined) tail.next = key;
+    } else {
+      queue.head = key;
+    }
+    queue.tail = key;
+    this.queryQueues.set(viewId, queue);
+    this.queryNodes.set(key, node);
+  }
+
+  private removeQueryKey(key: string): void {
+    this.confidence.remove(key);
+    this.queryEntries.delete(key);
+    this.removeQueuedKey(key);
+    this.readyQueryKeys.delete(key);
+    this.inFlightQueryKeys.delete(key);
+  }
+
+  private removeQueuedKey(key: string): void {
+    const node = this.queryNodes.get(key);
+    if (node === undefined) return;
+    const queue = this.queryQueues.get(node.viewId);
+    this.queryNodes.delete(key);
+    if (queue === undefined) return;
+    if (node.previous === undefined) queue.head = node.next;
+    else {
+      const previous = this.queryNodes.get(node.previous);
+      if (previous !== undefined) previous.next = node.next;
+    }
+    if (node.next === undefined) queue.tail = node.previous;
+    else {
+      const next = this.queryNodes.get(node.next);
+      if (next !== undefined) next.previous = node.previous;
+    }
+    if (queue.head === undefined) this.queryQueues.delete(node.viewId);
+  }
+}
+
+export type {
+  PrimitiveKey,
+  ViewKey,
+  VisibilityCandidate,
+  VisibilityFacetInspection,
+} from './types';
+export { primitiveKey, primitiveKeyId, viewKey, viewKeyId } from './types';

package/src/scene/visibility/gpu-frame-timing.ts

@@ -0,0 +1,101 @@
+/** Renderer-owned timestamp facts spanning one graph and one queue submit. */
+
+export interface GpuFrameTimingProtocol {
+  readonly firstMarker: 'frame.first-pass';
+  readonly terminalMarker: 'occlusion.resolve-copy';
+  readonly sameGraph: true;
+  readonly sameSubmit: true;
+}
+
+export interface GpuFrameTiming {
+  readonly frameId: number;
+  readonly deviceGeneration: number;
+  readonly protocol: GpuFrameTimingProtocol;
+  aborted: boolean;
+  submitId: number | undefined;
+}
+
+export interface GpuFrameTimingRecord {
+  readonly firstPassTimestampNs: number;
+  readonly occlusionResolveTimestampNs: number;
+  readonly submitted: boolean;
+  readonly graphGeneration: number;
+  readonly submitId: number;
+}
+
+export interface GpuFrameTimingSample {
+  readonly frameId: number;
+  readonly deviceGeneration: number;
+  readonly durationUs: number;
+  readonly protocol: GpuFrameTimingProtocol;
+  readonly graphGeneration: number;
+  readonly submitId: number;
+}
+
+export interface GpuFrameTimingSummary {
+  readonly medianUs: number;
+  readonly p95Us: number;
+  readonly samples: number;
+}
+
+const PROTOCOL: GpuFrameTimingProtocol = Object.freeze({
+  firstMarker: 'frame.first-pass',
+  terminalMarker: 'occlusion.resolve-copy',
+  sameGraph: true,
+  sameSubmit: true,
+});
+
+export function createGpuFrameTiming(input: {
+  readonly frameId: number;
+  readonly deviceGeneration: number;
+}): GpuFrameTiming {
+  return { ...input, protocol: PROTOCOL, aborted: false, submitId: undefined };
+}
+
+export function recordGpuFrameTiming(
+  timing: GpuFrameTiming,
+  record: GpuFrameTimingRecord,
+): GpuFrameTimingSample {
+  if (!record.submitted) {
+    timing.aborted = true;
+    throw new Error('GPU frame timing requires a submitted frame');
+  }
+  if (timing.aborted) throw new Error('GPU frame timing cannot cross a failed submit');
+  if (timing.submitId !== undefined && timing.submitId !== record.submitId) {
+    throw new Error('GPU frame timing markers must share one submit');
+  }
+  if (
+    !Number.isFinite(record.firstPassTimestampNs) ||
+    !Number.isFinite(record.occlusionResolveTimestampNs)
+  ) {
+    throw new Error('GPU frame timing requires finite timestamps');
+  }
+  if (record.occlusionResolveTimestampNs < record.firstPassTimestampNs) {
+    throw new Error('GPU frame timing terminal marker precedes first marker');
+  }
+  timing.submitId = record.submitId;
+  return Object.freeze({
+    frameId: timing.frameId,
+    deviceGeneration: timing.deviceGeneration,
+    durationUs: (record.occlusionResolveTimestampNs - record.firstPassTimestampNs) / 1_000,
+    protocol: PROTOCOL,
+    graphGeneration: record.graphGeneration,
+    submitId: record.submitId,
+  });
+}
+
+function nearestRank(values: readonly number[], percentile: number): number {
+  const sorted = [...values].sort((left, right) => left - right);
+  return sorted[Math.max(0, Math.ceil(percentile * sorted.length) - 1)] ?? 0;
+}
+
+export function summarizeGpuFrameTiming(
+  samples: readonly GpuFrameTimingSample[],
+): GpuFrameTimingSummary {
+  const values = samples.map((sample) => sample.durationUs);
+  return Object.freeze({
+    medianUs: nearestRank(values, 0.5),
+    p95Us: nearestRank(values, 0.95),
+    samples: values.length,
+  });
+}