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