Shaderc VkRunner (GPU Shader Sandbox)

🚀 VkRunner Documentation

VkRunner is a tool designed to run shader test scripts. It supports compiling and executing shaders through GLSL or SPIR-V and can output the results as PPM images. Additionally, it offers a C library interface, facilitating its integration into other test suites.

🚀 Quick Start

🔍 Overview

VkRunner is a tool for running shader test scripts. It supports compiling and executing shaders via GLSL or SPIR-V and can output the results as PPM images. Moreover, it provides a C library interface for easy integration into other test suites.

📦 Installation

No installation steps are provided in the original document, so this section is skipped.

✨ Features

Script Structure

Environment Configuration

• Device Selection: Use the --device-id DEVID option to specify a Vulkan device.
• Log Output: Use the -i IMG option to save the final rendering result as a PPM image.
• Debug Information: Use the -d option to display SPIR-V disassembly information.

Script Content

• Shader Configuration
  • Vertex Shader: Use the vertexShader directive to specify a GLSL or SPIR-V file.
  • Fragment Shader: Use the fragmentShader directive to specify a GLSL or SPIR-V file.
  • Compute Shader: Use the computeShader directive to specify a GLSL or SPIR-V file.
• Constant Buffer Configuration
  • UBO Configuration: Use the ubo N subdata TYPE VALUE to allocate initial values for the UBO.
• Shader Preprocessing
  • GLSL Compilation: Use the glslangValidator and spirv-as tools to convert GLSL to SPIR-V.
  • SPIR-V Precompilation: You can directly include SPIR-V binary data in the script to avoid compiler dependencies.
• Graphics Rendering
  • Draw Commands: Use the draw arrays or draw indexed directives for graphics rendering.
  • Vertex Data: Use the [vertex data] and [indices] sections to define vertex and index buffers.

💻 Usage Examples

Basic Usage

Example Script: basic.shader_test

[vertex data]
# Define the vertex coordinates of a triangle
0.0 0.0 1.0  # First vertex (x, y, z)
0.5 0.0 1.0  # Second vertex
0.25 0.5 1.0 # Third vertex

[vertex data]
# Define the vertex coordinates of a second triangle
-0.5 0.0 1.0
-0.75 0.5 1.0
-0.25 0.5 1.0

[index]
# Draw two triangles using an index buffer
0 1 2  # Draw the first triangle
3 4 5  # Draw the second triangle

[test commands]
draw arrays triangleStrip

Example Script: compute.shader_test

[ubo]
# Define a simple UBO structure
struct Buf {
    data vec4;
};

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

[test commands]
computeShader compute.comp  # Specify the compute shader file

Precompilation Tools

Tool Introduction

• precompile-script.py: Precompiles shader scripts into binary files to accelerate execution and reduce dependencies.
• Command-Line Options
  • -o OUTPUT_DIR: Specify the output directory.
  • -g GLSLANG_PATH: Specify the path to glslangValidator.
  • -s SPIRV_AS_PATH: Specify the path to spirv-as.

Usage Example

# Precompile all examples into the compiled-examples directory
./precompile-script.py -o compiled-examples examples/*.shader_test

# Execute the precompiled test cases
./src/vkrunner compiled-examples/*.