To mark parts of your shaderA program that runs on the GPU. More info
See in Glossary code conditional based on whether you enable or disable a shader keyword in a set, use an HLSL if statement.
For example:
#pragma multi_compile QUALITY_LOW QUALITY_MED QUALITY_HIGH
if (QUALITY_LOW)
{
// code for low quality setting
}
You can enable and disable keywords using the Inspector or C# scripting.
What Unity does with your shader code depends on which shader directive you use.
If you use dynamic_branch, Unity creates a uniform integer variable for each keyword. When you enable a keyword, Unity sets the integer for that variable to 1, and your GPU switches to using the code in the if statement for that keyword. This is dynamic branching.
If you use shader_feature or multi_compile, Unity creates separate shader variantsA verion of a shader program that Unity generates according to a specific combination of shader keywords and their status. A Shader object can contain multiple shader variants. More info
See in Glossary for each keyword state. Each variant contains the code from an if branch for that keyword. When you enable a keyword, Unity sends the matching variant to your GPU. This is static branching.
Refer to Conditionals in shaders for more information about when to use which shader directive.
For each keyword in a set, Unity automatically adds a _KEYWORD_DECLARED keyword. For example, if you declare a QUALITY_LOW keyword, Unity adds a QUALITY_LOW_KEYWORD_DECLARED keyword.
You can use this to check if a keyword exists, regardless of whether it’s enabled or disabled.
For example:
#pragma multi_compile QUALITY_LOW QUALITY_MED QUALITY_HIGH
#if defined(QUALITY_LOW_KEYWORD_DECLARED)
{
// The QUALITY_LOW keyword exists
}
To execute code when all keywords in a set are disabled, Unity must create an additional shader variant or uniform integer for that state.
If you use shader_feature or dynamic_branch to create a single keyword, Unity automatically creates an additional variant or uniform integer. For example:
// Creates a variant for when FEATURE_1_ON is enabled, and another for when FEATURE_1_ON is disabled.
#pragma shader_feature FEATURE_1_ON
// Creates a uniform integer for when FEATURE_2_ON is enabled, and another for when FEATURE_2_ON is disabled.
#pragma dynamic_branch FEATURE_2_ON
If you use shader_feature or dynamic_branch to create a set of two or more keywords, or you use multi_compile, add _ when you declare a keyword set so that Unity creates an additional variant or uniform integer. For example:
// Creates 5 shader variants, including one for when RED, GREEN, BLUE, and WHITE are all disabled.
#pragma shader_feature _ RED GREEN BLUE WHITE
// Creates 2 shader variants, including one for when FEATURE_3_ON is disabled.
#pragma multi_compile _ FEATURE_3_ON
// Creates 4 uniform integers, including one for when QUALITY_LOW, QUALITY_MED, and QUALITY_HIGH are all disabled.
#pragma dynamic_branch _ QUALITY_LOW QUALITY_MED QUALITY_HIGH
You can also use the following HLSL pre-processor directives to create conditional code:
Using these instead of if makes it more difficult to change the #pragma keyword directive later. For example, if you need to reduce the number of shader variants, it’s more difficult to change to dynamic_branch.