@aura3d/rendering 1.4.0 → 1.4.2

package/src/EnvironmentBackgroundResources.ts

@@ -1,309 +0,0 @@
-import {
-  createEnvironmentBackgroundUniforms,
-  type EnvironmentBackgroundEncoding,
-  type EnvironmentBackgroundOptions
-} from "./EnvironmentBackgroundPass";
-import { RenderDeviceError } from "./RenderDevice";
-import { Texture, bytesPerPixel, type TextureColorSpace, type TextureCubeFace, type TextureFormat, type TexturePixelData } from "./Texture";
-import { TextureBinding } from "./TextureBinding";
-
-export type EnvironmentBackgroundPixelFormat = Extract<TextureFormat, "rgba8" | "rgba16f" | "rgba32f">;
-
-export interface EnvironmentBackgroundResourceOptions {
-  readonly encoding?: EnvironmentBackgroundEncoding;
-  readonly intensity?: number;
-  readonly rotation?: number;
-  readonly outputColorSpace?: "linear" | "srgb";
-  readonly format?: EnvironmentBackgroundPixelFormat;
-  readonly colorSpace?: TextureColorSpace;
-  readonly textureLabel?: string;
-  readonly bindingName?: string;
-}
-
-export interface EquirectEnvironmentBackgroundResourceOptions extends EnvironmentBackgroundResourceOptions {
-  readonly width: number;
-  readonly height: number;
-  readonly data: TexturePixelData;
-}
-
-export interface CubemapEnvironmentBackgroundFacePixels {
-  readonly face: TextureCubeFace;
-  readonly data: TexturePixelData;
-}
-
-export interface CubemapEnvironmentBackgroundResourceOptions extends EnvironmentBackgroundResourceOptions {
-  readonly size: number;
-  readonly faces: readonly CubemapEnvironmentBackgroundFacePixels[];
-}
-
-export const ENVIRONMENT_BACKGROUND_CUBE_FACES: readonly TextureCubeFace[] = ["px", "nx", "py", "ny", "pz", "nz"];
-
-export function createEquirectEnvironmentBackgroundOptions(
-  options: EquirectEnvironmentBackgroundResourceOptions
-): EnvironmentBackgroundOptions {
-  const format = options.format ?? "rgba8";
-  const encoding = options.encoding ?? "linear";
-  const colorSpace = options.colorSpace ?? textureColorSpaceForEncoding(encoding);
-  validateEquirectPixelSource(options.width, options.height, options.data, format);
-  validateEncodingFormat(encoding, format);
-
-  const texture = new Texture({
-    width: options.width,
-    height: options.height,
-    dimension: "2d",
-    format,
-    colorSpace,
-    label: options.textureLabel ?? "environment-background-equirect",
-    data: options.data
-  });
-  const background: EnvironmentBackgroundOptions = {
-    projection: "equirect",
-    texture: new TextureBinding({
-      name: options.bindingName ?? "u_environmentBackgroundTexture",
-      texture,
-      required: true,
-      expectedColorSpace: colorSpace
-    }),
-    encoding,
-    intensity: options.intensity,
-    rotation: options.rotation,
-    outputColorSpace: options.outputColorSpace
-  };
-  return validateEnvironmentBackgroundResourceOptions(background);
-}
-
-export function createCubemapEnvironmentBackgroundOptions(
-  options: CubemapEnvironmentBackgroundResourceOptions
-): EnvironmentBackgroundOptions {
-  const format = options.format ?? "rgba8";
-  const encoding = options.encoding ?? "linear";
-  const colorSpace = options.colorSpace ?? textureColorSpaceForEncoding(encoding);
-  validateCubemapPixelSource(options.size, options.faces, format);
-  validateEncodingFormat(encoding, format);
-
-  const texture = new Texture({
-    width: options.size,
-    height: options.size,
-    dimension: "cube",
-    format,
-    colorSpace,
-    label: options.textureLabel ?? "environment-background-cubemap",
-    cubeFaces: ENVIRONMENT_BACKGROUND_CUBE_FACES.map((face) => ({
-      face,
-      mipLevels: [{
-        width: options.size,
-        height: options.size,
-        data: options.faces.find((candidate) => candidate.face === face)!.data
-      }]
-    }))
-  });
-  const background: EnvironmentBackgroundOptions = {
-    projection: "cubemap",
-    texture: new TextureBinding({
-      name: options.bindingName ?? "u_environmentBackgroundCubeTexture",
-      texture,
-      required: true,
-      expectedColorSpace: colorSpace
-    }),
-    encoding,
-    intensity: options.intensity,
-    rotation: options.rotation,
-    outputColorSpace: options.outputColorSpace
-  };
-  return validateEnvironmentBackgroundResourceOptions(background);
-}
-
-export function validateEnvironmentBackgroundResourceOptions(options: EnvironmentBackgroundOptions): EnvironmentBackgroundOptions {
-  const texture = options.texture.texture;
-  if (texture) {
-    if (options.projection === "equirect") {
-      validateEquirectTexture(texture.width, texture.height, texture.dimension, texture.format);
-    } else if (options.projection === "cubemap") {
-      validateCubemapTexture(texture.width, texture.height, texture.dimension, texture.cubeFaces.map((face) => face.face), texture.format);
-    }
-  }
-  createEnvironmentBackgroundUniforms(options);
-  return options;
-}
-
-function validateEquirectPixelSource(
-  width: number,
-  height: number,
-  data: TexturePixelData,
-  format: EnvironmentBackgroundPixelFormat
-): void {
-  validateEquirectTexture(width, height, "2d", format);
-  validatePixelData(width, height, data, format, "Equirect environment background pixels");
-}
-
-function validateCubemapPixelSource(
-  size: number,
-  faces: readonly CubemapEnvironmentBackgroundFacePixels[],
-  format: EnvironmentBackgroundPixelFormat
-): void {
-  validatePositiveInteger(size, "Cubemap environment background size");
-  if (faces.length !== 6) {
-    throw new RenderDeviceError("Cubemap environment background requires exactly six faces", "ENVIRONMENT_BACKGROUND_RESOURCE_CONTRACT", {
-      faceCount: faces.length
-    });
-  }
-  const seen = new Set<TextureCubeFace>();
-  for (const face of faces) {
-    validateCubeFace(face.face);
-    if (seen.has(face.face)) {
-      throw new RenderDeviceError("Duplicate cubemap environment background face", "ENVIRONMENT_BACKGROUND_RESOURCE_CONTRACT", {
-        face: face.face
-      });
-    }
-    seen.add(face.face);
-    validatePixelData(size, size, face.data, format, `Cubemap environment background face ${face.face}`);
-  }
-  for (const face of ENVIRONMENT_BACKGROUND_CUBE_FACES) {
-    if (!seen.has(face)) {
-      throw new RenderDeviceError("Cubemap environment background is missing a required face", "ENVIRONMENT_BACKGROUND_RESOURCE_CONTRACT", {
-        face
-      });
-    }
-  }
-}
-
-function validateEquirectTexture(width: number, height: number, dimension: string, format: TextureFormat): void {
-  validateSupportedBackgroundFormat(format);
-  validatePositiveInteger(width, "Equirect environment background width");
-  validatePositiveInteger(height, "Equirect environment background height");
-  if (dimension !== "2d") {
-    throw new RenderDeviceError("Equirect environment background requires a 2D texture", "ENVIRONMENT_BACKGROUND_RESOURCE_CONTRACT", {
-      textureDimension: dimension
-    });
-  }
-  if (width !== height * 2) {
-    throw new RenderDeviceError("Equirect environment background pixels must use a 2:1 width-to-height ratio", "ENVIRONMENT_BACKGROUND_RESOURCE_CONTRACT", {
-      width,
-      height
-    });
-  }
-}
-
-function validateCubemapTexture(
-  width: number,
-  height: number,
-  dimension: string,
-  faces: readonly TextureCubeFace[],
-  format: TextureFormat
-): void {
-  validateSupportedBackgroundFormat(format);
-  validatePositiveInteger(width, "Cubemap environment background width");
-  validatePositiveInteger(height, "Cubemap environment background height");
-  if (dimension !== "cube") {
-    throw new RenderDeviceError("Cubemap environment background requires a cube texture", "ENVIRONMENT_BACKGROUND_RESOURCE_CONTRACT", {
-      textureDimension: dimension
-    });
-  }
-  if (width !== height) {
-    throw new RenderDeviceError("Cubemap environment background faces must be square", "ENVIRONMENT_BACKGROUND_RESOURCE_CONTRACT", {
-      width,
-      height
-    });
-  }
-  if (faces.length !== 6) {
-    throw new RenderDeviceError("Cubemap environment background requires exactly six faces", "ENVIRONMENT_BACKGROUND_RESOURCE_CONTRACT", {
-      faceCount: faces.length
-    });
-  }
-  const seen = new Set<TextureCubeFace>();
-  for (const face of faces) {
-    validateCubeFace(face);
-    if (seen.has(face)) {
-      throw new RenderDeviceError("Duplicate cubemap environment background face", "ENVIRONMENT_BACKGROUND_RESOURCE_CONTRACT", {
-        face
-      });
-    }
-    seen.add(face);
-  }
-  for (const face of ENVIRONMENT_BACKGROUND_CUBE_FACES) {
-    if (!seen.has(face)) {
-      throw new RenderDeviceError("Cubemap environment background is missing a required face", "ENVIRONMENT_BACKGROUND_RESOURCE_CONTRACT", {
-        face
-      });
-    }
-  }
-}
-
-function validatePixelData(
-  width: number,
-  height: number,
-  data: TexturePixelData,
-  format: EnvironmentBackgroundPixelFormat,
-  label: string
-): void {
-  validateSupportedBackgroundFormat(format);
-  const expectedBytes = width * height * bytesPerPixel(format);
-  if (data.byteLength !== expectedBytes) {
-    throw new RenderDeviceError(`${label} for ${format} must contain exactly ${expectedBytes} bytes`, "ENVIRONMENT_BACKGROUND_RESOURCE_CONTRACT", {
-      width,
-      height,
-      format,
-      byteLength: data.byteLength,
-      expectedBytes
-    });
-  }
-  if (format === "rgba8" && !(data instanceof Uint8Array) && !(data instanceof Uint8ClampedArray)) {
-    throw new RenderDeviceError(`${label} for rgba8 must be Uint8Array or Uint8ClampedArray`, "ENVIRONMENT_BACKGROUND_RESOURCE_CONTRACT", {
-      format
-    });
-  }
-  if (format === "rgba16f" && !(data instanceof Uint16Array)) {
-    throw new RenderDeviceError(`${label} for rgba16f must be Uint16Array half-float data`, "ENVIRONMENT_BACKGROUND_RESOURCE_CONTRACT", {
-      format
-    });
-  }
-  if (format === "rgba32f") {
-    if (!(data instanceof Float32Array)) {
-      throw new RenderDeviceError(`${label} for rgba32f must be Float32Array data`, "ENVIRONMENT_BACKGROUND_RESOURCE_CONTRACT", {
-        format
-      });
-    }
-    if (!Array.from(data).every(Number.isFinite)) {
-      throw new RenderDeviceError(`${label} for rgba32f must contain finite values`, "ENVIRONMENT_BACKGROUND_RESOURCE_CONTRACT", {
-        format
-      });
-    }
-  }
-}
-
-function validateCubeFace(face: TextureCubeFace): void {
-  if (!ENVIRONMENT_BACKGROUND_CUBE_FACES.includes(face)) {
-    throw new RenderDeviceError("Unsupported cubemap environment background face", "ENVIRONMENT_BACKGROUND_RESOURCE_CONTRACT", {
-      face
-    });
-  }
-}
-
-function validateEncodingFormat(encoding: EnvironmentBackgroundEncoding, format: EnvironmentBackgroundPixelFormat): void {
-  if ((encoding === "srgb" || encoding === "rgbe") && format !== "rgba8") {
-    throw new RenderDeviceError("sRGB and RGBe environment background encodings require rgba8 pixel data", "ENVIRONMENT_BACKGROUND_RESOURCE_CONTRACT", {
-      encoding,
-      format
-    });
-  }
-}
-
-function validateSupportedBackgroundFormat(format: TextureFormat): asserts format is EnvironmentBackgroundPixelFormat {
-  if (format !== "rgba8" && format !== "rgba16f" && format !== "rgba32f") {
-    throw new RenderDeviceError("Environment background pixel format must be rgba8, rgba16f, or rgba32f", "ENVIRONMENT_BACKGROUND_RESOURCE_CONTRACT", {
-      format
-    });
-  }
-}
-
-function validatePositiveInteger(value: number, label: string): void {
-  if (!Number.isInteger(value) || value <= 0) {
-    throw new RenderDeviceError(`${label} must be a positive integer`, "ENVIRONMENT_BACKGROUND_RESOURCE_CONTRACT", {
-      value
-    });
-  }
-}
-
-function textureColorSpaceForEncoding(encoding: EnvironmentBackgroundEncoding): TextureColorSpace {
-  return encoding === "srgb" ? "srgb" : "linear";
-}

