@forgeax/engine-render 0.1.21 → 0.1.24

package/src/prepare/extended-lighting/ltc-resources.ts

@@ -0,0 +1,136 @@
+// @forgeax/engine-render - DeviceScope-owned RectArea LTC resources.
+
+import type { Result, RhiDevice, RhiError, Texture } from '@forgeax/engine-rhi';
+import { LTC_TABLE_HEIGHT, LTC_TABLE_WIDTH, LTC_TABLES } from '@forgeax/engine-shader';
+import { err, ok } from '@forgeax/engine-types';
+import { type DeviceScope, LifecycleTransaction } from '../../device/device-scope';
+import {
+  GPU_TEXTURE_USAGE_COPY_DST,
+  GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+} from '../../gpu-texture-usage';
+import { deriveExtendedLightingCapability, EXTENDED_LIGHTING_TOPOLOGY } from './resources';
+
+export interface LtcResourcePlanInput {
+  readonly scope: DeviceScope;
+  readonly ltcAvailable: boolean;
+  readonly residentGeneration?: number;
+}
+
+export interface LtcResourcePlan {
+  readonly topology: typeof EXTENDED_LIGHTING_TOPOLOGY;
+  readonly generation: number;
+  readonly rectAdmission: 'admitted' | 'omitted';
+  readonly tableCount: number;
+  readonly uploadCount: number;
+}
+
+export interface LtcResourceCandidate {
+  readonly topology: typeof EXTENDED_LIGHTING_TOPOLOGY;
+  readonly generation: number;
+  readonly scope: DeviceScope;
+  readonly lambertTexture: Texture;
+  readonly ggxTexture: Texture;
+  readonly tableCount: 2;
+  readonly uploadCount: 2;
+}
+
+export function deriveLtcResourcePlan(input: LtcResourcePlanInput): LtcResourcePlan {
+  const admitted = input.ltcAvailable;
+  return {
+    topology: EXTENDED_LIGHTING_TOPOLOGY,
+    generation: input.scope.generation,
+    rectAdmission: admitted ? 'admitted' : 'omitted',
+    tableCount: admitted ? 2 : 0,
+    uploadCount: admitted && input.residentGeneration !== input.scope.generation ? 2 : 0,
+  };
+}
+
+function failure(expected: string, actual: string): Result<never, RhiError> {
+  return err({
+    code: 'webgpu-runtime-error',
+    expected,
+    hint: 'inspect device capabilities and retry the extendedLighting candidate',
+    detail: { error: { code: 'ltc-resource', message: actual } },
+  } as RhiError);
+}
+
+function textureBytes(table: Uint16Array): Uint8Array {
+  return new Uint8Array(table.buffer, table.byteOffset, table.byteLength);
+}
+
+/** Create both tracked tables atomically; unavailable LTC only omits Rect. */
+export async function createLtcResourceCandidate(input: {
+  readonly device: RhiDevice | undefined;
+  readonly scope: DeviceScope;
+}): Promise<Result<LtcResourceCandidate | undefined, RhiError>> {
+  if (input.device === undefined) return ok(undefined);
+  if (!deriveExtendedLightingCapability(input.device).admitted) return ok(undefined);
+  const device = input.device;
+
+  const transaction = new LifecycleTransaction(input.scope);
+  let lambertTexture: Texture | undefined;
+  let ggxTexture: Texture | undefined;
+  const createTable = (label: string, table: Uint16Array): Texture => {
+    const texture = device.createTexture({
+      label,
+      size: { width: LTC_TABLE_WIDTH, height: LTC_TABLE_HEIGHT, depthOrArrayLayers: 1 },
+      mipLevelCount: 1,
+      sampleCount: 1,
+      dimension: '2d',
+      format: 'rgba16float',
+      usage: GPU_TEXTURE_USAGE_COPY_DST | GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+      viewFormats: [],
+      textureBindingViewDimension: undefined,
+    });
+    if (texture === undefined || !texture.ok) {
+      throw texture?.error ?? new Error('LTC texture creation returned no result');
+    }
+    const write = device.queue.writeTexture(
+      { texture: texture.value, mipLevel: 0, origin: { x: 0, y: 0, z: 0 } },
+      textureBytes(table),
+      { offset: 0, bytesPerRow: LTC_TABLE_WIDTH * 8, rowsPerImage: LTC_TABLE_HEIGHT },
+      { width: LTC_TABLE_WIDTH, height: LTC_TABLE_HEIGHT, depthOrArrayLayers: 1 },
+    );
+    if (!write.ok) throw write.error;
+    return texture.value;
+  };
+
+  transaction.add({
+    kind: 'texture',
+    create: () => {
+      lambertTexture = createTable('extended-lighting-ltc-lambert', LTC_TABLES.lambert);
+      return lambertTexture;
+    },
+    cleanup: (value) => {
+      const destroyed = input.device?.destroyTexture(value);
+      if (destroyed !== undefined && !destroyed.ok) throw destroyed.error;
+    },
+  });
+  transaction.add({
+    kind: 'texture',
+    create: () => {
+      ggxTexture = createTable('extended-lighting-ltc-ggx', LTC_TABLES.ggx);
+      return ggxTexture;
+    },
+    cleanup: (value) => {
+      const destroyed = input.device?.destroyTexture(value);
+      if (destroyed !== undefined && !destroyed.ok) throw destroyed.error;
+    },
+  });
+
+  const committed = await transaction.commit();
+  if (!committed.ok)
+    return failure(committed.error.primary.expected, committed.error.primary.message);
+  if (lambertTexture === undefined || ggxTexture === undefined) {
+    return failure('two LTC textures', 'the transaction committed without both tables');
+  }
+  return ok({
+    topology: EXTENDED_LIGHTING_TOPOLOGY,
+    generation: input.scope.generation,
+    scope: input.scope,
+    lambertTexture,
+    ggxTexture,
+    tableCount: 2,
+    uploadCount: 2,
+  });
+}

