@forgeax/engine-render 0.1.7 → 0.1.19

package/src/environment/inspection.ts

@@ -0,0 +1,87 @@
+import type { EnvironmentGeneration } from './generation';
+
+export type EnvironmentInspectionStatus = 'empty' | 'active' | 'candidate' | 'failed';
+
+export interface EnvironmentInspectionFailure {
+  readonly stage: 'prepare' | 'build' | 'execute' | 'finish' | 'submit';
+  readonly code: string;
+  readonly detail: Readonly<Record<string, unknown>>;
+}
+
+export interface EnvironmentInspectionGeneration {
+  readonly signature: string;
+  readonly generation: number;
+  readonly lane: 'direct' | 'clustered';
+  readonly source: 'none' | 'image' | 'atmosphere';
+  readonly resourceCount: number;
+  readonly bytes: number;
+  readonly residentBytes: number;
+  readonly retiringBytes: number;
+}
+
+export interface EnvironmentInspection {
+  readonly signature: string | undefined;
+  readonly generation: number | undefined;
+  readonly lane: 'direct' | 'clustered' | undefined;
+  readonly retired: boolean | undefined;
+  readonly source: 'none' | 'image' | 'atmosphere' | undefined;
+  readonly status: EnvironmentInspectionStatus;
+  readonly environmentSignature: string | undefined;
+  readonly fogSignature: string | undefined;
+  readonly activeSignature: string | undefined;
+  readonly lkgSignature: string | undefined;
+  readonly candidate: EnvironmentInspectionGeneration | undefined;
+  readonly active: EnvironmentInspectionGeneration | undefined;
+  readonly lkg: EnvironmentInspectionGeneration | undefined;
+  readonly bytes: number;
+  readonly resourceCount: number;
+  readonly residentBytes: number;
+  readonly retiringBytes: number;
+  readonly lastCandidateFailure: EnvironmentInspectionFailure | undefined;
+}
+
+export function inspectEnvironment(
+  generation: EnvironmentGeneration | undefined,
+  details: {
+    readonly source?: 'none' | 'image' | 'atmosphere';
+    readonly environmentSignature?: string;
+    readonly fogSignature?: string;
+    readonly active?: EnvironmentInspectionGeneration;
+    readonly lkg?: EnvironmentInspectionGeneration;
+    readonly candidate?: EnvironmentInspectionGeneration;
+    readonly lastCandidateFailure?: EnvironmentInspectionFailure;
+    readonly retiringBytes?: number;
+  } = {},
+): EnvironmentInspection {
+  const active = details.active;
+  const lkg = details.lkg;
+  const candidate = details.candidate;
+  const status: EnvironmentInspectionStatus =
+    candidate !== undefined
+      ? 'candidate'
+      : active !== undefined
+        ? 'active'
+        : details.lastCandidateFailure !== undefined
+          ? 'failed'
+          : 'empty';
+  return Object.freeze({
+    signature: generation?.signature,
+    generation: generation?.generation,
+    lane: generation?.lane,
+    retired: generation?.retired,
+    source: details.source,
+    status,
+    environmentSignature: details.environmentSignature,
+    fogSignature: details.fogSignature,
+    activeSignature: active?.signature,
+    lkgSignature: lkg?.signature,
+    candidate,
+    active,
+    lkg,
+    bytes: active?.bytes ?? candidate?.bytes ?? 0,
+    resourceCount: active?.resourceCount ?? candidate?.resourceCount ?? 0,
+    residentBytes: active?.residentBytes ?? 0,
+    retiringBytes: details.retiringBytes ?? active?.retiringBytes ?? 0,
+    lastCandidateFailure: details.lastCandidateFailure,
+  });
+}

package/src/environment/lifecycle.ts

