@luma.gl/webgl 9.0.17 → 9.1.0-alpha.10

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

@@ -2,355 +2,256 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-// Texture class.
-// @todo
-// - [ ] cube texture init params
+// @todo texture refactor
+// - [ ] cube texture init params P1
+// - [ ] 3d texture init params P1
+// - [ ] GPU memory tracking
+// - [ ] raw data inputs
 // - [ ] video (external) textures
 
-import {
+// import {TypedArray} from '@math.gl/types';
+import type {
   Device,
   TextureProps,
   TextureViewProps,
   Sampler,
   SamplerProps,
   SamplerParameters,
-  TypedArray
+  // TextureFormat,
+  TextureCubeFace,
+  ExternalImage,
+  TextureLevelData,
+  Texture1DData,
+  Texture2DData,
+  Texture3DData,
+  TextureCubeData,
+  TextureArrayData,
+  TextureCubeArrayData
 } from '@luma.gl/core';
-import {Texture, log, assert, loadImage, isObjectEmpty} from '@luma.gl/core';
-import {GL, GLSamplerParameters} from '@luma.gl/constants';
-import {withGLParameters} from '../../context/state-tracker/with-parameters';
+// import {decodeTextureFormat} from '@luma.gl/core';
+// import {Buffer, Texture, log} from '@luma.gl/core';
+import {Texture, log} from '@luma.gl/core';
 import {
-  convertTextureFormatToGL,
-  getWebGLTextureParameters,
-  getTextureFormatBytesPerPixel
-} from '../converters/texture-formats';
+  GL,
+  GLPixelType,
+  GLSamplerParameters,
+  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 {convertSamplerParametersToWebGL} from '../converters/sampler-parameters';
 import {WebGLDevice} from '../webgl-device';
-import {WEBGLBuffer} from './webgl-buffer';
+// import {WEBGLBuffer} from './webgl-buffer';
 import {WEBGLSampler} from './webgl-sampler';
 import {WEBGLTextureView} from './webgl-texture-view';
 
-export type WEBGLTextureProps = TextureProps & {
-  /** @deprecated use props.sampler */
-  parameters?: Record<number, number>;
-  /** @deprecated use props.data */
-  pixels?: any;
-  /** @deprecated use props.format */
-  dataFormat?: number | null;
-  /** @deprecated rarely supported */
-  border?: number;
-  /** @deprecated WebGL only. */
-  pixelStore?: object;
-  /** @deprecated WebGL only. */
-  textureUnit?: number;
-  /** @deprecated WebGL only. Use dimension. */
-  target?: number;
-};
-
-export const DEFAULT_WEBGL_TEXTURE_PROPS = {
-  // deprecated
-  parameters: {},
-  pixelStore: {},
-  pixels: null,
-  border: 0,
-  dataFormat: undefined!,
-  textureUnit: undefined!,
-  target: undefined!
-};
-
-export type TextureSourceData =
-  | TypedArray
-  | ImageData
-  | HTMLImageElement
-  | HTMLCanvasElement
-  | ImageBitmap
-  | HTMLVideoElement;
-
-type SetImageDataOptions = {
-  target?: number;
-  level?: number;
-  dataFormat?: any;
-  width?: number;
-  height?: number;
-  depth?: number;
-  glFormat?: GL;
-  type?: any;
-  offset?: number;
-  data: any; // TextureSourceData;
-  compressed?: boolean;
-  parameters?: Record<GL, any>;
-  /** @deprecated */
-  pixels?: any;
-};
+// import type {WebGLSetTextureOptions, WebGLCopyTextureOptions} from '../helpers/webgl-texture-utils';
+import {
+  initializeTextureStorage,
+  // clearMipLevel,
+  copyCPUImageToMipLevel,
+  copyCPUDataToMipLevel,
+  // copyGPUBufferToMipLevel,
+  getWebGLTextureTarget
+} from '../helpers/webgl-texture-utils';
+
+// PORTABLE HELPERS (Move to methods on Texture?)
 
 /**
- * @param {*} pixels, data -
- *  null - create empty texture of specified format
- *  Typed array - init from image data in typed array
- *  Buffer|WebGLBuffer - (WEBGL2) init from image data in WebGLBuffer
- *  HTMLImageElement|Image - Inits with content of image. Auto width/height
- *  HTMLCanvasElement - Inits with contents of canvas. Auto width/height
- *  HTMLVideoElement - Creates video texture. Auto width/height
- *
- * @param  x - xOffset from where texture to be updated
- * @param  y - yOffset from where texture to be updated
- * @param  width - width of the sub image to be updated
- * @param  height - height of the sub image to be updated
- * @param  level - mip level to be updated
- * @param {GLenum} format - internal format of image data.
- * @param {GLenum} type
- *  - format of array (autodetect from type) or
- *  - (WEBGL2) format of buffer or ArrayBufferView
- * @param {GLenum} dataFormat - format of image data.
- * @param {Number} offset - (WEBGL2) offset from start of buffer
- * @parameters - temporary settings to be applied, can be used to supply pixel store settings.
+ * Normalize TextureData to an array of TextureLevelData / ExternalImages
+ * @param data
+ * @param options
+ * @returns array of TextureLevelData / ExternalImages
  */
-type SetSubImageDataOptions = {
-  target?: number;
-  level?: number;
-  dataFormat?: any;
-  width?: number;
-  height?: number;
-  depth?: number;
-  glFormat?: any;
-  type?: any;
-  offset?: number;
-  data: any;
-  parameters?: Record<GL, any>;
-  compressed?: boolean;
-  x?: number;
-  y?: number;
-  /** @deprecated */
-  pixels?: any;
-};
-
-type SetImageData3DOptions = {
-  level?: number;
-  dataFormat?: any;
-  width?: number;
-  height?: number;
-  depth?: number;
-  format?: any;
-  type?: any;
-  offset?: number;
-  data: any;
-  parameters?: Record<GL, any>;
-};
-
-// Polyfill
-export class WEBGLTexture extends Texture<WEBGLTextureProps> {
-  // TODO - remove?
-  static FACES: number[] = [
-    GL.TEXTURE_CUBE_MAP_POSITIVE_X,
-    GL.TEXTURE_CUBE_MAP_NEGATIVE_X,
-    GL.TEXTURE_CUBE_MAP_POSITIVE_Y,
-    GL.TEXTURE_CUBE_MAP_NEGATIVE_Y,
-    GL.TEXTURE_CUBE_MAP_POSITIVE_Z,
-    GL.TEXTURE_CUBE_MAP_NEGATIVE_Z
-  ];
+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 device: WebGLDevice;
   readonly gl: WebGL2RenderingContext;
-  readonly handle: WebGLTexture;
+  handle: WebGLTexture;
 
-  // (TODO - currently unused in WebGL, but WebGL 2 does support sampler objects) */
-  sampler: WEBGLSampler = undefined;
+  sampler: WEBGLSampler = undefined; // TODO - currently unused in WebGL. Create dummy sampler?
+  view: WEBGLTextureView = undefined; // TODO - currently unused in WebGL. Create dummy view?
 
-  view: WEBGLTextureView = undefined;
-
-  // data;
-
-  glFormat: GL = undefined;
-  type: GL = undefined;
-  dataFormat: GL = undefined;
-  mipmaps: boolean = undefined;
+  mipmaps: boolean = false;
 
   /**
    * @note `target` cannot be modified by bind:
    * textures are special because when you first bind them to a target,
-   * they get special information. When you first bind a texture as a
-   * GL_TEXTURE_2D, you are saying that this texture is a 2D texture.
+   * When you first bind a texture as a GL_TEXTURE_2D, you are saying that this texture is a 2D texture.
    * And it will always be a 2D texture; this state cannot be changed ever.
    * A texture that was first bound as a GL_TEXTURE_2D, must always be bound as a GL_TEXTURE_2D;
    * attempting to bind it as GL_TEXTURE_3D will give rise to a run-time error
-   * */
-  target: GL;
-  textureUnit: number = undefined;
-
-  /**
-   * Program.draw() checks the loaded flag of all textures to avoid
-   * Textures that are still loading from promises
-   * Set to true as soon as texture has been initialized with valid data
    */
-  loaded: boolean = false;
+  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 */
+  textureUnit: number = 0;
+  /** For automatically updating video */
   _video: {
     video: HTMLVideoElement;
     parameters: any;
     lastTime: number;
-  };
+  } | null = null;
 
-  constructor(device: Device, props: WEBGLTextureProps) {
-    super(device, {...DEFAULT_WEBGL_TEXTURE_PROPS, format: 'rgba8unorm', ...props});
+  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!});
 
     this.device = device as WebGLDevice;
     this.gl = this.device.gl;
