Writing Surface Shaders

Writing shaders that interact with lighting is complex. There are different light types, different shadow options, different rendering paths (forward and deferred rendering), and the shader should somehow handle all that complexity.

Surface Shaders in Unity is a code generation approach that makes it much easier to write lit shaders than using low level vertex/pixel shader programs. Note that there is no custom languages, magic or ninjas involved in Surface Shaders; it just generates all the repetitive code that would have to be written by hand. You still write shader code in Cg / HLSL.

For some examples, take a look at Surface Shader Examples and Surface Shader Custom Lighting Examples.

How it works

You define a "surface function" that takes any UVs or data you need as input, and fills in output structure SurfaceOutput. SurfaceOutput basically describes properties of the surface (it's albedo color, normal, emission, specularity etc.). You write this code in Cg / HLSL.

Surface Shader compiler then figures out what inputs are needed, what outputs are filled and so on, and generates actual vertex&pixel shaders, as well as rendering passes to handle forward and deferred rendering.

Standard output structure of surface shaders is this:

struct SurfaceOutput {
    half3 Albedo;
    half3 Normal;
    half3 Emission;
    half Specular;
    half Gloss;
    half Alpha;


See Surface Shader Examples, Surface Shader Custom Lighting Examples and Surface Shader Tessellation pages.

Surface Shader compile directives

Surface shader is placed inside CGPROGRAM..ENDCG block, just like any other shader. The differences are:

The #pragma surface directive is:

    #pragma surface surfaceFunction lightModel [optionalparams]

Required parameters:

Optional parameters:

Additionally, you can write #pragma debug inside CGPROGRAM block, and then surface compiler will spit out a lot of comments of the generated code. You can view that using Open Compiled Shader in shader inspector.

Surface Shader input structure

The input structure Input generally has any texture coordinates needed by the shader. Texture coordinates must be named "uv" followed by texture name (or start it with "uv2" to use second texture coordinate set).

Additional values that can be put into Input structure:

Surface shaders and DirectX 11

Currently some parts of surface shader compilation pipeline do not understand DirectX 11-specific HLSL syntax, so if you're using HLSL features like StructuredBuffers, RWTextures and other non-DX9 syntax, you have to wrap it into a DX11-only preprocessor macro. See Platform Specific Differences page for details.

Further Documentation

Page last updated: 2013-10-14