Targeting shader models and GPU features in HLSL

You can use #pragma directives to indicate that a shader requires certain GPU features. At runtime, Unity uses this information to determine whether a shader program is compatible with the current hardware.

You can specify individual GPU features with the #pragma require directive, or specify a shader model with the #pragma target directive. A shader model is a shorthand for a group of GPU features; internally, it is the same as a #pragma require directive with the same list of features.

It is important to correctly describe the GPU features that your shader requires. If your shader uses features that are not included in the list of requirements, this can result in either compile time errors, or in devices failing to support shaders at runtime.

Default behavior

By default, Unity compiles shaders with #pragma require derivatives, which corresponds to #pragma target 2.5.

Special requirements for shader stages

If your shader defines certain shader stages, Unity automatically adds items to the list of requirements.

• If a shader defines a geometry stage (with #pragma geometry), Unity automatically adds geometry to the list of requirements.
• If a shader defines a tessellation stage (with #pragma hull or #pragma domain), Unity automatically adds tessellation to the list of requirements.

If the list of requirements (or the equivalent target value) does not already include these values, Unity displays a warning message when it compiles the shader, to indicate that it has added these requirements. To avoid seeing this warning message, explicitly add the requirements or use an appropriate target value in your code.

Specifying GPU features or a shader model

To specify required features, use the #pragma require directive, followed by a list of space-delimited values. For example:

#pragma require integers mrt8

You can also use the #pragma require directive followed by a colon and a list of space-delimited shader keywords. This means that the requirement applies only to variants that are used when any of the given keywords are enabled.

例如：

#pragma require integers mrt8 : EXAMPLE_KEYWORD OTHER_EXAMPLE_KEYWORD

You can use multiple #pragma require lines. In this example, the shader requires integers in all cases, and mrt8 if EXAMPLE_KEYWORD is enabled.

#pragma require integers
#pragma require integers mrt8 : EXAMPLE_KEYWORD

To specify a shader model, use #pragma target directive. For example:

#pragma target 4.0

You can also use the #pragma target directive followed by a list of space-delimited shader keywords. This means that the requirement applies only to variants that are used when any of the given keywords are enabled.

例如：

#pragma target 4.0 EXAMPLE_KEYWORD OTHER_EXAMPLE_KEYWORD

Note: The syntax for specifying keywords for #pragma require and #pragma target is slightly different. When you specify keywords for #pragma require, you use a colon. When you specify keywords for #pragma target, you do not use a colon.

List of ‘#pragma target’ values

Here is the list of shader models that Unity uses, and the combination of #pragma require values that each corresponds to.

Note: Unity’s shader models are similar to DirectX shader models and OpenGL version requirements, but they do not correspond exactly. Read the descriptions carefully to ensure that you understand the differences.

值	描述	支持	Equivalent #pragma require values
2.0	Equivalent to DirectX shader model 2.0. Limited amount of arithmetic and texture instructions; 8 interpolators; no vertex texture sampling; no derivatives in fragment shaders; no explicit LOD texture sampling.	Works on all platforms supported by Unity.	无
2.5	Almost the same as 3.0, but with only 8 interpolators, and no explicit LOD texture sampling.	DirectX 11 feature level 9+ OpenGL 3.2+ Vulkan Metal	derivatives
3.0	Equivalent to DirectX shader model 3.0. .	DirectX 11 feature level 10 + OpenGL 3.2+ OpenGL ES 3.0+ Vulkan Metal	Everything in 2.5, plus: interpolators10 samplelod fragcoord
3.5	Equivalent to OpenGL ES 3.0.	DirectX 11 feature level 10+ OpenGL 3.2+ OpenGL ES 3+ Vulkan Metal	Everything in 3.0, plus: interpolators15 mrt4 integers 2darray instancing
4.0	Equivalent to DirectX shader model 4.0, but without the requirement to support 8 MRTs.	DirectX 11 feature level 10+ OpenGL 3.2+ OpenGL ES 3.1+AEP Vulkan Metal (if no geometry stage is defined)	Everything in 3.5, plus: geometry
4.5	Equivalent to OpenGL ES 3.1.	DirectX 11 feature level 11+ OpenGL 4.3+ OpenGL ES 3.1 Vulkan Metal	Everything in 3.5, plus: compute randomwrite msaatex
4.6	Equivalent to OpenGL 4.1. This is the highest OpenGL level supported on a Mac.	DirectX 11 feature level 11+ OpenGL 4.1+ OpenGL ES 3.1+AEP Vulkan Metal (if no geometry stage is defined, and no hull or domain stage is defined)	Everything in 4.0, plus: cubearray tesshw tessellation msaatex
5.0	Equivalent to DirectX shader model 5.0, but without the requirement to support 32 interpolators or cubemap arrays.	DirectX 11 feature level 11+ OpenGL 4.3+ OpenGL ES 3.1+AEP Vulkan Metal (if no geometry stage is defined, and no hull or domain stage is defined)	Everything in 4.0, plus: compute randomwrite msaatex tesshw tessellation

For information on shader model support for console platforms, see the platform-specific documentation.

注意：

• In the DirectX definitions, shader model 4.0 includes mrt8, and shader model 5.0 includes interpolators32 and cubearray. Unity does not include these, for broader compatibility. To require these features, use an explicit #pragma require directive.
• If you use a target that requires geometry but your shader does not define a geometry stage, Unity removes geometry from the list of requirements at compile time.
• If you use a target that requires tessellation but your shader does not define a hull or domain stage, Unity removes tessellation from the list of requirements at compile time.

List of ‘#pragma require’ values

Here are all the valid values for the #pragma require directive.

值	描述
interpolators10	At least 10 vertex-to-fragment interpolators (“varyings”) are available.
interpolators15	At least 15 vertex-to-fragment interpolators (“varyings”) are available. Note: Internally, this also automatically adds integers to the list of requirements.
interpolators32	At least 32 vertex-to-fragment interpolators (“varyings”) are available.
integers	Integers are a supported data type, including bit/shift operations. Note: Internally, this also automatically adds interpolators15 to the list of requirements.
mrt4	At least 4 render targets are supported.
mrt8	At least 8 render targets are supported.
derivatives	Pixel shader derivative instructions (ddx/ddy) are supported.
samplelod	Explicit texture LOD sampling (tex2Dlod / SampleLevel) is supported.
fragcoord	Pixel location (XY on screen, ZW depth in clip space) input in pixel shader is supported.
2darray	2D texture arrays are a supported data type.
cubearray	Cubemap arrays are a supported data type.
instancing	SV_InstanceID input system value is supported.
geometry	Geometry shader stages are supported.
compute	Compute shaders, structured buffers, and atomic operations are supported.
randomwrite or uav	“Random write” (UAV) textures are supported.
tesshw	Hardware tessellation is supported, but not necessarily tessellation (hull/domain) shader stages. For example, Metal supports tessellation, but not hull or domain stages.
tessellation	Tessellation (hull/domain) shader stages are supported.
msaatex	The ability to access multi-sampled textures (Texture2DMS in HLSL) is supported.
sparsetex	Sparse textures with residency info (“Tier2” support in DirectX terms; CheckAccessFullyMapped HLSL function).
framebufferfetch or fbfetch	Framebuffer fetch (the ability to read input pixel color in the pixel shader) is supported.
setrtarrayindexfromanyshader	Setting the render target array index from any shader stage (not just the geometry shader stage) is supported.

Use shader keywords to target GPU features

You can use a shader keyword to target the following GPU features:

• Support for 16-bit data types.
• Support for wave operations in compute shaders.

Use the following syntax:

#pragma multi_compile _ <keyword>

You don’t need to add a pragma require directive.

Unity then does the following:

• Uses a compatible shader compiler and turns on compiler flags related to the feature.
• Automatically compiles both a shader variant with the keyword on and a shader variant with the keyword off.
• At runtime, automatically checks if the hardware supports the feature and selects the correct variant.

You can use an #if statement to make parts of your shader code conditional on whether the GPU supports the feature.

关键字

multi-compile keyword	GPU feature	Keyword for conditional shader code
UNITY_DEVICE_SUPPORTS_NATIVE_16BIT	Supports 16-bit data types. If you use this keyword, the layout of shader buffers might change, because data types such as half and min16float convert to 16-bit.	UNITY_DEVICE_SUPPORTS_NATIVE_16BIT
UNITY_DEVICE_SUPPORTS_WAVE_ANY	Supports wave operations of any size. Use this keyword only if you use wave operations where the size of the waves doesn’t matter.	UNITY_HW_SUPPORTS_WAVE
UNITY_DEVICE_SUPPORTS_WAVE_8	Supports wave operations with a wave size of 8.	UNITY_HW_SUPPORTS_WAVE
UNITY_DEVICE_SUPPORTS_WAVE_16	Supports wave operations with a wave size of 16.	UNITY_HW_SUPPORTS_WAVE
UNITY_DEVICE_SUPPORTS_WAVE_32	Supports wave operations with a wave size of 32.	UNITY_HW_SUPPORTS_WAVE
UNITY_DEVICE_SUPPORTS_WAVE_64	Supports wave operations with a wave size of 64.	UNITY_HW_SUPPORTS_WAVE
UNITY_DEVICE_SUPPORTS_WAVE_128	Supports wave operations with a wave size of 128.	UNITY_HW_SUPPORTS_WAVE

If you use a keyword that targets a specific wave size, Unity sets a UNITY_HW_WAVE_SIZE define to the same wave size so you can use it in shader code.

Refer to Declaring and using shader keywords in HLSL for more information.