Predefined shader preprocessor macros

Suggest a change

When compiling shader programs, Unity defines several preprocessor macros.

Target platform

SHADER_API_D3D9 - Direct3D 9
SHADER_API_D3D11 - desktop Direct3D 11
SHADER_API_OPENGL - desktop OpenGL
SHADER_API_GLES - OpenGL ES 2.0
SHADER_API_GLES3 - OpenGL ES 3.0
SHADER_API_METAL - iOS Metal
SHADER_API_D3D11_9X - Direct3D 11 “feature level 9.x” target for Windows Store Apps & Windows Phone
SHADER_API_PS4 - PlayStation 4
SHADER_API_XBOXONE - Xbox One
SHADER_API_PS3 - PlayStation 3
SHADER_API_XBOX360 - Xbox 360
SHADER_API_PSP2 - PlayStation Vita
SHADER_API_PSM - PlayStation Mobile

SHADER_API_MOBILE is defined for all “generally 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 macro will be defined to a numeric value that matches shader target compilation model (i.e. matching #pragma target directive). For example, SHADER_TARGET will be 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 macro will contain numeric value of Unity version, e.g. it will be 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, #if UNITY_VERSION >= 500 preprocessor check will only pass on versions 5.0.0 or later.

Platform difference helpers

Direct use of these platform macros is discouraged, since it’s not very future proof. For example, if you’re writing a shader that checks for D3D9, then maybe in the future the check should be extended to include D3D11. Instead, Unity defines several helper macros (in HLSLSupport.cginc) to help with that.

UNITY_BRANCH - add this before conditional statements to hint the compiler that this should be compiled into an actual branch. Expands to [branch] when on HLSL platforms.
UNITY_FLATTEN - add this before conditional statements to hint the compiler that this should be flattened to avoid an actual branch instruction. Expands to [flatten] when on HLSL platforms.
UNITY_NO_SCREENSPACE_SHADOWS - defined on platforms that do not use cascaded screenspace shadowmaps (mobile platforms).
UNITY_NO_LINEAR_COLORSPACE - defined on platforms that do not support Linear color space (mobile platforms).
UNITY_NO_RGBM - defined on platforms where RGBM compression for lightmaps is not used (mobile platforms).
UNITY_NO_DXT5nm - defined on platforms that do not use DXT5nm normal-map compression (mobile platforms).
UNITY_FRAMEBUFFER_FETCH_AVAILABLE - defined on platforms where “framebuffer color fetch” functionality can be available (generally iOS platforms - OpenGL ES 2.0, 3.0 and Metal).
UNITY_USE_RGBA_FOR_POINT_SHADOWS - defined on platforms where point light shadowmaps use RGBA textures with encoded depth (other platforms use single-channel floating point textures).
UNITY_ATTEN_CHANNEL - which channel of light attenuation texture contains the data; used in per-pixel lighting code. Defined to either ‘r’ or ‘a’.
UNITY_HALF_TEXEL_OFFSET - defined on platforms that need a half-texel offset adjustment in mapping texels to pixels (e.g. Direct3D 9).
UNITY_UV_STARTS_AT_TOP - always defined with value or 1 or 0; value of one is on platforms where texture V coordinate is zero at “top of the texture”. Direct3D-like platforms use value of 1; OpenGL-like platforms use value of 0.
UNITY_MIGHT_NOT_HAVE_DEPTH_TEXTURE - defined if a platform might emulate shadow maps or depth textures by manually rendering depth into a texture.
UNITY_PROJ_COORD(a) - given a 4-component vector, return a texture coordinate suitable for projected texture reads. On most platforms this returns the given value directly.
UNITY_NEAR_CLIP_VALUE - defined to the value of near clipping plane; Direct3D-like platforms use 0.0 while OpenGL-like platforms use –1.0.
UNITY_VPOS_TYPE - data type requires for pixel position input (VPOS). float2 on D3D9, float4 elsewhere.
UNITY_CAN_COMPILE_TESSELLATION - defined when the shader compiler “understands” tessellation shader HLSL syntax (currently only D3D11).
UNITY_INITIALIZE_OUTPUT(type,name) - initialize variable name of given type to zero.
UNITY_COMPILER_HLSL, UNITY_COMPILER_HLSL2GLSL, UNITY_COMPILER_CG - indicates which shader compiler is being used to compile shaders. Respectively, Microsoft’s HLSL (used for DX9, DX11, XboxOne, Xbox360, WinRT), HLSL to GLSL translator (used for OpenGL & iOS/Android), and NVIDIA’s Cg (used for surface shader analysis and some Sony platforms). Use this if you run into very specific corner case shader syntax handling differences between the compilers, and want to write different code for each compiler.

Shadow mapping macros

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

UNITY_DECLARE_SHADOWMAP(tex) - declares a shadowmap texture variable with name “tex”.
UNITY_SAMPLE_SHADOW(tex,uv) - samples shadowmap texture “tex” at given “uv” coordinate (XY components are texture location, Z component is depth to compare with). Returns single float value with the shadow term in 0..1 range.
UNITY_SAMPLE_SHADOW_PROJ(tex,uv) - similar to above, but does a projective shadowmap read. “uv” is a float4, all other components are divided by .w for doing the lookup.

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 & sampler pair. However, on some platforms (e.g. DX11) textures and samplers are separate objects; 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 several of your textures can in fact share a sampler (sampler defines texture filtering & wrapping modes).

UNITY_DECLARE_TEX2D(name) - declares a texture + sampler pair.
UNITY_DECLARE_TEX2D_NOSAMPLER(name) - declares a texture without a sampler.
UNITY_SAMPLE_TEX2D(name,uv) - sample from a texture+sampler pair, using given texture coordinate.
UNITY_SAMPLE_TEX2D_SAMPLER(name,samplername,uv) - sample from texture (name), using sampler from another texture (samplername).

Surface shader pass indicators

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

UNITY_PASS_FORWARDBASE - forward rendering base pass (main directional light, lightmaps, SH).
UNITY_PASS_FORWARDADD - forward rendering additive pass (one light per pass).
UNITY_PASS_DEFERRED - deferred shading pass (renders g-buffer).
UNITY_PASS_SHADOWCASTER - shadow caster and depth texture rendering pass.
UNITY_PASS_PREPASSBASE - legacy deferred lighting base pass (renders normals & specular exponent).
UNITY_PASS_PREPASSFINAL - legacy deferred lighting final pass (applies lighting & textures).

Built-in shader include files

Built-in shader variables

Unity Manual