Web 图形与 3D / 系统课时
加载 glTF 模型的顶点与索引
加载 glTF 模型的顶点与索引
本篇把一个三角形 glTF 2.0 网格读入 WebGL 2:从 JSON 引用定位二进制数据,识别位置、法线、UV 与索引,创建 GPU 缓冲区并实际绘制。示例只处理最小静态网格,不引入材质、动画或压缩扩展。
学习目标
- 分清
Buffer、BufferView、Accessor与Mesh的职责和引用关系。 - 根据字节偏移、分量类型和步长配置 WebGL 2 顶点属性及索引。
- 运行一个完整示例,确认三角形正确显示并识别加载器的适用边界。
沿四层引用找到几何数据
buffers 指向 .bin 或 data: URI 中的原始字节;bufferViews 用 buffer、byteOffset、byteLength 划出连续区段;accessors 再用 componentType、type、count 和自身的 byteOffset 解释区段内的数据。meshes[].primitives[] 通过 attributes.POSITION、NORMAL、TEXCOORD_0 和 indices 引用相应的 accessor 索引。

这里有两种容易混淆的偏移:bufferView.byteOffset 相对于整个原始 Buffer;accessor.byteOffset 相对于所属 BufferView。若先把 BufferView 切片上传为单独的 VBO,调用 vertexAttribPointer 时只能再传 accessor 的偏移,不能把两者重复相加。
用 102 字节验证类型和布局
下面示例只有三个顶点,属性按区段紧密存储,共四个 BufferView;不使用交错布局。5126 是 FLOAT(每分量 4 字节),5123 是 UNSIGNED_SHORT(每索引 2 字节)。Accessor.count 是元素个数,不是字节数。
| 数据 | BufferView 起点 | Accessor 类型 | 元素数 | 占用字节 |
|---|---|---|---|---|
| POSITION | 0 | VEC3 / 5126 |
3 | 36 |
| NORMAL | 36 | VEC3 / 5126 |
3 | 36 |
| TEXCOORD_0 | 72 | VEC2 / 5126 |
3 | 24 |
| indices | 96 | SCALAR / 5123 |
3 | 6 |
顶点索引内容为 [0, 1, 2],primitive.mode=4 对应 TRIANGLES。WebGL 中 34962 表示 ARRAY_BUFFER,34963 表示 ELEMENT_ARRAY_BUFFER。当 BufferView 定义 byteStride 时,顶点读取步长取该值;未定义则传 0,由 WebGL 根据格式连续读取。
运行完整的 WebGL 2 加载示例
将下列内容保存为 index.html,用支持 WebGL 2 的浏览器打开。为免准备额外文件,示例把 102 字节 .bin 数据放入 glTF 的 data: URI,再通过 Blob URL 模拟读取 .gltf JSON;实际部署时可以把 loadGltf 的参数换成服务器上的 .gltf 地址。
<!doctype html>
<html lang="zh-CN">
<meta charset="utf-8">
<canvas id="canvas" width="640" height="360"></canvas>
<script type="module">
const gl = document.querySelector('#canvas').getContext('webgl2');
if (!gl) throw new Error('浏览器不支持 WebGL 2');
// 最小 glTF:一个 Buffer 包含位置、法线、UV 和索引。
const gltf = {
asset: { version: '2.0' },
buffers: [{ byteLength: 102, uri: 'data:application/octet-stream;base64,zcxMvzMzM78AAAAAzcxMPzMzM78AAAAAAAAAAM3MTD8AAAAAAAAAAAAAAAAAAIA/AAAAAAAAAAAAAIA/AAAAAAAAAAAAAIA/AAAAAAAAAAAAAIA/AAAAAAAAAD8AAIA/AAABAAIA' }],
bufferViews: [
{ buffer: 0, byteOffset: 0, byteLength: 36, target: 34962 },
{ buffer: 0, byteOffset: 36, byteLength: 36, target: 34962 },
{ buffer: 0, byteOffset: 72, byteLength: 24, target: 34962 },
{ buffer: 0, byteOffset: 96, byteLength: 6, target: 34963 }
],
accessors: [
{ bufferView: 0, componentType: 5126, type: 'VEC3', count: 3, min: [-0.8, -0.7, 0], max: [0.8, 0.8, 0] },
{ bufferView: 1, componentType: 5126, type: 'VEC3', count: 3 },
{ bufferView: 2, componentType: 5126, type: 'VEC2', count: 3 },
{ bufferView: 3, componentType: 5123, type: 'SCALAR', count: 3 }
],
meshes: [{ primitives: [{ attributes: { POSITION: 0, NORMAL: 1, TEXCOORD_0: 2 }, indices: 3, mode: 4 }] }],
nodes: [{ mesh: 0 }], scenes: [{ nodes: [0] }], scene: 0
};
async function loadGltf(url) {
const doc = await (await fetch(url)).json();
if (doc.asset?.version !== '2.0' || doc.extensionsRequired?.length) {
throw new Error('只支持未使用必需扩展的 glTF 2.0');
}
// data: URI 和相对 .bin 文件都可以通过 URL 解析加载。
const buffers = await Promise.all(doc.buffers.map(async (b) => {
if (!b.uri) throw new Error('本例不支持 GLB 内嵌 BIN 块');
const res = await fetch(new URL(b.uri, url));
if (!res.ok) throw new Error(`Buffer 加载失败:${res.status}`);
const data = await res.arrayBuffer();
if (data.byteLength < b.byteLength) throw new Error('Buffer 长度不足');
return data;
}));
const primitive = doc.meshes[0].primitives[0];
if ((primitive.mode ?? 4) !== gl.TRIANGLES || primitive.indices === undefined) {
throw new Error('本例仅支持带索引的 TRIANGLES');
}
const vao = gl.createVertexArray();
gl.bindVertexArray(vao);
const gpuBuffers = new Map();
function bindAccessor(accessorIndex, target) {
const a = doc.accessors[accessorIndex];
if (a.bufferView === undefined || a.sparse) throw new Error('不支持稀疏或无 bufferView 的 accessor');
const view = doc.bufferViews[a.bufferView];
if (!gpuBuffers.has(a.bufferView)) {
const raw = buffers[view.buffer];
const start = view.byteOffset ?? 0;
if (start + view.byteLength > raw.byteLength) throw new Error('BufferView 越界');
const gpuBuffer = gl.createBuffer();
gl.bindBuffer(target, gpuBuffer);
gl.bufferData(target, new Uint8Array(raw, start, view.byteLength), gl.STATIC_DRAW);
gpuBuffers.set(a.bufferView, gpuBuffer);
} else {
gl.bindBuffer(target, gpuBuffers.get(a.bufferView));
}
return { a, view };
}
for (const [name, location, size] of [['POSITION', 0, 3], ['NORMAL', 1, 3], ['TEXCOORD_0', 2, 2]]) {
const index = primitive.attributes[name];
if (index === undefined) throw new Error(`缺少 ${name}`);
const { a, view } = bindAccessor(index, gl.ARRAY_BUFFER);
if (a.componentType !== gl.FLOAT || a.type !== `VEC${size}`) throw new Error(`${name} 格式不支持`);
gl.enableVertexAttribArray(location);
// 此偏移相对于已上传的 bufferView,而不是整个原始 Buffer。
gl.vertexAttribPointer(location, size, a.componentType, false, view.byteStride ?? 0, a.byteOffset ?? 0);
}
const { a: indices } = bindAccessor(primitive.indices, gl.ELEMENT_ARRAY_BUFFER);
if (indices.type !== 'SCALAR' || ![gl.UNSIGNED_BYTE, gl.UNSIGNED_SHORT, gl.UNSIGNED_INT].includes(indices.componentType)) {
throw new Error('索引类型不支持');
}
gl.bindVertexArray(null);
return { vao, count: indices.count, type: indices.componentType, offset: indices.byteOffset ?? 0 };
}
function shader(type, source) {
const s = gl.createShader(type);
gl.shaderSource(s, source);
gl.compileShader(s);
if (!gl.getShaderParameter(s, gl.COMPILE_STATUS)) throw new Error(gl.getShaderInfoLog(s));
return s;
}
const program = gl.createProgram();
gl.attachShader(program, shader(gl.VERTEX_SHADER, `#version 300 es
layout(location=0) in vec3 a_position;
layout(location=1) in vec3 a_normal;
layout(location=2) in vec2 a_uv;
out vec3 v_normal;
out vec2 v_uv;
void main() {
v_normal = a_normal;
v_uv = a_uv;
gl_Position = vec4(a_position, 1.0);
}`));
gl.attachShader(program, shader(gl.FRAGMENT_SHADER, `#version 300 es
precision highp float;
in vec3 v_normal;
in vec2 v_uv;
out vec4 fragColor;
void main() {
float light = 0.4 + 0.6 * max(dot(normalize(v_normal), vec3(0, 0, 1)), 0.0);
fragColor = vec4(vec3(v_uv, 0.7) * light, 1.0);
}`));
gl.linkProgram(program);
if (!gl.getProgramParameter(program, gl.LINK_STATUS)) throw new Error(gl.getProgramInfoLog(program));
const url = URL.createObjectURL(new Blob([JSON.stringify(gltf)], { type: 'model/gltf+json' }));
try {
const mesh = await loadGltf(url);
gl.viewport(0, 0, 640, 360);
gl.clearColor(0.95, 0.97, 1.0, 1);
gl.clear(gl.COLOR_BUFFER_BIT);
gl.useProgram(program);
gl.bindVertexArray(mesh.vao);
gl.drawElements(gl.TRIANGLES, mesh.count, mesh.type, mesh.offset);
console.log(`读取:顶点 3、索引 ${mesh.count}、Buffer 102 字节`);
} finally {
URL.revokeObjectURL(url);
}
</script>
</html>预期结果:画布显示浅蓝白背景和一个 UV 渐变色三角形,浏览器控制台输出:
读取:顶点 3、索引 3、Buffer 102 字节核对加载结果与能力边界
先核查 POSITION、NORMAL、TEXCOORD_0 三个属性是否都绑定到 VAO,并确认索引缓冲是在 VAO 绑定期间设置的;否则即使顶点数据存在,drawElements 也可能无法正确绘制。三角形若缺面,优先检查 indices、componentType 和 drawElements 的字节偏移,不要把索引编号当成字节地址。
这个加载器有意限制输入:只读取首个 Mesh 的首个 Primitive,要求三个属性均为 FLOAT、存在索引且绘制模式为 TRIANGLES。它支持普通 BufferView 的 byteStride 和相对 .bin 路径,但没有处理 .glb 的 BIN 块、稀疏 Accessor、整型归一化属性、节点变换、多个网格、PBR 材质、纹理、蒙皮、动画与压缩扩展。遇到这些数据应显式报错或扩展解析,不要直接按 Float32Array 强制解释所有字节。
要接入真实静态模型,先挑选包含单个三角形 Primitive、无必需扩展的 .gltf,确认浏览器能同时请求 JSON 和其关联的 .bin,再替换示例 URL。完整字段限制可查阅 Khronos glTF 2.0 规范。