Version: 2020.3
HLSL in Unity
Shader compilation: targeting shader models and GPU features

Shader compilation: pragma directives

In HLSL, you can use preprocessor directives to tell the compiler how to compile a shaderA program that runs on the GPU. More info
See in Glossary
program. Pragma directives are a type of preprocessor directive. This page contains information about pragma directives that you can use in your shader source code.

For general information on preprocessor directives in HLSL, see the Microsoft documentation: Preprocessor directives (HLSL).

Using pragma directives

Put pragma directives inside an HLSL code block, in your shader source file.

By default, Unity does not support pragma directives in include files. If you enable the Caching Preprocessor in your Editor Settings, you can use the #include_with_pragmas preprocessor directive. This directive lets you put pragma directives in include files. This can be especially useful for enabling or disabling shader debug symbols for multiple files.

Supported pragma directives

Shader stages

Use these pragma directives to tell the compiler which parts of your shader code to compile as different shader stages.

An HLSL snippet must contain at least a vertex program and a fragment program, so #pragma vertex and #pragma fragment directives are required.

Statement Function
#pragma vertex name Compile function name as the vertex shaderA program that runs on each vertex of a 3D model when the model is being rendered. More info
See in Glossary
.
#pragma fragment name Compile function name as the fragment shader.
#pragma geometry name Compile function name as DX10 geometry shader. This option automatically turns on #pragma target 4.0 as described in the table below.
#pragma hull name Compile function name as DX11 hull shader. This option automatically turns on #pragma target 5.0, as described in the table below.
#pragma domain name Compile function name as DX11 domain shader. This option automatically turns on #pragma target 5.0, as described in the table below.

Shader variants and keywords

Use these pragma directives to tell the shader compiler how to handle shader variants and keywords.

Statement Function
#pragma multi_compile ... Create shader variants for a given keyword. Unused variants of multi_compile shaders are included in the game build. For more information, see Shader variants and keywords.
#pragma multi_compile_local ... This statement is similar to multi_compile, but enumerated keywords are local. For more information, see Shader variants and keywords.
#pragma shader_feature ... Create shader variants for a given keyword. Unused variants of shader_feature shaders are not included in the game build. For more information, see Shader variants and keywords.
#pragma shader_feature_local ... This statement is similar to shader_feature, but enumerated keywords are local. For more information, see Shader variants and keywords.

Shader model and GPU features

Use these pragma directives to tell the compiler that your shader targets a specific shader model, or requires specific GPU features.

Statement Function
#pragma target name Which shader model to compile this shader program for. For more information, see Shader compilation: targeting shader models and GPU features.
#pragma require feature ... Which GPU features the shader program needs. For more information, see Shader compilation: targeting shader models and GPU features.

Graphics APIs

Use these pragma directives to tell the compiler to compile your shader for specific graphics APIs.

Statement Function
#pragma only_renderers space separated names Compile this shader program only for given graphics APIs. For more information, see Shader compilation: targeting graphics APIs.
#pragma exclude_renderers space separated names Do not compile this shader program for given graphics APIs. For more information, see Shader compilation: targeting graphics APIs.

Other pragma directives

Statement Function
#pragma enable_d3d11_debug_symbols Generates shader debug symbols and/or disables optimizations. Use this for debugging shader code in an external tool.

For Vulkan, DirectX 11 and 12, and supported console platforms, Unity generates debug symbols and disables optimizations.

For Metal and OpenGL, you can already debug shaders by default. When you use this pragma directive, Unity disables optimizations.

Warning: Using this directive results in an increased file size and reduced shader performance. When you have finished debugging your shaders and you are ready to make a final build of your application, remove this line from your shader source code and recompile the shaders.
#pragma hardware_tier_variants renderer name Generate multiple shader hardware variants of each shader the system compiles for each hardware tier that can run the selected renderer.
This statement is only supported in the Built-in Render Pipeline.
#pragma hlslcc_bytecode_disassembly Embed disassembled HLSLcc bytecode into a translated shader.
#pragma disable_fastmath Enable precise IEEE 754 rules involving NaN handling. This currently only affects the Metal platform.
#pragma glsl_es2 Set in a GLSL shader to generate a GLSL ES 1.0(OpenGL ES 2.0), even when the shader target is OpenGL ES 3.
#pragma editor_sync_compilation Force synchronous compilation. This affects the Unity Editor only. For more information, see Asynchronous Shader compilation.
#pragma enable_cbuffer Emit cbuffer(name) when using CBUFFER_START(name) and CBUFFER_END macros from HLSLSupport even if the current platform does not support constant buffers.

Unused pragma directives

The following compilation directives don’t do anything and can be safely removed:

  • #pragma glsl
  • #pragma glsl_no_auto_normalization
  • #pragma profileoption
  • #pragma fragmentoption
HLSL in Unity
Shader compilation: targeting shader models and GPU features