package/src/EnvironmentLighting.ts

@@ -1,96 +0,0 @@
-import type { EnvironmentLightingOptions, ProceduralEnvironmentMapLightingOptions } from "./ForwardPass";
-
-export interface EnvironmentLightingCompositionOptions {
-  readonly environmentMapIntensity?: number;
-  readonly environmentMapSpecularIntensity?: number;
-  readonly minimumEnvironmentMapIntensity?: number;
-  readonly minimumEnvironmentMapSpecularIntensity?: number;
-  readonly sampledReplacesProceduralMap?: boolean;
-}
-
-export function composeEnvironmentLighting(
-  base: EnvironmentLightingOptions,
-  sampled: EnvironmentLightingOptions,
-  options: EnvironmentLightingCompositionOptions = {}
-): EnvironmentLightingOptions {
-  const environmentMapIntensity = resolveLightingScalar(
-    options.environmentMapIntensity,
-    options.minimumEnvironmentMapIntensity,
-    base.environmentMapIntensity,
-    sampled.environmentMapIntensity
-  );
-  const environmentMapSpecularIntensity = resolveLightingScalar(
-    options.environmentMapSpecularIntensity,
-    options.minimumEnvironmentMapSpecularIntensity,
-    base.environmentMapSpecularIntensity,
-    sampled.environmentMapSpecularIntensity
-  );
-  const environmentMapRotation = sampled.environmentMapRotation ?? base.environmentMapRotation;
-  const environmentMapMipCount = sampled.environmentMapMipCount ?? base.environmentMapMipCount;
-  const environmentMapEncoding = sampled.environmentMapEncoding ?? base.environmentMapEncoding;
-  const proceduralMap = options.sampledReplacesProceduralMap
-    ? sampled.proceduralMap
-    : base.proceduralMap ?? sampled.proceduralMap;
-
-  return {
-    color: cloneColor(base.color),
-    intensity: base.intensity,
-    ...(proceduralMap ? { proceduralMap: cloneProceduralMap(proceduralMap) } : {}),
-    ...(sampled.environmentMapTexture ?? base.environmentMapTexture
-      ? { environmentMapTexture: sampled.environmentMapTexture ?? base.environmentMapTexture }
-      : {}),
-    ...(sampled.environmentCubeMapTexture ?? base.environmentCubeMapTexture
-      ? { environmentCubeMapTexture: sampled.environmentCubeMapTexture ?? base.environmentCubeMapTexture }
-      : {}),
-    ...(environmentMapIntensity !== undefined ? { environmentMapIntensity } : {}),
-    ...(environmentMapSpecularIntensity !== undefined ? { environmentMapSpecularIntensity } : {}),
-    ...(environmentMapRotation !== undefined ? { environmentMapRotation } : {}),
-    ...(environmentMapMipCount !== undefined ? { environmentMapMipCount } : {}),
-    ...(environmentMapEncoding ? { environmentMapEncoding } : {}),
-    ...(sampled.environmentBrdfLutTexture ?? base.environmentBrdfLutTexture
-      ? { environmentBrdfLutTexture: sampled.environmentBrdfLutTexture ?? base.environmentBrdfLutTexture }
-      : {})
-  };
-}
-
-function resolveLightingScalar(
-  explicit: number | undefined,
-  minimum: number | undefined,
-  base: number | undefined,
-  sampled: number | undefined
-): number | undefined {
-  const value = explicit ?? maxFinite(base, sampled);
-  if (value === undefined) return finiteOrUndefined(minimum);
-  const finiteMinimum = finiteOrUndefined(minimum);
-  return finiteMinimum === undefined ? value : Math.max(value, finiteMinimum);
-}
-
-function maxFinite(a: number | undefined, b: number | undefined): number | undefined {
-  const finiteA = finiteOrUndefined(a);
-  const finiteB = finiteOrUndefined(b);
-  if (finiteA === undefined) return finiteB;
-  if (finiteB === undefined) return finiteA;
-  return Math.max(finiteA, finiteB);
-}
-
-function finiteOrUndefined(value: number | undefined): number | undefined {
-  return value === undefined || !Number.isFinite(value) ? undefined : value;
-}
-
-function cloneColor(color: readonly [number, number, number]): [number, number, number] {
-  return [color[0], color[1], color[2]];
-}
-
-function cloneProceduralMap(
-  map: ProceduralEnvironmentMapLightingOptions | undefined
-): ProceduralEnvironmentMapLightingOptions | undefined {
-  if (!map) return undefined;
-  return {
-    skyColor: cloneColor(map.skyColor),
-    horizonColor: cloneColor(map.horizonColor),
-    groundColor: cloneColor(map.groundColor),
-    specularColor: cloneColor(map.specularColor),
-    intensity: map.intensity,
-    specularIntensity: map.specularIntensity
-  };
-}