@luma.gl/webgl 9.0.0-beta.4 → 9.0.0-beta.6

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

@@ -1,4 +1,5 @@
-// luma.gl, MIT license
+// luma.gl
+// SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
 import type {UniformValue, RenderPipelineProps, Binding} from '@luma.gl/core';
@@ -19,7 +20,7 @@ import {WEBGLBuffer} from './webgl-buffer';
 import {WEBGLShader} from './webgl-shader';
 import {WEBGLFramebuffer} from './webgl-framebuffer';
 import {WEBGLTexture} from './webgl-texture';
-// import {WEBGLVertexArray} from './webgl-vertex-array';
+import {WEBGLTextureView} from './webgl-texture-view';
 import {WEBGLRenderPass} from './webgl-render-pass';
 import {WEBGLTransformFeedback} from './webgl-transform-feedback';
 import {getGLDrawMode} from '../helpers/webgl-topology-utils';
@@ -65,14 +66,16 @@ export class WEBGLRenderPipeline extends RenderPipeline {
     // @ts-expect-error WebGL only
     const {varyings, bufferMode = GL.SEPARATE_ATTRIBS} = props;
     if (varyings && varyings.length > 0) {
-      this.device.assertWebGL2();
       this.varyings = varyings;
-      this.device.gl2?.transformFeedbackVaryings(this.handle, varyings, bufferMode);
+      this.device.gl.transformFeedbackVaryings(this.handle, varyings, bufferMode);
     }
 
-    this._compileAndLink();
+    this._linkShaders();
 
+    log.time(0, `RenderPipeline ${this.id} - shaderLayout introspection`)();
     this.introspectedLayout = getShaderLayout(this.device.gl, this.handle);
+    log.timeEnd(0, `RenderPipeline ${this.id} - shaderLayout introspection`)();
+
     // Merge provided layout with introspected layout
     this.shaderLayout = mergeShaderLayout(this.introspectedLayout, props.shaderLayout);
 
@@ -80,7 +83,9 @@ export class WEBGLRenderPipeline extends RenderPipeline {
     switch (this.props.topology) {
       case 'triangle-fan-webgl':
       case 'line-loop-webgl':
-        log.warn(`Primitive topology ${this.props.topology} is deprecated and will be removed in v9.1`);
+        log.warn(
+          `Primitive topology ${this.props.topology} is deprecated and will be removed in v9.1`
+        );
         break;
       default:
     }
@@ -132,7 +137,13 @@ export class WEBGLRenderPipeline extends RenderPipeline {
           }
           break;
         case 'texture':
-          if (!(value instanceof WEBGLTexture || value instanceof WEBGLFramebuffer)) {
+          if (
+            !(
+              value instanceof WEBGLTextureView ||
+              value instanceof WEBGLTexture ||
+              value instanceof WEBGLFramebuffer
+            )
+          ) {
             throw new Error('texture value');
           }
           break;
@@ -147,18 +158,6 @@ export class WEBGLRenderPipeline extends RenderPipeline {
     }
   }
 
-  /** This function is @deprecated, use uniform buffers */
-  setUniforms(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);
-  }
-
   /** @todo needed for portable model
    * @note The WebGL API is offers many ways to draw things
    * This function unifies those ways into a single call using common parameters with sane defaults
@@ -176,6 +175,11 @@ export class WEBGLRenderPipeline extends RenderPipeline {
     baseVertex?: number;
     transformFeedback?: WEBGLTransformFeedback;
   }): boolean {
+    // If we are using async linking, we need to wait until linking completes
+    if (this.linkStatus !== 'success') {
+      return false;
+    }
+
     const {
       renderPass,
       vertexArray,
@@ -217,31 +221,6 @@ export class WEBGLRenderPipeline extends RenderPipeline {
     this._applyUniforms();
 
     const webglRenderPass = renderPass as WEBGLRenderPass;
-    //     // TODO - Use polyfilled WebGL2RenderingContext instead of ANGLE extension
-    //     if (isIndexed && isInstanced) {
-    //       // ANGLE_instanced_arrays extension
-    //       this.device.gl2?.drawElementsInstanced(
-    //         drawMode,
-    //         vertexCount || 0, // indexCount?
-    //         indexType,
-    //         firstVertex,
-    //         instanceCount || 0
-    //       );
-    //       // } else if (isIndexed && this.device.isWebGL2 && !isNaN(start) && !isNaN(end)) {
-    //       //   this.device.gl2.drawRangeElements(drawMode, start, end, vertexCount, indexType, offset);
-    //     } else if (isIndexed) {
-    //       this.device.gl.drawElements(drawMode, vertexCount || 0, indexType, firstVertex); // indexCount?
-    //     } else if (isInstanced) {
-    //       this.device.gl2?.drawArraysInstanced(
-    //         drawMode,
-    //         firstVertex,
-    //         vertexCount || 0,
-    //         instanceCount || 0
-    //       );
-    //     } else {
-    //       this.device.gl.drawArrays(drawMode, firstVertex, vertexCount || 0);
-    //     }
-    //   });
 
     withDeviceAndGLParameters(
       this.device,
@@ -249,8 +228,7 @@ export class WEBGLRenderPipeline extends RenderPipeline {
       webglRenderPass.glParameters,
       () => {
         if (isIndexed && isInstanced) {
-          // ANGLE_instanced_arrays extension
-          this.device.gl2?.drawElementsInstanced(
+          this.device.gl.drawElementsInstanced(
             glDrawMode,
             vertexCount || 0, // indexCount?
             glIndexType,
@@ -258,11 +236,11 @@ export class WEBGLRenderPipeline extends RenderPipeline {
             instanceCount || 0
           );
           // } else if (isIndexed && this.device.isWebGL2 && !isNaN(start) && !isNaN(end)) {
-          //   this.device.gl2.drawRangeElements(glDrawMode, start, end, vertexCount, glIndexType, offset);
+          //   this.device.gldrawRangeElements(glDrawMode, start, end, vertexCount, glIndexType, offset);
         } else if (isIndexed) {
           this.device.gl.drawElements(glDrawMode, vertexCount || 0, glIndexType, firstVertex); // indexCount?
         } else if (isInstanced) {
-          this.device.gl2?.drawArraysInstanced(
+          this.device.gl.drawArraysInstanced(
             glDrawMode,
             firstVertex,
             vertexCount || 0,
@@ -283,10 +261,27 @@ 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 {}
   // setBindings(bindings: Record<string, Binding>): void {}
 
-  protected _compileAndLink() {
+  protected async _linkShaders() {
     const {gl} = this.device;
     gl.attachShader(this.handle, this.vs.handle);
     gl.attachShader(this.handle, this.fs.handle);
@@ -294,25 +289,89 @@ export class WEBGLRenderPipeline extends RenderPipeline {
     gl.linkProgram(this.handle);
     log.timeEnd(LOG_PROGRAM_PERF_PRIORITY, `linkProgram for ${this.id}`)();
 
-    // Avoid checking program linking error in production
-    // @ts-expect-error
-    if (!gl.debug && log.level === 0) {
+    // TODO Avoid checking program linking error in production
+    if (log.level === 0) {
       // return;
     }
 
+    if (!this.device.features.has('compilation-status-async-webgl')) {
+      const status = this._getLinkStatus();
+      this._reportLinkStatus(status);
+      return;
+    }
+
+    // async case
+    log.once(1, 'RenderPipeline linking is asynchronous')();
+    await this._waitForLinkComplete();
+    log.info(2, `RenderPipeline ${this.id} - async linking complete: ${this.linkStatus}`)();
+    const status = this._getLinkStatus();
+    this._reportLinkStatus(status);
+  }
+
+  /** Report link status. First, check for shader compilation failures if linking fails */
+  _reportLinkStatus(status: 'success' | 'linking' | 'validation') {
+    switch (status) {
+      case 'success':
+        return;
+
+      default:
+        // First check for shader compilation failures if linking fails
+        if (this.vs.compilationStatus === 'error') {
+          this.vs.debugShader();
+          throw new Error(`Error during compilation of shader ${this.vs.id}`);
+        }
+        if (this.fs?.compilationStatus === 'error') {
+          this.vs.debugShader();
+          throw new Error(`Error during compilation of shader ${this.fs.id}`);
+        }
+        throw new Error(`Error during ${status}: ${this.device.gl.getProgramInfoLog(this.handle)}`);
+    }
+  }
+
+  /**
+   * Get the shader compilation status
+   * 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' {
+    const {gl} = this.device;
     const linked = gl.getProgramParameter(this.handle, gl.LINK_STATUS);
     if (!linked) {
-      throw new Error(`Error linking: ${gl.getProgramInfoLog(this.handle)}`);
+      this.linkStatus = 'error';
+      return 'linking';
     }
 
     gl.validateProgram(this.handle);
     const validated = gl.getProgramParameter(this.handle, gl.VALIDATE_STATUS);
     if (!validated) {
-      throw new Error(`Error validating: ${gl.getProgramInfoLog(this.handle)}`);
+      this.linkStatus = 'error';
+      return 'validation';
     }
+
+    this.linkStatus = 'success';
+    return 'success';
   }
 
-  // PRIVATE METHODS
+  /** Use KHR_parallel_shader_compile extension if available */
+  async _waitForLinkComplete(): Promise<void> {
+    const waitMs = async (ms: number) => await new Promise(resolve => setTimeout(resolve, ms));
+    const DELAY_MS = 10; // Shader compilation is typically quite fast (with some exceptions)
+
+    // If status polling is not available, we can't wait for completion. Just wait a little to minimize blocking
+    if (!this.device.features.has('compilation-status-async-webgl')) {
+      await waitMs(DELAY_MS);
+      return;
+    }
+
+    const {gl} = this.device;
+    for (;;) {
+      const complete = gl.getProgramParameter(this.handle, GL.COMPLETION_STATUS_KHR);
+      if (complete) {
+        return;
+      }
+      await waitMs(DELAY_MS);
+    }
+  }
 
   /**
    * Checks if all texture-values uniforms are renderable (i.e. loaded)
@@ -334,13 +393,14 @@ export class WEBGLRenderPipeline extends RenderPipeline {
 
   /** Apply any bindings (before each draw call) */
   _applyBindings() {
-    this.device.gl.useProgram(this.handle);
-
-    const {gl2} = this.device;
-    if (!gl2) {
-      throw new Error('bindings');
+    // If we are using async linking, we need to wait until linking completes
+    if (this.linkStatus !== 'success') {
+      return;
     }
 
+    const {gl} = this.device;
+    gl.useProgram(this.handle);
+
     let textureUnit = 0;
     let uniformBufferIndex = 0;
     for (const binding of this.shaderLayout.bindings) {
@@ -354,16 +414,16 @@ export class WEBGLRenderPipeline extends RenderPipeline {
         case 'uniform':
           // Set buffer
           const {name} = binding;
-          const location = gl2.getUniformBlockIndex(this.handle, name);
-          if (location as GL === GL.INVALID_INDEX) {
+          const location = gl.getUniformBlockIndex(this.handle, name);
+          if ((location as GL) === GL.INVALID_INDEX) {
             throw new Error(`Invalid uniform block name ${name}`);
           }
-          gl2.uniformBlockBinding(this.handle, uniformBufferIndex, location);
+          gl.uniformBlockBinding(this.handle, uniformBufferIndex, location);
           // console.debug(binding, location);
           if (value instanceof WEBGLBuffer) {
-            gl2.bindBufferBase(GL.UNIFORM_BUFFER, uniformBufferIndex, value.handle);
+            gl.bindBufferBase(GL.UNIFORM_BUFFER, uniformBufferIndex, value.handle);
           } else {
-            gl2.bindBufferRange(
+            gl.bindBufferRange(
               GL.UNIFORM_BUFFER,
               uniformBufferIndex,
               // @ts-expect-error
@@ -378,11 +438,19 @@ export class WEBGLRenderPipeline extends RenderPipeline {
           break;
 
         case 'texture':
-          if (!(value instanceof WEBGLTexture || value instanceof WEBGLFramebuffer)) {
+          if (
+            !(
+              value instanceof WEBGLTextureView ||
+              value instanceof WEBGLTexture ||
+              value instanceof WEBGLFramebuffer
+            )
+          ) {
             throw new Error('texture');
           }
           let texture: WEBGLTexture;
-          if (value instanceof WEBGLTexture) {
+          if (value instanceof WEBGLTextureView) {
+            texture = value.texture;
+          } else if (value instanceof WEBGLTexture) {
             texture = value;
           } else if (
             value instanceof WEBGLFramebuffer &&
@@ -396,9 +464,9 @@ export class WEBGLRenderPipeline extends RenderPipeline {
             throw new Error('No texture');
           }
 
-          gl2.activeTexture(GL.TEXTURE0 + textureUnit);
-          gl2.bindTexture(texture.target, texture.handle);
-          // gl2.bindSampler(textureUnit, sampler.handle);
+          gl.activeTexture(GL.TEXTURE0 + textureUnit);
+          gl.bindTexture(texture.target, texture.handle);
+          // gl.bindSampler(textureUnit, sampler.handle);
           textureUnit += 1;
           break;
 

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

@@ -1,4 +1,5 @@
-// luma.gl, MIT license
+// luma.gl
+// SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
 import {Sampler, SamplerProps} from '@luma.gl/core';
@@ -8,8 +9,6 @@ import type {WebGLDevice} from '../webgl-device';
 
 /**
  * Sampler object -
- * Under WebGL2 we create an actual WebGL sampler
- * Under WebGL1, we just store the sampler parameters
  * so that they can be set directly on the texture
  * https://github.com/WebGLSamples/WebGL2Samples/blob/master/samples/sampler_object.html
  */
@@ -22,15 +21,13 @@ export class WEBGLSampler extends Sampler {
     super(device, props);
     this.device = device;
     this.parameters = convertSamplerParametersToWebGL(props);
-    if (this.device.isWebGL2) {
-      this.handle = this.handle || this.device.gl2.createSampler();
-      this._setSamplerParameters(this.parameters);
-    }
+    this.handle = this.handle || this.device.gl.createSampler();
+    this._setSamplerParameters(this.parameters);
   }
 
   override destroy(): void {
     if (this.handle) {
-      this.device.gl2.deleteSampler(this.handle);
+      this.device.gl.deleteSampler(this.handle);
       // @ts-expect-error read-only/undefined
       this.handle = undefined;
     }
@@ -49,10 +46,10 @@ export class WEBGLSampler extends Sampler {
       switch (param) {
         case GL.TEXTURE_MIN_LOD:
         case GL.TEXTURE_MAX_LOD:
-          this.device.gl2.samplerParameterf(this.handle, param, value);
+          this.device.gl.samplerParameterf(this.handle, param, value);
           break;
         default:
-          this.device.gl2.samplerParameteri(this.handle, param, value);
+          this.device.gl.samplerParameteri(this.handle, param, value);
           break;
       }
     }

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

@@ -1,7 +1,8 @@
-// luma.gl, MIT license
+// luma.gl
+// SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {Shader, ShaderProps, CompilerMessage} from '@luma.gl/core';
+import {Shader, ShaderProps, CompilerMessage, log} from '@luma.gl/core';
 import {GL} from '@luma.gl/constants';
 import {parseShaderCompilerLog} from '../helpers/parse-shader-compiler-log';
 import {WebGLDevice} from '../webgl-device';
@@ -39,6 +40,7 @@ export class WEBGLShader extends Shader {
   }
 
   override async getCompilationInfo(): Promise<readonly CompilerMessage[]> {
+    await this._waitForCompilationComplete();
     return this.getCompilationInfoSync();
   }
 
@@ -47,9 +49,16 @@ export class WEBGLShader extends Shader {
     return parseShaderCompilerLog(log);
   }
 
+  override getTranslatedSource(): string | null {
+    const extensions = this.device.getExtension('WEBGL_debug_shaders');
+    const ext = extensions.WEBGL_debug_shaders;
+    return ext?.getTranslatedShaderSource(this.handle);
+  }
+
   // PRIVATE METHODS
 
-  _compile(source: string): void {
+  /** Compile a shader and get compilation status */
+  protected async _compile(source: string): Promise<void> {
     const addGLSLVersion = (source: string) =>
       source.startsWith('#version ') ? source : `#version 100\n${source}`;
     source = addGLSLVersion(source);
@@ -58,18 +67,64 @@ export class WEBGLShader extends Shader {
     gl.shaderSource(this.handle, source);
     gl.compileShader(this.handle);
 
-    // TODO - For performance reasons, avoid checking shader compilation errors on production?
-    // TODO - Load log even when no error reported, to catch warnings?
-    // https://gamedev.stackexchange.com/questions/30429/how-to-detect-glsl-warnings
-    this.compilationStatus = gl.getShaderParameter(this.handle, GL.COMPILE_STATUS) ? 'success' : 'error';
+    // For performance reasons, avoid checking shader compilation errors on production
+    if (log.level === 0) {
+      this.compilationStatus = 'pending';
+      return;
+    }
 
-    // The `Shader` base class will determine if debug window should be opened based on props
+    // Sync case - slower, but advantage is that it throws in the constructor, making break on error more useful
+    if (!this.device.features.has('compilation-status-async-webgl')) {
+      this._getCompilationStatus();
+      if (this.compilationStatus === 'error') {
+        throw new Error(`GLSL compilation errors in ${this.props.stage} shader ${this.props.id}`);
+      }
+      // The `Shader` base class will determine if debug window should be opened based on this.compilationStatus
+      this.debugShader();
+      return;
+    }
+
+    // async case
+    log.once(1, 'Shader compilation is asynchronous')();
+    await this._waitForCompilationComplete();
+    log.info(2, `Shader ${this.id} - async compilation complete: ${this.compilationStatus}`)();
+    this._getCompilationStatus();
+
+    // The `Shader` base class will determine if debug window should be opened based on this.compilationStatus
     this.debugShader();
+  }
 
-    if (this.compilationStatus === 'error') {
-      throw new Error(`GLSL compilation errors in ${this.props.stage} shader ${this.props.id}`);
+  /** Use KHR_parallel_shader_compile extension if available */
+  protected async _waitForCompilationComplete(): Promise<void> {
+    const waitMs = async (ms: number) => await new Promise(resolve => setTimeout(resolve, ms));
+    const DELAY_MS = 10; // Shader compilation is typically quite fast (with some exceptions)
+
+    // If status polling is not available, we can't wait for completion. Just wait a little to minimize blocking
+    if (!this.device.features.has('compilation-status-async-webgl')) {
+      await waitMs(DELAY_MS);
+      return;
+    }
+
+    const {gl} = this.device;
+    for (;;) {
+      const complete = gl.getShaderParameter(this.handle, GL.COMPLETION_STATUS_KHR);
+      if (complete) {
+        return;
+      }
+      await waitMs(DELAY_MS);
     }
   }
+
+  /**
+   * Get the shader compilation status
+   * TODO - Load log even when no error reported, to catch warnings?
+   * https://gamedev.stackexchange.com/questions/30429/how-to-detect-glsl-warnings
+   */
+  protected _getCompilationStatus() {
+    this.compilationStatus = this.device.gl.getShaderParameter(this.handle, GL.COMPILE_STATUS)
+      ? 'success'
+      : 'error';
+  }
 }
 
 // TODO - Original code from luma.gl v8 - keep until new debug functionality has matured
@@ -81,4 +136,3 @@ export class WEBGLShader extends Shader {
 //   log.error(`GLSL compilation errors in ${shaderDescription}\n${formattedLog}`)();
 //   displayShaderLog(parsedLog, source, shaderName);
 // }
-

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

@@ -0,0 +1,28 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Device, TextureViewProps} from '@luma.gl/core';
+// import {decodeTextureFormat} from '@luma.gl/core';
+import {TextureView, Texture} from '@luma.gl/core';
+
+import {WebGLDevice} from '../webgl-device';
+import {WEBGLTexture} from './webgl-texture';
+
+export class WEBGLTextureView extends TextureView {
+  readonly device: WebGLDevice;
+  readonly gl: WebGL2RenderingContext;
+  readonly handle: WebGLTexture;
+
+  readonly texture: WEBGLTexture;
+
+  constructor(device: Device, props: TextureViewProps & {texture: WEBGLTexture}) {
+    super(device, {...Texture.defaultProps, ...props});
+
+    this.device = device as WebGLDevice;
+    this.gl = this.device.gl;
+    this.handle = null;
+
+    this.texture = props.texture;
+  }
+}