@loaders.gl/gltf 3.0.12 → 3.1.0-alpha.4

package/src/lib/api/gltf-extensions.ts

@@ -0,0 +1,71 @@
+/* eslint-disable camelcase */
+import {GLTF} from '../types/gltf-types';
+import type {GLTFLoaderOptions} from '../../gltf-loader';
+
+// GLTF 1.0 extensions (decode only)
+// import * as KHR_binary_gltf from './KHR_draco_mesh_compression';
+
+// GLTF 2.0 Khronos extensions (decode/encode)
+import * as EXT_meshopt_compression from '../extensions/EXT_meshopt_compression';
+import * as EXT_texture_webp from '../extensions/EXT_texture_webp';
+import * as KHR_texture_basisu from '../extensions/KHR_texture_basisu';
+import * as KHR_draco_mesh_compression from '../extensions/KHR_draco_mesh_compression';
+
+// Deprecated. These should be handled by rendering library (e.g. luma.gl), not the loader.
+import * as KHR_lights_punctual from '../extensions/deprecated/KHR_lights_punctual';
+import * as KHR_materials_unlit from '../extensions/deprecated/KHR_materials_unlit';
+import * as KHR_techniques_webgl from '../extensions/deprecated/KHR_techniques_webgl';
+
+// Vendor extensions
+
+type GLTFExtensionPlugin = {
+  name: string;
+  preprocess?: (gltfData: {json: GLTF}, options: GLTFLoaderOptions, context) => void;
+  decode?: (gltfData: {json: GLTF}, options: GLTFLoaderOptions, context) => Promise<void>;
+  encode?: (gltfData: {json: GLTF}, options: GLTFLoaderOptions) => void;
+};
+
+/**
+ * List of extensions processed by the GLTFLoader
+ * Note that may extensions can only be handled on the rendering stage and are left out here
+ * These are just extensions that can be handled fully or partially during loading.
+ */
+export const EXTENSIONS: GLTFExtensionPlugin[] = [
+  // 1.0
+  // KHR_binary_gltf is handled separately - must be processed before other parsing starts
+  // KHR_binary_gltf,
+
+  // 2.0
+  EXT_meshopt_compression,
+  EXT_texture_webp,
+  // Basisu should come after webp, we want basisu to be preferred if both are provided
+  KHR_texture_basisu,
+  KHR_draco_mesh_compression,
+  KHR_lights_punctual,
+  KHR_materials_unlit,
+  KHR_techniques_webgl
+];
+
+/** Call before any resource loading starts */
+export function preprocessExtensions(gltf, options: GLTFLoaderOptions = {}, context?) {
+  const extensions = EXTENSIONS.filter((extension) => useExtension(extension.name, options));
+  for (const extension of extensions) {
+    extension.preprocess?.(gltf, options, context);
+  }
+}
+
+/** Call after resource loading */
+export async function decodeExtensions(gltf, options: GLTFLoaderOptions = {}, context?) {
+  const extensions = EXTENSIONS.filter((extension) => useExtension(extension.name, options));
+  for (const extension of extensions) {
+    // Note: We decode async extensions sequentially, this might not be necessary
+    // Currently we only have Draco, but when we add Basis we may revisit
+    await extension.decode?.(gltf, options, context);
+  }
+}
+
+function useExtension(extensionName: string, options: GLTFLoaderOptions) {
+  const excludes = options?.gltf?.excludeExtensions || {};
+  const exclude = extensionName in excludes && !excludes[extensionName];
+  return !exclude;
+}

package/src/lib/api/gltf-scenegraph.ts

@@ -36,6 +36,7 @@ const DEFAULT_GLTF_JSON: GLTF = {
   buffers: []
 };
 
+type Extension = {[key: string]: any};
 /**
  * Class for structured access to GLTF data
  */
@@ -79,13 +80,13 @@ export default class GLTFScenegraph {
     return extras[key];
   }
 
