@haiyue/extensions 0.1.0

package/src/gltf/GltfLoaderErrors.ts

@@ -0,0 +1,59 @@
+import { EngineError, EngineErrorCode } from '@haiyue/engine';
+import { ErrorDomain, ErrorRecovery } from '@haiyue/engine/core';
+import { createAbortError } from '@haiyue/engine/experimental/async';
+
+export function throwIfGltfLoadAborted(signal: AbortSignal | undefined): void {
+  if (!signal?.aborted) return;
+  throw createAbortError('glTF load aborted.', signal.reason);
+}
+
+export function attachGltfSource(error: unknown, src: string): Error {
+  if (error instanceof Error && error.name === 'AbortError') return error;
+  if (error instanceof EngineError) {
+    return new EngineError(error.code, error.message, {
+      domain: error.domain,
+      recoverable: error.recoverable,
+      recovery: error.recovery,
+      context: { url: src, resourceType: 'model/gltf', ...error.context },
+      ...(error.path === undefined ? {} : { path: error.path }),
+      ...(error.hint === undefined ? {} : { hint: error.hint }),
+      ...(error.docsPath === undefined ? {} : { docsPath: error.docsPath }),
+      cause: error,
+    });
+  }
+  return gltfDataError(error instanceof Error ? error.message : String(error), { url: src }, undefined, error);
+}
+
+export function gltfDataError(
+  message: string,
+  context: Record<string, unknown> = {},
+  path?: string,
+  cause?: unknown,
+): EngineError {
+  const accessor = /[Aa]ccessor\s+(\d+)/.exec(message)?.[1];
+  const bufferView = /bufferView\s+(\d+)/i.exec(message)?.[1];
+  const buffer = /buffer\s+(\d+)/i.exec(message)?.[1];
+  const failedLoad = /^Failed to load/.test(message);
+  const resolvedPath = path
+    ?? (accessor === undefined ? undefined : `gltf.accessors[${accessor}]`)
+    ?? (bufferView === undefined ? undefined : `gltf.bufferViews[${bufferView}]`)
+    ?? (buffer === undefined ? undefined : `gltf.buffers[${buffer}]`)
+    ?? 'gltf';
+  return new EngineError(
+    failedLoad ? EngineErrorCode.AssetLoadFailed : EngineErrorCode.AssetInvalidData,
+    message,
+    {
+      domain: ErrorDomain.Component,
+      recovery: failedLoad ? ErrorRecovery.Retry : ErrorRecovery.ReleaseResource,
+      context: {
+        resourceType: 'model/gltf',
+        ...context,
+        ...(accessor === undefined ? {} : { accessor: Number(accessor) }),
+        ...(bufferView === undefined ? {} : { bufferView: Number(bufferView) }),
+        ...(buffer === undefined ? {} : { buffer: Number(buffer) }),
+      },
+      path: resolvedPath,
+      cause,
+    },
+  );
+}

package/src/gltf/GltfMaterialDescriptor.ts

