@luma.gl/webgl 9.0.0-alpha.23 → 9.0.0-alpha.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luma.gl/webgl",
-  "version": "9.0.0-alpha.23",
+  "version": "9.0.0-alpha.24",
   "description": "WebGL2 adapter for the luma.gl API",
   "type": "module",
   "license": "MIT",
@@ -44,12 +44,12 @@
   },
   "dependencies": {
     "@babel/runtime": "^7.0.0",
-    "@luma.gl/api": "9.0.0-alpha.23",
-    "@luma.gl/constants": "9.0.0-alpha.23",
+    "@luma.gl/api": "9.0.0-alpha.24",
+    "@luma.gl/constants": "9.0.0-alpha.24",
     "@probe.gl/env": "^4.0.2"
   },
   "devDependencies": {
-    "@luma.gl/test-utils": "9.0.0-alpha.23"
+    "@luma.gl/test-utils": "9.0.0-alpha.24"
   },
-  "gitHead": "5e4a30497333bea4be8f2b3f3db33c0b67931b9c"
+  "gitHead": "3707968c288edbfef7ab4060195493ca8f00e7d5"
 }

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

@@ -359,7 +359,7 @@ export class WEBGLRenderPipeline extends RenderPipeline {
   _applyUniforms() {
     for (const uniformLayout of this.layout.uniforms || []) {
       const {name, location, type, textureUnit} = uniformLayout;
-      const value = this.uniforms[name] || textureUnit;
+      const value = this.uniforms[name] ?? textureUnit;
       if (value !== undefined) {
         setUniform(this.device.gl, location, type, value);
       }

package/src/classic/clear.ts

@@ -0,0 +1,110 @@
+import {Device, Framebuffer, assert} from '@luma.gl/api';
+import {WebGLDevice} from '../adapter/webgl-device';
+import {withParameters} 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(
+  gl: Device | WebGLRenderingContext,
+  options?: {framebuffer?: Framebuffer; color?: any; depth?: any; stencil?: any}
+): void {
+  const device = WebGLDevice.attach(gl);
+  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(device.gl, parameters, () => {
+    device.gl.clear(clearFlags);
+  });
+}
+
+/** 
+ * WebGL2 - clear a specific drawing buffer 
+ * @deprecated Set clear color when creating a RenderPass
+ */
+export function clearBuffer(
+  gl: Device | WebGLRenderingContext,
+  options?: {framebuffer?: Framebuffer; buffer?: any; drawBuffer?: any; value?: any}
+) {
+  const device = WebGLDevice.attach(gl);
+
+  const {framebuffer = null, buffer = GL_COLOR, drawBuffer = 0, value = [0, 0, 0, 0]} = options || {};
+  withParameters(device.gl2, {framebuffer}, () => {
+    // Method selection per OpenGL ES 3 docs
+    switch (buffer) {
+      case GL_COLOR:
+        switch (value.constructor) {
+          case Int32Array:
+            device.gl2.clearBufferiv(buffer, drawBuffer, value);
+            break;
+          case Uint32Array:
+            device.gl2.clearBufferuiv(buffer, drawBuffer, value);
+            break;
+          case Float32Array:
+          default:
+            device.gl2.clearBufferfv(buffer, drawBuffer, value);
+        }
+        break;
+
+      case GL_DEPTH:
+        device.gl2.clearBufferfv(GL_DEPTH, 0, [value]);
+        break;
+
+      case GL_STENCIL:
+        device.gl2.clearBufferiv(GL_STENCIL, 0, [value]);
+        break;
+
+      case GL_DEPTH_STENCIL:
+        const [depth, stencil] = value;
+        device.gl2.clearBufferfi(GL_DEPTH_STENCIL, 0, depth, stencil);
+        break;
+
+      default:
+        assert(false, ERR_ARGUMENTS);
+    }
+  });
+}

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

@@ -0,0 +1,189 @@
+// luma.gl, MIT license
+import {assert, Texture, Framebuffer, FramebufferProps} from '@luma.gl/api';
+import GL from '@luma.gl/constants';
+
+import {ClassicBuffer as Buffer} from './buffer';
+import {WEBGLTexture}  from  '../adapter/resources/webgl-texture';
+import {WEBGLFramebuffer} from '../adapter/resources/webgl-framebuffer';
+import {withParameters} from '../context/state-tracker/with-parameters';
+import {getGLTypeFromTypedArray, getTypedArrayFromGLType} from './typed-array-utils';
+import {glFormatToComponents, glTypeToBytes} from './format-utils';
+
+/**
+ * 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} = options || {};
+  let {
+    sourceAttachment = GL.COLOR_ATTACHMENT0, // TODO - support gl.readBuffer
+    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 WEBGLTexture).type;
+
+  // 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.
+ * @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;
+  }
+): 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} = 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;
+  const gl2 = webglFramebuffer.device.assertWebGL2();
+
+  // deduce type if not available.
+  sourceType = sourceType || (target ? target.type : GL.UNSIGNED_BYTE);
+
+  if (!target) {
+    // Create new buffer with enough size
+    const components = glFormatToComponents(sourceFormat);
+    const byteCount = glTypeToBytes(sourceType);
+    const byteLength = targetByteOffset + sourceWidth * sourceHeight * components * byteCount;
+    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(
+      sourceX,
+      sourceY,
+      sourceWidth,
+      sourceHeight,
+      sourceFormat,
+      sourceType,
+      targetByteOffset
+    );
+  });
+  target.unbind({target: GL.PIXEL_PACK_BUFFER});
+  if (deleteFramebuffer) {
+    framebuffer.destroy();
+  }
+
+  return target;
+}
+
+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,43 @@
+import {assert} from '@luma.gl/api';
+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/context/context/create-browser-context.ts

@@ -2,21 +2,21 @@
 
 /**
  * ContextProps
-* @param webgl2 Set to false to not create a WebGL2 context (force webgl1)
-* @param webgl1 set to false to not create a WebGL1 context (fail if webgl2 not available)
-* @param onContextLost
-* @param onContextRestored
-*
-* BROWSER CONTEXT PARAMETERS
-* @param debug Instrument context (at the expense of performance).
-* @param alpha Default render target has an alpha buffer.
-* @param depth Default render target has a depth buffer of at least 16 bits.
-* @param stencil Default render target has a stencil buffer of at least 8 bits.
-* @param antialias Boolean that indicates whether or not to perform anti-aliasing.
-* @param premultipliedAlpha Boolean that indicates that the page compositor will assume the drawing buffer contains colors with pre-multiplied alpha.
-* @param preserveDrawingBuffer Default render target buffers will not be automatically cleared and will preserve their values until cleared or overwritten
-* @param failIfMajorPerformanceCaveat Do not create if the system performance is low.
-*/
+ * @param webgl2 Set to false to not create a WebGL2 context (force webgl1)
+ * @param webgl1 set to false to not create a WebGL1 context (fail if webgl2 not available)
+ * @param onContextLost
+ * @param onContextRestored
+ *
+ * BROWSER CONTEXT PARAMETERS
+ * @param debug Instrument context (at the expense of performance).
+ * @param alpha Default render target has an alpha buffer.
+ * @param depth Default render target has a depth buffer of at least 16 bits.
+ * @param stencil Default render target has a stencil buffer of at least 8 bits.
+ * @param antialias Boolean that indicates whether or not to perform anti-aliasing.
+ * @param premultipliedAlpha Boolean that indicates that the page compositor will assume the drawing buffer contains colors with pre-multiplied alpha.
+ * @param preserveDrawingBuffer Default render target buffers will not be automatically cleared and will preserve their values until cleared or overwritten
+ * @param failIfMajorPerformanceCaveat Do not create if the system performance is low.
+ */
 type ContextProps = {
   type?: 'webgl' | 'webgl1' | 'webgl2' | string;
   webgl1?: boolean;
@@ -27,10 +27,10 @@ type ContextProps = {
   desynchronized?: boolean; // hints the user agent to reduce the latency by desynchronizing the canvas paint cycle from the event loop
   antialias?: boolean; // indicates whether or not to perform anti-aliasing.
   depth?: boolean; // indicates that the drawing buffer has a depth buffer of at least 16 bits.
-  failIfMajorPerformanceCaveat?: boolean, // indicates if a context will be created if the system performance is low or if no hardware GPU is available.
-  powerPreference?: 'default' |  'high-performance' | 'low-power',
-  premultipliedAlpha?: boolean, // page compositor will assume the drawing buffer contains colors with pre-multiplied alpha.
-  preserveDrawingBuffer?: boolean // buffers will not be cleared and will preserve their values until cleared or overwritten by the author.
+  failIfMajorPerformanceCaveat?: boolean; // indicates if a context will be created if the system performance is low or if no hardware GPU is available.
+  powerPreference?: 'default' | 'high-performance' | 'low-power';
+  premultipliedAlpha?: boolean; // page compositor will assume the drawing buffer contains colors with pre-multiplied alpha.
+  preserveDrawingBuffer?: boolean; // buffers will not be cleared and will preserve their values until cleared or overwritten by the author.
 };
 
 const DEFAULT_CONTEXT_PROPS: ContextProps = {
@@ -40,24 +40,27 @@ const DEFAULT_CONTEXT_PROPS: ContextProps = {
   // eslint-disable-next-line no-console
   onContextLost: () => console.error('WebGL context lost'),
   // eslint-disable-next-line no-console
-  onContextRestored: () => console.info('WebGL context restored'),
+  onContextRestored: () => console.info('WebGL context restored')
 };
 
 /**
  * Create a WebGL context for a canvas
  * Note calling this multiple time on the same canvas does return the same context
-* @param canvas A canvas element or offscreen canvas
+ * @param canvas A canvas element or offscreen canvas
  */
-export function createBrowserContext(canvas: HTMLCanvasElement | OffscreenCanvas, props: ContextProps): WebGLRenderingContext {
+export function createBrowserContext(
+  canvas: HTMLCanvasElement | OffscreenCanvas,
+  props: ContextProps
+): WebGLRenderingContext {
   props = {...DEFAULT_CONTEXT_PROPS, ...props};
 
   // Try to extract any extra information about why context creation failed
   let errorMessage = null;
-  const onCreateError = (error) => (errorMessage = error.statusMessage || errorMessage);
+  const onCreateError = error => (errorMessage = error.statusMessage || errorMessage);
   canvas.addEventListener('webglcontextcreationerror', onCreateError, false);
 
   // Create the desired context
-  let gl: WebGLRenderingContext | null = null;
+  let gl: WebGLRenderingContext | WebGL2RenderingContext | null = null;
 
   if (props.type === 'webgl2') {
     props = {...props, webgl1: false};
@@ -67,11 +70,11 @@ export function createBrowserContext(canvas: HTMLCanvasElement | OffscreenCanvas
   }
 
   // Prefer webgl2 over webgl1 if both are acceptable
-  if (props.webgl2) {
-    gl = gl || canvas.getContext('webgl2', props) ;
+  if (!gl && props.webgl2) {
+    gl = canvas.getContext('webgl2', props) as WebGL2RenderingContext;
   }
-  if (props.webgl1) {
-    gl = gl || canvas.getContext('webgl', props) ;
+  if (!gl && props.webgl1) {
+    gl = canvas.getContext('webgl', props) as WebGLRenderingContext;
   }
 
   // TODO are we removing this listener before giving it a chance to fire?
@@ -88,12 +91,16 @@ export function createBrowserContext(canvas: HTMLCanvasElement | OffscreenCanvas
   if (props.onContextLost) {
     // Carefully extract and wrap callbacks to prevent addEventListener from rebinding them.
     const {onContextLost} = props;
-    canvas.addEventListener('webglcontextlost',(event: Event) => onContextLost(event), false);
+    canvas.addEventListener('webglcontextlost', (event: Event) => onContextLost(event), false);
   }
   if (props.onContextRestored) {
     // Carefully extract and wrap callbacks to prevent addEventListener from rebinding them.
     const {onContextRestored} = props;
-    canvas.addEventListener('webglcontextrestored', (event: Event) => onContextRestored(event), false);
+    canvas.addEventListener(
+      'webglcontextrestored',
+      (event: Event) => onContextRestored(event),
+      false
+    );
   }
 
   return gl;

package/src/index.ts

@@ -76,4 +76,9 @@ export {polyfillContext} from './context/polyfill/polyfill-context';
 export {getShaderLayout, getProgramBindings} from './adapter/helpers/get-shader-layout';
 export {convertGLToTextureFormat, _checkFloat32ColorAttachment} from './adapter/converters/texture-formats';
 
-export {TEXTURE_FORMATS as _TEXTURE_FORMATS} from './adapter/converters/texture-formats';
+// TEST EXPORTS
+export {TEXTURE_FORMATS as _TEXTURE_FORMATS} from './adapter/converters/texture-formats';
+
+// DEPRECATED EXPORTS
+export {clear} from './classic/clear';
+export {readPixelsToBuffer, readPixelsToArray} from './classic/copy-and-blit';