Ratty 的 WebGPU Vertex Buffer 几何管线解析

在终端模拟器领域，Ratty 代表了一种激进的范式转变：它不仅渲染文本，还通过 WebGPU 将 3D 几何图形直接嵌入到终端的二维画布中。这种架构的核心在于 Vertex Buffer 几何管线的精心设计，它使得终端单元格空间与 GPU 可编程渲染管线之间的数据流转变得流畅而高效。

终端渲染的三层架构

Ratty 的渲染管线遵循清晰的三层分离架构。第一层处理 PTY I/O 与终端状态解析，通过 portable-pty 创建伪终端会话，由 vt100 解析器将转义序列转换为屏幕状态。第二层由 Ratatui 接管，将终端状态构建为 GPU 可消费的缓冲区，再通过 parley 进行字体整形，最后由 Vello 在 WebGPU 上完成 2D 图元的光栅化。第三层则是 Bevy 游戏引擎的领地，它将前两层输出的纹理作为 3D 场景的材质进行渲染。

这种分离设计的关键价值在于：终端模拟逻辑与表现层完全解耦。同一套终端状态既可以被渲染为传统的 2D 终端视图，也可以被 Bevy 进行任意的 3D 变换 —— 比如将整个终端弯曲成球面，或让光标以旋转的 3D 老鼠形态悬浮在终端窗口中。

Vertex Buffer 的本质与配置

在 WebGPU 的语境中，Vertex Buffer 是一种特殊的 GPU Buffer，它不通过着色器直接访问，而是由 API 描述其内部数据的布局结构，再由 GPU 自动提取并传递给顶点着色器。理解这一点对把握 Ratty 的几何管线至关重要。

创建一个 Vertex Buffer 需要指定三个核心参数。size 定义缓冲区字节长度，usage 必须包含 GPUBufferUsage.VERTEX 标志以表明其用途，GPUBufferUsage.COPY_DST 则允许后续通过队列写入数据。Ratty 中加载 3D 模型文件（如 Wavefront OBJ 格式）后，会将顶点坐标、法线向量、纹理坐标等数据编码为连续字节块，然后写入 Vertex Buffer 供渲染使用。

渲染管线的 vertex 字段中的 buffers 数组则描述了如何从这些缓冲区中提取数据。arrayStride 指定相邻顶点数据之间的字节偏移量，例如对于包含位置（3 个 float32）和颜色（4 个 unorm8）的顶点结构，步幅为 3×4 + 4 = 16 字节。stepMode 控制数据推进的频率，vertex 模式每个顶点推进一次，instance 模式则每个实例推进一次 —— 后者是实现大量相似几何体高效渲染的关键。

attributes 数组定义了单个属性如何从缓冲区中映射到顶点着色器的输入。每个属性对象包含 shaderLocation（对应着色器中的 @location 限定符）、offset（属性在顶点内的字节偏移）和 format（数据的 GPU 格式，如 float32x3、unorm8x4 等）。Ratty 在注册 3D 模型时，会根据模型的顶点格式配置这些参数，确保 GPU 能够正确解析几何数据。

索引缓冲与几何优化

直接使用顶点数据绘制复杂几何体会产生大量冗余。对于一个由数百个三角形构成的网格，许多顶点会在多个三角形中重复出现，造成内存浪费和顶点着色器的重复计算。索引缓冲（Index Buffer）提供了一种优雅的解决方案。

索引缓冲包含无符号整数索引，指向顶点缓冲中的特定顶点。在绘制调用 drawIndexed 执行时，GPU 按照索引顺序而非连续顺序读取顶点数据。这意味着 Ratty 只需为共享顶点存储一份数据，通过索引复用即可构建完整网格。索引格式可以是 uint16（16 位，适合顶点数小于 65535 的模型）或 uint32（32 位，支持更大规模的场景）。

在实际渲染流程中，Ratty 首先将 OBJ 模型的顶点坐标、法线、UV 坐标打包为顶点缓冲，再将面索引序列化为索引缓冲。通过 pass.setIndexBuffer(indexBuffer, 'uint32') 将索引缓冲绑定到渲染通道，即可调用 drawIndexed 完成几何绘制。这种模式在处理 TempleOS 的 DolDoc 文档中嵌入的 3D 模型时尤为重要 —— 那些从 HolyC 源代码中提取的 SPT_MESH 记录，经过转换后同样需要经过类似的索引化处理才能高效渲染。

着色器端的顶点属性声明

WGSL 着色器语言通过 @location 限定符声明顶点着色器接收的顶点属性。在 Ratty 的自定义着色器中，典型的顶点输入结构体可能包含位置（@location(0)）、法线（@location(1)）、UV 坐标（@location(2)）以及可能的顶点颜色或实例变换数据。GPU 会根据渲染管线配置中对应的 shaderLocation 值，自动将 Vertex Buffer 中的数据提取并填充到这些输入变量中。

Ratty 的独特之处在于它将终端单元格坐标系统映射到 3D 场景空间。给定终端尺寸（列数与行数）和视口尺寸，可以计算出每个单元格的像素宽高，进而将光标位置从终端坐标转换为场景坐标。旋转的老鼠光标模型正是通过这种映射，在终端单元格空间中定位，然后以自旋和上下浮动动画叠加的方式在 3D 世界中运动。

工程落地的关键参数

在终端嵌入式场景中实现 Vertex Buffer 几何管线，有几个关键参数需要仔细调优。顶点格式选择直接影响带宽消耗与精度平衡：位置数据推荐 float32x3 以确保空间精度，颜色数据可用 unorm8x4 压缩到 4 字节并自动归一化到 0-1 范围，纹理坐标 float32x2 通常足够。实例化数据（如果使用）的步幅应与对齐要求匹配，WebGPU 要求属性偏移按属性大小的倍数对齐，否则可能导致渲染错误。

缓冲区更新策略也需要考虑。对于静态模型（如加载后不再变形的 OBJ 文件），可以在初始化时一次性写入顶点与索引数据，后续帧仅绑定使用。对于动态几何（如动画角色或变形网格），则需要每帧通过 device.queue.writeBuffer 更新缓冲区，并确保使用 COPY_DST 用途。对于高频更新的数据（如粒子系统），考虑使用 drawIndirect 或计算着色器直接写入 Buffer，减少 CPU-GPU 同步开销。

渲染通道的命令编码遵循固定顺序：先 setPipeline 绑定渲染管线，再 setVertexBuffer 按索引绑定所有顶点缓冲，接着如有索引缓冲则 setIndexBuffer，最后执行 draw 或 drawIndexed 调用。顺序错误或遗漏绑定会导致着色器接收到未定义的数据，产生视觉错误或性能问题。

Ratty 的架构证明，终端模拟器的核心挑战不再是字符渲染的性能，而是如何将传统的二维终端体验无缝嵌入到现代 GPU 可编程渲染管线中。Vertex Buffer 作为几何数据的载体，扮演着从文件格式解析到屏幕像素生成之间的关键桥梁角色。

资料来源：Ratty 项目博客（https://blog.orhun.dev/introducing-ratty/）、WebGPU 顶点缓冲基础（https://webgpufundamentals.org/webgpu/lessons/webgpu-vertex-buffers.html）

ai-systems