@luma.gl/gltf 9.3.0-alpha.4 → 9.3.0-alpha.8

package/src/gltf/gltf-animator.ts

@@ -2,32 +2,47 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {GLTFNodePostprocessed} from '@loaders.gl/gltf';
 import {log} from '@luma.gl/core';
 import {GroupNode} from '@luma.gl/engine';
-import {Matrix4} from '@math.gl/core';
 import {GLTFAnimation} from './animations/animations';
 import {interpolate} from './animations/interpolate';
 
+/** Construction props for a single glTF animation controller. */
 type GLTFSingleAnimatorProps = {
+  /** Animation data to evaluate. */
   animation: GLTFAnimation;
+  /** Mapping from glTF node ids to scenegraph nodes. */
+  gltfNodeIdToNodeMap: Map<string, GroupNode>;
+  /** Start time in seconds. */
   startTime?: number;
+  /** Whether playback is active. */
   playing?: boolean;
+  /** Playback speed multiplier. */
   speed?: number;
 };
 
+/** Evaluates one glTF animation against the generated scenegraph. */
 class GLTFSingleAnimator {
+  /** Animation definition being played. */
   animation: GLTFAnimation;
+  /** Target scenegraph lookup table. */
+  gltfNodeIdToNodeMap: Map<string, GroupNode>;
+  /** Playback start time in seconds. */
   startTime: number = 0;
+  /** Whether playback is currently enabled. */
   playing: boolean = true;
+  /** Playback speed multiplier. */
   speed: number = 1;
 
+  /** Creates a single-animation controller. */
   constructor(props: GLTFSingleAnimatorProps) {
     this.animation = props.animation;
+    this.gltfNodeIdToNodeMap = props.gltfNodeIdToNodeMap;
     this.animation.name ||= 'unnamed';
     Object.assign(this, props);
   }
 
+  /** Advances the animation to the supplied wall-clock time in milliseconds. */
   setTime(timeMs: number) {
     if (!this.playing) {
       return;
@@ -36,24 +51,36 @@ class GLTFSingleAnimator {
     const absTime = timeMs / 1000;
     const time = (absTime - this.startTime) * this.speed;
 
-    this.animation.channels.forEach(({sampler, target, path}) => {
-      interpolate(time, sampler, target, path);
-      applyTranslationRotationScale(target, (target as any)._node as GroupNode);
+    this.animation.channels.forEach(({sampler, targetNodeId, path}) => {
+      const targetNode = this.gltfNodeIdToNodeMap.get(targetNodeId);
+      if (!targetNode) {
+        throw new Error(`Cannot find animation target node ${targetNodeId}`);
+      }
+
+      interpolate(time, sampler, targetNode, path);
     });
   }
 }
 
+/** Construction props for {@link GLTFAnimator}. */
 export type GLTFAnimatorProps = {
+  /** Parsed animations from the source glTF. */
   animations: GLTFAnimation[];
+  /** Mapping from glTF node ids to scenegraph nodes. */
+  gltfNodeIdToNodeMap: Map<string, GroupNode>;
 };
 
+/** Coordinates playback of every animation found in a glTF scene. */
 export class GLTFAnimator {
+  /** Individual animation controllers. */
   animations: GLTFSingleAnimator[];
 
+  /** Creates an animator for the supplied glTF scenegraph. */
   constructor(props: GLTFAnimatorProps) {
     this.animations = props.animations.map((animation, index) => {
       const name = animation.name || `Animation-${index}`;
       return new GLTFSingleAnimator({
+        gltfNodeIdToNodeMap: props.gltfNodeIdToNodeMap,
         animation: {name, channels: animation.channels}
       });
     });
@@ -65,31 +92,13 @@ export class GLTFAnimator {
     this.setTime(time);
   }
 
+  /** Advances every animation to the supplied wall-clock time in milliseconds. */
   setTime(time: number): void {
     this.animations.forEach(animation => animation.setTime(time));
   }
 
+  /** Returns the per-animation controllers managed by this animator. */
   getAnimations() {
     return this.animations;
   }
 }
-
-// TODO: share with GLTFInstantiator
-const scratchMatrix = new Matrix4();
-
-function applyTranslationRotationScale(gltfNode: GLTFNodePostprocessed, node: GroupNode) {
-  node.matrix.identity();
-
-  if (gltfNode.translation) {
-    node.matrix.translate(gltfNode.translation);
-  }
-
-  if (gltfNode.rotation) {
-    const rotationMatrix = scratchMatrix.fromQuaternion(gltfNode.rotation);
-    node.matrix.multiplyRight(rotationMatrix);
-  }
-
-  if (gltfNode.scale) {
-    node.matrix.scale(gltfNode.scale);
-  }
-}

package/src/gltf/gltf-extension-support.ts

@@ -0,0 +1,214 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {GLTFPostprocessed} from '@loaders.gl/gltf';
+
+export type GLTFExtensionSupportLevel = 'built-in' | 'parsed-and-wired' | 'loader-only' | 'none';
+
+export type GLTFExtensionSupport = {
+  extensionName: string;
+  supported: boolean;
+  supportLevel: GLTFExtensionSupportLevel;
+  comment: string;
+};
+
+type GLTFExtensionSupportDefinition = Omit<GLTFExtensionSupport, 'extensionName' | 'supported'>;
+
+type GLTFPostprocessedWithRemovedExtensions = GLTFPostprocessed & {
+  extensionsRemoved?: string[];
+  lights?: unknown[];
+};
+
+const UNKNOWN_EXTENSION_SUPPORT: GLTFExtensionSupportDefinition = {
+  supportLevel: 'none',
+  comment: 'Not currently listed in the luma.gl glTF extension support registry.'
+};
+
+const GLTF_EXTENSION_SUPPORT_REGISTRY: Record<string, GLTFExtensionSupportDefinition> = {
+  KHR_draco_mesh_compression: {
+    supportLevel: 'built-in',
+    comment: 'Decoded by loaders.gl before luma.gl builds the scenegraph.'
+  },
+  EXT_meshopt_compression: {
+    supportLevel: 'built-in',
+    comment: 'Meshopt-compressed primitives are decoded during load.'
+  },
+  KHR_mesh_quantization: {
+    supportLevel: 'built-in',
+    comment: 'Quantized accessors are unpacked before geometry creation.'
+  },
+  KHR_lights_punctual: {
+    supportLevel: 'built-in',
+    comment: 'Parsed into luma.gl Light objects.'
+  },
+  KHR_materials_unlit: {
+    supportLevel: 'built-in',
+    comment: 'Unlit materials bypass the default lighting path.'
+  },
+  KHR_materials_emissive_strength: {
+    supportLevel: 'built-in',
+    comment: 'Applied by the stock PBR shader.'
+  },
+  KHR_texture_basisu: {
+    supportLevel: 'built-in',
+    comment: 'BasisU / KTX2 textures pass through when the device supports them.'
+  },
+  KHR_texture_transform: {
+    supportLevel: 'built-in',
+    comment: 'UV transforms are applied during load.'
+  },
+  EXT_texture_webp: {
+    supportLevel: 'loader-only',
+    comment:
+      'Texture source is resolved during load; final support depends on browser and device decode support.'
+  },
+  EXT_texture_avif: {
+    supportLevel: 'loader-only',
+    comment:
+      'Texture source is resolved during load; final support depends on browser and device decode support.'
+  },
+  KHR_materials_specular: {
+    supportLevel: 'built-in',
+    comment: 'The stock shader now applies specular factors and textures to the dielectric F0 term.'
+  },
+  KHR_materials_ior: {
+    supportLevel: 'built-in',
+    comment: 'The stock shader now drives dielectric reflectance from the glTF IOR value.'
+  },
+  KHR_materials_transmission: {
+    supportLevel: 'built-in',
+    comment:
+      'The stock shader now applies transmission to the base layer and exposes transparency through alpha, without a scene-color refraction buffer.'
+  },
+  KHR_materials_volume: {
+    supportLevel: 'built-in',
+    comment: 'Thickness and attenuation now tint transmitted light in the stock shader.'
+  },
+  KHR_materials_clearcoat: {
+    supportLevel: 'built-in',
+    comment: 'The stock shader now adds a secondary clearcoat specular lobe.'
+  },
+  KHR_materials_sheen: {
+    supportLevel: 'built-in',
+    comment: 'The stock shader now adds a sheen lobe for cloth-like materials.'
+  },
+  KHR_materials_iridescence: {
+    supportLevel: 'built-in',
+    comment:
+      'The stock shader now tints specular response with a view-dependent thin-film iridescence approximation.'
+  },
+  KHR_materials_anisotropy: {
+    supportLevel: 'built-in',
+    comment:
+      'The stock shader now shapes highlights and IBL response with an anisotropy-direction approximation.'
+  },
+  KHR_materials_pbrSpecularGlossiness: {
+    supportLevel: 'loader-only',
+    comment:
+      'Extension data can be loaded, but it is not translated into the default metallic-roughness material path.'
+  },
+  KHR_materials_variants: {
+    supportLevel: 'loader-only',
+    comment: 'Variant metadata can be loaded, but applications must choose and apply variants.'
+  },
+  EXT_mesh_gpu_instancing: {
+    supportLevel: 'none',
+    comment: 'GPU instancing data is not yet converted into luma.gl instanced draw setup.'
+  },
+  KHR_node_visibility: {
+    supportLevel: 'none',
+    comment: 'Node-visibility animations and toggles are not mapped onto runtime scenegraph state.'
+  },
+  KHR_animation_pointer: {
+    supportLevel: 'none',
+    comment: 'Animation pointers are not mapped onto runtime scenegraph updates.'
+  },
+  KHR_materials_diffuse_transmission: {
+    supportLevel: 'none',
+    comment: 'Diffuse-transmission shading is not implemented in the stock PBR shader.'
+  },
+  KHR_materials_dispersion: {
+    supportLevel: 'none',
+    comment: 'Chromatic dispersion is not implemented in the stock PBR shader.'
+  },
+  KHR_materials_volume_scatter: {
+    supportLevel: 'none',
+    comment: 'Volume scattering is not implemented in the stock PBR shader.'
+  },
+  KHR_xmp: {
+    supportLevel: 'none',
+    comment: 'Metadata payloads remain in the loaded glTF, but luma.gl does not interpret them.'
+  },
+  KHR_xmp_json_ld: {
+    supportLevel: 'none',
+    comment: 'Metadata is preserved in the glTF, but luma.gl does not interpret it.'
+  },
+  EXT_lights_image_based: {
+    supportLevel: 'none',
+    comment: 'Use loadPBREnvironment() or custom environment setup instead.'
+  },
+  EXT_texture_video: {
+    supportLevel: 'none',
+    comment: 'Video textures are not created automatically by the stock pipeline.'
+  },
+  MSFT_lod: {
+    supportLevel: 'none',
+    comment: 'Level-of-detail switching is not implemented in the stock scenegraph loader.'
+  }
+};
+
+export function getGLTFExtensionSupport(
+  gltf: GLTFPostprocessed
+): Map<string, GLTFExtensionSupport> {
+  const extensionNames = Array.from(collectGLTFExtensionNames(gltf)).sort();
+  const extensionSupportEntries: [string, GLTFExtensionSupport][] = extensionNames.map(
+    extensionName => {
+      const extensionSupportDefinition =
+        GLTF_EXTENSION_SUPPORT_REGISTRY[extensionName] || UNKNOWN_EXTENSION_SUPPORT;
+
+      return [
+        extensionName,
+        {
+          extensionName,
+          supported: extensionSupportDefinition.supportLevel === 'built-in',
+          supportLevel: extensionSupportDefinition.supportLevel,
+          comment: extensionSupportDefinition.comment
+        }
+      ];
+    }
+  );
+
+  return new Map(extensionSupportEntries);
+}
+
+function collectGLTFExtensionNames(gltf: GLTFPostprocessed): Set<string> {
+  const gltfWithRemovedExtensions = gltf as GLTFPostprocessedWithRemovedExtensions;
+  const extensionNames = new Set<string>();
+
+  addExtensionNames(extensionNames, gltf.extensionsUsed);
+  addExtensionNames(extensionNames, gltf.extensionsRequired);
+  addExtensionNames(extensionNames, gltfWithRemovedExtensions.extensionsRemoved);
+  addExtensionNames(extensionNames, Object.keys(gltf.extensions || {}));
+
+  if (gltfWithRemovedExtensions.lights?.length || gltf.nodes.some(node => 'light' in node)) {
+    extensionNames.add('KHR_lights_punctual');
+  }
+
+  if (
+    gltf.materials.some(material => {
+      const gltfMaterial = material as typeof material & {unlit?: boolean};
+      return gltfMaterial.unlit || gltfMaterial.extensions?.KHR_materials_unlit;
+    })
+  ) {
+    extensionNames.add('KHR_materials_unlit');
+  }
+
+  return extensionNames;
+}
+
+function addExtensionNames(extensionNames: Set<string>, newExtensionNames: string[] = []): void {
+  for (const extensionName of newExtensionNames) {
+    extensionNames.add(extensionName);
+  }
+}

package/src/index.ts

@@ -3,9 +3,17 @@
 export {loadPBREnvironment, type PBREnvironment} from './pbr/pbr-environment';
 export {type ParsedPBRMaterial} from './pbr/pbr-material';
 export {parsePBRMaterial, type ParsePBRMaterialOptions} from './parsers/parse-pbr-material';
-export {} from './pbr/pbr-environment';
 export {parseGLTFLights} from './parsers/parse-gltf-lights';
 
 // glTF Scenegraph Instantiator
-export {createScenegraphsFromGLTF} from './gltf/create-scenegraph-from-gltf';
+export {
+  createScenegraphsFromGLTF,
+  type GLTFScenegraphBounds,
+  type GLTFScenegraphs
+} from './gltf/create-scenegraph-from-gltf';
+export {
+  getGLTFExtensionSupport,
+  type GLTFExtensionSupport,
+  type GLTFExtensionSupportLevel
+} from './gltf/gltf-extension-support';
 export {GLTFAnimator} from './gltf/gltf-animator';

package/src/parsers/parse-gltf-animations.ts

@@ -2,8 +2,10 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
+import {log} from '@luma.gl/core';
 import {type GLTFAccessorPostprocessed, type GLTFPostprocessed} from '@loaders.gl/gltf';
 import {
+  GLTFAnimationPath,
   type GLTFAnimation,
   type GLTFAnimationChannel,
   type GLTFAnimationSampler
@@ -11,45 +13,104 @@ import {
 
 import {accessorToTypedArray} from '..//webgl-to-webgpu/convert-webgl-attribute';
 
+/** Parses glTF animation records into the runtime animation model used by `GLTFAnimator`. */
 export function parseGLTFAnimations(gltf: GLTFPostprocessed): GLTFAnimation[] {
   const gltfAnimations = gltf.animations || [];
-  return gltfAnimations.map((animation, index) => {
+  const accessorCache1D = new Map<GLTFAccessorPostprocessed, number[]>();
+  const accessorCache2D = new Map<GLTFAccessorPostprocessed, number[][]>();
+
+  return gltfAnimations.flatMap((animation, index) => {
     const name = animation.name || `Animation-${index}`;
-    const samplers: GLTFAnimationSampler[] = animation.samplers.map(
-      ({input, interpolation = 'LINEAR', output}) => ({
-        input: accessorToJsArray(gltf.accessors[input]) as number[],
-        interpolation,
-        output: accessorToJsArray(gltf.accessors[output])
-      })
-    );
-    const channels: GLTFAnimationChannel[] = animation.channels.map(({sampler, target}) => ({
-      sampler: samplers[sampler],
-      target: gltf.nodes[target.node ?? 0],
-      path: target.path as GLTFAnimationChannel['path']
-    }));
-    return {name, channels};
+    const samplerCache = new Map<number, GLTFAnimationSampler>();
+    const channels: GLTFAnimationChannel[] = animation.channels.flatMap(({sampler, target}) => {
+      const path = getSupportedAnimationPath(target.path);
+      if (!path) {
+        return [];
+      }
+
+      const targetNode = gltf.nodes[target.node ?? 0];
+      if (!targetNode) {
+        throw new Error(`Cannot find animation target ${target.node}`);
+      }
+
+      let parsedSampler = samplerCache.get(sampler);
+      if (!parsedSampler) {
+        const gltfSampler = animation.samplers[sampler];
+        if (!gltfSampler) {
+          throw new Error(`Cannot find animation sampler ${sampler}`);
+        }
+        const {input, interpolation = 'LINEAR', output} = gltfSampler;
+        parsedSampler = {
+          input: accessorToJsArray1D(gltf.accessors[input], accessorCache1D),
+          interpolation,
+          output: accessorToJsArray2D(gltf.accessors[output], accessorCache2D)
+        };
+        samplerCache.set(sampler, parsedSampler);
+      }
+
+      return {
+        sampler: parsedSampler,
+        targetNodeId: targetNode.id,
+        path
+      };
+    });
+
+    return channels.length ? [{name, channels}] : [];
   });
 }
 
-//
-
-function accessorToJsArray(
-  accessor: GLTFAccessorPostprocessed & {_animation?: number[] | number[][]}
-): number[] | number[][] {
-  if (!accessor._animation) {
-    const {typedArray: array, components} = accessorToTypedArray(accessor);
-
-    if (components === 1) {
-      accessor._animation = Array.from(array);
-    } else {
-      // Slice array
-      const slicedArray: number[][] = [];
-      for (let i = 0; i < array.length; i += components) {
-        slicedArray.push(Array.from(array.slice(i, i + components)));
-      }
-      accessor._animation = slicedArray;
-    }
+function getSupportedAnimationPath(path: string): GLTFAnimationPath | null {
+  if (path === 'pointer') {
+    log.warn('KHR_animation_pointer channels are not supported and will be skipped')();
+    return null;
+  }
+
+  return path as GLTFAnimationPath;
+}
+
+/** Converts a scalar accessor into a cached JavaScript number array. */
+function accessorToJsArray1D(
+  accessor: GLTFAccessorPostprocessed,
+  accessorCache: Map<GLTFAccessorPostprocessed, number[]>
+): number[] {
+  if (accessorCache.has(accessor)) {
+    return accessorCache.get(accessor)!;
   }
 
-  return accessor._animation;
+  const {typedArray: array, components} = accessorToTypedArray(accessor);
+  assert(components === 1, 'accessorToJsArray1D must have exactly 1 component');
+  const result = Array.from(array);
+
+  accessorCache.set(accessor, result);
+  return result;
+}
+
+/** Converts a scalar, vector, or matrix accessor into a cached JavaScript array-of-arrays. */
+function accessorToJsArray2D(
+  accessor: GLTFAccessorPostprocessed,
+  accessorCache: Map<GLTFAccessorPostprocessed, number[][]>
+): number[][] {
+  if (accessorCache.has(accessor)) {
+    return accessorCache.get(accessor)!;
+  }
+
+  const {typedArray: array, components} = accessorToTypedArray(accessor);
+  assert(components >= 1, 'accessorToJsArray2D must have at least 1 component');
+
+  const result = [];
+
+  // Slice array
+  for (let i = 0; i < array.length; i += components) {
+    result.push(Array.from(array.slice(i, i + components)));
+  }
+
+  accessorCache.set(accessor, result);
+  return result;
+}
+
+/** Throws when the supplied condition is false. */
+function assert(condition: boolean, message?: string): asserts condition {
+  if (!condition) {
+    throw new Error(message);
+  }
 }