@luma.gl/webgl 9.1.9 → 9.2.0-alpha.2

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

@@ -8,39 +8,28 @@ import type {
   TextureViewProps,
   Sampler,
   SamplerProps,
-  SamplerParameters,
-  TextureCubeFace,
-  ExternalImage,
-  Texture1DData,
-  Texture2DData,
-  Texture3DData,
-  TextureCubeData,
-  TextureArrayData,
-  TextureCubeArrayData
+  CopyExternalImageOptions,
+  CopyImageDataOptions,
+  TypedArray
 } from '@luma.gl/core';
 import {Texture, log} from '@luma.gl/core';
 import {
   GL,
+  GLTextureTarget,
+  GLTextureCubeMapTarget,
+  GLTexelDataFormat,
   GLPixelType,
+  // GLDataType,
   GLSamplerParameters,
-  GLTexelDataFormat,
-  GLTextureTarget
+  GLValueParameters
 } from '@luma.gl/constants';
 import {getTextureFormatWebGL} from '../converters/webgl-texture-table';
 import {convertSamplerParametersToWebGL} from '../converters/sampler-parameters';
+import {withGLParameters} from '../../context/state-tracker/with-parameters';
 import {WebGLDevice} from '../webgl-device';
 import {WEBGLSampler} from './webgl-sampler';
 import {WEBGLTextureView} from './webgl-texture-view';
 
-import {
-  initializeTextureStorage,
-  // clearMipLevel,
-  copyExternalImageToMipLevel,
-  copyCPUDataToMipLevel,
-  // copyGPUBufferToMipLevel,
-  getWebGLTextureTarget
-} from '../helpers/webgl-texture-utils';
-
 /**
  * WebGL... the texture API from hell... hopefully made simpler
  */
@@ -50,14 +39,9 @@ export class WEBGLTexture extends Texture {
   readonly gl: WebGL2RenderingContext;
   handle: WebGLTexture;
 
-  sampler: WEBGLSampler = undefined; // TODO - currently unused in WebGL. Create dummy sampler?
-  view: WEBGLTextureView = undefined; // TODO - currently unused in WebGL. Create dummy view?
-
-  mipmaps: boolean;
-
-  // Texture type
-  /** Whether the internal format is compressed */
-  compressed: boolean;
+  // @ts-ignore TODO - currently unused in WebGL. Create dummy sampler?
+  sampler: WEBGLSampler = undefined;
+  view: WEBGLTextureView;
 
   /**
    * The WebGL target corresponding to the texture type
@@ -75,81 +59,62 @@ export class WEBGLTexture extends Texture {
   glType: GLPixelType;
   /** The WebGL constant corresponding to the WebGPU style constant in format */
   glInternalFormat: GL;
+  /** Whether the internal format is compressed */
+  compressed: boolean;
 
   // state
   /** Texture binding slot - TODO - move to texture view? */
-  textureUnit: number = 0;
+  _textureUnit: number = 0;
 
   constructor(device: Device, props: TextureProps) {
     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;
 
+    const formatInfo = getTextureFormatWebGL(this.props.format);
+
     // Note: In WebGL the texture target defines the type of texture on first bind.
     this.glTarget = getWebGLTextureTarget(this.props.dimension);
-
-    // The target format of this texture
-    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);
-
-    this._initialize(propsWithData);
-
-    Object.seal(this);
-  }
 
