@luma.gl/webgl 9.0.0-alpha.9 → 9.0.0-beta.10

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

@@ -1,169 +1,107 @@
-// luma.gl, MIT license
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
 
-import type {FramebufferProps, DepthStencilTextureFormat, ColorTextureFormat} from '@luma.gl/api';
-import {Framebuffer, Texture, log, assert} from '@luma.gl/api';
-import GL from '@luma.gl/constants';
-import WebGLDevice from '../webgl-device';
-import WebGLTexture from './webgl-texture';
-import Renderbuffer from '../objects/webgl-renderbuffer';
-import {getWebGLTextureFormat, getWebGLDepthStencilAttachment} from '../converters/texture-formats';
+import type {FramebufferProps, TextureFormat} from '@luma.gl/core';
+import {Framebuffer, Texture, assert} from '@luma.gl/core';
+import {GL} from '@luma.gl/constants';
+import {WebGLDevice} from '../webgl-device';
+import {WEBGLTexture} from './webgl-texture';
+import {WEBGLTextureView} from './webgl-texture-view';
+import {getDepthStencilAttachmentWebGL} from '../converters/texture-formats';
 
-export type TextureAttachment = [Texture, number?, number?];
-export type Attachment = WebGLTexture | Renderbuffer | TextureAttachment;
+// TODO - for now we don't see a usage for renderbuffers in WebGL 2.
+// import {WEBGLRenderbuffer} from '../objects/webgl-renderbuffer';
+
+export type Attachment = WEBGLTextureView | WEBGLTexture; // | WEBGLRenderbuffer;
 
 /** luma.gl Framebuffer, WebGL implementation  */
