@aura3d/rendering 1.0.6

package/src/HDRRenderPipeline.ts

@@ -0,0 +1,94 @@
+import { RenderDeviceError, type RenderDevice, type RenderTarget } from "./RenderDevice";
+import { ToneMappingPass, type BloomOptions } from "./PostProcessPass";
+import { createExternalParityColorManagementPolicy, type A3DColorManagementPolicy } from "./ColorManagement";
+import { createExternalParityToneMappingPolicy, type ExternalParityToneMappingIntent, type ExternalParityToneMappingPolicy } from "./ToneMapping";
+
+export type ExternalParityHdrRenderTargetFormat = "rgba16f" | "rgba32f" | "rgba8";
+export type ExternalParityHdrPipelineMode = "hdr" | "ldr-fallback";
+
+export interface ExternalParityHdrPipelineDescriptor {
+  readonly width: number;
+  readonly height: number;
+  readonly intent?: ExternalParityToneMappingIntent;
+  readonly preferredFormat?: Extract<ExternalParityHdrRenderTargetFormat, "rgba16f" | "rgba32f">;
+  readonly allowLdrFallback?: boolean;
+  readonly bloom?: BloomOptions | false;
+}
+
+export interface ExternalParityHdrPipeline {
+  readonly mode: ExternalParityHdrPipelineMode;
+  readonly format: ExternalParityHdrRenderTargetFormat;
+  readonly colorTarget: RenderTarget;
+  readonly displayTarget: RenderTarget;
+  readonly colorManagement: A3DColorManagementPolicy;
+  readonly toneMapping: ExternalParityToneMappingPolicy;
+  readonly bloom: BloomOptions | false;
+  readonly warnings: readonly string[];
+}
+
+export function createExternalParityHdrPipeline(device: RenderDevice, descriptor: ExternalParityHdrPipelineDescriptor): ExternalParityHdrPipeline {
+  validateDimensions(descriptor.width, descriptor.height);
+  const colorManagement = createExternalParityColorManagementPolicy({
+    outputColorSpace: "srgb",
+    allowLdrFallback: descriptor.allowLdrFallback ?? true
+  });
+  const toneMapping = createExternalParityToneMappingPolicy(descriptor.intent ?? "product-catalog");
+  const capabilities = new Set(device.info.capabilities ?? []);
+  const supportsHdr = capabilities.has("hdr-render-targets") || device.kind === "mock";
+  const preferredFormat = descriptor.preferredFormat ?? "rgba16f";
+  const allowLdrFallback = descriptor.allowLdrFallback ?? true;
+  const format: ExternalParityHdrRenderTargetFormat = supportsHdr ? preferredFormat : "rgba8";
+  if (!supportsHdr && !allowLdrFallback) {
+    throw new RenderDeviceError("ExternalParity HDR pipeline requires HDR render targets or an explicit LDR fallback.", "EXTERNAL_PARITY_HDR_UNSUPPORTED", {
+      backend: device.kind
+    });
+  }
+
+  const colorTarget = device.createRenderTarget({
+    width: descriptor.width,
+    height: descriptor.height,
+    label: "external-parity-hdr-color",
+    format,
+    depth: "texture"
+  });
+  const displayTarget = device.createRenderTarget({
+    width: descriptor.width,
+    height: descriptor.height,
+    label: "external-parity-display-color",
+    format: "rgba8"
+  });
+
+  return {
+    mode: supportsHdr ? "hdr" : "ldr-fallback",
+    format,
+    colorTarget,
+    displayTarget,
+    colorManagement,
+    toneMapping,
+    bloom: descriptor.bloom ?? false,
+    warnings: supportsHdr
+      ? []
+      : ["Backend does not expose HDR render targets; using LDR fallback with linear lighting policy and explicit tone mapping."]
+  };
+}
+
+export function executeExternalParityToneMapPass(device: RenderDevice, pipeline: ExternalParityHdrPipeline): ToneMappingPass {
+  const pass = new ToneMappingPass({
+    source: pipeline.colorTarget,
+    target: pipeline.displayTarget,
+    exposure: pipeline.toneMapping.exposure,
+    whitePoint: pipeline.toneMapping.whitePoint,
+    gamma: pipeline.toneMapping.gamma,
+    operator: pipeline.toneMapping.operator,
+    inputColorSpace: pipeline.toneMapping.inputColorSpace,
+    outputColorSpace: pipeline.toneMapping.outputColorSpace
+  });
+  pass.execute({ device, width: pipeline.colorTarget.width, height: pipeline.colorTarget.height });
+  return pass;
+}
+
+function validateDimensions(width: number, height: number): void {
+  if (!Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0) {
+    throw new Error("ExternalParity HDR pipeline dimensions must be positive integers.");
+  }
+}

