Using shader keywords with C# scripts

At runtime, you can enable or disable shader keywords. When you enable or disable a shader keyword, Unity uses the appropriate shader variant for rendering.

Changing shader variants at runtime can impact performance. If a change in keywords requires a variant to be used for the first time, it can lead to hitches while the graphics driver prepares the shader program. This can be a particular problem for large or complex shaders, or if a global keyword state change affects multiple shaders. To avoid this, ensure that you consider keyword variants in your shader loading and prewarming strategy. For more information, see Shader loading.

Local and global shader keywords

In Unity, there are local shader keywords and global shader keywords:

• Local shader keywords affect an individual shader or compute shader.
• Global shader keywords affect multiple shaders and compute shaders at the same time.

You set the scope of a shader keyword when you declare it. For more information, see Shader keywords: global and local scope.

Enabling, disabling, and checking the state of global shader keywords

To enable or disable a global shader keyword, use Shader.EnableKeyword or Shader.DisableKeyword.

To enable or disable a global keyword with a Command Buffer, use CommandBuffer.EnableKeyword, or CommandBuffer.DisableKeyword.

To check the state, use [Shader.IsKeywordEnabled].

Enabling, disabling, and checking the state of local shader keywords

To enable or disable a local shader keyword for a graphics shader, use Material.EnableKeyword or Material.DisableKeyword. To check the state, use Material.IsKeywordEnabled.

To enable or disable a local shader keyword for a compute shader, use ComputeShader.EnableKeyword or ComputeShader.DisableKeyword. To check the state, use [ComputeShader.IsKeywordEnabled].

Managing sets of keywords at runtime

When you author your shader, you declare keywords in sets. A set contains mutually-exclusive keywords.

At runtime, Unity has no concept of these sets. It allows you to enable or disable any keyword independently, and enabling or disabling a keyword has no effect on the state of any other keyword. This means that it is possible to enable multiple keywords from the same set, or disable all the keywords in a set.

When more than one keyword in a set is enabled, or no keywords in a set are enabled, Unity chooses a variant that it considers a “good enough” match. There is no guarantee about what exactly happens, and it can lead to unintended results. It is best to avoid this situation by managing keyword state carefully.