-  getExtension(extensionName: string): {[key: string]: any} | null {
+  getExtension<T = Extension>(extensionName: string): T | null {
     const isExtension = this.getUsedExtensions().find((name) => name === extensionName);
     const extensions = this.json.extensions || {};
     return isExtension ? extensions[extensionName] || true : null;
   }
 
-  getRequiredExtension(extensionName: string): {[key: string]: any} | null {
+  getRequiredExtension<T = Extension>(extensionName: string): T | null {
     const isRequired = this.getRequiredExtensions().find((name) => name === extensionName);
     return isRequired ? this.getExtension(extensionName) : null;
   }
@@ -98,10 +99,7 @@ export default class GLTFScenegraph {
     return this.json.extensionsUsed || [];
   }
 
-  getObjectExtension(
-    object: {[key: string]: any},
-    extensionName: string
-  ): {[key: string]: any} | null {
+  getObjectExtension<T = Extension>(object: {[key: string]: any}, extensionName: string): T | null {
     const extensions = object.extensions || {};
     return extensions[extensionName];
   }

package/src/lib/api/normalize-gltf-v1.js

@@ -139,7 +139,8 @@ class GLTFV1Normalizer {
 
     // Extract bufferView indices for images
     // (this extension needs to be invoked early in the normalization process)
-    KHR_binary_glTF.decode(gltf);
+    // TODO can this be handled by standard extension processing instead of called explicitly?
+    KHR_binary_glTF.preprocess(gltf);
 
     // Convert object references from ids to indices
     this._convertObjectIdsToArrayIndices(json);

package/src/lib/extensions/EXT_meshopt_compression.ts

@@ -1,19 +1,9 @@
 /* eslint-disable camelcase */
+import type {GLTF, GLTFBufferView, GLTF_EXT_meshopt_compression} from '../types/gltf-types';
 import type {GLTFLoaderOptions} from '../../gltf-loader';
 import GLTFScenegraph from '../api/gltf-scenegraph';
-import {EXT_MESHOPT_COMPRESSION} from '../gltf-utils/gltf-constants';
 import {isMeshoptSupported, meshoptDecodeGltfBuffer} from '../../meshopt/meshopt-decoder';
 
-type GLTF_EXT_meshopt_compression = {
-  buffer: number;
-  byteOffset?: number;
-  byteLength: number;
-  byteStride: number;
-  count: number;
-  mode: 'ATTRIBUTES' | 'TRIANGLES' | 'INDICES';
-  filter?: 'NONE' | 'OCTAHEDRAL' | 'QUATERNION' | 'EXPONENTIAL';
-};
-
 // @ts-ignore
 // eslint-disable-next-line
 const DEFAULT_MESHOPT_OPTIONS = {
@@ -21,34 +11,51 @@ const DEFAULT_MESHOPT_OPTIONS = {
   filter: 'NONE'
 };
 
-// Note: We have a "soft dependency" on DracoWriter to avoid bundling it when not needed
-export async function decode(gltfData, options: GLTFLoaderOptions) {
-  if (!options?.gltf?.decompressMeshes || !isMeshoptSupported()) {
+/** Extension name */
+const EXT_MESHOPT_COMPRESSION = 'EXT_meshopt_compression';
+
+export const name = EXT_MESHOPT_COMPRESSION;
+
+export function preprocess(gltfData: {json: GLTF}) {
+  const scenegraph = new GLTFScenegraph(gltfData);
+  if (
+    scenegraph.getRequiredExtensions().includes(EXT_MESHOPT_COMPRESSION) &&
+    !isMeshoptSupported()
+  ) {
+    throw new Error(`gltf: Required extension ${EXT_MESHOPT_COMPRESSION} not supported by browser`);
+  }
+}
+
+export async function decode(gltfData: {json: GLTF}, options: GLTFLoaderOptions) {
+  const scenegraph = new GLTFScenegraph(gltfData);
+
+  if (!options?.gltf?.decompressMeshes) {
     return;
   }
 
   const promises: Promise<any>[] = [];
   for (const bufferViewIndex of gltfData.json.bufferViews || []) {
-    promises.push(decodeMeshoptBufferView(gltfData.json, bufferViewIndex));
+    promises.push(decodeMeshoptBufferView(scenegraph, bufferViewIndex));
   }
 
   // Decompress meshes in parallel
   await Promise.all(promises);
 
   // We have now decompressed all primitives, so remove the top-level extensions
-  const scenegraph = new GLTFScenegraph(gltfData);
   scenegraph.removeExtension(EXT_MESHOPT_COMPRESSION);
 }
 
 /** Decode one meshopt buffer view */
-async function decodeMeshoptBufferView(json, index: number): Promise<ArrayBuffer | null> {
-  const bufferView = json.bufferViews[index];
-
-  const meshoptExtension =
-    bufferView.extensions &&
-    (bufferView.extensions[EXT_MESHOPT_COMPRESSION] as GLTF_EXT_meshopt_compression);
+async function decodeMeshoptBufferView(
+  scenegraph: GLTFScenegraph,
+  bufferView: GLTFBufferView
+): Promise<ArrayBuffer | null> {
+  const meshoptExtension = scenegraph.getObjectExtension<GLTF_EXT_meshopt_compression>(
+    bufferView,
+    EXT_MESHOPT_COMPRESSION
+  );
   if (meshoptExtension) {
-    const buffer = json.buffers[meshoptExtension.buffer];
+    const buffer = bufferView.buffer;
 
     const {
       byteOffset = 0,
@@ -58,6 +65,8 @@ async function decodeMeshoptBufferView(json, index: number): Promise<ArrayBuffer
       mode,
       filter = 'NONE'
     } = meshoptExtension;
+
+    // @ts-expect-error TODO - fix buffer handling
     const source = new Uint8Array(buffer, byteOffset, byteLength);
     const result = new ArrayBuffer(count * byteStride);
     await meshoptDecodeGltfBuffer(new Uint8Array(result), count, byteStride, source, mode, filter);

package/src/lib/extensions/EXT_texture_webp.ts

@@ -0,0 +1,45 @@
+// GLTF EXTENSION: EXT_TEXTURE_WEBP
+// https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Khronos/EXT_TEXTURE_WEBP
+/* eslint-disable camelcase */
+
+import type {GLTF, GLTF_EXT_texture_webp} from '../types/gltf-types';
+import type {GLTFLoaderOptions} from '../../gltf-loader';
+
+import {_isImageFormatSupported} from '@loaders.gl/images';
+import GLTFScenegraph from '../api/gltf-scenegraph';
+
+const EXT_TEXTURE_WEBP = 'EXT_texture_webp';
+
+/** Extension name */
+export const name = EXT_TEXTURE_WEBP;
+
+/**
+ * Replaces a texture source reference with the extension texture
+ * Done in preprocess() to prevent load of default image
+ */
+export function preprocess(gltfData: {json: GLTF}, options: GLTFLoaderOptions): void {
+  const scenegraph = new GLTFScenegraph(gltfData);
+
+  if (!_isImageFormatSupported('image/webp')) {
+    if (scenegraph.getRequiredExtensions().includes(EXT_TEXTURE_WEBP)) {
+      throw new Error(`gltf: Required extension ${EXT_TEXTURE_WEBP} not supported by browser`);
+    }
+    return;
+  }
+
+  const {json} = scenegraph;
+
+  for (const texture of json.textures || []) {
+    const extension = scenegraph.getObjectExtension<GLTF_EXT_texture_webp>(
+      texture,
+      EXT_TEXTURE_WEBP
+    );
+    if (extension) {
+      texture.source = extension.source;
+    }
+    scenegraph.removeObjectExtension(texture, EXT_TEXTURE_WEBP);
+  }
+
+  // Remove the top-level extension
+  scenegraph.removeExtension(EXT_TEXTURE_WEBP);
+}

package/src/lib/extensions/KHR_binary_gltf.ts

@@ -1,12 +1,17 @@
 // GLTF 1.0 EXTENSION: KHR_binary_glTF
 // https://github.com/KhronosGroup/glTF/tree/master/extensions/1.0/Khronos/KHR_binary_glTF
+/* eslint-disable camelcase */
 
-import type {GLTF} from '../types/gltf-types';
+import type {GLTF, GLTF_KHR_binary_glTF} from '../types/gltf-types';
 
 import GLTFScenegraph from '../api/gltf-scenegraph';
-import {KHR_BINARY_GLTF} from '../gltf-utils/gltf-constants';
 
-export function decode(gltfData: {json: GLTF}): void {
+const KHR_BINARY_GLTF = 'KHR_binary_glTF';
+
+/** Extension name */
+export const name = KHR_BINARY_GLTF;
+
+export function preprocess(gltfData: {json: GLTF}): void {
   const gltfScenegraph = new GLTFScenegraph(gltfData);
   const {json} = gltfScenegraph;
 
@@ -15,15 +20,19 @@ export function decode(gltfData: {json: GLTF}): void {
 
   // Image and shader nodes can have the extension
   // https://github.com/KhronosGroup/glTF/blob/master/extensions/1.0/Khronos/KHR_binary_glTF/schema/image.KHR_binary_glTF.schema.json
-  for (const node of json.images || []) {
-    const extension = gltfScenegraph.removeObjectExtension(node, KHR_BINARY_GLTF);
+  for (const image of json.images || []) {
+    const extension = gltfScenegraph.getObjectExtension<GLTF_KHR_binary_glTF>(
+      image,
+      KHR_BINARY_GLTF
+    );
     // The data in the extension is valid as glTF 2.0 data inside the object, so just copy it in
     if (extension) {
-      Object.assign(node, extension);
+      Object.assign(image, extension);
     }
+    gltfScenegraph.removeObjectExtension(image, KHR_BINARY_GLTF);
   }
 
-  // TODO shaders
+  // TODO shaders - At least traverse and throw error if used?
   // https://github.com/KhronosGroup/glTF/blob/master/extensions/1.0/Khronos/KHR_binary_glTF/schema/shader.KHR_binary_glTF.schema.json
 
   // glTF v1 one files have a partially formed URI field that is not expected in (and causes problems in) 2.0
@@ -36,6 +45,6 @@ export function decode(gltfData: {json: GLTF}): void {
 }
 
 // KHR_binary_gltf is a 1.0 extension that is supported natively by 2.0
-export function encode() {
-  throw new Error(KHR_BINARY_GLTF);
-}
+// export function encode() {
+//   throw new Error(KHR_BINARY_GLTF);
+// }

package/src/lib/extensions/KHR_draco_mesh_compression.ts

@@ -1,19 +1,41 @@
 // https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Khronos/KHR_draco_mesh_compression
 // Only TRIANGLES: 0x0004 and TRIANGLE_STRIP: 0x0005 are supported
+/* eslint-disable camelcase */
 
 /* eslint-disable camelcase */
-import type {GLTF, GLTFAccessor, GLTFMeshPrimitive} from '../types/gltf-types';
+import type {
+  GLTF,
+  GLTFAccessor,
+  GLTFMeshPrimitive,
+  GLTF_KHR_draco_mesh_compression
+} from '../types/gltf-types';
 import type {GLTFLoaderOptions} from '../../gltf-loader';
 
 import type {LoaderContext} from '@loaders.gl/loader-utils';
 import {DracoLoader} from '@loaders.gl/draco';
-import {DracoLoaderOptions, DracoMeshData} from '@loaders.gl/draco';
+import {DracoLoaderOptions, DracoMesh} from '@loaders.gl/draco';
 import {sliceArrayBuffer} from '@loaders.gl/loader-utils';
 import {default as Scenegraph} from '../api/gltf-scenegraph';
-import {KHR_DRACO_MESH_COMPRESSION} from '../gltf-utils/gltf-constants';
 import {getGLTFAccessors, getGLTFAccessor} from '../gltf-utils/gltf-attribute-utils';
 
-// Note: We have a "soft dependency" on DracoWriter to avoid bundling it when not needed
+const KHR_DRACO_MESH_COMPRESSION = 'KHR_draco_mesh_compression';
+
+/** Extension name */
+export const name = KHR_DRACO_MESH_COMPRESSION;
+
+export function preprocess(
+  gltfData: {json: GLTF},
+  options: GLTFLoaderOptions,
+  context: LoaderContext
+): void {
+  const scenegraph = new Scenegraph(gltfData);
+  for (const primitive of makeMeshPrimitiveIterator(scenegraph)) {
+    if (scenegraph.getObjectExtension(primitive, KHR_DRACO_MESH_COMPRESSION)) {
+      // TODO - Remove fallback accessors to make sure we don't load unnecessary buffers
+    }
+  }
+}
+
 export async function decode(
   gltfData: {json: GLTF},
   options: GLTFLoaderOptions,
@@ -64,7 +86,10 @@ async function decompressPrimitive(
   options: GLTFLoaderOptions,
   context: LoaderContext
 ): Promise<void> {
-  const dracoExtension = scenegraph.getObjectExtension(primitive, KHR_DRACO_MESH_COMPRESSION);
+  const dracoExtension = scenegraph.getObjectExtension<GLTF_KHR_draco_mesh_compression>(
+    primitive,
+    KHR_DRACO_MESH_COMPRESSION
+  );
   if (!dracoExtension) {
     return;
   }
@@ -79,12 +104,7 @@ async function decompressPrimitive(
 
   // TODO - remove hack: The entire tileset might be included, too expensive to serialize
   delete dracoOptions['3d-tiles'];
-  const decodedData = (await parse(
-    bufferCopy,
-    DracoLoader,
-    dracoOptions,
-    context
-  )) as DracoMeshData;
+  const decodedData = (await parse(bufferCopy, DracoLoader, dracoOptions, context)) as DracoMesh;
 
   const decodedAttributes: {[key: string]: GLTFAccessor} = getGLTFAccessors(decodedData.attributes);
 

package/src/lib/extensions/KHR_texture_basisu.ts

@@ -0,0 +1,36 @@
+// GLTF EXTENSION: EXT_TEXTURE_WEBP
+// https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Khronos/EXT_TEXTURE_WEBP
+/* eslint-disable camelcase */
+
+import type {GLTF, GLTF_KHR_texture_basisu} from '../types/gltf-types';
+import type {GLTFLoaderOptions} from '../../gltf-loader';
+
+import GLTFScenegraph from '../api/gltf-scenegraph';
+
+const KHR_TEXTURE_BASISU = 'KHR_texture_basisu';
+
+/** Extension name */
+export const name = KHR_TEXTURE_BASISU;
+
+/**
+ * Replaces a texture source reference with the extension texture
+ * Done in preprocess() to prevent load of default image
+ */
+export function preprocess(gltfData: {json: GLTF}, options: GLTFLoaderOptions): void {
+  const scene = new GLTFScenegraph(gltfData);
+  const {json} = scene;
+
+  for (const texture of json.textures || []) {
+    const extension = scene.getObjectExtension<GLTF_KHR_texture_basisu>(
+      texture,
+      KHR_TEXTURE_BASISU
+    );
+    if (extension) {
+      texture.source = extension.source;
+    }
+    scene.removeObjectExtension(texture, KHR_TEXTURE_BASISU);
+  }
+
+  // Remove the top-level extension
+  scene.removeExtension(KHR_TEXTURE_BASISU);
+}

package/src/lib/extensions/{KHR_lights_punctual.ts → deprecated/KHR_lights_punctual.ts}

@@ -1,11 +1,14 @@
 // GLTF EXTENSION: KHR_lights_punctual
 // https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Khronos/KHR_lights_punctual
 
-import type {GLTF} from '../types/gltf-types';
+import type {GLTF} from '../../types/gltf-types';
 
-import {assert} from '../utils/assert';
-import GLTFScenegraph from '../api/gltf-scenegraph';
-import {KHR_LIGHTS_PUNCTUAL} from '../gltf-utils/gltf-constants';
+import {assert} from '../../utils/assert';
+import GLTFScenegraph from '../../api/gltf-scenegraph';
+
+const KHR_LIGHTS_PUNCTUAL = 'KHR_lights_punctual';
+
+export const name = KHR_LIGHTS_PUNCTUAL;
 
 export async function decode(gltfData: {json: GLTF}): Promise<void> {
   const gltfScenegraph = new GLTFScenegraph(gltfData);

package/src/lib/extensions/{KHR_materials_unlit.ts → deprecated/KHR_materials_unlit.ts}

@@ -1,10 +1,13 @@
 // GLTF EXTENSION: KHR_materials_unlit
 // https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Khronos/KHR_materials_unlit
 
-import type {GLTF} from '../types/gltf-types';
+import type {GLTF} from '../../types/gltf-types';
 
-import GLTFScenegraph from '../api/gltf-scenegraph';
-import {KHR_MATERIALS_UNLIT} from '../gltf-utils/gltf-constants';
+import GLTFScenegraph from '../../api/gltf-scenegraph';
+
+const KHR_MATERIALS_UNLIT = 'KHR_materials_unlit';
+
+export const name = KHR_MATERIALS_UNLIT;
 
 export async function decode(gltfData: {json: GLTF}): Promise<void> {
   const gltfScenegraph = new GLTFScenegraph(gltfData);