package/src/IBL.ts

@@ -0,0 +1,86 @@
+import {
+  createEnvironmentMapResourceSet,
+  type EnvironmentMapResourceSet,
+  type LinearHdrEnvironmentMapSource
+} from "./EnvironmentMapResources";
+import { createExternalParityGeneratedHdrEnvironmentMapSource, type ExternalParityEnvironmentPreset } from "./ExternalParityRenderPreset";
+import { createExternalParityBrdfLut, type ExternalParityBrdfLut } from "./BRDFLut";
+import { createExternalParityPmrem, type ExternalParityPmrem } from "./PMREM";
+
+export interface ExternalParityIblOptions {
+  readonly preset: ExternalParityEnvironmentPreset;
+  readonly width?: number;
+  readonly height?: number;
+  readonly rotation?: number;
+  readonly intensity?: number;
+  readonly backgroundIntensity?: number;
+  readonly sourceQuality?: "bootstrap-generated" | "licensed-hdr";
+}
+
+export interface ExternalParityIblResourceSet {
+  readonly preset: ExternalParityEnvironmentPreset;
+  readonly source: LinearHdrEnvironmentMapSource;
+  readonly resources: EnvironmentMapResourceSet;
+  readonly pmrem: ExternalParityPmrem;
+  readonly brdfLut: ExternalParityBrdfLut;
+  readonly rotation: number;
+  readonly intensity: number;
+  readonly backgroundIntensity: number;
+  readonly diagnostics: {
+    readonly sourceQuality: "bootstrap-generated" | "licensed-hdr";
+    readonly notFlagshipProof: boolean;
+    readonly hdrSource: boolean;
+    readonly maxLinearValue: number;
+    readonly diffuseIrradiance: boolean;
+    readonly specularPrefilter: boolean;
+    readonly brdfLut: boolean;
+    readonly environmentRotation: boolean;
+    readonly environmentIntensity: boolean;
+    readonly backgroundSeparation: boolean;
+  };
+}
+
+export function createExternalParityIblResources(options: ExternalParityIblOptions): ExternalParityIblResourceSet {
+  const source = createExternalParityGeneratedHdrEnvironmentMapSource(options.preset, options.width ?? 128, options.height ?? 64);
+  const resources = createEnvironmentMapResourceSet({ ...source, encoding: "linear-hdr" }, {
+    outputColorSpace: "srgb",
+    exposure: 1,
+    toneMapping: "reinhard",
+    specularLevels: 6,
+    specularBlurRadius: 3,
+    irradianceWidth: 16,
+    irradianceHeight: 8,
+    irradianceBlurRadius: 8,
+    brdfLutSize: 64
+  });
+  const pmrem = createExternalParityPmrem(resources.base, {
+    levels: 6,
+    blurRadius: 3,
+    textureLabel: `external-parity-${options.preset}-pmrem`
+  });
+  const brdfLut = createExternalParityBrdfLut(64);
+  const sourceQuality = options.sourceQuality ?? "bootstrap-generated";
+
+  return {
+    preset: options.preset,
+    source,
+    resources,
+    pmrem,
+    brdfLut,
+    rotation: options.rotation ?? 0,
+    intensity: options.intensity ?? 1,
+    backgroundIntensity: options.backgroundIntensity ?? 0.35,
+    diagnostics: {
+      sourceQuality,
+      notFlagshipProof: sourceQuality !== "licensed-hdr",
+      hdrSource: resources.diagnostics.hdrSource,
+      maxLinearValue: resources.diagnostics.maxLinearValue,
+      diffuseIrradiance: resources.diffuseIrradiance.width > 0 && resources.diffuseIrradiance.height > 0,
+      specularPrefilter: resources.specularMipLevels.length >= 4 && pmrem.diagnostics.directionalReflectionReady,
+      brdfLut: brdfLut.diagnostics.nonZeroPixels > 0 && brdfLut.diagnostics.monotonicRoughnessTrend,
+      environmentRotation: Number.isFinite(options.rotation ?? 0),
+      environmentIntensity: Number.isFinite(options.intensity ?? 1) && (options.intensity ?? 1) > 0,
+      backgroundSeparation: Number.isFinite(options.backgroundIntensity ?? 0.35) && (options.backgroundIntensity ?? 0.35) !== (options.intensity ?? 1)
+    }
+  };
+}

