WebGLRenderingContext

WebGLRenderingContext インターフェースは <canvas> 要素の描画サーフェスのためのOpenGL ES 2.0のレンダリングコンテキストを提供します。

このインターフェースを取得するためには、<canvas> 要素の getContext() を "webgl" の引数を与えて呼び出します:

var canvas = document.getElementById('myCanvas');
var gl = canvas.getContext('webgl');

一度キャンバスのWebGLレンダリングコンテキストを取得すれば、その中でレンダリングができます。

WebGL tutorial には、WebGLを始めるためのより多くの情報、サンプル、資料があります。

定数

WebGL constants ページを参照してください。

WebGL コンテキスト

次のプロパティやメソッドはWebGLコンテキストを扱うための一般的な情報や機能を提供します:

WebGLRenderingContext.canvas: 読み取り専用の HTMLCanvasElement への後方参照です。<canvas> 要素と関連付けられていない場合は null を返すことがあります。
WebGLRenderingContext.commit(): コンテキストが直接指定されたキャンバスに固定されていない場合、フレームを元の HTMLCanvasElement にプッシュします。
WebGLRenderingContext.drawingBufferWidth: 読み取り専用の現在の描画バッファの幅です。コンテキストが関連付けされたcanvas要素の幅と一致しているといえます。
WebGLRenderingContext.drawingBufferHeight: 読み取り専用の現在の描画バッファの高さです。コンテキストが関連付けされたcanvas要素の高さと一致しているといえます。
WebGLRenderingContext.getContextAttributes(): 実際のコンテキストパラメータを含む WebGLContextAttributes オブジェクトを返します。コンテキストが失われていた場合は null を返すことがあります。
WebGLRenderingContext.isContextLost(): コンテキストが失われている場合は true を返し、そうでない場合は false を返します。

ビューイングとクリッピング

WebGLRenderingContext.scissor(): シザーボックスを定義します。
WebGLRenderingContext.viewport(): ビューポートをセットします。

ステート情報

WebGLRenderingContext.activeTexture(): アクティブなテクスチャユニットを選択します。
WebGLRenderingContext.blendColor(): ブレンド元とブレンド先のブレンドファクターをセットします。
WebGLRenderingContext.blendEquation(): RGBのブレンド式とアルファのブレンド式をひとつの式にセットします。
WebGLRenderingContext.blendEquationSeparate(): RGBのブレンド式とアルファのブレンド式を分けて式にセットします。
WebGLRenderingContext.blendFunc(): どの関数がピクセルのブレンド演算に使用されるかを定義します。
WebGLRenderingContext.blendFuncSeparate(): どの関数がピクセルのブレンド演算に使用されるかをRGBとアルファ要素を個別に定義します。
WebGLRenderingContext.clearColor(): カラーバッファをクリアする時に使われる色を指定します。
WebGLRenderingContext.clearDepth(): 深度バッファをクリアする時に使用する深度値を指定します。
WebGLRenderingContext.clearStencil(): ステンシルバッファをクリアする時に使用するステンシル値を指定します。
WebGLRenderingContext.colorMask(): ドローイングまたは WebGLFramebuffer へのレンダリングの際に、どの色要素を有効または無効にするかをセットします。
WebGLRenderingContext.cullFace(): 前面ポリゴンと後面ポリゴンのいずれか、または両方をカリングするかどうかを指定します。
WebGLRenderingContext.depthFunc(): 現在の深度バッファの深度値と書き込むピクセルの深度値を比較する関数を指定します。
WebGLRenderingContext.depthMask(): 深度バッファへの書き込みを有効にするか無効にするかどうかをセットします。
WebGLRenderingContext.depthRange(): 正規化デバイス座標系からウィンドウまたはビューポート座標系への深度レンジマッピングを指定します。
WebGLRenderingContext.disable(): このコンテキストにおいて、指定したWebGL機能を無効にします。
WebGLRenderingContext.enable(): このコンテキストにおいて、指定したWebGL機能を有効にします。
WebGLRenderingContext.frontFace(): 前面ポリゴンなのか後面ポリゴンなのかを周る方向によって指定します。
WebGLRenderingContext.getParameter(): 渡されたパラメータ名の値を返します。
WebGLRenderingContext.getError(): エラー情報を返します。
WebGLRenderingContext.hint(): 一定の振る舞いについてのヒントを指定します。このヒントの振る舞いは実装に依存します。
WebGLRenderingContext.isEnabled(): このコンテキストで指定されたWebGL機能が有効であるか無効であるかをテストします。
WebGLRenderingContext.lineWidth(): ラスタライズする線の幅をセットします。
WebGLRenderingContext.pixelStorei(): ピクセルストレージモードを指定します。
WebGLRenderingContext.polygonOffset(): Specifies the scale factors and units to calculate depth values.
WebGLRenderingContext.sampleCoverage(): アンチエイリアシングエフェクトのためのマルチサンプルカバレッジパラメータを指定します。
WebGLRenderingContext.stencilFunc(): ステンシルテストための関数と参照値を、前面と後面の両面をセットします。
WebGLRenderingContext.stencilFuncSeparate(): ステンシルテストための関数と参照値を、前面と後面の両面、またはいずれかをセットします。
WebGLRenderingContext.stencilMask(): ステンシル平面の個々のビットの書き込みの有効と無効を、前面と後面の両面を操作します。
WebGLRenderingContext.stencilMaskSeparate(): ステンシル平面の個々のビットの書き込みの有効と無効を、前面と後面のいずれか、または両面を操作します。
WebGLRenderingContext.stencilOp(): 前面と後面のステンシルテストの振る舞いを同時にセットします。
WebGLRenderingContext.stencilOpSeparate(): 前面と後面のステンシルテストの振る舞いをセットします。

