为 Compiler 做贡献

本节介绍版本控制规则及其重要性。

编译器的工作原理

Dagor Shader Compiler （DSC） 用于创建编译的着色器转储（对于每个特定的驱动程序和着色器模型是独立的）。对于给定的编译器运行，最终结果通常是单个 <name><driver>.[bindless.]<shader model>.shdump.bin 文件和（可选）动态 CPP STCODE 库。为了减少编译时间，中间文件将被缓存并在将来的运行中重复使用：

  • SHA cache (二进制): 位于 <intermediate dir>/../../shaders_sha~<platform>-O<optimization level>[-bindless]/bin，包含为特定着色器编译的特定于驱动程序的二进制文件。如果在将来的编译器运行中编译完全相同的 HLSL（或类似 HLSL）的代码，请重复使用。

  • SHA cache (源代码): 位于 <intermediate dir>/../../shaders_sha~<platform>-O<optimization level>[-bindless]/src，可能包含要编译的特定着色器的最终 HLSL（或类似 HLSL）源代码。引用二进制缓存文件（如果已生成）。

  • .obj文件：位于 <intermediate dir>中，包含给定.dshl文件的完整编译器输出。如果.dshl文件自上次编译器运行以来未被修改，则重复使用。

以下是可用<driver> 值的列表：

  • DX12x - Xbox One 平台

  • DX12xs - Xbox Series 平台

  • DX12 - DirectX 12 API

  • SpirV - Vulkan API

  • PS4 - PlayStation 4 平台

  • PS5 - PlayStation 5 平台

  • MTL - Metal API

  • 空字符串 - DirectX 11 API

输入.blk 必须 具有变量 outDumpName:t="<dump path>/< name><driver>"。

[bindless]的存在由 DSC 标志-enableBindless:on定义。

<intermediate dir>由 DSC 标志-o定义。

版本控制

Dagor Shader Compiler 有 3 个不同的“版本”，每个版本都必须单独更新：

  • 如果生成的 HLSL（或类似 HLSL）代码可以生成与以前版本不同的字节码（例如，如果您更新了 HLSL 编译器的库），则相应的sha1_cache_version必须在prog/tools/ShaderCompiler2/sha1_cache_version.h中更新，因为它用于_output/shaders_sha~<platform>-O<optimization level>[-bindless]/中的缓存

  • 如果更改需要重建所有.obj （如果.dshl文件 可能 生成的.hlsl与以前的版本不同，或者 stcode 生成已更改）

    • 在某些平台上，相应的 _MAKE4C('version') 必须 在 prog/tools/ShaderCompiler2/ver_obj_<platform>.<h or cpp>

    • 所有平台，SHADER_CACHE_COMMON_VER必须在prog/tools/ShaderCompiler2/shCacheVer.h 中更新

  • 如果您实现一些新功能或修复了某些内容，则prog/tools/ShaderCompiler2/globalConfig.h中的CompilerConfig::version必须更新。它仅用于日志记录。