@forgeax/engine-render 0.1.4 → 0.1.7

package/src/environment/lifecycle.ts

@@ -1,124 +0,0 @@
-import type { RhiDevice } from '@forgeax/engine-rhi';
-import type { EnvironmentGenerationState } from './generation';
-import { isEnvironmentGpuBundle } from './gpu-bundle';
-
-export interface EnvironmentLifecycleEvidence {
-  readonly bytes: number;
-  readonly peakBytes: number;
-  readonly retireEvents: number;
-  readonly queueCompletions: number;
-}
-
-export function createEnvironmentLifecycleEvidence(): EnvironmentLifecycleEvidence {
-  return { bytes: 0, peakBytes: 0, retireEvents: 0, queueCompletions: 0 };
-}
-
-export function noteEnvironmentAllocation(
-  evidence: EnvironmentLifecycleEvidence,
-  bytes: number,
-): EnvironmentLifecycleEvidence {
-  const nextBytes = evidence.bytes + bytes;
-  return {
-    ...evidence,
-    bytes: nextBytes,
-    peakBytes: Math.max(evidence.peakBytes, nextBytes),
-  };
-}
-
-export function noteEnvironmentRetire(
-  evidence: EnvironmentLifecycleEvidence,
-): EnvironmentLifecycleEvidence {
-  return { ...evidence, retireEvents: evidence.retireEvents + 1 };
-}
-
-export function noteEnvironmentQueueCompletion(
-  evidence: EnvironmentLifecycleEvidence,
-): EnvironmentLifecycleEvidence {
-  return { ...evidence, queueCompletions: evidence.queueCompletions + 1 };
-}
-
-export function completeEnvironmentQueue(
-  state: EnvironmentGenerationState,
-  queueCompletion: string | number,
-): void {
-  for (const retired of state.retired) {
-    if (!retired.retired && retired.queueCompletion === queueCompletion) retired.retired = true;
-  }
-}
-
-/** Destroy only retired physical bundles after the queue fence is complete. */
-export function destroyCompletedEnvironmentGenerations(
-  state: EnvironmentGenerationState,
-  device: RhiDevice,
-  queueCompletion: string | number,
-): void {
-  for (const retired of state.retired) {
-    if (!retired.retired || retired.destroyed || retired.queueCompletion !== queueCompletion)
-      continue;
-    const handle = retired.record.handle;
-    if (isEnvironmentGpuBundle(handle)) {
-      const destroyed = handle.destroy(device);
-      if (!destroyed.ok) continue;
-    }
-    retired.destroyed = true;
-  }
-}
-
-export function abandonEnvironmentDevice(
-  state: EnvironmentGenerationState,
-  deviceGeneration: string | number,
-): void {
-  if (state.deviceGeneration !== deviceGeneration) return;
-  state.candidate = undefined;
-  state.active = undefined;
-  state.lastKnownGood = undefined;
-  state.bytes = 0;
-  state.failureStage = 'device-lost';
-  state.status = 'failed';
-  for (const retired of state.retired) retired.retired = true;
-}
-
-/** Re-arm the same Renderer owner against a new device without carrying refs across it. */
-export function recoverEnvironmentDevice(
-  state: EnvironmentGenerationState,
-  deviceGeneration: string | number,
-): void {
-  state.deviceGeneration = deviceGeneration;
-  state.candidate = undefined;
-  state.active = undefined;
-  state.lastKnownGood = undefined;
-  state.retired.length = 0;
-  state.failureStage = undefined;
-  state.status = 'idle';
-  state.bytes = 0;
-  state.peakBytes = 0;
-  state.rebuildCost = 0;
-  state.publishCount = 0;
-}
-
-/** Resize is a same-device replacement boundary; no old bundle remains visible. */
-export function resizeEnvironmentGeneration(
-  state: EnvironmentGenerationState,
-  deviceGeneration: string | number = state.deviceGeneration,
-): void {
-  if (state.status === 'disposed') return;
-  for (const retired of state.retired) retired.retired = true;
-  state.deviceGeneration = deviceGeneration;
-  state.desired = undefined;
-  state.candidate = undefined;
-  state.active = undefined;
-  state.lastKnownGood = undefined;
-  state.retired.length = 0;
-  state.failureStage = undefined;
-  state.status = 'idle';
-  state.bytes = 0;
-}
-
-export function disposeEnvironmentGeneration(state: EnvironmentGenerationState): void {
-  state.candidate = undefined;
-  state.active = undefined;
-  state.lastKnownGood = undefined;
-  state.bytes = 0;
-  state.status = 'disposed';
-  for (const retired of state.retired) retired.retired = true;
-}

package/src/environment/readiness.ts

