@aura3d/rendering 1.4.0 → 1.4.2

package/src/CullingFixtures.ts

@@ -1,280 +0,0 @@
-export interface CullingFixtureOptions {
-  readonly seed?: number;
-  readonly objectCount?: number;
-  readonly cameraX?: number;
-  readonly depthResolution?: readonly [number, number];
-}
-
-export interface CullingFixtureObject {
-  readonly id: string;
-  readonly center: readonly [number, number, number];
-  readonly halfExtents: readonly [number, number, number];
-  readonly projectedAreaPixels: number;
-}
-
-export interface CullingBvhTelemetry {
-  readonly nodeCount: number;
-  readonly leafCount: number;
-  readonly objectCount: number;
-  readonly maxDepth: number;
-  readonly averageLeafObjects: number;
-  readonly sahSplitCount: number;
-  readonly boundsTests: number;
-  readonly objectTests: number;
-  readonly rangeQueryHits: number;
-  readonly raycastHitId: string | null;
-  readonly raycastDistance: number;
-}
-
-export interface CullingFrustumTelemetry {
-  readonly testedObjects: number;
-  readonly visibleObjects: number;
-  readonly culledObjects: number;
-  readonly visibleRatio: number;
-}
-
-export interface CullingHiZTelemetry {
-  readonly depthResolution: readonly [number, number];
-  readonly mipLevels: number;
-  readonly depthPyramidTexels: number;
-  readonly maxDepthSamples: number;
-  readonly conservativeTests: number;
-  readonly visibleObjects: number;
-  readonly occludedObjects: number;
-  readonly unknownResults: number;
-  readonly frameCoherentReused: number;
-  readonly depthThreshold: number;
-  readonly estimatedBuildMs: number;
-  readonly estimatedTestMs: number;
-}
-
-export interface CullingFeatureEvidence {
-  readonly bvhHierarchy: boolean;
-  readonly frustumTraversal: boolean;
-  readonly hizPyramid: boolean;
-  readonly conservativeOcclusion: boolean;
-  readonly frameCoherency: boolean;
-}
-
-export interface CullingFixture {
-  readonly id: "external-parity-old-branch-bvh-hiz-culling-fixture";
-  readonly source: "origin-master-bvh-hiz-occlusion-adapted";
-  readonly sourceFiles: readonly string[];
-  readonly seed: number;
-  readonly cameraX: number;
-  readonly objectCount: number;
-  readonly objects: readonly CullingFixtureObject[];
-  readonly bvh: CullingBvhTelemetry;
-  readonly frustum: CullingFrustumTelemetry;
-  readonly hiz: CullingHiZTelemetry;
-  readonly featureEvidence: CullingFeatureEvidence;
-  readonly hash: string;
-  readonly claimBoundary: string;
-  readonly blockedClaims: readonly string[];
-}
-
-const sourceFiles = [
-  "origin/master:src/rendering/culling/BVH.ts",
-  "origin/master:src/rendering/culling/HiZCulling.ts",
-  "origin/master:src/rendering/culling/OcclusionCuller.ts",
-  "origin/master:src/rendering/culling/FrustumCuller.ts",
-  "origin/master:src/rendering/culling/GPUCulling.ts"
-] as const;
-
-const blockedClaims = [
-  "production GPU occlusion culling parity",
-  "hardware occlusion query parity",
-  "production Hi-Z renderer integration",
-  "portal/sector visibility parity",
-  "Unity occlusion culling parity",
-  "Unreal Nanite/occlusion parity"
-] as const;
-
-export function sampleCullingFixture(options: CullingFixtureOptions = {}): CullingFixture {
-  const seed = integer(options.seed ?? 0x3d2025, "seed");
-  const objectCount = integerRange(options.objectCount ?? 32, 8, 256, "objectCount");
-  const cameraX = finiteNumber(options.cameraX ?? 0, "cameraX");
-  const depthResolution = depthResolutionOption(options.depthResolution ?? [320, 180]);
-  const objects = createObjects(seed, objectCount, cameraX, depthResolution);
-  const visible = objects.filter((object) => inFrustum(object, cameraX));
-  const culledObjects = objectCount - visible.length;
-  const occlusionResults = visible.map((object, index) => ({
-    object,
-    occluded: isOccludedByHiZ(object, index, cameraX),
-    unknown: (index + seed) % 13 === 0
-  }));
-  const occludedObjects = occlusionResults.filter((result) => result.occluded && !result.unknown).length;
-  const unknownResults = occlusionResults.filter((result) => result.unknown).length;
-  const hizVisibleObjects = Math.max(0, visible.length - occludedObjects - unknownResults);
-  const leafSize = 4;
-  const leafCount = Math.ceil(objectCount / leafSize);
-  const nodeCount = leafCount * 2 - 1;
-  const maxDepth = Math.ceil(Math.log2(Math.max(1, leafCount))) + 1;
-  const mipLevels = mipCount(depthResolution[0], depthResolution[1]);
-  const depthPyramidTexels = depthTexels(depthResolution[0], depthResolution[1], mipLevels);
-  const rayHit = nearestRayHit(objects, cameraX);
-  const bvh: CullingBvhTelemetry = {
-    nodeCount,
-    leafCount,
-    objectCount,
-    maxDepth,
-    averageLeafObjects: round3(objectCount / leafCount),
-    sahSplitCount: Math.max(0, leafCount - 1),
-    boundsTests: nodeCount + visible.length * 2,
-    objectTests: Math.max(1, Math.ceil(visible.length * 0.65)),
-    rangeQueryHits: objects.filter((object) => Math.hypot(object.center[0] - cameraX, object.center[2]) < 0.85).length,
-    raycastHitId: rayHit?.id ?? null,
-    raycastDistance: rayHit?.distance ?? 0
-  };
-  const frustum: CullingFrustumTelemetry = {
-    testedObjects: objectCount,
-    visibleObjects: visible.length,
-    culledObjects,
-    visibleRatio: round3(visible.length / objectCount)
-  };
-  const hiz: CullingHiZTelemetry = {
-    depthResolution,
-    mipLevels,
-    depthPyramidTexels,
-    maxDepthSamples: Math.min(depthPyramidTexels, 128),
-    conservativeTests: visible.length,
-    visibleObjects: hizVisibleObjects,
-    occludedObjects,
-    unknownResults,
-    frameCoherentReused: Math.max(1, Math.floor(visible.length * 0.35)),
-    depthThreshold: 0.001,
-    estimatedBuildMs: round3(Math.min(0.49, depthPyramidTexels / 1_250_000)),
-    estimatedTestMs: round3(Math.min(0.29, visible.length / 9_500))
-  };
-  const hash = stableHash([
-    seed,
-    objectCount,
-    cameraX.toFixed(3),
-    depthResolution.join("x"),
-    objects.map((object) => `${object.id}:${object.center.join(",")}:${object.projectedAreaPixels}`).join("|"),
-    `${bvh.nodeCount}:${bvh.maxDepth}:${frustum.visibleObjects}:${hiz.occludedObjects}:${hiz.visibleObjects}:${hiz.unknownResults}`
-  ].join("#"));
-  return {
-    id: "external-parity-old-branch-bvh-hiz-culling-fixture",
-    source: "origin-master-bvh-hiz-occlusion-adapted",
-    sourceFiles,
-    seed,
-    cameraX: round3(cameraX),
-    objectCount,
-    objects,
-    bvh,
-    frustum,
-    hiz,
-    featureEvidence: {
-      bvhHierarchy: bvh.nodeCount > bvh.leafCount && bvh.maxDepth > 1,
-      frustumTraversal: frustum.visibleObjects > 0 && frustum.culledObjects > 0,
-      hizPyramid: hiz.mipLevels > 1 && hiz.depthPyramidTexels > depthResolution[0] * depthResolution[1],
-      conservativeOcclusion: hiz.conservativeTests > 0 && hiz.occludedObjects > 0 && hiz.visibleObjects > 0,
-      frameCoherency: hiz.frameCoherentReused > 0
-    },
-    hash,
-    claimBoundary: "Deterministic BVH, frustum traversal, Hi-Z mip telemetry, conservative occlusion-test counts, and frame-coherency metrics adapted from the old culling subsystem; this is bounded fixture evidence, not production GPU occlusion culling, hardware query, portal, or Nanite-style visibility parity.",
-    blockedClaims
-  };
-}
-
-function createObjects(
-  seed: number,
-  objectCount: number,
-  cameraX: number,
-  depthResolution: readonly [number, number]
-): readonly CullingFixtureObject[] {
-  return Array.from({ length: objectCount }, (_, index) => {
-    const lane = index % 5;
-    const t = objectCount <= 1 ? 0 : index / (objectCount - 1);
-    const centerX = -2.05 + t * 4.1 + (hash01(seed, index) - 0.5) * 0.12;
-    const centerY = -0.18 + (lane - 2) * 0.045 + hash01(seed + 17, index) * 0.08;
-    const centerZ = -0.18 + lane * 0.17 + hash01(seed + 29, index) * 0.08;
-    const halfX = 0.045 + hash01(seed + 41, index) * 0.08;
-    const halfY = 0.08 + hash01(seed + 53, index) * 0.18;
-    const halfZ = 0.035 + hash01(seed + 67, index) * 0.06;
-    const distance = Math.max(0.12, Math.hypot(centerX - cameraX, centerZ + 0.25));
-    const screenScale = Math.max(depthResolution[0], depthResolution[1]) / 4.5;
-    return {
-      id: `cull-object-${String(index).padStart(2, "0")}`,
-      center: [round3(centerX), round3(centerY), round3(centerZ)],
-      halfExtents: [round3(halfX), round3(halfY), round3(halfZ)],
-      projectedAreaPixels: Math.max(1, Math.round((halfX * 2 * halfY * 2 * screenScale) / distance))
-    };
-  });
-}
-
-function inFrustum(object: CullingFixtureObject, cameraX: number): boolean {
-  const x = object.center[0] - cameraX;
-  const z = object.center[2];
-  return Math.abs(x) <= 1.32 && z >= -0.22 && z <= 0.72;
-}
-
-function isOccludedByHiZ(object: CullingFixtureObject, visibleIndex: number, cameraX: number): boolean {
-  const distance = Math.hypot(object.center[0] - cameraX, object.center[2] + 0.18);
-  const smallEnoughForConservativeTest = object.projectedAreaPixels < 18;
-  return distance > 0.74 && (smallEnoughForConservativeTest || visibleIndex % 4 === 1);
-}
-
-function nearestRayHit(objects: readonly CullingFixtureObject[], cameraX: number): { readonly id: string; readonly distance: number } | null {
-  let best: { readonly id: string; readonly distance: number } | null = null;
-  for (const object of objects) {
-    const screenX = Math.abs(object.center[0] - cameraX);
-    if (screenX > object.halfExtents[0] + 0.08) continue;
-    const distance = Math.hypot(object.center[0] - cameraX, object.center[1], object.center[2] + 1);
-    if (!best || distance < best.distance) best = { id: object.id, distance: round3(distance) };
-  }
-  return best;
-}
-
-function depthResolutionOption(value: readonly [number, number]): readonly [number, number] {
-  const width = integerRange(value[0], 64, 4096, "depthResolution[0]");
-  const height = integerRange(value[1], 64, 4096, "depthResolution[1]");
-  return [width, height];
-}
-
-function mipCount(width: number, height: number): number {
-  return Math.floor(Math.log2(Math.max(width, height))) + 1;
-}
-
-function depthTexels(width: number, height: number, levels: number): number {
-  let texels = 0;
-  for (let level = 0; level < levels; level += 1) {
-    texels += Math.max(1, Math.ceil(width / 2 ** level)) * Math.max(1, Math.ceil(height / 2 ** level));
-  }
-  return texels;
-}
-
-function integer(value: number, name: string): number {
-  if (!Number.isInteger(value)) throw new RangeError(`Culling fixture ${name} must be an integer.`);
-  return value;
-}
-
-function integerRange(value: number, min: number, max: number, name: string): number {
-  const result = integer(value, name);
-  if (result < min || result > max) throw new RangeError(`Culling fixture ${name} must be between ${min} and ${max}.`);
-  return result;
-}
-
-function finiteNumber(value: number, name: string): number {
-  if (!Number.isFinite(value)) throw new RangeError(`Culling fixture ${name} must be finite.`);
-  return value;
-}
-
-function hash01(seed: number, index: number): number {
-  const x = Math.sin(seed * 12.9898 + index * 78.233) * 43758.5453;
-  return x - Math.floor(x);
-}
-
-function stableHash(input: string): string {
-  let hash = 0x811c9dc5;
-  for (let index = 0; index < input.length; index += 1) {
-    hash ^= input.charCodeAt(index);
-    hash = Math.imul(hash, 0x01000193);
-  }
-  return (hash >>> 0).toString(16).padStart(8, "0");
-}
-
-function round3(value: number): number {
-  return Number(value.toFixed(3));
-}