@@ -0,0 +1,250 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+import type { DeviceScope } from '../device/device-scope';
+import { EnvironmentGenerationFailedError } from '../errors/render';
+import type { EnvironmentFrame } from './frame';
+import type { EnvironmentGeneration, EnvironmentGenerationFailure } from './generation';
+import { sharedEnvironmentFrame } from './graph';
+import {
+  type EnvironmentInspection,
+  type EnvironmentInspectionFailure,
+  type EnvironmentInspectionGeneration,
+  inspectEnvironment,
+} from './inspection';
+
+export interface EnvironmentLease {
+  readonly generation: number;
+  release(): void;
+}
+
+interface RetiredGeneration {
+  readonly generation: EnvironmentGeneration;
+}
+
+/** Owns candidate, active, LKG, and DeviceScope generation transitions. */
+export class EnvironmentLifecycle {
+  private currentScope: DeviceScope;
+  private nextGeneration = 0;
+  private active: EnvironmentGeneration | undefined;
+  private lkg: EnvironmentGeneration | undefined;
+  private readonly candidates = new Map<string, EnvironmentGeneration>();
+  private readonly frames = new Map<string, EnvironmentFrame>();
+  private readonly retired: RetiredGeneration[] = [];
+  private readonly leaseCounts = new Map<number, number>();
+  private lastCandidateFailure: EnvironmentInspectionFailure | undefined;
+
+  constructor(scope: DeviceScope) {
+    this.currentScope = scope;
+    this.nextGeneration = scope.generation;
+  }
+
+  bindScope(scope: DeviceScope): void {
+    this.currentScope = scope;
+  }
+
+  isActive(generation: EnvironmentGeneration): boolean {
+    return this.active === generation;
+  }
+
+  discard(generation: EnvironmentGeneration): void {
+    if (this.active === generation) return;
+    if (this.candidates.get(generation.signature) !== generation) return;
+    this.candidates.delete(generation.signature);
+    this.frames.delete(generation.signature);
+    generation.retired = true;
+    generation.scope.retire();
+  }
+
+  recordCandidateFailure(error: EnvironmentGenerationFailedError): void {
+    this.lastCandidateFailure = Object.freeze({
+      stage: error.detail.stage,
+      code: error.code,
+      detail: Object.freeze({ sourceKey: error.detail.sourceKey }),
+    });
+  }
+
+  recordStageFailure(
+    stage: EnvironmentInspectionFailure['stage'],
+    generation: EnvironmentGeneration,
+  ): void {
+    const frame = this.frames.get(generation.signature);
+    const sourceKey =
+      frame?.source.kind === 'none' || frame === undefined ? 'none' : frame.source.sourceKey;
+    this.lastCandidateFailure = Object.freeze({
+      stage,
+      code: 'environment-frame-aborted',
+      detail: Object.freeze({
+        sourceKey,
+        signature: generation.signature,
+        generation: generation.generation,
+      }),
+    });
+  }
+
+  ensure(
+    frame: EnvironmentFrame,
+    laneOrFailure: 'direct' | 'clustered' | EnvironmentGenerationFailure = 'direct',
+  ): Result<EnvironmentGeneration, EnvironmentGenerationFailedError> {
+    const lane = typeof laneOrFailure === 'string' ? laneOrFailure : 'direct';
+    const failureAt = typeof laneOrFailure === 'string' ? undefined : laneOrFailure.failureAt;
+    if (failureAt !== undefined) {
+      return err(
+        new EnvironmentGenerationFailedError(
+          frame.source.kind === 'none' ? 'none' : frame.source.sourceKey,
+          failureAt,
+        ),
+      );
+    }
+    const existing = this.candidates.get(frame.signature);
+    if (existing?.scope.isAlive()) {
+      return ok(existing.lane === lane ? existing : this.laneView(existing, lane));
+    }
+    if (existing !== undefined) {
+      this.candidates.delete(frame.signature);
+      this.frames.delete(frame.signature);
+    }
+    const generation = ++this.nextGeneration;
+    const generationScope = this.currentScope.createChild(`environment-${generation}`);
+    const descriptor = frame.resourceDescriptor;
+    const resource =
+      descriptor === undefined
+        ? undefined
+        : generationScope.ref('texture', {
+            signature: frame.signature,
+            generation,
+            descriptor,
+          });
+    const created: EnvironmentGeneration = {
+      signature: frame.signature,
+      generation,
+      lane,
+      scope: generationScope,
+      liveHandle: (resource?.value ?? { signature: frame.signature, generation }) as object,
+      resourceCount: resource === undefined ? 0 : 1,
+      resourceBytes:
+        descriptor === undefined
+          ? 0
+          : descriptor.width * descriptor.height * descriptor.bytesPerPixel,
+      retired: false,
+    };
+    this.candidates.set(frame.signature, created);
+    this.frames.set(frame.signature, frame);
+    return ok(created);
+  }
+
+  publish(generation: EnvironmentGeneration): void {
+    this.candidates.delete(generation.signature);
+    if (this.active !== undefined && this.active !== generation) {
+      this.retired.push({ generation: this.active });
+    }
+    this.active = generation;
+    this.lkg = generation;
+  }
+
+  acquire(): EnvironmentLease {
+    const generation = this.active?.generation ?? -1;
+    this.leaseCounts.set(generation, (this.leaseCounts.get(generation) ?? 0) + 1);
+    let released = false;
+    return {
+      generation,
+      release: () => {
+        if (released) return;
+        released = true;
+        const count = this.leaseCounts.get(generation) ?? 0;
+        if (count <= 1) this.leaseCounts.delete(generation);
+        else this.leaseCounts.set(generation, count - 1);
+      },
+    };
+  }
+
+  collectRetired(): void {
+    for (const entry of this.retired) {
+      if ((this.leaseCounts.get(entry.generation.generation) ?? 0) === 0) {
+        entry.generation.retired = true;
+        entry.generation.scope.retire();
+      }
+    }
+    while (this.retired[0]?.generation.retired === true) this.retired.shift();
+    for (const [signature, generation] of this.candidates) {
+      if (generation.retired) {
+        this.candidates.delete(signature);
+        this.frames.delete(signature);
+      }
+    }
+  }
+
+  inspect(): EnvironmentInspection & {
+    readonly activeSignature: string | undefined;
+    readonly lkgSignature: string | undefined;
+  } {
+    const generation = (
+      value: EnvironmentGeneration | undefined,
+    ): EnvironmentInspectionGeneration | undefined => {
+      if (value === undefined) return undefined;
+      const resourceCount = value.resourceCount;
+      const resourceBytes = value.resourceBytes;
+      const source = this.frames.get(value.signature)?.source.kind ?? 'none';
+      return Object.freeze({
+        signature: value.signature,
+        generation: value.generation,
+        lane: value.lane,
+        source,
+        resourceCount,
+        bytes: resourceBytes,
+        residentBytes: value.retired ? 0 : resourceBytes,
+        retiringBytes: 0,
+      });
+    };
+    const active = generation(this.active);
+    const lkg = generation(this.lkg);
+    const candidate = generation([...this.candidates.values()][0]);
+    const retiringBytes = this.retired.reduce(
+      (bytes, entry) => bytes + (entry.generation.retired ? 0 : entry.generation.resourceBytes),
+      0,
+    );
+    const activeFrame =
+      this.active === undefined ? undefined : this.frames.get(this.active.signature);
+    return inspectEnvironment(this.active, {
+      ...(activeFrame === undefined ? {} : { source: activeFrame.source.kind }),
+      ...(activeFrame?.environmentSignature === undefined
+        ? {}
+        : { environmentSignature: activeFrame.environmentSignature }),
+      ...(activeFrame?.fogSignature === undefined
+        ? {}
+        : { fogSignature: activeFrame.fogSignature }),
+      ...(active === undefined ? {} : { active }),
+      ...(lkg === undefined ? {} : { lkg }),
+      ...(candidate === undefined ? {} : { candidate }),
+      retiringBytes,
+      ...(this.lastCandidateFailure === undefined
+        ? {}
+        : { lastCandidateFailure: this.lastCandidateFailure }),
+    });
+  }
+
+  async recover(
+    scope: DeviceScope,
+  ): Promise<Result<EnvironmentGeneration, EnvironmentGenerationFailedError>> {
+    if (this.active === undefined)
+      return err(new EnvironmentGenerationFailedError('none', 'prepare'));
+    this.currentScope = scope;
+    const previous = this.active;
+    this.candidates.delete(previous.signature);
+    const previousFrame = this.frames.get(previous.signature);
+    if (previousFrame === undefined) {
+      return err(new EnvironmentGenerationFailedError('none', 'prepare'));
+    }
+    const result = await this.ensure(
+      sharedEnvironmentFrame(previousFrame, previous.lane),
+      previous.lane,
+    );
+    if (!result.ok) return result;
+    return ok(result.value);
+  }
+
+  private laneView(
+    generation: EnvironmentGeneration,
+    lane: 'direct' | 'clustered',
+  ): EnvironmentGeneration {
+    return { ...generation, lane };
+  }
+}

