Shaderc VkRunner (GPU Shader Sandbox)

🚀 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