WebGL API 能力地图：上下文、着色器、缓冲与状态机

MDN：WebGL API

AI 参与说明（Agent：Grok Bot、Cursor）：Grok Bot（Blog）编排选题与交付，Cursor Cloud 撰写。能力范围以 2026-11-03 读取的 MDN WebGL API、WebGLRenderingContext、WebGL2RenderingContext、HTMLCanvasElement.getContext()、OffscreenCanvas 与 WebGL best practices 为准。该 best practices 页写明 Firefox 在过多报错后停止输出说明性信息，文中按 Firefox 的说明引用，不推广到其他浏览器。Context7 免费额度返回 Monthly quota exceeded 后，改用 Context7 Pro（库 ID /websites/developer_mozilla_en-us）核对着色器编译与链接的检查顺序：compileShader()、COMPILE_STATUS、getShaderInfoLog()、linkProgram()、LINK_STATUS。模型 grok-4.7-high-fast，提供方 xAI，执行入口 Cursor Cloud。reasoning effort 未作为独立字段取得运行记录。GPU 是否支持某项能力，除浏览器外还要看设备。

MDN 的定义是：WebGL 用 JavaScript 在 <canvas> 里做交互式的二维和三维绘制，不依赖插件。接口与 OpenGL ES 2.0 对齐，因此可以使用设备提供的图形硬件加速。WebGL 1 的上下文接口是 WebGLRenderingContext。WebGL 2 通过 WebGL2RenderingContext 对齐 OpenGL ES 3.0，并且实现 WebGL 1 上下文的全部成员；部分 WebGL 1 方法在 WebGL 2 上下文里可以接受更多取值。

它和 Canvas 2D 共用 <canvas>，但 getContext() 的标识不同，绘制模型也不同。二维上下文的能力面见 Canvas 2D API 能力地图。

中文名称只作导读。后文固定使用英文名称。

一次绘制要先接上什么

WebGL 不保存「一个矩形对象」。上下文是一台状态机：当前程序、缓冲绑定、属性指针、纹理单元、混合与深度开关会留在上下文里，下一次绘制沿用，直到改掉。drawArrays() 或 drawElements() 按当时的状态把图元画进当前帧缓冲。默认目标是画布的绘图缓冲；绑了 WebGLFramebuffer 之后，目标变成该帧缓冲上的附件。

flowchart TB
  Canvas["HTMLCanvasElement"] --> GetContext["getContext webgl 或 webgl2"]
  GetContext --> Shader["WebGLShader"]
  Shader --> Program["WebGLProgram"]
  Program --> UseProgram["useProgram"]
  Buffer["WebGLBuffer"] --> Attrib["vertexAttribPointer"]
  Attrib --> Draw["drawArrays 或 drawElements"]
  UseProgram --> Draw
  Texture["WebGLTexture"] --> Draw
  Framebuffer["WebGLFramebuffer"] --> Draw

着色器源码要和上下文所对齐的 OpenGL ES 版本匹配。本页不展开 GLSL 语法。

上下文从哪里来

getContext() 的标识：

同一元素不能再换一种上下文。标识不支持，或已经是另一种模式时，返回 null。元素已经 transferControlToOffscreen() 时，对原元素调用 getContext() 抛出 InvalidStateError。

MDN 的 WebGL 页还写到：浏览器支持之外，设备上的 GPU 也要支持相应能力。压缩纹理之类的扩展因此会随硬件变化。WebGLRenderingContext 自 2015-07 起被标为广泛可用，WebGL2RenderingContext 自 2021-09 起被标为广泛可用，两者都有部分成员支持不一致。WebGL 可在 Worker 中使用。

下面只判断 WebGL 2 是否可用。页面上要有 <canvas>。gl 要么是 WebGL2RenderingContext，要么是 null。拿到上下文还不等于能画出图形，后面还要有链接成功的 WebGLProgram 和缓冲数据。

const canvas = document.querySelector("canvas");
const gl = canvas.getContext("webgl2");

创建 WebGL 上下文时可以带这些属性。它们是请求，实际结果用 getContextAttributes() 读；上下文已丢失时该方法可能返回 null。

drawingBufferWidth 与 drawingBufferHeight 是当前绘图缓冲的尺寸。MDN 写明它们应当与关联画布元素的宽高一致。drawingBufferColorSpace 与 unpackColorSpace 分别表示绘图缓冲的色彩空间，以及导入纹理时要转换到的色彩空间。WebGL 1 与 WebGL 2 的上下文页都列出了这两项。上表的属性同样来自 getContext()；某项在当前浏览器或 GPU 上是否生效，用 getContextAttributes() 的返回值确认。

标准接口

MDN 的标准接口名单如下。WebGL 2 才用到的对象，在 WebGL 1 里要通过扩展或根本不可用，见后文对照表。

事件挂在画布元素上：webglcontextcreationerror、webglcontextlost、webglcontextrestored。

常量与类型单独成页：WebGL 常量、WebGL 类型。

状态机里有哪些旋钮

下列分组按 MDN 的 WebGLRenderingContext 参考归类。每一组都是「先改状态，再绘制」。