package/src/environment/signature.ts

@@ -0,0 +1,55 @@
+import type { EnvironmentCandidate, FogCandidate } from '../extract/environment';
+
+export interface EnvironmentSignatureInput {
+  readonly environments: readonly EnvironmentCandidate[];
+  readonly fogs: readonly FogCandidate[];
+  readonly suns: readonly {
+    readonly entityKey: number;
+    readonly direction: readonly [number, number, number];
+    readonly color: readonly [number, number, number];
+    readonly intensity: number;
+  }[];
+}
+
+export interface EnvironmentFactSignatures {
+  readonly environmentSignature: string;
+  readonly fogSignature: string;
+  readonly signature: string;
+}
+
+function sorted<T extends { readonly entityKey: number }>(items: readonly T[]): readonly T[] {
+  return [...items].sort((left, right) => left.entityKey - right.entityKey);
+}
+
+/** Derive a deterministic source signature without retaining GPU objects. */
+export function environmentSignature(input: EnvironmentSignatureInput): string {
+  return JSON.stringify({
+    environments: sorted(input.environments),
+    fogs: sorted(input.fogs),
+    suns: sorted(input.suns),
+  });
+}
+
+/** Signature for Environment and Sun facts, excluding the independent Fog channel. */
+export function environmentOnlySignature(input: EnvironmentSignatureInput): string {
+  return JSON.stringify({
+    environments: sorted(input.environments),
+    suns: sorted(input.suns),
+  });
+}
+
+/** Signature for the independent Fog channel. */
+export function fogOnlySignature(input: Pick<EnvironmentSignatureInput, 'fogs'>): string {
+  return JSON.stringify({ fogs: sorted(input.fogs) });
+}
+
+/** Build all frame signatures from one immutable source fact set. */
+export function environmentFactSignatures(
+  input: EnvironmentSignatureInput,
+): EnvironmentFactSignatures {
+  return {
+    environmentSignature: environmentOnlySignature(input),
+    fogSignature: fogOnlySignature(input),
+    signature: environmentSignature(input),
+  };
+}