バッファ

WebGLRenderingContext.bindBuffer(): WebGLBuffer オブジェクトを与えられたターゲットにバインドします。
WebGLRenderingContext.bufferData(): バッファデータを更新します。
WebGLRenderingContext.bufferSubData(): バッファデータを与えられたオフセットから更新します。
WebGLRenderingContext.createBuffer(): WebGLBuffer オブジェクトを作成します。
WebGLRenderingContext.deleteBuffer(): WebGLBuffer オブジェクトを削除します。
WebGLRenderingContext.getBufferParameter(): バッファについての情報を返します。
WebGLRenderingContext.isBuffer(): 与えられたバッファが有効であるかのブール値を返します。

フレームバッファ

WebGLRenderingContext.bindFramebuffer(): WebGLFrameBuffer オブジェクトを与えられたターゲットにバインドします。
WebGLRenderingContext.checkFramebufferStatus(): フレームバッファのステータスを返します。
WebGLRenderingContext.createFramebuffer(): WebGLFrameBuffer オブジェクトを作成します。
WebGLRenderingContext.deleteFramebuffer(): WebGLFrameBuffer オブジェクトを削除します。
WebGLRenderingContext.framebufferRenderbuffer(): WebGLRenderingBuffer オブジェクトを WebGLFrameBuffer オブジェクトにアタッチします。
WebGLRenderingContext.framebufferTexture2D(): テクスチャ画像を WebGLFrameBuffer オブジェクトにアタッチします。
WebGLRenderingContext.getFramebufferAttachmentParameter(): フレームバッファについての情報を返します。
WebGLRenderingContext.isFramebuffer(): 渡された WebGLFrameBuffer オブジェクトが有効かどうかを表すブール値を返します。
WebGLRenderingContext.readPixels(): WebGLFrameBuffer からピクセルブロックを読み取ります。

レンダーバッファ

WebGLRenderingContext.bindRenderbuffer(): 与えられたターゲットに WebGLRenderBuffer オブジェクトをバインドします。
WebGLRenderingContext.createRenderbuffer(): WebGLRenderBuffer オブジェクトを作成します。
WebGLRenderingContext.deleteRenderbuffer(): WebGLRenderBuffer オブジェクトを削除します。
WebGLRenderingContext.getRenderbufferParameter(): レンダーバッファについての情報を返します。
WebGLRenderingContext.isRenderbuffer(): 渡された WebGLRenderingBuffer が有効かどうかを表すブール値を返します。
WebGLRenderingContext.renderbufferStorage(): レンダーバッファデータストアを作成します。

テクスチャ

