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

package/src/_deprecated/context-api.ts

@@ -0,0 +1,140 @@
+// luma.gl, MIT license
+// LEGACY luma.gl v8 API for WebGLRendering context
+// DEPRECATED API - may be removed in luma.gl v9 or v10.
+
+/* eslint-disable quotes */
+import GL from '@luma.gl/constants';
+import {WebGLDevice, WebGLDeviceProps} from '@luma.gl/webgl';
+import {FEATURES} from './features';
+
+export type GLContextOptions = WebGLDeviceProps & {
+  throwOnError?: boolean; // If set to false, return `null` if context creation fails.
+};
+
+/** @deprecated Use `new WebGLDevice()` or `luma.createDevice()` */
+export function createGLContext(options?: GLContextOptions): WebGLRenderingContext | null {
+  const webglDevice = new WebGLDevice(options);
+  // Note: OK to return the context, it holds on to the device
+  return webglDevice.gl;
+}
+
+/** @deprecated Use `WebGLDevice.attach()` */
+export function instrumentGLContext(
+  gl: WebGLRenderingContext | WebGL2RenderingContext,
+  options?: GLContextOptions
+): WebGLRenderingContext {
+  const webglDevice = WebGLDevice.attach(gl, options);
+  return webglDevice.gl;
+}
+
+/**
+ * Resize the canvas' drawing buffer.
+ *
+ * Can match the canvas CSS size, and optionally also consider devicePixelRatio
+ * Can be called every frame
+ *
+ * Regardless of size, the drawing buffer will always be scaled to the viewport, but
+ * for best visual results, usually set to either:
+ *  canvas CSS width x canvas CSS height
+ *  canvas CSS width * devicePixelRatio x canvas CSS height * devicePixelRatio
+ * See http://webgl2fundamentals.org/webgl/lessons/webgl-resizing-the-canvas.html
+ *
+ * resizeGLContext(gl, {width, height, useDevicePixels})
+ * @deprecated Use WebGLDevice.resize()
+ */
+export function resizeGLContext(
+  gl: WebGLRenderingContext,
+  options?: {
+    width?: number;
+    height?: number;
+    useDevicePixels?: boolean | number;
+  }
+) {
+  const webglDevice = WebGLDevice.attach(gl);
+  webglDevice.resize(options);
+}
+
+/** 
+ * Check one or more features
+ * @deprecated Use `WebGLDevice.features.has()`
+*/
+export function hasFeatures(gl: WebGLRenderingContext, features: string | string[]): boolean {
+  const webglDevice = WebGLDevice.attach(gl);
+  const normalizedFeatures = Array.isArray(features) ? features : [features];
+  const deviceFeatures = normalizedFeatures.map(feature => getDeviceFeature(feature));
+  return deviceFeatures.every((feature) => webglDevice.webglFeatures.has(feature));
+}
+
+function getDeviceFeature(feature) {
+  return feature.toLowerCase().replace('webgl-', '').replace('-', '_');
+}
+
+/**
+ * Check one feature
+ * @deprecated Use `WebGLDevice.features`
+ */
+export function hasFeature(gl: WebGLRenderingContext, feature: string): boolean {
+  return hasFeatures(gl, feature);
+}
+
+/**
+ * Return a map of supported features
+ * @deprecated Use `WebGLDevice.features`
+ */
+export function getFeatures(gl: WebGLRenderingContext): Record<string, boolean>  {
+  const webglDevice = WebGLDevice.attach(gl);
+  const featureMap: Record<string, boolean> = {};
+  for (const feature in FEATURES) {
+    featureMap[feature] = webglDevice.webglFeatures.has(feature);
+  }
+  return featureMap;
+}
+
+/**
+ * Provides strings identifying the GPU vendor and driver.
+ * https://www.khronos.org/registry/webgl/extensions/WEBGL_debug_renderer_info/
+ *
+ * @deprecated Use `WebGLDevice.info`
+ */
+export function getContextDebugInfo(gl: WebGLRenderingContext): {
+  vendor: string;
+  renderer: string;
+  vendorMasked: string;
+  rendererMasked: string;
+  version: string;
+} {
+  const webglDevice = WebGLDevice.attach(gl);
+  const info = webglDevice.info;
+  return {
+    ...webglDevice.info,
+    vendorMasked: webglDevice.info.vendor,
+    rendererMasked: webglDevice.info.renderer
+  };
+}
+
+/** @deprecated Use `WebGLDevice.info` */
+export function getGLContextInfo(gl) {
+  const info = getContextDebugInfo(gl);
+  return {
+    [GL.UNMASKED_VENDOR_WEBGL]: info.vendor,
+    [GL.UNMASKED_RENDERER_WEBGL]: info.renderer,
+    [GL.VENDOR]: info.vendorMasked,
+    [GL.RENDERER]: info.rendererMasked,
+    [GL.VERSION]: info.version,
+  };
+}
+
+/** @deprecated Use `WebGLDevice.info` and `WebGLDevice.limits` */
+export function getContextInfo(gl) {
+  return {
+    ...getContextDebugInfo(gl),
+    ...getContextLimits(gl),
+    info: getGLContextInfo(gl),
+  };
+}
+
+/** @deprecated Use `WebGLDevice.limits` */
+export function getContextLimits(gl) {
+  const webglDevice = WebGLDevice.attach(gl);
+  return {limits: webglDevice.webglLimits};
+}

