@luma.gl/gltf 9.2.6 → 9.3.0-alpha.11

package/src/gltf/gltf-animator.ts

@@ -2,32 +2,77 @@
 // 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';
+import {GroupNode, Material} from '@luma.gl/engine';
+import {
+  GLTFAnimation,
+  GLTFMaterialAnimationChannel,
+  GLTFMaterialAnimationProperty,
+  GLTFTextureTransformAnimationChannel
+} from './animations/animations';
+import {evaluateSampler, interpolate} from './animations/interpolate';
+import {
+  getTextureTransformDeltaMatrix,
+  getTextureTransformSlotDefinition,
+  type PBRTextureTransform,
+  type PBRTextureTransformSlot
+} from '../pbr/texture-transform';
 
+/** 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>;
+  /** Materials aligned with the source glTF materials array. */
+  materials?: Material[];
+  /** 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>;
+  /** Materials aligned with the source glTF materials array. */
+  materials: Material[];
+  /** Playback start time in seconds. */
   startTime: number = 0;
+  /** Whether playback is currently enabled. */
   playing: boolean = true;
+  /** Playback speed multiplier. */
   speed: number = 1;
+  /** Mutable runtime texture-transform state for animated material slots. */
+  materialTextureTransformState = new Map<
+    Material,
+    Partial<Record<PBRTextureTransformSlot, PBRTextureTransform>>
+  >();
 
+  /** Creates a single-animation controller. */
   constructor(props: GLTFSingleAnimatorProps) {
     this.animation = props.animation;
+    this.gltfNodeIdToNodeMap = props.gltfNodeIdToNodeMap;
+    this.materials = props.materials || [];
     this.animation.name ||= 'unnamed';
     Object.assign(this, props);
+
+    if (
+      this.animation.channels.some(channel => channel.type !== 'node') &&
+      !this.materials.length
+    ) {
+      throw new Error(
+        `Animation ${this.animation.name} targets materials, but GLTFAnimator was created without a materials array`
+      );
+    }
   }
 
+  /** Advances the animation to the supplied wall-clock time in milliseconds. */
   setTime(timeMs: number) {
     if (!this.playing) {
       return;
@@ -36,24 +81,64 @@ 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(channel => {
+      if (channel.type === 'node') {
+        const {sampler, targetNodeId, path} = channel;
+        const targetNode = this.gltfNodeIdToNodeMap.get(targetNodeId);
+        if (!targetNode) {
+          throw new Error(`Cannot find animation target node ${targetNodeId}`);
+        }
+
+        interpolate(time, sampler, targetNode, path);
+        return;
+      }
+
+      const material = this.materials[channel.targetMaterialIndex];
+      if (!material) {
+        throw new Error(
+          `Cannot find animation target material ${channel.targetMaterialIndex} for ${channel.pointer}`
+        );
+      }
+
+      const value = evaluateSampler(time, channel.sampler);
+      if (value) {
+        if (channel.type === 'material') {
+          applyMaterialAnimationValue(material, channel, value);
+        } else {
+          applyTextureTransformAnimationValue(
+            material,
+            channel,
+            value,
+            this.materialTextureTransformState
+          );
+        }
+      }
     });
   }
 }
 
+/** 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>;
+  /** Materials aligned with the source glTF materials array. */
+  materials?: Material[];
 };
 
