Version: 2022.2
言語: 日本語
Check how many shader variants you have
C# スクリプトによるシェーダーキーワードの使用


Shader keywords allow you to use conditional behavior in your shader code. You can create shaders that share some common code, but have different functionality when a given keyword is enabled or disabled.

You can use shader keywords with dynamic branching, or with Shader variants. Before you use shader keywords, it is important to understand how these techniques work, and which one is right for your project.



Declaring shader keywords


例えば、以下のセットには 3 つのキーワードが含まれています。


ノート: Shader Graph では、用語が異なります。キーワードのセットを キーワード と呼び、セット内のキーワードを ステート と呼びます。Unity はこれらを同じようにコンパイルし、C# スクリプトなどと同じように扱うことができる、など内部的には機能は同じです。

The way that you declare shader keywords affects a number of things:

  • The type affects whether and how Unity uses the keywords to generate shader variants, or whether it uses them for dynamic branching.
  • The scope affects whether the keywords are local or global. This determines their behavior at runtime.
  • The stage affects which shader stage the keywords affect (where applicable).

Definition type: “multi compile”, “shader feature”, or “dynamic branch”

When you declare a set of keywords, you choose whether to use them with shader variants or with dynamic branching. If you choose shader variants, you must also choose how Unity defines the keywords internally; this affects the number of variants that Unity compiles.

  • “dynamic branch”: Use this to create a set of keywords for use with dynamic branching. Internally, Unity uses these keywords to create uniform variables.
  • “multi compile” or “shader feature”: Use this to create a set of keywords for use with shader variants. Internally, Unity uses these keyword to create #define preprocessor directives.
    • “multi compile” declares a set of keywords for use with shader variants.

      Unity compiles shader variants for all keywords in the set.
    • “shader feature” declares a set of keywords for use with shader variants, and also instructs the compiler to compile variants where none of these keywords are enabled.

      Unity examines the state of your project at build time, and only compiles variants for keywords that are in use. A keyword is in use if a material that is included in the build has that keyword enabled.

Whether to choose “multi compile” or “shader feature” depends on how you use the keywords. If you use the keywords to configure materials in your project and do not change their value from C# scripts at runtime, then you should use “shader feature” to reduce the number of shader keywords and variants in your project. If you enable and disable keywords at runtime using C# scripts, then you should use “multi compile” to prevent variants being stripped in error. For more information on shader stripping, see Shader variant stripping.

Note: If you add a shader to the list of Always Included Shaders in the Graphics settings window, Unity includes all keywords from all sets in the build, even if they were declared with “shader feature”.

To set this value, see the following documentation:

Local or global scope

When you declare a set of keywords, you choose whether the keywords in the set have local or global scope. This determines whether you can override the state of this keyword at runtime using a global shader keyword.

By default, you declare keywords with global scope. This means that you can override the state of this keyword at runtime using a global shader keyword. If you declare keywords with local scope, this means that you cannot override the state of this keyword at runtime using a global shader keyword. For more information and a code example, see Using shader keywords with C# scripts.

Note: If a keyword with the same name exists in a shader source file and its dependencies, the scope of the keyword in the source file overrides the scope in the dependencies. Dependencies comprise all Shaders that are included via the Fallback command, and Passes that are included via the UsePass command.

To set this value, see the following documentation:

Stage-specific keywords

デフォルトでは、Unity はシェーダーの各ステージに対してキーワードバリアントを生成します。例えば、シェーダーに頂点ステージとフラグメントステージが含まれている場合、Unity は頂点シェーダープログラムとフラグメントシェーダープログラムの両方について、すべてのキーワードの組み合わせに対するバリアントを生成します。また、あるキーワードセットがどちらか一方のステージでしか使われていない場合は、もう一方のステージでも同じバリアントが生成されます。Unity は、同じバリアントを自動的に識別し、複製 します。そのため、ビルドサイズは増加しませんが、それでもコンパイル時間の無駄、シェーダーのロード時間の増加、ランタイムのメモリ使用量の増加につながります。

To avoid this problem, when you declare a set of keywords in a hand-coded shader, you can instruct Unity to compile them only for a given shader stage. You are then responsible for ensuring that the keywords are only used in the specified shader stages.

Note: The following graphics APIs do not fully support stage-specific keywords. In OpenGL and Vulkan, at compile time, Unity automatically converts all stage-specific keyword directives to regular keyword directives. In Metal, any keyword targeting vertex stages also affects tessellation stages, and vice versa.

To set this value:

Making behavior conditional with shader keywords

You can use shader keywords to make parts of your shader conditional, so that certain behaviors only execute when a given keyword is in a given state.


Enabling and disabling shader keywords

You can enable or disable shader keywords. When you enable or disable a shader keyword, the shader displays the appropriate conditional behavior. Depending on whether the keyword work with shader variants or dynamic branching, this means that either Unity renders the appropriate shader variant, or the GPU executes the appropriate branch.

シェーダーキーワードの有効化無効化には 2 つの方法があります。

Unity の定義済みシェーダーキーワード

Unity uses predefined sets of shader keywords to generate shader variants that enable common functionality.

Unity adds the following sets of shader variant keywords at compile time:

  • By default, Unity adds this set of keywords to all graphics shader programs: STEREO_INSTANCING_ON, STEREO_MULTIVIEW_ON, STEREO_CUBEMAP_RENDER_ON, UNITY_SINGLE_PASS_STEREO. You can strip these keywords using an Editor script. For more information, see Shader variant stripping.
  • デフォルトでは、Unity はスタンダードシェーダーに LIGHTMAP_ON、DIRLIGHTMAP_COMBINED、 DYNAMICLIGHTMAP_ON、LIGHTMAP_SHADOW_MIXING、SHADOWS_SHADOWMASK のキーワードセットを加えます。これらのキーワードは、Graphics 設定 ウィンドウを使って取り除くことができます。
  • ビルトインレンダーパイプラインにおいて、プロジェクトに互いに異なる ティア設定 が使用されている場合、Unity は UNITY_HARDWARE_TIER1、UNITY_HARDWARE_TIER2、UNITY_HARDWARE_TIER3 のキーワードのセットをすべてのグラフィックスシェーダーに加えます。詳細については、グラフィックスティア: グラフィックスティアとシェーダーバリアント を参照してください。


Unity can use up to 4,294,967,294 global shader keywords. Individual shaders and compute shaders can use up to 65,534 local shader keywords. These totals include keywords used for variants, and keywords used for dynamic branching.

Every keyword declared in the shader source file and its dependencies count towards this limit. Dependencies include Passes that the shader includes with UsePass, and fallbacks.

Unity が同じ名前のシェーダーキーワードに複数回遭遇する場合は、制限数に 1 回カウントされます。

If a shader uses more than 128 keywords in total, it incurs a small runtime performance penalty; therefore, it is best to keep the number of keywords low. Unity always reserves 4 keywords per shader.

Check how many shader variants you have
C# スクリプトによるシェーダーキーワードの使用