package/src/DecalGeometry.ts

@@ -1,26 +0,0 @@
-export {
-  createProjectedDecalGeometry as createDecalGeometry,
-  createProjectedDecalGeometry,
-  createRaycastProjectedDecalGeometry,
-  raycastProjectedDecalMesh
-} from "./production-runtime/geometry/ProjectedDecalGeometry";
-export type {
-  ProjectedDecalBasis as DecalBasis,
-  ProjectedDecalBox as DecalBox,
-  ProjectedDecalGeometryResult as DecalGeometryResult,
-  ProjectedDecalRay as DecalRay,
-  ProjectedDecalRaycastHit as DecalRaycastHit,
-  ProjectedDecalRaycastOptions as DecalRaycastOptions,
-  ProjectedDecalRaycastResult as DecalRaycastResult,
-  ProjectedDecalShape as DecalShape,
-  ProjectedDecalTriangleMesh as DecalTriangleMesh,
-  ProjectedDecalBasis,
-  ProjectedDecalBox,
-  ProjectedDecalGeometryResult,
-  ProjectedDecalRay,
-  ProjectedDecalRaycastHit,
-  ProjectedDecalRaycastOptions,
-  ProjectedDecalRaycastResult,
-  ProjectedDecalShape,
-  ProjectedDecalTriangleMesh
-} from "./production-runtime/geometry/ProjectedDecalGeometry";

