@aura3d/assets 1.0.6

package/src/GLTFCompressionDecoders.ts

@@ -0,0 +1,190 @@
+import type {
+  GLTFDracoDecodeDescriptor,
+  GLTFDracoDecodedPrimitive,
+  GLTFDracoDecoder,
+  GLTFMeshoptDecodeDescriptor,
+  GLTFMeshoptDecoder
+} from "./GLTFLoader";
+
+export interface GLTFMeshoptDecoderModule {
+  readonly ready?: PromiseLike<void>;
+  decodeGltfBuffer(
+    target: Uint8Array,
+    count: number,
+    size: number,
+    source: Uint8Array,
+    mode: GLTFMeshoptDecodeDescriptor["mode"],
+    filter?: GLTFMeshoptDecodeDescriptor["filter"]
+  ): void;
+}
+
+export interface GLTFDracoStatus {
+  ok(): boolean;
+  error_msg(): string;
+}
+
+export interface GLTFDracoDecoderBuffer {
+  Init(data: Uint8Array, byteLength: number): void;
+}
+
+export interface GLTFDracoMesh {
+  num_points(): number;
+  num_faces(): number;
+}
+
+export interface GLTFDracoAttribute {
+  num_components(): number;
+}
+
+export interface GLTFDracoNumericArray {
+  size(): number;
+  GetValue(index: number): number;
+}
+
+export interface GLTFDracoDecoderInstance {
+  GetEncodedGeometryType(buffer: GLTFDracoDecoderBuffer): number;
+  DecodeBufferToMesh(buffer: GLTFDracoDecoderBuffer, mesh: GLTFDracoMesh): GLTFDracoStatus;
+  GetAttributeByUniqueId(mesh: GLTFDracoMesh, uniqueId: number): GLTFDracoAttribute | null;
+  GetAttributeFloatForAllPoints(mesh: GLTFDracoMesh, attribute: GLTFDracoAttribute, out: GLTFDracoNumericArray): boolean;
+  GetFaceFromMesh(mesh: GLTFDracoMesh, faceIndex: number, out: GLTFDracoNumericArray): boolean;
+}
+
+export interface GLTFDracoDecoderModule {
+  readonly TRIANGULAR_MESH: number;
+  readonly Decoder: new () => GLTFDracoDecoderInstance;
+  readonly DecoderBuffer: new () => GLTFDracoDecoderBuffer;
+  readonly Mesh: new () => GLTFDracoMesh;
+  readonly DracoFloat32Array: new () => GLTFDracoNumericArray;
+  readonly DracoInt32Array: new () => GLTFDracoNumericArray;
+  destroy?(object: unknown): void;
+}
+
+export function createMeshoptDecoder(module: GLTFMeshoptDecoderModule): GLTFMeshoptDecoder {
+  return async (source, descriptor) => {
+    if (module.ready) {
+      await module.ready;
+    }
+    const target = new Uint8Array(descriptor.count * descriptor.byteStride);
+    module.decodeGltfBuffer(
+      target,
+      descriptor.count,
+      descriptor.byteStride,
+      source,
+      descriptor.mode,
+      descriptor.filter
+    );
+    return target;
+  };
+}
+
+export function createDracoDecoder(module: GLTFDracoDecoderModule): GLTFDracoDecoder {
+  return (source, descriptor) => {
+    const allocated: unknown[] = [];
+    const decoder = track(new module.Decoder(), allocated);
+    const buffer = track(new module.DecoderBuffer(), allocated);
+    const mesh = track(new module.Mesh(), allocated);
+
+    try {
+      buffer.Init(source, source.byteLength);
+      const geometryType = decoder.GetEncodedGeometryType(buffer);
+      if (geometryType !== module.TRIANGULAR_MESH) {
+        throw new Error(`glTF Draco primitive ${descriptorLabel(descriptor)} must decode to a triangular mesh`);
+      }
+
+      const status = decoder.DecodeBufferToMesh(buffer, mesh);
+      if (!status.ok()) {
+        throw new Error(`glTF Draco primitive ${descriptorLabel(descriptor)} decode failed: ${status.error_msg()}`);
+      }
+
+      return {
+        attributes: decodeDracoAttributes(module, decoder, mesh, descriptor, allocated),
+        indices: decodeDracoIndices(module, decoder, mesh, descriptor, allocated)
+      };
+    } finally {
+      destroyAllocated(module, allocated);
+    }
+  };
+}
+
+function decodeDracoAttributes(
+  module: GLTFDracoDecoderModule,
+  decoder: GLTFDracoDecoderInstance,
+  mesh: GLTFDracoMesh,
+  descriptor: GLTFDracoDecodeDescriptor,
+  allocated: unknown[]
+): GLTFDracoDecodedPrimitive["attributes"] {
+  const pointCount = mesh.num_points();
+  const attributes: Record<string, number[][]> = {};
+
+  for (const [semantic, uniqueId] of Object.entries(descriptor.attributes)) {
+    const attribute = decoder.GetAttributeByUniqueId(mesh, uniqueId);
+    if (!attribute) {
+      throw new Error(`glTF Draco primitive ${descriptorLabel(descriptor)} is missing decoded attribute ${semantic} unique id ${uniqueId}`);
+    }
+
+    const componentCount = attribute.num_components();
+    if (!Number.isInteger(componentCount) || componentCount <= 0) {
+      throw new Error(`glTF Draco primitive ${descriptorLabel(descriptor)} decoded attribute ${semantic} has invalid component count ${componentCount}`);
+    }
+
+    const values = track(new module.DracoFloat32Array(), allocated);
+    if (!decoder.GetAttributeFloatForAllPoints(mesh, attribute, values)) {
+      throw new Error(`glTF Draco primitive ${descriptorLabel(descriptor)} failed to read decoded attribute ${semantic}`);
+    }
+    if (values.size() !== pointCount * componentCount) {
+      throw new Error(`glTF Draco primitive ${descriptorLabel(descriptor)} decoded attribute ${semantic} has ${values.size()} values but expected ${pointCount * componentCount}`);
+    }
+
+    const rows: number[][] = [];
+    for (let pointIndex = 0; pointIndex < pointCount; pointIndex += 1) {
+      const row: number[] = [];
+      for (let componentIndex = 0; componentIndex < componentCount; componentIndex += 1) {
+        row.push(values.GetValue(pointIndex * componentCount + componentIndex));
+      }
+      rows.push(row);
+    }
+    attributes[semantic] = rows;
+  }
+
+  return attributes;
+}
+
+function decodeDracoIndices(
+  module: GLTFDracoDecoderModule,
+  decoder: GLTFDracoDecoderInstance,
+  mesh: GLTFDracoMesh,
+  descriptor: GLTFDracoDecodeDescriptor,
+  allocated: unknown[]
+): number[] | undefined {
+  const faceCount = mesh.num_faces();
+  if (faceCount === 0) return undefined;
+
+  const face = track(new module.DracoInt32Array(), allocated);
+  const indices: number[] = [];
+  for (let faceIndex = 0; faceIndex < faceCount; faceIndex += 1) {
+    if (!decoder.GetFaceFromMesh(mesh, faceIndex, face)) {
+      throw new Error(`glTF Draco primitive ${descriptorLabel(descriptor)} failed to read decoded face ${faceIndex}`);
+    }
+    if (face.size() !== 3) {
+      throw new Error(`glTF Draco primitive ${descriptorLabel(descriptor)} decoded face ${faceIndex} has ${face.size()} indices but expected 3`);
+    }
+    indices.push(face.GetValue(0), face.GetValue(1), face.GetValue(2));
+  }
+  return indices;
+}
+
+function track<T>(value: T, allocated: unknown[]): T {
+  allocated.push(value);
+  return value;
+}
+
+function destroyAllocated(module: GLTFDracoDecoderModule, allocated: unknown[]): void {
+  if (!module.destroy) return;
+  for (let index = allocated.length - 1; index >= 0; index -= 1) {
+    module.destroy(allocated[index]);
+  }
+}
+
+function descriptorLabel(descriptor: GLTFDracoDecodeDescriptor): string {
+  return `${descriptor.meshIndex}/${descriptor.primitiveIndex}`;
+}

