Version: 2021.3
HLSL로 그래픽스 API 및 플랫폼 타게팅
셰이더 시맨틱

HLSL에서 셰이더 키워드 선언 및 사용

이 페이지는 HLSL 코드에서 셰이더 키워드를 사용하여 작업하는 방법에 대한 정보를 포함합니다. 셰이더 키워드에 대한 일반적인 안내는 셰이더 키워드를 참조하십시오. 셰이더 그래프에서 셰이더 키워드를 선언하고 사용하는 방법은 키워드를 참조하십시오.

HLSL 코드에서 셰이더 키워드를 선언하려면 #pragma 지시문을 사용하고, 셰이더 코드의 섹션이 셰이더 키워드의 상태에 종속됨을 나타내려면 #if 지시문을 사용하십시오. 일반 그래픽스 셰이더(표면 셰이더 포함)와 컴퓨트 셰이더에서 셰이더 키워드를 사용할 수 있습니다.

셰이더 키워드 선언

셰이더 키워드를 선언하려면 HLSL 코드에서 다음 #pragma 지시문 중 하나를 사용하십시오.

지시문 설명
#pragma multi_compile 키워드 세트를 선언합니다.

기본적으로 이러한 키워드는 전역 범위를 지니며, 모든 셰이더 단계에 영향을 미칩니다.

빌드 프로세스는 이 세트의 모든 키워드를 포함합니다.
#pragma shader_feature 키워드 세트를 선언하고, 또한 이러한 키워드 중 아무것도 활성화되지 않은 경우 배리언트를 컴파일하도록 컴파일러에 지시합니다.

기본적으로 이러한 키워드는 전역 범위를 지니며, 모든 셰이더 단계에 영향을 미칩니다.

빌드 프로세스는 이 세트의 키워드 중 빌드 시점에 사용 중인 키워드를 포함합니다.

#pragma multi_compile#pragma shader_feature의 차이점 및 각각을 언제 사용해야 하는지에 대한 내용은 셰이더 키워드를 참조하십시오

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 #pragma shader_feature.

이러한 지시문에 접미사를 추가하여 동작을 변경할 수 있습니다.

  • Add _local to indicate that a set of keywords has local scope and cannot be overridden by global keywords; otherwise, the keywords have global scope and can be overridden by global keywords. For more information, see Shader keywords: global and local scope.

    You can add this suffix to #pragma multi_compile, or #pragma shader_feature directives; for example, #pragma multi_compile_local, and #pragma shader_feature_local are valid.
  • Add _vertex, _fragment, _hull, _domain, _geometry, or _raytracing to indicate that a set of keywords only affects a given shader stage, which can reduce the number of unneeded shader variants. For more information, see Shader keywords: Stage-specific keywords.

    You can add these suffixes to #pragma multi_compile or #pragma shader_feature directives, either standalone or after a _local modifier; for example, #pragma multi_compile_vertex and #pragma shader_feature_local_fragment are valid.

또한 #pragma multi_compile의 "단축키" 배리에이션도 몇 가지 있는데, 이러한 배리에이션은 사전 정의된 키워드 세트를 추가합니다. 이에 대한 내용은 multi_compile 단축키를 참조하십시오.

키워드 세트 선언

키워드는 세트로 선언합니다. 세트는 상호 배타적인 키워드를 포함합니다.

키워드 세트를 선언하려면 뒤에 공백으로 구분된 키워드 리스트가 있는 #pragma multi_compile 또는 #pragma_shader_feature 지시문을 사용하십시오.

이 예제는 네 개의 키워드가 포함된 세트를 선언하는 방법을 나타냅니다.

# pragma multi_compile QUALITY_LOW QUALITY_MEDIUM QUALITY_HIGH QUALITY_ULTRA

내부적으로 이는 #define 지시문을 사용하여 작동합니다. Unity는 셰이더를 컴파일할 때 QUALITY_LOW가 정의된 배리언트 하나, QUALITY_MEDIUM이 정의된 배리언트 하나, QUALITY_HIGH가 정의된 배리언트 하나, QUALITY_ULTRA가 정의된 배리언트 하나를 포함한 네 가지 배리언트를 생성합니다. 런타임 시 Unity는 이 중 어느 키워드가 활성화되었는지에 따라 적절한 배리언트를 사용합니다.

