@forgeax/engine-render 0.1.20 → 0.1.23

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

package/src/prepare/extended-lighting/spot-modifiers.ts

@@ -0,0 +1,194 @@
+import type { TextureAsset } from '@forgeax/engine-types';
+import { COOKIE_SLICE_SIZE } from './resources';
+
+export interface SpotModifierFactors {
+  readonly brdf: number;
+  readonly range: number;
+  readonly cone: number;
+  readonly ies?: number | undefined;
+  readonly cookie?: number | undefined;
+  readonly shadow: number;
+}
+
+export interface IesCoordinates {
+  readonly azimuth: number;
+  readonly elevation: number;
+}
+
+export interface CookieUv {
+  readonly u: number;
+  readonly v: number;
+}
+
+/**
+ * The fixed GPU representation consumed by the extended-lighting Cookie
+ * array. The matrix is deliberately keyed by Cookie slice rather than by
+ * light: it carries only the source texture aspect correction. The shader
+ * still owns the light-local basis, roll, and outer-cone projection, so one
+ * Cookie can be shared by Spots with different directions or cone angles.
+ */
+export interface CookieProjection {
+  readonly data: Uint8Array;
+  readonly matrix: Float32Array;
+  readonly aspect: number;
+}
+
+const DEG_TO_RAD = Math.PI / 180;
+
+const COOKIE_PROJECTION_CACHE = new WeakMap<TextureAsset, CookieProjection | null>();
+
+function srgbToLinear(value: number): number {
+  return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+}
+
+function clamp01(value: number): number {
+  return Math.min(1, Math.max(0, value));
+}
+
+function sourceChannel(asset: TextureAsset, x: number, y: number, channel: number): number {
+  const offset = (y * asset.shape.extent.width + x) * 4 + channel;
+  const encoded = (asset.data[offset] ?? 0) / 255;
+  return channel < 3 && asset.colorSpace === 'srgb' ? srgbToLinear(encoded) : encoded;
+}
+
+function sampleSourceChannel(asset: TextureAsset, x: number, y: number, channel: number): number {
+  const sourceX = clamp01((x + 0.5) / COOKIE_SLICE_SIZE) * (asset.shape.extent.width - 1);
+  const sourceY = clamp01((y + 0.5) / COOKIE_SLICE_SIZE) * (asset.shape.extent.height - 1);
+  const x0 = Math.floor(sourceX);
+  const y0 = Math.floor(sourceY);
+  const x1 = Math.min(asset.shape.extent.width - 1, x0 + 1);
+  const y1 = Math.min(asset.shape.extent.height - 1, y0 + 1);
+  const tx = sourceX - x0;
+  const ty = sourceY - y0;
+  const top =
+    sourceChannel(asset, x0, y0, channel) * (1 - tx) + sourceChannel(asset, x1, y0, channel) * tx;
+  const bottom =
+    sourceChannel(asset, x0, y1, channel) * (1 - tx) + sourceChannel(asset, x1, y1, channel) * tx;
+  return top * (1 - ty) + bottom * ty;
+}
+
+/**
+ * Project a filterable 2D RGBA Cookie into the renderer's fixed linear
+ * 256x256 array slice. This is a producer-boundary operation and is cached by
+ * the immutable TextureAsset object, so the frame path never decodes or
+ * resamples the source repeatedly.
+ */
+export function prepareCookieProjection(asset: TextureAsset): CookieProjection | undefined {
+  if (COOKIE_PROJECTION_CACHE.has(asset)) {
+    return COOKIE_PROJECTION_CACHE.get(asset) ?? undefined;
+  }
+  const supportedFormat = asset.format === 'rgba8unorm' || asset.format === 'rgba8unorm-srgb';
+  const validDimensions =
+    Number.isSafeInteger(asset.shape.extent.width) &&
+    Number.isSafeInteger(asset.shape.extent.height) &&
+    asset.shape.extent.width > 0 &&
+    asset.shape.extent.height > 0;
+  const validFormatPair =
+    (asset.format === 'rgba8unorm-srgb' && asset.colorSpace === 'srgb') ||
+    (asset.format === 'rgba8unorm' && asset.colorSpace === 'linear');
+  const validPayload =
+    asset.data.byteLength >= asset.shape.extent.width * asset.shape.extent.height * 4;
+  if (!supportedFormat || !validDimensions || !validFormatPair || !validPayload) {
+    COOKIE_PROJECTION_CACHE.set(asset, null);
+    return undefined;
+  }
+
+  const data = new Uint8Array(COOKIE_SLICE_SIZE * COOKIE_SLICE_SIZE * 4);
+  for (let y = 0; y < COOKIE_SLICE_SIZE; y += 1) {
+    for (let x = 0; x < COOKIE_SLICE_SIZE; x += 1) {
+      const target = (y * COOKIE_SLICE_SIZE + x) * 4;
+      data[target] = Math.round(clamp01(sampleSourceChannel(asset, x, y, 0)) * 255);
+      data[target + 1] = Math.round(clamp01(sampleSourceChannel(asset, x, y, 1)) * 255);
+      data[target + 2] = Math.round(clamp01(sampleSourceChannel(asset, x, y, 2)) * 255);
+      // Alpha stays linear and is intentionally preserved: the shader
+      // multiplies sampled RGB by this lane as part of Cookie semantics.
+      data[target + 3] = Math.round(clamp01(sampleSourceChannel(asset, x, y, 3)) * 255);
+    }
+  }
+
+  // Column-major mat4. The shader multiplies the unprojected local
+  // (x/depth, y/depth) pair by this aspect-only matrix, then applies the
+  // Spot's outer-cone tangent and the [0,1] translation. Keeping outerCone
+  // out of this slice-keyed matrix allows one Cookie to be shared by lights.
+  const matrix = new Float32Array(16);
+  matrix[0] = asset.shape.extent.height / asset.shape.extent.width;
+  matrix[5] = 1;
+  matrix[10] = 1;
+  matrix[15] = 1;
+  const projection = {
+    data,
+    matrix,
+    aspect: asset.shape.extent.width / asset.shape.extent.height,
+  };
+  COOKIE_PROJECTION_CACHE.set(asset, projection);
+  return projection;
+}
+
+/** Create the deterministic identity payload used for unused Cookie slices. */
+export function createCookieProjectionMatrixData(count: number): Float32Array {
+  const data = new Float32Array(count * 16);
+  for (let index = 0; index < count; index += 1) {
+    const base = index * 16;
+    data[base] = 1;
+    data[base + 5] = 1;
+    data[base + 10] = 1;
+    data[base + 15] = 1;
+  }
+  return data;
+}
+
+function normalized(vector: ArrayLike<number>): [number, number, number] | undefined {
+  const x = vector[0] ?? 0;
+  const y = vector[1] ?? 0;
+  const z = vector[2] ?? 0;
+  const length = Math.hypot(x, y, z);
+  return length > 0 && Number.isFinite(length) ? [x / length, y / length, z / length] : undefined;
+}
+
+export function spotModifierProduct(factors: SpotModifierFactors): number {
+  return (
+    factors.brdf *
+    factors.range *
+    factors.cone *
+    (factors.ies ?? 1) *
+    (factors.cookie ?? 1) *
+    factors.shadow
+  );
+}
+
+export function projectIesCoordinates(
+  toPoint: ArrayLike<number>,
+  rollDeg: number,
+): IesCoordinates | undefined {
+  const direction = normalized(toPoint);
+  if (direction === undefined || direction[2] >= 0) return undefined;
+  const roll = rollDeg * DEG_TO_RAD;
+  const rolledX = direction[0] * Math.cos(roll) - direction[1] * Math.sin(roll);
+  const rolledY = direction[0] * Math.sin(roll) + direction[1] * Math.cos(roll);
+  return {
+    azimuth: (Math.atan2(rolledY, rolledX) + Math.PI * 2) % (Math.PI * 2),
+    elevation: Math.acos(Math.min(1, Math.max(-1, -direction[2]))) / Math.PI,
+  };
+}
+
+export function projectCookieUv(
+  toPoint: ArrayLike<number>,
+  rollDeg: number,
+  aspect: number,
+  outerConeDeg = 45,
+): CookieUv | undefined {
+  const direction = normalized(toPoint);
+  if (direction === undefined || direction[2] >= 0 || !Number.isFinite(aspect) || aspect <= 0)
+    return undefined;
+  const cone = Math.atan2(Math.hypot(direction[0], direction[1]), -direction[2]);
+  const outerCone = outerConeDeg * DEG_TO_RAD;
+  if (cone > outerCone) return undefined;
+  const roll = rollDeg * DEG_TO_RAD;
+  const x = direction[0] * Math.cos(roll) - direction[1] * Math.sin(roll);
+  const y = direction[0] * Math.sin(roll) + direction[1] * Math.cos(roll);
+  const scale = Math.tan(outerCone);
+  return {
+    u: 0.5 + (x / -direction[2] / scale / aspect) * 0.5,
+    v: 0.5 + (y / -direction[2] / scale) * 0.5,
+  };
+}

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

