glslangValidator Flags for SPIR-V 1.4 Ray Tracing

Compiling GLSL ray tracing shaders into SPIR-V 1.4 requires specific command-line flags when using glslangValidator. This guide outlines the exact flags needed to target SPIR-V 1.4, explains alternative target environment options, and clarifies why the SPIR-V 1.4 specification is mandatory for modern Vulkan ray tracing pipelines (VK_KHR_ray_tracing_pipeline).

The Required Command-Line Flags

To emit SPIR-V 1.4 code from a GLSL ray tracing shader, pass the -V flag alongside the --target-env argument set to spirv1.4:

glslangValidator -V --target-env spirv1.4 -o shader.spv shader.rgen
  • -V: Instructs glslangValidator to compile the shader into a binary SPIR-V file rather than simply validating the GLSL source code.
  • --target-env spirv1.4: Explicitly targets the SPIR-V 1.4 specification.

Vulkan Environment Target Alternatives

In Vulkan applications, you can also target the Vulkan environment directly instead of targeting the raw SPIR-V version:

  • --target-env vulkan1.1spirv1.4: Used if your application runs on Vulkan 1.1 with the VK_KHR_ray_tracing_pipeline or VK_KHR_spirv_1_4 extensions enabled.
  • --target-env vulkan1.2: Vulkan 1.2 incorporates SPIR-V 1.5 by default. Because SPIR-V is backward-compatible, targeting Vulkan 1.2 natively satisfies and exceeds the SPIR-V 1.4 requirement for ray tracing:
glslangValidator -V --target-env vulkan1.2 -o shader.spv shader.rgen

Why Ray Tracing Requires SPIR-V 1.4

The Vulkan KHR ray tracing extensions (GL_EXT_ray_tracing) require SPIR-V 1.4 or higher due to how variables are passed between ray tracing stages.

In SPIR-V 1.3 and earlier, only input and output storage classes (Input and Output) were listed in the entry point interface. SPIR-V 1.4 changed the interface rules so that all global variables accessed by an entry point—including ray tracing storage classes like RayPayloadKHR, IncomingRayPayloadKHR, HitAttributeKHR, and uniform or storage buffers—must be declared in the entry point’s interface list. Without the --target-env spirv1.4 (or newer) flag, compilation will fail with errors indicating that ray tracing features are incompatible with the target SPIR-V version.

Handling Shader Extensions

glslangValidator automatically detects the shader stage based on standard file extensions:

  • .rgen: Ray Generation
  • .rint: Intersection
  • .rahit: Any-Hit
  • .rchit: Closest-Hit
  • .rmiss: Miss
  • .rcall: Callable

If your shader files use a custom extension (such as .glsl), explicitly define the shader stage using the -S flag:

glslangValidator -V --target-env spirv1.4 -S rgen -o rgen.spv custom_shader_name.glsl