When you use a keyword, you can choose how Unity compiles the shaderA program that runs on the GPU. More info
See in Glossary code. The options are:
To use dynamic branching, use #pragma dynamic_branch to declare keywords. For example:
#pragma dynamic_branch RED GREEN
...
if (RED)
{
// Output red
}
else if (GREEN)
{
// Output green
}
At compile time, Unity converts each keyword into a uniform integer variable in the compiled shader code, which can have a value of either 0 or 1. At runtime, for each draw call, Unity sends the state of each keyword integer to the GPU.
You can use dynamic_branch if your shaders run on a fast GPU, and don’t have asymmetric code branches where one branch is longer or more complex than the other.
To use shader variants, use #pragma multi_compile or #pragma shader_feature to declare keywords. For example:
#pragma multi_compile RED GREEN
if (RED)
{
// Output red
}
else if (GREEN)
{
// Output green
}
At compile time, Unity splits the previous code into 2 separate but similar shader files called shader variants. One file contains the code that outputs red, and the other contains the code that outputs green. Each draw call, Unity sends the GPU the correct shader variant.
If you only need a shader to branch based on material properties, use shader_feature. Unity compiles shader variants for keyword combinations that materials in your build use, and removes other shader variants. This keeps build times low and file sizes small.
Note: At runtime, if you use a keyword combination you didn’t use at build time, Unity tries to find the shader variant that closely matches. You can highlight missing shaders at runtime instead, or include a shader variant collection in the list of preloaded shaders.
If you need to use a C# script to make the shader branch at runtime, use multi_compile. Unity compiles shader variants regardless of whether they’re used by materials in your build. For example, you can use multi_compile to give users dynamic control over whether fog appears in a game.
Important: If you use multi_compile, Unity might spend a long time compiling, because each combination of keywords becomes a shader variant. For example, if you have 8 keyword sets with 3 keywords each, Unity might compile over 6,000 shader variants. Use shader_feature instead, or use different ways to strip shader variants.
Did you find this page useful? Please give it a rating:
Thanks for rating this page!
What kind of problem would you like to report?
Thanks for letting us know! This page has been marked for review based on your feedback.
If you have time, you can provide more information to help us fix the problem faster.
Provide more information
You've told us this page needs code samples. If you'd like to help us further, you could provide a code sample, or tell us about what kind of code sample you'd like to see:
You've told us there are code samples on this page which don't work. If you know how to fix it, or have something better we could use instead, please let us know:
You've told us there is information missing from this page. Please tell us more about what's missing:
You've told us there is incorrect information on this page. If you know what we should change to make it correct, please tell us:
You've told us this page has unclear or confusing information. Please tell us more about what you found unclear or confusing, or let us know how we could make it clearer:
You've told us there is a spelling or grammar error on this page. Please tell us what's wrong:
You've told us this page has a problem. Please tell us more about what's wrong:
Thank you for helping to make the Unity documentation better!
Your feedback has been submitted as a ticket for our documentation team to review.
We are not able to reply to every ticket submitted.