@@ -0,0 +1,92 @@
+import type { LightResourceUnavailableError } from '../../errors/render';
+import {
+  type LightInspection,
+  lightInspectionIdentity,
+  projectLightInspection,
+} from '../../inspection-types';
+import type { ExtendedLightingResourceCandidate } from './resources';
+
+export type ExtendedLightingResourceStatus = 'empty' | 'candidate' | 'accepted';
+
+export interface ExtendedLightingState {
+  readonly enabled: boolean;
+  readonly generation: number;
+  readonly status: ExtendedLightingResourceStatus;
+  readonly candidate: ExtendedLightingResourceCandidate | undefined;
+  readonly accepted: ExtendedLightingResourceCandidate | undefined;
+  readonly lastKnownGood: ExtendedLightingResourceCandidate | undefined;
+  readonly resourceCount: number;
+  readonly descriptorBytes: number;
+  readonly uploadCount: number;
+  readonly passCount: number;
+  readonly bindGroupCount: number;
+  readonly failure: LightResourceUnavailableError | undefined;
+  readonly failureKeys: readonly string[];
+}
+
+export function createExtendedLightingState(generation: number): ExtendedLightingState {
+  return {
+    enabled: false,
+    generation,
+    status: 'empty',
+    candidate: undefined,
+    accepted: undefined,
+    lastKnownGood: undefined,
+    resourceCount: 0,
+    descriptorBytes: 0,
+    uploadCount: 0,
+    passCount: 0,
+    bindGroupCount: 0,
+    failure: undefined,
+    failureKeys: [],
+  };
+}
+
+export function promoteExtendedLightingCandidate(
+  state: ExtendedLightingState,
+  candidate: ExtendedLightingResourceCandidate | undefined,
+): ExtendedLightingState {
+  if (candidate === undefined) return state;
+  return {
+    ...state,
+    enabled: true,
+    generation: candidate.generation,
+    status: 'accepted',
+    candidate: undefined,
+    accepted: candidate,
+    lastKnownGood: candidate,
+    resourceCount: 4,
+    descriptorBytes: candidate.descriptorBytes,
+    uploadCount: candidate.uploadCount,
+  };
+}
+
+export function recordExtendedLightingFailure(
+  state: ExtendedLightingState,
+  failure: LightResourceUnavailableError,
+): ExtendedLightingState {
+  const key = `${failure.detail.entity}:${failure.detail.feature}:${failure.detail.generation}`;
+  if (state.failureKeys.includes(key)) return state;
+  return {
+    ...state,
+    failure,
+    failureKeys: [...state.failureKeys, key],
+  };
+}
+
+export function projectExtendedLightingInspection(state: ExtendedLightingState): LightInspection {
+  const identity = (candidate: ExtendedLightingResourceCandidate | undefined) =>
+    candidate === undefined
+      ? undefined
+      : lightInspectionIdentity(candidate.topology, candidate.generation);
+  return projectLightInspection({
+    generation: state.generation,
+    candidate: identity(state.candidate),
+    accepted: identity(state.accepted),
+    lastKnownGood: identity(state.lastKnownGood),
+    failure: state.failure?.code,
+    failureKeys: state.failureKeys,
+    resourceCount: state.resourceCount,
+    uploadBytes: state.descriptorBytes,
+  });
+}