+/** 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,
+        materials: props.materials,
         animation: {name, channels: animation.channels}
       });
     });
@@ -65,31 +150,124 @@ 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 applyMaterialAnimationValue(
+  material: Material,
+  channel: GLTFMaterialAnimationChannel,
+  value: number[]
+): void {
+  const pbrMaterial =
+    channel.component !== undefined
+      ? {
+          [channel.property]: updateMaterialArrayComponent(
+            getCurrentMaterialValue(material, channel.property),
+            channel.component,
+            value[0]
+          )
+        }
+      : {
+          [channel.property]: value.length === 1 ? value[0] : value
+        };
 
-function applyTranslationRotationScale(gltfNode: GLTFNodePostprocessed, node: GroupNode) {
-  node.matrix.identity();
+  material.setProps({pbrMaterial});
+}
 
-  if (gltfNode.translation) {
-    node.matrix.translate(gltfNode.translation);
-  }
+function getCurrentMaterialValue(
+  material: Material,
+  property: GLTFMaterialAnimationProperty
+): number[] {
+  const uniformValues = material.shaderInputs.getUniformValues() as Record<string, any>;
+  const currentValue = uniformValues['pbrMaterial']?.[property];
+  return Array.isArray(currentValue) ? [...currentValue] : [];
+}
 
-  if (gltfNode.rotation) {
-    const rotationMatrix = scratchMatrix.fromQuaternion(gltfNode.rotation);
-    node.matrix.multiplyRight(rotationMatrix);
+function updateMaterialArrayComponent(
+  currentValue: number[],
+  component: number,
+  nextValue: number
+): number[] {
+  const updatedValue = [...currentValue];
+  updatedValue[component] = nextValue;
+  return updatedValue;
+}
+
+function applyTextureTransformAnimationValue(
+  material: Material,
+  channel: GLTFTextureTransformAnimationChannel,
+  value: number[],
+  materialTextureTransformState: Map<
+    Material,
+    Partial<Record<PBRTextureTransformSlot, PBRTextureTransform>>
+  >
+): void {
+  const slotDefinition = getTextureTransformSlotDefinition(channel.textureSlot);
+  const currentTransform = getCurrentTextureTransform(
+    materialTextureTransformState,
+    material,
+    channel
+  );
+
+  switch (channel.path) {
+    case 'offset':
+      if (channel.component !== undefined) {
+        currentTransform.offset[channel.component] = value[0];
+      } else {
+        currentTransform.offset = [value[0], value[1]];
+      }
+      break;
+
+    case 'rotation':
+      currentTransform.rotation = value[0];
+      break;
+
+    case 'scale':
+      if (channel.component !== undefined) {
+        currentTransform.scale[channel.component] = value[0];
+      } else {
+        currentTransform.scale = [value[0], value[1]];
+      }
+      break;
   }
 
-  if (gltfNode.scale) {
-    node.matrix.scale(gltfNode.scale);
+  material.setProps({
+    pbrMaterial: {
+      [slotDefinition.uvTransformUniform]: getTextureTransformDeltaMatrix(
+        channel.baseTransform,
+        currentTransform
+      )
+    }
+  });
+}
+
+function getCurrentTextureTransform(
+  materialTextureTransformState: Map<
+    Material,
+    Partial<Record<PBRTextureTransformSlot, PBRTextureTransform>>
+  >,
+  material: Material,
+  channel: GLTFTextureTransformAnimationChannel
+): PBRTextureTransform {
+  const materialState = materialTextureTransformState.get(material) || {};
+  let textureTransformState = materialState[channel.textureSlot];
+  if (!textureTransformState) {
+    textureTransformState = {
+      offset: [...channel.baseTransform.offset] as [number, number],
+      rotation: channel.baseTransform.rotation,
+      scale: [...channel.baseTransform.scale] as [number, number]
+    };
+    materialState[channel.textureSlot] = textureTransformState;
+    materialTextureTransformState.set(material, materialState);
   }
+
+  return textureTransformState;
 }

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

@@ -0,0 +1,226 @@
+// 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: 'parsed-and-wired',
+    comment:
+      'Selected node TRS, material factor, and KHR_texture_transform offset/rotation/scale pointers are wired to runtime updates; unsupported targets are skipped.'
+  },
+  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' ||
+            extensionSupportDefinition.supportLevel === 'parsed-and-wired',
+          supportLevel: extensionSupportDefinition.supportLevel,
+          comment: extensionSupportDefinition.comment
+        }
+      ];
+    }
+  );
+
+  return new Map(extensionSupportEntries);
+}
+
+export function getRegisteredGLTFExtensionSupport(
+  extensionName: string
+): GLTFExtensionSupportDefinition | null {
+  return GLTF_EXTENSION_SUPPORT_REGISTRY[extensionName] || null;
+}
+
+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,8 +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';