@@ -0,0 +1,134 @@
+import { ColorSRGB } from '@haiyue/engine';
+import { type MaterialDescriptor, type MaterialTextureSource, type PbrMaterialState, type PbrTextureMappingOptions, type PbrTextureMappings, type PbrTextureSamplers, type PbrTextureSlot } from '@haiyue/engine/material';
+import type { GltfAsset, GltfMaterial, GltfPrimitive, GltfTextureInfo } from './GltfSchema';
+import {
+  collectGltfMaterialExtensionPatches,
+  type GltfExtensionAdapter,
+  type GltfMaterialTextureBinding,
+} from './GltfExtensionAdapter';
+
+export interface ResolvedGltfMaterialTexture {
+  readonly source: MaterialTextureSource;
+  readonly mapping: PbrTextureMappingOptions;
+  readonly sampler: GPUSamplerDescriptor | null;
+}
+
+export interface GltfMaterialDescriptorInput {
+  readonly gltf: GltfAsset;
+  readonly material: GltfMaterial | null;
+  readonly primitive: GltfPrimitive;
+  readonly materialPath: string;
+  readonly defaultBaseColor?: readonly [number, number, number, number];
+  readonly adapters: readonly GltfExtensionAdapter[];
+  readonly resolveTexture: (binding: GltfMaterialTextureBinding) => ResolvedGltfMaterialTexture;
+}
+
+const textureStateKeys: Readonly<Record<PbrTextureSlot, keyof PbrMaterialState>> = Object.freeze({
+  baseColor: 'baseColorTexture',
+  metallicRoughness: 'metallicRoughnessTexture',
+  normal: 'normalTexture',
+  occlusion: 'occlusionTexture',
+  emissive: 'emissiveTexture',
+  clearcoat: 'clearcoatTexture',
+  clearcoatRoughness: 'clearcoatRoughnessTexture',
+  clearcoatNormal: 'clearcoatNormalTexture',
+  specular: 'specularTexture',
+  specularColor: 'specularColorTexture',
+  sheenColor: 'sheenColorTexture',
+  sheenRoughness: 'sheenRoughnessTexture',
+  transmission: 'transmissionTexture',
+  thickness: 'thicknessTexture',
+});
+
+/** Compiles glTF core material data and extension patches into one engine descriptor. */
+export function createGltfMaterialDescriptor(
+  input: GltfMaterialDescriptorInput,
+): Extract<MaterialDescriptor, { shadingModel: 'pbr-metallic-roughness' }> {
+  const { material } = input;
+  const pbr = material?.pbrMetallicRoughness;
+  const state: PbrMaterialState = {
+    baseColor: pbr?.baseColorFactor
+      ? linearBaseColorFactorToSrgb(pbr.baseColorFactor)
+      : input.defaultBaseColor ?? [1, 1, 1, 1],
+    metallic: pbr?.metallicFactor ?? 1,
+    roughness: pbr?.roughnessFactor ?? 1,
+    normalScale: material?.normalTexture?.scale ?? 1,
+    occlusionStrength: material?.occlusionTexture?.strength ?? 1,
+    emissiveFactor: material?.emissiveFactor ?? [0, 0, 0],
+    alphaMode: material?.alphaMode === 'BLEND' ? 'blend' : material?.alphaMode === 'MASK' ? 'mask' : 'opaque',
+    alphaCutoff: material?.alphaCutoff ?? 0.5,
+    doubleSided: material?.doubleSided ?? false,
+  };
+  const patches = collectGltfMaterialExtensionPatches(
+    input.gltf,
+    material,
+    input.primitive,
+    input.materialPath,
+    input.adapters,
+  );
+  const textureMappings: Partial<Record<PbrTextureSlot, PbrTextureMappingOptions>> = {};
+  const samplers: Partial<Record<PbrTextureSlot, GPUSamplerDescriptor | null>> = {};
+  for (const patch of patches) {
+    Object.assign(state, patch.state);
+  }
+  for (const binding of collectGltfMaterialTextureBindings(
+    input.gltf,
+    material,
+    input.primitive,
+    input.materialPath,
+    input.adapters,
+  )) {
+    const texture = input.resolveTexture(binding);
+    state[textureStateKeys[binding.slot]] = texture.source as never;
+    textureMappings[binding.slot] = texture.mapping;
+    samplers[binding.slot] = texture.sampler;
+  }
+  if (Object.keys(textureMappings).length > 0) state.textureMappings = textureMappings as PbrTextureMappings;
+  if (Object.keys(samplers).length > 0) state.samplers = samplers as PbrTextureSamplers;
+  return Object.freeze({
+    shadingModel: 'pbr-metallic-roughness',
+    state: Object.freeze(state),
+  });
+}
+
+/** Shared semantic source for preload, UV planning, and descriptor compilation. */
+export function collectGltfMaterialTextureBindings(
+  gltf: GltfAsset,
+  material: GltfMaterial | null,
+  primitive: GltfPrimitive,
+  materialPath: string,
+  adapters: readonly GltfExtensionAdapter[],
+): readonly GltfMaterialTextureBinding[] {
+  if (!material) return Object.freeze([]);
+  const pbr = material.pbrMetallicRoughness;
+  const bindings: GltfMaterialTextureBinding[] = [];
+  addTexture(bindings, 'baseColor', pbr?.baseColorTexture, `${materialPath}.pbrMetallicRoughness.baseColorTexture`);
+  addTexture(bindings, 'metallicRoughness', pbr?.metallicRoughnessTexture, `${materialPath}.pbrMetallicRoughness.metallicRoughnessTexture`);
+  addTexture(bindings, 'normal', material.normalTexture, `${materialPath}.normalTexture`);
+  addTexture(bindings, 'occlusion', material.occlusionTexture, `${materialPath}.occlusionTexture`);
+  addTexture(bindings, 'emissive', material.emissiveTexture, `${materialPath}.emissiveTexture`);
+  for (const patch of collectGltfMaterialExtensionPatches(gltf, material, primitive, materialPath, adapters)) {
+    bindings.push(...patch.textures ?? []);
+  }
+  return Object.freeze(bindings);
+}
+
+function addTexture(
+  bindings: GltfMaterialTextureBinding[],
+  slot: PbrTextureSlot,
+  textureInfo: GltfTextureInfo | undefined,
+  path: string,
+): void {
+  if (textureInfo) bindings.push(Object.freeze({ slot, textureInfo, path }));
+}
+
+function linearBaseColorFactorToSrgb(
+  value: readonly [number, number, number, number],
+): [number, number, number, number] {
+  return [
+    ColorSRGB.linearToSRGB(value[0]),
+    ColorSRGB.linearToSRGB(value[1]),
+    ColorSRGB.linearToSRGB(value[2]),
+    value[3],
+  ];
+}

