@luma.gl/webgl 9.0.0-alpha.4 → 9.0.0-alpha.41

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

@@ -0,0 +1,314 @@
+// luma.gl, MIT license
+// Copyright (c) vis.gl contributors
+
+import {assert, Texture, Framebuffer, FramebufferProps} from '@luma.gl/core';
+import {GL} from '@luma.gl/constants';
+
+import {BufferWithAccessor as Buffer} from './buffer-with-accessor';
+import {WEBGLTexture} from '../adapter/resources/webgl-texture';
+import {WEBGLFramebuffer} from '../adapter/resources/webgl-framebuffer';
+import {withGLParameters} 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,
+    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 WEBGLTexture)?.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;
+  }
+): 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}});
+  }
+
+  target.bind({glTarget: GL.PIXEL_PACK_BUFFER});
+  withGLParameters(gl2, {framebuffer}, () => {
+    gl2.readPixels(
+      sourceX,
+      sourceY,
+      sourceWidth,
+      sourceHeight,
+      sourceFormat,
+      sourceType,
+      targetByteOffset
+    );
+  });
+  target.unbind({glTarget: GL.PIXEL_PACK_BUFFER});
+  if (deleteFramebuffer) {
+    framebuffer.destroy();
+  }
+
+  return target;
+}
+
+/**
+ * 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.assertWebGL2();
+        device.gl2.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,46 @@
+// luma.gl, MIT license
+// 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,26 +1,18 @@
-import {TypedArray} from '@luma.gl/api/types';
-import GL from '@luma.gl/constants';
-import {GLType} from '../types/webgl'
+// luma.gl, MIT license
+// Copyright (c) vis.gl contributors
 
-const ERR_TYPE_DEDUCTION = 'Failed to deduce GL constant from typed array';
+import {TypedArray, TypedArrayConstructor} from '@luma.gl/core';
+import {GL, GLDataType, GLPixelType} from '@luma.gl/constants';
 
-type TypedArrayConstructor =
-  | Float32ArrayConstructor
-  | Uint16ArrayConstructor
-  | Uint32ArrayConstructor
-  | Uint8ArrayConstructor
-  | Uint8ClampedArrayConstructor
-  | Int8ArrayConstructor
-  | Int16ArrayConstructor
-  | Int32ArrayConstructor;
+const ERR_TYPE_DEDUCTION = 'Failed to deduce GL constant from typed array';
 
 /**
  * Converts TYPED ARRAYS to corresponding GL constant
  * Used to auto deduce gl parameter types
- * @param {*} arrayOrType
+ * @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) {
@@ -48,13 +40,13 @@ export function getGLTypeFromTypedArray(arrayOrType: TypedArray): GLType {
 /**
  * Converts GL constant to corresponding TYPED ARRAY
  * Used to auto deduce gl parameter types
- * @param {*} glType
- * @param {*} param1
+ * @param glType
+ * @param param1
  * @returns
  */
 // eslint-disable-next-line complexity
 export function getTypedArrayFromGLType(
-  glType: any,
+  glType: GLDataType | GLPixelType,
   options?: {
     clamped?: boolean;
   }
@@ -88,14 +80,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,9 +108,9 @@ export function getTypedArrayFromGLType(
 
 
 export function scalePixels(options: {
-  data: any;
-  width: any;
-  height: any;
+  data: TypedArray;
+  width: number;
+  height: number;
 }): {
   data: Uint8Array;
   width: number;

package/src/context/context/create-browser-context.ts

@@ -0,0 +1,140 @@
+// luma.gl, MIT license
+// Copyright (c) vis.gl contributors
+
+/**
+ * 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.
+ */
+type ContextProps = {
+  type?: 'webgl' | 'webgl1' | 'webgl2' | string;
+  webgl1?: boolean;
+  webgl2?: boolean;
+  onContextLost?: (event: Event) => void;
+  onContextRestored?: (event: Event) => void;
+  alpha?: boolean; // indicates if the canvas contains an alpha buffer.
+  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.
+};
+
+const DEFAULT_CONTEXT_PROPS: ContextProps = {
+  webgl2: true, // Attempt to create a WebGL2 context
+  webgl1: true, // Attempt to create a WebGL1 context (false to fail if webgl2 not available)
+  powerPreference: 'high-performance', // After all, most apps are using WebGL for performance reasons
+  // eslint-disable-next-line no-console
+  onContextLost: () => console.error('WebGL context lost'),
+  // eslint-disable-next-line no-console
+  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
+ */
+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);
+  canvas.addEventListener('webglcontextcreationerror', onCreateError, false);
+
+  // Create the desired context
+  let gl: WebGLRenderingContext | WebGL2RenderingContext | null = null;
+
+  if (props.type === 'webgl2') {
+    props = {...props, webgl1: false};
+  }
+  if (props.type === 'webgl1') {
+    props = {...props, webgl2: false};
+  }
+
+  // props.failIfMajorPerformanceCaveat = true;
+
+  // Prefer webgl2 over webgl1 if both are acceptable
+  if (!gl && props.webgl2) {
+    gl = canvas.getContext('webgl2', props) as WebGL2RenderingContext;
+  }
+  if (!gl && props.webgl1) {
+    gl = canvas.getContext('webgl', props) as WebGLRenderingContext;
+  }
+
+  // Software GPU
+
+  // props.failIfMajorPerformanceCaveat = false;
+  // if (!gl && props.webgl2) {
+  //   gl = canvas.getContext('webgl2', props);
+  // }
+  // if (!gl && props.webgl1) {
+  //   gl = canvas.getContext('webgl', props);
+  // }
+
+  // TODO are we removing this listener before giving it a chance to fire?
+  canvas.removeEventListener('webglcontextcreationerror', onCreateError, false);
+
+  if (!gl) {
+    throw new Error(
+      `Failed to create ${props.webgl2 && !props.webgl1 ? 'WebGL2' : 'WebGL'} context: ${
+        errorMessage || 'Unknown error'
+      }`
+    );
+  }
+
+  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);
+  }
+  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
+    );
+  }
+
+  return gl;
+}
+
+/* TODO - can we call this asynchronously to catch the error events?
+export async function createBrowserContextAsync(canvas: HTMLCanvasElement | OffscreenCanvas, props: ContextProps): Promise<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);
+ canvas.addEventListener('webglcontextcreationerror', onCreateError, false);
+
+ const gl = createBrowserContext(canvas, props);
+
+ // Give the listener a chance to fire
+ await new Promise(resolve => setTimeout(resolve, 0));
+
+ canvas.removeEventListener('webglcontextcreationerror', onCreateError, false);
+
+ return gl;
+}
+*/