-  /** Initialize texture with supplied props */
-  // eslint-disable-next-line max-statements
-  _initialize(propsWithData: TextureProps): void {
     this.handle = this.props.handle || this.gl.createTexture();
-    this.device.setSpectorMetadata(this.handle, {...this.props, data: propsWithData.data});
-
-    let {width, height} = propsWithData;
-
-    if (!width || !height) {
-      const textureSize = Texture.getTextureDataSize(propsWithData.data);
-      width = textureSize?.width || 1;
-      height = textureSize?.height || 1;
+    this.device._setWebGLDebugMetadata(this.handle, this, {spector: this.props});
+
+    /**
+     * Use WebGL immutable texture storage to allocate and clear texture memory.
+     * - texStorage2D should be considered a preferred alternative to texImage2D. It may have lower memory costs than texImage2D in some implementations.
+     * - Once texStorage*D has been called, the texture is immutable and can only be updated with texSubImage*(), not texImage()
+     * @see https://registry.khronos.org/webgl/specs/latest/2.0/ WebGL 2 spec section 3.7.6
+     */
+    this.gl.bindTexture(this.glTarget, this.handle);
+    const {dimension, width, height, depth, mipLevels, glTarget, glInternalFormat} = this;
+    switch (dimension) {
+      case '2d':
+      case 'cube':
+        this.gl.texStorage2D(glTarget, mipLevels, glInternalFormat, width, height);
+        break;
+      case '2d-array':
+      case '3d':
+        this.gl.texStorage3D(glTarget, mipLevels, glInternalFormat, width, height, depth);
+        break;
+      default:
+        throw new Error(dimension);
     }
+    this.gl.bindTexture(this.glTarget, null);
 
-    // Store opts for accessors
-    this.width = width;
-    this.height = height;
-    this.depth = propsWithData.depth;
+    // Set data
+    this._initializeData(props.data);
 
     // Set texture sampler parameters
-    this.setSampler(propsWithData.sampler);
+    this.setSampler(this.props.sampler);
     // @ts-ignore TODO - fix types
     this.view = new WEBGLTextureView(this.device, {...this.props, texture: this});
 
-    this.bind();
-    initializeTextureStorage(this.gl, this.mipLevels, this);
-
-    if (propsWithData.data) {
-      // prettier-ignore
-      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(propsWithData.dimension);
-      }
-    }
-
-    if (this.mipmaps) {
-      this.generateMipmap();
-    }
+    Object.seal(this);
   }
 
   override destroy(): void {
@@ -166,245 +131,134 @@ export class WEBGLTexture extends Texture {
     return new WEBGLTextureView(this.device, {...props, texture: this});
   }
 
-  setSampler(sampler: Sampler | SamplerProps = {}): void {
-    let samplerProps: SamplerParameters;
-    if (sampler instanceof WEBGLSampler) {
-      this.sampler = sampler;
-      samplerProps = sampler.props;
-    } else {
-      this.sampler = new WEBGLSampler(this.device, sampler);
-      samplerProps = sampler as SamplerProps;
-    }
-
-    const parameters = convertSamplerParametersToWebGL(samplerProps);
+  override setSampler(sampler: Sampler | SamplerProps = {}): void {
+    super.setSampler(sampler);
+    // Apply sampler parameters to texture
+    const parameters = convertSamplerParametersToWebGL(this.sampler.props);
     this._setSamplerParameters(parameters);
   }
 
-  // Call to regenerate mipmaps after modifying texture(s)
-  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;
+  copyImageData(options_: CopyImageDataOptions): void {
+    const options = this._normalizeCopyImageDataOptions(options_);
+
+    const typedArray = options.data as TypedArray;
+    const {width, height, depth} = this;
+    const {mipLevel = 0, byteOffset = 0, x = 0, y = 0, z = 0} = options;
+    const {glFormat, glType, compressed} = this;
+    const glTarget = getWebGLCubeFaceTarget(this.glTarget, this.dimension, depth);
+
+    // WebGL automatically ignores these for compressed textures, but we are careful
+    const glParameters: GLValueParameters = !this.compressed
+      ? {
+          [GL.UNPACK_ROW_LENGTH]: options.bytesPerRow,
+          [GL.UNPACK_IMAGE_HEIGHT]: options.rowsPerImage
+        }
+      : {};
+
+    this.gl.bindTexture(glTarget, this.handle);
+
+    withGLParameters(this.gl, glParameters, () => {
+      switch (this.dimension) {
+        case '2d':
+        case 'cube':
+          if (compressed) {
+            // prettier-ignore
+            this.gl.compressedTexSubImage2D(glTarget, mipLevel, x, y, width, height, glFormat, typedArray, byteOffset); // , byteLength
+          } else {
+            // prettier-ignore
+            this.gl.texSubImage2D(glTarget, mipLevel, x, y, width, height, glFormat, glType, typedArray, byteOffset); // , byteLength
+          }
+          break;
+        case '2d-array':
+        case '3d':
+          if (compressed) {
+            // prettier-ignore
+            this.gl.compressedTexSubImage3D(glTarget, mipLevel, x, y, z, width, height, depth, glFormat, typedArray, byteOffset); // , byteLength
+          } else {
+            // prettier-ignore
+            this.gl.texSubImage3D(glTarget, mipLevel, x, y, z, width, height, depth, glFormat, glType, typedArray, byteOffset); // , byteLength
+          }
+          break;
+        default:
+        // Can never happen in WebGL
       }
-    }
+    });
 
-    try {
-      this.gl.bindTexture(this.glTarget, this.handle);
-      this.gl.generateMipmap(this.glTarget);
-    } catch (error) {
-      log.warn(`Error generating mipmap for ${this}: ${(error as Error).message}`)();
-    } finally {
-      this.gl.bindTexture(this.glTarget, null);
-    }
+    this.gl.bindTexture(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);
+  copyExternalImage(options_: CopyExternalImageOptions): {width: number; height: number} {
+    const options = this._normalizeCopyExternalImageOptions(options_);
 
     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.');
-  }
-
-  /** Set a simple texture */
-  setTexture2DData(lodData: Texture2DData, depth = 0): void {
-    this.bind();
-
-    const lodArray = Texture.normalizeTextureData(lodData, this);
-
-    // 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.`)();
-    }
-
-    for (let lodLevel = 0; lodLevel < lodArray.length; lodLevel++) {
-      const imageData = lodArray[lodLevel];
-      this._setMipLevel(depth, lodLevel, imageData);
-    }
-
-    this.unbind();
-  }
-
-  /**
-   * Sets a 3D texture
-   * @param data
-   */
-  setTexture3DData(data: Texture3DData): void {
-    if (this.props.dimension !== '3d') {
-      throw new Error(this.id);
-    }
-    if (ArrayBuffer.isView(data)) {
-      this.bind();
-      copyCPUDataToMipLevel(this.device.gl, data, this);
-      this.unbind();
-    }
-  }
-
-  /**
-   * 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);
-    }
-  }
-
-  /**
-   * Sets an entire texture array
-   * @param data
-   */
-  setTextureArrayData(data: TextureArrayData): void {
-    if (this.props.dimension !== '2d-array') {
-      throw new Error(this.id);
-    }
-    throw new Error('setTextureArrayData not implemented.');
-  }
-
-  /**
-   * Sets an entire texture cube array
-   * @param data
-   */
-  setTextureCubeArrayData(data: TextureCubeArrayData): void {
-    throw new Error('setTextureCubeArrayData not supported in WebGL2.');
-  }
-
-  setTextureCubeFaceData(lodData: Texture2DData, face: TextureCubeFace, depth: number = 0): void {
-    // assert(this.props.dimension === 'cube');
+    const {glFormat, glType} = this;
+    const {image, depth, mipLevel, x, y, z, width, height} = options;
 
-    // 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.`)();
-    }
+    // WebGL cube maps specify faces by overriding target instead of using the depth parameter
+    const glTarget = getWebGLCubeFaceTarget(this.glTarget, this.dimension, depth);
+    const glParameters: GLValueParameters = options.flipY ? {[GL.UNPACK_FLIP_Y_WEBGL]: true} : {};
 
-    const faceDepth = Texture.CubeFaces.indexOf(face);
+    this.gl.bindTexture(this.glTarget, this.handle);
 
-    this.setTexture2DData(lodData, faceDepth);
-  }
+    withGLParameters(this.gl, glParameters, () => {
+      switch (this.dimension) {
+        case '2d':
+        case 'cube':
+          // prettier-ignore
+          this.gl.texSubImage2D(glTarget, mipLevel, x, y, width, height, glFormat, glType, image);
+          break;
+        case '2d-array':
+        case '3d':
+          // prettier-ignore
+          this.gl.texSubImage3D(glTarget, mipLevel, x, y, z, width, height, depth, glFormat, glType, image);
+          break;
+        default:
+        // Can never happen in WebGL
+      }
+    });
 
