Version: 2021.2
Shader keywords
Using shader keywords with the material Inspector

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.

How shader keywords are represented in C#

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

  • Local shader keywords represent the keywords that you declared in your shader or compute shader source files. When you enable or disable local shader keywords, they affect an individual shader or compute shader.
  • Global shader keywords act as overrides for local shader keywords. When you enable or disable global shader keywords, they can affect multiple shaders and compute shaders at the same time.

Local shader keywords

When you declare a shader keyword in a shader source file, Unity represents this in C# with a LocalKeyword struct. This is called a local shader keyword.

The isOverridable property of a LocalKeyword indicates whether the keyword was declared with a global or local scope in the source file. It is true if the keyword was declared with global scope, and false if it was declared with local scope. This value determines whether this local keyword can be overridden by a global keyword with the same name.

Unity stores all local shader keywords that affect a shader or compute shader in a LocalKeywordSpace struct. For a graphics shader, you can access this with Shader.keywordSpace. For a compute shader, you can access this with ComputeShader-keywordSpace.

Global shader keywords

In addition to the local shader keywords that you declared in your source files, Unity maintains a separate list of global shader keywords. Global shader keywords act as overrides for local shader keywords, and can affect multiple shaders and compute shaders at the same time.

Unity represents a global shader keyword with a GlobalKeyword struct.

Setting a global shader keyword can be convenient when you need to enable or disable the same shader keyword for many materials and compute shaders. However, it has the following potential downsides:

  • Setting the global state of keywords can lead to unintended consequences if shaders accidentally define a keyword with the same name. You can guard against this by declaring keywords with local scope, or by naming keywords in a way that reduces the likelihood of clashes.
  • When you create a new GlobalKeyword, Unity updates its internal mapping between global and local keyword space for all shaders and compute shaders loaded at this point. This can be a CPU-intensive operation. To reduce the impact of this operation, try to create all global keywords shortly after application startup, while your application is loading.

Determining whether a shader keyword is enabled or disabled

When a global and local shader keyword with the same name have different states, Unity uses the isOverridable property of a LocalKeyword to determine whether the keyword is enabled or disabled for an individual material or compute shader.

  • When isOverridable is true: If a global keyword with the same name exists and is enabled, Unity uses the state of the global keyword. Otherwise, Unity uses the state of the local keyword.
  • When isOverridable is false: Unity always uses the state of the local keyword.

Therefore, to understand whether a shader keyword is enabled or disabled for an individual material or compute shader, you must examine the state of the isOverridable property and the global and/or local keyword state.

This example demonstrates how to check whether Unity considers a keyword enabled or disabled for a material:

using UnityEngine;
using UnityEngine.Rendering;

public class KeywordExample : MonoBehaviour
{
    public Material material;

    void Start()
    {
        CheckShaderKeywordState();
    }

    void CheckShaderKeywordState()
    {
        // Get the instance of the Shader class that the material uses
        var shader = material.shader;

        // Get all the local keywords that affect the Shader
        var keywordSpace = shader.keywordSpace;

        // Iterate over the local keywords
        foreach (var localKeyword in keywordSpace.keywords)
        {
            // If the local keyword is overridable (i.e., it was declared with a global scope),
            // and a global keyword with the same name exists and is enabled,
            // then Unity uses the global keyword state
            if (localKeyword.isOverridable && Shader.IsKeywordEnabled(localKeyword.name))
            {
                Debug.Log("Local keyword with name of " + localKeyword.name + " is overridden by a global keyword, and is enabled");
            }
            // Otherwise, Unity uses the local keyword state
            else
            {
                var state = material.IsKeywordEnabled(localKeyword) ? "enabled" : "disabled";
                Debug.Log("Local keyword with name of " + localKeyword.name + " is " + state);
            }            
        }
    }
}

To check whether a local keyword is enabled for a graphics shader, use Material.IsKeywordEnabled or Material.enabledKeywords. For a compute shader, use ComputeShader.IsKeywordEnabled, or [ComputeShader.enabledKeywords].

To check whether a global keyword is enabled, use Shader.IsKeywordEnabled or Shader.enabledGlobalKeywords or ComputeShader.enabledKeywords.

Enabling and disabling shader keywords

To enable or disable a local shader keyword for a graphics shader, use Material.SetKeyword, Material.EnableKeyword, or Material.DisableKeyword. For a compute shader, use ComputeShader.SetKeyword, ComputeShader.EnableKeyword, or ComputeShader.DisableKeyword.

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

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

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.

Shader keywords
Using shader keywords with the material Inspector
Copyright © 2023 Unity Technologies
优美缔软件(上海)有限公司 版权所有
"Unity"、Unity 徽标及其他 Unity 商标是 Unity Technologies 或其附属机构在美国及其他地区的商标或注册商标。其他名称或品牌是其各自所有者的商标。
公安部备案号:
31010902002961