-    this.handle = this.props.handle || this.gl.createTexture();
-    this.device.setSpectorMetadata(this.handle, {...this.props, data: typeof this.props.data}); // {name: this.props.id};
 
-    this.glFormat = GL.RGBA;
-    this.target = getWebGLTextureTarget(this.props);
+    // Note: In WebGL the texture target defines the type of texture on first bind.
+    this.glTarget = getWebGLTextureTarget(this.props.dimension);
 
-    // Program.draw() checks the loaded flag of all textures
-    this.loaded = false;
+    // 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;
 
-    // Signature: new Texture2D(gl, {data: url})
-    if (typeof this.props?.data === 'string') {
-      Object.assign(this.props, {data: loadImage(this.props.data)});
+    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));
     }
 
-    this.initialize(this.props);
+    // We removed data, we need to add it again.
+    // @ts-expect-error
+    this.initialize({...this.props, data: props.data});
 
     Object.seal(this);
   }
 
-  override destroy(): void {
-    if (this.handle) {
-      this.gl.deleteTexture(this.handle);
-      this.removeStats();
-      this.trackDeallocatedMemory('Texture');
-      // this.handle = null;
-      this.destroyed = true;
-    }
-  }
-
-  override toString(): string {
-    return `Texture(${this.id},${this.width}x${this.height})`;
-  }
-
-  createView(props: TextureViewProps): WEBGLTextureView {
-    return new WEBGLTextureView(this.device, {...props, texture: this});
-  }
-
+  /**
+   * Initialize texture with supplied props
+   */
   // eslint-disable-next-line max-statements
