@forgeax/engine-render 0.1.7 → 0.1.20

package/src/device/gpu-residency.ts

@@ -60,6 +60,7 @@ import {
   type AssetError,
   countExtraUvSets,
   type DecodedImage,
+  deriveTextureLayout,
   type EquirectAsset,
   type Handle,
   handleSlot,
@@ -72,6 +73,7 @@ import {
   type SamplerAsset,
   type Submesh,
   type TextureAsset,
+  type TextureShape,
   type MeshAsset as TypesMeshAsset,
   toShared,
 } from '@forgeax/engine-types';
@@ -98,7 +100,6 @@ import {
 import type { RhiErrorListenerRegistry } from '../lifecycle';
 import {
   type CubeRenderData,
-  deriveMipUploadLayout,
   deriveRenderDataCubemap,
   deriveRenderDataMesh,
   deriveRenderDataTexture,
@@ -281,10 +282,25 @@ type RegisterCube = (
 // not destroyable on their own; their lifetime is bound to the parent
 // GpuTexture, which the wrapper owns. destroyAll() walks the GpuResource
 // fields and forwards .destroy() to the RHI shim.
-interface TextureGpuEntry {
+export interface TextureResidencyReceipt {
+  readonly shape: TextureShape;
+  readonly format: GPUTextureFormat;
+  readonly extent: {
+    readonly width: number;
+    readonly height: number;
+    readonly depthOrArrayLayers: number;
+  };
+  readonly bytes: number;
+  readonly view: '2d' | '2d-array' | '3d';
+  readonly generation: number;
+  readonly deviceEpoch: number;
+}
+
+export interface TextureGpuEntry {
   readonly texture: GpuTexture;
   /** Opaque RHI view handle; lifetime is bound to the parent texture. */
   readonly view: TextureView;
+  readonly receipt: TextureResidencyReceipt;
 }
 
 // feat-20260630-equirect-kind-internalized-ibl-declarative-skyligh M2 / w11
@@ -388,6 +404,8 @@ export class GpuResidencyCache {
   // Hardware-probe caps injected at `configureGpuDevice`; guards the HDR cubemap
   // path (_uploadCubemapFromEquirect) when `rgba16floatRenderable` is false.
   private caps: RhiCaps | undefined = undefined;
+  private deviceEpoch = 0;
+  private textureGeneration = 0;
 
   private readonly textureGpuHandles: Map<string | number, TextureGpuEntry> = new Map();
   private readonly samplerGpuHandles: Map<string | number, Sampler> = new Map();
@@ -432,6 +450,12 @@ export class GpuResidencyCache {
     registerCube: RegisterCube,
     caps: RhiCaps,
   ): void {
+    for (const entry of this.textureGpuHandles.values()) {
+      if (!entry.texture.isDestroyed) entry.texture.destroy();
+    }
+    if (this.textureGpuHandles.size > 0) this.materialResourceEpoch += 1;
+    this.textureGpuHandles.clear();
+    this.deviceEpoch += 1;
     this.meshResidencyEpoch += 1;
     this.gpuDevice = device;
     this.asyncCreateShaderModule = asyncCreateShaderModule;
@@ -997,7 +1021,7 @@ export class GpuResidencyCache {
     const cacheKey = this.worldKey(handleSlot(handle), worldId);
     if (gpuTexture === undefined) return ok(undefined);
 
-    if (!projected.value.compressed && decoded.mipmap === true && levels > 1) {
+    if (!projected.value.compressed && tex.mips.kind === 'generate' && levels > 1) {
       const factory = this.asyncCreateShaderModule;
       if (factory === undefined) {
         return err(
@@ -1020,8 +1044,8 @@ export class GpuResidencyCache {
       }
       const blitRes = blitMipmapsSync(device, gpuTexture, {
         format: tex.format,
-        width: tex.width,
-        height: tex.height,
+        width: tex.shape.extent.width,
+        height: tex.shape.extent.height,
         levels,
       });
       if (!blitRes.ok) return blitRes as Result<void, RhiError>;
@@ -1029,13 +1053,14 @@ export class GpuResidencyCache {
 
     const viewRes = device.createTextureView(gpuTexture, {
       label: `texture-view-${cacheKey}`,
-      dimension: '2d',
+      dimension: projected.value.shape.viewDimension,
     });
     if (!viewRes.ok) return viewRes;
     const previous = this.textureGpuHandles.get(cacheKey);
-    const next = {
+    const next: TextureGpuEntry = {
       texture: this.wrapTex(gpuTexture),
       view: viewRes.value,
+      receipt: this.textureReceipt(pod, projected.value),
     };
     this.textureGpuHandles.set(cacheKey, next);
     this.materialResourceEpoch += 1;
@@ -1077,11 +1102,11 @@ export class GpuResidencyCache {
     const { tex, levels, gpuTexture } = prepared.value;
     const cacheKey = this.worldKey(handleSlot(handle), worldId);
 
-    if (!renderData.compressed && decoded.mipmap === true && levels > 1) {
+    if (!renderData.compressed && tex.mips.kind === 'generate' && levels > 1) {
       const blitRes = blitMipmapsSync(device, gpuTexture, {
         format: tex.format,
-        width: tex.width,
-        height: tex.height,
+        width: tex.shape.extent.width,
+        height: tex.shape.extent.height,
         levels,
       });
       if (!blitRes.ok) return blitRes as Result<TextureGpuEntry, RhiError>;
@@ -1089,10 +1114,14 @@ export class GpuResidencyCache {
 
     const viewRes = device.createTextureView(gpuTexture, {
       label: `texture-view-${cacheKey}`,
-      dimension: '2d',
+      dimension: renderData.shape.viewDimension,
     });
     if (!viewRes.ok) return viewRes;
-    const entry: TextureGpuEntry = { texture: this.wrapTex(gpuTexture), view: viewRes.value };
+    const entry: TextureGpuEntry = {
+      texture: this.wrapTex(gpuTexture),
+      view: viewRes.value,
+      receipt: this.textureReceipt(pod, renderData),
+    };
     const previous = this.textureGpuHandles.get(cacheKey);
     this.textureGpuHandles.set(cacheKey, entry);
     this.materialResourceEpoch += 1;
@@ -1106,6 +1135,25 @@ export class GpuResidencyCache {
     return ok(entry);
   }
 
+  private textureReceipt(
+    pod: TextureAsset,
+    renderData: TextureRenderData,
+  ): TextureResidencyReceipt {
+    return {
+      shape: pod.shape,
+      format: renderData.format,
+      extent: {
+        width: renderData.physicalExtent.width,
+        height: renderData.physicalExtent.height,
+        depthOrArrayLayers: renderData.depthOrArrayLayers,
+      },
+      bytes: pod.data.byteLength,
+      view: renderData.shape.viewDimension,
+      generation: ++this.textureGeneration,
+      deviceEpoch: this.deviceEpoch,
+    };
+  }
+
   /**
    * Shared texture-upload prelude: format / colorSpace consistency assertion,
    * GPU texture allocation + writeTexture. Returns `gpuTexture: undefined`
@@ -1155,13 +1203,21 @@ export class GpuResidencyCache {
     // upload before allocating a handle; binding a texture that the backend
     // accepted syntactically but cannot use later surfaces only as a generic
     // invalid-bind-group submit error.
-    const maxDimension = device.limits.maxTextureDimension2D;
-    if (tex.width > maxDimension || tex.height > maxDimension) {
+    const maxDimension =
+      tex.shape.viewDimension === '3d'
+        ? device.limits.maxTextureDimension3D
+        : device.limits.maxTextureDimension2D;
+    const width = tex.shape.extent.width;
+    const height = tex.shape.extent.height;
+    const layers = renderData.depthOrArrayLayers;
+    const exceedsLayerLimit =
+      tex.shape.viewDimension === '2d-array' && layers > device.limits.maxTextureArrayLayers;
+    if (width > maxDimension || height > maxDimension || exceedsLayerLimit) {
       return err(
         makeImageError({
           code: 'image-dimension-out-of-bounds',
-          requested: { width: tex.width, height: tex.height },
-          limit: maxDimension,
+          requested: { width, height },
+          limit: exceedsLayerLimit ? device.limits.maxTextureArrayLayers : maxDimension,
         }),
       );
     }
@@ -1171,11 +1227,11 @@ export class GpuResidencyCache {
       size: {
         width: renderData.physicalExtent.width,
         height: renderData.physicalExtent.height,
-        depthOrArrayLayers: 1,
+        depthOrArrayLayers: renderData.depthOrArrayLayers,
       },
       mipLevelCount: levels,
       sampleCount: 1,
-      dimension: '2d',
+      dimension: tex.shape.viewDimension === '3d' ? '3d' : '2d',
       format: renderData.format,
       usage: renderData.usage,
       viewFormats: [],
@@ -1193,28 +1249,77 @@ export class GpuResidencyCache {
       // block math). Full-subresource copies retain their logical size, including
       // non-block-aligned dimensions. queue.writeTexture avoids the 256 B
       // copyBufferToTexture alignment trap.
-      const layout = deriveMipUploadLayout(renderData.format, tex.width, tex.height, levels);
-      for (const lvl of layout) {
-        const slice = decoded.bytes.subarray(lvl.byteOffset, lvl.byteOffset + lvl.byteLength);
-        const writeRes = queue.writeTexture(
-          { texture: gpuTexture, mipLevel: lvl.level, origin: { x: 0, y: 0, z: 0 } },
-          slice,
-          { offset: 0, bytesPerRow: lvl.bytesPerRow, rowsPerImage: lvl.rowsPerImage },
-          { width: lvl.copyWidth, height: lvl.copyHeight, depthOrArrayLayers: 1 },
+      const layout = deriveTextureLayout({
+        shape: tex.shape,
+        format: renderData.format,
+        mips: tex.mips,
+      });
+      if (!layout.ok) {
+        return err(
+          makeAssetError({
+            code: 'invalid-source-format',
+            expected: layout.error.expected,
+            hint: layout.error.hint,
+          }),
         );
-        if (!writeRes.ok) return writeRes;
+      }
+      for (const level of layout.value.levels) {
+        for (let image = 0; image < level.imagesPerMip; image++) {
+          const imageBytes = level.bytesPerRow * level.rowsPerImage;
+          const offset = level.byteOffset + image * imageBytes;
+          const slice = decoded.bytes.subarray(offset, offset + imageBytes);
+          const writeRes = queue.writeTexture(
+            {
+              texture: gpuTexture,
+              mipLevel: level.level,
+              origin: { x: 0, y: 0, z: image },
+            },
+            slice,
+            { offset: 0, bytesPerRow: level.bytesPerRow, rowsPerImage: level.rowsPerImage },
+            {
+              width: level.physicalWidth,
+              height: level.physicalHeight,
+              depthOrArrayLayers: 1,
+            },
+          );
+          if (!writeRes.ok) return writeRes;
+        }
       }
       return ok({ id, tex, levels, gpuTexture });
     }
 
     // Uncompressed base-mip write; higher mips (when mipmap) are GPU-generated by
     // the caller's blit pass. rowsPerImage is the pixel height for linear RGBA.
-    const bytesPerRow = renderData.bytesPerRow;
+    const textureLayout = deriveTextureLayout({
+      shape: tex.shape,
+      format: renderData.format,
+      mips: tex.mips,
+    });
+    if (!textureLayout.ok) {
+      return err(
+        makeAssetError({
+          code: 'invalid-source-format',
+          expected: textureLayout.error.expected,
+          hint: textureLayout.error.hint,
+        }),
+      );
+    }
+    const baseLevel = textureLayout.value.levels[0];
+    if (baseLevel === undefined) {
+      return err(
+        makeAssetError({
+          code: 'invalid-source-format',
+          expected: 'texture layout contains a base mip level',
+          hint: ASSET_ERROR_HINTS['invalid-source-format'],
+        }),
+      );
+    }
+    const bytesPerRow = baseLevel.bytesPerRow;
     const writeTextureRes = queue.writeTexture(
       { texture: gpuTexture, mipLevel: 0, origin: { x: 0, y: 0, z: 0 } },
       decoded.bytes,
-      { offset: 0, bytesPerRow, rowsPerImage: tex.height },
-      { width: tex.width, height: tex.height, depthOrArrayLayers: 1 },
+      { offset: 0, bytesPerRow, rowsPerImage: height },
+      { width, height, depthOrArrayLayers: renderData.depthOrArrayLayers },
     );
     if (!writeTextureRes.ok) return writeTextureRes;
 
@@ -1333,14 +1438,21 @@ export class GpuResidencyCache {
     // / format / data / colorSpace) but has no CPU mip chain, so the derived
     // texture view declares `mipmap:false` (the IBL prefilter mip chain is a
     // GPU-side pass, not a CPU-authored level set).
+    const sourceData =
+      sourcePod.data instanceof Uint8ClampedArray
+        ? new Uint8Array(
+            sourcePod.data.buffer,
+            sourcePod.data.byteOffset,
+            sourcePod.data.byteLength,
+          )
+        : sourcePod.data;
     const sourceTex: TextureAsset = {
       kind: 'texture',
-      width: sourcePod.width,
-      height: sourcePod.height,
+      shape: { viewDimension: '2d', extent: { width: sourcePod.width, height: sourcePod.height } },
       format: sourcePod.format,
-      data: sourcePod.data,
+      data: sourceData,
       colorSpace: sourcePod.colorSpace,
-      mipmap: false,
+      mips: { kind: 'none' },
     };
 
     // Project the equirect source POD into the cubemap descriptor (D-5): the
@@ -1365,20 +1477,11 @@ export class GpuResidencyCache {
     const tex: TextureAsset = projected.needsHalfConversion
       ? {
           kind: 'texture',
-          width: sourceTex.width,
-          height: sourceTex.height,
+          shape: sourceTex.shape,
           format: projected.outputFormat,
-          data: halfFloat.f32ToF16Bytes(
-            sourceTex.data instanceof Uint8ClampedArray
-              ? new Uint8Array(
-                  sourceTex.data.buffer,
-                  sourceTex.data.byteOffset,
-                  sourceTex.data.byteLength,
-                )
-              : sourceTex.data,
-          ),
+          data: halfFloat.f32ToF16Bytes(sourceTex.data),
           colorSpace: 'linear',
-          mipmap: false,
+          mips: { kind: 'none' },
         }
       : sourceTex;
 
@@ -1503,7 +1606,11 @@ export class GpuResidencyCache {
 
     const equirectTextureResult = device.createTexture({
       label: `equirect-${sourceId}`,
-      size: { width: tex.width, height: tex.height, depthOrArrayLayers: 1 },
+      size: {
+        width: tex.shape.extent.width,
+        height: tex.shape.extent.height,
+        depthOrArrayLayers: 1,
+      },
       mipLevelCount: 1,
       sampleCount: 1,
       dimension: '2d',
@@ -1526,8 +1633,15 @@ export class GpuResidencyCache {
     const equirectWriteResult = device.queue.writeTexture(
       { texture: equirectGpuTex },
       tex.data,
-      { bytesPerRow: tex.width * bytesPerPixel, rowsPerImage: tex.height },
-      { width: tex.width, height: tex.height, depthOrArrayLayers: 1 },
+      {
+        bytesPerRow: tex.shape.extent.width * bytesPerPixel,
+        rowsPerImage: tex.shape.extent.height,
+      },
+      {
+        width: tex.shape.extent.width,
+        height: tex.shape.extent.height,
+        depthOrArrayLayers: 1,
+      },
     );
     if (!equirectWriteResult.ok) return recordFailed(equirectWriteResult.error);
 
@@ -1803,20 +1917,16 @@ export class GpuResidencyCache {
 /**
  * Synthesize the `DecodedImage` view the texture-upload prelude consumes from
  * a `TextureAsset` POD (the record-stage pull path holds only the POD). The
- * POD's `data` is the pixel bytes; `colorSpace` + `mipmap` drive the
+ * POD's `data` is the pixel bytes; `colorSpace` + `mips` drive the
  * consistency assertion + mip count.
  */
 function decodedFromTexture(tex: TextureAsset): DecodedImage {
-  const bytes =
-    tex.data instanceof Uint8ClampedArray
-      ? new Uint8Array(tex.data.buffer, tex.data.byteOffset, tex.data.byteLength)
-      : tex.data;
   return {
-    bytes,
-    width: tex.width,
-    height: tex.height,
+    bytes: tex.data,
+    width: tex.shape.extent.width,
+    height: tex.shape.extent.height,
     mime: 'image/png',
     colorSpace: tex.colorSpace,
-    mipmap: tex.mipmap,
+    mipmap: tex.mips.kind === 'generate',
   };
 }

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