@loaders.gl/textures 4.4.0-alpha.2 → 4.4.0

package/src/lib/texture-api/load-image-cube.ts

@@ -2,47 +2,27 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {ImageLoader} from '@loaders.gl/images';
-import type {GetUrl, UrlOptions} from './texture-api-types';
+import {
+  loadCompositeImageUrlTree,
+  normalizeCompositeImageOptions
+} from '../composite-image/parse-composite-image';
+import {
+  IMAGE_TEXTURE_CUBE_FACES,
+  type ImageCubeTexture
+} from '../composite-image/image-texture-cube';
+import type {GetUrl, TextureLoaderOptions} from './texture-api-types';
 import {getImageUrls} from './load-image';
-import {deepLoad} from './deep-load';
-
-// Returned map will be have keys corresponding to GL cubemap constants
-const GL_TEXTURE_CUBE_MAP_POSITIVE_X = 0x8515;
-const GL_TEXTURE_CUBE_MAP_NEGATIVE_X = 0x8516;
-const GL_TEXTURE_CUBE_MAP_POSITIVE_Y = 0x8517;
-const GL_TEXTURE_CUBE_MAP_NEGATIVE_Y = 0x8518;
-const GL_TEXTURE_CUBE_MAP_POSITIVE_Z = 0x8519;
-const GL_TEXTURE_CUBE_MAP_NEGATIVE_Z = 0x851a;
-
-const CUBE_FACES = [
-  {face: GL_TEXTURE_CUBE_MAP_POSITIVE_X, direction: 'right', axis: 'x', sign: 'positive'},
-  {face: GL_TEXTURE_CUBE_MAP_NEGATIVE_X, direction: 'left', axis: 'x', sign: 'negative'},
-  {face: GL_TEXTURE_CUBE_MAP_POSITIVE_Y, direction: 'top', axis: 'y', sign: 'positive'},
-  {face: GL_TEXTURE_CUBE_MAP_NEGATIVE_Y, direction: 'bottom', axis: 'y', sign: 'negative'},
-  {face: GL_TEXTURE_CUBE_MAP_POSITIVE_Z, direction: 'front', axis: 'z', sign: 'positive'},
-  {face: GL_TEXTURE_CUBE_MAP_NEGATIVE_Z, direction: 'back', axis: 'z', sign: 'negative'}
-];
-
-export type ImageCubeTexture = {
-  GL_TEXTURE_CUBE_MAP_POSITIVE_X: any;
-  GL_TEXTURE_CUBE_MAP_NEGATIVE_X: any;
-  GL_TEXTURE_CUBE_MAP_POSITIVE_Y: any;
-  GL_TEXTURE_CUBE_MAP_NEGATIVE_Y: any;
-  GL_TEXTURE_CUBE_MAP_POSITIVE_Z: any;
-  GL_TEXTURE_CUBE_MAP_NEGATIVE_Z: any;
-};
 
 // Returns an object with six key-value pairs containing the urls (or url mip arrays)
 // for each cube face