-  initialize(props: WEBGLTextureProps = {}): this {
-    // Cube textures
-    if (this.props.dimension === 'cube') {
-      return this.initializeCube(props);
-    }
-
-    let data = props.data;
-
-    if (data instanceof Promise) {
-      data.then(resolvedImageData =>
-        this.initialize(
-          Object.assign({}, props, {
-            pixels: resolvedImageData,
-            data: resolvedImageData
-          })
-        )
-      );
-      return this;
-    }
+  initialize(props: TextureProps = {}): void {
+    this.handle = this.props.handle || this.gl.createTexture();
+    this.device.setSpectorMetadata(this.handle, {...this.props, data: typeof this.props.data});
 
-    const isVideo = typeof HTMLVideoElement !== 'undefined' && data instanceof HTMLVideoElement;
-    // @ts-expect-error
-    if (isVideo && data.readyState < HTMLVideoElement.HAVE_METADATA) {
-      this._video = null; // Declare member before the object is sealed
-      // @ts-expect-error
-      data.addEventListener('loadeddata', () => this.initialize(props));
-      return this;
-    }
+    const data = props.data;
 
-    const {parameters = {} as Record<GL, any>} = props;
+    // const {parameters = {}  as Record<GL, any>} = props;
 
-    const {pixels = null, pixelStore = {}, textureUnit = undefined, mipmaps = true} = props;
+    let {width, height} = props;
 
-    // pixels variable is for API compatibility purpose
-    if (!data) {
-      // TODO - This looks backwards? Commenting out for now until we decide
-      // which prop to use
-      // log.deprecated('data', 'pixels')();
-      data = pixels;
+    if (!width || !height) {
+      const textureSize = Texture.getTextureDataSize(data);
+      width = textureSize?.width || 1;
+      height = textureSize?.height || 1;
     }
 
-    let {width, height, dataFormat, type, compressed = false} = props;
-    const {depth = 0} = props;
-
-    const glFormat = convertTextureFormatToGL(props.format);
-
-    // Deduce width and height
-    ({width, height, compressed, dataFormat, type} = this._deduceParameters({
-      format: props.format,
-      type,
-      dataFormat,
-      compressed,
-      data,
-      width,
-      height
-    }));
-
     // Store opts for accessors
     this.width = width;
     this.height = height;
-    // this.depth = depth;
-    this.glFormat = glFormat;
-    this.type = type;
-    this.dataFormat = dataFormat;
-    this.textureUnit = textureUnit;
-
-    if (Number.isFinite(this.textureUnit)) {
-      this.gl.activeTexture(GL.TEXTURE0 + this.textureUnit);
-      this.gl.bindTexture(this.target, this.handle);
-    }
-
-    this.mipmaps = mipmaps;
-
-    this.setImageData({
-      data,
-      width,
-      height,
-      depth,
-      format: glFormat,
-      type,
-      dataFormat,
-      // @ts-expect-error
-      parameters: pixelStore,
-      compressed
-    });
+    this.depth = props.depth;
 
     // Set texture sampler parameters
     this.setSampler(props.sampler);
-    this._setSamplerParameters(parameters);
-
-    this.view = this.createView({...this.props, mipLevelCount: 1, arrayLayerCount: 1});
+    // @ts-ignore
+    this.view = new WEBGLTextureView(this.device, {...this.props, texture: this});
 
-    if (mipmaps && this.device.isTextureFormatFilterable(props.format)) {
-      this.generateMipmap();
+    this.bind();
+    if (!this.props.data) {
+      initializeTextureStorage(this.gl, this.mipLevels, this);
     }
 
-    if (isVideo) {
-      this._video = {
-        video: data as HTMLVideoElement,
-        parameters,
+    if (props.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;
         // @ts-expect-error
-        lastTime: data.readyState >= HTMLVideoElement.HAVE_CURRENT_DATA ? data.currentTime : -1
-      };
+        default: throw new Error(props.dimension);
+      }
+    }
+
+    this.mipmaps = Boolean(props.mipmaps);
+
+    if (this.mipmaps) {
+      this.generateMipmap();
     }
 
-    return this;
+    // 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?: WEBGLTextureProps): this {
-    const {mipmaps = true, parameters = {} as Record<GL, any>} = props;
+  /*
+  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.setCubeMapImageData(props).then(() => {
-      this.loaded = true;
-
+    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) {
@@ -358,12 +259,33 @@ export class WEBGLTexture extends Texture<WEBGLTextureProps> {
       }
 
       this.setSampler(props.sampler);
-      this._setSamplerParameters(parameters);
+
+      // v8 compatibility?
+      // const {parameters = {} as Record<GL, any>} = props;
+      // this._setSamplerParameters(parameters);
     });
-    return this;
   }
+  */
 
-  setSampler(sampler: Sampler | SamplerProps = {}): this {
+  override destroy(): void {
+    if (this.handle) {
+      this.gl.deleteTexture(this.handle);
+      this.removeStats();
+      this.trackDeallocatedMemory('Texture');
+      // this.handle = null;
+      this.destroyed = true;
+    }
+  }
+
+  override toString(): string {
+    return `Texture(${this.id},${this.width}x${this.height})`;
+  }
+
+  createView(props: TextureViewProps): WEBGLTextureView {
+    return new WEBGLTextureView(this.device, {...props, texture: this});
+  }
+
+  setSampler(sampler: Sampler | SamplerProps = {}): void {
     let samplerProps: SamplerParameters;
     if (sampler instanceof WEBGLSampler) {
       this.sampler = sampler;
@@ -375,422 +297,260 @@ export class WEBGLTexture extends Texture<WEBGLTextureProps> {
 
     const parameters = convertSamplerParametersToWebGL(samplerProps);
     this._setSamplerParameters(parameters);
-    return this;
-  }
-
-  /**
-   * If size has changed, reinitializes with current format
-   * @note note clears image and mipmaps
-   */
-  resize(options: {height: number; width: number; mipmaps?: boolean}): this {
-    const {height, width, mipmaps = false} = options;
-    if (width !== this.width || height !== this.height) {
-      return this.initialize({
-        width,
-        height,
-        format: this.format,
-        type: this.type,
-        dataFormat: this.dataFormat,
-        mipmaps
-      });
-    }
-    return this;
   }
 
-  /** Update external texture (video frame) */
+  /** Update external texture (video frame or canvas) */
   update(): void {
-    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;
-    }
+    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 = {}): this {
+  generateMipmap(params = {}): void {
+    if (!this.props.data) {
+      return;
+    }
     this.mipmaps = true;
-
-    this.gl.bindTexture(this.target, this.handle);
+    this.gl.bindTexture(this.glTarget, this.handle);
     withGLParameters(this.gl, params, () => {
-      this.gl.generateMipmap(this.target);
+      this.gl.generateMipmap(this.glTarget);
     });
-    this.gl.bindTexture(this.target, null);
-    return this;
+    this.gl.bindTexture(this.glTarget, null);
   }
 
-  /*
-   * Allocates storage
-   * @param {*} pixels -
-   *  null - create empty texture of specified format
-   *  Typed array - init from image data in typed array
-   *  Buffer|WebGLBuffer - (WEBGL2) init from image data in WebGLBuffer
-   *  HTMLImageElement|Image - Inits with content of image. Auto width/height
-   *  HTMLCanvasElement - Inits with contents of canvas. Auto width/height
-   *  HTMLVideoElement - Creates video texture. Auto width/height
-   *
-   * @param  width -
-   * @param  height -
-   * @param  mipMapLevel -
-   * @param {GLenum} format - format of image data.
-   * @param {GLenum} type
-   *  - format of array (autodetect from type) or
-   *  - (WEBGL2) format of buffer
-   * @param {Number} offset - (WEBGL2) offset from start of buffer
-   * @parameters - temporary settings to be applied, can be used to supply pixel store settings.
-   */
-  // eslint-disable-next-line max-statements, complexity
-  setImageData(options: SetImageDataOptions) {
-    if (this.props.dimension === '3d' || this.props.dimension === '2d-array') {
-      return this.setImageData3D(options);
-    }
+  // 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;
+  }): {width: number; height: number} {
+    const size = Texture.getExternalImageSize(options.image);
+    const opts = {...Texture.defaultCopyExternalImageOptions, ...size, ...options};
+    const {depth, mipLevel: lodLevel, image} = opts;
+    this.bind();
+    this._setMipLevel(depth, lodLevel, image);
+    this.unbind();
+    return {width: opts.width, height: opts.height};
+  }
 
-    this.trackDeallocatedMemory('Texture');
+  setTexture1DData(data: Texture1DData): void {
+    throw new Error('setTexture1DData not supported in WebGL.');
+  }
 
-    const {
-      target = this.target,
-      pixels = null,
-      level = 0,
-      glFormat = this.glFormat,
-      offset = 0,
-      parameters = {} as Record<GL, any>
-    } = options;
+  /** Set a simple texture */
+  setTexture2DData(lodData: Texture2DData, depth = 0): void {
+    this.bind();
 
-    let {
-      data = null,
-      type = this.type,
-      width = this.width,
-      height = this.height,
-      dataFormat = this.dataFormat,
-      compressed = false
-    } = options;
+    const lodArray = normalizeTextureData(lodData, this);
 
-    // pixels variable is  for API compatibility purpose
-    if (!data) {
-      data = pixels;
+    // If the user provides multiple LODs, then automatic mipmap
+    // generation generateMipmap() should be disabled to avoid overwriting them.
+    if (lodArray.length > 1 && this.props.mipmaps !== false) {
+      log.warn(`Texture ${this.id} mipmap and multiple LODs.`)();
     }
 
-    ({type, dataFormat, compressed, width, height} = this._deduceParameters({
-      format: this.props.format,
-      type,
-      dataFormat,
-      compressed,
-      data,
-      width,
-      height
-    }));
-
-    const {gl} = this;
-    gl.bindTexture(this.target, this.handle);
-
-    let dataType = null;
-    ({data, dataType} = this._getDataType({data, compressed}));
-
-    withGLParameters(this.gl, parameters, () => {
-      switch (dataType) {
-        case 'null':
-          gl.texImage2D(
-            target,
-            level,
-            glFormat,
-            width,
-            height,
-            0 /* border*/,
-            dataFormat,
-            type,
-            data
-          );
-          break;
-        case 'typed-array':
-          gl.texImage2D(
-            target,
-            level,
-            glFormat,
-            width,
-            height,
-            0, // border (must be 0)
-            dataFormat,
-            type,
-            data,
-            offset
-          );
-          break;
-        case 'buffer':
-          // WebGL2 enables creating textures directly from a WebGL buffer
-          this.device.gl.bindBuffer(GL.PIXEL_UNPACK_BUFFER, data.handle || data);
-          this.device.gl.texImage2D(
-            target,
-            level,
-            glFormat,
-            width,
-            height,
-            0 /* border*/,
-            dataFormat,
-            type,
-            offset
-          );
-          this.device.gl.bindBuffer(GL.PIXEL_UNPACK_BUFFER, null);
-          break;
-        case 'browser-object':
-          gl.texImage2D(
-            target,
-            level,
-            glFormat,
-            width,
-            height,
-            0 /* border*/,
-            dataFormat,
-            type,
-            data
-          );
-          break;
-        case 'compressed':
-          for (const [levelIndex, levelData] of data.entries()) {
-            gl.compressedTexImage2D(
-              target,
-              levelIndex,
-              levelData.format,
-              levelData.width,
-              levelData.height,
-              0 /* border, must be 0 */,
-              levelData.data
-            );
-          }
-
-          break;
-        default:
-          assert(false, 'Unknown image data type');
-      }
-    });
-
-    if (data && data.byteLength) {
-      this.trackAllocatedMemory(data.byteLength, 'Texture');
-    } else {
-      const bytesPerPixel = getTextureFormatBytesPerPixel(this.props.format);
-      this.trackAllocatedMemory(this.width * this.height * bytesPerPixel, 'Texture');
+    for (let lodLevel = 0; lodLevel < lodArray.length; lodLevel++) {
+      const imageData = lodArray[lodLevel];
+      this._setMipLevel(depth, lodLevel, imageData);
     }
 
-    this.loaded = true;
-
-    return this;
+    this.unbind();
   }
 
   /**
-   * Redefines an area of an existing texture
-   * Note: does not allocate storage
-   * Redefines an area of an existing texture
+   * Sets a 3D texture
+   * @param data
    */
-  setSubImageData({
-    target = this.target,
-    pixels = null,
-    data = null,
-    x = 0,
-    y = 0,
-    width = this.width,
-    height = this.height,
-    level = 0,
-    glFormat = this.glFormat,
-    type = this.type,
-    dataFormat = this.dataFormat,
-    compressed = false,
-    offset = 0,
-    parameters = {} as Record<GL, any>
-  }: SetSubImageDataOptions) {
-    ({type, dataFormat, compressed, width, height} = this._deduceParameters({
-      format: this.props.format,
-      type,
-      dataFormat,
-      compressed,
-      data,
-      width,
-      height
-    }));
-
-    assert(this.depth === 1, 'texSubImage not supported for 3D textures');
-
-    // pixels variable is  for API compatibility purpose
-    if (!data) {
-      data = pixels;
+  setTexture3DData(data: Texture3DData): void {
+    if (this.props.dimension !== '3d') {
+      throw new Error(this.id);
     }
-
-    // Support ndarrays
-    if (data && data.data) {
-      const ndarray = data;
-      data = ndarray.data;
-      width = ndarray.shape[0];
-      height = ndarray.shape[1];
+    if (ArrayBuffer.isView(data)) {
+      this.bind();
+      copyCPUDataToMipLevel(this.device.gl, data, this);
+      this.unbind();
     }
+  }
 
-    // Support buffers
-    if (data instanceof WEBGLBuffer) {
-      data = data.handle;
+  /**
+   * Set a Texture Cube Data
+   * @todo - could support TextureCubeArray with depth
+   * @param data
+   * @param index
+   */
+  setTextureCubeData(data: TextureCubeData, depth: number = 0): void {
+    if (this.props.dimension !== 'cube') {
+      throw new Error(this.id);
+    }
+    for (const face of Texture.CubeFaces) {
+      this.setTextureCubeFaceData(data[face], face);
     }
-
-    this.gl.bindTexture(this.target, this.handle);
-
-    withGLParameters(this.gl, parameters, () => {
-      // TODO - x,y parameters
-      if (compressed) {
-        this.gl.compressedTexSubImage2D(target, level, x, y, width, height, glFormat, data);
-      } else if (data === null) {
-        this.gl.texSubImage2D(target, level, x, y, width, height, dataFormat, type, null);
-      } else if (ArrayBuffer.isView(data)) {
-        this.gl.texSubImage2D(target, level, x, y, width, height, dataFormat, type, data, offset);
-      } else if (typeof WebGLBuffer !== 'undefined' && data instanceof WebGLBuffer) {
-        // WebGL2 allows us to create texture directly from a WebGL buffer
-        // This texImage2D signature uses currently bound GL.PIXEL_UNPACK_BUFFER
-        this.device.gl.bindBuffer(GL.PIXEL_UNPACK_BUFFER, data);
-        this.device.gl.texSubImage2D(target, level, x, y, width, height, dataFormat, type, offset);
-        this.device.gl.bindBuffer(GL.PIXEL_UNPACK_BUFFER, null);
-      } else {
-        // Assume data is a browser supported object (ImageData, Canvas, ...)
-        this.device.gl.texSubImage2D(target, level, x, y, width, height, dataFormat, type, data);
-      }
-    });
-
-    this.gl.bindTexture(this.target, null);
   }
 
   /**
-   * Defines a two-dimensional texture image or cube-map texture image with
-   * pixels from the current framebuffer (rather than from client memory).
-   * (gl.copyTexImage2D wrapper)
-   *
-   * Note that binding a texture into a Framebuffer's color buffer and
-   * rendering can be faster.
+   * Sets an entire texture array
+   * @param data
    */
-  copyFramebuffer(opts = {}) {
-    log.error(
-      'Texture.copyFramebuffer({...}) is no logner supported, use copyToTexture(source, target, opts})'
-    )();
-    return null;
+  setTextureArrayData(data: TextureArrayData): void {
+    if (this.props.dimension !== '2d-array') {
+      throw new Error(this.id);
+    }
+    throw new Error('setTextureArrayData not implemented.');
   }
 
-  getActiveUnit(): number {
-    return this.gl.getParameter(GL.ACTIVE_TEXTURE) - GL.TEXTURE0;
+  /**
+   * Sets an entire texture cube array
+   * @param data
+   */
+  setTextureCubeArrayData(data: TextureCubeArrayData): void {
+    throw new Error('setTextureCubeArrayData not supported in WebGL2.');
   }
 
-  bind(textureUnit = this.textureUnit) {
-    const {gl} = this;
+  setTextureCubeFaceData(lodData: Texture2DData, face: TextureCubeFace, depth: number = 0): void {
+    // assert(this.props.dimension === 'cube');
 
-    if (textureUnit !== undefined) {
-      this.textureUnit = textureUnit;
-      gl.activeTexture(gl.TEXTURE0 + textureUnit);
+    // If the user provides multiple LODs, then automatic mipmap
+    // generation generateMipmap() should be disabled to avoid overwriting them.
+    if (Array.isArray(lodData) && lodData.length > 1 && this.props.mipmaps !== false) {
+      log.warn(`${this.id} has mipmap and multiple LODs.`)();
     }
 
-    gl.bindTexture(this.target, this.handle);
-    return textureUnit;
+    const faceDepth = Texture.CubeFaces.indexOf(face);
+
+    this.setTexture2DData(lodData, faceDepth);
   }
 
-  unbind(textureUnit = this.textureUnit) {
-    const {gl} = this;
+  // INTERNAL METHODS
 
-    if (textureUnit !== undefined) {
-      this.textureUnit = textureUnit;
-      gl.activeTexture(gl.TEXTURE0 + textureUnit);
-    }
+  /** @todo update this method to accept LODs */
+  setImageDataForFace(options): void {
+    const {
+      face,
+      width,
+      height,
+      pixels,
+      data,
+      format = GL.RGBA,
+      type = GL.UNSIGNED_BYTE
+      // generateMipmap = false // TODO
+    } = options;
 
-    gl.bindTexture(this.target, null);
-    return textureUnit;
-  }
+    const {gl} = this;
 
-  // PRIVATE METHODS
+    const imageData = pixels || data;
 
-  _getDataType({data, compressed = false}) {
-    if (compressed) {
-      return {data, dataType: 'compressed'};
-    }
-    if (data === null) {
-      return {data, dataType: 'null'};
-    }
-    if (ArrayBuffer.isView(data)) {
-      return {data, dataType: 'typed-array'};
-    }
-    if (data instanceof WEBGLBuffer) {
-      return {data: data.handle, dataType: 'buffer'};
+    this.bind();
+    if (imageData instanceof Promise) {
+      imageData.then(resolvedImageData =>
+        this.setImageDataForFace(
+          Object.assign({}, options, {
+            face,
+            data: resolvedImageData,
+            pixels: resolvedImageData
+          })
+        )
+      );
+    } else if (this.width || this.height) {
+      gl.texImage2D(face, 0, format, width, height, 0 /* border*/, format, type, imageData);
+    } else {
+      gl.texImage2D(face, 0, format, format, type, imageData);
     }
-    // Raw WebGL handle (not a luma wrapper)
-    if (typeof WebGLBuffer !== 'undefined' && data instanceof WebGLBuffer) {
-      return {data, dataType: 'buffer'};
+  }
+
+  _getImageDataMap(faceData: Record<string | GL, any>): Record<GL, any> {
+    for (let i = 0; i < Texture.CubeFaces.length; ++i) {
+      const faceName = Texture.CubeFaces[i];
+      if (faceData[faceName]) {
+        faceData[GL.TEXTURE_CUBE_MAP_POSITIVE_X + i] = faceData[faceName];
+        delete faceData[faceName];
+      }
     }
-    // Assume data is a browser supported object (ImageData, Canvas, ...)
-    return {data, dataType: 'browser-object'};
+    return faceData;
   }
 
-  // HELPER METHODS
+  // RESOURCE METHODS
 
-  _deduceParameters(opts: WEBGLTextureProps) {
-    const {format, data} = opts;
-    let {width, height, dataFormat, type, compressed} = opts;
+  /**
+   * Sets sampler parameters on texture
+   */
+  _setSamplerParameters(parameters: GLSamplerParameters): void {
+    log.log(1, 'texture sampler parameters', parameters)();
 
-    // Deduce format and type from format
-    const parameters = getWebGLTextureParameters(format);
-    dataFormat = dataFormat || parameters.dataFormat;
-    type = type || parameters.type;
-    compressed = compressed || parameters.compressed;
+    this.gl.bindTexture(this.glTarget, this.handle);
+    for (const [pname, pvalue] of Object.entries(parameters)) {
+      const param = Number(pname) as keyof GLSamplerParameters;
+      const value = pvalue;
 
-    ({width, height} = this._deduceImageSize(data, width, height));
+      // Apparently integer/float issues require two different texture parameter setting functions in JavaScript.
+      // For now, pick the float version for parameters specified as GLfloat.
+      switch (param) {
+        case GL.TEXTURE_MIN_LOD:
+        case GL.TEXTURE_MAX_LOD:
+          this.gl.texParameterf(this.glTarget, param, value);
+          break;
 
-    return {dataFormat, type, compressed, width, height, format, data};
-  }
+        case GL.TEXTURE_MIN_FILTER:
+          this.gl.texParameteri(this.glTarget, param, value);
+          break;
 
-  // eslint-disable-next-line complexity
-  _deduceImageSize(data, width, height): {width: number; height: number} {
-    let size;
-
-    if (typeof ImageData !== 'undefined' && data instanceof ImageData) {
-      size = {width: data.width, height: data.height};
-    } else if (typeof HTMLImageElement !== 'undefined' && data instanceof HTMLImageElement) {
-      size = {width: data.naturalWidth, height: data.naturalHeight};
-    } else if (typeof HTMLCanvasElement !== 'undefined' && data instanceof HTMLCanvasElement) {
-      size = {width: data.width, height: data.height};
-    } else if (typeof ImageBitmap !== 'undefined' && data instanceof ImageBitmap) {
-      size = {width: data.width, height: data.height};
-    } else if (typeof HTMLVideoElement !== 'undefined' && data instanceof HTMLVideoElement) {
-      size = {width: data.videoWidth, height: data.videoHeight};
-    } else if (!data) {
-      size = {width: width >= 0 ? width : 1, height: height >= 0 ? height : 1};
-    } else {
-      size = {width, height};
+        case GL.TEXTURE_WRAP_S:
+        case GL.TEXTURE_WRAP_T:
+          this.gl.texParameteri(this.glTarget, param, value);
+          break;
+        case GL.TEXTURE_MAX_ANISOTROPY_EXT:
+          // We have to query feature before using it
+          if (this.device.features.has('texture-filterable-anisotropic-webgl')) {
+            this.gl.texParameteri(this.glTarget, param, value);
+          }
+          break;
+        default:
+          this.gl.texParameteri(this.glTarget, param, value);
+          break;
+      }
     }
 
-    assert(size, 'Could not deduced texture size');
-    assert(
-      width === undefined || size.width === width,
-      'Deduced texture width does not match supplied width'
-    );
-    assert(
-      height === undefined || size.height === height,
-      'Deduced texture height does not match supplied height'
-    );
-
-    return size;
+    this.gl.bindTexture(this.glTarget, null);
   }
 
-  // CUBE MAP METHODS
+  // CLASSIC
 
-  /* eslint-disable max-statements, max-len */
-  async setCubeMapImageData(options: {
-    width: any;
-    height: any;
-    pixels: any;
-    data: any;
+  /*
+  setCubeMapData(options: {
+    width: number;
+    height: number;
+    data: Record<GL, Texture2DData> | Record<TextureCubeFace, Texture2DData>;
     format?: any;
     type?: any;
-  }): Promise<void> {
+    /** @deprecated Use .data *
+    pixels: any;
+  }): void {
     const {gl} = this;
 
     const {width, height, pixels, data, format = GL.RGBA, type = GL.UNSIGNED_BYTE} = options;
-    const imageDataMap = pixels || data;
 
     // pixel data (imageDataMap) is an Object from Face to Image or Promise.
     // For example:
@@ -805,13 +565,12 @@ export class WEBGLTexture extends Texture<WEBGLTextureProps> {
     // GL.TEXTURE_CUBE_MAP_NEGATIVE_X : [Image-or-Promise-LOD-0, Image-or-Promise-LOD-1],
     // ... }
 
-    const resolvedFaces = await Promise.all(
-      WEBGLTexture.FACES.map(face => {
-        const facePixels = imageDataMap[face];
-        return Promise.all(Array.isArray(facePixels) ? facePixels : [facePixels]);
-      })
-    );
+    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) => {
@@ -823,7 +582,7 @@ export class WEBGLTexture extends Texture<WEBGLTextureProps> {
       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);
+          gl.texImage2D(face, lodLevel, format, width, height, 0 /* border*, format, type, image);
         } else {
           gl.texImage2D(face, lodLevel, format, format, type, image);
         }
@@ -832,168 +591,70 @@ export class WEBGLTexture extends Texture<WEBGLTextureProps> {
 
     this.unbind();
   }
+  */
 
-  /** @todo update this method to accept LODs */
-  setImageDataForFace(options) {
-    const {
-      face,
-      width,
-      height,
-      pixels,
-      data,
-      format = GL.RGBA,
-      type = GL.UNSIGNED_BYTE
-      // generateMipmap = false // TODO
-    } = options;
+  // INTERNAL SETTERS
 
-    const {gl} = this;
-
-    const imageData = pixels || data;
-
-    this.bind();
-    if (imageData instanceof Promise) {
-      imageData.then(resolvedImageData =>
-        this.setImageDataForFace(
-          Object.assign({}, options, {
-            face,
-            data: resolvedImageData,
-            pixels: resolvedImageData
-          })
-        )
-      );
-    } else if (this.width || this.height) {
-      gl.texImage2D(face, 0, format, width, height, 0 /* border*/, format, type, imageData);
-    } else {
-      gl.texImage2D(face, 0, format, format, type, imageData);
+  /**
+   * Copy a region of data from a CPU memory buffer into this texture.
+   * @todo -   GLUnpackParameters parameters
+   */
+  protected _setMipLevel(
+    depth: number,
+    level: number,
+    textureData: Texture2DData,
+    glTarget: GL = this.glTarget
+  ) {
+    // if (!textureData) {
+    //   clearMipLevel(this.device.gl, {...this, depth, level});
+    //   return;
+    // }
+
+    if (Texture.isExternalImage(textureData)) {
+      copyCPUImageToMipLevel(this.device.gl, textureData, {...this, depth, level, glTarget});
+      return;
     }
 
-    return this;
-  }
-
-  /** Image 3D copies from Typed Array or WebGLBuffer */
-  setImageData3D(options: SetImageData3DOptions) {
-    const {
-      level = 0,
-      dataFormat,
-      format,
-      type, // = GL.UNSIGNED_BYTE,
-      width,
-      height,
-      depth = 1,
-      offset = 0,
-      data,
-      parameters = {}
-    } = options;
-
-    this.trackDeallocatedMemory('Texture');
-
-    this.gl.bindTexture(this.target, this.handle);
-
-    const webglTextureFormat = getWebGLTextureParameters(format);
-
-    withGLParameters(this.gl, parameters, () => {
-      if (ArrayBuffer.isView(data)) {
-        this.gl.texImage3D(
-          this.target,
-          level,
-          webglTextureFormat.format,
-          width,
-          height,
-          depth,
-          0 /* border, must be 0 */,
-          webglTextureFormat.dataFormat,
-          webglTextureFormat.type, // dataType: getWebGL,
-          data
-        );
-      }
-
-      if (data instanceof WEBGLBuffer) {
-        this.gl.bindBuffer(GL.PIXEL_UNPACK_BUFFER, data.handle);
-        this.gl.texImage3D(
-          this.target,
-          level,
-          dataFormat,
-          width,
-          height,
-          depth,
-          0 /* border, must be 0 */,
-          format,
-          type,
-          offset
-        );
-      }
-    });
-
-    if (data && data.byteLength) {
-      this.trackAllocatedMemory(data.byteLength, 'Texture');
-    } else {
-      const bytesPerPixel = getTextureFormatBytesPerPixel(this.props.format);
-      this.trackAllocatedMemory(this.width * this.height * this.depth * bytesPerPixel, 'Texture');
+    // @ts-expect-error
+    if (Texture.isTextureLevelData(textureData)) {
+      copyCPUDataToMipLevel(this.device.gl, textureData.data, {
+        ...this,
+        depth,
+        level,
+        glTarget
+      });
+      return;
     }
 
-    this.loaded = true;
+    throw new Error('Texture: invalid image data');
+  }
+  // HELPERS
 
-    return this;
+  getActiveUnit(): number {
+    return this.gl.getParameter(GL.ACTIVE_TEXTURE) - GL.TEXTURE0;
   }
 
-  // RESOURCE METHODS
+  bind(textureUnit?: number): number {
+    const {gl} = this;
 
-  /**
-   * Sets sampler parameters on texture
-   */
-  _setSamplerParameters(parameters: GLSamplerParameters): void {
-    // NPOT parameters may populate an empty object
-    if (isObjectEmpty(parameters)) {
-      return;
+    if (textureUnit !== undefined) {
+      this.textureUnit = textureUnit;
+      gl.activeTexture(gl.TEXTURE0 + textureUnit);
     }
 
-    logParameters(parameters);
-
-    this.gl.bindTexture(this.target, this.handle);
-    for (const [pname, pvalue] of Object.entries(parameters)) {
-      const param = Number(pname) as GL.TEXTURE_MIN_LOD | GL.TEXTURE_MAX_LOD;
-      const value = pvalue;
+    gl.bindTexture(this.glTarget, this.handle);
+    return textureUnit;
+  }
 
-      // Apparently there are integer/float conversion issues requires two parameter setting functions in JavaScript.
-      // For now, pick the float version for parameters specified as GLfloat.
-      switch (param) {
-        case GL.TEXTURE_MIN_LOD:
-        case GL.TEXTURE_MAX_LOD:
-          this.gl.texParameterf(this.target, param, value);
-          break;
+  unbind(textureUnit?: number): number | undefined {
+    const {gl} = this;
 
-        default:
-          this.gl.texParameteri(this.target, param, value);
-          break;
-      }
+    if (textureUnit !== undefined) {
+      this.textureUnit = textureUnit;
+      gl.activeTexture(gl.TEXTURE0 + textureUnit);
     }
-    this.gl.bindTexture(this.target, null);
-    return;
-  }
-}
 
-// HELPERS
-
-function getWebGLTextureTarget(props: TextureProps) {
-  switch (props.dimension) {
-    // supported in WebGL
-    case '2d':
-      return GL.TEXTURE_2D;
-    case 'cube':
-      return GL.TEXTURE_CUBE_MAP;
-    // supported in WebGL2
-    case '2d-array':
-      return GL.TEXTURE_2D_ARRAY;
-    case '3d':
-      return GL.TEXTURE_3D;
-    // not supported in any WebGL version
-    case '1d':
-    case 'cube-array':
-    default:
-      throw new Error(props.dimension);
+    gl.bindTexture(this.glTarget, null);
+    return textureUnit;
   }
 }
-
-function logParameters(parameters: Record<number, GL | number>) {
-  log.log(1, 'texture sampler parameters', parameters)();
-}