WebGLRenderingContext

这篇翻译不完整。请帮忙从英语翻译这篇文章

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编程的知识。

常量

请参考 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()
Specifies the scale factors and units to calculate depth values.
WebGLRenderingContext.sampleCoverage()
为抗锯齿效果设置多重取样覆盖参数。
WebGLRenderingContext.stencilFunc()
Sets the both front and back function and reference value for stencil testing.
WebGLRenderingContext.stencilFuncSeparate()
Sets the front and/or back function and reference value for stencil testing.
WebGLRenderingContext.stencilMask()
Controls enabling and disabling of both the front and back writing of individual bits in the stencil planes.
WebGLRenderingContext.stencilMaskSeparate()
Controls enabling and disabling of front and/or back writing of individual bits in the stencil planes.
WebGLRenderingContext.stencilOp()
Sets both the front and back-facing stencil test actions.
WebGLRenderingContext.stencilOpSeparate()
Sets the front and/or back-facing stencil test actions.

缓冲区

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()
Binds a generic vertex index to a named attribute variable.
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()
Returns a WebGLShaderPrecisionFormat object describing the precision for the numeric format of the shader.
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()
Disables a vertex attribute array at a given position.
WebGLRenderingContext.enableVertexAttribArray()
Enables a vertex attribute array at a given position.
WebGLRenderingContext.getActiveAttrib()
Returns information about an active attribute variable.
WebGLRenderingContext.getActiveUniform()
Returns information about an active uniform variable.
WebGLRenderingContext.getAttribLocation()
Returns the location of an attribute variable.
WebGLRenderingContext.getUniform()
Returns the value of a uniform variable at a given location.
WebGLRenderingContext.getUniformLocation()
Returns the location of a uniform variable.
WebGLRenderingContext.getVertexAttrib()
Returns information about a vertex attribute at a given position.
WebGLRenderingContext.getVertexAttribOffset()
Returns the address of a given vertex attribute.
WebGLRenderingContext.uniform[1234][fi][v]()
Specifies a value for a uniform variable.
WebGLRenderingContext.uniformMatrix[234]fv()
Specifies a matrix value for a uniform variable.
WebGLRenderingContext.vertexAttrib[1234]f[v]()
Specifies a value for a generic vertex attribute.
WebGLRenderingContext.vertexAttribPointer()
Specifies the data formats and locations of vertex attributes in a vertex attributes array.

绘制缓冲区

WebGLRenderingContext.clear()
把指定的缓冲区清空为预设的值。
WebGLRenderingContext.drawArrays()
渲染数组中的原始数据。
WebGLRenderingContext.drawElements()
渲染元素数组中的原始数据。
WebGLRenderingContext.finish()
阻断执行,直到之前所有的操作都完成。
WebGLRenderingContext.flush()
清空缓冲的命令,这会导致所有命令尽快执行完。

使用扩展插件

这些方法管理 WebGL 扩展:

WebGLRenderingContext.getSupportedExtensions()
返回一个包含 DOMString 的 Array ,每个元素都为支持的WebGL扩展。
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.

Canvas 尺寸对使用 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);

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

规范

Specification Status Comment
WebGL 1.0
WebGLRenderingContext
Recommendation 原始定义

浏览器兼容性

Feature Chrome Edge Firefox Internet Explorer Opera Safari Servo
Basic Support91214.0111125.1No support
Available in workersNo supportNo supportNo support2No supportNo supportNo supportNo support
Feature Android Chrome for Android Edge Mobile Firefox for Android IE Mobile Opera Mobile Safari Mobile
Basic Support(Yes)25No support(Yes)111128.1
Available in workersNo supportNo supportNo supportNo supportNo supportNo supportNo support

1. To access the WebGL context, use experimental-webgl rather than the standard webgl

2. This feature is experimentally implemented since Firefox 44; to activate it, in about:config, set gfx.offscreencanvas.enabled to true

相关内容

文档标签和贡献者

 此页面的贡献者: luojia, LiebeU, JoshuaLee, fscholz
 最后编辑者: luojia,