package/src/_deprecated/features.ts

@@ -0,0 +1,159 @@
+// Feature detection for WebGL
+// Provides a function that enables simple checking of which WebGL features are
+// available in an WebGL1 or WebGL2 environment.
+
+import GL from '@luma.gl/constants';
+import {isWebGL2} from '@luma.gl/webgl';
+import {assert} from '@luma.gl/api';
+
+// TODO - this should be the default export, test cases need updating
+export const FEATURES = {
+  WEBGL2: 'WEBGL2',
+
+  // API SUPPORT
+  VERTEX_ARRAY_OBJECT: 'VERTEX_ARRAY_OBJECT',
+  TIMER_QUERY: 'TIMER_QUERY',
+  INSTANCED_RENDERING: 'INSTANCED_RENDERING',
+  MULTIPLE_RENDER_TARGETS: 'MULTIPLE_RENDER_TARGETS',
+
+  // FEATURES
+  ELEMENT_INDEX_UINT32: 'ELEMENT_INDEX_UINT32',
+
+  // BLENDING
+  BLEND_EQUATION_MINMAX: 'BLEND_EQUATION_MINMAX',
+  FLOAT_BLEND: 'FLOAT_BLEND',
+
+  // TEXTURES: '// TEXTURES', RENDERBUFFERS
+  COLOR_ENCODING_SRGB: 'COLOR_ENCODING_SRGB',
+
+  // TEXTURES
+  TEXTURE_DEPTH: 'TEXTURE_DEPTH',
+  TEXTURE_FLOAT: 'TEXTURE_FLOAT',
+  TEXTURE_HALF_FLOAT: 'TEXTURE_HALF_FLOAT',
+
+  TEXTURE_FILTER_LINEAR_FLOAT: 'TEXTURE_FILTER_LINEAR_FLOAT',
+  TEXTURE_FILTER_LINEAR_HALF_FLOAT: 'TEXTURE_FILTER_LINEAR_HALF_FLOAT',
+  TEXTURE_FILTER_ANISOTROPIC: 'TEXTURE_FILTER_ANISOTROPIC',
+
+  // FRAMEBUFFERS: '// FRAMEBUFFERS', TEXTURES AND RENDERBUFFERS
+  COLOR_ATTACHMENT_RGBA32F: 'COLOR_ATTACHMENT_RGBA32F',
+  COLOR_ATTACHMENT_FLOAT: 'COLOR_ATTACHMENT_FLOAT',
+  COLOR_ATTACHMENT_HALF_FLOAT: 'COLOR_ATTACHMENT_HALF_FLOAT',
+
+  // GLSL extensions
+  GLSL_FRAG_DATA: 'GLSL_FRAG_DATA',
+  GLSL_FRAG_DEPTH: 'GLSL_FRAG_DEPTH',
+  GLSL_DERIVATIVES: 'GLSL_DERIVATIVES',
+  GLSL_TEXTURE_LOD: 'GLSL_TEXTURE_LOD'
+};
+
+/** Extract all WebGL features */
+export function getWebGLFeatures(gl: WebGLRenderingContext): Set<string> {
+  // Enable EXT_float_blend first: https://developer.mozilla.org/en-US/docs/Web/API/EXT_float_blend
+  gl.getExtension('EXT_color_buffer_float');
+  gl.getExtension('WEBGL_color_buffer_float');
+  gl.getExtension('EXT_float_blend');
+
+  const features = new Set<string>();
+  for (const feature in WEBGL_FEATURES) {
+    if (isFeatureSupported(gl, feature)) {
+      features.add(feature);
+    }
+  }
+  return features;
+}
+
+function isFeatureSupported(gl: WebGLRenderingContext, cap: string): boolean {
+  const feature = WEBGL_FEATURES[cap];
+  assert(feature, cap);
+
+  const [webgl1Feature, webgl2Feature] = feature;
+
+  // Get extension name from table
+  const featureDefinition = isWebGL2(gl) ? webgl2Feature : webgl1Feature;
+
+  if (cap === FEATURES.COLOR_ATTACHMENT_RGBA32F && !isWebGL2(gl)) {
+    return checkFloat32ColorAttachment(gl);
+  }
+
+  // Check if the value is dependent on checking one or more extensions
+  if (typeof featureDefinition === 'string') {
+    return Boolean(gl.getExtension(featureDefinition));
+  }
+
+  return featureDefinition;
+}
+
+
+// function to test if Float 32 bit format texture can be bound as color attachment
+function checkFloat32ColorAttachment(gl: WebGLRenderingContext) {
+  let texture: WebGLTexture;
+  let framebuffer: WebGLFramebuffer;
+  try {
+    const texture = gl.createTexture();
+    gl.bindTexture(GL.TEXTURE_2D, texture);
+
+    const level = 0;
+    const internalFormat = gl.RGBA;
+    const width = 1;
+    const height = 1;
+    const border = 0;
+    const srcFormat = gl.RGBA;
+    const srcType = gl.UNSIGNED_BYTE;
+    const pixel = new Uint8Array([0, 0, 255, 255]);  // opaque blue
+    gl.texImage2D(gl.TEXTURE_2D, level, internalFormat,
+                  width, height, border, srcFormat, srcType,
+                  pixel);
+
+    const framebuffer = gl.createFramebuffer();
+    gl.bindFramebuffer(GL.FRAMEBUFFER, framebuffer);
+    gl.framebufferTexture2D(GL.FRAMEBUFFER, GL.COLOR_ATTACHMENT0, GL.TEXTURE_2D, texture, 0);
+    const status = gl.checkFramebufferStatus(GL.FRAMEBUFFER) === GL.FRAMEBUFFER_COMPLETE;
+    return status;
+  } finally {
+    gl.deleteTexture(texture);
+    gl.deleteFramebuffer(framebuffer);
+  }
+}
+
+// Defines luma.gl "feature" names and semantics
+// Format: 'feature-name: [WebGL1 support, WebGL2 support] / [WebGL1 and WebGL2 support]', when support is 'string' it is the name of the extension
+const WEBGL_FEATURES: Record<string, [boolean | string, boolean | string]> = {
+  [FEATURES.WEBGL2]: [false, true],
+
+  // API SUPPORT
+  [FEATURES.VERTEX_ARRAY_OBJECT]: ['OES_vertex_array_object', true],
+  [FEATURES.TIMER_QUERY]: ['EXT_disjoint_timer_query', 'EXT_disjoint_timer_query_webgl2'],
+  [FEATURES.INSTANCED_RENDERING]: ['ANGLE_instanced_arrays', true],
+  [FEATURES.MULTIPLE_RENDER_TARGETS]: ['WEBGL_draw_buffers', true],
+
+  // FEATURES
+  [FEATURES.ELEMENT_INDEX_UINT32]: ['OES_element_index_uint', true],
+
+  // BLENDING
+  [FEATURES.BLEND_EQUATION_MINMAX]: ['EXT_blend_minmax', true],
+  [FEATURES.FLOAT_BLEND]: ['EXT_float_blend', 'EXT_float_blend'],
+
+  // TEXTURES, RENDERBUFFERS
+  [FEATURES.COLOR_ENCODING_SRGB]: ['EXT_sRGB', true],
+
+  // TEXTURES
+  [FEATURES.TEXTURE_DEPTH]: ['WEBGL_depth_texture', true],
+  [FEATURES.TEXTURE_FLOAT]: ['OES_texture_float', true],
+  [FEATURES.TEXTURE_HALF_FLOAT]: ['OES_texture_half_float', true],
+
+  [FEATURES.TEXTURE_FILTER_LINEAR_FLOAT]: ['OES_texture_float_linear', 'OES_texture_float_linear'],
+  [FEATURES.TEXTURE_FILTER_LINEAR_HALF_FLOAT]: ['OES_texture_half_float_linear', 'OES_texture_half_float_linear'],
+  [FEATURES.TEXTURE_FILTER_ANISOTROPIC]: ['EXT_texture_filter_anisotropic', 'EXT_texture_filter_anisotropic'],
+
+  // FRAMEBUFFERS, TEXTURES AND RENDERBUFFERS
+  [FEATURES.COLOR_ATTACHMENT_RGBA32F]: [false, 'EXT_color_buffer_float'], // Note override check
+  [FEATURES.COLOR_ATTACHMENT_FLOAT]: [false, 'EXT_color_buffer_float'],
+  [FEATURES.COLOR_ATTACHMENT_HALF_FLOAT]: ['EXT_color_buffer_half_float', 'EXT_color_buffer_half_float'],
+
+  // GLSL extensions
+  [FEATURES.GLSL_FRAG_DATA]: ['WEBGL_draw_buffers', true],
+  [FEATURES.GLSL_FRAG_DEPTH]: ['EXT_frag_depth', true],
+  [FEATURES.GLSL_DERIVATIVES]: ['OES_standard_derivatives', true],
+  [FEATURES.GLSL_TEXTURE_LOD]: ['EXT_shader_texture_lod', true]
+};

package/src/index.ts

@@ -110,6 +110,9 @@ export {getDebugTableForUniforms} from './debug/debug-uniforms';
 export {getDebugTableForVertexArray} from './debug/debug-vertex-array';
 export {getDebugTableForProgramConfiguration} from './debug/debug-program-configuration';
 
+// HELPERS - EXPERIMENTAL
+export {getProgramBindings} from './helpers/get-program-bindings';
+
 // DEPRECATED
 
 // Deprecated re-exports
@@ -117,15 +120,23 @@ export {lumaStats} from './init';
 export {log, assert, uid, isObjectEmpty} from '@luma.gl/api';
 export {setPathPrefix, loadFile, loadImage} from '@luma.gl/api';
 
-// export {
-//   getContextInfo, getGLContextInfo, getContextLimits,
-//   FEATURES,
-//   getFeatures,
-//   canCompileGLGSExtension
-// } from '@luma.gl/gltools';
-
-// HELPERS - EXPERIMENTAL
-export {getProgramBindings} from './helpers/get-program-bindings';
+// 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 {FEATURES} from './_deprecated/features';
 
 // REMOVED in v8.7
 // getShaderInfo,