@@ -1,76 +0,0 @@
-import type { RhiDevice } from '@forgeax/engine-rhi';
-import { err, ok, type Result } from '@forgeax/engine-types';
-import { AtmosphereCapsInsufficientError, AtmosphereProducerFailedError } from '../errors/render';
-
-export const ATMOSPHERE_CAPABILITY_OPERATIONS = [
-  'renderAttachment',
-  'sample',
-  'filter',
-  'mip',
-  'face',
-] as const;
-
-export type AtmosphereCapabilityOperation = (typeof ATMOSPHERE_CAPABILITY_OPERATIONS)[number];
-export type AtmosphereBackendKind = RhiDevice['caps']['backendKind'];
-export type AtmosphereCapabilityStatus = 'pass' | 'partial' | 'unavailable' | 'structural-only';
-
-export interface AtmosphereMatrixBackend {
-  readonly status: AtmosphereCapabilityStatus;
-  readonly [operation: string]: string | AtmosphereCapabilityStatus | undefined;
-}
-
-export interface AtmosphereCapabilityMatrix {
-  readonly format: 'rgba16float';
-  readonly backends: Readonly<Record<string, AtmosphereMatrixBackend>>;
-}
-
-export interface AtmosphereReadiness {
-  readonly backendKind: AtmosphereBackendKind;
-  readonly status: 'ready';
-  readonly operations: readonly AtmosphereCapabilityOperation[];
-}
-
-const matrixBackendName = (backend: AtmosphereBackendKind): string =>
-  backend === 'webgpu' ? 'browser-webgpu' : backend === 'wgpu-native' ? 'dawn-node' : backend;
-
-/**
- * Consume the immutable M0 matrix and fail closed. This function does not
- * mirror RhiCaps and does not create any shader, pipeline, or bundle. The
- * actual producer calls it only from its lazy readiness path.
- */
-export function admitAtmosphereCapability(
-  matrix: AtmosphereCapabilityMatrix,
-  backendKind: AtmosphereBackendKind,
-): Result<AtmosphereReadiness, AtmosphereCapsInsufficientError | AtmosphereProducerFailedError> {
-  const backend = matrix.backends[matrixBackendName(backendKind)];
-  if (backend === undefined || backend.status !== 'pass') {
-    return err(
-      new AtmosphereCapsInsufficientError(
-        `backend.${matrixBackendName(backendKind)}.status`,
-        backend?.status === 'pass',
-        true,
-      ),
-    );
-  }
-  for (const operation of ATMOSPHERE_CAPABILITY_OPERATIONS) {
-    if (backend[operation] !== 'pass') {
-      return err(
-        new AtmosphereCapsInsufficientError(
-          `backend.${matrixBackendName(backendKind)}.${operation}`,
-          backend[operation] === 'pass',
-          true,
-        ),
-      );
-    }
-  }
-  return ok({ backendKind, status: 'ready', operations: ATMOSPHERE_CAPABILITY_OPERATIONS });
-}
-
-/** Map a live producer stage failure without treating it as a capability gap. */
-export function atmosphereProducerFailure(
-  stage: 'build' | 'execute' | 'submit',
-  reason: string,
-  generation?: number,
-): Result<never, AtmosphereProducerFailedError> {
-  return err(new AtmosphereProducerFailedError(stage, reason, generation));
-}

package/src/environment/signature.ts

