Ratty 终端缓冲区到 3D 渲染管线的数据流集成

Ratty 是一个将 3D 图形直接嵌入终端屏幕的实验性终端模拟器。与传统 GPU 加速终端仅优化文本渲染性能不同，Ratty 的核心创新在于：终端缓冲区状态既是文本内容的来源，也是 3D 场景的驱动信号。本文聚焦其终端缓冲区到渲染管线的数据流集成机制，解析 PTY 解析层、Ratatui 缓冲区层与 Bevy 场景层之间的状态传递与坐标变换逻辑。

三层渲染架构概述

Ratty 的渲染管线分为三个严格分离的阶段，每一层负责不同的职责边界。

第一层是 PTY 仿真层。Shell 进程运行在由 portable-pty crate 创建的伪终端中，所有输出包括 ANSI 转义序列都被捕获并交给 vt100 crate 解析。解析结果被维护为终端屏幕的内部状态，包括每个单元格的字符、样式、光标位置等信息。这一层完全与渲染解耦，只负责协议解析和状态维护。

第二层是 Ratatui 缓冲区层。Ratty 将解析后的终端状态重建为 Ratatui 风格的缓冲区（Buffer），每个终端单元格映射到缓冲区的对应位置。parley crate 负责字体塑形（font shaping），Vello GPU 渲染器负责将文本内容绘制到 GPU 纹理上。该纹理作为第二层的输出，同时承载了完整的 2D 终端画面。

第三层是 Bevy 场景层。Bevy 引擎将第二层输出的纹理映射为 3D 空间中的一个或多个平面。这个平面作为终端屏幕的几何表示存在，摄像机、光照和其他 3D 对象可以在场景中自由运动。整个 3D 世界的更新节拍由 Bevy 的主循环驱动，而纹理内容的更新则由终端状态变化驱动，两者通过数据流松耦合。

这种分离设计的关键价值在于：终端仿真逻辑不依赖任何渲染实现细节，未来可以用不同的渲染后端替换 Bevy 层，只需保证纹理输出格式兼容即可。

终端缓冲区到 GPU 纹理的映射

Ratatui 缓冲区是连接终端状态与 GPU 渲染的中间桥梁。Buffer 结构体以矩形区域（Rect）为单位组织，每个单元格存储字符、样式（前景色、背景色、加粗、下划线等属性）以及修饰标记。Ratty 的终端模块（src/terminal.rs）负责将 vt100 解析出的屏幕状态转换为 Buffer 实例：

use ratatui::buffer::Buffer;
use ratatui::layout::Rect;

let area = Rect::new(0, 0, cols, rows);
let mut buffer = Buffer::empty(area);

// 从 vt100 屏幕状态逐行填充缓冲区
for row in 0..rows {
    for col in 0..cols {
        let cell = vt100_screen.cell(row as u16, col as u16);
        buffer[(col as u16, row as u16)]
            .set_char(cell.ch())
            .set_fg(cell.fg())
            .set_bg(cell.bg());
    }
}

填充完成后，parley 对整个缓冲区执行字体塑形，包括字形选择、字距调整和连字处理。塑形结果交给 Vello 执行 GPU 光栅化，最终生成 RGBA 纹理。这张纹理包含完整的终端画面，但其像素空间与终端逻辑单元格空间存在一一对应关系 —— 每个单元格对应的像素区域是可计算的。

单元格空间到场景空间的坐标变换

纹理映射到 3D 平面后，需要将终端单元格坐标转换为 Bevy 场景空间坐标。Ratty 提供了明确的线性变换公式：

let cell_width = viewport_size.x / cols as f32;
let cell_height = viewport_size.y / rows as f32;

let x = -viewport_size.x * 0.5 + (cursor_col as f32 + 0.5) * cell_width;
let y = viewport_size.y * 0.5 - (cursor_row as f32 + 0.5) * cell_height;

这个变换的核心逻辑是：以视口中心为原点，单元格坐标（列号、行号）通过线性插值映射到归一化的视口坐标，然后乘以视口尺寸得到世界坐标。行号在 Y 轴上反转是因为终端坐标系的原点位于左上角，而 3D 场景通常以左下角为 Y 轴零点。

Z 轴坐标决定物体在终端平面之上或之下的层叠关系。Ratty 允许通过 RGP 协议的 depth 参数控制每个 3D 对象的 Z 深度值。正深度将物体置于终端平面之前（靠近摄像机），负深度则将物体推到终端平面之后。这使得 3D 对象可以出现在终端文本之前或之后，实现视觉上的层叠效果。

光标实体的场景驱动机制

Ratty 将终端光标实现为 Bevy 场景中的一个普通 3D 实体，而非终端缓冲区的一部分。在 Ratatui 缓冲区中，光标单元格被渲染为空格字符以避免双重显示：

buffer[(cursor_col, cursor_row)].set_char(' ');

与此同时，Bevy 侧独立管理光标实体，绑定网格（Mesh）和材质（Material）组件：

commands.spawn((
    CursorModel,
    Mesh3d(mesh_handle),
    MeshMaterial3d(material_handle),
    Transform::from_xyz(0.0, 0.0, 10.0),
));

每帧渲染时，Ratty 从终端状态查询光标的行列位置，通过坐标变换公式转换为场景坐标，然后驱动实体的变换组件：

let spin = elapsed_secs * spin_speed as f32;
let bob = (elapsed_secs * bob_speed as f32).sin() * cell_height * bob_amplitude;

