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

package/src/classic/accessor.ts

@@ -1,5 +1,9 @@
-import {assert, checkProps, Buffer, AccessorObject} from '@luma.gl/api';
-import GL from '@luma.gl/constants';
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {assert, checkProps, Buffer, AccessorObject} from '@luma.gl/core';
+import {GL} from '@luma.gl/constants';
 import {getTypedArrayFromGLType} from './typed-array-utils';
 
 const DEFAULT_ACCESSOR_VALUES = {
@@ -19,7 +23,7 @@ const PROP_CHECKS = {
   }
 };
 
-export default class Accessor implements AccessorObject {
+export class Accessor implements AccessorObject {
   offset?: number;
   stride?: number;
   type?: number;
@@ -55,7 +59,7 @@ export default class Accessor implements AccessorObject {
   }
 
   constructor(...accessors: AccessorObject[]) {
-    accessors.forEach((accessor) => this._assign(accessor)); // Merge in sequence
+    accessors.forEach(accessor => this._assign(accessor)); // Merge in sequence
     Object.freeze(this);
   }
 
@@ -84,8 +88,8 @@ export default class Accessor implements AccessorObject {
       this.type = props.type;
 
       // Auto-deduce integer type?
-      if (props.type === GL.INT || props.type === GL.UNSIGNED_INT) {
-      this.integer = true;
+      if ((props.type as GL) === GL.INT || (props.type as GL) === GL.UNSIGNED_INT) {
+        this.integer = true;
       }
     }
     if (props.size !== undefined) {
@@ -148,10 +152,10 @@ export default class Accessor implements AccessorObject {
     if (this.divisor === undefined) delete this.divisor;
     if (this.normalized === undefined) delete this.normalized;
     if (this.integer === undefined) delete this.integer;
-  
+
     if (this.buffer === undefined) delete this.buffer;
     if (this.index === undefined) delete this.index;
-  
+
     return this;
   }
 }

package/src/classic/clear.ts

@@ -0,0 +1,118 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Device, Framebuffer, assert} from '@luma.gl/core';
+import {WebGLDevice} from '../adapter/webgl-device';
+import {withGLParameters} from '../context/state-tracker/with-parameters';
+
+// Should collapse during minification
+const GL_DEPTH_BUFFER_BIT = 0x00000100;
+const GL_STENCIL_BUFFER_BIT = 0x00000400;
+const GL_COLOR_BUFFER_BIT = 0x00004000;
+
+const GL_COLOR = 0x1800;
+const GL_DEPTH = 0x1801;
+const GL_STENCIL = 0x1802;
+const GL_DEPTH_STENCIL = 0x84f9;
+
+// Should disappear if asserts are removed
+const ERR_ARGUMENTS = 'clear: bad arguments';
+
+/**
+ * Optionally clears depth, color and stencil buffers
+ * @deprecated Set clear color when creating a RenderPass.
+ */
+export function clear(
+  device: Device,
+  options?: {framebuffer?: Framebuffer; color?: any; depth?: any; stencil?: any}
+): void {
+  const {framebuffer = null, color = null, depth = null, stencil = null} = options || {};
+  const parameters: any = {};
+
+  if (framebuffer) {
+    parameters.framebuffer = framebuffer;
+  }
+
+  let clearFlags = 0;
+
+  if (color) {
+    clearFlags |= GL_COLOR_BUFFER_BIT;
+    if (color !== true) {
+      parameters.clearColor = color;
+    }
+  }
+
+  if (depth) {
+    clearFlags |= GL_DEPTH_BUFFER_BIT;
+    if (depth !== true) {
+      parameters.clearDepth = depth;
+    }
+  }
+
+  if (stencil) {
+    clearFlags |= GL_STENCIL_BUFFER_BIT;
+    if (depth !== true) {
+      parameters.clearStencil = depth;
+    }
+  }
+
+  assert(clearFlags !== 0, ERR_ARGUMENTS);
+
+  // Temporarily set any clear "colors" and call clear
+  const gl = (device as WebGLDevice).gl;
+  withGLParameters(gl, parameters, () => {
+    gl.clear(clearFlags);
+  });
+}
+
+/**
+ * WebGL2 - clear a specific drawing buffer
+ * @deprecated Set clear color when creating a RenderPass
+ */
+export function clearBuffer(
+  device: Device,
+  options?: {framebuffer?: Framebuffer; buffer?: any; drawBuffer?: any; value?: any}
+) {
+  const {
+    framebuffer = null,
+    buffer = GL_COLOR,
+    drawBuffer = 0,
+    value = [0, 0, 0, 0]
+  } = options || {};
+  const gl = (device as WebGLDevice).gl;
+  withGLParameters(gl, {framebuffer}, () => {
+    // Method selection per OpenGL ES 3 docs
+    switch (buffer) {
+      case GL_COLOR:
+        switch (value.constructor) {
+          case Int32Array:
+            gl.clearBufferiv(buffer, drawBuffer, value);
+            break;
+          case Uint32Array:
+            gl.clearBufferuiv(buffer, drawBuffer, value);
+            break;
+          case Float32Array:
+          default:
+            gl.clearBufferfv(buffer, drawBuffer, value);
+        }
+        break;
+
+      case GL_DEPTH:
+        gl.clearBufferfv(GL_DEPTH, 0, [value]);
+        break;
+
+      case GL_STENCIL:
+        gl.clearBufferiv(GL_STENCIL, 0, [value]);
+        break;
+
+      case GL_DEPTH_STENCIL:
+        const [depth, stencil] = value;
+        gl.clearBufferfi(GL_DEPTH_STENCIL, 0, depth, stencil);
+        break;
+
+      default:
+        assert(false, ERR_ARGUMENTS);
+    }
+  });
+}

package/src/classic/copy-and-blit.ts

@@ -0,0 +1,318 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {assert, Buffer, Texture, Framebuffer, FramebufferProps} from '@luma.gl/core';
+import {GL} from '@luma.gl/constants';
+
+import {WEBGLTextureView} from '../adapter/resources/webgl-texture-view';
+import {WEBGLFramebuffer} from '../adapter/resources/webgl-framebuffer';
+import {getGLTypeFromTypedArray, getTypedArrayFromGLType} from './typed-array-utils';
+import {glFormatToComponents, glTypeToBytes} from './format-utils';
+import {WEBGLBuffer} from '../adapter/resources/webgl-buffer';
+
+/**
+ * Copies data from a type  or a Texture object into ArrayBuffer object.
+ * App can provide targetPixelArray or have it auto allocated by this method
+ *  newly allocated by this method unless provided by app.
+ * @deprecated Use CommandEncoder.copyTextureToBuffer and Buffer.read
+ * @note Slow requires roundtrip to GPU
+ *
+ * @param source
+ * @param options
+ * @returns pixel array,
+ */
+export function readPixelsToArray(
+  source: Framebuffer | Texture,
+  options?: {
+    sourceX?: number;
+    sourceY?: number;
+    sourceFormat?: number;
+    sourceAttachment?: number;
+    target?: Uint8Array | Uint16Array | Float32Array;
+    // following parameters are auto deduced if not provided
+    sourceWidth?: number;
+    sourceHeight?: number;
+    sourceType?: number;
+  }
+): Uint8Array | Uint16Array | Float32Array {
+  const {
+    sourceX = 0,
+    sourceY = 0,
+    sourceFormat = GL.RGBA,
+    sourceAttachment = GL.COLOR_ATTACHMENT0 // TODO - support gl.readBuffer
+  } = options || {};
+  let {
+    target = null,
+    // following parameters are auto deduced if not provided
+    sourceWidth,
+    sourceHeight,
+    sourceType
+  } = options || {};
+
+  const {framebuffer, deleteFramebuffer} = getFramebuffer(source);
+  assert(framebuffer);
+  const {gl, handle} = framebuffer as WEBGLFramebuffer;
+  sourceWidth = sourceWidth || framebuffer.width;
+  sourceHeight = sourceHeight || framebuffer.height;
+
+  // TODO - Set and unset gl.readBuffer
+  // if (sourceAttachment === GL.COLOR_ATTACHMENT0 && handle === null) {
+  //   sourceAttachment = GL.FRONT;
+  // }
+
+  const attachment = sourceAttachment - GL.COLOR_ATTACHMENT0;
+  // assert(attachments[sourceAttachment]);
+
+  // Deduce the type from color attachment if not provided.
+  sourceType =
+    sourceType ||
+    (framebuffer.colorAttachments[attachment] as WEBGLTextureView)?.texture?.type ||
+    GL.UNSIGNED_BYTE;
+
+  // Deduce type and allocated pixelArray if needed
+  target = getPixelArray(target, sourceType, sourceFormat, sourceWidth, sourceHeight);
+
+  // Pixel array available, if necessary, deduce type from it.
+  sourceType = sourceType || getGLTypeFromTypedArray(target);
+
+  const prevHandle = gl.bindFramebuffer(GL.FRAMEBUFFER, handle);
+  gl.readPixels(sourceX, sourceY, sourceWidth, sourceHeight, sourceFormat, sourceType, target);
+  // @ts-expect-error
+  gl.bindFramebuffer(GL.FRAMEBUFFER, prevHandle || null);
+  if (deleteFramebuffer) {
+    framebuffer.destroy();
+  }
+  return target;
+}
+
+/**
+ * Copies data from a Framebuffer or a Texture object into a Buffer object.
+ * NOTE: doesn't wait for copy to be complete, it programs GPU to perform a DMA transffer.
+ * @deprecated Use CommandEncoder
+ * @param source
+ * @param options
+ */
+export function readPixelsToBuffer(
+  source: Framebuffer | Texture,
+  options?: {
+    sourceX?: number;
+    sourceY?: number;
+    sourceFormat?: number;
+    target?: Buffer; // A new Buffer object is created when not provided.
+    targetByteOffset?: number; // byte offset in buffer object
+    // following parameters are auto deduced if not provided
+    sourceWidth?: number;
+    sourceHeight?: number;
+    sourceType?: number;
+  }
+): WEBGLBuffer {
+  const {
+    target,
+    sourceX = 0,
+    sourceY = 0,
+    sourceFormat = GL.RGBA,
+    targetByteOffset = 0
+  } = options || {};
+  // following parameters are auto deduced if not provided
+  let {sourceWidth, sourceHeight, sourceType} = options || {};
+  const {framebuffer, deleteFramebuffer} = getFramebuffer(source);
+  assert(framebuffer);
+  sourceWidth = sourceWidth || framebuffer.width;
+  sourceHeight = sourceHeight || framebuffer.height;
+
+  // Asynchronous read (PIXEL_PACK_BUFFER) is WebGL2 only feature
+  const webglFramebuffer = framebuffer as WEBGLFramebuffer;
+
+  // deduce type if not available.
+  sourceType = sourceType || GL.UNSIGNED_BYTE;
+
+  let webglBufferTarget = target as unknown as WEBGLBuffer | undefined;
+  if (!webglBufferTarget) {
+    // Create new buffer with enough size
+    const components = glFormatToComponents(sourceFormat);
+    const byteCount = glTypeToBytes(sourceType);
+    const byteLength = targetByteOffset + sourceWidth * sourceHeight * components * byteCount;
+    webglBufferTarget = webglFramebuffer.device.createBuffer({byteLength});
+  }
+
+  // TODO(donmccurdy): Do we have tests to confirm this is working?
+  const commandEncoder = source.device.createCommandEncoder();
+  commandEncoder.copyTextureToBuffer({
+    source: source as Texture,
+    width: sourceWidth,
+    height: sourceHeight,
+    origin: [sourceX, sourceY],
+    destination: webglBufferTarget,
+    byteOffset: targetByteOffset
+  });
+  commandEncoder.destroy();
+
+  if (deleteFramebuffer) {
+    framebuffer.destroy();
+  }
+
+  return webglBufferTarget;
+}
+
+/**
+ * Copy a rectangle from a Framebuffer or Texture object into a texture (at an offset)
+ * @deprecated Use CommandEncoder
+ */
+// eslint-disable-next-line complexity, max-statements
+export function copyToTexture(
+  source: Framebuffer | Texture,
+  target: Texture | GL,
+  options?: {
+    sourceX?: number;
+    sourceY?: number;
+
+    targetX?: number;
+    targetY?: number;
+    targetZ?: number;
+    targetMipmaplevel?: number;
+    targetInternalFormat?: number;
+
+    width?: number; // defaults to target width
+    height?: number; // defaults to target height
+  }
+): Texture {
+  const {
+    sourceX = 0,
+    sourceY = 0,
+    // attachment = GL.COLOR_ATTACHMENT0, // TODO - support gl.readBuffer
+    targetMipmaplevel = 0,
+    targetInternalFormat = GL.RGBA
+  } = options || {};
+  let {
+    targetX,
+    targetY,
+    targetZ,
+    width, // defaults to target width
+    height // defaults to target height
+  } = options || {};
+
+  const {framebuffer, deleteFramebuffer} = getFramebuffer(source);
+  assert(framebuffer);
+  const webglFramebuffer = framebuffer as WEBGLFramebuffer;
+  const {device, handle} = webglFramebuffer;
+  const isSubCopy =
+    typeof targetX !== 'undefined' ||
+    typeof targetY !== 'undefined' ||
+    typeof targetZ !== 'undefined';
+  targetX = targetX || 0;
+  targetY = targetY || 0;
+  targetZ = targetZ || 0;
+  const prevHandle = device.gl.bindFramebuffer(GL.FRAMEBUFFER, handle);
+  // TODO - support gl.readBuffer (WebGL2 only)
+  // const prevBuffer = gl.readBuffer(attachment);
+  assert(target);
+  let texture = null;
+  let textureTarget: GL;
+  if (target instanceof Texture) {
+    texture = target;
+    width = Number.isFinite(width) ? width : texture.width;
+    height = Number.isFinite(height) ? height : texture.height;
+    texture.bind(0);
+    textureTarget = texture.target;
+  } else {
+    textureTarget = target;
+  }
+
+  if (!isSubCopy) {
+    device.gl.copyTexImage2D(
+      textureTarget,
+      targetMipmaplevel,
+      targetInternalFormat,
+      sourceX,
+      sourceY,
+      width,
+      height,
+      0 /* border must be 0 */
+    );
+  } else {
+    switch (textureTarget) {
+      case GL.TEXTURE_2D:
+      case GL.TEXTURE_CUBE_MAP:
+        device.gl.copyTexSubImage2D(
+          textureTarget,
+          targetMipmaplevel,
+          targetX,
+          targetY,
+          sourceX,
+          sourceY,
+          width,
+          height
+        );
+        break;
+      case GL.TEXTURE_2D_ARRAY:
+      case GL.TEXTURE_3D:
+        device.gl.copyTexSubImage3D(
+          textureTarget,
+          targetMipmaplevel,
+          targetX,
+          targetY,
+          targetZ,
+          sourceX,
+          sourceY,
+          width,
+          height
+        );
+        break;
+      default:
+    }
+  }
+  if (texture) {
+    texture.unbind();
+  }
+  // @ts-expect-error
+  device.gl.bindFramebuffer(GL.FRAMEBUFFER, prevHandle || null);
+  if (deleteFramebuffer) {
+    framebuffer.destroy();
+  }
+  return texture;
+}
+
+function getFramebuffer(source: Texture | Framebuffer): {
+  framebuffer: Framebuffer;
+  deleteFramebuffer: boolean;
+} {
+  if (!(source instanceof Framebuffer)) {
+    return {framebuffer: toFramebuffer(source), deleteFramebuffer: true};
+  }
+  return {framebuffer: source, deleteFramebuffer: false};
+}
+
+/**
+ * Wraps a given texture into a framebuffer object, that can be further used
+ * to read data from the texture object.
+ */
+export function toFramebuffer(texture: Texture, props?: FramebufferProps): Framebuffer {
+  const {device, width, height, id} = texture;
+  const framebuffer = device.createFramebuffer({
+    ...props,
+    id: `framebuffer-for-${id}`,
+    width,
+    height,
+    colorAttachments: [texture]
+  });
+  return framebuffer;
+}
+
+function getPixelArray(
+  pixelArray,
+  type,
+  format,
+  width: number,
+  height: number
+): Uint8Array | Uint16Array | Float32Array {
+  if (pixelArray) {
+    return pixelArray;
+  }
+  // Allocate pixel array if not already available, using supplied type
+  type = type || GL.UNSIGNED_BYTE;
+  const ArrayType = getTypedArrayFromGLType(type, {clamped: false});
+  const components = glFormatToComponents(format);
+  // TODO - check for composite type (components = 1).
+  return new ArrayType(width * height * components) as Uint8Array | Uint16Array | Float32Array;
+}

package/src/classic/format-utils.ts

@@ -0,0 +1,47 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {assert} from '@luma.gl/core';
+import {GL} from '@luma.gl/constants';
+
+// Returns number of components in a specific readPixels WebGL format
+export function glFormatToComponents(format) {
+  switch (format) {
+    case GL.ALPHA:
+    case GL.R32F:
+    case GL.RED:
+      return 1;
+    case GL.RG32F:
+    case GL.RG:
+      return 2;
+    case GL.RGB:
+    case GL.RGB32F:
+      return 3;
+    case GL.RGBA:
+    case GL.RGBA32F:
+      return 4;
+    // TODO: Add support for additional WebGL2 formats
+    default:
+      assert(false);
+      return 0;
+  }
+}
+
+// Return byte count for given readPixels WebGL type
+export function glTypeToBytes(type) {
+  switch (type) {
+    case GL.UNSIGNED_BYTE:
+      return 1;
+    case GL.UNSIGNED_SHORT_5_6_5:
+    case GL.UNSIGNED_SHORT_4_4_4_4:
+    case GL.UNSIGNED_SHORT_5_5_5_1:
+      return 2;
+    case GL.FLOAT:
+      return 4;
+    // TODO: Add support for additional WebGL2 types
+    default:
+      assert(false);
+      return 0;
+  }
+}

package/src/classic/typed-array-utils.ts

@@ -1,28 +1,20 @@
-// luma.gl, MIT license
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
 
-import {TypedArray} from '@luma.gl/api';
-import GL from '@luma.gl/constants';
-import {GLType} from '../types/webgl'
+import {TypedArray, TypedArrayConstructor} from '@luma.gl/core';
+import {GL, GLDataType, GLPixelType} from '@luma.gl/constants';
 
 const ERR_TYPE_DEDUCTION = 'Failed to deduce GL constant from typed array';
 
-type TypedArrayConstructor =
-  | Float32ArrayConstructor
-  | Uint16ArrayConstructor
-  | Uint32ArrayConstructor
-  | Uint8ArrayConstructor
-  | Uint8ClampedArrayConstructor
-  | Int8ArrayConstructor
-  | Int16ArrayConstructor
-  | Int32ArrayConstructor;
-
 /**
  * Converts TYPED ARRAYS to corresponding GL constant
  * Used to auto deduce gl parameter types
- * @param {*} arrayOrType
+ * @deprecated Use getDataTypeFromTypedArray
+ * @param arrayOrType
  * @returns
  */
-export function getGLTypeFromTypedArray(arrayOrType: TypedArray): GLType {
+export function getGLTypeFromTypedArray(arrayOrType: TypedArray): GLDataType {
   // If typed array, look up constructor
   const type = ArrayBuffer.isView(arrayOrType) ? arrayOrType.constructor : arrayOrType;
   switch (type) {
@@ -50,13 +42,14 @@ export function getGLTypeFromTypedArray(arrayOrType: TypedArray): GLType {
 /**
  * Converts GL constant to corresponding TYPED ARRAY
  * Used to auto deduce gl parameter types
- * @param {*} glType
- * @param {*} param1
+ * @deprecated Use getTypedArrayFromDataType
+ * @param glType
+ * @param param1
  * @returns
  */
 // eslint-disable-next-line complexity
 export function getTypedArrayFromGLType(
-  glType: any,
+  glType: GLDataType | GLPixelType,
   options?: {
     clamped?: boolean;
   }
@@ -90,14 +83,14 @@ export function getTypedArrayFromGLType(
  * Flip rows (can be used on arrays returned from `Framebuffer.readPixels`)
  * https: *stackoverflow.com/questions/41969562/
  * how-can-i-flip-the-result-of-webglrenderingcontext-readpixels
- * @param {*} param0
+ * @param param0
  */
- export function flipRows(options: {
-  data: any;
-  width: any;
-  height: any;
+export function flipRows(options: {
+  data: TypedArray;
+  width: number;
+  height: number;
   bytesPerPixel?: number;
-  temp?: any;
+  temp?: Uint8Array;
 }): void {
   const {data, width, height, bytesPerPixel = 4, temp} = options;
   const bytesPerRow = width * bytesPerPixel;
@@ -116,12 +109,7 @@ export function getTypedArrayFromGLType(
   }
 }
 
-
-export function scalePixels(options: {
-  data: any;
-  width: any;
-  height: any;
-}): {
+export function scalePixels(options: {data: TypedArray; width: number; height: number}): {
   data: Uint8Array;
   width: number;
   height: number;

package/src/context/debug/spector.ts

@@ -1,5 +1,8 @@
-// luma.gl, MIT license
-import {log, loadScript} from '@luma.gl/api';
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {log, loadScript} from '@luma.gl/core';
 
 /** Spector debug initialization options */
 type SpectorProps = {
@@ -23,6 +26,7 @@ let spector: any = null;
 let initialized: boolean = false;
 
 declare global {
+  // eslint-disable-next-line no-var
   var SPECTOR: any;
 }
 
@@ -31,8 +35,8 @@ export async function loadSpectorJS(props?: SpectorProps) {
   if (!globalThis.SPECTOR) {
     try {
       await loadScript(SPECTOR_CDN_URL);
-    } catch(error) {
-      log.warn(String(error))
+    } catch (error) {
+      log.warn(String(error));
     }
   }
 }
@@ -44,7 +48,7 @@ export function initializeSpectorJS(props?: SpectorProps) {
   }
 
   if (!spector && globalThis.SPECTOR) {
-    log.probe(LOG_LEVEL, "SPECTOR found and initialized")();
+    log.probe(LOG_LEVEL, 'SPECTOR found and initialized')();
     spector = new globalThis.SPECTOR.Spector();
     if (globalThis.luma) {
       globalThis.luma.spector = spector;
@@ -61,14 +65,16 @@ export function initializeSpectorJS(props?: SpectorProps) {
     // enables recording some extra information merged in the capture like texture memory sizes and formats
     spector.spyCanvases();
     // A callback when results are ready
-    spector?.onCaptureStarted.add((capture: unknown) => log.info(`Spector capture started:`, capture)());
+    spector?.onCaptureStarted.add((capture: unknown) =>
+      log.info('Spector capture started:', capture)()
+    );
     spector?.onCapture.add((capture: unknown) => {
-      log.info(`Spector capture complete:`, capture)();
+      log.info('Spector capture complete:', capture)();
       // Use undocumented Spector API to open the UI with our capture
       // See https://github.com/BabylonJS/Spector.js/blob/767ad1195a25b85a85c381f400eb50a979239eca/src/spector.ts#L124
-      spector?.getResultUI()
+      spector?.getResultUI();
       spector?.resultView.display();
-      spector?.resultView.addCapture(capture)
+      spector?.resultView.addCapture(capture);
     });
   }
 
@@ -82,7 +88,7 @@ export function initializeSpectorJS(props?: SpectorProps) {
     // spector?.captureCanvas(props?.canvas);
     spector?.startCapture(props?.canvas, 500); // 500 commands
     new Promise(resolve => setTimeout(resolve, 2000)).then(_ => {
-      log.info(`Spector capture stopped after 2 seconds`)();
+      log.info('Spector capture stopped after 2 seconds')();
       spector?.stopCapture();
       // spector?.displayUI();
     });