OffscreenCanvas: getContext() 方法

语法

getContext(contextType, contextAttributes)

参数

contextType

一个包含上下文标识符的字符串，用于定义与画布关联的绘图上下文。可能的值包括：

2d

创建一个表示二维渲染上下文的 OffscreenCanvasRenderingContext2D 对象。

webgl

创建一个表示三维渲染上下文的 WebGLRenderingContext 对象。此上下文仅在实现 WebGL 1（OpenGL ES 2.0）的浏览器中可用。

webgl2

创建一个表示三维渲染上下文的 WebGL2RenderingContext 对象。此上下文仅在实现 WebGL 2（OpenGL ES 3.0）的浏览器中可用。

"webgpu"

创建一个表示 WebGPU 渲染管道的三维渲染上下文的 GPUCanvasContext 对象。此上下文仅在实现 WebGPU API 的浏览器中可用。

bitmaprenderer

创建一个 ImageBitmapRenderingContext，它仅提供用给定的 ImageBitmap 替换画布内容的功能。

注意：在 WebGL 的实现中也使用了标识符 "experimental-webgl" 或 "experimental-webgl2"。这些实现尚未达到测试套件的符合性，或者平台上的图形驱动程序情况尚未稳定。Khronos Group 根据某些 符合性规则认证 WebGL 实现。

contextAttributes 可选

创建渲染上下文时，您可以使用多个上下文属性，例如：

js

const gl = canvas.getContext("webgl", {
  antialias: false,
  depth: false,
});

2d 上下文属性

alpha

一个布尔值，指示画布是否包含 alpha 通道。如果设置为 false，浏览器会知道背景始终是不透明的，这可以加快透明内容和图像的绘制速度。

colorSpace 可选

指定渲染上下文的颜色空间。可能的值包括：

• "srgb" 选择 sRGB 颜色空间。这是默认值。
• "display-p3" 选择 display-p3 颜色空间。

colorType 可选

指定渲染上下文的颜色类型。可能的值包括：

• "unorm8" 将颜色通道设置为 8 位无符号值。这是默认值。
• "float16" 将颜色通道设置为 16 位浮点值。

desynchronized

一个布尔值，提示用户代理通过将画布绘制周期与事件循环分离来减少延迟。

willReadFrequently

一个布尔值，指示是否计划进行大量读取操作。这将强制使用软件（而非硬件加速）的 2D 画布，并在频繁调用 getImageData() 时节省内存。

WebGL 上下文属性

alpha

一个布尔值，指示画布是否包含 alpha 缓冲区。

depth

一个布尔值，指示是否要求绘制缓冲区至少具有 16 位的深度缓冲区。

stencil

一个布尔值，指示是否要求绘制缓冲区至少具有 8 位的模板缓冲区。

desynchronized

一个布尔值，提示用户代理通过将画布绘制周期与事件循环分离来减少延迟。

antialias

一个布尔值，指示是否在可能的情况下执行抗锯齿。

failIfMajorPerformanceCaveat

一个布尔值，指示当系统性能较低或没有硬件 GPU 可用时，是否创建上下文。

powerPreference

一个提示，用于指示哪种 GPU 配置适合 WebGL 上下文。可能的值包括：

"default"

让用户代理决定哪种 GPU 配置最合适。这是默认值。

"high-performance"

在功耗之上优先考虑渲染性能。

"low-power"

在渲染性能之上优先考虑省电。

premultipliedAlpha

一个布尔值，指示页面合成器将假设绘制缓冲区包含预乘 alpha 的颜色。

preserveDrawingBuffer

如果值为 true，则缓冲区不会被清除，并且将保留其值，直到被作者清除或覆盖。

xrCompatible

一个布尔值，提示用户代理使用与 沉浸式 XR 设备兼容的图形适配器。在创建上下文时设置此同步标志是不推荐的；而应在您打算开始 XR 会话时调用异步方法 WebGLRenderingContext.makeXRCompatible()。

注意： WebGPU 规范未为 getContext() 定义任何特定的上下文属性。相反，它通过 GPUCanvasContext.configure() 方法提供配置选项。

返回值

一个渲染上下文，它可以是：

• "2d" 的 OffscreenCanvasRenderingContext2D，
• "webgl" 和 "experimental-webgl" 的 WebGLRenderingContext，
• "webgl2" 和 "experimental-webgl2" 的 WebGL2RenderingContext，
• "webgpu" 的 GPUCanvasContext，
• "bitmaprenderer" 的 ImageBitmapRenderingContext。

如果上下文标识符不受支持，或者画布已被设置为不同的上下文模式，则返回 null。

异常

InvalidStateError DOMException

如果画布已转移到另一个上下文范围（例如，到 worker），则会抛出异常。

示例

const offscreen = new OffscreenCanvas(256, 256);
const gl = offscreen.getContext("webgl");

gl; // WebGLRenderingContext
gl.canvas; // OffscreenCanvas

规范

浏览器兼容性

另见

• 定义此方法的接口：OffscreenCanvas
• HTMLCanvasElement.getContext()
• 可用渲染上下文：CanvasRenderingContext2D、WebGLRenderingContext、WebGL2RenderingContext、ImageBitmapRenderingContext 和 OffscreenCanvasRenderingContext2D