package/src/DepthPass.ts

@@ -1,110 +0,0 @@
-import { Material } from "./Material";
-import { type DrawCommand, type RenderDevice, RenderDeviceError, type RenderShaderProgram } from "./RenderDevice";
-import { BaseRenderPass, type RenderPassContext } from "./RenderPass";
-import { ShaderModule } from "./ShaderModule";
-import { DEFAULT_DEPTH_SHADER_NAME, type ShaderLibrary, createDefaultShaderLibrary } from "./ShaderLibrary";
-import { type RenderItem } from "./ForwardPass";
-import { identityMat4, multiplyMat4, type Mat4 } from "@aura3d/scene";
-
-export interface DepthPassOptions {
-  readonly casters: readonly RenderItem[];
-  readonly shaderLibrary?: ShaderLibrary;
-  readonly viewProjectionMatrix?: Float32Array | readonly number[];
-}
-
-export class DepthMaterial extends Material {
-  constructor() {
-    super({
-      name: "depth",
-      shaderKey: DEFAULT_DEPTH_SHADER_NAME,
-      parameters: {
-        u_modelViewProjection: identityMatrix()
-      },
-      requiredAttributes: ["a_position"],
-      uniformSchema: [{ name: "u_modelViewProjection", kind: "mat4" }]
-    });
-  }
-}
-
-export class DepthPass extends BaseRenderPass {
-  private readonly shaderLibrary: ShaderLibrary;
-  private readonly material = new DepthMaterial();
-  private shaderModule: ShaderModule | null = null;
-
-  constructor(private readonly options: DepthPassOptions) {
-    super("depth", [], ["depth"]);
-    this.shaderLibrary = options.shaderLibrary ?? createDefaultShaderLibrary();
-  }
-
-  execute(context: RenderPassContext): void {
-    for (const caster of this.options.casters) {
-      this.drawCaster(context.device, caster);
-    }
-  }
-
-  private drawCaster(device: RenderDevice, caster: RenderItem): void {
-    const shader = this.getShader(device);
-    const vertexBuffer = caster.geometry.vertexBuffer.upload(device);
-    const indexBuffer = caster.geometry.indexBuffer?.upload(device);
-    const drawRange = resolveDepthDrawRange(caster.geometry, caster.drawRange);
-    const modelMatrix = toMat4(caster.modelMatrix ?? identityMat4(), caster.label);
-    const viewProjection = toMat4(this.options.viewProjectionMatrix ?? identityMat4(), caster.label);
-    this.material.setParameter("u_modelViewProjection", multiplyMat4(viewProjection, modelMatrix));
-    const command: DrawCommand = {
-      label: caster.label ?? "shadow-caster",
-      topology: caster.geometry.topology,
-      vertexBuffer,
-      vertexFormat: caster.geometry.vertexBuffer.format,
-      vertexCount: indexBuffer ? caster.geometry.vertexBuffer.vertexCount : drawRange.count,
-      ...(indexBuffer === undefined && drawRange.start > 0 ? { firstVertex: drawRange.start } : {}),
-      shader,
-      uniforms: this.material.getParameters()
-    };
-    if (indexBuffer) {
-      Object.assign(command, {
-        indexBuffer,
-        indexType: caster.geometry.indexBuffer?.type,
-        indexCount: drawRange.count,
-        ...(drawRange.start > 0 ? { firstIndex: drawRange.start } : {})
-      });
-    }
-    device.draw(command);
-  }
-
-  private getShader(device: RenderDevice): RenderShaderProgram {
-    if (!this.shaderModule) {
-      this.shaderModule = ShaderModule.fromLibrary(this.shaderLibrary, this.material.shaderKey);
-    }
-    return this.shaderModule.compile(device);
-  }
-}
-
-function resolveDepthDrawRange(geometry: RenderItem["geometry"], range: RenderItem["drawRange"]): { readonly start: number; readonly count: number } {
-  const available = geometry.indexBuffer?.count ?? geometry.vertexBuffer.vertexCount;
-  if (!range) return { start: 0, count: available };
-  if (!Number.isInteger(range.start) || range.start < 0 || !Number.isInteger(range.count) || range.count <= 0 || range.start + range.count > available) {
-    throw new RenderDeviceError("Depth caster drawRange must fit inside geometry draw count", "DEPTH_DRAW_RANGE_INVALID", {
-      start: range.start,
-      count: range.count,
-      available
-    });
-  }
-  return range;
-}
-
-function identityMatrix(): Float32Array {
-  return new Float32Array([
-    1, 0, 0, 0,
-    0, 1, 0, 0,
-    0, 0, 1, 0,
-    0, 0, 0, 1
-  ]);
-}
-
-function toMat4(value: Float32Array | readonly number[], label?: string): Mat4 {
-  const values = Array.from(value);
-  if (values.length !== 16 || values.some((entry) => !Number.isFinite(entry))) {
-    throw new Error(`DepthPass ${label ?? "caster"} matrix must contain 16 finite numbers.`);
-  }
-  return values as unknown as Mat4;
-}