package/src/gltf/GltfMaterialEncoder.ts

@@ -0,0 +1,173 @@
+import type { MaterialTextureSource, PbrMaterial, PbrTextureSlot } from '@haiyue/engine/material';
+import type { GltfMaterial, GltfTextureInfo, GltfTextureTransform } from './GltfSchema';
+
+export interface EncodeGltfPbrMaterialOptions {
+  readonly name?: string;
+  /**
+   * Resolves an engine texture source to the texture index already allocated
+   * by the surrounding glTF/GLB exporter.
+   */
+  readonly resolveTextureIndex: (slot: PbrTextureSlot, source: MaterialTextureSource) => number;
+}
+
+export interface EncodedGltfPbrMaterial {
+  readonly material: GltfMaterial;
+  readonly extensionsUsed: readonly string[];
+}
+
+/**
+ * Encodes the standard glTF material portion without taking ownership of image,
+ * sampler, or buffer allocation. Scene exporters can share this codec instead
+ * of duplicating KHR material semantics.
+ */
+export function encodeGltfPbrMaterial(
+  material: PbrMaterial,
+  options: EncodeGltfPbrMaterialOptions,
+): EncodedGltfPbrMaterial {
+  const extensionsUsed = new Set<string>();
+  const texture = (slot: PbrTextureSlot, source: MaterialTextureSource): GltfTextureInfo | undefined => {
+    if (!source) return undefined;
+    const index = options.resolveTextureIndex(slot, source);
+    if (!Number.isSafeInteger(index) || index < 0) {
+      throw new RangeError(`glTF texture index for PBR slot "${slot}" must be a non-negative safe integer.`);
+    }
+    return encodeTextureInfo(material, slot, index, extensionsUsed);
+  };
+
+  const baseColor = new Float32Array(4);
+  material.baseColor.writeLinear(baseColor);
+  const baseColorTexture = texture('baseColor', material.baseColorTexture);
+  const metallicRoughnessTexture = texture('metallicRoughness', material.metallicRoughnessTexture);
+  const normalTexture = texture('normal', material.normalTexture);
+  const occlusionTexture = texture('occlusion', material.occlusionTexture);
+  const emissiveTexture = texture('emissive', material.emissiveTexture);
+  const clearcoatTexture = texture('clearcoat', material.clearcoatTexture);
+  const clearcoatRoughnessTexture = texture('clearcoatRoughness', material.clearcoatRoughnessTexture);
+  const clearcoatNormalTexture = texture('clearcoatNormal', material.clearcoatNormalTexture);
+  const specularTexture = texture('specular', material.specularTexture);
+  const specularColorTexture = texture('specularColor', material.specularColorTexture);
+  const sheenColorTexture = texture('sheenColor', material.sheenColorTexture);
+  const sheenRoughnessTexture = texture('sheenRoughness', material.sheenRoughnessTexture);
+  const transmissionTexture = texture('transmission', material.transmissionTexture);
+  const thicknessTexture = texture('thickness', material.thicknessTexture);
+
+  const extensions: NonNullable<GltfMaterial['extensions']> = {};
+  if (
+    material.clearcoatFactor !== 0
+    || material.clearcoatRoughnessFactor !== 0
+    || clearcoatTexture
+    || clearcoatRoughnessTexture
+    || clearcoatNormalTexture
+  ) {
+    extensions.KHR_materials_clearcoat = {
+      clearcoatFactor: material.clearcoatFactor,
+      ...(clearcoatTexture ? { clearcoatTexture } : {}),
+      clearcoatRoughnessFactor: material.clearcoatRoughnessFactor,
+      ...(clearcoatRoughnessTexture ? { clearcoatRoughnessTexture } : {}),
+      ...(clearcoatNormalTexture ? {
+        clearcoatNormalTexture: { ...clearcoatNormalTexture, scale: material.clearcoatNormalScale },
+      } : {}),
+    };
+    extensionsUsed.add('KHR_materials_clearcoat');
+  }
+  if (material.ior !== 1.5) {
+    extensions.KHR_materials_ior = { ior: material.ior };
+    extensionsUsed.add('KHR_materials_ior');
+  }
+  if (
+    material.specularFactor !== 1
+    || material.specularColorFactor.some(channel => channel !== 1)
+    || specularTexture
+    || specularColorTexture
+  ) {
+    extensions.KHR_materials_specular = {
+      specularFactor: material.specularFactor,
+      ...(specularTexture ? { specularTexture } : {}),
+      specularColorFactor: [...material.specularColorFactor],
+      ...(specularColorTexture ? { specularColorTexture } : {}),
+    };
+    extensionsUsed.add('KHR_materials_specular');
+  }
+  if (
+    material.sheenColorFactor.some(channel => channel !== 0)
+    || material.sheenRoughnessFactor !== 0
+    || sheenColorTexture
+    || sheenRoughnessTexture
+  ) {
+    extensions.KHR_materials_sheen = {
+      sheenColorFactor: [...material.sheenColorFactor],
+      ...(sheenColorTexture ? { sheenColorTexture } : {}),
+      sheenRoughnessFactor: material.sheenRoughnessFactor,
+      ...(sheenRoughnessTexture ? { sheenRoughnessTexture } : {}),
+    };
+    extensionsUsed.add('KHR_materials_sheen');
+  }
+  if (material.transmissionFactor !== 0 || transmissionTexture) {
+    extensions.KHR_materials_transmission = {
+      transmissionFactor: material.transmissionFactor,
+      ...(transmissionTexture ? { transmissionTexture } : {}),
+    };
+    extensionsUsed.add('KHR_materials_transmission');
+  }
+  if (
+    material.thicknessFactor !== 0
+    || thicknessTexture
+    || material.attenuationDistance !== Infinity
+    || material.attenuationColor.some(channel => channel !== 1)
+  ) {
+    extensions.KHR_materials_volume = {
+      thicknessFactor: material.thicknessFactor,
+      ...(thicknessTexture ? { thicknessTexture } : {}),
+      ...(material.attenuationDistance === Infinity ? {} : { attenuationDistance: material.attenuationDistance }),
+      attenuationColor: [...material.attenuationColor],
+    };
+    extensionsUsed.add('KHR_materials_volume');
+    if (material.transmissionFactor === 0 && !transmissionTexture) {
+      extensions.KHR_materials_transmission = { transmissionFactor: 0 };
+      extensionsUsed.add('KHR_materials_transmission');
+    }
+  }
+
+  const gltfMaterial: GltfMaterial = {
+    ...(options.name ? { name: options.name } : {}),
+    pbrMetallicRoughness: {
+      baseColorFactor: [baseColor[0]!, baseColor[1]!, baseColor[2]!, baseColor[3]!],
+      ...(baseColorTexture ? { baseColorTexture } : {}),
+      ...(metallicRoughnessTexture ? { metallicRoughnessTexture } : {}),
+      metallicFactor: material.metallic,
+      roughnessFactor: material.roughness,
+    },
+    emissiveFactor: [...material.emissiveFactor],
+    ...(emissiveTexture ? { emissiveTexture } : {}),
+    ...(normalTexture ? { normalTexture: { ...normalTexture, scale: material.normalScale } } : {}),
+    ...(occlusionTexture ? { occlusionTexture: { ...occlusionTexture, strength: material.occlusionStrength } } : {}),
+    alphaMode: material.alphaMode === 'blend' ? 'BLEND' : material.alphaMode === 'mask' ? 'MASK' : 'OPAQUE',
+    ...(material.alphaMode === 'mask' ? { alphaCutoff: material.alphaCutoff } : {}),
+    doubleSided: material.doubleSided,
+    ...(Object.keys(extensions).length > 0 ? { extensions } : {}),
+  };
+  return Object.freeze({
+    material: gltfMaterial,
+    extensionsUsed: Object.freeze([...extensionsUsed]),
+  });
+}
+
+function encodeTextureInfo(
+  material: PbrMaterial,
+  slot: PbrTextureSlot,
+  index: number,
+  extensionsUsed: Set<string>,
+): GltfTextureInfo {
+  const mapping = material.getTextureMapping(slot);
+  const transform: GltfTextureTransform = {};
+  if (mapping.offset[0] !== 0 || mapping.offset[1] !== 0) transform.offset = [...mapping.offset];
+  if (mapping.rotation !== 0) transform.rotation = mapping.rotation;
+  if (mapping.scale[0] !== 1 || mapping.scale[1] !== 1) transform.scale = [...mapping.scale];
+  const transformed = Object.keys(transform).length > 0;
+  if (transformed) extensionsUsed.add('KHR_texture_transform');
+  return {
+    index,
+    ...(mapping.texCoord !== 0 ? { texCoord: mapping.texCoord } : {}),
+    ...(transformed ? { extensions: { KHR_texture_transform: transform } } : {}),
+  };
+}

