Predefined Shader preprocessor macros

Unity defines several preprocessor macros when compiling Shader programs.

Target platform

SHADER_API_MOBILE is defined for all general mobile platforms (GLES, GLES3, METAL, PSP2).

Additionally, SHADER_TARGET_GLSL is defined when the target shading language is GLSL (always true for OpenGL/GLES platforms).

Shader target model

SHADER_TARGET is defined to a numeric value that matches the Shader target compilation model (that is, matching #pragma target directive). For example, SHADER_TARGET is 30 when compiling into Shader model 3.0. You can use it in Shader code to do conditional checks. For example:

#if SHADER_TARGET < 30
    // less than Shader model 3.0:
    // very limited Shader capabilities, do some approximation
#else
    // decent capabilities, do a better thing
#endif

Unity version

UNITY_VERSION contains the numeric value of the Unity version. For example, UNITY_VERSION is 501 for Unity 5.0.1. This can be used for version comparisons if you need to write Shaders that use different built-in Shader functionality. For example, a #if UNITY_VERSION >= 500 preprocessor check only passes on versions 5.0.0 or later.

Shader stage being compiled

Preprocessor macros SHADER_STAGE_VERTEX, SHADER_STAGE_FRAGMENT, SHADER_STAGE_DOMAIN, SHADER_STAGE_HULL, SHADER_STAGE_GEOMETRY, SHADER_STAGE_COMPUTE are defined when compiling each Shader stage. Typically they are useful when sharing Shader code between pixel Shaders and compute Shaders, to handle cases where some things have to be done slightly differently.

Platform difference helpers

Direct use of these platform macros is discouraged, as they don’t always contribute to the future-proofing of your code. For example, if you’re writing a Shader that checks for D3D11, you may want to ensure that, in the future, the check is extended to include Vulkan. Instead, Unity defines several helper macros (in HLSLSupport.cginc):

• UNITY_REVERSED_Z - defined on plaftorms using reverse Z buffer. Stored Z values are in the range 1..0 instead of 0..1.

Shadow mapping macros

Declaring and sampling shadow maps can be very different depending on the platform. Unity has several macros to help with this:

NOTE: Not all graphics cards support shadowmaps. Use SystemInfo.SupportsRenderTextureFormat to check for support.

Constant buffer macros

Direct3D 11 groups all Shader variables into “constant buffers”. Most of Unity’s built-in variables are already grouped, but for variables in your own Shaders it might be more optimal to put them into separate constant buffers depending on expected frequency of updates.

Use CBUFFER_START(name) and CBUFFER_END macros for that:

CBUFFER_START(MyRarelyUpdatedVariables)
    float4 _SomeGlobalValue;
CBUFFER_END

Texture/Sampler declaration macros

Usually you would use texture2D in Shader code to declare a Texture and Sampler pair. However on some platforms (such as DX11), Textures and Samplers are separate GameObjects, and maximum possible Sampler count is quite limited. Unity has some macros to declare Textures without Samplers, and to sample a Texture using a Sampler from another Texture. Use this if you end up running into Sampler limits, and you know that several of your Textures can in fact share a Sampler (Samplers define Texture filtering and wrapping modes).

For more information, see documentation on Sampler States.

Surface Shader pass indicators

When Surface Shaders are compiled, they generate a lot of code for various passes to do lighting. When compiling each pass, one of the following macros is defined:

Disable Auto-Upgrade

UNITY_SHADER_NO_UPGRADE allows you to disable Unity from automatically upgrading or modifying your shader file.

See also

• Built-in Shader include files
• Built-in Shader variables
• Vertex and Fragment program examples

• 2017–05–16 Page amended with no editorial review