WebGLRenderingContext - Web API 接口参考 编辑

WebGLRenderingContext 接口提供基于 OpenGL ES 2.0 的绘图上下文，用于在 HTML <canvas> 元素内绘图。 

要获得这个接口的对象，可以通过在 <canvas> 元素上调用 getContext() 函数，调用时传入 “webgl” 参数：

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

当你获取到 canvas 元素的 WebGL 绘图上下文，你便可以在里面绘图。

点击 WebGL tutorial 获取更多资料，例子，和关于如何开始WebGL编程的知识。

补充：以下内容很多函数都没有提供参数，所以最好还是参见具体API。

常量

请参考 WebGL constants 。

WebGL上下文

以下的属性和方法提供只读的关于上下文的信息：

WebGLRenderingContext.canvas

只读属性，对 HTMLCanvasElement 的向后引用。如果上下文没有相联系的 <canvas> 元素，值将会为 null。

WebGLRenderingContext.commit()

如果上下文没有指定的canvas，把帧交给原始的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 混和表达式和 alpha 混和表达式。

WebGLRenderingContext.blendEquationSeparate()

分开设置 RGB 混和表达式和 alpha 混和表达式。

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()

设置多边形偏移的比例和单位，从而计算深度值。（补充：解决深度冲突）

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 object.

WebGLRenderingContext.getFramebufferAttachmentParameter()

返回帧缓冲区的信息。

WebGLRenderingContext.isFramebuffer()

返回 Boolean 值，表示给入的 WebGLFrameBuffer 对象是否有效。

WebGLRenderingContext.readPixels()

读取 WebGLFrameBuffer 的像素。

渲染缓冲区

WebGLRenderingContext.bindRenderbuffer()

把 WebGLRenderBuffer 对象绑定到指定的对象上。

WebGLRenderingContext.createRenderbuffer()

创建 WebGLRenderBuffer 对象。

WebGLRenderingContext.deleteRenderbuffer()

删除 WebGLRenderBuffer 对象。

WebGLRenderingContext.getRenderbufferParameter()

返回渲染缓冲区的信息。

WebGLRenderingContext.isBuffer()

返回 Boolean 值，表示给入的 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()

返回 Boolean 值，表示给入的 WebGLTexture 是否有效。

WebGLRenderingContext.texImage2D()

指定2D纹理图片。

WebGLRenderingContext.texSubImage2D()

更新当前 WebGLTexture 的子矩形。

WebGLRenderingContext.texParameterf()

设置纹理参数。

WebGLRenderingContext.texParameteri()

设置纹理参数。

程序对象和着色器对象

WebGLRenderingContext.attachShader()

把 WebGLShader 添加到 WebGLProgram。

WebGLRenderingContext.bindAttribLocation()

绑定一个普通顶点索引到一个命名的attribute 变量

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()

返回一个 Boolean 值，表示给入的 WebGLProgram 是否有效。

WebGLRenderingContext.isShader()

返回一个 Boolean 值，表示给入的 WebGLShader 是否有效。

WebGLRenderingContext.linkProgram()

链接给入的 WebGLProgram 对象。

WebGLRenderingContext.shaderSource()

设置一个 WebGLShader 的源码。

WebGLRenderingContext.useProgram()

使用指定的 WebGLProgram 作为当前渲染状态的一部分。

WebGLRenderingContext.validateProgram()

使 WebGLProgram 生效。

Uniform 和 Attribute

WebGLRenderingContext.disableVertexAttribArray()

在给定的位置，禁用顶点attribute数组。

WebGLRenderingContext.enableVertexAttribArray()

在给定的位置，启用顶点attribute数组。

WebGLRenderingContext.getActiveAttrib()

返回激活状态的attribute变量信息。

WebGLRenderingContext.getActiveUniform()

返回激活状态的uniform 变量信息。

WebGLRenderingContext.getAttribLocation()

返回attribute变量的指针位置。

WebGLRenderingContext.getUniform()

返回指定位置的uniform 变量。

WebGLRenderingContext.getUniformLocation()

返回uniform 变量的指针位置。

WebGLRenderingContext.getVertexAttrib()

返回指定位置的顶点attribute变量。

WebGLRenderingContext.getVertexAttribOffset()

获取给定索引的顶点attribute位置。

WebGLRenderingContext.uniform[1234][fi][v]()

指定一个uniform变量。

WebGLRenderingContext.uniformMatrix[234]fv()

指定一个uniform矩阵变量。

WebGLRenderingContext.vertexAttrib[1234]f[v]()

指定一个普通顶点attribute的值。

WebGLRenderingContext.vertexAttribPointer()

指定一个顶点attributes 数组中，顶点attributes 变量的数据格式和位置。

绘制缓冲区

WebGLRenderingContext.clear()

把指定的缓冲区清空为预设的值。

WebGLRenderingContext.drawArrays()

渲染数组中的原始数据。

WebGLRenderingContext.drawElements()

渲染元素数组中的原始数据。

WebGLRenderingContext.finish()

阻断执行，直到之前所有的操作都完成。

WebGLRenderingContext.flush()

清空缓冲的命令，这会导致所有命令尽快执行完。

使用扩展插件

这些方法管理 WebGL 扩展：

WebGLRenderingContext.getSupportedExtensions()

返回一个包含 DOMString 的 Array ，每个元素都为支持的WebGL扩展。

WebGLRenderingContext.getExtension()

返回一个扩展对象。

示例

检测 WebGL 上下文特性支持

这个例子演示了如何通过渲染上下文来检测WebGL，并将结果报告给用户。

<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);

这个例子的源代码可以在GitHub上获取。

Canvas 尺寸对使用 WebGL 渲染的影响

使用 scissor() 和 clear() 我们可以观察到canvas属性大小是如何影响WebGL绘图展示的。

第一个canvas元素通过css样式定义了元素的大小，之后通过javascript获取该元素的 clientWidth 和clientHeight 值，并分别赋值给元素的  width 和height。

相反的，第二个canvas元素并没有这样做，canvas内部对象的width 和 height 属性值仍然是默认值，这样导致在浏览器中实际画布大小是不同的。

使用 scissor() 和clear()在canvas中绘制矩形的效果是清晰可见的，在第一个canvas中，通过指定位置和像素大小，可以得到我们想要的效果，但是在第二个canvas中，这个矩形的位置、大小都是错误展示的。

<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);

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

规范

浏览器兼容性

No compatibility data found. Please contribute data for "api/WebGLRenderingContext" (depth: WebGLRenderingContext) to the MDN compatibility data repository.

相关内容

• HTMLCanvasElement