HTMLCanvasElement: getContext() メソッド

HTMLCanvasElement.getContext() メソッドは、描画コンテキストを返します。対応していないコンテキスト識別子であったり、既に別なコンテキストモードが設定されていたりした場合は null になります。

同じキャンバス要素において、同じ contextType 引数を指定して後からこのメソッドを呼び出すと、常に最初の時点で呼び出された時と同じ描画コンテキストインスタンスが返されます。そのキャンバス要素で異なる描画コンテキストオブジェクトを取得することはできません。

構文

js
getContext(contextType)
getContext(contextType, contextAttributes)

引数

contextType

キャンバスに関連する描画コンテキストを定義するコンテキスト識別子が入っている文字列です。利用可能な値は次の通りです。

  • "2d": 2 次元の描画コンテキストを表す CanvasRenderingContext2D オブジェクトが作成されます。
  • "webgl"（または "experimental-webgl"）: 3 次元レンダリングコンテキストを表す WebGLRenderingContext オブジェクトを作成します。このコンテキストは、WebGL version 1 (OpenGL ES 2.0) を実装しているブラウザーでのみ利用可能です。
  • "webgl2": 3 次元レンダリングコンテキストを表す WebGL2RenderingContext (en-US) オブジェクトを作成します。このコンテキストは、WebGL version 2 (OpenGL ES 3.0) を実装しているブラウザーでのみ利用できます。
  • "webgpu": これは、WebGPU レンダーパイプライン用の 3 次元レンダリングコンテキストを表す GPUCanvasContext (en-US) オブジェクトを作成するものです。このコンテキストは、WebGPU API を実装しているブラウザーでのみ利用できます。
  • "bitmaprenderer": 指定されたImageBitmapRenderingContext (en-US)でキャンバスのコンテンツを置き換える機能のみを提供します。

メモ: 識別子 "experimental-webgl" は、WebGL の新しい実装で使用されます。これらの実装は、テストスイート適合性に達していないか、プラットフォームのグラフィックドライバーがまだ安定していないかのいずれかです。Khronos Group が、一定の適合性ルールのもと、WebGL 実装を認証しています。

contextAttributes 省略可

レンダリングコンテキストを作成する際に、いくつかのコンテキスト属性を使用することができます。例えば、以下のようなものです。

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

2 次元のコンテキスト属性:

alpha

キャンバスにアルファチャンネルが含まれているかどうかを示す論理値です。false に設定すると、ブラウザーは背景が常に不透明であることを認識するようになり、透過コンテンツや画像の描画を高速化することができます。

colorSpace 省略可

レンダリングコンテキストの色空間を指定します。使用可能な値は以下の通りです。

desynchronized

論理値で、ユーザーエージェントがキャンバスの描画サイクルをイベントループから非同期化することによって、遅延を縮小することを示唆します。

willReadFrequently

多くのリードバック操作を予定しているかどうかを示す論理値です。これにより、（ハードウェアアクセラレーションではなく）ソフトウェア2Dキャンバスを使用するようになり、getImageData() を頻繁に呼び出す際にメモリーを節約することができます。

WebGL コンテキスト属性:

alpha

論理値で、キャンバスがアルファバッファーを持っているかどうかを示します。

depth

論理値で、描画バッファーに 16 ビット以上のの深度バッファーがあることがリクエストされたことを示します。

stencil

論理値で、描画バッファーに 8 ビット以上のステンシルバッファーを持つようリクエストされたことを示します。

desynchronized

論理値で、ユーザーエージェントがキャンバスの描画サイクルをイベントループから非同期化することでレイテンシーを縮小することを示唆します。

antialias

論理値で、可能であればアンチエイリアスを行うか否かを示します。

failIfMajorPerformanceCaveat

論理値で、システム性能が低い場合やハードウェア GPU が利用できない場合に、コンテキストを作成するかどうかを示します。

powerPreference

どのような GPU 構成が WebGL コンテキストに適しているかを示すユーザーエージェントへのヒントです。使用可能な値は次のとおりです。

"default"

どの GPU 構成が最も適しているかをユーザーエージェントに決定させます。これが既定値です。

"high-performance"

消費電力よりもレンダリング性能を優先します。

"low-power"

描画性能よりも省電力を優先します。

premultipliedAlpha

論理値で、ページコンポジターが描画バッファーにアルファがあらかじめ乗算された色を格納することを想定することを示します。

preserveDrawingBuffer

値が true の場合、バッファーがクリアされることはなく、作者がクリアするか上書きするまでその値が保持されます。

xrCompatible

論理値で、没入型 XR 機器に対応したグラフィックアダプターを使用するよう、ユーザーエージェントに示唆します。コンテキスト生成時にこの同期フラグを設定することは推奨されません。XR セッションを始めるには、非同期の WebGLRenderingContext.makeXRCompatible() (en-US) メソッドを呼び出す必要があります。

メモ: WebGPU 仕様書では、getContext() に固有のコンテキスト属性を定義していません。その代わりに、GPUCanvasContext.configure() (en-US) メソッドで構成オプションを提供しています。

返値

次のいずれかの描画コンテキストです。

contextType が使用可能な描画コンテキストに一致しない場合、または最初にリクエストされた contextType と異なる場合は、null を返します。

例

この <canvas> 要素があったとします。

html
<canvas id="canvas" width="300" height="300"></canvas>

以下のコードで、キャンバスの 2d コンテキストを取得することができます。

js
const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");
console.log(ctx); // CanvasRenderingContext2D { /* … */ }

これでキャンバスの 2D 描画コンテキストを取得し、その中に描画することができるようになりました。

仕様書

Specification
HTML Standard
# dom-canvas-getcontext-dev

ブラウザーの互換性

BCD tables only load in the browser

関連情報