🚀 VkRunner 使用文档

VkRunner 是一款专门用于运行 shader 测试脚本的工具。它支持通过 GLSL 或 SPIR-V 进行 shader 的编译与执行，并且能够将运行结果输出为 PPM 图像。此外，该工具还提供了 C 库接口，便于集成到其他测试套件中。

🚀 快速开始

环境配置

• 设备选择：使用 --device-id DEVID 选项指定 Vulkan 设备。
• 日志输出：使用 -i IMG 选项将最终渲染结果保存为 PPM 图像。
• 调试信息：使用 -d 选项显示 SPIR-V 反汇编信息。

脚本内容

着色器配置

• 顶点着色器：使用 vertexShader 指令指定 GLSL 或 SPIR-V 文件。
• 片段着色器：使用 fragmentShader 指令指定 GLSL 或 SPIR-V 文件。
• 计算着色器：使用 computeShader 指令指定 GLSL 或 SPIR-V 文件。

常量缓冲区配置

• ubo 配置：使用 ubo N subdata TYPE VALUE 为 UBO 分配初始值。

着色器预处理

• GLSL 编译：使用 glslangValidator 和 spirv-as 工具将 GLSL 转换为 SPIR-V。
• SPIR-V 预编译：可以通过脚本直接包含 SPIR-V 二进制数据，避免编译器依赖。

图形渲染

• 绘制命令：使用 draw arrays 或 draw indexed 指令进行图形渲染。
• 顶点数据：使用 [vertex data] 和 [indices] 部分定义顶点和索引缓冲区。

✨ 主要特性

• 支持 GLSL 或 SPIR-V 编译和执行 shader。
• 可将运行结果输出为 PPM 图像。
• 提供 C 库接口，方便集成到其他测试套件。
• 可通过脚本直接包含 SPIR-V 二进制数据，减少编译器依赖。

💻 使用示例

基础用法

示例脚本：basic.shader_test

[vertex data]
# 定义一个三角形的顶点坐标
0.0 0.0 1.0  # 第一个顶点 (x, y, z)
0.5 0.0 1.0  # 第二个顶点
0.25 0.5 1.0 # 第三个顶点

[vertex data]
# 定义第二个三角形的顶点坐标
-0.5 0.0 1.0
-0.75 0.5 1.0
-0.25 0.5 1.0

[index]
# 使用索引缓冲区绘制两个三角形
0 1 2  # 绘制第一个三角形
3 4 5  # 绘制第二个三角形

[test commands]
draw arrays triangleStrip

示例脚本：compute.shader_test

[ubo]
# 定义一个简单的 UBO 结构体
struct Buf {
    data vec4;
};

buf Buf ubodata = (Buf){vec4(1.0, 0.0, 0.0, 1.0)};

[test commands]
computeShader compute.comp  # 指定计算着色器文件

高级用法

预编译工具使用

工具介绍

• precompile-script.py：将 shader 脚本预编译为二进制文件，加速执行并减少依赖。
• 命令行选项：
  • -o OUTPUT_DIR：指定输出目录。
  • -g GLSLANG_PATH：指定 glslangValidator 的路径。
  • -s SPIRV_AS_PATH：指定 spirv-as 的路径。

使用示例

# 预编译所有例子到 compiled-examples 目录
./precompile-script.py -o compiled-examples examples/*.shader_test

# 执行预编译后的测试用例
./src/vkrunner compiled-examples/*.shader_test