package/src/IndexBuffer.ts

@@ -0,0 +1,57 @@
+import { type IndexType, type RenderBuffer, type RenderDevice, RenderDeviceError } from "./RenderDevice";
+
+export class IndexBuffer {
+  public readonly type: IndexType;
+  public readonly data: Uint16Array | Uint32Array;
+  private gpuBuffer: RenderBuffer | null = null;
+  private disposed = false;
+
+  constructor(indices: readonly number[], vertexCount?: number) {
+    if (indices.length === 0) {
+      throw new Error("IndexBuffer requires at least one index");
+    }
+    let maxIndex = 0;
+    for (const index of indices) {
+      if (!Number.isInteger(index) || index < 0) {
+        throw new Error("IndexBuffer indices must be non-negative integers");
+      }
+      if (index > maxIndex) maxIndex = index;
+    }
+    if (vertexCount !== undefined && maxIndex >= vertexCount) {
+      throw new RangeError(`Index ${maxIndex} is outside vertex count ${vertexCount}`);
+    }
+    this.type = maxIndex > 65535 ? "uint32" : "uint16";
+    this.data = this.type === "uint32" ? new Uint32Array(indices) : new Uint16Array(indices);
+  }
+
+  get count(): number {
+    return this.data.length;
+  }
+
+  get byteLength(): number {
+    return this.data.byteLength;
+  }
+
+  get uploadedBuffer(): RenderBuffer | null {
+    return this.gpuBuffer;
+  }
+
+  upload(device: RenderDevice): RenderBuffer {
+    this.assertAlive();
+    if (!this.gpuBuffer || this.gpuBuffer.disposed) {
+      this.gpuBuffer = device.createBuffer("index", this.data.byteLength, this.data);
+    }
+    return this.gpuBuffer;
+  }
+
+  dispose(): void {
+    this.gpuBuffer?.dispose();
+    this.disposed = true;
+  }
+
+  private assertAlive(): void {
+    if (this.disposed) {
+      throw new RenderDeviceError("IndexBuffer is disposed", "DISPOSED_RESOURCE");
+    }
+  }
+}

package/src/InstancedPBRMaterial.ts

