Feature Checking

Provides WebGL feature detection.

WebGL capabilities can vary quite dramatically between browsers (from minimal WebGL 1 (e.g. headless-gl) to WebGL 1 with dozens of extensions to full WebGL 2, which also has a growing number of extensions). Unfortunately, the raw WebGL API sometimes expose the same functionalities through APIs that are slightly different and not exactly compatible.

To simplify detecting and working with conditionally available capabilities (or "features") luma.gl provides:

• A set of functions that enable you to check if the application is currently running on an environment that supports a certain feature (regardless of whether it is supported through e.g. WebGL 2 or a WebGL 1 extension).

In addition, luma.gl's WebGL classes transparently use WebGL extensions or WebGL 2 APIs as appropriate, meaning that the amount of conditional logic in application code can be kept to a minimum. Once you have established that a capability exists, luma.gl offers you one unified way to use it.

Usage

Check if a feature is available (whether as a WebGL 1 or WebGL 2 extension or through WebGL 2)

import {hasFeature, FEATURES} from '@luma.gl/webgl';
if (hasFeature(gl, FEATURES.INSTANCED_RENDERING)) {
   // Will work both on WebGL 1 (via extension) and WebGL 2 via the standard API
   program.draw({instanceCount: ..., ....});
}

Another example of feature detection

import {hasFeature, FEATURES} from '@luma.gl/webgl';
// Checks if `Query` objects can do async queries of GPU timings
if (hasFeature(gl, FEATURES.TIMER_QUERY)) {
   ...
}
// Alternatively - do the same query using raw extensions
if (hasFeature(gl, 'EXT_disjoint_timer_query') || hasFeature(gl, 'EXT_disjoint_timer_query_webgl2')) {
   ...
}

There are a few additional capability query functions sprinkled through the luma.gl API. In particular, WebGL 2 specific classes have an isSupported method that duplicates some of the queryies that can be made using the capability system

import {Query} from '@luma.gl/webgl';
if (Query.isSupported(gl)) {
  ...
}

Functions

hasFeature

Allows the app to query whether a capability is supported without being concerned about how it is being provided (WebGL 2, an extension etc)

• gl (WebGLRenderingContext) - gl context
• capability (String) - capability name (can be a webgl extension name or a luma.gl FEATURES constant).

hasFeatures

Allows the app to query whether a capability is supported without being concerned about how it is being provided (WebGL 2, an extension etc)

• gl (WebGLRenderingContext) - gl context
• feature (String|String[]) - capability name (can be a webgl extension name or a luma.gl FEATURES constant).

getFeatures

This function returns an object containing all available features.

WebGL Feature Detection

WebGL 2 Classes with some WebGL 1 support

Note that luma has a few WebGL 2 classes that can be instantiated under WebGL 1

• VertexAttributeObject. Can be instanitated under WebGL 1 if the commonly supported extension is available. Also, luma.gl treats the global vertex array as a "default" VertexArrayObject, so that can always be accessed.
• Query objects use GPU timing extensions if available. They can always be created but obviously queries will fail if capabilities are not present.
• UniformBufferLayout - this class does not create any WebGL resources, it just helps the application access memory in the layout format expected by WebGL 2 uniform buffers.

VertexAttributeObject and Query have a static isSupported() method that you can call instead of checking for WebGL 2.

WebGL 2 Classes that only work in WebGL 2

A list of luma classes that can only be instantiated under WebGL 2:

• Texture3D - e.g for volumetric rendering
• Texture2DArray - an array of textures, e.g. a texture atlas
• Sampler - holds a separate set of texture sampler parameters
• TransformFeedback - holds a list of output buffers for shaders to write to.
• Sync -

Each of these classes has a static isSupported() method that you can call instead of checking for WebGL 2.

WebGL 2-only Features

A partial list of features that are only available in WebGL 2:

• Non-power-of-2 textures - non-POT textures can have mipmaps in WebGL 2
• Sized texture formats -
• Integer based texture formats and attributes -
• Multi-Sampled renderbuffers -
• Guaranteed texture access in vertex shaders - WebGL 1 is not required to support this (although it often does)

GLSL 3.00

• textureSize - query size of texture from within shaders
• texelFetch - access textures by pixel coordinates (0-width, 0-height) instead of texel coordinates (0-1)
• inverse and transpose Matrix operations available in GLSL
• loop restrictions removed

Optional Feature Detection

The WebGL standard comes with an elaborate "extension" system allowing applications to check for the availability of features beyond the base WebGL 1 and WebGL 2 standards. These extensions tend to be rather technical, plus they have to be used differently in WebGL 1 and WebGL 2, so luma provides a simplified feature detection system. Following table lists all the available features, and their support under WebGL 1 and WebGL 2 , NO implies not supported, 'YES' implies supported and * implies supported through an extension.

Parameters to hasFeatures:

Remarks

• WebGL 1 only supports one color buffer format (RBG32F is deprecated)
• WebGL 2 supports multiple color buffer formats
• Some extensions will not be enabled until they have been queries. luma always queries on startup to enable, app only needs to query again it wants to test platform.
• The capability detection system works regardless of whether the app is running in a browser or in headless mode under Node.js.
• Naturally, given that queries to driver and GPU are typically expensive in WebGL, the capabilities system will cache any queries.