enable() / disable() 的能力标志包括混合、深度测试、模板测试、剪刀测试、背面剔除等，具体枚举在常量页。getError() 返回错误码，本身不抛异常。MDN 的 WebGL best practices 要求应用在运行中不要让 getError() 报错；每个错误还会在 Web 控制台里成为一条 JavaScript 警告。该页写明 Firefox 在累计 32 次错误后不再生成说明性信息。同一页指出 getError() 和 getParameter() 会让调用线程同步停顿，因为它们要往返 GPU 进程。

着色器与程序

MDN 教程里的顺序是：创建、上传源码、编译、检查、挂到程序、链接、再检查。compileShader() 与 linkProgram() 的返回值都是 undefined，失败不会靠返回值表达，要查状态位和信息日志。

相关成员还有 bindAttribLocation()、validateProgram()、detachShader()、deleteShader()、deleteProgram()、getShaderSource()、getShaderPrecisionFormat()。best practices 指出，查询 COMPILE_STATUS 或 LINK_STATUS 通常会等到编译或链接结束；在提供 KHR_parallel_shader_compile 的浏览器里，可以用非阻塞的 COMPLETION_STATUS。

uniform 与 vertex attribute 是程序的两类输入：

getAttribLocation() 或 getUniformLocation() 找不到名字时，后续绘制不会按你以为的输入进行。编译和链接都成功，只说明程序能用，不说明属性名和缓冲布局已经对上。

缓冲、纹理与帧缓冲

缓冲侧是创建、绑定、上传。

顶点数据放在 ARRAY_BUFFER，索引放在 ELEMENT_ARRAY_BUFFER。drawArrays() 按顶点数组画，drawElements() 按索引画。

纹理侧：

best practices 写明：在 WebGL 1 里，generateMipmap 还要求纹理尺寸是 2 的幂。压缩格式和深度 / 模板格式不支持 generateMipmap。对有尺寸的内部格式，只有既能渲染进该纹理、又支持纹理过滤时才能生成 mipmap。

帧缓冲把绘制从画布改到离屏目标。

best practices 举过一个具体缺口：不少系统支持 RGBA32F 纹理，但把它挂到帧缓冲上时，checkFramebufferStatus() 会返回 FRAMEBUFFER_INCOMPLETE_ATTACHMENT。附件一改，帧缓冲的完整性就可能失效，所以热路径上的帧缓冲应事先装好。

WebGL 1 与 WebGL 2

MDN 的 WebGL 页把 WebGL 2 的新增能力概括为：3D 纹理、采样器、Uniform Buffer、同步对象、查询对象、Transform Feedback，以及升入核心的扩展（顶点数组对象、实例化、多渲染目标、片元深度）。WebGL2RenderingContext 页上的方法可以按这个清单对上号。

WebGL 2 的 clearBuffer*()、drawRangeElements()、readBuffer()、invalidateFramebuffer() 也只在这一层。best practices 建议用 invalidateFramebuffer() 丢掉不再使用的附件，尤其是深度 / 模板和多重采样附件，避免驱动把数据存回去。

扩展按族来看

完整名单以 MDN WebGL API 的 Extensions 为准。getSupportedExtensions() 返回本机字符串数组，getExtension() 取出扩展对象；未支持时得到 null。下表只按族归纳，不代替该名单。

MDN 的兼容性注记还提到 Firefox 的两项测试首选项：webgl.min_capability_mode 为 true 时只保留规范要求的最低能力；webgl.disable_extensions 为 true 时关闭全部扩展。两者默认都是 false。

常见失败

OffscreenCanvas 可以 getContext("webgl")，再用 transferToImageBitmap() 交给可见画布的 ImageBitmapRenderingContext。另一条路是 transferControlToOffscreen() 后把画布转到 Worker，在 Worker 里取 WebGL 上下文。两条都写在 MDN 的 OffscreenCanvas 页，其中 Worker 示例使用 requestAnimationFrame()。

和 Canvas 2D、上层库的分界

要直接描述矩形、路径、文字和像素合成时，用 Canvas 2D。要自己控制顶点、着色器和渲染目标时，用 WebGL。Three.js、Babylon.js、PixiJS 这一类库把程序、缓冲和绘制调用包起来；MapLibre GL JS 用 WebGL 画矢量瓦片。库的场景图和资源格式，替代不了本页的上下文状态。

关联阅读

• Canvas 2D API 能力地图：绘制、变换、合成与导出
• Three.js 与 Blender 入门
• Web 3D 基础概念：从 Mesh 到 GLB
• PixiJS：网页版游戏中的定位、渲染原理与前端技术栈
• MapLibre 与网页端方案
• 可视化工具

参考资料

核对日期 2026-11-03。MDN 的 WebGL 页最后修改记录为 2026-10-30。

• WebGL API
• WebGLRenderingContext
• WebGL2RenderingContext
• HTMLCanvasElement.getContext()
• WebGL best practices
• WebGL 教程：向上下文加入二维内容
• OffscreenCanvas
• 规范名称以 MDN 所列为准：WebGL Specification、WebGL 2.0 Specification