@aura3d/rendering 1.0.6

package/src/TerrainFixtures.ts

@@ -0,0 +1,180 @@
+export type TerrainFixtureBiome = "water" | "beach" | "grassland" | "forest" | "rock" | "snow";
+
+export interface TerrainHeightfieldFixtureOptions {
+  readonly width?: number;
+  readonly height?: number;
+  readonly seed?: number;
+  readonly minHeight?: number;
+  readonly maxHeight?: number;
+}
+
+export interface TerrainHeightfieldSample {
+  readonly x: number;
+  readonly y: number;
+  readonly height: number;
+  readonly moisture: number;
+  readonly temperature: number;
+  readonly biome: TerrainFixtureBiome;
+}
+
+export interface TerrainHeightfieldFixture {
+  readonly id: "external-parity-old-branch-terrain-heightfield";
+  readonly width: number;
+  readonly height: number;
+  readonly seed: number;
+  readonly minHeight: number;
+  readonly maxHeight: number;
+  readonly data: Float32Array;
+  readonly samples: readonly TerrainHeightfieldSample[];
+  readonly biomeCounts: Readonly<Record<TerrainFixtureBiome, number>>;
+  readonly meanHeight: number;
+  readonly roughness: number;
+  readonly riverCellCount: number;
+  readonly hash: string;
+  readonly source: "origin-master-terrain-generator-adapted";
+  readonly claimBoundary: string;
+}
+
+const terrainBiomes: readonly TerrainFixtureBiome[] = ["water", "beach", "grassland", "forest", "rock", "snow"] as const;
+
+export function createTerrainHeightfieldFixture(options: TerrainHeightfieldFixtureOptions = {}): TerrainHeightfieldFixture {
+  const width = options.width ?? 32;
+  const height = options.height ?? 32;
+  if (!Number.isInteger(width) || width < 8 || !Number.isInteger(height) || height < 8) {
+    throw new RangeError("Terrain heightfield fixture dimensions must be integer values >= 8.");
+  }
+  const seed = options.seed ?? 0x7434_2025;
+  if (!Number.isInteger(seed)) {
+    throw new RangeError("Terrain heightfield fixture seed must be an integer.");
+  }
+  const minHeight = finite(options.minHeight ?? -0.12, "minHeight");
+  const maxHeight = finite(options.maxHeight ?? 0.42, "maxHeight");
+  if (maxHeight <= minHeight) {
+    throw new RangeError("Terrain heightfield fixture maxHeight must be greater than minHeight.");
+  }
+  const data = new Float32Array(width * height);
+  const biomeCounts = Object.fromEntries(terrainBiomes.map((biome) => [biome, 0])) as Record<TerrainFixtureBiome, number>;
+  let sum = 0;
+  let roughness = 0;
+  let riverCellCount = 0;
+  const samples: TerrainHeightfieldSample[] = [];
+  for (let y = 0; y < height; y += 1) {
+    for (let x = 0; x < width; x += 1) {
+      const u = x / Math.max(1, width - 1);
+      const v = y / Math.max(1, height - 1);
+      const base = fractalNoise(u * 3.3, v * 3.3, seed, 5);
+      const detail = fractalNoise(u * 13.7 + 4.1, v * 13.7 - 2.4, seed ^ 0x4f53, 3);
+      const river = Math.max(0, 1 - Math.abs(v - (0.48 + Math.sin(u * Math.PI * 2.2) * 0.08)) * 32);
+      const normalized = clamp(base * 0.82 + detail * 0.18 - river * 0.22, 0, 1);
+      const value = minHeight + normalized * (maxHeight - minHeight);
+      data[y * width + x] = value;
+      sum += value;
+      if (river > 0.35) riverCellCount += 1;
+      const moisture = clamp(fractalNoise(u * 2.4 + 7.2, v * 2.4 - 1.8, seed ^ 0x9ab1, 4) + river * 0.28, 0, 1);
+      const temperature = clamp((1 - v) * 0.78 + fractalNoise(u * 1.8 - 3.2, v * 1.8 + 5.8, seed ^ 0x1c0d, 3) * 0.22 - normalized * 0.38, 0, 1);
+      const biome = biomeFor(normalized, moisture, temperature, river);
+      biomeCounts[biome] += 1;
+      if (x % Math.max(1, Math.floor(width / 4)) === 0 && y % Math.max(1, Math.floor(height / 4)) === 0) {
+        samples.push({ x, y, height: Number(value.toFixed(4)), moisture: Number(moisture.toFixed(4)), temperature: Number(temperature.toFixed(4)), biome });
+      }
+      if (x > 0) roughness += Math.abs(value - (data[y * width + x - 1] ?? value));
+      if (y > 0) roughness += Math.abs(value - (data[(y - 1) * width + x] ?? value));
+    }
+  }
+  return {
+    id: "external-parity-old-branch-terrain-heightfield",
+    width,
+    height,
+    seed,
+    minHeight,
+    maxHeight,
+    data,
+    samples,
+    biomeCounts,
+    meanHeight: Number((sum / data.length).toFixed(5)),
+    roughness: Number((roughness / Math.max(1, data.length * 2 - width - height)).toFixed(5)),
+    riverCellCount,
+    hash: hashFloat32(data),
+    source: "origin-master-terrain-generator-adapted",
+    claimBoundary: "Deterministic heightfield, biome, roughness, and river-cell telemetry adapted from the old terrain generator concepts; this is a bounded local fixture, not full terrain ECS, erosion, collision, vegetation, or streaming terrain parity."
+  };
+}
+
+export function sampleTerrainHeightfield(fixture: TerrainHeightfieldFixture, u: number, v: number): TerrainHeightfieldSample {
+  const x = Math.max(0, Math.min(fixture.width - 1, Math.round(clamp(u, 0, 1) * (fixture.width - 1))));
+  const y = Math.max(0, Math.min(fixture.height - 1, Math.round(clamp(v, 0, 1) * (fixture.height - 1))));
+  const height = fixture.data[y * fixture.width + x] ?? 0;
+  const normalized = (height - fixture.minHeight) / Math.max(0.0001, fixture.maxHeight - fixture.minHeight);
+  const moisture = clamp(fractalNoise((x / fixture.width) * 2.4 + 7.2, (y / fixture.height) * 2.4 - 1.8, fixture.seed ^ 0x9ab1, 4), 0, 1);
+  const temperature = clamp((1 - y / fixture.height) * 0.78 + fractalNoise((x / fixture.width) * 1.8 - 3.2, (y / fixture.height) * 1.8 + 5.8, fixture.seed ^ 0x1c0d, 3) * 0.22 - normalized * 0.38, 0, 1);
+  return { x, y, height: Number(height.toFixed(4)), moisture: Number(moisture.toFixed(4)), temperature: Number(temperature.toFixed(4)), biome: biomeFor(normalized, moisture, temperature, 0) };
+}
+
+function biomeFor(height: number, moisture: number, temperature: number, river: number): TerrainFixtureBiome {
+  if (height < 0.18 || river > 0.62) return "water";
+  if (height < 0.24) return "beach";
+  if (height > 0.78 && temperature < 0.34) return "snow";
+  if (height > 0.68) return "rock";
+  if (moisture > 0.58) return "forest";
+  return "grassland";
+}
+
+function fractalNoise(x: number, y: number, seed: number, octaves: number): number {
+  let value = 0;
+  let amplitude = 0.5;
+  let frequency = 1;
+  let total = 0;
+  for (let octave = 0; octave < octaves; octave += 1) {
+    value += smoothNoise(x * frequency, y * frequency, seed + octave * 1013) * amplitude;
+    total += amplitude;
+    amplitude *= 0.5;
+    frequency *= 2;
+  }
+  return total === 0 ? 0 : value / total;
+}
+
+function smoothNoise(x: number, y: number, seed: number): number {
+  const x0 = Math.floor(x);
+  const y0 = Math.floor(y);
+  const tx = x - x0;
+  const ty = y - y0;
+  const a = valueNoise(x0, y0, seed);
+  const b = valueNoise(x0 + 1, y0, seed);
+  const c = valueNoise(x0, y0 + 1, seed);
+  const d = valueNoise(x0 + 1, y0 + 1, seed);
+  const sx = tx * tx * (3 - 2 * tx);
+  const sy = ty * ty * (3 - 2 * ty);
+  return lerp(lerp(a, b, sx), lerp(c, d, sx), sy);
+}
+
+function valueNoise(x: number, y: number, seed: number): number {
+  let value = Math.imul(x, 374761393) ^ Math.imul(y, 668265263) ^ seed;
+  value = Math.imul(value ^ (value >>> 13), 1274126177);
+  return ((value ^ (value >>> 16)) >>> 0) / 0xffffffff;
+}
+
+function hashFloat32(values: Float32Array): string {
+  let hash = 0x811c9dc5;
+  const view = new DataView(new ArrayBuffer(4));
+  for (const value of values) {
+    view.setFloat32(0, value, true);
+    for (let index = 0; index < 4; index += 1) {
+      hash ^= view.getUint8(index);
+      hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+  }
+  return hash.toString(16).padStart(8, "0");
+}
+
+function finite(value: number, label: string): number {
+  if (!Number.isFinite(value)) throw new RangeError(`Terrain heightfield fixture ${label} must be finite.`);
+  return value;
+}
+
+function lerp(left: number, right: number, amount: number): number {
+  return left + (right - left) * amount;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}

package/src/Texture.ts

@@ -0,0 +1,307 @@
+export type TextureCompressedFormat = "bc1-rgba-unorm" | "bc3-rgba-unorm" | "etc2-rgba8unorm" | "astc-4x4-rgba-unorm";
+export type TextureFormat = "rgba8" | "rgba16f" | "rgba32f" | "depth24" | TextureCompressedFormat;
+export type TextureColorSpace = "linear" | "srgb";
+export type TexturePixelData = Uint8Array | Uint8ClampedArray | Uint16Array | Float32Array;
+export type TextureDimension = "2d" | "cube";
+export type TextureCubeFace = "px" | "nx" | "py" | "ny" | "pz" | "nz";
+
+export interface TextureMipLevelDescriptor {
+  readonly width: number;
+  readonly height: number;
+  readonly data: TexturePixelData;
+}
+
+export interface TextureMipLevel {
+  readonly width: number;
+  readonly height: number;
+  readonly data: TexturePixelData;
+}
+
+export interface TextureCubeFaceDescriptor {
+  readonly face: TextureCubeFace;
+  readonly mipLevels: readonly TextureMipLevelDescriptor[];
+}
+
+export interface TextureCubeFaceLevel {
+  readonly face: TextureCubeFace;
+  readonly mipLevels: readonly TextureMipLevel[];
+}
+
+export interface TextureDescriptor {
+  readonly width: number;
+  readonly height: number;
+  readonly dimension?: TextureDimension;
+  readonly format?: TextureFormat;
+  readonly colorSpace?: TextureColorSpace;
+  readonly label?: string;
+  readonly data?: TexturePixelData;
+  readonly mipLevels?: readonly TextureMipLevelDescriptor[];
+  readonly cubeFaces?: readonly TextureCubeFaceDescriptor[];
+  readonly source?: TexImageSource;
+  readonly fallbackData?: Uint8Array | Uint8ClampedArray;
+  readonly fallbackMipLevels?: readonly TextureMipLevelDescriptor[];
+}
+
+export class Texture {
+  public readonly width: number;
+  public readonly height: number;
+  public readonly dimension: TextureDimension;
+  public readonly format: TextureFormat;
+  public readonly colorSpace: TextureColorSpace;
+  public readonly label: string;
+  public readonly data: TexturePixelData | null;
+  public readonly mipLevels: readonly TextureMipLevel[];
+  public readonly cubeFaces: readonly TextureCubeFaceLevel[];
+  public readonly source: TexImageSource | null;
+  public readonly fallbackData: Uint8Array | null;
+  public readonly fallbackMipLevels: readonly TextureMipLevel[];
+  public disposed = false;
+
+  constructor(descriptor: TextureDescriptor) {
+    if (!Number.isInteger(descriptor.width) || descriptor.width <= 0) {
+      throw new Error("Texture width must be a positive integer");
+    }
+    if (!Number.isInteger(descriptor.height) || descriptor.height <= 0) {
+      throw new Error("Texture height must be a positive integer");
+    }
+    this.width = descriptor.width;
+    this.height = descriptor.height;
+    this.dimension = descriptor.dimension ?? (descriptor.cubeFaces ? "cube" : "2d");
+    this.format = descriptor.format ?? "rgba8";
+    this.colorSpace = descriptor.colorSpace ?? "linear";
+    this.label = descriptor.label ?? "texture";
+    if (this.dimension === "cube" && descriptor.width !== descriptor.height) {
+      throw new Error("Cube textures require square width and height");
+    }
+    if (descriptor.data && descriptor.source) {
+      throw new Error("Texture cannot define both raw pixel data and image source");
+    }
+    if (descriptor.mipLevels && descriptor.source) {
+      throw new Error("Texture cannot define both mipLevels and image source");
+    }
+    if (descriptor.data && descriptor.mipLevels) {
+      throw new Error("Texture cannot define both data and mipLevels");
+    }
+    this.data = descriptor.data ? clonePixelData(descriptor.data) : null;
+    this.mipLevels = descriptor.mipLevels ? cloneMipLevels(descriptor.mipLevels, "mipLevels") : [];
+    this.cubeFaces = descriptor.cubeFaces ? cloneCubeFaces(descriptor.cubeFaces) : [];
+    this.source = descriptor.source ?? null;
+    this.fallbackData = descriptor.fallbackData ? new Uint8Array(descriptor.fallbackData) : null;
+    this.fallbackMipLevels = descriptor.fallbackMipLevels ? cloneMipLevels(descriptor.fallbackMipLevels, "fallbackMipLevels") : [];
+    if (this.dimension === "cube") {
+      if (this.data || this.mipLevels.length > 0 || this.source || this.fallbackData || this.fallbackMipLevels.length > 0) {
+        throw new Error("Cube textures must define cubeFaces instead of 2D data, mipLevels, source, or fallbacks");
+      }
+      if (isCompressedTextureFormat(this.format) || this.format === "depth24") {
+        throw new Error("Cube textures currently support rgba8, rgba16f, or rgba32f formats");
+      }
+      validateCubeFaces(this.cubeFaces, this.width, this.height, this.format);
+      return;
+    }
+    if (this.cubeFaces.length > 0) {
+      throw new Error("2D textures cannot define cubeFaces");
+    }
+    if (isCompressedTextureFormat(this.format)) {
+      if (!this.data && this.mipLevels.length === 0) {
+        throw new Error("Compressed textures require compressed data bytes");
+      }
+      if (this.source) {
+        throw new Error("Compressed textures cannot use TexImageSource uploads");
+      }
+      const levels = this.textureLevels;
+      for (const [index, level] of levels.entries()) {
+        const expected = compressedTextureByteLength(level.width, level.height, this.format);
+        if (level.data.byteLength !== expected) {
+          throw new Error(`Compressed texture mip level ${index} for ${this.format} must contain ${expected} bytes`);
+        }
+      }
+      if (levels[0]?.width !== this.width || levels[0]?.height !== this.height) {
+        throw new Error("Compressed texture first mip level must match width and height");
+      }
+      if (this.fallbackData && this.fallbackData.byteLength !== this.width * this.height * 4) {
+        throw new Error("Compressed texture fallbackData must contain exactly width * height * 4 RGBA8 bytes");
+      }
+      for (const [index, level] of this.fallbackTextureLevels.entries()) {
+        if (level.data.byteLength !== level.width * level.height * 4) {
+          throw new Error(`Compressed texture fallback mip level ${index} must contain exactly width * height * 4 RGBA8 bytes`);
+        }
+      }
+      if (this.fallbackTextureLevels.length > 0 && (this.fallbackTextureLevels[0]?.width !== this.width || this.fallbackTextureLevels[0]?.height !== this.height)) {
+        throw new Error("Compressed texture first fallback mip level must match width and height");
+      }
+    } else {
+      if (this.source && this.format !== "rgba8") {
+        throw new Error("TexImageSource uploads are only supported for rgba8 textures");
+      }
+      if (this.format === "depth24" && (this.data || this.mipLevels.length > 0 || this.source)) {
+        throw new Error("Depth textures cannot define color data, mipLevels, or image sources");
+      }
+      if (this.mipLevels.length > 0) {
+        validateTextureMipLevels(this.mipLevels, this.width, this.height, this.format, "mipLevels");
+      }
+      if (this.data) {
+        validateTexturePixelData(this.data, this.width, this.height, this.format, "texture data");
+      }
+      if (this.fallbackData) {
+        throw new Error("fallbackData is only valid for compressed textures");
+      }
+      if (this.fallbackMipLevels.length > 0) {
+        throw new Error("fallbackMipLevels are only valid for compressed textures");
+      }
+    }
+  }
+
+  dispose(): void {
+    this.disposed = true;
+  }
+
+  get byteLength(): number {
+    if (isCompressedTextureFormat(this.format)) {
+      const format = this.format;
+      return this.textureLevels.reduce((total, level) => total + compressedTextureByteLength(level.width, level.height, format), 0);
+    }
+    if (this.dimension === "cube") {
+      return this.cubeFaces.reduce((total, face) => total + face.mipLevels.reduce((faceTotal, level) => faceTotal + level.data.byteLength, 0), 0);
+    }
+    if (this.mipLevels.length > 0) {
+      return this.mipLevels.reduce((total, level) => total + level.data.byteLength, 0);
+    }
+    return this.width * this.height * bytesPerPixel(this.format);
+  }
+
+  get fallbackByteLength(): number {
+    return this.fallbackTextureLevels.reduce((total, level) => total + level.data.byteLength, 0);
+  }
+
+  get textureLevels(): readonly TextureMipLevel[] {
+    if (this.mipLevels.length > 0) return this.mipLevels;
+    return this.data ? [{ width: this.width, height: this.height, data: this.data }] : [];
+  }
+
+  get fallbackTextureLevels(): readonly TextureMipLevel[] {
+    if (this.fallbackMipLevels.length > 0) return this.fallbackMipLevels;
+    return this.fallbackData ? [{ width: this.width, height: this.height, data: this.fallbackData }] : [];
+  }
+}
+
+export function bytesPerPixel(format: TextureFormat): number {
+  switch (format) {
+    case "rgba8":
+      return 4;
+    case "rgba16f":
+      return 8;
+    case "rgba32f":
+      return 16;
+    case "depth24":
+      return 4;
+    case "bc1-rgba-unorm":
+    case "bc3-rgba-unorm":
+    case "etc2-rgba8unorm":
+    case "astc-4x4-rgba-unorm":
+      return 0;
+  }
+}
+
+export function isCompressedTextureFormat(format: TextureFormat): format is TextureCompressedFormat {
+  return format === "bc1-rgba-unorm" || format === "bc3-rgba-unorm" || format === "etc2-rgba8unorm" || format === "astc-4x4-rgba-unorm";
+}
+
+export function compressedTextureByteLength(width: number, height: number, format: TextureCompressedFormat): number {
+  const blocksWide = Math.max(1, Math.ceil(width / 4));
+  const blocksHigh = Math.max(1, Math.ceil(height / 4));
+  return blocksWide * blocksHigh * compressedBlockByteLength(format);
+}
+
+export function compressedBlockByteLength(format: TextureCompressedFormat): number {
+  switch (format) {
+    case "bc1-rgba-unorm":
+      return 8;
+    case "bc3-rgba-unorm":
+    case "etc2-rgba8unorm":
+    case "astc-4x4-rgba-unorm":
+      return 16;
+  }
+}
+
+function cloneMipLevels(levels: readonly TextureMipLevelDescriptor[], label: string): TextureMipLevel[] {
+  if (levels.length === 0) {
+    throw new Error(`${label} must contain at least one level`);
+  }
+  return levels.map((level, index) => {
+    if (!Number.isInteger(level.width) || level.width <= 0) {
+      throw new Error(`${label} level ${index} width must be a positive integer`);
+    }
+    if (!Number.isInteger(level.height) || level.height <= 0) {
+      throw new Error(`${label} level ${index} height must be a positive integer`);
+    }
+    return { width: level.width, height: level.height, data: clonePixelData(level.data) };
+  });
+}
+
+function cloneCubeFaces(faces: readonly TextureCubeFaceDescriptor[]): TextureCubeFaceLevel[] {
+  if (faces.length !== 6) {
+    throw new Error("Cube textures require exactly six faces");
+  }
+  return faces.map((face) => ({
+    face: face.face,
+    mipLevels: cloneMipLevels(face.mipLevels, `cubeFaces.${face.face}.mipLevels`)
+  }));
+}
+
+function clonePixelData(data: TexturePixelData): TexturePixelData {
+  if (data instanceof Uint8ClampedArray) return new Uint8ClampedArray(data);
+  if (data instanceof Uint16Array) return new Uint16Array(data);
+  if (data instanceof Float32Array) return new Float32Array(data);
+  return new Uint8Array(data);
+}
+
+function validateCubeFaces(faces: readonly TextureCubeFaceLevel[], width: number, height: number, format: TextureFormat): void {
+  const expectedFaces: readonly TextureCubeFace[] = ["px", "nx", "py", "ny", "pz", "nz"];
+  const seen = new Set<TextureCubeFace>();
+  for (const face of faces) {
+    if (!expectedFaces.includes(face.face)) {
+      throw new Error(`Unsupported cube texture face: ${face.face}`);
+    }
+    if (seen.has(face.face)) {
+      throw new Error(`Duplicate cube texture face: ${face.face}`);
+    }
+    seen.add(face.face);
+    validateTextureMipLevels(face.mipLevels, width, height, format, `cubeFaces.${face.face}.mipLevels`);
+  }
+  for (const face of expectedFaces) {
+    if (!seen.has(face)) {
+      throw new Error(`Missing cube texture face: ${face}`);
+    }
+  }
+}
+
+function validateTextureMipLevels(levels: readonly TextureMipLevel[], width: number, height: number, format: TextureFormat, label: string): void {
+  if (levels[0]?.width !== width || levels[0]?.height !== height) {
+    throw new Error(`${label} first level must match width and height`);
+  }
+  for (const [index, level] of levels.entries()) {
+    validateTexturePixelData(level.data, level.width, level.height, format, `${label} level ${index}`);
+  }
+}
+
+function validateTexturePixelData(data: TexturePixelData, width: number, height: number, format: TextureFormat, label: string): void {
+  if (format === "rgba8") {
+    if (!(data instanceof Uint8Array) && !(data instanceof Uint8ClampedArray)) {
+      throw new Error(`${label} for rgba8 textures must be Uint8Array or Uint8ClampedArray`);
+    }
+  } else if (format === "rgba16f") {
+    if (!(data instanceof Uint16Array)) {
+      throw new Error(`${label} for rgba16f textures must be Uint16Array half-float data`);
+    }
+  } else if (format === "rgba32f") {
+    if (!(data instanceof Float32Array)) {
+      throw new Error(`${label} for rgba32f textures must be Float32Array data`);
+    }
+  } else if (format === "depth24") {
+    throw new Error(`${label} is not valid for depth24 textures`);
+  }
+  const expected = width * height * bytesPerPixel(format);
+  if (data.byteLength !== expected) {
+    throw new Error(`${label} for ${format} textures must contain exactly ${expected} bytes`);
+  }
+}

package/src/TextureBinding.ts

@@ -0,0 +1,91 @@
+import { Sampler } from "./Sampler";
+import { Texture, type TextureColorSpace, type TextureDimension } from "./Texture";
+
+export interface TextureBindingDescriptor {
+  readonly name: string;
+  readonly texture?: Texture | null;
+  readonly sampler?: Sampler;
+  readonly required?: boolean;
+  readonly ready?: boolean;
+  readonly expectedColorSpace?: TextureColorSpace;
+  readonly expectedDimension?: TextureDimension;
+  readonly transform?: TextureTransformDescriptor;
+}
+
+export interface TextureTransformDescriptor {
+  readonly offset?: readonly [number, number];
+  readonly scale?: readonly [number, number];
+  readonly rotation?: number;
+}
+
+export interface TextureBindingValidation {
+  readonly ok: boolean;
+  readonly diagnostics: readonly string[];
+  readonly warnings: readonly string[];
+}
+
+export class TextureBinding {
+  public readonly name: string;
+  public readonly texture: Texture | null;
+  public readonly sampler: Sampler;
+  public readonly required: boolean;
+  public readonly ready: boolean;
+  public readonly expectedColorSpace?: TextureColorSpace;
+  public readonly expectedDimension?: TextureDimension;
+  public readonly offset: readonly [number, number];
+  public readonly scale: readonly [number, number];
+  public readonly rotation: number;
+
+  constructor(descriptor: TextureBindingDescriptor) {
+    if (!descriptor.name.trim()) {
+      throw new Error("Texture binding name is required");
+    }
+    this.name = descriptor.name;
+    this.texture = descriptor.texture ?? null;
+    this.sampler = descriptor.sampler ?? new Sampler();
+    this.required = descriptor.required ?? false;
+    this.ready = descriptor.ready ?? true;
+    this.expectedColorSpace = descriptor.expectedColorSpace;
+    this.expectedDimension = descriptor.expectedDimension;
+    this.offset = descriptor.transform?.offset ? [descriptor.transform.offset[0], descriptor.transform.offset[1]] : [0, 0];
+    this.scale = descriptor.transform?.scale ? [descriptor.transform.scale[0], descriptor.transform.scale[1]] : [1, 1];
+    this.rotation = descriptor.transform?.rotation ?? 0;
+  }
+
+  validate(): TextureBindingValidation {
+    const diagnostics: string[] = [];
+    const warnings: string[] = [];
+    if (this.required && !this.texture) {
+      diagnostics.push(`Missing required texture: ${this.name}`);
+    } else if (!this.required && !this.texture) {
+      warnings.push(`Optional texture is not bound; using fallback texture: ${this.name}`);
+    }
+    if (this.texture?.disposed) {
+      diagnostics.push(`Texture is disposed: ${this.name}`);
+    }
+    if (this.texture && !this.ready) {
+      diagnostics.push(`Texture is not ready: ${this.name}`);
+    }
+    if (this.texture && this.expectedColorSpace && this.texture.colorSpace !== this.expectedColorSpace) {
+      diagnostics.push(`Texture ${this.name} colorSpace must be ${this.expectedColorSpace}, got ${this.texture.colorSpace}`);
+    }
+    if (this.texture && this.expectedDimension && this.texture.dimension !== this.expectedDimension) {
+      diagnostics.push(`Texture ${this.name} dimension must be ${this.expectedDimension}, got ${this.texture.dimension}`);
+    }
+    if (![...this.offset, ...this.scale, this.rotation].every(Number.isFinite)) {
+      diagnostics.push(`Texture transform must contain finite values: ${this.name}`);
+    }
+    return { ok: diagnostics.length === 0, diagnostics, warnings };
+  }
+
+  transformUV(uv: readonly [number, number]): readonly [number, number] {
+    const scaledX = uv[0] * this.scale[0];
+    const scaledY = uv[1] * this.scale[1];
+    const cos = Math.cos(this.rotation);
+    const sin = Math.sin(this.rotation);
+    return [
+      scaledX * cos - scaledY * sin + this.offset[0],
+      scaledX * sin + scaledY * cos + this.offset[1]
+    ];
+  }
+}