@luma.gl/webgl 8.5.10 → 8.6.0-alpha.4

package/src/classes/clear.ts

@@ -0,0 +1,108 @@
+import {Device, assert} from '@luma.gl/api';
+import {assertWebGL2Context} from '../context/context/webgl-checks';
+import {withParameters} from '../context/state-tracker/with-parameters';
+import Framebuffer from './framebuffer';
+
+// 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 */
+export function clear(
+  device: Device | WebGLRenderingContext,
+  options?: {framebuffer?: Framebuffer; color?: any; depth?: any; stencil?: any}
+): void {
+  // @ts-expect-error Extract context
+  const gl = device.gl || device;
+  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
+  withParameters(gl, parameters, () => {
+    gl.clear(clearFlags);
+  });
+}
+
+/** WebGL2 - clear a specific drawing buffer */
+export function clearBuffer(
+  device: Device | WebGLRenderingContext,
+  options?: {framebuffer?: Framebuffer; buffer?: any; drawBuffer?: any; value?: any}
+) {
+  // @ts-expect-error Extract context
+  const gl = device.gl || device;
+  assertWebGL2Context(gl);
+
+  const {framebuffer = null, buffer = GL_COLOR, drawBuffer = 0, value = [0, 0, 0, 0]} = options || {};
+  withParameters(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/classes/{copy-and-blit.js → copy-and-blit.ts}

@@ -1,21 +1,40 @@
+import {log, assert} from '@luma.gl/api';
 import GL from '@luma.gl/constants';
-import Buffer from './buffer';
+import Buffer from './webgl-buffer';
 import Framebuffer from './framebuffer';
 import Texture from './texture';
-import {assertWebGL2Context, withParameters, log} from '@luma.gl/gltools';
+import {assertWebGL2Context} from '../context/context/webgl-checks';
+import {withParameters} from '../context/state-tracker/with-parameters';
 import {flipRows, scalePixels} from '../webgl-utils/typed-array-utils';
 import {getTypedArrayFromGLType, getGLTypeFromTypedArray} from '../webgl-utils/typed-array-utils';
 import {glFormatToComponents, glTypeToBytes} from '../webgl-utils/format-utils';
 import {toFramebuffer} from '../webgl-utils/texture-utils';
-import {assert} from '../utils/assert';
 
-// NOTE: Slow requires roundtrip to GPU
-// Copies data from a Framebuffer or a Texture object into ArrayBuffer object.
-// App can provide targetPixelArray or have it auto allocated by this method
+/**
+ * Copies data from a Framebuffer 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.
+ * @note Slow requires roundtrip to GPU
+ *
+ * @param source
+ * @param options
 // @returns {Uint8Array|Uint16Array|FloatArray} - pixel array,
-//  newly allocated by this method unless provided by app.
-export function readPixelsToArray(source, options = {}) {
-  const {sourceX = 0, sourceY = 0, sourceFormat = GL.RGBA} = options;
+ */
+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} = options || {};
   let {
     sourceAttachment = GL.COLOR_ATTACHMENT0, // TODO - support gl.readBuffer
     target = null,
@@ -23,7 +42,7 @@ export function readPixelsToArray(source, options = {}) {
     sourceWidth,
     sourceHeight,
     sourceType
-  } = options;
+  } = options || {};
 
   const {framebuffer, deleteFramebuffer} = getFramebuffer(source);
   assert(framebuffer);
@@ -49,7 +68,7 @@ export function readPixelsToArray(source, options = {}) {
 
   const prevHandle = gl.bindFramebuffer(GL.FRAMEBUFFER, handle);
   gl.readPixels(sourceX, sourceY, sourceWidth, sourceHeight, sourceFormat, sourceType, target);
-  // @ts-ignore
+  // @ts-expect-error
   gl.bindFramebuffer(GL.FRAMEBUFFER, prevHandle || null);
   if (deleteFramebuffer) {
     framebuffer.delete();
@@ -57,28 +76,42 @@ export function readPixelsToArray(source, options = {}) {
   return target;
 }
 
-// NOTE: doesn't wait for copy to be complete, it programs GPU to perform a DMA transffer.
-// Copies data from a Framebuffer or a Texture object into a Buffer object.
+/**
+ * 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.
+ * @param source
+ * @param options
+ */
 export function readPixelsToBuffer(
-  source,
-  {
-    sourceX = 0,
-    sourceY = 0,
-    sourceFormat = GL.RGBA,
-    target = null, // A new Buffer object is created when not provided.
-    targetByteOffset = 0, // byte offset in buffer object
+  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;
+  }
+): Buffer {
+  const {sourceX = 0, sourceY = 0, sourceFormat = GL.RGBA,
+    targetByteOffset = 0
+  } = options || {};
     // following parameters are auto deduced if not provided
+  let {
+    target,
     sourceWidth,
     sourceHeight,
-    sourceType
-  }
-) {
+    sourceType,
+  } = options || {}
   const {framebuffer, deleteFramebuffer} = getFramebuffer(source);
   assert(framebuffer);
   sourceWidth = sourceWidth || framebuffer.width;
   sourceHeight = sourceHeight || framebuffer.height;
 
-  // Asynchronus read (PIXEL_PACK_BUFFER) is WebGL2 only feature
+  // Asynchronous read (PIXEL_PACK_BUFFER) is WebGL2 only feature
   const gl2 = assertWebGL2Context(framebuffer.gl);
 
   // deduce type if not available.
@@ -92,6 +125,7 @@ export function readPixelsToBuffer(
     target = new Buffer(gl2, {byteLength, accessor: {type: sourceType, size: components}});
   }
 
+  // @ts-expect-error
   target.bind({target: GL.PIXEL_PACK_BUFFER});
   withParameters(gl2, {framebuffer}, () => {
     gl2.readPixels(
@@ -112,6 +146,15 @@ export function readPixelsToBuffer(
   return target;
 }
 
+// Reads pixels from a Framebuffer or Texture object to a dataUrl
+export function copyToDataUrl(
+  source,
+  options?: {
+    sourceAttachment?: number; // TODO - support gl.readBuffer
+    targetMaxHeight?: number;
+  }
+): string;
+
 // Reads pixels from a Framebuffer or Texture object to a dataUrl
 export function copyToDataUrl(
   source,
@@ -144,37 +187,58 @@ export function copyToDataUrl(
   return canvas.toDataURL();
 }
 
+// Reads pixels from a Framebuffer or Texture object into an HTML Image
 // Reads pixels from a Framebuffer or Texture object into an HTML Image
 export function copyToImage(
-  source,
-  {
-    sourceAttachment = GL.COLOR_ATTACHMENT0, // TODO - support gl.readBuffer
-    targetImage = null
-  } = {}
-) {
-  const dataUrl = copyToDataUrl(source, {sourceAttachment});
-  targetImage = targetImage || new Image();
+  source: Framebuffer | Texture,
+  options?: {
+    sourceAttachment?: number; // TODO - support gl.readBuffer
+    targetImage?: typeof Image;
+  }
+): typeof Image {
+  const dataUrl = copyToDataUrl(source, {sourceAttachment: options?.sourceAttachment || GL.COLOR_ATTACHMENT0});
+  const targetImage = options?.targetImage || new Image();
+  // @ts-expect-error
   targetImage.src = dataUrl;
+  // @ts-expect-error
   return targetImage;
 }
 
-// Copy a rectangle from a Framebuffer or Texture object into a texture (at an offset)
+/**
+ * Copy a rectangle from a Framebuffer or Texture object into a texture (at an offset)
+ */
 // eslint-disable-next-line complexity, max-statements
-export function copyToTexture(source, target, options = {}) {
+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;
+  } = options || {};
   let {
     targetX,
     targetY,
     targetZ,
     width, // defaults to target width
     height // defaults to target height
-  } = options;
+  } = options || {};
 
   const {framebuffer, deleteFramebuffer} = getFramebuffer(source);
   assert(framebuffer);
@@ -191,17 +255,20 @@ export function copyToTexture(source, target, options = {}) {
   // 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);
-    target = texture.target;
+    textureTarget = texture.target;
+  } else {
+    textureTarget = target;
   }
 
   if (!isSubCopy) {
     gl.copyTexImage2D(
-      target,
+      textureTarget,
       targetMipmaplevel,
       targetInternalFormat,
       sourceX,
@@ -211,11 +278,11 @@ export function copyToTexture(source, target, options = {}) {
       0 /* border must be 0 */
     );
   } else {
-    switch (target) {
+    switch (textureTarget) {
       case GL.TEXTURE_2D:
       case GL.TEXTURE_CUBE_MAP:
         gl.copyTexSubImage2D(
-          target,
+          textureTarget,
           targetMipmaplevel,
           targetX,
           targetY,
@@ -229,7 +296,7 @@ export function copyToTexture(source, target, options = {}) {
       case GL.TEXTURE_3D:
         const gl2 = assertWebGL2Context(gl);
         gl2.copyTexSubImage3D(
-          target,
+          textureTarget,
           targetMipmaplevel,
           targetX,
           targetY,
@@ -246,7 +313,7 @@ export function copyToTexture(source, target, options = {}) {
   if (texture) {
     texture.unbind();
   }
-  // @ts-ignore
+  // @ts-expect-error
   gl.bindFramebuffer(GL.FRAMEBUFFER, prevHandle || null);
   if (deleteFramebuffer) {
     framebuffer.delete();
@@ -254,10 +321,34 @@ export function copyToTexture(source, target, options = {}) {
   return texture;
 }
 
-// NOTE: WEBLG2 only
-// Copies a rectangle of pixels between Framebuffer or Texture objects
+/**
+ * Copies a rectangle of pixels between Framebuffer or Texture objects
+ * @note NOTE: WEBLG2 only
+ * @param source
+ * @param target
+ * @param options
+ */
 // eslint-disable-next-line max-statements, complexity
-export function blit(source, target, options = {}) {
+export function blit(
+  source,
+  target,
+  options: {
+    sourceAttachment?: number;
+    sourceX0?: number;
+    sourceY0?: number;
+    sourceX1?: number;
+    sourceY1?: number;
+    targetX0?: number;
+    targetY0?: number;
+    targetX1?: number;
+    targetY1?: number;
+    color?: boolean;
+    depth?: boolean;
+    stencil?: boolean;
+    mask?: number;
+    filter?: number;
+  }
+): void {
   const {
     sourceX0 = 0,
     sourceY0 = 0,
@@ -278,16 +369,13 @@ export function blit(source, target, options = {}) {
     mask = 0
   } = options;
 
-  const {framebuffer: srcFramebuffer, deleteFramebuffer: deleteSrcFramebuffer} = getFramebuffer(
-    source
-  );
-  const {framebuffer: dstFramebuffer, deleteFramebuffer: deleteDstFramebuffer} = getFramebuffer(
-    target
-  );
+  const {framebuffer: srcFramebuffer, deleteFramebuffer: deleteSrcFramebuffer} =
+    getFramebuffer(source);
+  const {framebuffer: dstFramebuffer, deleteFramebuffer: deleteDstFramebuffer} =
+    getFramebuffer(target);
 
   assert(srcFramebuffer);
   assert(dstFramebuffer);
-  // @ts-ignore
   const {gl, handle, width, height, readBuffer} = dstFramebuffer;
   const gl2 = assertWebGL2Context(gl);
 
@@ -336,9 +424,9 @@ export function blit(source, target, options = {}) {
     filter
   );
   gl2.readBuffer(readBuffer);
-  // @ts-ignore
+  // @ts-expect-error
   gl2.bindFramebuffer(GL.READ_FRAMEBUFFER, prevReadHandle || null);
-  // @ts-ignore
+  // @ts-expect-error
   gl2.bindFramebuffer(GL.DRAW_FRAMEBUFFER, prevDrawHandle || null);
   if (deleteSrcFramebuffer) {
     srcFramebuffer.delete();
@@ -347,7 +435,7 @@ export function blit(source, target, options = {}) {
     dstFramebuffer.delete();
   }
 
-  return dstFramebuffer;
+  // return dstFramebuffer;
 }
 
 // Helper methods