package/src/EnvironmentBackgroundPass.ts

@@ -1,194 +0,0 @@
-import { Geometry } from "./Geometry";
-import { DEFAULT_RENDER_STATE } from "./Material";
-import { type RenderDevice, RenderDeviceError, type RenderShaderProgram, type UniformValue } from "./RenderDevice";
-import { RenderPipeline } from "./RenderPipeline";
-import { BaseRenderPass, type RenderPassContext } from "./RenderPass";
-import { ShaderModule } from "./ShaderModule";
-import { createDefaultShaderLibrary, DEFAULT_ENVIRONMENT_BACKGROUND_SHADER_NAME, type ShaderLibrary } from "./ShaderLibrary";
-import { TextureBinding } from "./TextureBinding";
-import { VertexBuffer } from "./VertexBuffer";
-import { VertexFormat } from "./VertexFormat";
-
-export type EnvironmentBackgroundProjection = "equirect" | "cubemap";
-export type EnvironmentBackgroundEncoding = "linear" | "srgb" | "rgbe";
-
-export interface EnvironmentBackgroundOptions {
-  readonly projection: EnvironmentBackgroundProjection;
-  readonly texture: TextureBinding;
-  readonly encoding?: EnvironmentBackgroundEncoding;
-  readonly intensity?: number;
-  readonly rotation?: number;
-  readonly outputColorSpace?: "linear" | "srgb";
-  readonly inverseViewProjectionMatrix?: Float32Array | readonly number[];
-  readonly shaderLibrary?: ShaderLibrary;
-}
-
-export const ENVIRONMENT_BACKGROUND_COLOR_RESOURCE = "environment-background-color";
-
-const BACKGROUND_RENDER_STATE = {
-  ...DEFAULT_RENDER_STATE,
-  depthTest: false,
-  depthWrite: false,
-  cullMode: "none" as const
-};
-
-export class EnvironmentBackgroundPass extends BaseRenderPass {
-  private static readonly shaderCaches = new WeakMap<RenderDevice, WeakMap<ShaderLibrary, ShaderModule>>();
-  private readonly shaderLibrary: ShaderLibrary;
-
-  constructor(private readonly options: EnvironmentBackgroundOptions) {
-    super("environment-background", [], [ENVIRONMENT_BACKGROUND_COLOR_RESOURCE]);
-    this.shaderLibrary = options.shaderLibrary ?? createDefaultShaderLibrary();
-  }
-
-  execute(context: RenderPassContext): void {
-    validateEnvironmentBackgroundOptions(this.options);
-    const geometry = createFullscreenTriangleGeometry();
-    try {
-      const shader = this.getShader(context.device);
-      const pipeline = new RenderPipeline({
-        label: "environment-background",
-        shader,
-        vertexFormat: geometry.vertexBuffer.format,
-        topology: geometry.topology,
-        renderState: BACKGROUND_RENDER_STATE
-      });
-      const command = pipeline.createDrawCommand({
-        label: "environment-background",
-        vertexBuffer: geometry.vertexBuffer.upload(context.device),
-        vertexCount: geometry.vertexBuffer.vertexCount,
-        uniforms: createEnvironmentBackgroundUniforms(this.options)
-      });
-      context.device.draw(command);
-    } finally {
-      geometry.dispose();
-    }
-  }
-
-  private getShader(device: RenderDevice): RenderShaderProgram {
-    let libraryCaches = EnvironmentBackgroundPass.shaderCaches.get(device);
-    if (!libraryCaches) {
-      libraryCaches = new WeakMap<ShaderLibrary, ShaderModule>();
-      EnvironmentBackgroundPass.shaderCaches.set(device, libraryCaches);
-    }
-    let module = libraryCaches.get(this.shaderLibrary);
-    if (!module) {
-      module = ShaderModule.fromLibrary(this.shaderLibrary, DEFAULT_ENVIRONMENT_BACKGROUND_SHADER_NAME);
-      libraryCaches.set(this.shaderLibrary, module);
-    }
-    return module.compile(device);
-  }
-}
-
-export function createEnvironmentBackgroundUniforms(options: EnvironmentBackgroundOptions): ReadonlyMap<string, UniformValue> {
-  validateEnvironmentBackgroundOptions(options);
-  const projectionMode = options.projection === "cubemap" ? 2 : 1;
-  const encoding = options.encoding ?? "linear";
-  const uniforms = new Map<string, UniformValue>();
-  uniforms.set(
-    "u_environmentBackgroundTexture",
-    options.projection === "equirect"
-      ? options.texture
-      : new TextureBinding({ name: "u_environmentBackgroundTexture", required: false })
-  );
-  uniforms.set(
-    "u_environmentBackgroundCubeTexture",
-    options.projection === "cubemap"
-      ? options.texture
-      : new TextureBinding({ name: "u_environmentBackgroundCubeTexture", required: false })
-  );
-  uniforms.set("u_environmentBackgroundProjection", projectionMode);
-  uniforms.set("u_environmentBackgroundRotation", options.rotation ?? 0);
-  uniforms.set("u_environmentBackgroundIntensity", options.intensity ?? 1);
-  uniforms.set("u_environmentBackgroundEncoding", backgroundEncodingUniform(encoding));
-  uniforms.set("u_outputColorSpace", (options.outputColorSpace ?? "srgb") === "srgb" ? 1 : 0);
-  uniforms.set("u_environmentBackgroundInverseViewProjection", toMat4Uniform(options.inverseViewProjectionMatrix, "inverseViewProjectionMatrix"));
-  return uniforms;
-}
-
-function createFullscreenTriangleGeometry(): Geometry {
-  const vertices = new VertexBuffer(VertexFormat.P3, 3);
-  vertices.setAttribute(0, "position", [-1, -1, 0]);
-  vertices.setAttribute(1, "position", [3, -1, 0]);
-  vertices.setAttribute(2, "position", [-1, 3, 0]);
-  return new Geometry(vertices, null, "triangles", { min: [-1, -1, 0], max: [3, 3, 0] });
-}
-
-function validateEnvironmentBackgroundOptions(options: EnvironmentBackgroundOptions): void {
-  if (options.projection !== "equirect" && options.projection !== "cubemap") {
-    throw new RenderDeviceError("Environment background projection must be equirect or cubemap", "ENVIRONMENT_BACKGROUND_CONTRACT", {
-      projection: options.projection
-    });
-  }
-  const validation = options.texture.validate();
-  if (!options.texture.texture) {
-    throw new RenderDeviceError("Environment background requires a texture binding", "ENVIRONMENT_BACKGROUND_CONTRACT", {
-      projection: options.projection,
-      diagnostics: ["Missing required texture: environment background"]
-    });
-  }
-  if (!validation.ok) {
-    throw new RenderDeviceError("Environment background texture binding validation failed", "ENVIRONMENT_BACKGROUND_CONTRACT", {
-      projection: options.projection,
-      diagnostics: validation.diagnostics
-    });
-  }
-  if (options.projection === "cubemap" && options.texture.texture.dimension !== "cube") {
-    throw new RenderDeviceError("Cubemap environment background requires a cube texture", "ENVIRONMENT_BACKGROUND_CONTRACT", {
-      textureDimension: options.texture.texture.dimension
-    });
-  }
-  if (options.projection === "equirect" && options.texture.texture.dimension !== "2d") {
-    throw new RenderDeviceError("Equirect environment background requires a 2D panorama texture", "ENVIRONMENT_BACKGROUND_CONTRACT", {
-      textureDimension: options.texture.texture.dimension
-    });
-  }
-  if (options.intensity !== undefined && (!Number.isFinite(options.intensity) || options.intensity < 0)) {
-    throw new RenderDeviceError("Environment background intensity must be finite and non-negative", "ENVIRONMENT_BACKGROUND_CONTRACT", {
-      intensity: options.intensity
-    });
-  }
-  if (options.rotation !== undefined && !Number.isFinite(options.rotation)) {
-    throw new RenderDeviceError("Environment background rotation must be finite", "ENVIRONMENT_BACKGROUND_CONTRACT", {
-      rotation: options.rotation
-    });
-  }
-  const outputColorSpace = options.outputColorSpace ?? "srgb";
-  if (outputColorSpace !== "linear" && outputColorSpace !== "srgb") {
-    throw new RenderDeviceError("Environment background outputColorSpace must be linear or srgb", "ENVIRONMENT_BACKGROUND_CONTRACT", {
-      outputColorSpace
-    });
-  }
-  backgroundEncodingUniform(options.encoding ?? "linear");
-  toMat4Uniform(options.inverseViewProjectionMatrix, "inverseViewProjectionMatrix");
-}
-
-function backgroundEncodingUniform(encoding: EnvironmentBackgroundEncoding): number {
-  switch (encoding) {
-    case "linear":
-    case "srgb":
-      return 0;
-    case "rgbe":
-      return 2;
-    default:
-      throw new RenderDeviceError("Environment background encoding must be linear, srgb, or rgbe", "ENVIRONMENT_BACKGROUND_CONTRACT", {
-        encoding
-      });
-  }
-}
-
-function toMat4Uniform(value: Float32Array | readonly number[] | undefined, label: string): Float32Array {
-  const source = value ?? [
-    1, 0, 0, 0,
-    0, 1, 0, 0,
-    0, 0, 1, 0,
-    0, 0, 0, 1
-  ];
-  if (source.length !== 16 || !Array.from(source).every(Number.isFinite)) {
-    throw new RenderDeviceError("Environment background inverse view-projection matrix must contain 16 finite numbers", "ENVIRONMENT_BACKGROUND_CONTRACT", {
-      label,
-      matrixLength: source.length
-    });
-  }
-  return new Float32Array(source);
-}