@luma.gl/webgl 8.6.0-alpha.1 → 8.6.0-alpha.5

package/src/helpers/get-program-bindings.ts

@@ -0,0 +1,244 @@
+import GL from '@luma.gl/constants';
+import {isWebGL2} from '../context/context/webgl-checks';
+import {ProgramBindings, AttributeBinding, UniformBinding, UniformBlockBinding, VaryingBinding} from './program-bindings'
+import Accessor from '../classes/accessor';
+import {decomposeCompositeGLType} from '../webgl-utils/attribute-utils';
+
+/**
+ * Extract metadata describing binding information for a program's shaders
+ * Note: `linkProgram()` needs to have been called
+ * (although linking does not need to have been successful).
+*/
+export function getProgramBindings(gl: WebGL2RenderingContext, program: WebGLProgram): ProgramBindings {
+  const config: ProgramBindings = {
+    attributes: readAttributeBindings(gl, program),
+    uniforms: readUniformBindings(gl, program),
+    uniformBlocks: readUniformBlocks(gl, program),
+    varyings: readVaryings(gl, program)
+  };
+
+  Object.seal(config);
+  return config;
+  // generateWebGPUStyleBindings(bindings);
+}
+
+
+/**
+ * Extract info about all transform feedback varyings
+ *
+ * linkProgram needs to have been called, although linking does not need to have been successful
+ */
+function readAttributeBindings(gl: WebGL2RenderingContext, program: WebGLProgram): AttributeBinding[] {
+  const attributes: AttributeBinding[] = [];
+
+  const count = gl.getProgramParameter(program, gl.ACTIVE_ATTRIBUTES);
+
+  for (let index = 0; index < count; index++) {
+    const {name, type: compositeType, size} = gl.getActiveAttrib(program, index);
+    const location = gl.getAttribLocation(program, name);
+    // Add only user provided attributes, for built-in attributes like
+    // `gl_InstanceID` locaiton will be < 0
+    if (location >= 0) {
+      const {type, components} = decomposeCompositeGLType(compositeType);
+      const accessor = {type, size: size * components};
+      inferProperties(location, name, accessor);
+    
+      const attributeInfo = {location, name, accessor: new Accessor(accessor)}; // Base values
+      attributes.push(attributeInfo);
+    }
+  }
+
+  attributes.sort((a, b) => a.location - b.location);
+  return attributes;
+}
+
+/**
+ * Extract info about all transform feedback varyings
+ *
+ * linkProgram needs to have been called, although linking does not need to have been successful
+ */
+function readVaryings(gl: WebGL2RenderingContext, program: WebGLProgram): VaryingBinding[] {
+  if (!isWebGL2(gl)) {
+    return [];
+  }
+
+  const varyings = [];
+
+  const count = gl.getProgramParameter(program, gl.TRANSFORM_FEEDBACK_VARYINGS);
+  for (let location = 0; location < count; location++) {
+    const {name, type: compositeType, size} = gl.getTransformFeedbackVarying(program, location);
+    const {type, components} = decomposeCompositeGLType(compositeType);
+    const accessor = new Accessor({type, size: size * components});
+    const varying = {location, name, accessor}; // Base values
+    varyings.push(varying);
+  }
+
+  varyings.sort((a, b) => a.location - b.location);
+  return varyings;
+}
+
+/**
+ * Extract info about all uniforms
+ *
+ * Query uniform locations and build name to setter map.
+ */
+function readUniformBindings(gl: WebGL2RenderingContext, program: WebGLProgram): UniformBinding[] {
+  const uniforms: UniformBinding[] = [];
+
+  const uniformCount = gl.getProgramParameter(program, gl.ACTIVE_UNIFORMS);
+  for (let i = 0; i < uniformCount; i++) {
+    const {name: rawName, size, type} = gl.getActiveUniform(program, i);
+    const {name, isArray} = parseUniformName(rawName);
+    let webglLocation = gl.getUniformLocation(program, name);
+    const uniformInfo = {
+      // WebGL locations are uniquely typed but just numbers
+      location: webglLocation as number,
+      name,
+      size,
+      type,
+      isArray
+    };
+    uniforms.push(uniformInfo);
+
+    // Array (e.g. matrix) uniforms can occupy several 4x4 byte banks
+    if (uniformInfo.size > 1) {
+      for (let j = 0; j < uniformInfo.size; j++) {
+        const elementName = `${name}[${j}]`;
+
+        webglLocation = gl.getUniformLocation(program, elementName);
+
+        const arrayElementUniformInfo = {
+          ...uniformInfo,
+          name: elementName,
+          location: webglLocation as number
+        };
+
+        uniforms.push(arrayElementUniformInfo);
+      }
+    }
+  }
+  return uniforms;
+}
+
+/**
+ * Extract info about all "active" uniform blocks
+ *
+ * ("Active" just means that unused (aka inactive) blocks may have been
+ * optimized away during linking)
+ */
+function readUniformBlocks(gl: WebGL2RenderingContext, program: WebGLProgram): UniformBlockBinding[] {
+  const getBlockParameter = (blockIndex, pname) => gl.getActiveUniformBlockParameter(program, blockIndex, pname);
+
+  const uniformBlocks: UniformBlockBinding[] = [];
+
+  const blockCount = gl.getProgramParameter(program, gl.ACTIVE_UNIFORM_BLOCKS);
+  for (let blockIndex = 0; blockIndex < blockCount; blockIndex++) {
+
+    const blockInfo = {
+      name: gl.getActiveUniformBlockName(program, blockIndex),
+      location: getBlockParameter(blockIndex, gl.UNIFORM_BLOCK_BINDING),
+      byteLength: getBlockParameter(blockIndex, gl.UNIFORM_BLOCK_DATA_SIZE),
+      vertex: getBlockParameter(blockIndex, gl.UNIFORM_BLOCK_REFERENCED_BY_VERTEX_SHADER),
+      fragment: getBlockParameter(blockIndex, gl.UNIFORM_BLOCK_REFERENCED_BY_FRAGMENT_SHADER),
+      uniformCount: getBlockParameter(blockIndex, gl.UNIFORM_BLOCK_ACTIVE_UNIFORMS),
+      uniformIndices: getBlockParameter(blockIndex, gl.UNIFORM_BLOCK_ACTIVE_UNIFORM_INDICES),
+      uniforms: []
+    }
+
+    for (let uniformIndex = 0; uniformIndex < blockInfo.uniformCount; ++uniformIndex) {
+      // TODO - Can we extract more?
+    }
+
+    uniformBlocks.push(blockInfo);
+  }
+
+  uniformBlocks.sort((a, b) => a.location - b.location);
+  return uniformBlocks;
+}
+
+const SAMPLER_UNIFORMS_GL_TO_GPU = {
+  [GL.SAMPLER_2D]: ['2d', 'float'],
+  [GL.SAMPLER_CUBE]: ['cube', 'float'],
+  [GL.SAMPLER_3D]: ['3d', 'float'],
+  [GL.SAMPLER_2D_SHADOW]: ['3d', 'depth'],
+  [GL.SAMPLER_2D_ARRAY]: ['2d-array', 'float'],
+  [GL.SAMPLER_2D_ARRAY_SHADOW]: ['2d-array', 'depth'],
+  [GL.SAMPLER_CUBE_SHADOW]: ['cube', 'float'],
+  [GL.INT_SAMPLER_2D]: ['2d', 'sint'],
+  [GL.INT_SAMPLER_3D]: ['3d', 'sint'],
+  [GL.INT_SAMPLER_CUBE]: ['cube', 'sint'],
+  [GL.INT_SAMPLER_2D_ARRAY]: ['2d-array', 'sint'],
+  [GL.UNSIGNED_INT_SAMPLER_2D]: ['2d', 'sint'],
+  [GL.UNSIGNED_INT_SAMPLER_3D]: ['3d', 'sint'],
+  [GL.UNSIGNED_INT_SAMPLER_CUBE]: ['cube', 'sint'],
+  [GL.UNSIGNED_INT_SAMPLER_2D_ARRAY]: ['2d-array', 'sint']
+};
+
+/**
+ * Generate a list of "WebGPU-style" bindings for this program
+ */
+function generateWebGPUStyleBindings(config: ProgramBindings) {
+  const bindings: any = [];
+
+  // Uniform blocks
+  for (const blockInfo of config.uniformBlocks) {
+    bindings.push({
+      binding: blockInfo.location,
+      visibility: (blockInfo.vertex ? 0x1 : 0) & (blockInfo.fragment ? 0x2 : 0),
+      buffer: {
+        type: 'uniform',
+        // minBindingSize: blockInfo.size
+      }
+    })
+  }
+
+  // Sampler uniforms
+  for (const uniformInfo of config.uniforms) {
+    let sampler = SAMPLER_UNIFORMS_GL_TO_GPU[uniformInfo.type];
+    if (sampler) {
+      const [viewDimension, sampleType] = sampler;
+      bindings.push({
+        binding: uniformInfo.location,
+        visibility: 0, // Not available in WebGL on individual uniforms?
+        texture: {
+          viewDimension,
+          sampleType
+        }
+      });
+    }
+  }
+}
+
+// HELPERS
+
+function parseUniformName(name) {
+  // Shortcut to avoid redundant or bad matches
+  if (name[name.length - 1] !== ']'){
+    return {
+      name,
+      length: 1,
+      isArray: false
+    };
+  }
+
+  // if array name then clean the array brackets
+  const UNIFORM_NAME_REGEXP = /([^[]*)(\[[0-9]+\])?/;
+  const matches = name.match(UNIFORM_NAME_REGEXP);
+  if (!matches || matches.length < 2) {
+    throw new Error(`Failed to parse GLSL uniform name ${name}`);
+  }
+
+  return {
+    name: matches[1],
+    length: matches[2] || 1,
+    isArray: Boolean(matches[2])
+  };
+}
+
+// Extract additional attribute metadata from shader names (based on attribute naming conventions)
+function inferProperties(accessor, location, name) {
+  if (/instance/i.test(name)) {
+    // Any attribute containing the word "instance" will be assumed to be instanced
+    accessor.divisor = 1;
+  }
+}

package/src/helpers/program-bindings.ts

@@ -0,0 +1,46 @@
+import {Accessor} from '../types/accessor';
+
+/** Describes an attribute binding for a program */
+export type AttributeBinding = {
+  location: number;
+  name: string;
+  accessor: Accessor;
+}
+
+/** Describes a varying binding for a program */
+export type VaryingBinding = {
+  location: number;
+  name: string;
+  accessor: Accessor;
+}
+
+/** Describes a uniform block binding for a program */
+export type UniformBlockBinding = {
+  location: number;
+  name: string;
+  byteLength: number;
+  vertex: boolean;
+  fragment: boolean;
+  uniformCount: number;
+  uniformIndices: number[];
+}
+
+/** Describes a uniform (sampler etc) binding for a program */
+export type UniformBinding = {
+  location: number;
+  name: string;
+  size: number;
+  type: number;
+  isArray: boolean;
+}
+
+/**
+ * Holds metadata describing attribute configurations for a program's shaders
+ */
+export type ProgramBindings = {
+  readonly attributes: AttributeBinding[];
+  readonly varyings: VaryingBinding[];
+  readonly uniformBlocks: UniformBlockBinding[];
+  // Note - samplers are always in unform bindings, even if uniform blocks are used
+  readonly uniforms: UniformBinding[];
+}

package/src/index.ts

@@ -5,7 +5,11 @@
 // Higher level abstractions can be built on these classes
 
 // Initialize any global state
-export {lumaStats} from './init';
+import './init';
+
+// export type {WebGLDeviceProps, WebGLDeviceInfo, WebGPUDeviceLimits} from './lib/webgl-device';
+export type {WebGLDeviceProps} from './adapter/webgl-device';
+export {default as WebGLDevice, getWebGLDevice} from './adapter/webgl-device';
 
 // UTILS
 export {requestAnimationFrame, cancelAnimationFrame} from './webgl-utils/request-animation-frame';
@@ -13,24 +17,28 @@ export {requestAnimationFrame, cancelAnimationFrame} from './webgl-utils/request
 // WebGL Functions
 export {cloneTextureFrom} from './webgl-utils/texture-utils';
 export {getKeyValue, getKey} from './webgl-utils/constants-to-keys';
-export {getContextInfo, getGLContextInfo, getContextLimits} from './features/limits';
-export {FEATURES} from './features/webgl-features-table';
-export {hasFeature, hasFeatures, getFeatures} from './features/features';
-export {default as canCompileGLGSExtension} from './features/check-glsl-extension';
 
 // WebGL Helper Classes
 export {default as Accessor} from './classes/accessor';
 
 // WebGL1 classes
-// export type {BufferProps} from './api/buffer';
+export type {BufferProps} from '@luma.gl/api';
 export {default as Buffer} from './classes/webgl-buffer';
-export {default as Texture2D, Texture2DProps} from './classes/texture-2d';
-export {default as TextureCube, TextureCubeProps} from './classes/texture-cube';
+export type {Texture2DProps} from './classes/texture-2d';
+export {default as Texture2D} from './classes/texture-2d';
+export type {TextureCubeProps} from './classes/texture-cube';
+export {default as TextureCube} from './classes/texture-cube';
+
+export type {ProgramProps} from './classes/program';
+export {default as Program} from './classes/program';
+export type {FramebufferProps} from './classes/framebuffer';
+export {default as Framebuffer} from './classes/framebuffer';
+export type {RenderbufferProps} from './classes/renderbuffer';
+export {default as Renderbuffer} from './classes/renderbuffer';
 
-export {Shader, VertexShader, FragmentShader, ShaderProps} from './classes/webgl-shader';
-export {default as Program, ProgramProps} from './classes/program';
-export {default as Framebuffer, FramebufferProps} from './classes/framebuffer';
-export {default as Renderbuffer, RenderbufferProps} from './classes/renderbuffer';
+// Classic luma.gl classes (For backwards compatibility)
+export type {ShaderProps} from './classes/shader';
+export {Shader, VertexShader, FragmentShader} from './classes/shader';
 
 export {clear, clearBuffer} from './classes/clear';
 
@@ -45,21 +53,56 @@ export {
 } from './classes/copy-and-blit';
 
 // WebGL2 classes & Extensions
-export {default as Query, QueryProps} from './classes/query';
-export {default as Texture3D, Texture3DProps} from './classes/texture-3d';
-export {default as TransformFeedback, TransformFeedbackProps} from './classes/transform-feedback';
-export {default as VertexArrayObject, VertexArrayObjectProps} from './classes/vertex-array-object';
-export {default as VertexArray, VertexArrayProps} from './classes/vertex-array';
+export type {QueryProps} from './classes/query';
+export {default as Query} from './classes/query';
+export type {Texture3DProps} from './classes/texture-3d';
+export {default as Texture3D} from './classes/texture-3d';
+export type {TransformFeedbackProps} from './classes/transform-feedback';
+export {default as TransformFeedback} from './classes/transform-feedback';
+export type {VertexArrayObjectProps} from './classes/vertex-array-object';
+export {default as VertexArrayObject} from './classes/vertex-array-object';
+export type {VertexArrayProps} from './classes/vertex-array';
+export {default as VertexArray} from './classes/vertex-array';
 export {default as UniformBufferLayout} from './classes/uniform-buffer-layout';
 
-// experimental WebGL exports
+export {setDeviceParameters} from './adapter/converters/set-device-parameters';
 
-export {setPathPrefix, loadFile, loadImage} from './utils/load-file';
+// experimental WebGL exports
 
 // UTILS
-export {log} from '@luma.gl/gltools';
-export {default as assert} from './utils/assert';
-export {uid, isObjectEmpty} from './utils/utils';
+export {
+  isWebGL,
+  isWebGL2,
+  getWebGL2Context,
+  assertWebGLContext,
+  assertWebGL2Context
+} from './context/context/webgl-checks';
+
+// Device ratio
+export {cssToDeviceRatio, cssToDevicePixels} from './context/context/device-pixels';
+
+// Unified parameter API
+
+export type {GLParameters} from './context/parameters/webgl-parameters';
+export {
+  getParameters,
+  setParameters,
+  resetParameters
+} from './context/parameters/unified-parameter-api';
+
+export {
+  withParameters
+} from './context/state-tracker/with-parameters';
+
+// State tracking
+export {
+  trackContextState,
+  pushContextState,
+  popContextState
+} from './context/state-tracker/track-context-state';
+
+// Polyfills (supports a subset of WebGL2 APIs on WebGL1 contexts)
+export {polyfillContext} from './context/polyfill/polyfill-context';
 
 // INTERNAL
 export {parseUniformName, getUniformSetter} from './classes/uniforms';
@@ -67,7 +110,35 @@ export {getDebugTableForUniforms} from './debug/debug-uniforms';
 export {getDebugTableForVertexArray} from './debug/debug-vertex-array';
 export {getDebugTableForProgramConfiguration} from './debug/debug-program-configuration';
 
-// REMOVED in v8.6
+// HELPERS - EXPERIMENTAL
+export {getProgramBindings} from './helpers/get-program-bindings';
+
+// DEPRECATED
+
+// Deprecated re-exports
+export {lumaStats} from './init';
+export {log, assert, uid, isObjectEmpty} from '@luma.gl/api';
+export {setPathPrefix, loadFile, loadImage} from '@luma.gl/api';
+
+// GLTOOLS
+export type {GLContextOptions} from './_deprecated/context-api';
+export {
+  createGLContext,
+  instrumentGLContext,
+  resizeGLContext,
+  hasFeature,
+  hasFeatures,
+  getFeatures,
+  getContextInfo,
+  getGLContextInfo,
+  getContextLimits,
+  getContextDebugInfo
+} from './_deprecated/context-api';
+
+// Features
+export {DEPRECATED_FEATURES as FEATURES} from './_deprecated/features';
+
+// REMOVED in v8.7
 // getShaderInfo,
 // getShaderName
 // getShaderVersion

package/src/init.ts

@@ -1,9 +1,10 @@
-import {log} from '@luma.gl/gltools';
-import {isBrowser, global} from 'probe.gl/env';
-import {lumaStats} from '@luma.gl/api';
+import {log} from '@luma.gl/api';
+import {isBrowser} from '@probe.gl/env';
+import {luma, lumaStats} from '@luma.gl/api';
+import WebGLDevice from './adapter/webgl-device';
 
 // Version detection using babel plugin
-// @ts-ignore
+// @ts-expect-error
 const VERSION = typeof __VERSION__ !== 'undefined' ? __VERSION__ : 'untranspiled source';
 
 const STARTUP_MESSAGE = 'set luma.log.level=1 (or higher) to trace rendering';
@@ -11,16 +12,18 @@ const STARTUP_MESSAGE = 'set luma.log.level=1 (or higher) to trace rendering';
 // 0: none, 1: minimal, 2: verbose, 3: attribute/uniforms, 4: gl logs
 // luma.log.break[], set to gl funcs, luma.log.profile[] set to model names`;
 
-if (global.luma && global.luma.VERSION !== VERSION) {
-  throw new Error(`luma.gl - multiple VERSIONs detected: ${global.luma.VERSION} vs ${VERSION}`);
+if (globalThis.luma && globalThis.luma.VERSION !== VERSION) {
+  throw new Error(`luma.gl - multiple VERSIONs detected: ${globalThis.luma.VERSION} vs ${VERSION}`);
 }
 
-if (!global.luma) {
+if (!globalThis.luma) {
+  luma.registerDevices([WebGLDevice]);
+
   if (isBrowser()) {
     log.log(1, `luma.gl ${VERSION} - ${STARTUP_MESSAGE}`)();
   }
 
-  global.luma = global.luma || {
+  globalThis.luma = globalThis.luma || {
     VERSION,
     version: VERSION,
     log,
@@ -42,4 +45,4 @@ if (!global.luma) {
 }
 
 export {lumaStats};
-export default global.luma;
+export default globalThis.luma;

package/src/types/accessor.d.ts

@@ -0,0 +1,29 @@
+// ACCESSORS
+
+/**
+ * Attribute descriptor object
+ */
+export type Accessor = {
+  format?: string;
+  offset?: number;
+  location?: number;
+
+  // can now be described with single WebGPU-style `format` string
+  type?: number;
+  size?: number;
+  normalized?: boolean;
+  integer?: boolean;
+
+  // deprecated - now shared between accessors in the surrounding BufferAccessor object
+  stride?: number;
+  divisor?: number;
+};
+
+/**
+ * List of attribute descriptors for one interleaved buffer
+ */
+export type BufferAccessors = {
+  stride?: number;
+  stepMode?: 'vertex' | 'instance';
+  attributes: Accessor[];
+}

package/src/types.ts

@@ -5,4 +5,4 @@ export type AccessorObject = {
   divisor?: number;
   offset?: number;
   stride?: number;
-};
+};

package/src/webgl-utils/attribute-utils.ts

@@ -1,4 +1,4 @@
-import {assert} from '../utils';
+import {assert} from '@luma.gl/api';
 
 const GL_BYTE = 0x1400;
 const GL_UNSIGNED_BYTE = 0x1401;

package/src/webgl-utils/constants-to-keys.ts

@@ -1,4 +1,4 @@
-import {assert} from '../utils';
+import {assert} from '@luma.gl/api';
 
 // Resolve a WebGL enumeration name (returns itself if already a number)
 export function getKeyValue(gl, name) {

package/src/webgl-utils/format-utils.ts

@@ -1,5 +1,5 @@
+import {assert} from '@luma.gl/api';
 import GL from '@luma.gl/constants';
-import {assert} from '../utils';
 
 // Returns number of components in a specific readPixels WebGL format
 export function glFormatToComponents(format) {

package/src/webgl-utils/{texture-utils.js → texture-utils.ts}

@@ -1,14 +1,16 @@
 // TODO: Two subdirectories must not depend on each other (classes vs utils)!
+import {assert} from '@luma.gl/api';
+import GL from '@luma.gl/constants';
+import Texture from '../classes/texture';
 import Texture2D from '../classes/texture-2d';
 import TextureCube from '../classes/texture-cube';
 import Texture3D from '../classes/texture-3d';
-import Framebuffer from '../classes/framebuffer';
-import GL from '@luma.gl/constants';
-import {assert} from '../utils';
+import Framebuffer, {FramebufferProps} from '../classes/framebuffer';
+
+type TextureType = Texture2D | TextureCube | Texture3D;
 
-// Clone a new texture object from a reference texture object.
-/** @type {import('./texture-utils').cloneTextureFrom} */
-export function cloneTextureFrom(refTexture, overrides) {
+/** Clone a new texture object from a reference texture object. */
+export function cloneTextureFrom<T extends TextureType>(refTexture: T, overrides?: any): T {
   assert(
     refTexture instanceof Texture2D ||
       refTexture instanceof TextureCube ||
@@ -37,10 +39,11 @@ export function cloneTextureFrom(refTexture, overrides) {
   return new TextureType(gl, textureOptions);
 }
 
-// Wraps a given texture into a framebuffer object, that can be further used
-// to read data from the texture object.
-/** @type {import('./texture-utils').toFramebuffer} */
-export function toFramebuffer(texture, opts) {
+/**
+ * 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, opts?: FramebufferProps): Framebuffer {
   const {gl, width, height, id} = texture;
   const framebuffer = new Framebuffer(
     gl,