@forgeax/engine-render 0.1.6 → 0.1.19

package/src/construct-renderer.ts

@@ -1,5 +1,5 @@
 import type { AssetRegistry } from '@forgeax/engine-assets-runtime';
-import type { RhiBackendPack } from './assembly/backend-contract';
+import { EngineEnvironmentError, type RhiBackendPack } from './assembly/backend-contract';
 import type { BundlerOptions } from './assembly/factory';
 import { createRenderer, exposeRenderer } from './assembly/factory';
 import type {
@@ -30,12 +30,46 @@ export interface RendererHostAssembly {
   readonly assets: AssetRegistry;
 }
 
+function describeRendererInitializationFailure(error: unknown): string {
+  const candidate = error as unknown as {
+    readonly code?: unknown;
+    readonly hint?: unknown;
+    readonly detail?: unknown;
+  };
+  const detail = candidate.detail;
+  if (typeof detail === 'object' && detail !== null && 'compilerMessages' in detail) {
+    const messages = (detail as { readonly compilerMessages?: unknown }).compilerMessages;
+    if (Array.isArray(messages)) {
+      const compilerMessages = messages.map((message) => {
+        const value = message as {
+          readonly message?: unknown;
+          readonly type?: unknown;
+          readonly lineNum?: unknown;
+          readonly linePos?: unknown;
+          readonly offset?: unknown;
+          readonly length?: unknown;
+        };
+        return {
+          message: value.message,
+          type: value.type,
+          lineNum: value.lineNum,
+          linePos: value.linePos,
+          offset: value.offset,
+          length: value.length,
+        };
+      });
+      return `${String(candidate.code)}: ${String(candidate.hint)}; detail=${JSON.stringify({ compilerMessages })}`;
+    }
+  }
+  return `${String(candidate.code)}: ${String(candidate.hint)}; detail=${JSON.stringify(detail)}`;
+}
+
 export async function constructRendererHost(
   canvas: unknown,
   options?: RendererOptions,
   bundler?: BundlerOptions,
   backend?: RhiBackendPack,
-): Promise<RenderResult<RendererHostAssembly, RenderError>> {
+): Promise<RenderResult<RendererHostAssembly, RenderError | EngineEnvironmentError>> {
   try {
     const implementation = await createRenderer(canvas, options, bundler, backend);
     const ready = await implementation.initialization;
@@ -44,7 +78,7 @@ export async function constructRendererHost(
         ok: false,
         error: new RendererContractFailureError(
           'construct',
-          `${ready.error.code}: ${ready.error.hint}`,
+          describeRendererInitializationFailure(ready.error),
         ),
       };
     }
@@ -58,6 +92,9 @@ export async function constructRendererHost(
       },
     };
   } catch (cause) {
+    if (cause instanceof EngineEnvironmentError) {
+      return { ok: false, error: cause };
+    }
     const detail = cause instanceof Error ? cause.message : String(cause);
     return {
       ok: false,

package/src/device/device-scope.ts

@@ -77,6 +77,15 @@ export class DeviceScope {
     return [...this.children];
   }
 
+  /** Create a renderer-owned child scope without exposing a second device owner. */
+  createChild(owner: string): DeviceScope {
+    if (this.lifecycleState !== 'active') {
+      throw new Error('Cannot create a child DeviceScope from an inactive scope.');
+    }
+    if (owner.length === 0) throw new TypeError('DeviceScope child owner must not be empty.');
+    return new DeviceScope(this.generation, owner, this);
+  }
+
   ref<T>(kind: DeviceResourceKind, value: T): ResourceRef<T> {
     const ref = new DeviceResourceRef(kind, this.owner, this.generation, value);
     this.resources.push({ ref: ref as DeviceResourceRef<unknown>, cleanup: () => undefined });
@@ -128,8 +137,13 @@ export class DeviceScope {
     return resources;
   }
 
+  /** Mark an active child as retiring without releasing in-flight resources. */
+  beginRetire(): void {
+    if (this.lifecycleState === 'active') this.lifecycleState = 'retiring';
+  }
+
   retire(): void {
-    if (this.lifecycleState !== 'active') return;
+    if (this.lifecycleState !== 'active' && this.lifecycleState !== 'retiring') return;
     this.lifecycleState = 'retiring';
     this._clearResources();
     this.lifecycleState = 'retired';

package/src/environment/frame.ts

@@ -0,0 +1,185 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { EnvironmentSourceConflictError, FogCardinalityError } from '../errors/render';
+import type {
+  EnvironmentCandidate,
+  EnvironmentFrame,
+  EnvironmentSource,
+  FogCandidate,
+  FogFrame,
+} from '../extract/environment';
+import { validateAtmosphereParameters } from '../extract/environment';
+import { environmentFactSignatures } from './signature';
+
+export type { EnvironmentCandidate, EnvironmentFrame, EnvironmentSource, FogCandidate, FogFrame };
+
+export interface SunCandidate {
+  readonly entityKey: number;
+  readonly direction: readonly [number, number, number];
+  readonly color: readonly [number, number, number];
+  readonly intensity: number;
+}
+
+export interface EnvironmentSelectionInput {
+  readonly environments: readonly EnvironmentCandidate[];
+  readonly fogs: readonly FogCandidate[];
+  readonly suns: readonly SunCandidate[];
+  readonly lane: 'direct' | 'clustered';
+}
+
+export interface EnvironmentSelectionParameterDetail {
+  readonly field: string;
+  readonly value: number;
+}
+
+export class EnvironmentSelectionParameterError extends Error {
+  readonly code = 'environment-selection-invalid' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: EnvironmentSelectionParameterDetail;
+
+  constructor(field: string, value: number, expected: string) {
+    super(`environment selection field ${field} is invalid`);
+    this.name = 'EnvironmentSelectionParameterError';
+    this.expected = expected;
+    this.hint = `set ${field} to a finite value satisfying ${expected}`;
+    this.detail = { field, value };
+  }
+}
+
+export interface SunCardinalityDetail {
+  readonly field: 'sun';
+  readonly value: number;
+}
+
+export class SunCardinalityError extends Error {
+  readonly code = 'sun-cardinality' as const;
+  readonly expected = 'atmosphere has exactly one sun owner';
+  readonly hint = 'add exactly one DirectionalLight sun for the atmosphere owner';
+  readonly detail: SunCardinalityDetail;
+
+  constructor(value: number) {
+    super(`atmosphere sun cardinality is ${value}`);
+    this.name = 'SunCardinalityError';
+    this.detail = { field: 'sun', value };
+  }
+}
+
+export interface EnvironmentSelectionErrorDetail {
+  readonly owners?: readonly {
+    readonly kind: 'image' | 'atmosphere';
+    readonly entityKey: number;
+    readonly sourceKey: string;
+  }[];
+  readonly field?: string;
+  readonly value?: number;
+  readonly count?: number;
+}
+
+export interface EnvironmentSelectionError {
+  readonly code:
+    | 'environment-source-conflict'
+    | 'fog-cardinality'
+    | 'environment-selection-invalid'
+    | 'atmosphere-invalid-parameter'
+    | 'sun-cardinality';
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: EnvironmentSelectionErrorDetail;
+}
+
+export interface SelectedEnvironmentFrame extends EnvironmentFrame {
+  readonly sun: SunCandidate | undefined;
+  readonly lane: 'direct' | 'clustered';
+}
+
+function freezeCandidate<T extends object>(candidate: T): T {
+  return Object.freeze(candidate);
+}
+
+function freezeFog(candidate: FogCandidate): FogFrame {
+  return Object.freeze({
+    ...candidate,
+    color: Object.freeze([...candidate.color] as unknown as FogFrame['color']),
+  });
+}
+
+function validFog(candidate: FogCandidate): boolean {
+  return (
+    candidate.color.every(Number.isFinite) &&
+    Number.isFinite(candidate.density) &&
+    candidate.density >= 0 &&
+    Number.isFinite(candidate.heightFalloff) &&
+    candidate.heightFalloff >= 0 &&
+    Number.isFinite(candidate.maxOpacity) &&
+    candidate.maxOpacity >= 0 &&
+    candidate.maxOpacity <= 1
+  );
+}
+
+/** Select one immutable frame fact set for both Standard lighting lanes. */
+export function selectEnvironment(
+  input: EnvironmentSelectionInput,
+): Result<SelectedEnvironmentFrame, EnvironmentSelectionError> {
+  if (input.environments.length > 1) {
+    return err(
+      new EnvironmentSourceConflictError(
+        [...input.environments]
+          .sort((left, right) => left.entityKey - right.entityKey)
+          .map(({ kind, entityKey, sourceKey }) => ({ kind, entityKey, sourceKey })),
+      ),
+    );
+  }
+  if (input.fogs.length > 1) return err(new FogCardinalityError(input.fogs.length));
+  const selectedFog = input.fogs[0];
+  if (selectedFog !== undefined && !validFog(selectedFog)) {
+    const field =
+      !Number.isFinite(selectedFog.density) || selectedFog.density < 0
+        ? 'density'
+        : !Number.isFinite(selectedFog.heightFalloff) || selectedFog.heightFalloff < 0
+          ? 'heightFalloff'
+          : 'maxOpacity';
+    return err(
+      new EnvironmentSelectionParameterError(field, selectedFog[field], 'finite and in range'),
+    );
+  }
+  const selected = input.environments[0];
+  if (selected?.kind === 'atmosphere') {
+    const invalid = validateAtmosphereParameters(selected.atmosphere);
+    if (invalid !== undefined) return err(invalid);
+  }
+  if (selected?.kind === 'atmosphere' && input.suns.length !== 1) {
+    return err(new SunCardinalityError(input.suns.length));
+  }
+  const source: EnvironmentSource =
+    selected === undefined
+      ? { kind: 'none' }
+      : selected.kind === 'atmosphere'
+        ? {
+            kind: 'atmosphere',
+            entityKey: selected.entityKey,
+            sourceKey: selected.sourceKey,
+            atmosphere: Object.freeze({ ...selected.atmosphere }),
+          }
+        : {
+            kind: 'image',
+            entityKey: selected.entityKey,
+            sourceKey: selected.sourceKey,
+          };
+  const sun = input.suns[0] === undefined ? undefined : freezeCandidate({ ...input.suns[0] });
+  const fog = selectedFog === undefined ? undefined : freezeFog(selectedFog);
+  const signatureInput = {
+    environments: selected === undefined ? [] : [selected],
+    fogs: selectedFog === undefined ? [] : [selectedFog],
+    suns: input.suns,
+  };
+  const signatures = environmentFactSignatures(signatureInput);
+  const result = {
+    source: Object.freeze(source),
+    fog,
+    ...signatures,
+    revision: 0,
+    sun,
+  } as SelectedEnvironmentFrame;
+  Object.defineProperty(result, 'lane', { value: input.lane, enumerable: false });
+  return ok(Object.freeze(result));
+}

package/src/environment/generation.ts

@@ -0,0 +1,23 @@
+import type { DeviceScope } from '../device/device-scope';
+import type { EnvironmentFrame } from './frame';
+
+export interface EnvironmentGeneration {
+  readonly signature: string;
+  readonly generation: number;
+  readonly lane: 'direct' | 'clustered';
+  readonly scope: DeviceScope;
+  readonly liveHandle: object;
+  readonly resourceCount: number;
+  readonly resourceBytes: number;
+  retired: boolean;
+}
+
+export interface EnvironmentGenerationFailure {
+  readonly failureAt?: 'prepare' | 'build' | 'execute' | 'finish' | 'submit';
+}
+
+export interface EnvironmentGenerationState {
+  readonly frame: EnvironmentFrame;
+  readonly scope: DeviceScope;
+  readonly generation: number;
+}

package/src/environment/graph.ts

@@ -0,0 +1,9 @@
+import type { EnvironmentFrame } from './frame';
+
+/** Both Standard lanes consume the same selected CPU environment facts. */
+export function sharedEnvironmentFrame(
+  frame: EnvironmentFrame,
+  _lane: 'direct' | 'clustered',
+): EnvironmentFrame {
+  return frame;
+}

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 };
+  }
+}