@itwin/webgl-compatibility
Version:
APIs for determining the level of compatibility of a browser+device with the iTwin.js rendering system.
115 lines • 7.72 kB
JavaScript
/*---------------------------------------------------------------------------------------------
* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
* See LICENSE.md in the project root for license terms and full copyright notice.
*--------------------------------------------------------------------------------------------*/
/** @packageDocumentation
* @module Compatibility
*/
import { Capabilities } from "./Capabilities";
/** Enumerates the required and optional WebGL features used by the [RenderSystem]($frontend).
* @public
*/
export var WebGLFeature;
(function (WebGLFeature) {
/** This feature allows transparent geometry to be rendered more efficiently, using 1 pass instead of 2. */
WebGLFeature["MrtTransparency"] = "mrt transparency";
/** This feature allows picking to occur more efficiently, using 1 pass instead of 3. */
WebGLFeature["MrtPick"] = "mrt pick";
/** This feature ensures large meshes (with more than 21,845 triangles) can be rendered. */
WebGLFeature["UintElementIndex"] = "uint element index";
/** This feature allows transparency to achieve the optimal quality. Without this feature, overlapping transparent geometry will "wash out" more easily. */
WebGLFeature["FloatRendering"] = "float rendering";
/** This feature allows for the display of non-3D classification data and solar shadows. */
WebGLFeature["DepthTexture"] = "depth texture";
/** This feature allows instancing of repeated geometry, which can reduce memory consumption. */
WebGLFeature["Instancing"] = "instancing";
/** This feature indicates that the system has enough texture units available for the shaders to run properly. */
WebGLFeature["MinimalTextureUnits"] = "minimal texture units";
/** Indicates that shadow maps are supported. Without this feature, shadows cannot be displayed. */
WebGLFeature["ShadowMaps"] = "shadow maps";
/** This feature allows a logarithmic depth buffer to be used. Without this feature, z-fighting will be much more likely to occur. */
WebGLFeature["FragDepth"] = "fragment depth";
/** This feature allows the renderer to achieve accurate contour lines for isoline and stepped delimiter modes of thematic display. */
WebGLFeature["StandardDerivatives"] = "standard derivatives";
/** This feature allows the renderer to smooth curved lines. */
WebGLFeature["AntiAliasing"] = "anti-aliasing";
})(WebGLFeature || (WebGLFeature = {}));
/** An enumeration that describes a general "compatibility rating" based on the contents of a [[WebGLRenderCompatibilityInfo]].
* @public
*/
export var WebGLRenderCompatibilityStatus;
(function (WebGLRenderCompatibilityStatus) {
/**
* Signifies that everything is ideal: context created successfully, all required and optional features are available,
* and browser did not signal a major performance caveat.
*/
WebGLRenderCompatibilityStatus[WebGLRenderCompatibilityStatus["AllOkay"] = 0] = "AllOkay";
/**
* Signifies that the base requirements of compatibility are met but at least some optional features are missing.
* Consult the contents of [[WebGLRenderCompatibilityInfo.missingOptionalFeatures]].
*/
WebGLRenderCompatibilityStatus[WebGLRenderCompatibilityStatus["MissingOptionalFeatures"] = 1] = "MissingOptionalFeatures";
/**
* Signifies that the base requirements of compatibility are met but WebGL reported a major performance caveat. The browser
* has likely fallen back to software rendering due to lack of a usable GPU.
* Consult [[WebGLRenderCompatibilityInfo.contextErrorMessage]] for a possible description of what went wrong.
* There could also be some missing optional features; consult the contents of [[WebGLRenderCompatibilityInfo.missingOptionalFeatures]].
*/
WebGLRenderCompatibilityStatus[WebGLRenderCompatibilityStatus["MajorPerformanceCaveat"] = 2] = "MajorPerformanceCaveat";
/**
* Signifies that the base requirements of compatibility are not met; rendering cannot occur.
* Consult the contents of [[WebGLRenderCompatibilityInfo.missingRequiredFeatures]].
*/
WebGLRenderCompatibilityStatus[WebGLRenderCompatibilityStatus["MissingRequiredFeatures"] = 3] = "MissingRequiredFeatures";
/**
* Signifies an inability to create either a canvas or a WebGL rendering context; rendering cannot occur. Consult
* [[WebGLRenderCompatibilityInfo.contextErrorMessage]] for a possible description of what went wrong.
*/
WebGLRenderCompatibilityStatus[WebGLRenderCompatibilityStatus["CannotCreateContext"] = 4] = "CannotCreateContext";
})(WebGLRenderCompatibilityStatus || (WebGLRenderCompatibilityStatus = {}));
function createDefaultContext(canvas, useWebGL2 = true, attributes) {
let context = useWebGL2 ? canvas.getContext("webgl2", attributes) : canvas.getContext("webgl", attributes);
if (context === null && useWebGL2)
context = canvas.getContext("webgl", attributes);
return context ?? undefined;
}
/** This function returns information about the client system's level of compatibility with the iTwin.js rendering system, describing the client system's support for both optional and required features. It will also report if there is a major issue with the client system such as the browser falling back to software rendering or an inability to create a either a canvas or a WebGL rendering context.
* @param useWebGL2 A boolean which will be passed to the createContext function in order to create the desired type of context; set this to `true` to use WebGL2, `false` to use WebGL1.
* @param createContext A function of type [[ContextCreator]] that returns a WebGLContext. If not specified, this by default uses `canvas.getContext()` to create the WebGLContext.
* @returns A [[WebGLRenderCompatibilityInfo]] object which contains a compatibility summary.
* @see [[WebGLRenderCompatibilityInfo]]
* @public
*/
export function queryRenderCompatibility(useWebGL2, createContext) {
const canvas = document.createElement("canvas");
if (null === canvas)
return { status: WebGLRenderCompatibilityStatus.CannotCreateContext, missingOptionalFeatures: [], missingRequiredFeatures: [], userAgent: navigator.userAgent, driverBugs: {} };
let errorMessage;
canvas.addEventListener("webglcontextcreationerror", (event) => {
errorMessage = event.statusMessage || "webglcontextcreationerror was triggered with no error provided";
}, false);
if (undefined === createContext)
createContext = createDefaultContext;
let hasMajorPerformanceCaveat = false;
let context = createContext(canvas, useWebGL2, { failIfMajorPerformanceCaveat: true });
if (undefined === context) {
hasMajorPerformanceCaveat = true;
context = createContext(canvas, useWebGL2); // try to create context without black-listed GPU
if (undefined === context)
return {
status: WebGLRenderCompatibilityStatus.CannotCreateContext,
missingOptionalFeatures: [],
missingRequiredFeatures: [],
userAgent: navigator.userAgent,
contextErrorMessage: errorMessage,
driverBugs: {},
};
}
const capabilities = new Capabilities();
const compatibility = capabilities.init(context, undefined);
compatibility.contextErrorMessage = errorMessage;
if (hasMajorPerformanceCaveat && compatibility.status !== WebGLRenderCompatibilityStatus.MissingRequiredFeatures)
compatibility.status = WebGLRenderCompatibilityStatus.MajorPerformanceCaveat;
return compatibility;
}
//# sourceMappingURL=RenderCompatibility.js.map