-  // DEPRECATED METHODS
+    this.gl.bindTexture(this.glTarget, null);
 
-  /** Update external texture (video frame or canvas) @deprecated Use ExternalTexture */
-  update(): void {
-    throw new Error('Texture.update() not implemented. Use ExternalTexture');
+    return {width: options.width, height: options.height};
   }
 
-  // INTERNAL METHODS
-
-  /** @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;
-
-    const {gl} = this;
+  // WEBGL SPECIFIC
 
-    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);
+  generateMipmapsWebGL(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;
+      }
     }
-  }
 
-  _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];
-      }
+    try {
+      this.gl.bindTexture(this.glTarget, this.handle);
+      this.gl.generateMipmap(this.glTarget);
+    } catch (error) {
+      log.warn(`Error generating mipmap for ${this}: ${(error as Error).message}`)();
+    } finally {
+      this.gl.bindTexture(this.glTarget, null);
     }
-    return faceData;
   }
 
-  // RESOURCE METHODS
+  // INTERNAL
 
   /**
    * Sets sampler parameters on texture
    */
   _setSamplerParameters(parameters: GLSamplerParameters): void {
-    log.log(1, `${this.id} sampler parameters`, this.device.getGLKeys(parameters))();
+    log.log(2, `${this.id} sampler parameters`, this.device.getGLKeys(parameters))();
 
     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;
@@ -417,21 +271,26 @@ export class WEBGLTexture extends Texture {
           this.gl.texParameterf(this.glTarget, param, value);
           break;
 
+        case GL.TEXTURE_MAG_FILTER:
         case GL.TEXTURE_MIN_FILTER:
           this.gl.texParameteri(this.glTarget, param, value);
           break;
 
         case GL.TEXTURE_WRAP_S:
         case GL.TEXTURE_WRAP_T:
+        case GL.TEXTURE_WRAP_R:
           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:
+
+        case GL.TEXTURE_COMPARE_MODE:
+        case GL.TEXTURE_COMPARE_FUNC:
           this.gl.texParameteri(this.glTarget, param, value);
           break;
       }
@@ -439,132 +298,63 @@ export class WEBGLTexture extends Texture {
 
     this.gl.bindTexture(this.glTarget, null);
   }
-
-  // INTERNAL SETTERS
-
-  /**
-   * Copy a region of data from a CPU memory buffer into this texture.
-   * @todo -   GLUnpackParameters parameters
-   */
-  protected _setMipLevel(
-    depth: number,
-    mipLevel: number,
-    textureData: Texture2DData,
-    glTarget: GL = this.glTarget
-  ) {
-    // if (!textureData) {
-    //   clearMipLevel(this.device.gl, {...this, depth, level});
-    //   return;
-    // }
-
-    if (Texture.isExternalImage(textureData)) {
-      copyExternalImageToMipLevel(this.device.gl, this.handle, textureData, {
-        ...this,
-        depth,
-        mipLevel,
-        glTarget,
-        flipY: this.props.flipY
-      });
-      return;
-    }
-
-    // @ts-expect-error
-    if (Texture.isTextureLevelData(textureData)) {
-      copyCPUDataToMipLevel(this.device.gl, textureData.data, {
-        ...this,
-        depth,
-        mipLevel,
-        glTarget
-      });
-      return;
-    }
-
-    throw new Error('Texture: invalid image data');
-  }
-  // HELPERS
-
-  getActiveUnit(): number {
+  _getActiveUnit(): number {
     return this.gl.getParameter(GL.ACTIVE_TEXTURE) - GL.TEXTURE0;
   }
 
-  bind(textureUnit?: number): number {
+  _bind(_textureUnit?: number): number {
     const {gl} = this;
 
-    if (textureUnit !== undefined) {
-      this.textureUnit = textureUnit;
-      gl.activeTexture(gl.TEXTURE0 + textureUnit);
+    if (_textureUnit !== undefined) {
+      this._textureUnit = _textureUnit;
+      gl.activeTexture(gl.TEXTURE0 + _textureUnit);
     }
 
     gl.bindTexture(this.glTarget, this.handle);
-    return textureUnit;
+    // @ts-ignore TODO fix types
+    return _textureUnit;
   }
 
-  unbind(textureUnit?: number): number | undefined {
+  _unbind(_textureUnit?: number): number | undefined {
     const {gl} = this;
 
-    if (textureUnit !== undefined) {
-      this.textureUnit = textureUnit;
-      gl.activeTexture(gl.TEXTURE0 + textureUnit);
+    if (_textureUnit !== undefined) {
+      this._textureUnit = _textureUnit;
+      gl.activeTexture(gl.TEXTURE0 + _textureUnit);
     }
 
     gl.bindTexture(this.glTarget, null);
-    return textureUnit;
+    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);
-      }
-    });
-  });
+// INTERNAL HELPERS
+
+/** Convert a WebGPU style texture constant to a WebGL style texture constant */
+export function getWebGLTextureTarget(
+  dimension: '1d' | '2d' | '2d-array' | 'cube' | 'cube-array' | '3d'
+): GLTextureTarget {
+  // prettier-ignore
+  switch (dimension) {
+    case '1d': break; // not supported in any WebGL version
+    case '2d': return GL.TEXTURE_2D; // supported in WebGL1
+    case '3d': return GL.TEXTURE_3D; // supported in WebGL2
+    case 'cube': return GL.TEXTURE_CUBE_MAP; // supported in WebGL1
+    case '2d-array': return GL.TEXTURE_2D_ARRAY; // supported in WebGL2
+    case 'cube-array': break; // not supported in any WebGL version
+  }
+  throw new Error(dimension);
+}
 
-  this.unbind();
+/**
+ * In WebGL, cube maps specify faces by overriding target instead of using the depth parameter.
+ * @note We still bind the texture using GL.TEXTURE_CUBE_MAP, but we need to use the face-specific target when setting mip levels.
+ * @returns glTarget unchanged, if dimension !== 'cube'.
+ */
+export function getWebGLCubeFaceTarget(
+  glTarget: GLTextureTarget,
+  dimension: '1d' | '2d' | '2d-array' | 'cube' | 'cube-array' | '3d',
+  level: number
+): GLTextureTarget | GLTextureCubeMapTarget {
+  return dimension === 'cube' ? GL.TEXTURE_CUBE_MAP_POSITIVE_X + level : glTarget;
 }
-*/