@luma.gl/webgl 9.1.0-alpha.9 → 9.1.0-beta.3

package/src/adapter/resources/webgl-texture.ts

@@ -2,14 +2,6 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-// @todo texture refactor
-// - [ ] cube texture init params P1
-// - [ ] 3d texture init params P1
-// - [ ] GPU memory tracking
-// - [ ] raw data inputs
-// - [ ] video (external) textures
-
-// import {TypedArray} from '@math.gl/types';
 import type {
   Device,
   TextureProps,
@@ -17,10 +9,8 @@ import type {
   Sampler,
   SamplerProps,
   SamplerParameters,
-  // TextureFormat,
   TextureCubeFace,
   ExternalImage,
-  TextureLevelData,
   Texture1DData,
   Texture2DData,
   Texture3DData,
@@ -28,8 +18,6 @@ import type {
   TextureArrayData,
   TextureCubeArrayData
 } from '@luma.gl/core';
-// import {decodeTextureFormat} from '@luma.gl/core';
-// import {Buffer, Texture, log} from '@luma.gl/core';
 import {Texture, log} from '@luma.gl/core';
 import {
   GL,
@@ -38,62 +26,26 @@ import {
   GLTexelDataFormat,
   GLTextureTarget
 } from '@luma.gl/constants';
-// import {GLPixelDataType} from '@luma.gl/constants';
-import {withGLParameters} from '../../context/state-tracker/with-parameters';
-// getTextureFormatBytesPerPixel
-import {getTextureFormatWebGL} from '../converters/texture-formats';
+import {getTextureFormatWebGL} from '../converters/webgl-texture-table';
 import {convertSamplerParametersToWebGL} from '../converters/sampler-parameters';
 import {WebGLDevice} from '../webgl-device';
-// import {WEBGLBuffer} from './webgl-buffer';
 import {WEBGLSampler} from './webgl-sampler';
 import {WEBGLTextureView} from './webgl-texture-view';
 
-// import type {WebGLSetTextureOptions, WebGLCopyTextureOptions} from '../helpers/webgl-texture-utils';
 import {
   initializeTextureStorage,
   // clearMipLevel,
-  copyCPUImageToMipLevel,
+  copyExternalImageToMipLevel,
   copyCPUDataToMipLevel,
   // copyGPUBufferToMipLevel,
   getWebGLTextureTarget
 } from '../helpers/webgl-texture-utils';
 
-// PORTABLE HELPERS (Move to methods on Texture?)
-
-/**
- * Normalize TextureData to an array of TextureLevelData / ExternalImages
- * @param data
- * @param options
- * @returns array of TextureLevelData / ExternalImages
- */
-function normalizeTextureData(
-  data: Texture2DData,
-  options: {width: number; height: number; depth: number}
-): (TextureLevelData | ExternalImage)[] {
-  let lodArray: (TextureLevelData | ExternalImage)[];
-  if (ArrayBuffer.isView(data)) {
-    lodArray = [
-      {
-        // ts-expect-error does data really need to be Uint8ClampedArray?
-        data,
-        width: options.width,
-        height: options.height
-        // depth: options.depth
-      }
-    ];
-  } else if (!Array.isArray(data)) {
-    lodArray = [data];
-  } else {
-    lodArray = data;
-  }
-  return lodArray;
-}
-
 /**
  * WebGL... the texture API from hell... hopefully made simpler
  */
 export class WEBGLTexture extends Texture {
-  readonly MAX_ATTRIBUTES: number;
+  // readonly MAX_ATTRIBUTES: number;
   readonly device: WebGLDevice;
   readonly gl: WebGL2RenderingContext;
   handle: WebGLTexture;
@@ -101,9 +53,14 @@ export class WEBGLTexture extends Texture {
   sampler: WEBGLSampler = undefined; // TODO - currently unused in WebGL. Create dummy sampler?
   view: WEBGLTextureView = undefined; // TODO - currently unused in WebGL. Create dummy view?
 
-  mipmaps: boolean = false;
+  mipmaps: boolean;
+
+  // Texture type
+  /** Whether the internal format is compressed */
+  compressed: boolean;
 
   /**
+   * The WebGL target corresponding to the texture type
    * @note `target` cannot be modified by bind:
    * textures are special because when you first bind them to a target,
    * When you first bind a texture as a GL_TEXTURE_2D, you are saying that this texture is a 2D texture.
@@ -112,39 +69,23 @@ export class WEBGLTexture extends Texture {
    * attempting to bind it as GL_TEXTURE_3D will give rise to a run-time error
    */
   glTarget: GLTextureTarget;
-
-  // Texture type
-
   /** The WebGL format - essentially channel structure */
   glFormat: GLTexelDataFormat;
   /** The WebGL data format - the type of each channel */
   glType: GLPixelType;
   /** The WebGL constant corresponding to the WebGPU style constant in format */
   glInternalFormat: GL;
-  /** Whether the internal format is compressed */
-  compressed: boolean;
-
-  // data;
-  // inherited props
-  // dimension: ...
-  // format: GLTextureTarget;
-  // width: number = undefined;
-  // height: number = undefined;
-  // depth: number = undefined;
 
   // state
-  /** Texture binding slot */
+  /** Texture binding slot - TODO - move to texture view? */
   textureUnit: number = 0;
-  /** For automatically updating video */
-  _video: {
-    video: HTMLVideoElement;
-    parameters: any;
-    lastTime: number;
-  } | null = null;
 
   constructor(device: Device, props: TextureProps) {
-    // Note: Clear out `props.data` so that we don't hold a reference to any big memory chunks
-    super(device, {...Texture.defaultProps, ...props, data: undefined!});
+    super(device, props);
+
+    // Texture base class strips out the data prop, so we need to add it back in
+    const propsWithData = {...this.props};
+    propsWithData.data = props.data;
 
     this.device = device as WebGLDevice;
     this.gl = this.device.gl;
@@ -153,46 +94,33 @@ export class WEBGLTexture extends Texture {
     this.glTarget = getWebGLTextureTarget(this.props.dimension);
 
     // The target format of this texture
-    const format = getTextureFormatWebGL(this.props.format);
-    this.glInternalFormat = format.internalFormat;
-    this.glFormat = format.format;
-    this.glType = format.type;
-    this.compressed = format.compressed;
-
-    if (
-      typeof HTMLVideoElement !== 'undefined' &&
-      props.data instanceof HTMLVideoElement &&
-      // @ts-expect-error
-      props.data.readyState < HTMLVideoElement.HAVE_METADATA
-    ) {
-      const video = props.data;
-      this._video = null; // Declare member before the object is sealed
-      video.addEventListener('loadeddata', () => this.initialize(props));
-    }
+    const formatInfo = getTextureFormatWebGL(this.props.format);
+    this.glInternalFormat = formatInfo.internalFormat;
+    this.glFormat = formatInfo.format;
+    this.glType = formatInfo.type;
+    this.compressed = formatInfo.compressed;
+    this.mipmaps = Boolean(this.props.mipmaps);
 
-    // We removed data, we need to add it again.
-    // @ts-expect-error
-    this.initialize({...this.props, data: props.data});
+    this._initialize(propsWithData);
 
     Object.seal(this);
   }
 
-  /**
-   * Initialize texture with supplied props
-   */
+  /** Initialize texture with supplied props */
   // eslint-disable-next-line max-statements
-  initialize(props: TextureProps = {}): void {
+  _initialize(propsWithData: TextureProps): void {
     this.handle = this.props.handle || this.gl.createTexture();
-    this.device.setSpectorMetadata(this.handle, {...this.props, data: typeof this.props.data});
-
-    const data = props.data;
-
-    // const {parameters = {}  as Record<GL, any>} = props;
+    this.device._setWebGLDebugMetadata(this.handle, this, {
+      spector: {
+        ...this.props,
+        data: propsWithData.data
+      }
+    });
 
-    let {width, height} = props;
+    let {width, height} = propsWithData;
 
     if (!width || !height) {
-      const textureSize = this.getTextureDataSize(data);
+      const textureSize = Texture.getTextureDataSize(propsWithData.data);
       width = textureSize?.width || 1;
       height = textureSize?.height || 1;
     }
@@ -200,73 +128,35 @@ export class WEBGLTexture extends Texture {
     // Store opts for accessors
     this.width = width;
     this.height = height;
-    this.depth = props.depth;
+    this.depth = propsWithData.depth;
 
     // Set texture sampler parameters
-    this.setSampler(props.sampler);
-    // @ts-ignore
+    this.setSampler(propsWithData.sampler);
+    // @ts-ignore TODO - fix types
     this.view = new WEBGLTextureView(this.device, {...this.props, texture: this});
 
     this.bind();
-    if (!this.props.data) {
-      initializeTextureStorage(this.gl, this.mipLevels, this);
-    }
+    initializeTextureStorage(this.gl, this.mipLevels, this);
 
-    if (props.data) {
+    if (propsWithData.data) {
       // prettier-ignore
-      switch (props.dimension) {
-        case '1d': this.setTexture1DData(props.data); break;
-        case '2d': this.setTexture2DData(props.data); break;
-        case '3d': this.setTexture3DData(props.data); break;
-        case 'cube': this.setTextureCubeData(props.data); break;
-        case '2d-array': this.setTextureArrayData(props.data); break;
-        case 'cube-array': this.setTextureCubeArrayData(props.data); break;
+      switch (propsWithData.dimension) {
+        case '1d': this.setTexture1DData(propsWithData.data); break;
+        case '2d': this.setTexture2DData(propsWithData.data); break;
+        case '3d': this.setTexture3DData(propsWithData.data); break;
+        case 'cube': this.setTextureCubeData(propsWithData.data); break;
+        case '2d-array': this.setTextureArrayData(propsWithData.data); break;
+        case 'cube-array': this.setTextureCubeArrayData(propsWithData.data); break;
         // @ts-expect-error
-        default: throw new Error(props.dimension);
+        default: throw new Error(propsWithData.dimension);
       }
     }
 
-    this.mipmaps = Boolean(props.mipmaps);
-
     if (this.mipmaps) {
       this.generateMipmap();
     }
-
-    // if (isVideo) {
-    //   this._video = {
-    //     video: data,
-    //     // TODO  - should we be using the sampler parameters here?
-    //     parameters: {},
-    //     // @ts-expect-error HTMLVideoElement.HAVE_CURRENT_DATA is not declared
-    //     lastTime: data.readyState >= HTMLVideoElement.HAVE_CURRENT_DATA ? data.currentTime : -1
-    //   };
-    // }
   }
 
-  /*
-  initializeCube(props?: TextureProps): void {
-    const {mipmaps = true} = props; // , parameters = {} as Record<GL, any>} = props;
-
-    // Store props for accessors
-    // this.props = props;
-
-    // @ts-expect-error
-    this.setCubeMapData(props).then(() => {
-      // TODO - should genMipmap() be called on the cubemap or on the faces?
-      // TODO - without generateMipmap() cube textures do not work at all!!! Why?
-      if (mipmaps) {
-        this.generateMipmap(props);
-      }
-
-      this.setSampler(props.sampler);
-
-      // v8 compatibility?
-      // const {parameters = {} as Record<GL, any>} = props;
-      // this._setSamplerParameters(parameters);
-    });
-  }
-  */
-
   override destroy(): void {
     if (this.handle) {
       this.gl.deleteTexture(this.handle);
@@ -277,10 +167,6 @@ export class WEBGLTexture extends Texture {
     }
   }
 
-  override toString(): string {
-    return `Texture(${this.id},${this.width}x${this.height})`;
-  }
-
   createView(props: TextureViewProps): WEBGLTextureView {
     return new WEBGLTextureView(this.device, {...props, texture: this});
   }
@@ -299,40 +185,79 @@ export class WEBGLTexture extends Texture {
     this._setSamplerParameters(parameters);
   }
 
-  /** Update external texture (video frame or canvas) */
-  update(): void {
-    log.warn('Texture.update() not implemented');
-    // if (this._video) {
-    //   const {video, parameters, lastTime} = this._video;
-    //   // @ts-expect-error
-    //   if (lastTime === video.currentTime || video.readyState < HTMLVideoElement.HAVE_CURRENT_DATA) {
-    //     return;
-    //   }
-    //   this.setSubImageData({
-    //     data: video,
-    //     parameters
-    //   });
-    //   if (this.mipmaps) {
-    //     this.generateMipmap();
-    //   }
-    //   this._video.lastTime = video.currentTime;
-    // }
-  }
-
   // Call to regenerate mipmaps after modifying texture(s)
-  generateMipmap(params = {}): void {
-    if (!this.props.data) {
-      return;
+  generateMipmap(options?: {force?: boolean}): void {
+    const isFilterableAndRenderable =
+      this.device.isTextureFormatRenderable(this.props.format) &&
+      this.device.isTextureFormatFilterable(this.props.format);
+    if (!isFilterableAndRenderable) {
+      log.warn(`${this} is not renderable or filterable, may not be able to generate mipmaps`)();
+      if (!options?.force) {
+        return;
+      }
     }
-    this.mipmaps = true;
-    this.gl.bindTexture(this.glTarget, this.handle);
-    withGLParameters(this.gl, params, () => {
+
+    try {
+      this.gl.bindTexture(this.glTarget, this.handle);
       this.gl.generateMipmap(this.glTarget);
-    });
-    this.gl.bindTexture(this.glTarget, null);
+    } catch (error) {
+      log.warn(`Error generating mipmap for ${this}: ${(error as Error).message}`)();
+    } finally {
+      this.gl.bindTexture(this.glTarget, null);
+    }
   }
 
   // Image Data Setters
+  copyExternalImage(options: {
+    image: ExternalImage;
+    sourceX?: number;
+    sourceY?: number;
+    width?: number;
+    height?: number;
+    depth?: number;
+    mipLevel?: number;
+    x?: number;
+    y?: number;
+    z?: number;
+    aspect?: 'all' | 'stencil-only' | 'depth-only';
+    colorSpace?: 'srgb';
+    premultipliedAlpha?: boolean;
+    flipY?: boolean;
+  }): {width: number; height: number} {
+    const size = Texture.getExternalImageSize(options.image);
+    const opts = {...Texture.defaultCopyExternalImageOptions, ...size, ...options};
+
+    const {image, depth, mipLevel, x, y, z, flipY} = opts;
+    let {width, height} = opts;
+    const {dimension, glTarget, glFormat, glInternalFormat, glType} = this;
+
+    // WebGL will error if we try to copy outside the bounds of the texture
+    width = Math.min(width, this.width - x);
+    height = Math.min(height, this.height - y);
+
+    if (options.sourceX || options.sourceY) {
+      // requires copyTexSubImage2D from a framebuffer'
+      throw new Error('WebGL does not support sourceX/sourceY)');
+    }
+
+    copyExternalImageToMipLevel(this.device.gl, this.handle, image, {
+      dimension,
+      mipLevel,
+      x,
+      y,
+      z,
+      width,
+      height,
+      depth,
+      glFormat,
+      glInternalFormat,
+      glType,
+      glTarget,
+      flipY
+    });
+
+    return {width: opts.width, height: opts.height};
+  }
 
   setTexture1DData(data: Texture1DData): void {
     throw new Error('setTexture1DData not supported in WebGL.');
@@ -342,7 +267,7 @@ export class WEBGLTexture extends Texture {
   setTexture2DData(lodData: Texture2DData, depth = 0): void {
     this.bind();
 
-    const lodArray = normalizeTextureData(lodData, this);
+    const lodArray = Texture.normalizeTextureData(lodData, this);
 
     // If the user provides multiple LODs, then automatic mipmap
     // generation generateMipmap() should be disabled to avoid overwriting them.
@@ -421,6 +346,13 @@ export class WEBGLTexture extends Texture {
     this.setTexture2DData(lodData, faceDepth);
   }
 
+  // DEPRECATED METHODS
+
+  /** Update external texture (video frame or canvas) @deprecated Use ExternalTexture */
+  update(): void {
+    throw new Error('Texture.update() not implemented. Use ExternalTexture');
+  }
+
   // INTERNAL METHODS
 
   /** @todo update this method to accept LODs */
@@ -475,7 +407,7 @@ export class WEBGLTexture extends Texture {
    * Sets sampler parameters on texture
    */
   _setSamplerParameters(parameters: GLSamplerParameters): void {
-    log.log(1, 'texture sampler parameters', parameters)();
+    log.log(1, `${this.id} sampler parameters`, this.device.getGLKeys(parameters))();
 
     this.gl.bindTexture(this.glTarget, this.handle);
     for (const [pname, pvalue] of Object.entries(parameters)) {
@@ -513,63 +445,6 @@ export class WEBGLTexture extends Texture {
     this.gl.bindTexture(this.glTarget, null);
   }
 
-  // CLASSIC
-
-  /*
-  setCubeMapData(options: {
-    width: number;
-    height: number;
-    data: Record<GL, Texture2DData> | Record<TextureCubeFace, Texture2DData>;
-    format?: any;
-    type?: any;
-    /** @deprecated Use .data *
-    pixels: any;
-  }): void {
-    const {gl} = this;
-
-    const {width, height, pixels, data, format = GL.RGBA, type = GL.UNSIGNED_BYTE} = options;
-
-    // pixel data (imageDataMap) is an Object from Face to Image or Promise.
-    // For example:
-    // {
-    // GL.TEXTURE_CUBE_MAP_POSITIVE_X : Image-or-Promise,
-    // GL.TEXTURE_CUBE_MAP_NEGATIVE_X : Image-or-Promise,
-    // ... }
-    // To provide multiple level-of-details (LODs) this can be Face to Array
-    // of Image or Promise, like this
-    // {
-    // GL.TEXTURE_CUBE_MAP_POSITIVE_X : [Image-or-Promise-LOD-0, Image-or-Promise-LOD-1],
-    // GL.TEXTURE_CUBE_MAP_NEGATIVE_X : [Image-or-Promise-LOD-0, Image-or-Promise-LOD-1],
-    // ... }
-
-    const imageDataMap = this._getImageDataMap(pixels || data);
-
-    const resolvedFaces = WEBGLTexture.FACES.map(face => {
-      const facePixels = imageDataMap[face];
-      return Array.isArray(facePixels) ? facePixels : [facePixels];
-    });
-    this.bind();
-
-    WEBGLTexture.FACES.forEach((face, index) => {
-      if (resolvedFaces[index].length > 1 && this.props.mipmaps !== false) {
-        // If the user provides multiple LODs, then automatic mipmap
-        // generation generateMipmap() should be disabled to avoid overwritting them.
-        log.warn(`${this.id} has mipmap and multiple LODs.`)();
-      }
-      resolvedFaces[index].forEach((image, lodLevel) => {
-        // TODO: adjust width & height for LOD!
-        if (width && height) {
-          gl.texImage2D(face, lodLevel, format, width, height, 0 /* border*, format, type, image);
-        } else {
-          gl.texImage2D(face, lodLevel, format, format, type, image);
-        }
-      });
-    });
-
-    this.unbind();
-  }
-  */
-
   // INTERNAL SETTERS
 
   /**
@@ -578,7 +453,7 @@ export class WEBGLTexture extends Texture {
    */
   protected _setMipLevel(
     depth: number,
-    level: number,
+    mipLevel: number,
     textureData: Texture2DData,
     glTarget: GL = this.glTarget
   ) {
@@ -588,16 +463,22 @@ export class WEBGLTexture extends Texture {
     // }
 
     if (Texture.isExternalImage(textureData)) {
-      copyCPUImageToMipLevel(this.device.gl, textureData, {...this, depth, level, glTarget});
+      copyExternalImageToMipLevel(this.device.gl, this.handle, textureData, {
+        ...this,
+        depth,
+        mipLevel,
+        glTarget,
+        flipY: this.props.flipY
+      });
       return;
     }
 
     // @ts-expect-error
-    if (this.isTextureLevelData(textureData)) {
+    if (Texture.isTextureLevelData(textureData)) {
       copyCPUDataToMipLevel(this.device.gl, textureData.data, {
         ...this,
         depth,
-        level,
+        mipLevel,
         glTarget
       });
       return;
@@ -635,3 +516,60 @@ export class WEBGLTexture extends Texture {
     return textureUnit;
   }
 }
+
+// TODO - Remove when texture refactor is complete
+
+/*
+setCubeMapData(options: {
+  width: number;
+  height: number;
+  data: Record<GL, Texture2DData> | Record<TextureCubeFace, Texture2DData>;
+  format?: any;
+  type?: any;
+  /** @deprecated Use .data *
+  pixels: any;
+}): void {
+  const {gl} = this;
+
+  const {width, height, pixels, data, format = GL.RGBA, type = GL.UNSIGNED_BYTE} = options;
+
+  // pixel data (imageDataMap) is an Object from Face to Image or Promise.
+  // For example:
+  // {
+  // GL.TEXTURE_CUBE_MAP_POSITIVE_X : Image-or-Promise,
+  // GL.TEXTURE_CUBE_MAP_NEGATIVE_X : Image-or-Promise,
+  // ... }
+  // To provide multiple level-of-details (LODs) this can be Face to Array
+  // of Image or Promise, like this
+  // {
+  // GL.TEXTURE_CUBE_MAP_POSITIVE_X : [Image-or-Promise-LOD-0, Image-or-Promise-LOD-1],
+  // GL.TEXTURE_CUBE_MAP_NEGATIVE_X : [Image-or-Promise-LOD-0, Image-or-Promise-LOD-1],
+  // ... }
+
+  const imageDataMap = this._getImageDataMap(pixels || data);
+
+  const resolvedFaces = WEBGLTexture.FACES.map(face => {
+    const facePixels = imageDataMap[face];
+    return Array.isArray(facePixels) ? facePixels : [facePixels];
+  });
+  this.bind();
+
+  WEBGLTexture.FACES.forEach((face, index) => {
+    if (resolvedFaces[index].length > 1 && this.props.mipmaps !== false) {
+      // If the user provides multiple LODs, then automatic mipmap
+      // generation generateMipmap() should be disabled to avoid overwritting them.
+      log.warn(`${this.id} has mipmap and multiple LODs.`)();
+    }
+    resolvedFaces[index].forEach((image, lodLevel) => {
+      // TODO: adjust width & height for LOD!
+      if (width && height) {
+        gl.texImage2D(face, lodLevel, format, width, height, 0 /* border*, format, type, image);
+      } else {
+        gl.texImage2D(face, lodLevel, format, format, type, image);
+      }
+    });
+  });
+
+  this.unbind();
+}
+*/

package/src/adapter/webgl-adapter.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {Adapter, Device, DeviceProps, CanvasContext, log} from '@luma.gl/core';
+import {Adapter, Device, DeviceProps, log} from '@luma.gl/core';
 import {WebGLDevice} from './webgl-device';
 import {enforceWebGL2} from '../context/polyfills/polyfill-webgl1-extensions';
 import {loadSpectorJS, DEFAULT_SPECTOR_PROPS} from '../context/debug/spector';
@@ -52,7 +52,7 @@ export class WebGLAdapter extends Adapter {
     if (!isWebGL(gl)) {
       throw new Error('Invalid WebGL2RenderingContext');
     }
-    return new WebGLDevice({gl: gl as WebGL2RenderingContext});
+    return new WebGLDevice({_handle: gl as WebGL2RenderingContext});
   }
 
   async create(props: DeviceProps = {}): Promise<WebGLDevice> {
@@ -61,20 +61,14 @@ export class WebGLAdapter extends Adapter {
     const promises: Promise<unknown>[] = [];
 
     // Load webgl and spector debug scripts from CDN if requested
-    if (props.debug) {
+    if (props.debugWebGL || props.debug) {
       promises.push(loadWebGLDeveloperTools());
     }
 
-    if (props.debugWithSpectorJS) {
+    if (props.debugSpectorJS) {
       promises.push(loadSpectorJS(props));
     }
 
-    // Wait for page to load: if canvas is a string we need to query the DOM for the canvas element.
-    // We only wait when props.canvas is string to avoids setting the global page onload callback unless necessary.
-    if (typeof props.canvas === 'string') {
-      promises.push(CanvasContext.pageLoaded);
-    }
-
     // Wait for all the loads to settle before creating the context.
     // The Device.create() functions are async, so in contrast to the constructor, we can `await` here.
     const results = await Promise.allSettled(promises);
@@ -84,8 +78,6 @@ export class WebGLAdapter extends Adapter {
       }
     }
 
-    log.probe(LOG_LEVEL + 1, 'DOM is loaded')();
-
     const device = new WebGLDevice(props);
 
     // Log some debug info about the newly created context