diff --git a/source/interfaces/webgl-context-attributes.ts b/source/interfaces/webgl-context-attributes.ts index 2dd64836..6c20dbc6 100644 --- a/source/interfaces/webgl-context-attributes.ts +++ b/source/interfaces/webgl-context-attributes.ts @@ -1,10 +1,11 @@ /** * WebGLContextAttributes object that contains the actual context parameters. + * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext#parameters (@WebGL context attributes) * @see https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/getContextAttributes */ export interface IWebGLContextAttributes { /** - * If set to true, the context will have an alpha (transparency) channel. + * If set to true, the context contains an alpha (transparency) buffer. * @public * @readonly * @type {boolean} @@ -13,26 +14,42 @@ export interface IWebGLContextAttributes { readonly alpha?: boolean; /** - * If set to true, the context will attempt to perform antialiased rendering - * if possible. + * If set to true, the context is requested to have a 16 bit depth buffer. * @public * @readonly * @type {boolean} * @default true */ - readonly antialias?: boolean; - + readonly depth?: boolean; + /** - * If set to true, the context will have a 16 bit depth buffer. Defaults to - * true. Use gl.enable(DEPTH_TEST) to enable the depth test and - * gl.depthFunc(), gl.depthMask(), and gl.depthRange() to configure the depth - * test. + * If set to true, the context is requested to have a stencil buffer of at least 8 bits. + * @public + * @readonly + * @type {boolean} + * @default false + */ + readonly stencil?: boolean; + + /** + * If set to true, this hints the user agent (browser) to reduce the latency by + * desynchronizing the context paint cycle from the event loop + * @public + * @readonly + * @type {boolean} + * @default false + */ + readonly desynchronized?: boolean; + + /** + * If set to true, the context will attempt to perform antialiased rendering + * if possible. * @public * @readonly * @type {boolean} * @default true */ - readonly depth?: boolean; + readonly antialias?: boolean; /** * If the value is true, context creation will fail if the implementation @@ -51,7 +68,7 @@ export interface IWebGLContextAttributes { readonly failIfMajorPerformanceCaveat?: boolean; /** - * Provides a hint to the user agent indicating what configuration of GPU is + * Provides a hint to the user agent (browser) indicating what configuration of GPU is * suitable for this WebGL context. This may influence which GPU is used in a * system with multiple GPUs. For example, a dual-GPU system might have one * GPU that consumes less power at the expense of rendering performance. @@ -59,6 +76,11 @@ export interface IWebGLContextAttributes { * choose to ignore it. WebGL implementations use context lost and restored * events to regulate power and memory consumption, regardless of the value of * this attribute. + * + * "default": Let the user agent (browser) decide which GPU configuration is most suitable. + * "high-performance": Prioritizes rendering performance over power consumption. + * "low-power": Prioritizes power saving over rendering performance. + * * @public * @readonly * @type {boolean} @@ -67,8 +89,9 @@ export interface IWebGLContextAttributes { readonly powerPreference?: "default" | "high-performance" | "low-power"; /** - * If set to true, the color channels in the framebuffer will be stored - * premultipled by the alpha channel to improve performance. + * If set to true, page compositor will assume the drawing buffer contains colors + * with pre-multiplied alpha. (The color channels in the framebuffer should be + * stored premultipled by the alpha channel to improve performance.) * @public * @readonly * @type {boolean} @@ -77,11 +100,11 @@ export interface IWebGLContextAttributes { readonly premultipliedAlpha?: boolean; /** - * If set to false, the buffer will be cleared after rendering. If you wish to - * use canvas.toDataURL(), you will either need to draw to the canvas - * immediately before calling toDataURL(), or set preserveDrawingBuffer to - * true to keep the buffer available after the browser has displayed the - * buffer (at the cost of increased memory use). + * If set to true, the buffers will not be cleared and will preserve their values + * until cleared or overwritten by the author. If you wish to use canvas.toDataURL() + * you will either need to draw to the canvas immediately before calling toDataURL() + * or set preserveDrawingBuffer to true to keep the buffer available after the + * browser has displayed the buffer (at the cost of increased memory use). * @public * @readonly * @type {boolean} @@ -90,29 +113,10 @@ export interface IWebGLContextAttributes { readonly preserveDrawingBuffer?: boolean; /** - * - * @public - * @readonly - * @type {boolean} - * @default false - */ - readonly stencil?: boolean; - - /** - * If set to true, the context will have an 8 bit stencil buffer. Defaults to - * false. Use gl.enable(STENCIL_TEST) to enable depth test and - * gl.stencilFunc(), gl.stencilFuncSeparate(), gl.stencilMask(), - * gl.stencilMaskSeparate(), gl.stencilOp(), and gl.stencilOpSeparate() - * to configure the stencil test. - * @public - * @readonly - * @type {boolean} - * @default false - */ - readonly desynchronized?: boolean; - - /** - * xrCompatible is a boolean that indicates whether the context is compatible. + * If set to true, this hints to the user agent (browser) to use a compatible graphics + * adapter for an immersive XR device. Setting this synchronous flag at context creation + * is discouraged; rather call the asynchronous WebGLRenderingContext.makeXRCompatible() + * method the moment you intend to start an XR session. * @public * @readonly * @type {boolean}