@loaders.gl/gltf 4.0.0-alpha.6 → 4.0.0-alpha.8

package/src/lib/parsers/parse-glb.ts

@@ -4,24 +4,29 @@
 import type {GLB} from '../types/glb-types';
 import {padToNBytes, assert} from '@loaders.gl/loader-utils';
 
-export type GLBParseOptions = {
+/** Options for parsing a GLB */
+export type ParseGLBOptions = {
+  /** @deprecated This option was used by XVIZ protocol to define a non-standard magic number */
   magic?: number;
+  /** @deprecated This option was used by XVIZ protocol to embed non-standard chunks */
   strict?: boolean;
 };
 
-const MAGIC_glTF = 0x676c5446; // glTF in Big-Endian ASCII
+/** Binary GLTF is little endian. */
+const LITTLE_ENDIAN = true;
 
+/** 'glTF' in Big-Endian ASCII */
+const MAGIC_glTF = 0x676c5446;
 const GLB_FILE_HEADER_SIZE = 12;
 const GLB_CHUNK_HEADER_SIZE = 8;
-
 const GLB_CHUNK_TYPE_JSON = 0x4e4f534a;
 const GLB_CHUNK_TYPE_BIN = 0x004e4942;
-const GLB_CHUNK_TYPE_JSON_XVIZ_DEPRECATED = 0; // DEPRECATED - Backward compatibility for old xviz files
-const GLB_CHUNK_TYPE_BIX_XVIZ_DEPRECATED = 1; // DEPRECATED - Backward compatibility for old xviz files
-
 const GLB_V1_CONTENT_FORMAT_JSON = 0x0;
 
-const LE = true; // Binary GLTF is little endian.
+/** @deprecated - Backward compatibility for old xviz files */
+const GLB_CHUNK_TYPE_JSON_XVIZ_DEPRECATED = 0;
+/** @deprecated - Backward compatibility for old xviz files */
+const GLB_CHUNK_TYPE_BIX_XVIZ_DEPRECATED = 1;
 
 function getMagicString(dataView, byteOffset = 0) {
   return `\
@@ -31,11 +36,11 @@ ${String.fromCharCode(dataView.getUint8(byteOffset + 2))}\
 ${String.fromCharCode(dataView.getUint8(byteOffset + 3))}`;
 }
 
-// Check if a data view is a GLB
+/** Check if the contents of an array buffer contains GLB byte markers */
 export function isGLB(
   arrayBuffer: ArrayBuffer,
   byteOffset: number = 0,
-  options: GLBParseOptions = {}
+  options: ParseGLBOptions = {}
 ): boolean {
   const dataView = new DataView(arrayBuffer);
   // Check that GLB Header starts with the magic number
@@ -44,19 +49,27 @@ export function isGLB(
   return magic1 === magic || magic1 === MAGIC_glTF;
 }
 
-export default function parseGLBSync(
+/**
+ * Synchronously parse a GLB
+ * @param glb - Target, Output is stored there
+ * @param arrayBuffer - Input data
+ * @param byteOffset - Offset into arrayBuffer to start parsing from (for "embedded" GLBs, e.g. in 3D tiles)
+ * @param options
+ * @returns
+ */
+export function parseGLBSync(
   glb: GLB,
   arrayBuffer: ArrayBuffer,
   byteOffset: number = 0,
-  options: GLBParseOptions = {}
+  options: ParseGLBOptions = {}
 ) {
   // Check that GLB Header starts with the magic number
   const dataView = new DataView(arrayBuffer);
 
   // Compare format with GLBLoader documentation
   const type = getMagicString(dataView, byteOffset + 0);
-  const version = dataView.getUint32(byteOffset + 4, LE); // Version 2 of binary glTF container format
-  const byteLength = dataView.getUint32(byteOffset + 8, LE); // Total byte length of binary file
+  const version = dataView.getUint32(byteOffset + 4, LITTLE_ENDIAN); // Version 2 of binary glTF container format
+  const byteLength = dataView.getUint32(byteOffset + 8, LITTLE_ENDIAN); // Total byte length of binary file
 
   Object.assign(glb, {
     // Put less important stuff in a header, to avoid clutter
@@ -77,24 +90,29 @@ export default function parseGLBSync(
 
   switch (glb.version) {
     case 1:
-      // eslint-disable-next-line
       return parseGLBV1(glb, dataView, byteOffset);
     case 2:
-      // eslint-disable-next-line
       return parseGLBV2(glb, dataView, byteOffset, (options = {}));
     default:
-      throw new Error(`Invalid GLB version ${glb.version}. Only supports v1 and v2.`);
+      throw new Error(`Invalid GLB version ${glb.version}. Only supports version 1 and 2.`);
   }
 }
 
+/**
+ * Parse a V1 GLB
+ * @param glb - target, output is stored in this object
+ * @param dataView - Input, memory to be parsed
+ * @param byteOffset - Offset of first byte of GLB data in the data view
+ * @returns Number of bytes parsed (there could be additional non-GLB data after the GLB)
+ */
 function parseGLBV1(glb: GLB, dataView: DataView, byteOffset: number): number {
   // Sanity: ensure file is big enough to hold at least the headers
   assert(glb.header.byteLength > GLB_FILE_HEADER_SIZE + GLB_CHUNK_HEADER_SIZE);
 
   // Explanation of GLB structure:
   // https://cloud.githubusercontent.com/assets/3479527/22600725/36b87122-ea55-11e6-9d40-6fd42819fcab.png
-  const contentLength = dataView.getUint32(byteOffset + 0, LE); // Byte length of chunk
-  const contentFormat = dataView.getUint32(byteOffset + 4, LE); // Chunk format as uint32
+  const contentLength = dataView.getUint32(byteOffset + 0, LITTLE_ENDIAN); // Byte length of chunk
+  const contentFormat = dataView.getUint32(byteOffset + 4, LITTLE_ENDIAN); // Chunk format as uint32
   byteOffset += GLB_CHUNK_HEADER_SIZE;
 
   // GLB v1 only supports a single chunk type
@@ -108,11 +126,18 @@ function parseGLBV1(glb: GLB, dataView: DataView, byteOffset: number): number {
   return byteOffset;
 }
 
+/**
+ * Parse a V2 GLB
+ * @param glb - target, output is stored in this object
+ * @param dataView - Input, memory to be parsed
+ * @param byteOffset - Offset of first byte of GLB data in the data view
+ * @returns Number of bytes parsed (there could be additional non-GLB data after the GLB)
+ */
 function parseGLBV2(
   glb: GLB,
   dataView: DataView,
   byteOffset: number,
-  options: GLBParseOptions
+  options: ParseGLBOptions
 ): number {
   // Sanity: ensure file is big enough to hold at least the first chunk header
   assert(glb.header.byteLength > GLB_FILE_HEADER_SIZE + GLB_CHUNK_HEADER_SIZE);
@@ -122,17 +147,18 @@ function parseGLBV2(
   return byteOffset + glb.header.byteLength;
 }
 
+/** Iterate over GLB chunks and parse them */
 function parseGLBChunksSync(
   glb: GLB,
   dataView: DataView,
   byteOffset: number,
-  options: GLBParseOptions
+  options: ParseGLBOptions
 ) {
   // Per spec we must iterate over chunks, ignoring all except JSON and BIN
   // Iterate as long as there is space left for another chunk header
   while (byteOffset + 8 <= glb.header.byteLength) {
-    const chunkLength = dataView.getUint32(byteOffset + 0, LE); // Byte length of chunk
-    const chunkFormat = dataView.getUint32(byteOffset + 4, LE); // Chunk format as uint32
+    const chunkLength = dataView.getUint32(byteOffset + 0, LITTLE_ENDIAN); // Byte length of chunk
+    const chunkFormat = dataView.getUint32(byteOffset + 4, LITTLE_ENDIAN); // Chunk format as uint32
     byteOffset += GLB_CHUNK_HEADER_SIZE;
 
     // Per spec we must iterate over chunks, ignoring all except JSON and BIN
@@ -168,7 +194,7 @@ function parseGLBChunksSync(
   return byteOffset;
 }
 
-// Parse a GLB JSON chunk
+/* Parse a GLB JSON chunk */
 function parseJSONChunk(glb: GLB, dataView: DataView, byteOffset: number, chunkLength: number) {
   // 1. Create a "view" of the binary encoded JSON data inside the GLB
   const jsonChunk = new Uint8Array(dataView.buffer, byteOffset, chunkLength);
@@ -183,7 +209,7 @@ function parseJSONChunk(glb: GLB, dataView: DataView, byteOffset: number, chunkL
   return padToNBytes(chunkLength, 4);
 }
 
-// Parse a GLB BIN chunk
+/** Parse a GLB BIN chunk */
 function parseBINChunk(glb: GLB, dataView, byteOffset, chunkLength) {
   // Note: BIN chunk can be optional
   glb.header.hasBinChunk = true;

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

@@ -1,34 +1,35 @@
 /* eslint-disable camelcase, max-statements, no-restricted-globals */
 import type {LoaderContext} from '@loaders.gl/loader-utils';
-import {BasisLoader, selectSupportedBasisFormat} from '@loaders.gl/textures';
 import type {GLTFLoaderOptions} from '../../gltf-loader';
-import type {GLB} from '../types/glb-types';
 import type {GLTFWithBuffers} from '../types/gltf-types';
+import type {GLB} from '../types/glb-types';
+import type {ParseGLBOptions} from './parse-glb';
 
-import {ImageLoader} from '@loaders.gl/images';
 import {parseJSON, sliceArrayBuffer} from '@loaders.gl/loader-utils';
+import {ImageLoader} from '@loaders.gl/images';
+import {BasisLoader, selectSupportedBasisFormat} from '@loaders.gl/textures';
+
 import {assert} from '../utils/assert';
+import {isGLB, parseGLBSync} from './parse-glb';
 import {resolveUrl} from '../gltf-utils/resolve-url';
 import {getTypedArrayForBufferView} from '../gltf-utils/get-typed-array';
 import {preprocessExtensions, decodeExtensions} from '../api/gltf-extensions';
 import {normalizeGLTFV1} from '../api/normalize-gltf-v1';
-import {postProcessGLTF} from '../api/post-process-gltf';
-import parseGLBSync, {isGLB} from './parse-glb';
 
-export type GLTFParseOptions = {
+/**  */
+export type ParseGLTFOptions = ParseGLBOptions & {
   normalize?: boolean;
   loadImages?: boolean;
   loadBuffers?: boolean;
   decompressMeshes?: boolean;
-  postProcess?: boolean;
   excludeExtensions?: string[];
-};
 
-// export type GLTFOptions = {
-//   gltf?: GLTFParseOptions;
-// };
+  /** @deprecated not supported in v4. `postProcessGLTF()` must be called by the application */
+  postProcess?: false;
+};
 
-export function isGLTF(arrayBuffer, options?): boolean {
+/** Check if an array buffer appears to contain GLTF data */
+export function isGLTF(arrayBuffer: ArrayBuffer, options?: ParseGLTFOptions): boolean {
   const byteOffset = 0;
   return isGLB(arrayBuffer, byteOffset, options);
 }
@@ -39,36 +40,36 @@ export async function parseGLTF(
   byteOffset = 0,
   options: GLTFLoaderOptions,
   context: LoaderContext
-) {
+): Promise<GLTFWithBuffers> {
   parseGLTFContainerSync(gltf, arrayBufferOrString, byteOffset, options);
 
   normalizeGLTFV1(gltf, {normalize: options?.gltf?.normalize});
 
   preprocessExtensions(gltf, options, context);
 
-  const promises: Promise<any>[] = [];
-
   // Load linked buffers asynchronously and decodes base64 buffers in parallel
   if (options?.gltf?.loadBuffers && gltf.json.buffers) {
     await loadBuffers(gltf, options, context);
   }
 
+  // loadImages and decodeExtensions should not be running in parallel, because
+  // decodeExtensions uses data from images taken during the loadImages call.
   if (options?.gltf?.loadImages) {
-    const promise = loadImages(gltf, options, context);
-    promises.push(promise);
+    await loadImages(gltf, options, context);
   }
 
-  const promise = decodeExtensions(gltf, options, context);
-  promises.push(promise);
-
-  // Parallelize image loading and buffer loading/extension decoding
-  await Promise.all(promises);
+  await decodeExtensions(gltf, options, context);
 
-  // Post processing resolves indices to objects, buffers
-  return options?.gltf?.postProcess ? postProcessGLTF(gltf, options) : gltf;
+  return gltf;
 }
 
-// `data` - can be ArrayBuffer (GLB), ArrayBuffer (Binary JSON), String (JSON), or Object (parsed JSON)
+/**
+ *
+ * @param gltf
+ * @param data - can be ArrayBuffer (GLB), ArrayBuffer (Binary JSON), String (JSON), or Object (parsed JSON)
+ * @param byteOffset
+ * @param options
+ */
 function parseGLTFContainerSync(gltf, data, byteOffset, options) {
   // Initialize gltf container
   if (options.uri) {