When a global and local shaderA program that runs on the GPU. More info
See in Glossary 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. isOverridable
is true if the keyword was declared with global scope, and false
if it was declared with local scope.
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.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.EnableKeyword. For a compute shader, use ComputeShader.IsKeywordEnabled, or ComputeShader.EnableKeyword.
To check whether a global keyword is enabled, use Shader.IsKeywordEnabled or Shader.EnableKeyword or ComputeShader.enabledKeywords.
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 .
Note: When you enable or disable keywords that work with shader variants, Unity uses different shader variants. 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, if you use keywords with shader variants, ensure that you consider keyword variants in your shader loading and prewarming strategy. For more information, see Shader loading.
In Unity, you can use shader keywords with shader variants, or you can use them with dynamic branching. You decide when you declare the keywords.
The isDynamic property of a LocalKeyword
indicates whether the keyword was declared for use with dynamic branching in the shader source file. It is true
if the keyword was declared for use with dynamic branching, and false
if it was declared for use with 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.