@@ -0,0 +1,186 @@
+import { Material, type RenderState } from "./Material";
+import { DEFAULT_PBR_ENVIRONMENT_INTENSITY, DEFAULT_PBR_PROCEDURAL_ENVIRONMENT_MAP } from "./PBRLightingDefaults";
+import { DEFAULT_INSTANCED_PBR_SHADER_NAME } from "./ShaderLibrary";
+import { TextureBinding } from "./TextureBinding";
+
+export const MAX_INSTANCED_PBR_INSTANCES = 64;
+
+export interface InstancedPBRMaterialOptions {
+  readonly name?: string;
+  readonly baseColor?: readonly [number, number, number, number];
+  readonly renderState?: Partial<RenderState>;
+  readonly metallic?: number;
+  readonly roughness?: number;
+  readonly environmentColor?: readonly [number, number, number];
+  readonly environmentIntensity?: number;
+  readonly proceduralEnvironmentMap?: InstancedPBRProceduralEnvironmentMapOptions;
+  readonly environmentMapTexture?: TextureBinding;
+  readonly environmentMapIntensity?: number;
+  readonly environmentMapSpecularIntensity?: number;
+  readonly environmentMapRotation?: number;
+  readonly environmentMapMipCount?: number;
+  readonly environmentBrdfLutTexture?: TextureBinding;
+  readonly emissiveColor?: readonly [number, number, number];
+  readonly emissiveStrength?: number;
+}
+
+export interface InstancedPBRProceduralEnvironmentMapOptions {
+  readonly skyColor: readonly [number, number, number];
+  readonly horizonColor: readonly [number, number, number];
+  readonly groundColor: readonly [number, number, number];
+  readonly specularColor: readonly [number, number, number];
+  readonly intensity: number;
+  readonly specularIntensity: number;
+}
+
+export class InstancedPBRMaterial extends Material {
+  constructor(options: InstancedPBRMaterialOptions = {}) {
+    const baseColor = options.baseColor ?? [1, 1, 1, 1];
+    const environmentColor = options.environmentColor ?? [1, 1, 1];
+    const proceduralEnvironmentMap: InstancedPBRProceduralEnvironmentMapOptions = options.proceduralEnvironmentMap ?? DEFAULT_PBR_PROCEDURAL_ENVIRONMENT_MAP;
+    const emissiveColor = options.emissiveColor ?? [0, 0, 0];
+    validateColor4(baseColor, "baseColor");
+    validateColor3(environmentColor, "environmentColor");
+    validateProceduralEnvironmentMap(proceduralEnvironmentMap);
+    validateNonNegative(options.environmentMapIntensity ?? 0, "environmentMapIntensity");
+    validateNonNegative(options.environmentMapSpecularIntensity ?? 0, "environmentMapSpecularIntensity");
+    validateFinite(options.environmentMapRotation ?? 0, "environmentMapRotation");
+    validateMipCount(options.environmentMapMipCount ?? 1);
+    validateColor3(emissiveColor, "emissiveColor");
+    validateUnit(options.metallic ?? 0, "metallic");
+    validateUnit(options.roughness ?? 0.5, "roughness");
+    validateNonNegative(options.environmentIntensity ?? DEFAULT_PBR_ENVIRONMENT_INTENSITY, "environmentIntensity");
+    validateNonNegative(options.emissiveStrength ?? 1, "emissiveStrength");
+
+    super({
+      name: options.name ?? "instanced-pbr",
+      shaderKey: DEFAULT_INSTANCED_PBR_SHADER_NAME,
+      renderState: options.renderState,
+      parameters: {
+        u_baseColor: baseColor,
+        u_alphaCutoff: 0,
+        u_metallic: options.metallic ?? 0,
+        u_roughness: options.roughness ?? 0.5,
+        u_environmentColor: environmentColor,
+        u_environmentIntensity: options.environmentIntensity ?? DEFAULT_PBR_ENVIRONMENT_INTENSITY,
+        u_environmentSkyColor: proceduralEnvironmentMap.skyColor,
+        u_environmentHorizonColor: proceduralEnvironmentMap.horizonColor,
+        u_environmentGroundColor: proceduralEnvironmentMap.groundColor,
+        u_environmentSpecularColor: proceduralEnvironmentMap.specularColor,
+        u_environmentMapIntensity: proceduralEnvironmentMap.intensity,
+        u_environmentSpecularIntensity: proceduralEnvironmentMap.specularIntensity,
+        u_environmentMapTexture: options.environmentMapTexture ?? new TextureBinding({ name: "u_environmentMapTexture", required: false }),
+        u_environmentMapTextureEnabled: options.environmentMapTexture ? 1 : 0,
+        u_environmentMapTextureIntensity: options.environmentMapIntensity ?? 0,
+        u_environmentMapTextureSpecularIntensity: options.environmentMapSpecularIntensity ?? 0,
+        u_environmentMapTextureRotation: options.environmentMapRotation ?? 0,
+        u_environmentMapTextureMipCount: options.environmentMapMipCount ?? 1,
+        u_environmentMapTextureEncoding: 0,
+        u_environmentBrdfLutTexture: options.environmentBrdfLutTexture ?? new TextureBinding({ name: "u_environmentBrdfLutTexture", required: false }),
+        u_environmentBrdfLutEnabled: options.environmentBrdfLutTexture ? 1 : 0,
+        u_emissiveColor: emissiveColor,
+        u_emissiveStrength: options.emissiveStrength ?? 1,
+        u_lightCount: 0,
+        u_lightData: new Float32Array(0),
+        u_instanceMatrices: defaultInstanceMatrices(),
+        u_instanceCount: 1,
+        u_instanceAttributeMode: 0,
+        u_modelViewProjection: identityMatrix(),
+        u_normalMatrix: identityMatrix()
+      },
+      requiredAttributes: ["a_position", "a_normal"],
+      uniformSchema: [
+        { name: "u_baseColor", kind: "vec4" },
+        { name: "u_alphaCutoff", kind: "float" },
+        { name: "u_metallic", kind: "float" },
+        { name: "u_roughness", kind: "float" },
+        { name: "u_environmentColor", kind: "vec3" },
+        { name: "u_environmentIntensity", kind: "float" },
+        { name: "u_environmentSkyColor", kind: "vec3" },
+        { name: "u_environmentHorizonColor", kind: "vec3" },
+        { name: "u_environmentGroundColor", kind: "vec3" },
+        { name: "u_environmentSpecularColor", kind: "vec3" },
+        { name: "u_environmentMapIntensity", kind: "float" },
+        { name: "u_environmentSpecularIntensity", kind: "float" },
+        { name: "u_environmentMapTexture", kind: "texture2d", required: false },
+        { name: "u_environmentMapTextureEnabled", kind: "float" },
+        { name: "u_environmentMapTextureIntensity", kind: "float" },
+        { name: "u_environmentMapTextureSpecularIntensity", kind: "float" },
+        { name: "u_environmentMapTextureRotation", kind: "float" },
+        { name: "u_environmentMapTextureMipCount", kind: "float" },
+        { name: "u_environmentMapTextureEncoding", kind: "float" },
+        { name: "u_environmentBrdfLutTexture", kind: "texture2d", required: false },
+        { name: "u_environmentBrdfLutEnabled", kind: "float", required: false },
+        { name: "u_emissiveColor", kind: "vec3" },
+        { name: "u_emissiveStrength", kind: "float" },
+        { name: "u_lightCount", kind: "float" },
+        { name: "u_lightData", kind: "any" },
+        { name: "u_instanceMatrices", kind: "any" },
+        { name: "u_instanceCount", kind: "float" },
+        { name: "u_instanceAttributeMode", kind: "float" },
+        { name: "u_modelViewProjection", kind: "mat4" },
+        { name: "u_normalMatrix", kind: "mat4" }
+      ]
+    });
+  }
+}
+
+function defaultInstanceMatrices(): Float32Array {
+  const matrices = new Float32Array(MAX_INSTANCED_PBR_INSTANCES * 16);
+  matrices.set(identityMatrix(), 0);
+  return matrices;
+}
+
+function validateNonNegative(value: number, label: string): void {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new RangeError(`InstancedPBRMaterial ${label} must be finite and non-negative`);
+  }
+}
+
+function validateFinite(value: number, label: string): void {
+  if (!Number.isFinite(value)) {
+    throw new RangeError(`InstancedPBRMaterial ${label} must be finite`);
+  }
+}
+
+function validateMipCount(value: number): void {
+  if (!Number.isInteger(value) || value < 1) {
+    throw new RangeError("InstancedPBRMaterial environmentMapMipCount must be a positive integer");
+  }
+}
+
+function validateProceduralEnvironmentMap(value: InstancedPBRProceduralEnvironmentMapOptions): void {
+  validateColor3(value.skyColor, "proceduralEnvironmentMap.skyColor");
+  validateColor3(value.horizonColor, "proceduralEnvironmentMap.horizonColor");
+  validateColor3(value.groundColor, "proceduralEnvironmentMap.groundColor");
+  validateColor3(value.specularColor, "proceduralEnvironmentMap.specularColor");
+  validateNonNegative(value.intensity, "proceduralEnvironmentMap.intensity");
+  validateNonNegative(value.specularIntensity, "proceduralEnvironmentMap.specularIntensity");
+}
+
+function validateUnit(value: number, label: string): void {
+  if (!Number.isFinite(value) || value < 0 || value > 1) {
+    throw new RangeError(`InstancedPBRMaterial ${label} must be finite and within [0, 1]`);
+  }
+}
+
+function validateColor4(value: readonly number[], label: string): void {
+  if (value.length !== 4 || value.some((channel) => !Number.isFinite(channel) || channel < 0 || channel > 1)) {
+    throw new RangeError(`InstancedPBRMaterial ${label} must contain four finite values in [0, 1]`);
+  }
+}
+
+function validateColor3(value: readonly number[], label: string): void {
+  if (value.length !== 3 || value.some((channel) => !Number.isFinite(channel) || channel < 0 || channel > 1)) {
+    throw new RangeError(`InstancedPBRMaterial ${label} must contain three finite values in [0, 1]`);
+  }
+}
+
+function identityMatrix(): Float32Array {
+  return new Float32Array([
+    1, 0, 0, 0,
+    0, 1, 0, 0,
+    0, 0, 1, 0,
+    0, 0, 0, 1
+  ]);
+}

