HLSL语言的编译指令#include_with_pragmas的具体用法

请尊重原作者的工作，转载时请务必注明转载自：www.xionggf.com

#include_with_pragmas 在 HLSL 语言中的作用

#include_with_pragmas 是 Unity Shader 编译器提供的一个扩展指令，用于 在包含 HLSL 头文件 (.hlsl) 时，同时解析其中的 #pragma 指令。这与普通的 #include 不同，普通 #include 只会包含代码，但不会处理 #pragma 相关的指令。

基本语法

#include_with_pragmas "MyShaderHeader.hlsl"

与普通的 #include 相比：

• #include 不会解析 #pragma multi_compile 等编译指令。
• #include_with_pragmas 会解析 #pragma 指令，确保 .hlsl 文件中的 #pragma 也会影响 Shader 变体编译。

使用示例

示例 1：在 .hlsl 文件中定义 multi_compile

MyShaderHeader.hlsl

#pragma multi_compile _ FEATURE_ENABLED
float4 CustomFunction() { return float4(1, 0, 0, 1); }

MyShader.shader

Shader "Example/Shader"
{
    SubShader
    {
        Pass
        {
            HLSLPROGRAM
            #include_with_pragmas "MyShaderHeader.hlsl" // 解析 MyShaderHeader.hlsl 里的 #pragma
            ENDHLSL
        }
    }
}

示例 2：对比 #include 与 #include_with_pragmas

错误的方式（使用 #include，不会解析 #pragma）

HLSLPROGRAM
#include "MyShaderHeader.hlsl"  // 这里不会解析 `#pragma multi_compile`
ENDHLSL

问题：如果 MyShaderHeader.hlsl 里面有 #pragma multi_compile _ FEATURE_ENABLED，它不会生效，因为 Unity 的 Shader 编译器 不会在普通 #include 里解析 #pragma 指令。

正确的方式（使用 #include_with_pragmas）

HLSLPROGRAM
#include_with_pragmas "MyShaderHeader.hlsl"  // 这里会解析 `#pragma multi_compile`
ENDHLSL

效果：Unity 会正确解析 #pragma multi_compile _ FEATURE_ENABLED，并生成 Shader 变体。

#include_with_pragmas 的应用场景

1. 在多个 Shader 共享 #pragma multi_compile 变体时

   • 避免在每个 Shader 文件中重复写 #pragma multi_compile。
   • 只需在一个 .hlsl 文件中定义 #pragma，然后用 #include_with_pragmas 引入。

2. 模块化 Shader 结构

   • 例如，将不同的 Shader 功能模块拆分到多个 .hlsl 文件中，每个模块包含自己的 #pragma，这样主 Shader 只需要 #include_with_pragmas，避免重复编写 #pragma 规则。

3. 防止 unknown pragma ignored 警告

   • 如果 #pragma multi_compile 直接放在 .hlsl 里，而使用的是 #include，可能会触发 unknown pragma ignored 警告。
   • 通过 #include_with_pragmas，可以确保 Unity 解析 #pragma 语句，不会被忽略。

总结

• #include_with_pragmas 和 #include 的区别：
  • #include 不会解析 #pragma 指令。
  • #include_with_pragmas 会解析 #pragma，确保 Shader 变体正常生效。
• 适用于共享 #pragma 规则的情况，如 multi_compile、shader_feature 等，减少重复代码。
• 避免 unknown pragma ignored 警告，确保 multi_compile 和 shader_feature 变体能正确解析。

如果你的 .hlsl 里有 #pragma 语句，推荐使用 #include_with_pragmas 来确保它们正确生效！