#pragma shader_feature를 사용하여 키워드 세트를 선언하면 Unity는 해당 세트의 키워드 중 아무것도 정의되지 않은 배리언트도 컴파일합니다. 그러면 추가적인 키워드를 사용하지 않고도 동작을 정의할 수 있습니다. 키워드 수를 줄이는 것은 여러모로 유용합니다. 즉, Unity가 컴파일하는 총 배리언트 수를 줄여 빌드 시간과 런타임 성능을 모두 개선할 수 있습니다. 또한 셰이더가 사용하는 총 키워드 수를 줄여 셰이더 키워드 제한에 도달하는 일을 방지하며, 활성화/비활성화할 키워드 수가 감소하므로 C# 스크립트에서 키워드 상태를 관리하는 것도 더 간단해집니다.

이 예제는 키워드가 하나만 포함된 세트를 선언하는 방법을 나타냅니다.

# pragma shader_feature EXAMPLE_ON

#pragma multi_compile을 사용할 때 Unity가 키워드가 하나만 포함된 세트를 선언하도록 지시할 수도 있습니다. 이를 수행하려면 다음과 같이 “빈” 키워드와 함께 언더바(_)가 하나 이상 있는 이름을 세트에 추가하십시오.

# pragma multi_compile __ EXAMPLE_ON

여러 개의 키워드 세트 선언

여러 개의 키워드 세트를 선언하여 서로 다른 기능을 나타낼 수 있습니다. 이를 수행하려면 여러 개의 #pragma multi_compile 또는 #pragma_shader_feature 지시문을 사용하십시오.

이 예제는 키워드가 네 개 포함된 세트 하나와, 키워드가 세 개 포함된 또 다른 세트 하나를 선언하는 방법을 나타냅니다.

# pragma multi_compile QUALITY_LOW QUALITY_MEDIUM QUALITY_HIGH QUALITY_ULTRA
# pragma multi_compile COLOR_RED COLOR_GREEN COLOR_BLUE

제한 사항

키워드 세트를 선언하는 방법에는 몇 가지 제한이 있습니다.

  • 같은 세트에 같은 키워드를 두 번 이상 포함해서는 안 됩니다. 단, 다른 세트에서 같은 키워드를 선언하는 것은 가능합니다.
  • 셰이더 프로그램에서 같은 키워드 세트를 두 번 이상 선언할 수는 없습니다.
  • 셰이더가 사용할 수 있는 키워드 수에는 제한이 있습니다. 셰이더 소스 파일 및 그 종속성에서 선언된 모든 키워드는 이 제한에 포함됩니다. 자세한 내용은 셰이더 키워드 제한을 참조하십시오.

셰이더 키워드 사용

특정 셰이더 키워드가 활성화된 경우에만 사용되는 코드를 컴파일하려면 다음과 같이 #if 지시문을 사용하십시오.

// Declare a set of keywords
# pragma multi_compile QUALITY_LOW QUALITY_MEDIUM QUALITY_HIGH QUALITY_ULTRA


# if QUALITY_ULTRA
// Code here is compiled for variants that are used when the keyword QUALITY_ULTRA is enabled
# endif

Unity에서 #if 지시문은 표준 HLSL과 동일하게 작동합니다. #if 지시문에 대해 자세히 알아보려면 HLSL 문서인 [#if, # elif, # else 및 # endif 지시문](https://docs.microsoft.com/ko-kr/windows/win32/direct3dhlsl/dx-graphics-hlsl-appendix-pre-if)을 참조하십시오.

또한 #pragma require#pragma target 지시문은 키워드를 파라미터로 가져와 특정 키워드가 활성화된 경우 배리언트에만 적용되게 할 수 있습니다. 자세한 내용은 HLSL의 셰이더 모델 타게팅 및 GPU 기능을 참조하십시오.

multi_compile 단축키

Unity는 셰이더 키워드 선언을 위한 여러 "단축키" 표기법을 제공합니다.