package/src/GLTFExtensionSupport.ts

@@ -0,0 +1,138 @@
+export type GLTFExtensionSupportFamily =
+  | "texture"
+  | "geometry"
+  | "material"
+  | "animation"
+  | "scene"
+  | "compression";
+
+export type GLTFExtensionSupportStatus =
+  | "runtime-supported"
+  | "decoder-required"
+  | "parsed-with-limits"
+  | "diagnostic-only"
+  | "unsupported";
+
+export interface GLTFExtensionSupportEntry {
+  readonly name: string;
+  readonly family: GLTFExtensionSupportFamily;
+  readonly status: GLTFExtensionSupportStatus;
+  readonly requiredAccepted: boolean;
+  readonly publicApi: readonly string[];
+  readonly decoder?: "draco" | "meshopt" | "ktx2-basis";
+  readonly knownLimits: readonly string[];
+}
+
+export interface GLTFExtensionSupportEvaluation {
+  readonly schemaVersion: "gltf-extension-support";
+  readonly requested: readonly GLTFExtensionSupportEntry[];
+  readonly supported: readonly GLTFExtensionSupportEntry[];
+  readonly runtimeSupported: readonly GLTFExtensionSupportEntry[];
+  readonly parsedWithLimits: readonly GLTFExtensionSupportEntry[];
+  readonly diagnosticOnly: readonly GLTFExtensionSupportEntry[];
+  readonly unsupportedUsed: readonly string[];
+  readonly unsupportedRequired: readonly string[];
+  readonly notAcceptedUsed: readonly string[];
+  readonly decoderRequired: readonly GLTFExtensionSupportEntry[];
+}
+
+export const GLTF_EXTENSION_SUPPORT_MATRIX: readonly GLTFExtensionSupportEntry[] = [
+  entry("EXT_texture_avif", "texture", "runtime-supported", ["GLTFLoader"], []),
+  entry("EXT_texture_webp", "texture", "runtime-supported", ["GLTFLoader"], []),
+  entry("KHR_texture_basisu", "compression", "decoder-required", ["GLTFLoader", "createGLTFRenderResources", "transcodeKTX2BasisTexture"], ["Requires loaders.gl Basis/KTX2 transcoder modules at render-resource creation time."], "ktx2-basis"),
+  entry("KHR_texture_transform", "texture", "runtime-supported", ["GLTFLoader", "TexturedPBRMaterial"], []),
+  entry("KHR_mesh_quantization", "geometry", "runtime-supported", ["GLTFLoader"], []),
+  entry("KHR_draco_mesh_compression", "compression", "decoder-required", ["GLTFLoader", "createDracoDecoder"], ["Requires an injected Draco decoder module."], "draco"),
+  entry("EXT_meshopt_compression", "compression", "decoder-required", ["GLTFLoader", "createMeshoptDecoder"], ["Requires an injected meshoptimizer decoder module."], "meshopt"),
+  entry("KHR_meshopt_compression", "compression", "decoder-required", ["GLTFLoader", "createMeshoptDecoder"], ["Requires an injected meshoptimizer decoder module."], "meshopt"),
+  entry("EXT_mesh_gpu_instancing", "geometry", "runtime-supported", ["GLTFLoader", "Renderable.instanceTransforms", "ProductionWebGL2Renderer"], ["Supports TRS instance attributes; custom per-instance material attributes remain out of scope."]),
+  entry("KHR_lights_punctual", "scene", "runtime-supported", ["GLTFLoader", "Scene", "ProductionWebGL2Renderer"], []),
+  entry("KHR_materials_unlit", "material", "runtime-supported", ["GLTFLoader", "UnlitMaterial"], []),
+  entry("KHR_materials_emissive_strength", "material", "runtime-supported", ["GLTFLoader", "TexturedPBRMaterial"], []),
+  entry("KHR_materials_clearcoat", "material", "parsed-with-limits", ["GLTFLoader", "TexturedPBRMaterial"], ["Clearcoat factors/textures are mapped; full reference BRDF parity still requires visual corpus acceptance."]),
+  entry("KHR_materials_transmission", "material", "parsed-with-limits", ["GLTFLoader", "TexturedPBRMaterial"], ["Transmission is mapped to the current WebGL2 fallback path; screen-space/refraction parity remains blocked."]),
+  entry("KHR_materials_diffuse_transmission", "material", "parsed-with-limits", ["GLTFLoader", "TexturedPBRMaterial"], ["Diffuse transmission factors/textures are mapped; full reference energy parity remains blocked."]),
+  entry("KHR_materials_volume", "material", "parsed-with-limits", ["GLTFLoader", "TexturedPBRMaterial"], ["Volume attenuation/thickness are mapped for fallback rendering, not full volumetric path tracing."]),
+  entry("KHR_materials_ior", "material", "runtime-supported", ["GLTFLoader", "TexturedPBRMaterial"], []),
+  entry("KHR_materials_specular", "material", "parsed-with-limits", ["GLTFLoader", "TexturedPBRMaterial"], ["Specular factors/textures are mapped; full reference BRDF parity still requires visual corpus acceptance."]),
+  entry("KHR_materials_sheen", "material", "parsed-with-limits", ["GLTFLoader", "TexturedPBRMaterial"], ["Sheen factors/textures are mapped; cloth reference parity remains blocked."]),
+  entry("KHR_materials_anisotropy", "material", "parsed-with-limits", ["GLTFLoader", "TexturedPBRMaterial"], ["Anisotropy factors/textures are mapped; tangent-space visual parity remains under review."]),
+  entry("KHR_materials_iridescence", "material", "parsed-with-limits", ["GLTFLoader", "TexturedPBRMaterial"], ["Iridescence factors/textures are mapped; thin-film reference parity remains under review."]),
+  entry("KHR_materials_dispersion", "material", "parsed-with-limits", ["GLTFLoader", "TexturedPBRMaterial"], ["Dispersion factor is preserved for material fallback; spectral dispersion rendering remains blocked."]),
+  entry("KHR_materials_pbrSpecularGlossiness", "material", "parsed-with-limits", ["GLTFLoader", "TexturedPBRMaterial"], ["Spec/gloss assets are converted into the current metallic-roughness runtime contract."]),
+  entry("KHR_materials_variants", "material", "parsed-with-limits", ["GLTFLoader"], ["Variant mappings are loaded; authoring/persistence workflow parity remains blocked."]),
+  entry("KHR_animation_pointer", "animation", "diagnostic-only", ["GLTFLoader"], ["Optional animation pointer channels are reported as unsupported tracks unless promoted into runtime targets."])
+];
+
+export const GLTF_SUPPORTED_EXTENSION_NAMES = GLTF_EXTENSION_SUPPORT_MATRIX
+  .filter((extension) => extension.status !== "diagnostic-only" && extension.status !== "unsupported")
+  .map((extension) => extension.name);
+
+export const GLTF_RUNTIME_SUPPORTED_EXTENSION_NAMES = extensionNamesByStatus("runtime-supported");
+export const GLTF_DECODER_REQUIRED_EXTENSION_NAMES = extensionNamesByStatus("decoder-required");
+export const GLTF_PARSED_WITH_LIMITS_EXTENSION_NAMES = extensionNamesByStatus("parsed-with-limits");
+export const GLTF_DIAGNOSTIC_ONLY_EXTENSION_NAMES = extensionNamesByStatus("diagnostic-only");
+export const GLTF_REQUIRED_ACCEPTED_EXTENSION_NAMES = GLTF_EXTENSION_SUPPORT_MATRIX
+  .filter((extension) => extension.requiredAccepted)
+  .map((extension) => extension.name);
+
+export function getGLTFExtensionSupport(name: string): GLTFExtensionSupportEntry {
+  return GLTF_EXTENSION_SUPPORT_MATRIX.find((entry) => entry.name === name)
+    ?? {
+      name,
+      family: "scene",
+      status: "unsupported",
+      requiredAccepted: false,
+      publicApi: [],
+      knownLimits: ["No A3D loader/runtime support is registered for this extension."]
+    };
+}
+
+export function evaluateGLTFExtensionSupport(
+  extensionsUsed: readonly string[] = [],
+  extensionsRequired: readonly string[] = []
+): GLTFExtensionSupportEvaluation {
+  const requested = [...new Set([...extensionsUsed, ...extensionsRequired])].sort();
+  const requestedEntries = requested.map((name) => getGLTFExtensionSupport(name));
+  const supported = requestedEntries.filter((entry) => entry.status !== "unsupported");
+  const unsupportedUsed = extensionsUsed.filter((name) => getGLTFExtensionSupport(name).status === "unsupported").sort();
+  const unsupportedRequired = extensionsRequired.filter((name) => !getGLTFExtensionSupport(name).requiredAccepted).sort();
+  const notAcceptedUsed = extensionsUsed.filter((name) => !getGLTFExtensionSupport(name).requiredAccepted).sort();
+  return {
+    schemaVersion: "gltf-extension-support",
+    requested: requestedEntries,
+    supported,
+    runtimeSupported: supported.filter((entry) => entry.status === "runtime-supported"),
+    parsedWithLimits: supported.filter((entry) => entry.status === "parsed-with-limits"),
+    diagnosticOnly: supported.filter((entry) => entry.status === "diagnostic-only"),
+    unsupportedUsed,
+    unsupportedRequired,
+    notAcceptedUsed,
+    decoderRequired: supported.filter((entry) => entry.status === "decoder-required")
+  };
+}
+
+function extensionNamesByStatus(status: GLTFExtensionSupportStatus): readonly string[] {
+  return GLTF_EXTENSION_SUPPORT_MATRIX
+    .filter((extension) => extension.status === status)
+    .map((extension) => extension.name);
+}
+
+function entry(
+  name: string,
+  family: GLTFExtensionSupportFamily,
+  status: Exclude<GLTFExtensionSupportStatus, "unsupported">,
+  publicApi: readonly string[],
+  knownLimits: readonly string[],
+  decoder?: GLTFExtensionSupportEntry["decoder"]
+): GLTFExtensionSupportEntry {
+  return {
+    name,
+    family,
+    status,
+    requiredAccepted: status !== "diagnostic-only",
+    publicApi,
+    ...(decoder === undefined ? {} : { decoder }),
+    knownLimits
+  };
+}