@@ -1,185 +0,0 @@
-import type { Vec3 } from '@forgeax/engine-math';
-
-export interface EnvironmentSignatureInput {
-  readonly atmosphere: {
-    readonly turbidity: number;
-    readonly rayleigh: number;
-    readonly mieCoefficient: number;
-    readonly mieDirectionalG: number;
-    readonly sunAngularRadius: number;
-  };
-  readonly sun: {
-    readonly direction: Vec3 | readonly [number, number, number];
-    readonly color: Vec3 | readonly [number, number, number];
-    readonly illuminance: number;
-  };
-  readonly quality: EnvironmentQuality;
-  readonly algorithmRevision: string;
-  readonly worldId: number;
-  readonly entity: number;
-  readonly deviceGeneration: number;
-  readonly outputFormat: EnvironmentOutputFormat;
-}
-
-export interface EnvironmentQuality {
-  readonly skySize: number;
-  readonly irradianceSize: number;
-  readonly prefilterMips: number;
-}
-
-/** Analytic sky is an HDR producer. LDR fallback would silently change the
- * radiometry contract and is intentionally not part of this union. */
-export type EnvironmentOutputFormat = 'rgba16float';
-export type EnvironmentSignature = string & { readonly __environmentSignature: unique symbol };
-
-const floatBuffer = new ArrayBuffer(4);
-const floatView = new DataView(floatBuffer);
-
-function floatBits(value: number): string {
-  floatView.setFloat32(0, value, true);
-  return floatView.getUint32(0, true).toString(16).padStart(8, '0');
-}
-
-function numberBits(value: number): string {
-  return floatBits(value);
-}
-
-function textBits(value: string): string {
-  return `${value.length}:${value}`;
-}
-
-function component(value: ArrayLike<number>, index: number): number {
-  return value[index] ?? 0;
-}
-
-function normalize(value: ArrayLike<number>): readonly [number, number, number] {
-  const x = component(value, 0);
-  const y = component(value, 1);
-  const z = component(value, 2);
-  const length = Math.hypot(x, y, z);
-  if (!(length > 1e-6) || !Number.isFinite(length)) return [0, 0, 0];
-  return [x / length, y / length, z / length];
-}
-
-/**
- * Canonical output identity. Float32 bit patterns are used deliberately: a
- * rounded JSON representation cannot distinguish the values that reach a GPU
- * uniform, while this identity must invalidate the candidate on those changes.
- */
-export function environmentSignature(input: EnvironmentSignatureInput): EnvironmentSignature {
-  const direction = normalize(input.sun.direction);
-  const chunks = [
-    'environment-signature-v1',
-    textBits(input.algorithmRevision),
-    numberBits(input.atmosphere.turbidity),
-    numberBits(input.atmosphere.rayleigh),
-    numberBits(input.atmosphere.mieCoefficient),
-    numberBits(input.atmosphere.mieDirectionalG),
-    numberBits(input.atmosphere.sunAngularRadius),
-    numberBits(direction[0]),
-    numberBits(direction[1]),
-    numberBits(direction[2]),
-    numberBits(component(input.sun.color, 0)),
-    numberBits(component(input.sun.color, 1)),
-    numberBits(component(input.sun.color, 2)),
-    numberBits(input.sun.illuminance),
-    String(input.quality.skySize),
-    String(input.quality.irradianceSize),
-    String(input.quality.prefilterMips),
-    String(input.worldId),
-    String(input.entity),
-    String(input.deviceGeneration),
-    textBits(input.outputFormat),
-  ];
-  return chunks.join('|') as EnvironmentSignature;
-}
-
-export { floatBits as canonicalEnvironmentFloatBits };
-
-const bytesPerTexelFor = (_format: EnvironmentOutputFormat): 8 => 8;
-
-export interface EnvironmentCubeDescriptor {
-  readonly kind: 'sky' | 'irradiance' | 'prefilter';
-  readonly width: number;
-  readonly height: number;
-  readonly mipLevel: number;
-  readonly arrayLayers: 6;
-  readonly format: EnvironmentOutputFormat;
-  readonly usage: readonly ['render-attachment', 'texture-binding'];
-}
-
-export interface EnvironmentCubeFace {
-  readonly kind: EnvironmentCubeDescriptor['kind'];
-  readonly mipLevel: number;
-  readonly face: 0 | 1 | 2 | 3 | 4 | 5;
-  readonly width: number;
-  readonly height: number;
-  readonly bytes: number;
-}
-
-export interface EnvironmentBundleDescriptors {
-  readonly sky: EnvironmentCubeDescriptor;
-  readonly irradiance: EnvironmentCubeDescriptor;
-  readonly prefilter: EnvironmentCubeDescriptor;
-  readonly mips: readonly EnvironmentCubeDescriptor[];
-  readonly faces: readonly EnvironmentCubeFace[];
-  readonly bytesPerTexel: 8 | 4;
-  readonly logicalBytes: number;
-}
-
-function cubeDescriptor(
-  kind: EnvironmentCubeDescriptor['kind'],
-  size: number,
-  mipLevel: number,
-  format: EnvironmentOutputFormat,
-): EnvironmentCubeDescriptor {
-  return {
-    kind,
-    width: size,
-    height: size,
-    mipLevel,
-    arrayLayers: 6,
-    format,
-    usage: ['render-attachment', 'texture-binding'],
-  };
-}
-
-export function deriveEnvironmentBundleDescriptors(
-  quality: EnvironmentQuality,
-  format: EnvironmentOutputFormat,
-): EnvironmentBundleDescriptors {
-  const bytesPerTexel = bytesPerTexelFor(format);
-  const sky = cubeDescriptor('sky', quality.skySize, 0, format);
-  const irradiance = cubeDescriptor('irradiance', quality.irradianceSize, 0, format);
-  const mips = Array.from({ length: quality.prefilterMips }, (_, mipLevel) =>
-    cubeDescriptor('prefilter', Math.max(1, quality.skySize >> mipLevel), mipLevel, format),
-  );
-  const descriptors = [sky, irradiance, ...mips];
-  const faces = descriptors.flatMap((descriptor) =>
-    Array.from({ length: 6 }, (_, face) => ({
-      kind: descriptor.kind,
-      mipLevel: descriptor.mipLevel,
-      face: face as EnvironmentCubeFace['face'],
-      width: descriptor.width,
-      height: descriptor.height,
-      bytes: descriptor.width * descriptor.height * bytesPerTexel,
-    })),
-  );
-  return {
-    sky,
-    irradiance,
-    prefilter: mips[0] as EnvironmentCubeDescriptor,
-    mips,
-    faces,
-    bytesPerTexel,
-    logicalBytes: faces.reduce((total, face) => total + face.bytes, 0),
-  };
-}
-
-/** Recompute logical inspection bytes from raw descriptor roster, independently. */
-export function environmentBundleBytes(descriptors: EnvironmentBundleDescriptors): number {
-  return descriptors.faces.reduce(
-    (total, face) => total + face.width * face.height * descriptors.bytesPerTexel,
-    0,
-  );
-}