Version: 2022.1
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가지 키워드를 포함합니다.


참고: 셰이더 그래프에서는 용어가 다릅니다. 키워드 세트는 키워드, 세트에 포함된 키워드는 상태라고 합니다. 내부적으로 기능은 동일합니다. 즉, 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.

참고: 셰이더 소스 파일과 종속성에 이름이 같은 키워드가 존재하는 경우, 소스 파일의 키워드 범위가 종속성의 범위를 오버라이드합니다. 종속성은 폴백 커맨드를 통해 포함된 모든 셰이더를 구성하며, UsePass 커맨드를 통해 포함된 패스를 구성합니다.

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.

이 작업을 수행하는 방법은 다음과 같습니다.

셰이더 키워드 활성화 및 비활성화

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.

다음 두 가지 방법으로 셰이더 키워드를 활성화/비활성화할 수 있습니다.

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:

  • 기본적으로 Unity는 모든 그래픽스 셰이더 프로그램에 다음 키워드 세트를 추가합니다: STEREO_INSTANCING_ON, STEREO_MULTIVIEW_ON, STEREO_CUBEMAP_RENDER_ON, UNITY_SINGLE_PASS_STEREO. 에디터 스크립트를 사용하여 이러한 키워드를 스트리핑할 수 있습니다. 자세한 내용은 셰이더 배리언트 스트리핑을 참조하십시오.
  • 기본적으로 Unity는 스탠다드 셰이더에 다음 키워드 세트를 추가합니다: LIGHTMAP_ON, DIRLIGHTMAP_COMBINED, DYNAMICLIGHTMAP_ON, LIGHTMAP_SHADOW_MIXING, SHADOWS_SHADOWMASK. Graphics settings 창을 사용하여 이러한 키워드를 스트리핑할 수 있습니다.
  • 빌트인 렌더 파이프라인에서, 프로젝트가 서로 다른 티어 설정을 사용하는 경우 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는 해당 셰이더 키워드를 한도에서 한 번만 차감합니다.

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# 스크립트 함께 사용