package/src/context/context/create-headless-context.ts

@@ -0,0 +1,51 @@
+// luma.gl, MIT license
+// Copyright (c) vis.gl contributors
+
+const ERR_HEADLESSGL_FAILED =
+  'Failed to create WebGL context in Node.js, headless gl returned null';
+
+const ERR_HEADLESSGL_LOAD = '\
+  luma.gl: loaded under Node.js without headless gl installed, meaning that WebGL \
+  contexts can not be created. This may not be an error. For example, this is a \
+  typical configuration for isorender applications running on the server.';
+
+const CONTEXT_DEFAULTS = {
+  width: 1,
+  height: 1,
+  debug: true,
+  throwOnError: false
+};
+
+/** Duck typing for the main headless gl export, a function to create contexts */
+export type HeadlessGL = (width: number, height: number, options: Record<string, unknown>) => WebGLRenderingContext;
+
+let headlessGL: HeadlessGL | null = null; 
+
+/** By importing `gl` and registering it with this function, contexts can be created under Node.js */
+export function registerHeadlessGL(headlessgl: HeadlessGL) {
+  headlessGL = headlessgl;
+}
+
+/** @returns true if headless gl is registered */
+export function isHeadlessGLRegistered(): boolean {
+  return headlessGL !== null;
+}
+
+/** Create headless gl context (for running under Node.js) */
+export function createHeadlessContext(options?: Record<string, any>): WebGLRenderingContext {
+  options = {...CONTEXT_DEFAULTS, ...options};
+
+  const {width, height, webgl1, webgl2} = options;
+
+  if (webgl2 && !webgl1) {
+    throw new Error('headless-gl does not support WebGL2');
+  }
+  if (!headlessGL) {
+    throw new Error(ERR_HEADLESSGL_LOAD);
+  }
+  const gl = headlessGL(width, height, options);
+  if (!gl) {
+    throw new Error(ERR_HEADLESSGL_FAILED);
+  }
+  return gl;
+}

package/src/context/context/webgl-checks.ts

@@ -1,5 +1,7 @@
 // luma.gl, MIT license
-import {assert} from '@luma.gl/api';
+// Copyright (c) vis.gl contributors
+
+import {assert} from '@luma.gl/core';
 
 const ERR_CONTEXT = 'Invalid WebGLRenderingContext';
 export const ERR_WEBGL = ERR_CONTEXT;