Skip to content
Sources: tools/build_shaders.py .github/actions/build-sdl3-shaders/action.yml src/cata_shader.cpp data/shaders/nightvision.frag commit d32b9cc880a8 build-config

SDL3 shaders

SDL3 tiles builds compile GLSL sources to backend-specific artifacts before packaging. At runtime CCB selects SPIR-V for Vulkan, DXIL for D3D12, or MSL for Metal according to the GPU formats reported by SDL.

Authoritative pipeline

  • Human-maintained sources are data/shaders/*.frag and *.vert.
  • tools/build_shaders.py invokes glslangValidator and SDL_shadercross.
  • .github/actions/build-sdl3-shaders/action.yml pins/builds the toolchain and uploads artifacts.
  • Make/CMake/MSVC rules consume the artifacts; src/cata_shader.* selects and owns them at runtime.

The explicit generator interface is:

python3 tools/build_shaders.py --shader-dir data/shaders --formats spv,dxil,msl

It requires external compilers. A command that failed because those tools are absent is not a shader validation pass.

Generated boundary

.spv, .dxil, .msl, and build-stamp files are generated artifacts. Change GLSL or the generator, then regenerate; do not hand-edit binaries. Keep large/generated outputs in CI or release artifacts unless the main repository's generated-file policy explicitly tracks them.

Runtime invariants

Artifact basename/stage matches the GLSL source; uniform/sampler counts match runtime creation; at least one shipped format matches the active GPU; missing/invalid artifacts fail with useful logs; renderer recovery releases and recreates shader/render-state resources safely.

Validation

Compile every requested format, preserve generator logs, run the SDL3 shader CI lane, launch on representative Vulkan/D3D12/Metal backends, exercise each visual variant and renderer recovery, and compare a controlled screenshot. SDL2 does not validate this pipeline.

Performance and compatibility

Avoid compiling at runtime and avoid rebuilding render state per draw. Changing uniforms, bindings, or backend preference is an API-like renderer change and requires all three artifact formats plus fallback/error-path evidence.