package/src/gltf/GltfMaterialLoader.ts

@@ -0,0 +1,293 @@
+import type { PbrMaterial } from '@haiyue/engine';
+import {
+  createMaterialFromDescriptor,
+  getPbrTextureFormat,
+  type MaterialDescriptorVariant,
+  type MaterialTextureSource,
+  type PbrTextureMappingOptions,
+  type PbrTextureSlot,
+} from '@haiyue/engine/material';
+import type { AssetHandle, CompressedTextureSourceDescriptor } from '@haiyue/engine/assets';
+import {
+  collectGltfMaterialVariantReferences,
+} from './GltfExtensionAdapter';
+import {
+  collectGltfMaterialTextureBindings,
+  createGltfMaterialDescriptor,
+} from './GltfMaterialDescriptor';
+import { getGltfUvChannel, type GltfUvSemanticPlan } from './GltfUvSemanticPlanner';
+import { gltfDataError, throwIfGltfLoadAborted } from './GltfLoaderErrors';
+import type { GltfLoadContext, LoadGltfOptions } from './GltfLoaderContract';
+import type {
+  GltfAsset,
+  GltfImage,
+  GltfMaterial,
+  GltfPrimitive,
+  GltfTextureInfo,
+} from './GltfSchema';
+
+export async function createGltfMaterial(gltf: GltfAsset, buffers: ArrayBuffer[], primitive: GltfPrimitive, options: LoadGltfOptions, context: GltfLoadContext, uvPlan: GltfUvSemanticPlan): Promise<PbrMaterial> {
+  throwIfGltfLoadAborted(options.signal);
+  const materialIndex = primitive.material;
+  const gltfMaterial = materialIndex === undefined ? null : gltf.materials?.[materialIndex] ?? null;
+  const createDescriptor = (material: GltfMaterial | null, materialPath: string) => createGltfMaterialDescriptor({
+    gltf,
+    material,
+    primitive,
+    materialPath,
+    ...(options.baseColorFactor === undefined ? {} : { defaultBaseColor: options.baseColorFactor }),
+    adapters: context.extensionAdapters,
+    resolveTexture: binding => ({
+      source: createTextureSource(gltf, buffers, binding.textureInfo.index, binding.slot, context),
+      mapping: resolveGltfTextureMapping(binding.textureInfo, primitive, binding.path, uvPlan),
+      sampler: createSamplerDescriptor(gltf, binding.textureInfo.index),
+    }),
+  });
+  const descriptor = createDescriptor(
+    gltfMaterial,
+    materialIndex === undefined ? 'gltf.defaultMaterial' : `gltf.materials[${materialIndex}]`,
+  );
+  const variants: MaterialDescriptorVariant[] = collectGltfMaterialVariantReferences(
+    gltf,
+    primitive,
+    context.extensionAdapters,
+  ).map(variant => ({
+    name: variant.name,
+    state: createDescriptor(
+      gltf.materials?.[variant.materialIndex] ?? null,
+      `gltf.materials[${variant.materialIndex}]`,
+    ).state,
+  }));
+  return createMaterialFromDescriptor({ ...descriptor, variants });
+}
+
+function resolveGltfTextureMapping(
+  textureInfo: GltfTextureInfo,
+  primitive: GltfPrimitive,
+  path: string,
+  uvPlan: GltfUvSemanticPlan,
+): PbrTextureMappingOptions {
+  const transform = textureInfo.extensions?.KHR_texture_transform;
+  const textureCoord = transform?.texCoord ?? textureInfo.texCoord ?? 0;
+  const texCoordPath = transform?.texCoord === undefined
+    ? `${path}.texCoord`
+    : `${path}.extensions.KHR_texture_transform.texCoord`;
+  const semantic = `TEXCOORD_${textureCoord}`;
+  if (primitive.attributes[semantic] === undefined) {
+    throw gltfDataError(
+      `Texture references ${semantic}, but the mesh primitive does not provide that attribute.`,
+      { texCoord: textureCoord, semantic },
+      texCoordPath,
+    );
+  }
+  const channel = getGltfUvChannel(uvPlan, textureCoord);
+  if (channel === null) {
+    throw gltfDataError(
+      `${semantic} was not assigned to a physical PBR UV channel.`,
+      { texCoord: textureCoord, semantic, capacity: uvPlan.capacity },
+      texCoordPath,
+    );
+  }
+  return {
+    texCoord: channel,
+    offset: transform?.offset ?? [0, 0],
+    rotation: transform?.rotation ?? 0,
+    scale: transform?.scale ?? [1, 1],
+  };
+}
+
+function createSamplerDescriptor(gltf: GltfAsset, textureIndex: number): GPUSamplerDescriptor | null {
+  const texture = gltf.textures?.[textureIndex];
+  const sampler = texture?.sampler === undefined ? null : gltf.samplers?.[texture.sampler] ?? null;
+  return {
+    addressModeU: mapWrapMode(sampler?.wrapS),
+    addressModeV: mapWrapMode(sampler?.wrapT),
+    magFilter: mapMagFilter(sampler?.magFilter),
+    minFilter: mapMinFilter(sampler?.minFilter),
+    mipmapFilter: mapMipmapFilter(sampler?.minFilter),
+  };
+}
+
+function mapWrapMode(mode: number | undefined): GPUAddressMode {
+  switch (mode) {
+    case 33071: return 'clamp-to-edge';
+    case 33648: return 'mirror-repeat';
+    case 10497:
+    case undefined:
+      return 'repeat';
+    default:
+      return 'repeat';
+  }
+}
+
+function mapMagFilter(filter: number | undefined): GPUFilterMode {
+  return filter === 9728 ? 'nearest' : 'linear';
+}
+
+function mapMinFilter(filter: number | undefined): GPUFilterMode {
+  switch (filter) {
+    case 9728:
+    case 9984:
+    case 9986:
+      return 'nearest';
+    default:
+      return 'linear';
+  }
+}
+
+function mapMipmapFilter(filter: number | undefined): GPUMipmapFilterMode {
+  switch (filter) {
+    case 9984:
+    case 9985:
+      return 'nearest';
+    case 9986:
+    case 9987:
+      return 'linear';
+    default:
+      return 'linear';
+  }
+}
+
+interface GltfTextureReference {
+  readonly source: string | CompressedTextureSourceDescriptor;
+  readonly cacheKey: string;
+  readonly requestKey: string;
+  readonly format: 'rgba8unorm-srgb' | 'rgba8unorm';
+}
+
+export async function preloadGltfTextures(
+  gltf: GltfAsset,
+  buffers: ArrayBuffer[],
+  options: LoadGltfOptions,
+  context: GltfLoadContext,
+): Promise<void> {
+  const assetManager = options.assetManager;
+  if (!assetManager) return;
+  const requests = new Map<string, GltfTextureReference>();
+  for (const mesh of gltf.meshes ?? []) {
+    for (const primitive of mesh.primitives) {
+      const materialIndexes = new Set<number>();
+      if (primitive.material !== undefined) materialIndexes.add(primitive.material);
+      for (const variant of collectGltfMaterialVariantReferences(gltf, primitive, context.extensionAdapters)) {
+        materialIndexes.add(variant.materialIndex);
+      }
+      for (const materialIndex of materialIndexes) {
+        const material = gltf.materials?.[materialIndex] ?? null;
+        for (const binding of collectGltfMaterialTextureBindings(
+          gltf,
+          material,
+          primitive,
+          `gltf.materials[${materialIndex}]`,
+          context.extensionAdapters,
+        )) {
+          const reference = resolveTextureReference(gltf, buffers, binding.textureInfo.index, binding.slot, context);
+          if (reference) requests.set(reference.requestKey, reference);
+        }
+      }
+    }
+  }
+  const results = await Promise.allSettled([...requests.values()].map(async reference => ({
+    reference,
+    handle: await assetManager.loadTexture(reference.source, {
+      cacheKey: reference.cacheKey,
+      format: reference.format,
+      mipmaps: 'generate',
+      ...(options.signal === undefined ? {} : { signal: options.signal }),
+    }),
+  })));
+  const loaded: Array<{ reference: GltfTextureReference; handle: AssetHandle<GPUTexture> }> = [];
+  let firstError: unknown = null;
+  for (const result of results) {
+    if (result.status === 'fulfilled') loaded.push(result.value);
+    else if (firstError === null) firstError = result.reason;
+  }
+  if (firstError !== null) {
+    for (const { handle } of loaded) handle.release();
+    throw firstError;
+  }
+  for (const { reference, handle } of loaded) {
+    context.preloadedTextures.set(reference.requestKey, handle.value);
+    context.assetHandles.push(handle);
+  }
+}
+
+function createTextureSource(
+  gltf: GltfAsset,
+  buffers: ArrayBuffer[],
+  textureIndex: number,
+  slot: PbrTextureSlot,
+  context: GltfLoadContext,
+): MaterialTextureSource {
+  const reference = resolveTextureReference(gltf, buffers, textureIndex, slot, context);
+  if (!reference) return null;
+  return context.preloadedTextures.get(reference.requestKey) ?? reference.source;
+}
+
+function resolveTextureReference(
+  gltf: GltfAsset,
+  buffers: ArrayBuffer[],
+  textureIndex: number,
+  slot: PbrTextureSlot,
+  context: GltfLoadContext,
+): GltfTextureReference | null {
+  const texture = gltf.textures?.[textureIndex];
+  const basisuSource = texture?.extensions?.KHR_texture_basisu?.source;
+  const imageIndex = basisuSource ?? texture?.source;
+  if (imageIndex === undefined) return null;
+  const image = gltf.images?.[imageIndex] ?? null;
+  if (!image) return null;
+  const compressed = basisuSource !== undefined || image.mimeType === 'image/ktx2';
+  const src = createImageUrl(gltf, buffers, imageIndex, image, context);
+  if (!src) return null;
+  const source: string | CompressedTextureSourceDescriptor = compressed
+    ? { kind: 'compressed-texture', type: 'texture/ktx2', src }
+    : src;
+  const cacheKey = createImageCacheKey(imageIndex, image, context);
+  const format = getPbrTextureFormat(slot);
+  return {
+    source,
+    cacheKey,
+    requestKey: compressed ? `compressed:${cacheKey}` : `${format}:${cacheKey}`,
+    format,
+  };
+}
+
+function createImageCacheKey(imageIndex: number, image: GltfImage, context: GltfLoadContext): string {
+  if (image.uri) {
+    const url = image.uri.startsWith('data:') || image.uri.startsWith('blob:')
+      ? image.uri
+      : new URL(image.uri, context.baseUrl).href;
+    return `url:${url}`;
+  }
+  return `gltf:${context.assetIdentity}:image:${imageIndex}`;
+}
+
+function createImageUrl(
+  gltf: GltfAsset,
+  buffers: ArrayBuffer[],
+  imageIndex: number,
+  image: GltfImage,
+  context: GltfLoadContext,
+): string | null {
+  const cached = context.imageSources.get(imageIndex);
+  if (typeof cached === 'string') return cached;
+  if (image.uri) {
+    const url = image.uri.startsWith('data:') || image.uri.startsWith('blob:')
+      ? image.uri
+      : new URL(image.uri, context.baseUrl).href;
+    context.imageSources.set(imageIndex, url);
+    return url;
+  }
+  if (image.bufferView === undefined) return null;
+  const view = gltf.bufferViews?.[image.bufferView];
+  if (!view) return null;
+  const buffer = buffers[view.buffer];
+  if (!buffer) throw gltfDataError(`Image bufferView references missing buffer ${view.buffer}.`);
+  const bytes = new Uint8Array(buffer, view.byteOffset ?? 0, view.byteLength);
+  const blob = new Blob([bytes.slice()], { type: image.mimeType || 'application/octet-stream' });
+  const url = URL.createObjectURL(blob);
+  if (!context.sharedImageSources) context.objectUrls.push(url);
+  context.imageSources.set(imageIndex, url);
+  return url;
+}
+