WebGLRenderingContext.bindTexture(): 与えられたターゲットに WebGLTexture オブジェクトをバインドします。
WebGLRenderingContext.compressedTexImage2D(): 2Dテクスチャ画像を圧縮フォーマットで指定します。
WebGLRenderingContext.compressedTexSubImage2D(): 2Dテクスチャ部分画像を圧縮フォーマットで指定します。
WebGLRenderingContext.copyTexImage2D(): 2Dテクスチャ画像をコピーします。
WebGLRenderingContext.copyTexSubImage2D(): 2Dテクスチャ部分画像をコピーします。
WebGLRenderingContext.createTexture(): WebGLTexture オブジェクトを作成します。
WebGLRenderingContext.deleteTexture(): WebGLTexture オブジェクトを削除します。
WebGLRenderingContext.generateMipmap(): WebGLTexture オブジェクトに対してミップマップ集合を生成します。
WebGLRenderingContext.getTexParameter(): テクスチャに対しての情報を返します。
WebGLRenderingContext.isTexture(): 渡された WebGLTexture が有効かどうかを表すブール値を返します。
WebGLRenderingContext.texImage2D(): 2Dテクスチャ画像を指定します。
WebGLRenderingContext.texSubImage2D(): 現在の WebGLTexture の部分矩形を更新します。
WebGLRenderingContext.texParameterf(): テクスチャパラメータをセットします。
WebGLRenderingContext.texParameteri(): テクスチャパラメータをセットします。

プログラムとシェーダ

WebGLRenderingContext.attachShader(): WebGLShader を WebGLProgram にアタッチします。
WebGLRenderingContext.bindAttribLocation(): 汎用頂点インデックスを名前付き属性変数にバインドします。
WebGLRenderingContext.compileShader(): WebGLShader をコンパイルします。
WebGLRenderingContext.createProgram(): WebGLProgram を作成します。
WebGLRenderingContext.createShader(): WebGLShader を作成します。
WebGLRenderingContext.deleteProgram(): WebGLProgram を削除します。
WebGLRenderingContext.deleteShader(): WebGLShader を削除します。
WebGLRenderingContext.detachShader(): WebGLShader をでタッチします。
WebGLRenderingContext.getAttachedShaders(): WebGLProgram にアタッチされた WebGLShader オブジェクトのリストを返します。
WebGLRenderingContext.getProgramParameter(): プログラムについての情報を返します。
WebGLRenderingContext.getProgramInfoLog(): WebGLProgram オブジェクトについての情報ログを返します。
WebGLRenderingContext.getShaderParameter(): シェーダについての情報を返します。
WebGLRenderingContext.getShaderPrecisionFormat(): シェーダの数値フォーマットの精度について記述した WebGLShaderPrecisionFormat オブジェクトを返します。
WebGLRenderingContext.getShaderInfoLog(): WebGLShader についての情報ログを返します。
WebGLRenderingContext.getShaderSource(): WebGLShader のソースコードを文字列として返します。
WebGLRenderingContext.isProgram(): 渡された WebGLProgram 有効かを表すブール値を返します。
WebGLRenderingContext.isShader(): 渡された WebGLShader 有効かを表すブール値を返します。
WebGLRenderingContext.linkProgram(): 渡された WebGLProgram オブジェクトをリンクします。
WebGLRenderingContext.shaderSource(): WebGLShader にソースコードをセットします。
WebGLRenderingContext.useProgram(): 指定した WebGLProgram を現在のレンダリングステートの一部として使用します。
WebGLRenderingContext.validateProgram(): WebGLProgram を検証します。

ユニフォームと属性

WebGLRenderingContext.disableVertexAttribArray(): 与えられたポジションの頂点属性配列を無効にします。
WebGLRenderingContext.enableVertexAttribArray(): 与えられたポジションの頂点属性配列を有効にします。
WebGLRenderingContext.getActiveAttrib(): 有効な属性変数についての情報を返します。
WebGLRenderingContext.getActiveUniform(): 有効なユニフォーム変数についての情報を返します。
WebGLRenderingContext.getAttribLocation(): 属性変数のロケーションを返します。
WebGLRenderingContext.getUniform(): 与えられたロケーションのユニフォーム変数の値を返します。
WebGLRenderingContext.getUniformLocation(): ユニフォーム変数のロケーションを返します。
WebGLRenderingContext.getVertexAttrib(): 与えられたポジションの頂点属性についての情報を返します。
WebGLRenderingContext.getVertexAttribOffset(): 与えられた頂点配列のアドレスを返します。
WebGLRenderingContext.uniform[1234][fi][v](): ユニフォーム変数の値を指定します。
WebGLRenderingContext.uniformMatrix[234]fv(): ユニフォーム変数の行列を指定します。
WebGLRenderingContext.vertexAttrib[1234]f[v](): 汎用頂点属性の値を指定します。
WebGLRenderingContext.vertexAttribPointer(): データフォーマットと頂点属性配列中の頂点属性のロケーションを指定します。

