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

package/src/parsers/parse-pbr-material.ts

@@ -2,11 +2,11 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {Device, Texture} from '@luma.gl/core';
+import type {Device, SamplerProps, TextureFormat, TypedArray} from '@luma.gl/core';
+import {Texture, log, textureFormatDecoder} from '@luma.gl/core';
 import type {GLTFSampler} from '@loaders.gl/gltf';
 import {GL} from '@luma.gl/constants';
 
-import {log} from '@luma.gl/core';
 import {type ParsedPBRMaterial} from '../pbr/pbr-material';
 import {type PBREnvironment} from '../pbr/pbr-environment';
 import {type PBRMaterialBindings} from '@luma.gl/shadertools';
@@ -107,6 +107,7 @@ export function parsePBRMaterial(
   if (attributes['NORMAL']) parsedMaterial.defines['HAS_NORMALS'] = true;
   if (attributes['TANGENT'] && options?.useTangents) parsedMaterial.defines['HAS_TANGENTS'] = true;
   if (attributes['TEXCOORD_0']) parsedMaterial.defines['HAS_UV'] = true;
+  if (attributes['JOINTS_0'] && attributes['WEIGHTS_0']) parsedMaterial.defines['HAS_SKIN'] = true;
   if (attributes['COLOR_0']) parsedMaterial.defines['HAS_COLORS'] = true;
 
   if (options?.imageBasedLightingEnvironment) parsedMaterial.defines['USE_IBL'] = true;
@@ -239,14 +240,6 @@ function addTexture(
   parsedMaterial: ParsedPBRMaterial
 ): void {
   const image = gltfTexture.texture.source.image;
-  let textureOptions;
-
-  if (image.compressed) {
-    textureOptions = image;
-  } else {
-    // Texture2D accepts a promise that returns an image as data (Async Textures)
-    textureOptions = {data: image};
-  }
 
   const gltfSampler = {
     wrapS: 10497, // default REPEAT S (U) wrapping mode.
@@ -256,17 +249,214 @@ function addTexture(
     ...gltfTexture?.texture?.sampler
   } as GLTFSampler;
 
-  const texture: Texture = device.createTexture({
+  const baseOptions = {
     id: gltfTexture.uniformName || gltfTexture.id,
-    sampler: convertSampler(gltfSampler),
-    ...textureOptions
-  });
+    sampler: convertSampler(gltfSampler)
+  };
+
+  let texture: Texture;
+
+  if (image.compressed) {
+    texture = createCompressedTexture(device, image, baseOptions);
+  } else {
+    const {width, height} = device.getExternalImageSize(image);
+    texture = device.createTexture({
+      ...baseOptions,
+      width,
+      height,
+      data: image
+    });
+  }
 
   parsedMaterial.bindings[uniformName] = texture;
   if (define) parsedMaterial.defines[define] = true;
   parsedMaterial.generatedTextures.push(texture);
 }
 
+/** One mip level as produced by loaders.gl compressed texture parsers */
+export type CompressedMipLevel = {
+  data: TypedArray;
+  width: number;
+  height: number;
+  textureFormat?: TextureFormat;
+};
+
+/**
+ * Compressed image from current loaders.gl releases.
+ * - `mipmaps` is a boolean (true), NOT an array
+ * - `data` is an Array of TextureLevel-like objects
+ * - Per-level `textureFormat` is already a luma.gl TextureFormat
+ * - Top-level `width`/`height` may be undefined
+ */
+export type CompressedImageDataArray = {
+  compressed: true;
+  mipmaps?: boolean;
+  width?: number;
+  height?: number;
+  data: CompressedMipLevel[];
+};
+
+/**
+ * Hypothetical future format where `mipmaps` is an actual array.
+ * Kept for forward compatibility.
+ */
+export type CompressedImageMipmapArray = {
+  compressed: true;
+  width?: number;
+  height?: number;
+  mipmaps: CompressedMipLevel[];
+};
+
+/** Union of all known loaders.gl compressed image shapes */
+export type CompressedImage = CompressedImageDataArray | CompressedImageMipmapArray;
+
+function createCompressedTextureFallback(
+  device: Device,
+  baseOptions: {id: string; sampler: SamplerProps}
+): Texture {
+  return device.createTexture({
+    ...baseOptions,
+    format: 'rgba8unorm',
+    width: 1,
+    height: 1,
+    mipLevels: 1
+  });
+}
+
+function resolveCompressedTextureFormat(level: CompressedMipLevel): TextureFormat | undefined {
+  return level.textureFormat;
+}
+
+/**
+ * Maximum mip levels that can be filled for a compressed texture.
+ * texStorage2D allocates level i at (baseW >> i) × (baseH >> i).
+ * Compressed formats can't upload data for levels smaller than one block,
+ * so we stop before either dimension drops below the block size.
+ */
+function getMaxCompressedMipLevels(
+  baseWidth: number,
+  baseHeight: number,
+  format: TextureFormat
+): number {
+  const {blockWidth = 1, blockHeight = 1} = textureFormatDecoder.getInfo(format);
+  let count = 1;
+  for (let i = 1; ; i++) {
+    const w = Math.max(1, baseWidth >> i);
+    const h = Math.max(1, baseHeight >> i);
+    if (w < blockWidth || h < blockHeight) break;
+    count++;
+  }
+  return count;
+}
+
+/**
+ * Create a texture from compressed image data produced by loaders.gl.
+ * Handles current loaders.gl compressed image layouts:
+ *
+ *   current:      {compressed, mipmaps: true, data: [{data, width, height, textureFormat}, ...]}
+ *   forward:      {compressed, mipmaps: [{data, width, height, textureFormat}, ...]}
+ */
+export function createCompressedTexture(
+  device: Device,
+  image: CompressedImage,
+  baseOptions: {id: string; sampler: SamplerProps}
+): Texture {
+  // Normalize mip levels from all known loaders.gl formats
+  let levels: CompressedMipLevel[];
+
+  if (Array.isArray((image as any).data) && (image as any).data[0]?.data) {
+    // loaders.gl current format: image.data is Array of mip-level objects
+    levels = (image as CompressedImageDataArray).data;
+  } else if ('mipmaps' in image && Array.isArray((image as CompressedImageMipmapArray).mipmaps)) {
+    // Hypothetical future format: image.mipmaps is an Array
+    levels = (image as CompressedImageMipmapArray).mipmaps;
+  } else {
+    levels = [];
+  }
+
+  if (levels.length === 0 || !levels[0]?.data) {
+    log.warn(
+      'createCompressedTexture: compressed image has no valid mip levels, creating fallback'
+    )();
+    return createCompressedTextureFallback(device, baseOptions);
+  }
+
+  const baseLevel = levels[0];
+  const baseWidth = baseLevel.width ?? (image as any).width ?? 0;
+  const baseHeight = baseLevel.height ?? (image as any).height ?? 0;
+
+  if (baseWidth <= 0 || baseHeight <= 0) {
+    log.warn('createCompressedTexture: base level has invalid dimensions, creating fallback')();
+    return createCompressedTextureFallback(device, baseOptions);
+  }
+
+  const format = resolveCompressedTextureFormat(baseLevel);
+
+  if (!format) {
+    log.warn('createCompressedTexture: compressed image has no textureFormat, creating fallback')();
+    return createCompressedTextureFallback(device, baseOptions);
+  }
+
+  // Validate mip levels: truncate chain at first invalid level.
+  // Levels must be contiguous, so we stop at the first level that has
+  // a format mismatch, missing data, non-positive dimensions, or
+  // dimensions that don't match what texStorage2D will allocate.
+  //
+  // For block-compressed formats (ASTC, BC, ETC2), texStorage2D allocates
+  // mip levels down to 1×1 texels, but compressed data can't be smaller
+  // than one block (e.g. 4×4 for ASTC-4x4). Cap the chain so we never
+  // try to upload data whose block-aligned size exceeds the allocated level.
+  const maxMipLevels = getMaxCompressedMipLevels(baseWidth, baseHeight, format);
+  const levelLimit = Math.min(levels.length, maxMipLevels);
+
+  let validLevelCount = 1;
+  for (let i = 1; i < levelLimit; i++) {
+    const level = levels[i];
+    if (!level.data || level.width <= 0 || level.height <= 0) {
+      log.warn(`createCompressedTexture: mip level ${i} has invalid data/dimensions, truncating`)();
+      break;
+    }
+    const levelFormat = resolveCompressedTextureFormat(level);
+    if (levelFormat && levelFormat !== format) {
+      log.warn(
+        `createCompressedTexture: mip level ${i} format '${levelFormat}' differs from base '${format}', truncating`
+      )();
+      break;
+    }
+    const expectedW = Math.max(1, baseWidth >> i);
+    const expectedH = Math.max(1, baseHeight >> i);
+    if (level.width !== expectedW || level.height !== expectedH) {
+      log.warn(
+        `createCompressedTexture: mip level ${i} dimensions ${level.width}x${level.height} ` +
+          `don't match expected ${expectedW}x${expectedH}, truncating`
+      )();
+      break;
+    }
+    validLevelCount++;
+  }
+
+  const texture = device.createTexture({
+    ...baseOptions,
+    format,
+    usage: Texture.TEXTURE | Texture.COPY_DST,
+    width: baseWidth,
+    height: baseHeight,
+    mipLevels: validLevelCount,
+    data: baseLevel.data
+  });
+
+  // Upload additional validated mip levels
+  for (let i = 1; i < validLevelCount; i++) {
+    texture.writeData(levels[i].data, {
+      width: levels[i].width,
+      height: levels[i].height,
+      mipLevel: i
+    });
+  }
+
+  return texture;
+}
+
 /*
 /**
  * Parses a GLTF material definition into uniforms and parameters for the PBR shader module

package/src/pbr/pbr-environment.ts

@@ -10,13 +10,19 @@ import {loadImageTexture} from '@loaders.gl/textures';
 export type PBREnvironment = {
   /** Bi-directional Reflectance Distribution Function (BRDF) lookup table */
   brdfLutTexture: DynamicTexture;
+  /** Diffuse irradiance cubemap. */
   diffuseEnvSampler: DynamicTexture;
+  /** Specular reflection cubemap with mip chain. */
   specularEnvSampler: DynamicTexture;
 };
 
+/** Configuration used to load an image-based lighting environment. */
 export type PBREnvironmentProps = {
+  /** URL of the BRDF lookup texture. */
   brdfLutUrl: string;
+  /** Callback that returns the URL for a diffuse or specular cubemap face and mip level. */
   getTexUrl: (name: string, dir: number, level: number) => string;
+  /** Number of mip levels in the specular environment map. */
   specularMipLevels?: number;
 };
 
@@ -73,6 +79,7 @@ export function loadPBREnvironment(device: Device, props: PBREnvironmentProps):
 // TODO put somewhere common
 const FACES = [0, 1, 2, 3, 4, 5];
 
+/** Construction props for an asynchronously loaded cubemap. */
 function makeCube(
   device: Device,
   {
@@ -80,8 +87,11 @@ function makeCube(
     getTextureForFace,
     sampler
   }: {
+    /** Debug id assigned to the created texture. */
     id: string;
+    /** Returns the image promise or mip-array promises for one cubemap face. */
     getTextureForFace: (dir: number) => Promise<any> | Promise<any>[];
+    /** Sampler configuration shared across faces. */
     sampler: SamplerProps;
   }
 ): DynamicTexture {

package/src/pbr/pbr-material.ts

@@ -1,10 +1,15 @@
 import type {Texture, Parameters} from '@luma.gl/core';
 import {PBRMaterialBindings, PBRMaterialUniforms, PBRProjectionProps} from '@luma.gl/shadertools';
 
+/** Material state extracted from a glTF primitive for consumption by the PBR shader module. */
 export type ParsedPBRMaterial = {
+  /** Shader defines inferred from geometry and material features. */
   readonly defines: Record<string, boolean>;
+  /** Texture and sampler bindings for the PBR shader module. */
   readonly bindings: Partial<PBRMaterialBindings>;
+  /** Uniform values for the projection and PBR shader modules. */
   readonly uniforms: Partial<PBRProjectionProps & PBRMaterialUniforms>;
+  /** Render pipeline parameters derived from the glTF material. */
   readonly parameters: Parameters;
   /** @deprecated Use parameters */
   readonly glParameters: Record<string, any>;

package/src/webgl-to-webgpu/convert-webgl-attribute.ts

@@ -5,6 +5,7 @@
 // TODO: convert in loaders.gl?
 import type {TypedArray} from '@math.gl/types';
 
+/** Maps glTF accessor type strings to their component counts. */
 export const ATTRIBUTE_TYPE_TO_COMPONENTS: Record<string, number> = {
   SCALAR: 1,
   VEC2: 2,
@@ -15,6 +16,7 @@ export const ATTRIBUTE_TYPE_TO_COMPONENTS: Record<string, number> = {
   MAT4: 16
 };
 
+/** Maps glTF accessor component-type enums to typed-array constructors. */
 export const ATTRIBUTE_COMPONENT_TYPE_TO_ARRAY: Record<number, any> = {
   5120: Int8Array,
   5121: Uint8Array,
@@ -24,16 +26,25 @@ export const ATTRIBUTE_COMPONENT_TYPE_TO_ARRAY: Record<number, any> = {
   5126: Float32Array
 };
 
+/** Minimal accessor shape required to materialize a typed array. */
 type GLTFAccessor = {
+  /** Numeric component type enum. */
   componentType: number;
+  /** Accessor type string such as `VEC3` or `SCALAR`. */
   type: string;
+  /** Number of logical elements in the accessor. */
   count: number;
-  bufferView?: {data: {buffer: ArrayBuffer; byteOffset?: number}};
+  /** Buffer view carrying the raw bytes. */
+  bufferView?: {data: {buffer: ArrayBufferLike; byteOffset?: number}};
+  /** Byte offset into the buffer view. */
   byteOffset?: number;
 };
 
+/** Converts a glTF accessor into a typed array plus its component count. */
 export function accessorToTypedArray(accessor: GLTFAccessor): {
+  /** Typed array view over the accessor data. */
   typedArray: TypedArray;
+  /** Number of scalar components per element. */
   components: number;
 } {
   const ArrayType = ATTRIBUTE_COMPONENT_TYPE_TO_ARRAY[accessor.componentType];

package/src/webgl-to-webgpu/convert-webgl-sampler.ts

@@ -7,10 +7,15 @@
 import type {SamplerProps} from '@luma.gl/core';
 import {GL} from '@luma.gl/constants';
 
+/** Minimal glTF sampler representation used during conversion. */
 type GLTFSampler = {
+  /** Horizontal wrap mode. */
   wrapS?: GL.CLAMP_TO_EDGE | GL.REPEAT | GL.MIRRORED_REPEAT;
+  /** Vertical wrap mode. */
   wrapT?: GL.CLAMP_TO_EDGE | GL.REPEAT | GL.MIRRORED_REPEAT;
+  /** Magnification filter. */
   magFilter?: GL.NEAREST | GL.LINEAR;
+  /** Minification and mip filter combination. */
   minFilter?:
     | GL.NEAREST
     | GL.LINEAR
@@ -20,6 +25,7 @@ type GLTFSampler = {
     | GL.LINEAR_MIPMAP_LINEAR;
 };
 
+/** Converts a glTF sampler into luma.gl sampler props. */
 export function convertSampler(gltfSampler: GLTFSampler): SamplerProps {
   return {
     addressModeU: convertSamplerWrapMode(gltfSampler.wrapS),
@@ -29,6 +35,7 @@ export function convertSampler(gltfSampler: GLTFSampler): SamplerProps {
   };
 }
 
+/** Converts a glTF wrap enum into a luma.gl address mode. */
 function convertSamplerWrapMode(
   mode: GL.CLAMP_TO_EDGE | GL.REPEAT | GL.MIRRORED_REPEAT | undefined
 ): 'clamp-to-edge' | 'repeat' | 'mirror-repeat' | undefined {
@@ -44,6 +51,7 @@ function convertSamplerWrapMode(
   }
 }
 
+/** Converts a glTF mag filter enum into a luma.gl mag filter. */
 function convertSamplerMagFilter(
   mode: GL.NEAREST | GL.LINEAR | undefined
 ): 'nearest' | 'linear' | undefined {
@@ -57,6 +65,7 @@ function convertSamplerMagFilter(
   }
 }
 
+/** Converts a glTF min filter enum into luma.gl minification and mipmap filters. */
 function convertSamplerMinFilter(
   mode:
     | GL.NEAREST

package/src/webgl-to-webgpu/convert-webgl-topology.ts

@@ -8,6 +8,7 @@ import {PrimitiveTopology} from '@luma.gl/core';
 // `@luma.gl/constants`. Locally we use `GLEnum` instead of `GL` to avoid
 // conflicts with the `babel-plugin-inline-webgl-constants` plugin.
 // eslint-disable-next-line no-shadow
+/** Minimal WebGL draw-mode enum subset used by the glTF converter. */
 export enum GLEnum {
   POINTS = 0x0,
   LINES = 0x1,
@@ -18,6 +19,7 @@ export enum GLEnum {
   TRIANGLE_FAN = 0x6
 }
 
+/** Converts a WebGL draw mode into a luma.gl primitive topology string. */
 export function convertGLDrawModeToTopology(
   drawMode:
     | GLEnum.POINTS

package/dist/utils/deep-copy.d.ts

@@ -1,3 +0,0 @@
-/** Deeply copies a JS data structure */
-export declare function deepCopy(object: any): any;
-//# sourceMappingURL=deep-copy.d.ts.map

package/dist/utils/deep-copy.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"deep-copy.d.ts","sourceRoot":"","sources":["../../src/utils/deep-copy.ts"],"names":[],"mappings":"AAAA,wCAAwC;AACxC,wBAAgB,QAAQ,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG,CAoBzC"}

package/dist/utils/deep-copy.js

@@ -1,21 +0,0 @@
-/** Deeply copies a JS data structure */
-export function deepCopy(object) {
-    // don't copy binary data
-    if (ArrayBuffer.isView(object) ||
-        object instanceof ArrayBuffer ||
-        object instanceof ImageBitmap) {
-        return object;
-    }
-    if (Array.isArray(object)) {
-        return object.map(deepCopy);
-    }
-    if (object && typeof object === 'object') {
-        const result = {};
-        for (const key in object) {
-            result[key] = deepCopy(object[key]);
-        }
-        return result;
-    }
-    return object;
-}
-//# sourceMappingURL=deep-copy.js.map

package/dist/utils/deep-copy.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"deep-copy.js","sourceRoot":"","sources":["../../src/utils/deep-copy.ts"],"names":[],"mappings":"AAAA,wCAAwC;AACxC,MAAM,UAAU,QAAQ,CAAC,MAAW;IAClC,yBAAyB;IACzB,IACE,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC;QAC1B,MAAM,YAAY,WAAW;QAC7B,MAAM,YAAY,WAAW,EAC7B,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,OAAO,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC9B,CAAC;IACD,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QACzC,MAAM,MAAM,GAAkB,EAAE,CAAC;QACjC,KAAK,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;YACzB,MAAM,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QACtC,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/src/utils/deep-copy.ts

@@ -1,22 +0,0 @@
-/** Deeply copies a JS data structure */
-export function deepCopy(object: any): any {
-  // don't copy binary data
-  if (
-    ArrayBuffer.isView(object) ||
-    object instanceof ArrayBuffer ||
-    object instanceof ImageBitmap
-  ) {
-    return object;
-  }
-  if (Array.isArray(object)) {
-    return object.map(deepCopy);
-  }
-  if (object && typeof object === 'object') {
-    const result: typeof object = {};
-    for (const key in object) {
-      result[key] = deepCopy(object[key]);
-    }
-    return result;
-  }
-  return object;
-}