Writing vertex and fragment shaders

ShaderLab shaders encompass more than just “hardware shaders”. They do many things. They describe properties that are displayed in the Material Inspector, contain multiple shader implementations for different graphics hardware, configure fixed function hardware state and so on. The actual programmable shaders - like vertex and fragment programs - are just a part of the whole ShaderLab’s “shader” concept. Take a look at shader tutorial for a basic introduction. Here we’ll call the low-level hardware shaders shader programs.

If you want to write shaders that interact with lighting, take a look at Surface Shaders documentation. For some examples, take a look at Vertex and Fragment Shader Examples. The rest of this page will assume shaders that do not interact with Unity lights (e.g. special effects, Image Effects etc.)

Shader programs are written in Cg / HLSL language, by embedding “snippets” in the shader text, somewhere inside the Pass command. They usually look like this:

  Pass {
      // ... the usual pass state setup ...
      
      CGPROGRAM
      // compilation directives for this snippet, e.g.:
      #pragma vertex vert
      #pragma fragment frag
      
      // the Cg/HLSL code itself
      
      ENDCG
      // ... the rest of pass setup ...
  }

Cg snippets

Cg program snippets are written between CGPROGRAM and ENDCG.

At the start of the snippet compilation directives can be given as #pragma statements. Directives indicating which shader functions to compile:

• #pragma vertex name - compile function name as the vertex shader.
• #pragma fragment name - compile function name as the fragment shader.
• #pragma geometry name - compile function name as DX10 geometry shader. Having this option automatically turns on #pragma target 4.0, described below.
• #pragma hull name - compile function name as DX11 hull shader. Having this option automatically turns on #pragma target 5.0, described below.
• #pragma domain name - compile function name as DX11 domain shader. Having this option automatically turns on #pragma target 5.0, described below.

Other compilation directives:

• #pragma target name - which shader target to compile to. See Shader targets below for details.
• #pragma only_renderers space separated names - compile shader only for given renderers. By default shaders are compiled for all renderers. See Renderers below for details.
• #pragma exclude_renderers space separated names - do not compile shader for given renderers. By default shaders are compiled for all renderers. See Renderers below for details.
• #pragma multi_compile …_ - for working with multiple shader variants.
• #pragma enable_d3d11_debug_symbols - generate debug information for shaders compiled for DirectX 11, this will allow you to debug shaders via Visual Studio 2012 (or higher) Graphics debugger.

Each snippet must contain at least a vertex program and a fragment program. Thus #pragma vertex and #pragma fragment directives are required.

Compilation directives that don’t do anything starting with Unity 5.0 and can be safely removed: #pragma glsl, #pragma glsl_no_auto_normalization, #pragma profileoption, #pragma fragmentoption.

Shader targets

By default, Unity compiles shaders into roughly shader model 2.0 equivalent. Using #pragma target allows shaders to be compiled into other capability levels. Currently these targets are supported:

• #pragma target 2.0 (default) - roughly shader model 2.0
  • Shader Model 2.0 on Direct3D 9.
  • Limited amount of arithmetic & texture instructions; no vertex texture sampling; no derivatives in fragment shaders.
• #pragma target 3.0 - compile to shader model 3.0:
  • Shader Model 3.0 on Direct3D 9.
• #pragma target 4.0 - compile to DX10 shader model 4.0. This target is currently only supported by DirectX 11 and XboxOne/PS4 platforms.
• #pragma target 5.0 - compile to DX11 shader model 5.0. This target is currently only supported by DirectX 11 and XboxOne/PS4 platforms.

Note that all OpenGL-like platforms (including mobile) are treated as “capable of shader model 3.0”. WP8/WinRT platforms (DX11 feature level 9.x) are treated as only capable of shader model 2.0.

Rendering platforms

Unity supports several rendering APIs (e.g. Direct3D 9 and OpenGL), and by default all shader programs are compiled into all supported renderers. You can indicate which renderers to compile to using #pragma only_renderers or #pragma exclude_renderers directives. This is mostly useful in cases where you are explicitly using some shader language features that you know aren’t possible on some platforms. Currently supported renderer names are:

• d3d9 - Direct3D 9.
• d3d11 - Direct3D 11.
• opengl - OpenGL.
• gles - OpenGL ES 2.0.
• gles3 - OpenGL ES 3.0.
• metal - iOS Metal.
• d3d11_9x - Direct3D 11 9.x feature level, as commonly used on WSA/WP8 platforms.
• xbox360 - Xbox 360.
• xboxone - Xbox One.
• ps3 - PlayStation 3.
• ps4 - PlayStation 4.
• psp2 - PlayStation Vita.

For example, this line would only compile shader into D3D9 mode:

#pragma only_renderers d3d9