@luma.gl/webgl 9.1.0-beta.8 → 9.2.0-alpha.1

package/src/adapter/helpers/webgl-texture-utils.ts

@@ -2,13 +2,10 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-//
-// WebGL... the texture API from hell... hopefully made simpler
-//
+// @ts-nocheck This file will be deleted in upcoming refactor
 
-import {TypedArray} from '@math.gl/types';
-import type {ExternalImage} from '@luma.gl/core';
-import {Buffer, Texture, Framebuffer, FramebufferProps} from '@luma.gl/core';
+import type {Buffer, Texture, FramebufferProps} from '@luma.gl/core';
+import {Framebuffer, getTypedArrayFromDataType, getDataTypeFromTypedArray} from '@luma.gl/core';
 import {
   GL,
   GLTextureTarget,
@@ -18,12 +15,12 @@ import {
   GLDataType
 } from '@luma.gl/constants';
 
+import {convertDataTypeToGLDataType} from '../converters/webgl-shadertypes';
 import {WEBGLFramebuffer} from '../resources/webgl-framebuffer';
-import {getGLTypeFromTypedArray, getTypedArrayFromGLType} from './typed-array-utils';
 import {glFormatToComponents, glTypeToBytes} from './format-utils';
 import {WEBGLBuffer} from '../resources/webgl-buffer';
 import {WEBGLTexture} from '../resources/webgl-texture';
-import {withGLParameters} from '../../context/state-tracker/with-parameters';
+import {convertGLDataTypeToDataType} from '../converters/shader-formats';
 
 /** A "border" parameter is required in many WebGL texture APIs, but must always be 0... */
 const BORDER = 0;
@@ -83,120 +80,6 @@ export type WebGLCopyTextureOptions = {
   byteLength?: number;
 };
 
-/**
- * Initializes a texture memory space
- * Clear all the textures and mip levels of a two-dimensional or array texture at the same time.
- * On some implementations faster than repeatedly setting levels
- *
- * @note From WebGL 2 spec section 3.7.6:
- * @see https://registry.khronos.org/webgl/specs/latest/2.0/
- * - The image contents are set as if a buffer of sufficient size initialized to 0 would be passed to each level's texImage2D/3D
- * - 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()
- */
-export function initializeTextureStorage(
-  gl: WebGL2RenderingContext,
-  levels: number,
-  options: WebGLSetTextureOptions
-): void {
-  const {dimension, width, height, depth = 0} = options;
-  const {glInternalFormat} = options;
-  const glTarget = options.glTarget; // getWebGLCubeFaceTarget(options.glTarget, dimension, depth);
-  switch (dimension) {
-    case '2d-array':
-    case '3d':
-      gl.texStorage3D(glTarget, levels, glInternalFormat, width, height, depth);
-      break;
-
-    default:
-      gl.texStorage2D(glTarget, levels, glInternalFormat, width, height);
-  }
-}
-
-/**
- * Copy a region of compressed data from a GPU memory buffer into this texture.
- */
-export function copyExternalImageToMipLevel(
-  gl: WebGL2RenderingContext,
-  handle: WebGLTexture,
-  image: ExternalImage,
-  options: WebGLCopyTextureOptions & {flipY?: boolean}
-): void {
-  const {width, height} = options;
-  const {dimension, depth = 0, mipLevel = 0} = options;
-  const {x = 0, y = 0, z = 0} = options;
-  const {glFormat, glType} = options;
-
-  const glTarget = getWebGLCubeFaceTarget(options.glTarget, dimension, depth);
-
-  const glParameters = options.flipY ? {[GL.UNPACK_FLIP_Y_WEBGL]: true} : {};
-  withGLParameters(gl, glParameters, () => {
-    switch (dimension) {
-      case '2d-array':
-      case '3d':
-        gl.bindTexture(glTarget, handle);
-        // prettier-ignore
-        gl.texSubImage3D(glTarget, mipLevel, x, y, z, width, height, depth, glFormat, glType, image);
-        gl.bindTexture(glTarget, null);
-        break;
-
-      case '2d':
-      case 'cube':
-        gl.bindTexture(glTarget, handle);
-        // prettier-ignore
-        gl.texSubImage2D(glTarget, mipLevel, x, y, width, height, glFormat, glType, image);
-        gl.bindTexture(glTarget, null);
-        break;
-
-      default:
-        throw new Error(dimension);
-    }
-  });
-}
-
-/**
- * Copy a region of data from a CPU memory buffer into this texture.
- */
-export function copyCPUDataToMipLevel(
-  gl: WebGL2RenderingContext,
-  typedArray: TypedArray,
-  options: WebGLCopyTextureOptions
-): void {
-  const {dimension, width, height, depth = 0, mipLevel = 0, byteOffset = 0} = options;
-  const {x = 0, y = 0, z = 0} = options;
-  const {glFormat, glType, compressed} = options;
-  const glTarget = getWebGLCubeFaceTarget(options.glTarget, dimension, depth);
-
-  // gl.bindTexture(glTarget, null);
-
-  switch (dimension) {
-    case '2d-array':
-    case '3d':
-      if (compressed) {
-        // prettier-ignore
-        gl.compressedTexSubImage3D(glTarget, mipLevel, x, y, z, width, height, depth, glFormat, typedArray, byteOffset); // , byteLength
-      } else {
-        // prettier-ignore
-        gl.texSubImage3D(glTarget, mipLevel, x, y, z, width, height, depth, glFormat, glType, typedArray, byteOffset); // , byteLength
-      }
-      break;
-
-    case '2d':
-    case 'cube':
-      if (compressed) {
-        // prettier-ignore
-        gl.compressedTexSubImage2D(glTarget, mipLevel, x, y, width, height, glFormat, typedArray, byteOffset); // , byteLength
-      } else {
-        // prettier-ignore
-        gl.texSubImage2D(glTarget, mipLevel, x, y, width, height, glFormat, glType, typedArray, byteOffset); // , byteLength
-      }
-      break;
-
-    default:
-      throw new Error(dimension);
-  }
-}
-
 /**
  * Copy a region of compressed data from a GPU memory buffer into this texture.
  */
@@ -570,7 +453,8 @@ export function readPixelsToArray(
   target = getPixelArray(target, sourceType, sourceFormat, sourceWidth, sourceHeight, sourceDepth);
 
   // Pixel array available, if necessary, deduce type from it.
-  sourceType = sourceType || getGLTypeFromTypedArray(target);
+  const signedType = getDataTypeFromTypedArray(target);
+  sourceType = sourceType || convertDataTypeToGLDataType(signedType);
 
   // Note: luma.gl overrides bindFramebuffer so that we can reliably restore the previous framebuffer (this is the only function for which we do that)
   const prevHandle = gl.bindFramebuffer(
@@ -717,7 +601,7 @@ export function copyToTexture(
     texture = destinationTexture;
     width = Number.isFinite(width) ? width : texture.width;
     height = Number.isFinite(height) ? height : texture.height;
-    texture?.bind(0);
+    texture?._bind(0);
     // @ts-ignore
     textureTarget = texture.target;
   } else {
@@ -769,7 +653,7 @@ export function copyToTexture(
     }
   }
   if (texture) {
-    texture.unbind();
+    texture._unbind();
   }
   // @ts-expect-error
   device.gl.bindFramebuffer(GL.FRAMEBUFFER, prevHandle || null);
@@ -817,10 +701,11 @@ function getPixelArray(
   if (pixelArray) {
     return pixelArray;
   }
-  // const formatInfo = decodeTextureFormat(format);
+  // const formatInfo = getTextureFormatInfo(format);
   // Allocate pixel array if not already available, using supplied type
   glType ||= GL.UNSIGNED_BYTE;
-  const ArrayType = getTypedArrayFromGLType(glType, {clamped: false});
+  const shaderType = convertGLDataTypeToDataType(glType);
+  const ArrayType = getTypedArrayFromDataType(shaderType);
   const components = glFormatToComponents(glFormat);
   // TODO - check for composite type (components = 1).
   return new ArrayType(width * height * components) as Uint8Array | Uint16Array | Float32Array;

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

@@ -21,9 +21,9 @@ export class WEBGLBuffer extends Buffer {
   readonly glIndexType: GL.UNSIGNED_SHORT | GL.UNSIGNED_INT = GL.UNSIGNED_SHORT;
 
   /** Number of bytes allocated on the GPU for this buffer */
-  byteLength: number;
+  byteLength: number = 0;
   /** Number of bytes used */
-  bytesUsed: number;
+  bytesUsed: number = 0;
 
   constructor(device: WebGLDevice, props: BufferProps = {}) {
     super(device, props);

package/src/adapter/resources/webgl-command-buffer.ts

@@ -73,7 +73,7 @@ export class WEBGLCommandBuffer extends CommandBuffer {
     this.device = device;
   }
 
-  submitCommands(commands: Command[] = this.commands) {
+  _executeCommands(commands: Command[] = this.commands) {
     for (const command of commands) {
       switch (command.name) {
         case 'copy-buffer-to-buffer':
@@ -285,13 +285,13 @@ function _copyTextureToTexture(device: WebGLDevice, options: CopyTextureToTextur
   // TODO - support gl.readBuffer (WebGL2 only)
   // const prevBuffer = gl.readBuffer(attachment);
 
-  let texture: WEBGLTexture = null;
+  let texture: WEBGLTexture;
   let textureTarget: GL;
   if (destinationTexture instanceof WEBGLTexture) {
     texture = destinationTexture;
     width = Number.isFinite(width) ? width : texture.width;
     height = Number.isFinite(height) ? height : texture.height;
-    texture.bind(0);
+    texture._bind(0);
     textureTarget = texture.glTarget;
   } else {
     throw new Error('invalid destination');
@@ -329,7 +329,7 @@ function _copyTextureToTexture(device: WebGLDevice, options: CopyTextureToTextur
   }
 
   if (texture) {
-    texture.unbind();
+    texture._unbind();
   }
   device.gl.bindFramebuffer(GL.FRAMEBUFFER, prevHandle);
   if (destroyFramebuffer) {
@@ -413,7 +413,7 @@ function getFramebuffer(source: Texture | Framebuffer): {
  * Returns number of components in a specific readPixels WebGL format
  * @todo use shadertypes utils instead?
  */
-export function glFormatToComponents(format): 1 | 2 | 3 | 4 {
+export function glFormatToComponents(format: GL): 1 | 2 | 3 | 4 {
   switch (format) {
     case GL.ALPHA:
     case GL.R32F:

package/src/adapter/resources/webgl-command-encoder.ts

@@ -4,21 +4,26 @@
 
 import {CommandEncoder, CommandEncoderProps} from '@luma.gl/core';
 import type {
+  RenderPassProps,
+  ComputePass,
+  ComputePassProps,
+  QuerySet,
+  Buffer,
   CopyBufferToBufferOptions,
   CopyBufferToTextureOptions,
   CopyTextureToBufferOptions,
-  CopyTextureToTextureOptions,
+  CopyTextureToTextureOptions
   // ClearTextureOptions,
   // ReadTextureOptions,
-  QuerySet,
-  Buffer
 } from '@luma.gl/core';
 
 import {WEBGLCommandBuffer} from './webgl-command-buffer';
+import {WEBGLRenderPass} from './webgl-render-pass';
 import {WebGLDevice} from '../webgl-device';
 
 export class WEBGLCommandEncoder extends CommandEncoder {
   readonly device: WebGLDevice;
+  readonly handle = null;
 
   readonly commandBuffer: WEBGLCommandBuffer;
 
@@ -30,13 +35,17 @@ export class WEBGLCommandEncoder extends CommandEncoder {
 
   override destroy(): void {}
 
-  override finish(): void {
-    this.commandBuffer.submitCommands();
+  override finish(): WEBGLCommandBuffer {
+    return this.commandBuffer;
   }
 
-  // beginRenderPass(GPURenderPassDescriptor descriptor): GPURenderPassEncoder;
-  // beginComputePass(optional GPUComputePassDescriptor descriptor = {}): GPUComputePassEncoder;
-  // finish(options?: {id?: string}): GPUCommandBuffer;
+  beginRenderPass(props: RenderPassProps): WEBGLRenderPass {
+    return new WEBGLRenderPass(this.device, props);
+  }
+
+  beginComputePass(props: ComputePassProps): ComputePass {
+    throw new Error('ComputePass not supported in WebGL');
+  }
 
   copyBufferToBuffer(options: CopyBufferToBufferOptions): void {
     this.commandBuffer.commands.push({name: 'copy-buffer-to-buffer', options});

package/src/adapter/resources/webgl-query-set.ts

@@ -27,7 +27,11 @@ export class WEBGLQuerySet extends QuerySet {
       throw new Error('WebGL QuerySet can only have one value');
     }
 
-    this.handle = this.device.gl.createQuery();
+    const handle = this.device.gl.createQuery();
+    if (!handle) {
+      throw new Error('WebGL query not supported');
+    }
+    this.handle = handle;
     Object.seal(this);
   }
 

package/src/adapter/resources/webgl-render-pass.ts

@@ -11,20 +11,20 @@ import {setGLParameters} from '../../context/parameters/unified-parameter-api';
 import {WEBGLQuerySet} from './webgl-query-set';
 import {WEBGLFramebuffer} from './webgl-framebuffer';
 
-const COLOR_CHANNELS = [0x1, 0x2, 0x4, 0x8]; // GPUColorWrite RED, GREEN, BLUE, ALPHA
+const COLOR_CHANNELS: NumberArray4 = [0x1, 0x2, 0x4, 0x8]; // GPUColorWrite RED, GREEN, BLUE, ALPHA
 
 export class WEBGLRenderPass extends RenderPass {
   readonly device: WebGLDevice;
 
   /** Parameters that should be applied before each draw call */
-  glParameters: GLParameters;
+  glParameters: GLParameters = {};
 
   constructor(device: WebGLDevice, props: RenderPassProps) {
     super(device, props);
     this.device = device;
 
     // If no viewport is provided, apply reasonably defaults
-    let viewport;
+    let viewport: NumberArray4 | undefined;
     if (!props?.parameters?.viewport) {
       if (props?.framebuffer) {
         // Set the viewport to the size of the framebuffer
@@ -44,7 +44,7 @@ export class WEBGLRenderPass extends RenderPass {
     // Specify mapping of draw buffer locations to color attachments
     const webglFramebuffer = this.props.framebuffer as WEBGLFramebuffer;
     // Default framebuffers can only be set to GL.BACK or GL.NONE
-    if (webglFramebuffer?.handle) {
+    if (this.props.framebuffer && webglFramebuffer?.handle) {
       const drawBuffers = this.props.framebuffer.colorAttachments.map(
         (_, i) => GL.COLOR_ATTACHMENT0 + i
       );
@@ -93,7 +93,10 @@ export class WEBGLRenderPass extends RenderPass {
       // WebGPU viewports are 6 coordinates (X, Y, Z)
       if (parameters.viewport.length >= 6) {
         glParameters.viewport = parameters.viewport.slice(0, 4) as NumberArray4;
-        glParameters.depthRange = [parameters.viewport[4], parameters.viewport[5]];
+        glParameters.depthRange = [
+          parameters.viewport[4] as number,
+          parameters.viewport[5] as number
+        ];
       } else {
         // WebGL viewports are 4 coordinates (X, Y)
         glParameters.viewport = parameters.viewport as NumberArray4;
@@ -111,12 +114,12 @@ export class WEBGLRenderPass extends RenderPass {
       console.warn('RenderPassParameters.stencilReference not yet implemented in WebGL');
       // parameters.stencilFunc = [func, ref, mask];
       // Does this work?
-      parameters[GL.STENCIL_REF] = parameters.stencilReference;
+      glParameters[GL.STENCIL_REF] = parameters.stencilReference;
     }
 
-    if (parameters.colorMask) {
+    if ('colorMask' in parameters) {
       glParameters.colorMask = COLOR_CHANNELS.map(channel =>
-        Boolean(channel & parameters.colorMask)
+        Boolean(channel & (parameters.colorMask as number))
       );
     }
 

package/src/adapter/resources/webgl-render-pipeline.ts

@@ -16,10 +16,9 @@ import {RenderPipeline, log} from '@luma.gl/core';
 // import {getAttributeInfosFromLayouts} from '@luma.gl/core';
 import {GL} from '@luma.gl/constants';
 
-import {getShaderLayoutFromGLSL} from '../helpers/get-shader-layout';
+import {getShaderLayoutFromGLSL} from '../helpers/get-shader-layout-from-glsl';
 import {withDeviceAndGLParameters} from '../converters/device-parameters';
 import {setUniform} from '../helpers/set-uniform';
-import {splitUniformsAndBindings} from '../../utils/split-uniforms-and-bindings';
 // import {copyUniform, checkUniformValues} from '../../classes/uniforms';
 
 import {WebGLDevice} from '../webgl-device';
@@ -87,7 +86,9 @@ export class WEBGLRenderPipeline extends RenderPipeline {
     log.timeEnd(3, `RenderPipeline ${this.id} - shaderLayout introspection`)();
 
     // Merge provided layout with introspected layout
-    this.shaderLayout = mergeShaderLayout(this.introspectedLayout, props.shaderLayout);
+    this.shaderLayout = props.shaderLayout
+      ? mergeShaderLayout(this.introspectedLayout, props.shaderLayout)
+      : this.introspectedLayout;
   }
 
   override destroy(): void {
@@ -98,6 +99,7 @@ export class WEBGLRenderPipeline extends RenderPipeline {
       this.destroyed = true;
       // @ts-expect-error
       this.handle.destroyed = true;
+      // @ts-ignore
       this.handle = null;
     }
   }
@@ -150,7 +152,7 @@ export class WEBGLRenderPipeline extends RenderPipeline {
               value instanceof WEBGLFramebuffer
             )
           ) {
-            throw new Error('texture value');
+            throw new Error(`${this} Bad texture binding for ${name}`);
           }
           break;
         case 'sampler':
@@ -276,21 +278,6 @@ export class WEBGLRenderPipeline extends RenderPipeline {
     return true;
   }
 
-  // DEPRECATED METHODS
-
-  override setUniformsWebGL(uniforms: Record<string, UniformValue>) {
-    const {bindings} = splitUniformsAndBindings(uniforms);
-    Object.keys(bindings).forEach(name => {
-      log.warn(
-        `Unsupported value "${JSON.stringify(
-          bindings[name]
-        )}" used in setUniforms() for key ${name}. Use setBindings() instead?`
-      )();
-    });
-    // TODO - check against layout
-    Object.assign(this.uniforms, uniforms);
-  }
-
   // PRIVATE METHODS
 
   // setAttributes(attributes: Record<string, Buffer>): void {}
@@ -324,19 +311,21 @@ export class WEBGLRenderPipeline extends RenderPipeline {
   }
 
   /** Report link status. First, check for shader compilation failures if linking fails */
-  async _reportLinkStatus(status: 'success' | 'linking' | 'validation'): Promise<void> {
+  async _reportLinkStatus(status: 'success' | 'link-error' | 'validation-error'): Promise<void> {
     switch (status) {
       case 'success':
         return;
 
       default:
+        const errorType = status === 'link-error' ? 'Link error' : 'Validation error';
         // First check for shader compilation failures if linking fails
         switch (this.vs.compilationStatus) {
           case 'error':
             this.vs.debugShader();
-            throw new Error(`Error during compilation of shader ${this.vs.id}`);
+            throw new Error(`${this} ${errorType} during compilation of ${this.vs}`);
           case 'pending':
-            this.vs.asyncCompilationStatus.then(() => this.vs.debugShader());
+            await this.vs.asyncCompilationStatus;
+            this.vs.debugShader();
             break;
           case 'success':
             break;
@@ -345,16 +334,17 @@ export class WEBGLRenderPipeline extends RenderPipeline {
         switch (this.fs?.compilationStatus) {
           case 'error':
             this.fs.debugShader();
-            throw new Error(`Error during compilation of shader ${this.fs.id}`);
+            throw new Error(`${this} ${errorType} during compilation of ${this.fs}`);
           case 'pending':
-            this.fs.asyncCompilationStatus.then(() => this.fs.debugShader());
+            await this.fs.asyncCompilationStatus;
+            this.fs.debugShader();
             break;
           case 'success':
             break;
         }
 
         const linkErrorLog = this.device.gl.getProgramInfoLog(this.handle);
-        throw new Error(`Error during ${status}: ${linkErrorLog}`);
+        this.device.reportError(new Error(`${errorType} during ${status}: ${linkErrorLog}`));
     }
   }
 
@@ -363,19 +353,19 @@ export class WEBGLRenderPipeline extends RenderPipeline {
    * TODO - Load log even when no error reported, to catch warnings?
    * https://gamedev.stackexchange.com/questions/30429/how-to-detect-glsl-warnings
    */
-  _getLinkStatus(): 'success' | 'linking' | 'validation' {
+  _getLinkStatus(): 'success' | 'link-error' | 'validation-error' {
     const {gl} = this.device;
-    const linked = gl.getProgramParameter(this.handle, gl.LINK_STATUS);
+    const linked = gl.getProgramParameter(this.handle, GL.LINK_STATUS);
     if (!linked) {
       this.linkStatus = 'error';
-      return 'linking';
+      return 'link-error';
     }
 
     gl.validateProgram(this.handle);
-    const validated = gl.getProgramParameter(this.handle, gl.VALIDATE_STATUS);
+    const validated = gl.getProgramParameter(this.handle, GL.VALIDATE_STATUS);
     if (!validated) {
       this.linkStatus = 'error';
-      return 'validation';
+      return 'validation-error';
     }
 
     this.linkStatus = 'success';

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

@@ -21,7 +21,7 @@ export class WEBGLSampler extends Sampler {
     super(device, props);
     this.device = device;
     this.parameters = convertSamplerParametersToWebGL(props);
-    this.handle = this.handle || this.device.gl.createSampler();
+    this.handle = props.handle || this.device.gl.createSampler();
     this._setSamplerParameters(this.parameters);
   }
 

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

@@ -46,7 +46,10 @@ export class WEBGLShader extends Shader {
   }
 
   get asyncCompilationStatus(): Promise<'pending' | 'success' | 'error'> {
-    return this._waitForCompilationComplete().then(() => this.compilationStatus);
+    return this._waitForCompilationComplete().then(() => {
+      this._getCompilationStatus();
+      return this.compilationStatus;
+    });
   }
 
   override async getCompilationInfo(): Promise<readonly CompilerMessage[]> {

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

@@ -3,7 +3,7 @@
 // Copyright (c) vis.gl contributors
 
 import type {Device, TextureViewProps} from '@luma.gl/core';
-// import {decodeTextureFormat} from '@luma.gl/core';
+// import {getTextureFormatInfo} from '@luma.gl/core';
 import {TextureView, Texture} from '@luma.gl/core';
 
 import {WebGLDevice} from '../webgl-device';