バッファへの書き込み

WebGLRenderingContext.clear(): 指定されたバッファを既定値でクリアします。
WebGLRenderingContext.drawArrays(): プリミティブを配列データからレンダリングします。
WebGLRenderingContext.drawElements(): プリミティブを要素配列データからレンダリングします。
WebGLRenderingContext.finish(): 以前に呼び出されたコマンドが終了するまで処理をブロックします。
WebGLRenderingContext.flush(): 可能な限り速くすべてのコマンドを実行し、バッファコマンドを空にします。

拡張を使用する

これらのメソッドはWebGL拡張を管理します:

WebGLRenderingContext.getSupportedExtensions(): サポートしている全てのWebGL拡張を DOMString の Array で返します。
WebGLRenderingContext.getExtension(): 拡張オブジェクトを返します。

例

WebGL コンテキストフィーチャーの検出

This example demonstrates how to detect a WebGL rendering context and reports the result to the user.

<p>[ Here would go the result of WebGL feature detection ]</p>
<button>Press here to detect WebGLRenderingContext</button>

body {
  text-align : center;
}
button {
  display : block;
  font-size : inherit;
  margin : auto;
  padding : 0.6em;
}

// Run everything inside window load event handler, to make sure
// DOM is fully loaded and styled before trying to manipulate it.
window.addEventListener("load", function() {
  var paragraph = document.querySelector("p"),
    button = document.querySelector("button");
  // Adding click event handler to button.
  button.addEventListener("click", detectWebGLContext, false);
  function detectWebGLContext () {
    // Create canvas element. The canvas is not added to the
    // document itself, so it is never displayed in the
    // browser window.
    var canvas = document.createElement("canvas");
    // Get WebGLRenderingContext from canvas element.
    var gl = canvas.getContext("webgl")
      || canvas.getContext("experimental-webgl");
    // Report the result.
    if (gl && gl instanceof WebGLRenderingContext) {
      paragraph.innerHTML =
        "Congratulations! Your browser supports WebGL.";
    } else {
      paragraph.innerHTML = "Failed to get WebGL context. "
        + "Your browser or device may not support WebGL.";
    }
  }
}, false);

The source code of this example is also available on GitHub.

WebGLレンダリングにおけるキャンバスサイズの効果

With scissor() and clear() we can demonstrate how the WebGL drawing buffer is affected by the size of the canvas.

The size of the first canvas is set to the styled Element size, determined by CSS. This is done by assigning the width and height properties of the canvas to the values of the clientWidth and clientHeight properties, respectively.

In contrast, no such assignment is done for the second canvas. The internal width and height properties of the canvas remain at default values, which are different than the actual size of the canvas Element in the browser window.

The effect is clearly visible when using scissor() and clear() to draw a square in the center of the canvas, by specifying its position and size in pixels. In the first canvas, we get the desired result. In the second, the square has the wrong shape, size, and position.

<p>Compare the two canvases.</p>
<canvas>Your browser does not seem to support 
    HTML5 canvas.</canvas>
<canvas>Your browser does not seem to support 
    HTML5 canvas.</canvas>

body {
  text-align : center;
}
canvas {
  display : inline-block;
  width : 120px;
  height : 80px;
  margin : auto;
  padding : 0;
  border : none;
  background-color : black;
}

window.addEventListener("load", function() {
  "use strict"
  var firstCanvas = document.getElementsByTagName("canvas")[0],
    secondCanvas = document.getElementsByTagName("canvas")[1];
  firstCanvas.width = firstCanvas.clientWidth;
  firstCanvas.height = firstCanvas.clientHeight;
  [firstCanvas, secondCanvas].forEach(function(canvas) {
    var gl = canvas.getContext("webgl")
      || canvas.getContext("experimental-webgl");
    if (!gl) {
      document.querySelector("p").innerHTML =
        "Failed to get WebGL context. "
        + "Your browser or device may not support WebGL.";
      return;
    }
    gl.viewport(0, 0,
      gl.drawingBufferWidth, gl.drawingBufferHeight);
    gl.enable(gl.SCISSOR_TEST);
    gl.scissor(30, 10, 60, 60);
    gl.clearColor(1.0, 1.0, 0.0, 1.0);
    gl.clear(gl.COLOR_BUFFER_BIT);
  });
}, false);