transform.translation = Vec3::new(x, y + bob, 10.0);
transform.rotation = Quat::from_rotation_y(spin) * Quat::from_rotation_x(-0.25);
transform.scale = Vec3::splat(cell_width.min(cell_height));

这种设计将光标的行为完全交由场景引擎控制 —— 可以旋转、浮动、缩放、响应光照 —— 而其位置始终由终端状态决定。配置文件中暴露的 spin_speed、bob_speed、bob_amplitude 等参数正是这种分离的工程体现：终端提供位置语义，渲染层决定表现形式。

RGP 协议的单元格锚定机制

Ratty Graphics Protocol（RGP）定义了一套基于 APC（Application Program Command）控制序列的通信协议，用于在终端中注册和放置 3D 对象。协议格式如下：

ESC _ ratty ; g ; <verb> [ ; <key=value> ... ] ESC \

四个核心动词构成了 RGP 的全部操作集：s 查询终端对 RGP 的支持情况，r 注册一个 3D 资产（指定格式如 OBJ 或 GLB），p 将资产锚定到终端单元格空间，d 删除已放置的对象。

锚定操作是 RGP 的核心语义。以 p 动词为例：

ESC _ ratty;g;p;id=7;row=5;col=10;w=3;h=2;animate=1;scale=1.0;depth=1.5;color=7fd0ff;brightness=1.0 ESC \

row 和 col 指定锚点单元格，w 和 h 定义对象在单元格空间中占据的宽高区域。scale 控制对象的缩放系数，depth 控制 Z 深度，color 和 brightness 分别设置颜色覆盖和亮度调整。当锚点单元格因滚动或编辑而移动时，3D 对象随之移动 —— 这是 RGP 与终端缓冲区状态保持同步的关键机制。

ratatui-ratty widget 封装了 RGP 协议的使用细节。应用程序只需构建 RattyGraphicSettings 并调用 register() 方法，widget 会自动生成对应的 APC 序列并写入标准输出。渲染逻辑完全由 Ratty 接管：

use ratatui_ratty::{RattyGraphic, RattyGraphicSettings};

let graphic = RattyGraphic::new(
    RattyGraphicSettings::new("model.obj")
        .id(7)
        .animate(true)
        .scale(1.0)
        .depth(1.5)
        .color([0x7f, 0xd0, 0xff])
        .brightness(1.0),
);

graphic.register()?;

需要注意的是，widget 并不直接在缓冲区中绘制图形对象，而是生成 RGP 控制序列。这意味着应用程序在 Ratatui 层面的渲染调用（如 widget.render()）主要用于计算对象在单元格空间中的边界，而不参与实际的 3D 渲染流程。这种职责分离确保了 RGP 对象的渲染完全由 Ratty 的 Bevy 层处理，与终端文本的 Ratatui 渲染流水线互不干扰。

数据流的同步与性能边界

终端缓冲区到 GPU 纹理的更新节拍与 Bevy 场景的帧更新节拍通常不同步。终端输入的到达是异步的（按键、网络响应、进程输出），而 Bevy 渲染循环以固定帧率（如 60 FPS）推进。Ratty 采用事件驱动的纹理更新策略：当终端缓冲区内容发生变化时，触发 Ratatui 重新渲染纹理；Bevy 每帧采样当前纹理内容进行场景更新。

这种设计在大多数场景下工作良好，因为 Ratatui 的 GPU 渲染本身也是增量式的 —— 只有变化的单元格需要重绘。但在终端快速滚动或大量输出时，纹理更新频率可能超过 Bevy 的帧预算，导致视觉延迟。Ratty 目前通过依赖 Bevy 引擎的资源管理机制来应对这一问题，尚未实现帧预算自适应或异步渲染流水线。

资源消耗是另一个工程边界。Bevy 作为游戏引擎，依赖 wgpu 进行 GPU 资源分配，一个运行中的 Ratty 实例需要维护终端状态、Ratatui 缓冲区、GPU 纹理、Bevy 场景图和 3D 模型资源等多层数据结构。相比传统终端模拟器（如 Alacritty、Kitty），内存占用显著更高。Ratty 并不追求替代传统终端，而是作为 3D 终端渲染的实验性探索，其资源模型与这一目标定位一致。

可落地参数与集成要点

对于希望在 Ratty 架构上构建应用的开发者，以下参数和集成要点值得关注。

渲染分辨率与单元格尺寸的计算直接影响坐标映射精度。推荐使用视口尺寸除以终端列数 / 行数得到精确的单元格像素尺寸，而非固定缩放值。动态调整终端大小时，必须同步更新 Bevy 场景中终端平面的 UV 坐标映射。

光标动画参数（spin_speed、bob_speed、bob_amplitude）建议以终端刷新率的倍数作为旋转变换的时间步长基准，避免动画速度随帧率波动。可以通过 time::Delta 而不是 elapsed_secs 累积时间来实现帧率无关的动画。

RGP 协议的 depth 参数范围建议控制在 [-10, 10] 区间内，超出范围可能导致 Z-fighting 或物体不可见。多个对象处于相近深度时，Bevy 的深度测试会按相机距离排序渲染。

对于跨平台部署，wgpu 后端在不同操作系统上的 GPU 驱动支持存在差异。Linux 环境下推荐使用 Vulkan 后端以获得最佳性能，macOS 上使用 Metal 后端，Windows 上 DX12 和 Vulkan 均可。Ratty 目前未暴露后端选择配置接口，这是未来可优化的方向。

资料来源

• Ratty 项目介绍与渲染架构详解：https://blog.orhun.dev/introducing-ratty/

systems