package/src/prepare/extended-lighting/resources.ts

@@ -0,0 +1,389 @@
+import type { Buffer, Result, RhiDevice, Sampler, Texture } from '@forgeax/engine-rhi';
+import { RhiError } from '@forgeax/engine-rhi';
+import { err, ok } from '@forgeax/engine-types';
+import type { DeviceScope } from '../../device/device-scope';
+import { LifecycleTransaction } from '../../device/lifecycle-transaction';
+import {
+  GPU_TEXTURE_USAGE_COPY_DST,
+  GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+} from '../../gpu-texture-usage';
+import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_UNIFORM } from '../../gpu-usage';
+
+export const EXTENDED_LIGHTING_TOPOLOGY = 'extendedLighting' as const;
+export const IES_SLICE_CAPACITY = 32;
+export const COOKIE_SLICE_CAPACITY = 32;
+export const PROBE_RECORD_CAPACITY = 64;
+export const IES_SLICE_WIDTH = 256;
+export const IES_SLICE_HEIGHT = 128;
+export const COOKIE_SLICE_SIZE = 256;
+export const COOKIE_MATRIX_BYTES = 32 * 16 * Float32Array.BYTES_PER_ELEMENT;
+/**
+ * Minimum per-stage sampled-texture limit for the shared PBR + extended-
+ * lighting pipeline-layout topology. The current BGL closure reserves 18
+ * sampled textures for the URP path and 20 for the HDRP/Probe path after the
+ * material IBL and transmission injections; WebGPU validates this pipeline-
+ * layout count even when a compiled shader variant does not read every
+ * optional entry.
+ */
+export const EXTENDED_LIGHTING_REQUIRED_SAMPLED_TEXTURES = 20;
+
+/**
+ * Keep shader-variant selection and resource admission on one capability fact.
+ * An omitted limit is treated as unavailable: a caller must not claim the
+ * extended topology without a numeric device limit proving it fits.
+ */
+export function extendedLightingSampledTextureCapacityAvailable(
+  maxSampledTexturesPerShaderStage: number | undefined,
+): boolean {
+  return (
+    maxSampledTexturesPerShaderStage !== undefined &&
+    maxSampledTexturesPerShaderStage >= EXTENDED_LIGHTING_REQUIRED_SAMPLED_TEXTURES
+  );
+}
+
+export interface ExtendedLightingCapabilityResult {
+  readonly admitted: boolean;
+  readonly topology: typeof EXTENDED_LIGHTING_TOPOLOGY;
+  readonly reason: string | undefined;
+}
+
+export interface ExtendedLightingResourceInput {
+  readonly device: RhiDevice | undefined;
+  readonly scope: DeviceScope;
+  readonly iesSliceCount: number;
+  readonly cookieSliceCount: number;
+  readonly cookieMatrices: number;
+  readonly iesData?: Uint8Array | undefined;
+  readonly cookieData?: Uint8Array | undefined;
+  readonly cookieMatrixData?: Float32Array | undefined;
+}
+
+export interface ExtendedLightingResourceCandidate {
+  readonly topology: typeof EXTENDED_LIGHTING_TOPOLOGY;
+  readonly generation: number;
+  readonly scope: DeviceScope;
+  readonly iesSliceCount: number;
+  readonly cookieSliceCount: number;
+  readonly cookieMatrices: number;
+  readonly sampler: Sampler;
+  readonly iesTexture: Texture | undefined;
+  readonly cookieTexture: Texture | undefined;
+  readonly cookieMatrixBuffer: Buffer | undefined;
+  readonly descriptorBytes: number;
+  readonly uploadCount: number;
+}
+
+export interface ExtendedLightingResourceInspection {
+  readonly topology: typeof EXTENDED_LIGHTING_TOPOLOGY;
+  readonly generation: number;
+  readonly status: 'empty' | 'candidate' | 'accepted';
+  readonly accepted: boolean;
+  readonly resourceCount: number;
+  readonly descriptorBytes: number;
+  readonly uploadCount: number;
+  readonly blendInvalidations: number;
+  readonly passCount: number;
+}
+
+function failure(expected: string, actual: string): Result<never, RhiError> {
+  return err(
+    new RhiError({
+      code: 'webgpu-runtime-error',
+      expected,
+      hint: 'repair the extended lighting resource facts and retry the candidate generation',
+      detail: { error: { code: 'extended-lighting-resource', message: actual } },
+    }),
+  );
+}
+
+function validCount(value: number, capacity: number): boolean {
+  return Number.isSafeInteger(value) && value >= 0 && value <= capacity;
+}
+
+/** Derive admission from the RHI facts; no backend-kind policy is involved. */
+export function deriveExtendedLightingCapability(
+  device: Pick<RhiDevice, 'caps' | 'limits'>,
+): ExtendedLightingCapabilityResult {
+  const maxSampledTextures = device.limits.maxSampledTexturesPerShaderStage;
+  if (!extendedLightingSampledTextureCapacityAvailable(maxSampledTextures)) {
+    return {
+      admitted: false,
+      topology: EXTENDED_LIGHTING_TOPOLOGY,
+      reason: `maxSampledTexturesPerShaderStage ${maxSampledTextures ?? 0} < ${EXTENDED_LIGHTING_REQUIRED_SAMPLED_TEXTURES}`,
+    };
+  }
+  const maxLayers = device.limits.maxTextureArrayLayers ?? 0;
+  const maxUniformBuffers = device.limits.maxUniformBuffersPerShaderStage ?? 0;
+  if (maxLayers < IES_SLICE_CAPACITY) {
+    return {
+      admitted: false,
+      topology: EXTENDED_LIGHTING_TOPOLOGY,
+      reason: `maxTextureArrayLayers ${maxLayers} < ${IES_SLICE_CAPACITY}`,
+    };
+  }
+  if (maxUniformBuffers < 1) {
+    return {
+      admitted: false,
+      topology: EXTENDED_LIGHTING_TOPOLOGY,
+      reason: `maxUniformBuffersPerShaderStage ${maxUniformBuffers} < 1`,
+    };
+  }
+  if (
+    !device.caps.storageBuffer ||
+    !device.caps.rgba16floatRenderable ||
+    !device.caps.samplerAliasing
+  ) {
+    return {
+      admitted: false,
+      topology: EXTENDED_LIGHTING_TOPOLOGY,
+      reason: 'required storage-buffer, rgba16float, or sampler capability is unavailable',
+    };
+  }
+  return { admitted: true, topology: EXTENDED_LIGHTING_TOPOLOGY, reason: undefined };
+}
+
+function createTexture(
+  device: RhiDevice,
+  label: string,
+  format: 'r16float' | 'rgba8unorm',
+  width: number,
+  height: number,
+  layers: number,
+): Result<Texture, RhiError> {
+  return device.createTexture({
+    label,
+    size: { width, height, depthOrArrayLayers: layers },
+    mipLevelCount: 1,
+    sampleCount: 1,
+    dimension: '2d',
+    format,
+    usage: GPU_TEXTURE_USAGE_COPY_DST | GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+    viewFormats: [],
+    textureBindingViewDimension: undefined,
+  });
+}
+
+function requireResource<T>(result: Result<T, RhiError>): T {
+  if (!result.ok) throw result.error;
+  return result.value;
+}
+
+function writeTextureSlices(
+  device: RhiDevice,
+  texture: Texture,
+  data: Uint8Array | undefined,
+  bytesPerRow: number,
+  height: number,
+  layerCount: number,
+  width: number,
+): number {
+  if (data === undefined || layerCount === 0) return 0;
+  const bytesPerSlice = bytesPerRow * height;
+  const requiredBytes = bytesPerSlice * layerCount;
+  if (data.byteLength < requiredBytes) {
+    throw new Error(`extended lighting texture upload requires ${requiredBytes} bytes`);
+  }
+  for (let layer = 0; layer < layerCount; layer += 1) {
+    const start = layer * bytesPerSlice;
+    requireResource(
+      device.queue.writeTexture(
+        { texture, mipLevel: 0, origin: { x: 0, y: 0, z: layer } },
+        data.subarray(start, start + bytesPerSlice),
+        { offset: 0, bytesPerRow, rowsPerImage: height },
+        { width, height, depthOrArrayLayers: 1 },
+      ),
+    );
+  }
+  return layerCount;
+}
+
+/** Build a complete candidate; nothing is adopted until the transaction commits. */
+export async function createExtendedLightingResourceCandidate(
+  input: ExtendedLightingResourceInput,
+): Promise<Result<ExtendedLightingResourceCandidate, RhiError>> {
+  const { device, scope } = input;
+  if (device === undefined) return failure('a live RHI device is required', 'device is undefined');
+  if (!validCount(input.iesSliceCount, IES_SLICE_CAPACITY)) {
+    return failure(`IES slice count <= ${IES_SLICE_CAPACITY}`, String(input.iesSliceCount));
+  }
+  if (!validCount(input.cookieSliceCount, COOKIE_SLICE_CAPACITY)) {
+    return failure(
+      `Cookie slice count <= ${COOKIE_SLICE_CAPACITY}`,
+      String(input.cookieSliceCount),
+    );
+  }
+  if (!validCount(input.cookieMatrices, COOKIE_SLICE_CAPACITY)) {
+    return failure(`Cookie matrix count <= ${COOKIE_SLICE_CAPACITY}`, String(input.cookieMatrices));
+  }
+  const capability = deriveExtendedLightingCapability(device);
+  if (!capability.admitted)
+    return failure('extendedLighting capability admission', capability.reason ?? 'unavailable');
+  if (
+    input.cookieMatrixData !== undefined &&
+    input.cookieMatrixData.byteLength < input.cookieMatrices * 16 * Float32Array.BYTES_PER_ELEMENT
+  ) {
+    return failure(
+      'cookie matrix upload payload',
+      `requires ${input.cookieMatrices * 16 * Float32Array.BYTES_PER_ELEMENT} bytes`,
+    );
+  }
+
+  const transaction = new LifecycleTransaction(scope);
+  let iesTexture: Texture | undefined;
+  let cookieTexture: Texture | undefined;
+  let cookieMatrixBuffer: Buffer | undefined;
+  let sampler: Sampler | undefined;
+  let uploadCount = 0;
+  transaction.add({
+    kind: 'texture',
+    create: () => {
+      const created = requireResource(
+        createTexture(
+          device,
+          'extended-lighting-ies',
+          'r16float',
+          IES_SLICE_WIDTH,
+          IES_SLICE_HEIGHT,
+          IES_SLICE_CAPACITY,
+        ),
+      );
+      uploadCount += writeTextureSlices(
+        device,
+        created,
+        input.iesData,
+        IES_SLICE_WIDTH * 2,
+        IES_SLICE_HEIGHT,
+        input.iesSliceCount,
+        IES_SLICE_WIDTH,
+      );
+      iesTexture = created;
+      return created;
+    },
+    cleanup: (value) => {
+      const destroyed = device.destroyTexture(value);
+      if (!destroyed.ok) throw destroyed.error;
+    },
+  });
+  transaction.add({
+    kind: 'texture',
+    create: () => {
+      const created = requireResource(
+        createTexture(
+          device,
+          'extended-lighting-cookie',
+          'rgba8unorm',
+          COOKIE_SLICE_SIZE,
+          COOKIE_SLICE_SIZE,
+          COOKIE_SLICE_CAPACITY,
+        ),
+      );
+      uploadCount += writeTextureSlices(
+        device,
+        created,
+        input.cookieData,
+        COOKIE_SLICE_SIZE * 4,
+        COOKIE_SLICE_SIZE,
+        input.cookieSliceCount,
+        COOKIE_SLICE_SIZE,
+      );
+      cookieTexture = created;
+      return created;
+    },
+    cleanup: (value) => {
+      const destroyed = device.destroyTexture(value);
+      if (!destroyed.ok) throw destroyed.error;
+    },
+  });
+  transaction.add({
+    kind: 'buffer',
+    create: () => {
+      const created = requireResource(
+        device.createBuffer({
+          label: 'extended-lighting-cookie-matrices',
+          size: COOKIE_MATRIX_BYTES,
+          usage: GPU_BUFFER_USAGE_COPY_DST | GPU_BUFFER_USAGE_UNIFORM,
+          mappedAtCreation: false,
+        }),
+      );
+      if (input.cookieMatrixData !== undefined && input.cookieMatrices > 0) {
+        requireResource(device.queue.writeBuffer(created, 0, input.cookieMatrixData));
+        uploadCount += 1;
+      }
+      cookieMatrixBuffer = created;
+      return created;
+    },
+    cleanup: (value) => {
+      const destroyed = device.destroyBuffer(value);
+      if (!destroyed.ok) throw destroyed.error;
+    },
+  });
+  transaction.add({
+    // Samplers are bindable GPU resources, not host listeners. Keeping the
+    // lifecycle kind aligned with the resource's actual renderer role makes
+    // scope inspection and rollback receipts truthful.
+    kind: 'binding',
+    create: () => {
+      const created = requireResource(
+        device.createSampler({
+          label: 'extended-lighting-clamp-linear',
+          addressModeU: 'clamp-to-edge',
+          addressModeV: 'clamp-to-edge',
+          addressModeW: 'clamp-to-edge',
+          magFilter: 'linear',
+          minFilter: 'linear',
+          mipmapFilter: 'nearest',
+        }),
+      );
+      sampler = created;
+      return created;
+    },
+    cleanup: () => undefined,
+  });
+  const committed = await transaction.commit();
+  if (!committed.ok)
+    return failure(committed.error.primary.expected, committed.error.primary.message);
+  if (
+    iesTexture === undefined ||
+    cookieTexture === undefined ||
+    cookieMatrixBuffer === undefined ||
+    sampler === undefined
+  ) {
+    return failure(
+      'complete extendedLighting candidate resources',
+      'resource transaction returned an incomplete set',
+    );
+  }
+  return ok({
+    topology: EXTENDED_LIGHTING_TOPOLOGY,
+    generation: scope.generation,
+    scope,
+    iesSliceCount: input.iesSliceCount,
+    cookieSliceCount: input.cookieSliceCount,
+    cookieMatrices: input.cookieMatrices,
+    sampler,
+    iesTexture,
+    cookieTexture,
+    cookieMatrixBuffer,
+    descriptorBytes:
+      IES_SLICE_WIDTH * IES_SLICE_HEIGHT * 2 * IES_SLICE_CAPACITY +
+      COOKIE_SLICE_SIZE * COOKIE_SLICE_SIZE * 4 * COOKIE_SLICE_CAPACITY +
+      COOKIE_MATRIX_BYTES,
+    uploadCount,
+  });
+}
+
+export function inspectExtendedLightingResources(
+  scope: DeviceScope,
+): ExtendedLightingResourceInspection {
+  return {
+    topology: EXTENDED_LIGHTING_TOPOLOGY,
+    generation: scope.generation,
+    status: 'empty',
+    accepted: false,
+    resourceCount: 0,
+    descriptorBytes: 0,
+    uploadCount: 0,
+    blendInvalidations: 0,
+    passCount: 0,
+  };
+}