package/src/InstancedUnlitMaterial.ts

@@ -0,0 +1,60 @@
+import { Material, type RenderState } from "./Material";
+import { DEFAULT_INSTANCED_UNLIT_SHADER_NAME } from "./ShaderLibrary";
+
+export const MAX_INSTANCED_UNLIT_INSTANCES = 64;
+
+export interface InstancedUnlitMaterialOptions {
+  readonly name?: string;
+  readonly color?: readonly [number, number, number, number];
+  readonly renderState?: Partial<RenderState>;
+}
+
+export class InstancedUnlitMaterial extends Material {
+  constructor(options: InstancedUnlitMaterialOptions = {}) {
+    const color = options.color ?? [1, 1, 1, 1];
+    validateColor(color);
+    super({
+      name: options.name ?? "instanced-unlit",
+      shaderKey: DEFAULT_INSTANCED_UNLIT_SHADER_NAME,
+      renderState: options.renderState,
+      parameters: {
+        u_baseColor: color,
+        u_alphaCutoff: 0,
+        u_instanceMatrices: defaultInstanceMatrices(),
+        u_instanceCount: 1,
+        u_instanceAttributeMode: 0,
+        u_modelViewProjection: identityMatrix()
+      },
+      requiredAttributes: ["a_position"],
+      uniformSchema: [
+        { name: "u_baseColor", kind: "vec4" },
+        { name: "u_alphaCutoff", kind: "float" },
+        { name: "u_instanceMatrices", kind: "any" },
+        { name: "u_instanceCount", kind: "float" },
+        { name: "u_instanceAttributeMode", kind: "float" },
+        { name: "u_modelViewProjection", kind: "mat4" }
+      ]
+    });
+  }
+}
+
+function defaultInstanceMatrices(): Float32Array {
+  const matrices = new Float32Array(MAX_INSTANCED_UNLIT_INSTANCES * 16);
+  matrices.set(identityMatrix(), 0);
+  return matrices;
+}
+
+function validateColor(color: readonly [number, number, number, number]): void {
+  if (color.length !== 4 || color.some((channel) => channel < 0 || channel > 1 || !Number.isFinite(channel))) {
+    throw new Error("InstancedUnlitMaterial color must contain four finite values in [0, 1]");
+  }
+}
+
+function identityMatrix(): Float32Array {
+  return new Float32Array([
+    1, 0, 0, 0,
+    0, 1, 0, 0,
+    0, 0, 1, 0,
+    0, 0, 0, 1
+  ]);
+}