-export async function getImageCubeUrls(getUrl: GetUrl, options: UrlOptions) {
+export async function getImageCubeUrls(getUrl: GetUrl, options: TextureLoaderOptions) {
   // Calculate URLs
   const urls: Record<number, string | string[]> = {};
   const promises: Promise<any>[] = [];
 
   let index = 0;
-  for (let i = 0; i < CUBE_FACES.length; ++i) {
-    const face = CUBE_FACES[index];
+  for (let i = 0; i < IMAGE_TEXTURE_CUBE_FACES.length; ++i) {
+    const face = IMAGE_TEXTURE_CUBE_FACES[index];
     const promise = getImageUrls(getUrl, options, {...face, index: index++}).then((url) => {
       urls[face.face] = url;
     });
@@ -56,10 +36,16 @@ export async function getImageCubeUrls(getUrl: GetUrl, options: UrlOptions) {
 
 // Returns an object with six key-value pairs containing the images (or image mip arrays)
 // for each cube face
+/**
+ * @deprecated Use `load(url, TextureCubeLoader)` for manifest-driven loading.
+ */
 export async function loadImageTextureCube(
   getUrl: GetUrl,
-  options = {}
+  options: TextureLoaderOptions = {}
 ): Promise<ImageCubeTexture> {
   const urls = await getImageCubeUrls(getUrl, options);
-  return (await deepLoad(urls, ImageLoader.parse, options)) as ImageCubeTexture;
+  return (await loadCompositeImageUrlTree(
+    urls,
+    normalizeCompositeImageOptions(options)
+  )) as ImageCubeTexture;
 }

package/src/lib/texture-api/load-image.ts

@@ -3,19 +3,29 @@
 // Copyright (c) vis.gl contributors
 
 import {assert} from '@loaders.gl/loader-utils';
-import {ImageLoader, getImageSize} from '@loaders.gl/images';
-import type {GetUrl, UrlOptions} from './texture-api-types';
+import {getImageSize} from '@loaders.gl/images';
+import {
+  loadCompositeImageMember,
+  loadCompositeImageUrlTree,
+  normalizeCompositeImageOptions
+} from '../composite-image/parse-composite-image';
+import type {GetUrl, TextureLoaderOptions, UrlOptions} from './texture-api-types';
 import {generateUrl} from './generate-url';
-import {deepLoad, shallowLoad} from './deep-load';
 
-export async function loadImageTexture(getUrl: string | GetUrl, options = {}): Promise<any> {
+/**
+ * @deprecated Use `load(url, TextureLoader)` for manifest-driven loading.
+ */
+export async function loadImageTexture(
+  getUrl: string | GetUrl,
+  options: TextureLoaderOptions = {}
+): Promise<any> {
   const imageUrls = await getImageUrls(getUrl, options);
-  return await deepLoad(imageUrls, ImageLoader.parse, options);
+  return await loadCompositeImageUrlTree(imageUrls, normalizeCompositeImageOptions(options));
 }
 
 export async function getImageUrls(
   getUrl: string | GetUrl,
-  options: any,
+  options: TextureLoaderOptions,
   urlOptions: UrlOptions = {}
 ): Promise<any> {
   const mipLevels = (options && options.image && options.image.mipLevels) || 0;
@@ -27,15 +37,16 @@ export async function getImageUrls(
 async function getMipmappedImageUrls(
   getUrl: string | GetUrl,
   mipLevels: number | 'auto',
-  options: any,
+  options: TextureLoaderOptions,
   urlOptions: UrlOptions
 ): Promise<string[]> {
   const urls: string[] = [];
+  const normalizedOptions = normalizeCompositeImageOptions(options);
 
   // If no mip levels supplied, we need to load the level 0 image and calculate based on size
   if (mipLevels === 'auto') {
     const url = generateUrl(getUrl, options, {...urlOptions, lod: 0});
-    const image = await shallowLoad(url, ImageLoader.parse, options);
+    const image = await loadCompositeImageMember(url, normalizedOptions);
 
     const {width, height} = getImageSize(image);
     mipLevels = getMipLevels({width, height});

package/src/lib/texture-api/texture-api-types.ts

@@ -2,6 +2,9 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
+import type {LoaderOptions} from '@loaders.gl/loader-utils';
+import type {ImageLoaderOptions} from '@loaders.gl/images';
+
 export type {ImageType} from '@loaders.gl/images';
 
 export type UrlOptions = {
@@ -12,3 +15,15 @@ export type UrlOptions = {
   direction?: string;
 };
 export type GetUrl = (options: UrlOptions) => string;
+
+export type TextureLoaderOptions = LoaderOptions & {
+  core?: NonNullable<LoaderOptions['core']> & {
+    /** Base URL for resolving composite image members when no loader context URL is available */
+    baseUrl?: string;
+  };
+  /** @deprecated Legacy helper alias kept for loadImageTexture* compatibility */
+  baseUrl?: string;
+  image?: NonNullable<ImageLoaderOptions['image']> & {
+    mipLevels?: number | 'auto';
+  };
+};

package/src/lib/utils/detect-supported-texture-formats.ts

@@ -0,0 +1,210 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {GPUTextureFormat, TextureFormat} from '@loaders.gl/schema';
+
+const BROWSER_PREFIXES = ['', 'WEBKIT_', 'MOZ_'];
+
+const WEBGL_TEXTURE_FORMATS: {[key: string]: TextureFormat[]} = {
+  /* eslint-disable camelcase */
+  WEBGL_compressed_texture_s3tc: [
+    'bc1-rgb-unorm-webgl',
+    'bc1-rgba-unorm',
+    'bc2-rgba-unorm',
+    'bc3-rgba-unorm'
+  ],
+  WEBGL_compressed_texture_s3tc_srgb: [
+    'bc1-rgb-unorm-srgb-webgl',
+    'bc1-rgba-unorm-srgb',
+    'bc2-rgba-unorm-srgb',
+    'bc3-rgba-unorm-srgb'
+  ],
+  EXT_texture_compression_rgtc: ['bc4-r-unorm', 'bc4-r-snorm', 'bc5-rg-unorm', 'bc5-rg-snorm'],
+  EXT_texture_compression_bptc: [
+    'bc6h-rgb-ufloat',
+    'bc6h-rgb-float',
+    'bc7-rgba-unorm',
+    'bc7-rgba-unorm-srgb'
+  ],
+  WEBGL_compressed_texture_etc1: ['etc1-rgb-unorm-webgl'],
+  WEBGL_compressed_texture_etc: [
+    'etc2-rgb8unorm',
+    'etc2-rgb8unorm-srgb',
+    'etc2-rgb8a1unorm',
+    'etc2-rgb8a1unorm-srgb',
+    'etc2-rgba8unorm',
+    'etc2-rgba8unorm-srgb',
+    'eac-r11unorm',
+    'eac-r11snorm',
+    'eac-rg11unorm',
+    'eac-rg11snorm'
+  ],
+  WEBGL_compressed_texture_pvrtc: [
+    'pvrtc-rgb4unorm-webgl',
+    'pvrtc-rgba4unorm-webgl',
+    'pvrtc-rgb2unorm-webgl',
+    'pvrtc-rgba2unorm-webgl'
+  ],
+  WEBGL_compressed_texture_atc: [
+    'atc-rgb-unorm-webgl',
+    'atc-rgba-unorm-webgl',
+    'atc-rgbai-unorm-webgl'
+  ],
+  WEBGL_compressed_texture_astc: [
+    'astc-4x4-unorm',
+    'astc-4x4-unorm-srgb',
+    'astc-5x4-unorm',
+    'astc-5x4-unorm-srgb',
+    'astc-5x5-unorm',
+    'astc-5x5-unorm-srgb',
+    'astc-6x5-unorm',
+    'astc-6x5-unorm-srgb',
+    'astc-6x6-unorm',
+    'astc-6x6-unorm-srgb',
+    'astc-8x5-unorm',
+    'astc-8x5-unorm-srgb',
+    'astc-8x6-unorm',
+    'astc-8x6-unorm-srgb',
+    'astc-8x8-unorm',
+    'astc-8x8-unorm-srgb',
+    'astc-10x5-unorm',
+    'astc-10x5-unorm-srgb',
+    'astc-10x6-unorm',
+    'astc-10x6-unorm-srgb',
+    'astc-10x8-unorm',
+    'astc-10x8-unorm-srgb',
+    'astc-10x10-unorm',
+    'astc-10x10-unorm-srgb',
+    'astc-12x10-unorm',
+    'astc-12x10-unorm-srgb',
+    'astc-12x12-unorm',
+    'astc-12x12-unorm-srgb'
+  ]
+  /* eslint-enable camelcase */
+};
+
+const GPU_TEXTURE_FORMATS: {[key in GPUTextureFormat]: TextureFormat[]} = {
+  dxt: ['bc1-rgb-unorm-webgl', 'bc1-rgba-unorm', 'bc2-rgba-unorm', 'bc3-rgba-unorm'],
+  'dxt-srgb': [
+    'bc1-rgb-unorm-srgb-webgl',
+    'bc1-rgba-unorm-srgb',
+    'bc2-rgba-unorm-srgb',
+    'bc3-rgba-unorm-srgb'
+  ],
+  etc1: ['etc1-rgb-unorm-webgl'],
+  etc2: [
+    'etc2-rgb8unorm',
+    'etc2-rgb8unorm-srgb',
+    'etc2-rgb8a1unorm',
+    'etc2-rgb8a1unorm-srgb',
+    'etc2-rgba8unorm',
+    'etc2-rgba8unorm-srgb',
+    'eac-r11unorm',
+    'eac-r11snorm',
+    'eac-rg11unorm',
+    'eac-rg11snorm'
+  ],
+  pvrtc: [
+    'pvrtc-rgb4unorm-webgl',
+    'pvrtc-rgba4unorm-webgl',
+    'pvrtc-rgb2unorm-webgl',
+    'pvrtc-rgba2unorm-webgl'
+  ],
+  atc: ['atc-rgb-unorm-webgl', 'atc-rgba-unorm-webgl', 'atc-rgbai-unorm-webgl'],
+  astc: [
+    'astc-4x4-unorm',
+    'astc-4x4-unorm-srgb',
+    'astc-5x4-unorm',
+    'astc-5x4-unorm-srgb',
+    'astc-5x5-unorm',
+    'astc-5x5-unorm-srgb',
+    'astc-6x5-unorm',
+    'astc-6x5-unorm-srgb',
+    'astc-6x6-unorm',
+    'astc-6x6-unorm-srgb',
+    'astc-8x5-unorm',
+    'astc-8x5-unorm-srgb',
+    'astc-8x6-unorm',
+    'astc-8x6-unorm-srgb',
+    'astc-8x8-unorm',
+    'astc-8x8-unorm-srgb',
+    'astc-10x5-unorm',
+    'astc-10x5-unorm-srgb',
+    'astc-10x6-unorm',
+    'astc-10x6-unorm-srgb',
+    'astc-10x8-unorm',
+    'astc-10x8-unorm-srgb',
+    'astc-10x10-unorm',
+    'astc-10x10-unorm-srgb',
+    'astc-12x10-unorm',
+    'astc-12x10-unorm-srgb',
+    'astc-12x12-unorm',
+    'astc-12x12-unorm-srgb'
+  ],
+  rgtc: ['bc4-r-unorm', 'bc4-r-snorm', 'bc5-rg-unorm', 'bc5-rg-snorm']
+};
+
+let formats: Set<GPUTextureFormat> | null = null;
+let textureFormats: Set<TextureFormat> | null = null;
+
+// DEPRECATED
+/**
+ * @deprecated Pass `basis.supportedTextureFormats` to Basis loaders instead of relying on global detection.
+ */
+export function detectSupportedTextureFormats(gl?: WebGLRenderingContext): Set<TextureFormat> {
+  if (!textureFormats) {
+    gl = gl || getWebGLContext() || undefined;
+    textureFormats = new Set<TextureFormat>();
+
+    for (const prefix of BROWSER_PREFIXES) {
+      for (const extension in WEBGL_TEXTURE_FORMATS) {
+        if (gl && gl.getExtension(`${prefix}${extension}`)) {
+          for (const textureFormat of WEBGL_TEXTURE_FORMATS[extension]) {
+            textureFormats.add(textureFormat);
+          }
+        }
+      }
+    }
+  }
+
+  return textureFormats;
+}
+
+// DEPRECATED
+/**
+ * Returns a list of formats.
+ * Creates a temporary WebGLRenderingContext if none is provided.
+ *
+ * @deprecated Pass `basis.supportedTextureFormats` to Basis loaders instead of relying on global detection.
+ * @param gl - Optional context.
+ */
+export function detectSupportedGPUTextureFormats(gl?: WebGLRenderingContext): Set<string> {
+  if (!formats) {
+    formats = new Set<GPUTextureFormat>();
+    const supportedTextureFormats = detectSupportedTextureFormats(gl);
+
+    for (const gpuTextureFormat in GPU_TEXTURE_FORMATS) {
+      const textureFormatsForGroup = GPU_TEXTURE_FORMATS[gpuTextureFormat as GPUTextureFormat];
+      if (
+        textureFormatsForGroup.some((textureFormat) => supportedTextureFormats.has(textureFormat))
+      ) {
+        formats.add(gpuTextureFormat as GPUTextureFormat);
+      }
+    }
+  }
+
+  return formats;
+}
+
+/**
+ * @returns {WebGLRenderingContext?}
+ */
+function getWebGLContext() {
+  try {
+    const canvas = document.createElement('canvas');
+    return canvas.getContext('webgl');
+  } catch (error) {
+    return null;
+  }
+}

package/src/lib/utils/extract-mipmap-images.ts

@@ -2,14 +2,21 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {TextureLevel} from '@loaders.gl/schema';
+import type {TextureFormat, TextureLevel} from '@loaders.gl/schema';
+import type {GLTextureFormat} from '../gl-types';
+import {
+  getTextureFormatFromWebGLFormat,
+  getWebGLFormatFromTextureFormat
+} from './texture-format-map';
 
 export type CompressedTextureExtractOptions = {
   mipMapLevels: number;
   width: number;
   height: number;
   sizeFunction: Function;
-  internalFormat: number;
+  internalFormat?: GLTextureFormat;
+  /** Canonical loaders.gl texture format for the mip levels being extracted. */
+  textureFormat?: TextureFormat;
 };
 
 /**
@@ -20,6 +27,7 @@ export type CompressedTextureExtractOptions = {
  * @param options.height - height of 0 - level
  * @param options.sizeFunction - format-related function to calculate level size in bytes
  * @param options.internalFormat - WebGL compatible format code
+ * @param options.textureFormat - canonical loaders.gl texture format
  * @returns Array of the texture levels
  */
 export function extractMipmapImages(
@@ -27,6 +35,9 @@ export function extractMipmapImages(
   options: CompressedTextureExtractOptions
 ): TextureLevel[] {
   const images = new Array(options.mipMapLevels);
+  const textureFormat =
+    options.textureFormat || getTextureFormatFromWebGLFormat(options.internalFormat);
+  const format = options.internalFormat || getWebGLFormatFromTextureFormat(options.textureFormat);
 
   let levelWidth = options.width;
   let levelHeight = options.height;
@@ -38,15 +49,23 @@ export function extractMipmapImages(
     // @ts-expect-error
     const levelData = getLevelData(data, i, offset, levelSize);
 
-    images[i] = {
+    const image: TextureLevel = {
+      shape: 'texture-level',
       compressed: true,
-      format: options.internalFormat,
       data: levelData,
       width: levelWidth,
       height: levelHeight,
       levelSize
     };
 
+    if (format !== undefined) {
+      image.format = format;
+    }
+    if (textureFormat) {
+      image.textureFormat = textureFormat;
+    }
+    images[i] = image;
+
     levelWidth = Math.max(1, levelWidth >> 1);
     levelHeight = Math.max(1, levelHeight >> 1);