TsundereStation/data/shaders/vulkan/README.md

46 lines
1.9 KiB
Markdown
Raw Normal View History

common/vulkan, core: pre-bake screen-quad VS, no glslang at runtime This is the probe patch in a series that eliminates dep/glslang from the libretro core build. It establishes the infrastructure - the GLSL source tree, the embedded-SPIR-V loader, the regeneration tool, and the build wiring - by converting exactly one call site so the pattern can be smoke-tested in isolation before the rest of Bucket A and then Bucket B follow in subsequent patches. glslang stays in the tree until the final patch in the series, which removes dep/glslang and the surrounding shader_compiler.cpp. What this patch does: - Adds data/shaders/vulkan/screen_quad.vert.glsl - the GLSL source for the screen-quad VS, kept in the tree for human readability. The build does NOT see this file; it is consumed only by the offline regen tool. - Adds src/common/vulkan/embedded_spirv/screen_quad_vs.inc - the pre-compiled SPIR-V blob as a 'const uint32_t[]' (367 words, 1.4 KiB), generated offline from the .glsl by glslangValidator targeting vulkan1.0. The .inc is checked in and #include'd by embedded_shaders.cpp inside namespace Vulkan::EmbeddedShaders. spirv-val confirms the blob is valid Vulkan 1.0 SPIR-V (magic 0x07230203, version 1.0). - Adds src/common/vulkan/embedded_shaders.{h,cpp}. The header exposes a pair of extern declarations per blob and a single CreateShaderModule(const uint32_t*, size_t) loader. The loader intentionally bypasses Vulkan::ShaderCache - pre-baked SPIR-V is already final, so there is nothing to compile and nothing worth caching on disk. Just a sized-and-checked vkCreateShaderModule call. - Adds tools/regen_vulkan_spirv.py - the offline workflow for contributors who edit shader .glsl sources. It invokes glslangValidator on each .glsl under data/shaders/vulkan/ and rewrites the matching .inc. CRITICAL: this tool is NEVER invoked by Make or CMake. The build sees only .h/.cpp/.inc files and has no shader- compiler dependency. Contributors run the script manually after editing .glsl, commit both files together. - Adds data/shaders/vulkan/README.md documenting the workflow and the invariant that the build must never invoke an external shader compiler. - Switches GPU_HW_Vulkan::GetFullscreenQuadVertexShader() (in src/core/gpu_hw_vulkan.cpp) from g_vulkan_shader_cache->GetVertexShader(m_shadergen->Generate...) to Vulkan::EmbeddedShaders::CreateShaderModule(k_screen_quad_vs, ...). The m_shadergen null-check is removed since the embedded path has no such ordering dependency. The function's contract (lazy creation, stored in m_fullscreen_quad_vertex_shader, returned to multiple pipeline builders) is unchanged. - Registers src/common/vulkan/embedded_shaders.cpp in both Makefile.libretro (alphabetical order in the vulkan/ SOURCES_CXX block) and src/common/CMakeLists.txt (alphabetical order in the common target's source list). Neither change adds any build-tool dependency; the new .cpp compiles like any other. What this patch does NOT do: - It does not remove dep/glslang or the SOURCES_CXX entries that pull in its 99 translation units. glslang is still needed for every shader generator that has not yet been converted - in particular all of GPU_HW_ShaderGen, plus the remaining utility shaders (UV quad VS, VRAM read/copy/write/fill/update-depth FS, display FS, adaptive downsample mip/blur/composite FS, box-sample downsample FS). Subsequent patches in this series convert those one bucket at a time. The final patch removes dep/glslang, src/common/vulkan/shader_compiler.{h,cpp}, the glslang link line in CMake, and the Makefile entries. - It does not touch the disk-backed Vulkan::ShaderCache. That cache still serves the runtime-glslang path for remaining shaders. Smoke tests performed in isolation: - glslangValidator --target-env vulkan1.0 succeeds on the .glsl source, producing 367 32-bit words of SPIR-V. - spirv-val --target-env vulkan1.0 reports VALID on the blob. - spirv-dis confirms the entry point, VertexData block, and Position/ VertexIndex built-ins are correctly emitted. - A standalone harness including the .inc inside the Vulkan::EmbeddedShaders namespace and calling CreateShaderModule through a stubbed vkCreateShaderModule reads back the correct magic word and size. - g++ -fsyntax-only on embedded_shaders.cpp against the real headers in the tree (excluding only the platform-specific X11 surface define not used by this TU) is clean. Smoke tests that require the user's setup: - Real build on Windows (RTX 5090) and macOS. - Vulkan core boots, RetroArch's pipeline cache populates, and at least one game renders past the first frame using the screen-quad pipeline (VRAM ops, display, downsample - all of which call GetFullscreenQuadVertexShader internally).
2026-05-17 17:49:19 +00:00
# Vulkan shader sources (pre-baked SPIR-V)
This directory holds the GLSL sources for shaders used by the Vulkan backend
that have been moved off the runtime `ShaderGen` path. Each `.glsl` file here
has a matching pre-compiled SPIR-V blob checked in to
`src/common/vulkan/embedded_spirv/`.
## Why this exists
Historically the Vulkan backend generated GLSL at runtime via
`src/core/shadergen.cpp` and `src/core/gpu_hw_shadergen.cpp`, then handed the
text to glslang inside `src/common/vulkan/shader_compiler.cpp` to produce
SPIR-V. Both `dep/glslang/` (4.4 MB of vendored source, 99 translation units)
and the disk-backed runtime shader cache exist solely to support that path.
Pre-baking the SPIR-V removes:
* the glslang dependency from the libretro core build,
* the per-launch shader compilation stall, and
* a class of "stale cache after glslang version bump" runtime failures.
The OpenGL / OpenGL ES / D3D11 / D3D12 backends still use the runtime
`ShaderGen` path; only the Vulkan backend reads from the embedded SPIR-V.
## Build-time constraint
The core build (`Makefile.libretro` and `src/common/CMakeLists.txt`) must
never invoke an external shader compiler. The `.inc` files under
`src/common/vulkan/embedded_spirv/` are checked into the repository and
compiled like any other C++ source. The `tools/regen_vulkan_spirv.py` helper
exists for contributors who edit the `.glsl` sources in this directory; it is
not part of the build.
## Regenerating the SPIR-V blobs
After editing a `.glsl` file here, run:
python3 tools/regen_vulkan_spirv.py
This invokes `glslangValidator --target-env vulkan1.0` on each `.glsl` file
and rewrites the matching `.inc` under `src/common/vulkan/embedded_spirv/`.
Both the `.glsl` and the regenerated `.inc` must be committed together so the
two stay in sync.
`glslangValidator` is part of the Vulkan SDK (or the `glslang-tools` package
on Debian / Ubuntu). It is **not** invoked by the core build.