package/src/Instancing.ts

@@ -0,0 +1,19 @@
+import type { InstanceVertexAttribute, RenderBuffer } from "./RenderDevice";
+
+export interface InstanceAttributePlan {
+  readonly attributes: readonly InstanceVertexAttribute[];
+  readonly instanceCount: number;
+}
+
+export function createMatrixInstanceAttribute(buffer: RenderBuffer, instanceCount: number, shaderPrefix = "a_instanceMatrix"): InstanceAttributePlan {
+  if (!Number.isInteger(instanceCount) || instanceCount <= 0) throw new Error("instanceCount must be a positive integer.");
+  const attributes: InstanceVertexAttribute[] = [0, 1, 2, 3].map((column) => ({
+    buffer,
+    shaderName: `${shaderPrefix}${column}`,
+    components: 4,
+    stride: 64,
+    offset: column * 16,
+    divisor: 1
+  }));
+  return { attributes, instanceCount };
+}

package/src/LightCollector.ts

@@ -0,0 +1,82 @@
+import { DirectionalLight, Light, PointLight, Scene, SpotLight } from "@aura3d/scene";
+
+export type CollectedLightKind = "directional" | "point" | "spot";
+
+export interface CollectedLight {
+  readonly kind: CollectedLightKind;
+  readonly color: readonly [number, number, number];
+  readonly intensity: number;
+  readonly position: readonly [number, number, number];
+  readonly direction: readonly [number, number, number];
+  readonly range: number;
+  readonly spotAngle: number;
+  readonly penumbra: number;
+  readonly castsShadow: boolean;
+  readonly layerMask: number;
+  readonly source: Light;
+}
+
+export interface LightCollectorOptions {
+  readonly maxLights?: number;
+  readonly layerMask?: number;
+  readonly includeDisabled?: boolean;
+}
+
+export class LightCollector {
+  collect(scene: Scene, options: LightCollectorOptions = {}): readonly CollectedLight[] {
+    const maxLights = options.maxLights ?? Number.POSITIVE_INFINITY;
+    if (maxLights !== Number.POSITIVE_INFINITY && (!Number.isInteger(maxLights) || maxLights < 0)) {
+      throw new RangeError("LightCollector maxLights must be a non-negative integer");
+    }
+    scene.updateWorldTransforms();
+    return scene
+      .collectLights()
+      .filter((light) => (options.includeDisabled ?? false) || light.visible)
+      .filter((light) => ((options.layerMask ?? 0xffffffff) & light.layerMask) !== 0)
+      .map((light) => collectLight(light))
+      .sort((a, b) => b.intensity - a.intensity)
+      .slice(0, maxLights);
+  }
+}
+
+function collectLight(light: Light): CollectedLight {
+  const matrix = matrixElements(light.transform.worldMatrix);
+  const position: [number, number, number] = [matrix[12], matrix[13], matrix[14]];
+  const direction = light instanceof DirectionalLight
+    ? vectorToTuple(light.getDirection())
+    : normalize([-matrix[8], -matrix[9], -matrix[10]]);
+  const range = light instanceof PointLight || light instanceof SpotLight ? light.range : 0;
+  const spotAngle = light instanceof SpotLight ? light.angle : 0;
+  const penumbra = light instanceof SpotLight ? light.penumbra : 0;
+  return {
+    kind: light.kind,
+    color: vectorToTuple(light.color),
+    intensity: light.intensity,
+    position,
+    direction,
+    range,
+    spotAngle,
+    penumbra,
+    castsShadow: light.castsShadow,
+    layerMask: light.layerMask,
+    source: light
+  };
+}
+
+function vectorToTuple(value: unknown): readonly [number, number, number] {
+  if (Array.isArray(value)) {
+    return [value[0] ?? 0, value[1] ?? 0, value[2] ?? 0];
+  }
+  const vector = value as { readonly x?: number; readonly y?: number; readonly z?: number };
+  return [vector.x ?? 0, vector.y ?? 0, vector.z ?? 0];
+}
+
+function matrixElements(value: unknown): readonly number[] {
+  const elements = (value as { readonly elements?: readonly number[] }).elements;
+  return elements ?? (value as readonly number[]);
+}
+
+function normalize(value: readonly [number, number, number]): readonly [number, number, number] {
+  const length = Math.hypot(value[0], value[1], value[2]);
+  return length === 0 ? [0, 0, -1] : [value[0] / length, value[1] / length, value[2] / length];
+}