-export default class WEBGLFramebuffer extends Framebuffer {
+export class WEBGLFramebuffer extends Framebuffer {
   device: WebGLDevice;
-  gl: WebGLRenderingContext;
+  gl: WebGL2RenderingContext;
   handle: WebGLFramebuffer;
 
-  get texture() { return this.colorAttachments[0]; }
-  readonly colorAttachments: WebGLTexture[] = [];
-  readonly depthStencilAttachment: WebGLTexture | null = null;  d 
-  protected _ownResources: (WebGLTexture | Renderbuffer)[] = [];
+  get texture() {
+    return this.colorAttachments[0];
+  }
 
   constructor(device: WebGLDevice, props: FramebufferProps) {
     super(device, props);
-    this.device = device;
-    this.gl = device.gl;
-    this.handle = this.props.handle !== undefined ? this.props.handle : this.gl.createFramebuffer();
-
-    if (this.handle) { // default framebuffer is null...
-      // @ts-expect-error Per SPECTOR docs
-      this.handle.__SPECTOR_Metadata = {id: this.props.id, props: this.props};
-    }
-
-    this.colorAttachments = this._createColorAttachments();
-    // @ts-expect-error
-    this.depthStencilAttachment = this._createDepthStencilAttachment();
 
-    /** Attach from a map of attachments */
-    const prevHandle = this.gl.bindFramebuffer(GL.FRAMEBUFFER, this.handle);
+    // WebGL default framebuffer handle is null
+    const isDefaultFramebuffer = props.handle === null;
 
-    // Walk the attachments
-    for (let i = 0; i < this.colorAttachments.length; ++i) {
-      const attachment = this.colorAttachments[i];
-      const attachmentPoint = GL.COLOR_ATTACHMENT0 + i;
-      if (attachment) {
-        this._attachOne(attachmentPoint, attachment);
+    this.device = device;
+    this.gl = device.gl;
+    this.handle =
+      this.props.handle || isDefaultFramebuffer ? this.props.handle : this.gl.createFramebuffer();
+
+    if (!isDefaultFramebuffer) {
+      // default framebuffer handle is null, so we can't set spector metadata...
+      device.setSpectorMetadata(this.handle, {id: this.props.id, props: this.props});
+
+      // Auto create textures for attachments if needed
+      this.autoCreateAttachmentTextures();
+
+      /** Attach from a map of attachments */
+      this.gl.bindFramebuffer(GL.FRAMEBUFFER, this.handle);
+
+      // Walk the attachments
+      for (let i = 0; i < this.colorAttachments.length; ++i) {
+        const attachment = this.colorAttachments[i] as WEBGLTextureView;
+        const attachmentPoint = GL.COLOR_ATTACHMENT0 + i;
+        if (attachment) {
+          this._attachOne(attachmentPoint, attachment);
+        }
       }
-    }
 
-    if (this.props.depthStencilAttachment) {
-      this._attachOne(getWebGLDepthStencilAttachment(this.depthStencilAttachment.format), this.depthStencilAttachment);
-    }
+      if (this.depthStencilAttachment) {
+        this._attachOne(
+          getDepthStencilAttachmentWebGL(this.depthStencilAttachment.props.format),
+          this.depthStencilAttachment as WEBGLTextureView
+        );
+      }
 
-    // @ts-expect-error
-    this.gl.bindFramebuffer(GL.FRAMEBUFFER, prevHandle || null);
+      /** Check the status */
+      // @ts-expect-error
+      if (props.check !== false) {
+        const status = this.gl.checkFramebufferStatus(GL.FRAMEBUFFER) as GL;
+        if (status !== GL.FRAMEBUFFER_COMPLETE) {
+          throw new Error(`Framebuffer ${_getFrameBufferStatus(status)}`);
+        }
+      }
 
-    // @ts-expect-error
-    if (props.check !== false) {
-      this._checkStatus();
+      this.gl.bindFramebuffer(GL.FRAMEBUFFER, null);
     }
   }
 
-  destroy() {
-    if (this.handle !== null) {
-      for (const resource of this._ownResources) {
-        resource.destroy();
-      }
+  /** destroys any auto created resources etc. */
+  override destroy(): void {
+    super.destroy(); // destroys owned resources etc.
+    if (!this.destroyed && this.handle !== null) {
       this.gl.deleteFramebuffer(this.handle);
       // this.handle = null;
-      this.destroyed = true;
     }
   }
 
   // PRIVATE
 
-  /** Check the status */
-  protected _checkStatus(): void {
-    const {gl} = this;
-    const prevHandle = gl.bindFramebuffer(GL.FRAMEBUFFER, this.handle);
-    const status = gl.checkFramebufferStatus(GL.FRAMEBUFFER);
-    // @ts-expect-error
-    gl.bindFramebuffer(GL.FRAMEBUFFER, prevHandle || null);
-    if (status !== gl.FRAMEBUFFER_COMPLETE) {
-      throw new Error(`Framebuffer ${_getFrameBufferStatus(status)}`);
-    }
-  }
-
-  _createColorAttachments(): WebGLTexture[] {
-    return this.props.colorAttachments.map(colorAttachment => {
-      if (!colorAttachment) {
-        return undefined;
-      }
-      if (colorAttachment instanceof WebGLTexture) {
-        return colorAttachment;
-      }
-      // if (typeof colorAttachment === 'default') {
-      //   return this._createColorAttachment('rgba8unorm', this.width, this.height);
-      // }
-      // @ts-expect-error
-      return this._createColorAttachment(colorAttachment, this.width, this.height);
-    });
-  }
-
-  /** Create a color attachment */
-  protected _createColorAttachment(format: ColorTextureFormat, width: number, height: number): WebGLTexture {
-    const texture = this.device._createTexture({
-      id: `${this.id}-color`,
-      data: null, // reserves texture memory, but texels are undefined
+  /** In WebGL we must use renderbuffers for depth/stencil attachments (unless we have extensions) */
+  protected override createDepthStencilTexture(format: TextureFormat): Texture {
+    // return new WEBGLRenderbuffer(this.device, {
+    return new WEBGLTexture(this.device, {
+      id: `${this.id}-depth-stencil`,
       format,
-      // type: GL.UNSIGNED_BYTE,
-      width,
-      height,
-      // Note: Mipmapping can be disabled by texture resource when we resize the texture
-      // to a non-power-of-two dimenstion (NPOT texture) under WebGL1. To have consistant
-      // behavior we always disable mipmaps.
-      mipmaps: false,
-      // Set MIN and MAG filtering parameters so mipmaps are not used in sampling.
-      // Use LINEAR so subpixel algos like fxaa work.
-      // Set WRAP modes that support NPOT textures too.
-      sampler: {
-        minFilter: 'linear',
-        magFilter: 'linear',
-        addressModeU: 'clamp-to-edge',
-        addressModeV: 'clamp-to-edge'
-      },
-      // parameters: {
-      //   [GL.TEXTURE_MIN_FILTER]: GL.LINEAR,
-      //   [GL.TEXTURE_MAG_FILTER]: GL.LINEAR,
-      //   [GL.TEXTURE_WRAP_S]: GL.CLAMP_TO_EDGE,
-      //   [GL.TEXTURE_WRAP_T]: GL.CLAMP_TO_EDGE
-      // }
-    }) as WebGLTexture;
-    this._ownResources.push(texture);
-    return texture;
-  }
-
-  /** Create a depth stencil attachment GL.DEPTH24_STENCIL8 */
-  protected _createDepthStencilAttachment(): Renderbuffer | WebGLTexture {
-    if (!this.props.depthStencilAttachment) {
-      return undefined;
-    }
-    if (this.props.depthStencilAttachment instanceof Renderbuffer) {
-      return this.props.depthStencilAttachment;
-    }
-    if (this.props.depthStencilAttachment instanceof Texture) {
-      return this.props.depthStencilAttachment as unknown as WebGLTexture;
-    }
-    const format = this.props.depthStencilAttachment;
-    const webglFormat = getWebGLTextureFormat(this.gl, format);
-
-    const texture = new Renderbuffer(this.device, {
-      id: `${this.id}-depth-stencil`, // TODO misleading if not depth and stencil?
-      format: webglFormat,
-      // dataFormat: GL.DEPTH_STENCIL,
-      // type: GL.UNSIGNED_INT_24_8,
       width: this.width,
-      height: this.height
+      height: this.height,
+      mipmaps: false
     });
-    this._ownResources.push(texture);
-    return texture;
   }
 
-  /** Attachment resize is expected to be a noop if size is same */
-  protected _resizeAttachments(width: number, height: number): this {
+  /**
+   * Attachment resize is expected to be a noop if size is same
+   */
+  protected override resizeAttachments(width: number, height: number): this {
     // for default framebuffer, just update the stored size
     if (this.handle === null) {
       // assert(width === undefined && height === undefined);
@@ -171,6 +109,7 @@ export default class WEBGLFramebuffer extends Framebuffer {
       this.height = this.gl.drawingBufferHeight;
       return this;
     }
+
     if (width === undefined) {
       width = this.gl.drawingBufferWidth;
     }
@@ -178,56 +117,75 @@ export default class WEBGLFramebuffer extends Framebuffer {
       height = this.gl.drawingBufferHeight;
     }
 
-    if (width !== this.width && height !== this.height) {
-      log.log(2, `Resizing framebuffer ${this.id} to ${width}x${height}`)();
-    }
+    // TODO Not clear that this is better than default destroy/create implementation
 
     for (const colorAttachment of this.colorAttachments) {
-      colorAttachment.resize({width, height});
+      (colorAttachment.texture as WEBGLTexture).resize({width, height});
+    }
+    if (this.depthStencilAttachment) {
+      (this.depthStencilAttachment.texture as WEBGLTexture).resize({width, height});
     }
-    this.depthStencilAttachment?.resize({width, height});
     return this;
   }
 
   /** Attach one attachment */
-  protected _attachOne(attachmentPoint: GL, attachment: Attachment): WebGLTexture | Renderbuffer {
-    if (attachment instanceof Renderbuffer) {
-      this._attachRenderbuffer(attachmentPoint, attachment);
-      return attachment;
-    } else if (Array.isArray(attachment)) {
+  protected _attachOne(attachmentPoint: GL, attachment: Attachment): WEBGLTexture {
+    // if (attachment instanceof WEBGLRenderbuffer) {
+    //   this._attachWEBGLRenderbuffer(attachmentPoint, attachment);
+    //   return attachment;
+    // }
+    if (Array.isArray(attachment)) {
       const [texture, layer = 0, level = 0] = attachment;
-      this._attachTexture(attachmentPoint, texture as unknown as WebGLTexture, layer, level);
-      return texture as unknown as WebGLTexture;
-    } else if (attachment instanceof WebGLTexture) {
+      this._attachTexture(attachmentPoint, texture as unknown as WEBGLTexture, layer, level);
+      return texture as unknown as WEBGLTexture;
+    }
+    if (attachment instanceof WEBGLTexture) {
       this._attachTexture(attachmentPoint, attachment, 0, 0);
       return attachment;
     }
+    if (attachment instanceof WEBGLTextureView) {
+      const textureView = attachment;
+      this._attachTexture(
+        attachmentPoint,
+        textureView.texture,
+        textureView.props.baseMipLevel,
+        textureView.props.baseArrayLayer
+      );
+      return attachment.texture;
+    }
+    throw new Error('attach');
   }
 
-  protected _attachRenderbuffer(attachment: GL, renderbuffer: Renderbuffer): void {
-    this.gl.framebufferRenderbuffer(
-      GL.FRAMEBUFFER,
-      attachment,
-      GL.RENDERBUFFER,
-      renderbuffer.handle
-    );
-  }
+  // TODO - we do not seem to need render buffers in WebGL 2
+  // protected _attachWEBGLRenderbuffer(attachment: GL, renderbuffer: WEBGLRenderbuffer): void {
+  //   this.gl.framebufferRenderbuffer(
+  //     GL.FRAMEBUFFER,
+  //     attachment,
+  //     GL.RENDERBUFFER,
+  //     renderbuffer.handle
+  //   );
+  // }
 
   /**
    * @param attachment
    * @param texture
-   * @param layer = 0 - index into WebGLTextureArray and Texture3D or face for `TextureCubeMap`
-   * @param level  = 0 - mipmapLevel (must be 0 in WebGL1)
+   * @param layer = 0 - index into WEBGLTextureArray and Texture3D or face for `TextureCubeMap`
+   * @param level = 0 - mipmapLevel
    */
-   protected _attachTexture(attachment: GL, texture: WebGLTexture, layer: number, level: number): void {
-    const {gl, gl2} = this.device;
+  protected _attachTexture(
+    attachment: GL,
+    texture: WEBGLTexture,
+    layer: number,
+    level: number
+  ): void {
+    const {gl} = this.device;
+
     gl.bindTexture(texture.target, texture.handle);
 
     switch (texture.target) {
       case GL.TEXTURE_2D_ARRAY:
       case GL.TEXTURE_3D:
-        this.device.assertWebGL2();
-        gl2?.framebufferTextureLayer(GL.FRAMEBUFFER, attachment, texture.target, level, layer);
+        gl.framebufferTextureLayer(GL.FRAMEBUFFER, attachment, texture.target, level, layer);
         break;
 
       case GL.TEXTURE_CUBE_MAP:
@@ -251,15 +209,17 @@ export default class WEBGLFramebuffer extends Framebuffer {
 // Helper functions
 
 // Map an index to a cube map face constant
-function mapIndexToCubeMapFace(layer) {
+function mapIndexToCubeMapFace(layer: number | GL): GL {
   // TEXTURE_CUBE_MAP_POSITIVE_X is a big value (0x8515)
   // if smaller assume layer is index, otherwise assume it is already a cube map face constant
-  return layer < GL.TEXTURE_CUBE_MAP_POSITIVE_X ? layer + GL.TEXTURE_CUBE_MAP_POSITIVE_X : layer;
+  return layer < (GL.TEXTURE_CUBE_MAP_POSITIVE_X as number)
+    ? layer + GL.TEXTURE_CUBE_MAP_POSITIVE_X
+    : layer;
 }
 
 // Helper METHODS
 // Get a string describing the framebuffer error if installed
-function _getFrameBufferStatus(status) {
+function _getFrameBufferStatus(status: GL) {
   switch (status) {
     case GL.FRAMEBUFFER_COMPLETE:
       return 'success';

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

@@ -0,0 +1,171 @@
+// WebGL2 Query (also handles disjoint timer extensions)
+import {QuerySet, QuerySetProps} from '@luma.gl/core';
+import {GL} from '@luma.gl/constants';
+import {WebGLDevice} from '../webgl-device';
+
+/**
+ * Asynchronous queries for different kinds of information
+ */
+export class WEBGLQuerySet extends QuerySet {
+  device: WebGLDevice;
+  handle: WebGLQuery;
+
+  target: number | null = null;
+  _queryPending = false;
+  _pollingPromise: Promise<any> | null = null;
+
+  override get [Symbol.toStringTag](): string {
+    return 'Query';
+  }
+
+  // Create a query class
+  constructor(device: WebGLDevice, props: QuerySetProps) {
+    super(device, props);
+    this.device = device;
+
+    if (props.count > 1) {
+      throw new Error('WebGL QuerySet can only have one value');
+    }
+
+    this.handle = this.device.gl.createQuery();
+    Object.seal(this);
+  }
+
+  override destroy() {
+    this.device.gl.deleteQuery(this.handle);
+  }
+
+  // FOR RENDER PASS AND COMMAND ENCODER
+
+  /**
+   * Shortcut for timer query (dependent on extension in both WebGL1 and 2)
+   * Measures GPU time delta between this call and a matching `end` call in the
+   * GPU instruction stream.
+   */
+  beginTimestampQuery(): void {
+    return this._begin(GL.TIME_ELAPSED_EXT);
+  }
+
+  endTimestampQuery(): void {
+    this._end();
+  }
+
+  // Shortcut for occlusion queries
+  beginOcclusionQuery(options?: {conservative?: boolean}): void {
+    return this._begin(
+      options?.conservative ? GL.ANY_SAMPLES_PASSED_CONSERVATIVE : GL.ANY_SAMPLES_PASSED
+    );
+  }
+
+  endOcclusionQuery() {
+    this._end();
+  }
+
+  // Shortcut for transformFeedbackQuery
+  beginTransformFeedbackQuery(): void {
+    return this._begin(GL.TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN);
+  }
+
+  endTransformFeedbackQuery(): void {
+    this._end();
+  }
+
+  async resolveQuery(): Promise<bigint[]> {
+    const value = await this.pollQuery();
+    return [value];
+  }
+
+  // PRIVATE METHODS
+
+  /**
+   * Due to OpenGL API limitations, after calling `begin()` on one Query
+   * instance, `end()` must be called on that same instance before
+   * calling `begin()` on another query. While there can be multiple
+   * outstanding queries representing disjoint `begin()`/`end()` intervals.
+   * It is not possible to interleave or overlap `begin` and `end` calls.
+   */
+  protected _begin(target: number): void {
+    // Don't start a new query if one is already active.
+    if (this._queryPending) {
+      return;
+    }
+
+    this.target = target;
+    this.device.gl.beginQuery(this.target, this.handle);
+
+    return;
+  }
+
+  // ends the current query
+  protected _end(): void {
+    // Can't end a new query if the last one hasn't been resolved.
+    if (this._queryPending) {
+      return;
+    }
+
+    if (this.target) {
+      this.device.gl.endQuery(this.target);
+      this.target = null;
+      this._queryPending = true;
+    }
+    return;
+  }
+
+  // Returns true if the query result is available
+  isResultAvailable(): boolean {
+    if (!this._queryPending) {
+      return false;
+    }
+
+    const resultAvailable = this.device.gl.getQueryParameter(
+      this.handle,
+      GL.QUERY_RESULT_AVAILABLE
+    );
+    if (resultAvailable) {
+      this._queryPending = false;
+    }
+    return resultAvailable;
+  }
+
+  // Timing query is disjoint, i.e. results are invalid
+  isTimerDisjoint(): boolean {
+    return this.device.gl.getParameter(GL.GPU_DISJOINT_EXT);
+  }
+
+  // Returns query result.
+  getResult(): any {
+    return this.device.gl.getQueryParameter(this.handle, GL.QUERY_RESULT);
+  }
+
+  // Returns the query result, converted to milliseconds to match JavaScript conventions.
+  getTimerMilliseconds() {
+    return this.getResult() / 1e6;
+  }
+
+  // Polls the query
+  pollQuery(limit: number = Number.POSITIVE_INFINITY): Promise<any> {
+    if (this._pollingPromise) {
+      return this._pollingPromise;
+    }
+
+    let counter = 0;
+
+    this._pollingPromise = new Promise((resolve, reject) => {
+      const poll = () => {
+        if (this.isResultAvailable()) {
+          resolve(this.getResult());
+          this._pollingPromise = null;
+        } else if (counter++ > limit) {
+          reject('Timed out');
+          this._pollingPromise = null;
+        } else {
+          requestAnimationFrame(poll);
+        }
+      };
+
+      requestAnimationFrame(poll);
+    });
+
+    return this._pollingPromise;
+  }
+}