다음의 단축키는 빌트인 렌더 파이프라인의 광원, 그림자 및 라이트매핑과 관련됩니다.

  • multi_compile_fwdbase는 DIRECTIONAL LIGHTMAP_ON DIRLIGHTMAP_COMBINED DYNAMICLIGHTMAP_ON SHADOWS_SCREEN SHADOWS_SHADOWMASK LIGHTMAP_SHADOW_MIXING LIGHTPROBE_SH 키워드 세트를 추가합니다. PassType.ForwardBase가 이러한 배리언트를 필요로 합니다.
  • multi_compile_fwdbasealpha는 DIRECTIONAL LIGHTMAP_ON DIRLIGHTMAP_COMBINED DYNAMICLIGHTMAP_ON LIGHTMAP_SHADOW_MIXING VERTEXLIGHT_ON LIGHTPROBE_SH 키워드 세트를 추가합니다. PassType.ForwardBase가 이러한 배리언트를 필요로 합니다.
  • multi_compile_fwdadd는 POINT DIRECTIONAL SPOT POINT_COOKIE DIRECTIONAL_COOKIE 키워드 세트를 추가합니다. PassType.ForwardAdd가 이러한 배리언트를 필요로 합니다.
  • multi_compile_fwdadd_fullshadows는 POINT DIRECTIONAL SPOT POINT_COOKIE DIRECTIONAL_COOKIE SHADOWS_DEPTH SHADOWS_SCREEN SHADOWS_CUBE SHADOWS_SOFT SHADOWS_SHADOWMASK LIGHTMAP_SHADOW_MIXING 키워드 세트를 추가합니다. multi_compile_fwdadd와 동일하지만, 광원이 실시간 그림자를 가질 수 있는 기능을 추가합니다.
  • multi_compile_lightpass는 POINT DIRECTIONAL SPOT POINT_COOKIE DIRECTIONAL_COOKIE SHADOWS_DEPTH SHADOWS_SCREEN SHADOWS_CUBE SHADOWS_SOFT SHADOWS_SHADOWMASK LIGHTMAP_SHADOW_MIXING 키워드 세트를 추가합니다. 실질적으로 라이트 프로브 외 실시간 광원과 그림자와 관련된 모든 기능을 위한 포괄적 단축키입니다.
  • multi_compile_shadowcaster는 SHADOWS_DEPTH SHADOWS_CUBE 키워드 세트를 추가합니다. PassType.ShadowCaster가 이러한 배리언트를 필요로 합니다.
  • multi_compile_shadowcollector는 SHADOWS_SPLIT_SPHERES SHADOWS_SINGLE_CASCADE 키워드 세트를 추가합니다. 또한 이러한 키워드 없이도 배리언트를 컴파일합니다. 이러한 배리언트는 스크린 공간 그림자에 필요합니다.
  • multi_compile_prepassfinal는 LIGHTMAP_ON DIRLIGHTMAP_COMBINED DYNAMICLIGHTMAP_ON UNITY_HDR_ON SHADOWS_SHADOWMASK LIGHTPROBE_SH 키워드 세트를 추가합니다. 또한 이러한 키워드 없이도 배리언트를 컴파일합니다. PassType.LightPrePassFinalPassType.Deferred가 이러한 배리언트를 필요로 합니다.

다음 단축키는 기타 설정과 관련됩니다.

  • multi_compile_particles는 빌트인 파티클 시스템에 관련된 SOFTPARTICLES_ON 키워드를 추가합니다. 또한 이 키워드 없이도 배리언트를 컴파일합니다. 자세한 내용은 빌트인 파티클 시스템을 참조하십시오.
  • multi_compile_fog는 안개에 관련된 FOG_LINEAR, FOG_EXP, FOG_EXP2 키워드 세트를 추가합니다. 또한 이러한 키워드 없이도 배리언트를 컴파일합니다. Graphics settings 창에서 이 동작을 컨트롤할 수 있습니다.
  • multi_compile_instancing은 인스턴싱에 관련된 키워드를 추가합니다. 셰이더가 절차적 인스턴싱을 사용하는 경우 이 단축키는 INSTANCING_ON PROCEDURAL_ON 키워드 세트를 추가합니다. 이외의 경우에는 INSTANCING_ON 키워드를 추가합니다. 또한 이러한 키워드 없이도 배리언트를 컴파일합니다. Graphics settings 창에서 이 동작을 컨트롤할 수 있습니다.

이러한 단축키의 대다수는 여러 개의 키워드를 포함합니다. 프로젝트에 필요하지 않은 경우에는 #pragma skip_variants를 사용하여 그중 일부를 제거할 수 있습니다. 예를 들면 다음과 같습니다.

# pragma multi_compile_fwdadd
# pragma skip_variants POINT POINT_COOKIE

컴파일러에 다른 지시문에서 POINT 또는 POINT_COOKIE 키워드를 제거하도록 지시합니다.

HLSL로 그래픽스 API 및 플랫폼 타게팅
셰이더 시맨틱