package/src/LightUniforms.ts

@@ -0,0 +1,47 @@
+import { type CollectedLight } from "./LightCollector";
+import { UniformLayout } from "./UniformLayout";
+
+export const MAX_DIRECT_LIGHTS = 16;
+
+export interface PackedLightUniforms {
+  readonly lightCount: number;
+  readonly data: Float32Array;
+  readonly layout: UniformLayout;
+}
+
+export class LightUniforms {
+  static readonly floatsPerLight = 16;
+
+  static readonly layout = new UniformLayout([
+    { name: "u_lightCount", type: "float" },
+    { name: "u_lightData", type: "vec4", arrayLength: MAX_DIRECT_LIGHTS * 4 }
+  ]);
+
+  static pack(lights: readonly CollectedLight[], maxLights = MAX_DIRECT_LIGHTS): PackedLightUniforms {
+    if (!Number.isInteger(maxLights) || maxLights <= 0 || maxLights > MAX_DIRECT_LIGHTS) {
+      throw new RangeError(`maxLights must be an integer in [1, ${MAX_DIRECT_LIGHTS}]`);
+    }
+    const selected = lights.slice(0, maxLights);
+    const data = new Float32Array(MAX_DIRECT_LIGHTS * LightUniforms.floatsPerLight);
+    selected.forEach((light, index) => {
+      const offset = index * LightUniforms.floatsPerLight;
+      const forwardShadowSupported = light.castsShadow;
+      data.set([light.color[0], light.color[1], light.color[2], light.intensity], offset);
+      data.set([light.position[0], light.position[1], light.position[2], light.range], offset + 4);
+      data.set([light.direction[0], light.direction[1], light.direction[2], kindToFloat(light.kind)], offset + 8);
+      data.set([light.spotAngle, light.penumbra, forwardShadowSupported ? 1 : 0, light.layerMask], offset + 12);
+    });
+    return { lightCount: selected.length, data, layout: LightUniforms.layout };
+  }
+}
+
+function kindToFloat(kind: CollectedLight["kind"]): number {
+  switch (kind) {
+    case "directional":
+      return 0;
+    case "point":
+      return 1;
+    case "spot":
+      return 2;
+  }
+}