What every line of a Unity shader file is for

The first time I opened a .shader file, it looked like a wall of curly brackets and SHOUTY WORDS. It’s really a few boxes inside each other, and most of them say the same thing in every shader. Let’s take apart the small file behind this little sticker, top to bottom. It has one control of each kind.

A sticker to drag and tweaklivein Unity

Drag the sticker, or press Tab to reach it and use the arrow keys

Turn on JavaScript to run this demo.

SizeHow big the sticker is.

0.40

RingsHow many thin rings echo the edge.

2

TintThe sticker's color.

GlowA soft light around the sticker.

ShapeWhich shape the sticker has.CircleSquareDiamond

sticker.hlsl draws the demo aboveHLSLGLSL

Boxes inside boxes

Copy for Unity, the cube button on a demo’s code window, turns the demo into this file. Point at or tap any dotted word for its meaning.

Shader "DocMe/unity-shader-file/fig_01"
{
    Properties
    {
        _Size ("Size", Range(0.2, 0.6)) = 0.4
        [IntRange] _Rings ("Rings", Range(0, 4)) = 2
        _Tint ("Tint", Color) = (1, 0.4, 0.8, 1)
        [ToggleUI] _Glow ("Glow", Float) = 1
        [Enum(Circle, 0, Square, 1, Diamond, 2)] _Shape ("Shape", Float) = 0
        _Pointer ("Pointer", Vector) = (0.5, 0.5, 0, 0)
    }
    SubShader
    {
        Tags { "RenderType"="Opaque" "Queue"="Geometry" }
        Pass
        {
            CGPROGRAM
            #pragma vertex vert
            #pragma fragment frag
            #pragma target 3.0
            #include "UnityCG.cginc"

            float4 _Pointer;

            // Library: common
            // Always included. Constants, coordinates, anti-aliasing, hashes and the stage colors.
            // The same code runs on this site (DOCME_WEB) and in Unity; only where the picture's size comes from differs.

            #define PI 3.14159265359
            #define TAU 6.28318530718

            float remap(float x, float a, float b, float c, float d) { return c + (x - a) * (d - c) / (b - a); }
            float remap01(float x, float a, float b) { return saturate((x - a) / (b - a)); }

            // Width over height of the picture: the canvas on the site, the quad's scale in Unity.
            float docmeAspect()
            {
            #ifdef DOCME_WEB
                return _ScreenParams.x / _ScreenParams.y;
            #else
                return length(unity_ObjectToWorld._m00_m10_m20) / length(unity_ObjectToWorld._m01_m11_m21);
            #endif
            }

            // Square coordinates with the origin in the middle: the short side of the picture spans -1..1.
            float2 centered(float2 uv)
            {
                float a = docmeAspect();
                return (uv * 2.0 - 1.0) * float2(a, 1.0) / min(a, 1.0);
            }

            // The pointer (or the _Pointer material setting in Unity) in the same coordinates as centered().
            float2 pointerCentered()
            {
                float a = docmeAspect();
                return (_Pointer.xy * 2.0 - 1.0) * float2(a, 1.0) / min(a, 1.0);
            }

            // Width of one pixel in centered() units. Measured once per pixel before shade() runs, outside any branch.
            static float docmePixel;
            float pixelSize() { return docmePixel; }

            // Anti-aliased coverage of a signed distance: 1 inside, 0 outside, a one pixel ramp at the edge.
            float fillAA(float d)
            {
                float w = max(fwidth(d), 1e-5);
                return saturate(0.5 - d / w);
            }
            // Anti-aliased line of a given width (same units as d) around the zero line of d.
            float strokeAA(float d, float width) { return fillAA(abs(d) - 0.5 * width); }

            // Cheap hashes: one random number per input. Dave Hoskins, Hash without Sine (MIT License).
            float hash11(float p)
            {
                p = frac(p * 0.1031);
                p *= p + 33.33;
                p *= p + p;
                return frac(p);
            }
            float hash12(float2 p)
            {
                float3 p3 = frac(p.xyx * 0.1031);
                p3 += dot(p3, p3.yzx + 33.33);
                return frac((p3.x + p3.y) * p3.z);
            }
            float2 hash22(float2 p)
            {
                float3 p3 = frac(p.xyx * float3(0.1031, 0.1030, 0.0973));
                p3 += dot(p3, p3.yzx + 33.33);
                return frac((p3.xx + p3.yz) * p3.zy);
            }

            // Turns a point by a radians, counterclockwise: mul(rot2(a), p).
            float2x2 rot2(float a)
            {
                float c = cos(a), s = sin(a);
                return float2x2(c, -s, s, c);
            }

            // Color. Shaders work in linear light, as Unity does in a linear project; the screen gets sRGB at the end.
            float3 srgbToLinear(float3 c) { return lerp(c / 12.92, pow((c + 0.055) / 1.055, float3(2.4, 2.4, 2.4)), step(0.04045, c)); }
            float3 linearToSrgb(float3 c)
            {
                c = max(c, 0.0);
                return lerp(c * 12.92, 1.055 * pow(c, float3(0.41666667, 0.41666667, 0.41666667)) - 0.055, step(0.0031308, c));
            }
            // Blends two colors in steps that look even to the eye (in sRGB), for value ramps such as distance bands.
            // Edges and coverage still blend with lerp, in linear light, as light really adds up.
            float3 tint(float3 a, float3 b, float t) { return srgbToLinear(lerp(linearToSrgb(a), linearToSrgb(b), t)); }
            // Rolls HDR values above 1 off softly instead of clipping them.
            float3 tonemapACES(float3 x) { return saturate((x * (2.51 * x + 0.03)) / (x * (2.43 * x + 0.59) + 0.14)); }
            float luminance(float3 c) { return dot(c, float3(0.2126, 0.7152, 0.0722)); }

            // The dusk stage colors, in linear light. Series colors are used in this order: mint, pink, butter.
            float3 themeSurface() { return float3(0.0080, 0.0048, 0.0243); }
            float3 themeInk() { return float3(0.8794, 0.8154, 1.0000); }
            float3 themeMuted() { return float3(0.3971, 0.3280, 0.6383); }
            float3 themeGrid() { return float3(0.0243, 0.0138, 0.0646); }
            float3 series1() { return float3(0.2085, 0.8710, 0.5771); }
            float3 series2() { return float3(1.0000, 0.2749, 0.5771); }
            float3 series3() { return float3(1.0000, 0.6577, 0.2540); }

            // A glowing sticker with one control of each kind, to read in its Unity file.
            uniform float _Size;   // @range 0.2 0.6 0.01 = 0.4 | Size | How big the sticker is.
            uniform float _Rings;  // @range 0 4 1 = 2 | Rings | How many thin rings echo the edge.
            uniform float3 _Tint;  // @color = #ff66cc | Tint | The sticker's color.
            uniform float _Glow;   // @toggle = 1 | Glow | A soft light around the sticker.
            uniform float _Shape;  // @select = 0 | Shape | Circle=0, Square=1, Diamond=2 | Which shape the sticker has.

            float4 shade(float2 uv)
            {
                float2 p = centered(uv) - pointerCentered();

                // The distance from this pixel to the sticker's edge: negative inside.
                int shape = int(_Shape + 0.5);
                float d = length(p) - _Size;
                float2 r = shape == 2 ? mul(rot2(PI / 4.0), p) : p;
                float2 q = abs(r) - 0.7 * _Size;
                if (shape > 0) d = length(max(q, 0.0)) + min(max(q.x, q.y), 0.0) - 0.2 * _Size;

                float3 col = float3(0.012, 0.012, 0.025);
                col += _Tint * 0.6 * exp(-8.0 * max(d, 0.0)) * _Glow;
                float gap = 0.09;
                float ring = abs(d - gap * clamp(round(d / gap), 1.0, max(_Rings, 1.0)));
                col += _Tint * 0.5 * strokeAA(ring, 0.012) * saturate(_Rings);
                col = tonemapACES(col);
                col = lerp(col, _Tint, fillAA(d));
                col = lerp(col, float3(1.0, 1.0, 1.0), strokeAA(d, 0.016));
                return float4(col, 1.0);
            }


            struct appdata
            {
                float4 vertex : POSITION;
                float2 uv : TEXCOORD0;
                UNITY_VERTEX_INPUT_INSTANCE_ID
            };

            struct v2f
            {
                float4 pos : SV_POSITION;
                float2 uv : TEXCOORD0;
                UNITY_VERTEX_OUTPUT_STEREO
            };

            v2f vert(appdata v)
            {
                v2f o;
                UNITY_SETUP_INSTANCE_ID(v);
                UNITY_INITIALIZE_OUTPUT(v2f, o);
                UNITY_INITIALIZE_VERTEX_OUTPUT_STEREO(o);
                o.pos = UnityObjectToClipPos(v.vertex);
                o.uv = v.uv;
                return o;
            }

            float4 frag(v2f i) : SV_Target
            {
                UNITY_SETUP_STEREO_EYE_INDEX_POST_VERTEX(i);
                docmePixel = length(fwidth(centered(i.uv))) * 0.70710678;
                return float4(shade(i.uv).rgb, 1.0);
            }
            ENDCG
        }
    }
}

The outer boxes are ShaderLab, Unity’s language for describing a shader: Shader holds everything, Properties the settings, SubShader the drawing and Pass the code. The code itself, between CGPROGRAM and ENDCG, is HLSL (more in a later lesson).

The first line, Shader "DocMe/unity-shader-file/fig_01", is the name you pick in a material’s Shader menu (each slash opens a submenu). It needn’t match the file’s name.

The material’s settings in Properties

Each line in Properties becomes one setting on the material:

_Size ("Size", Range(0.2, 0.6)) = 0.4

The other lines bring more types. Tint is a Color (a color picker), Glow and Shape are a Float (one number) and Pointer a Vector (four numbers). A word in square brackets is a drawer, which only changes how the setting looks. IntRange makes Rings stop on whole numbers, ToggleUI turns Glow into a checkbox and Enum turns Shape into a dropdown of named numbers.

Further down, a variable has the same name:

uniform float _Size;   // @range 0.2 0.6 0.01 = 0.4 | Size | How big the sticker is.

Before each draw, Unity copies the material’s value into it. Uniform means one value for all pixels, and the comment only builds this site’s slider. Misspell the name and the variable stays at 0, however much you move the setting.

SubShader, Tags and Pass

Tags { "RenderType"="Opaque" "Queue"="Geometry" }

A shader can hold several SubShaders, say a simpler one for older graphics cards, and Unity uses the first one the card can run. Its tags say when and how it draws. Queue sets its turn, and the lowest number goes first. Solid things draw in Geometry, then see-through things in Transparent, back to front so each blends over what’s behind. RenderType is a label for when Unity redraws the scene with stand-in shaders.

A Pass is one drawing of the object, and toon shaders often add a second for an outline. Passes have tags too. LightMode names the pass’s lighting job, such as the main light or shadows, and without it the pass draws unlit.

Where the code begins

CGPROGRAM
#pragma vertex vert
#pragma fragment frag
#pragma target 3.0
#include "UnityCG.cginc"

#pragma lines are notes for the compiler, which turns this text into graphics card instructions. The first two name the functions: vert, the vertex shader, runs for every corner of the mesh, and frag, the fragment shader, for every pixel it covers. target 3.0 asks for shader model 3.0, a feature set every graphics card has today.

UnityCG.cginc holds Unity’s ready made helpers. After it come the site’s helpers (folded away above) and the demo, word for word.

Two little structs

A struct is a bundle of values with one name. The first, appdata, carries the two things the mesh hands over for each corner, its position and its UV. The second, v2f (vertex to fragment), is what vert passes on to frag:

struct v2f
{
    float4 pos : SV_POSITION;
    float2 uv : TEXCOORD0;
    UNITY_VERTEX_OUTPUT_STEREO
};

The words after the colons are semantics, labels that tell the graphics card what each value is. SV stands for system value, one the graphics card itself acts on.

vert places corners, frag colors pixels

v2f o;
UNITY_SETUP_INSTANCE_ID(v);
UNITY_INITIALIZE_OUTPUT(v2f, o);
UNITY_INITIALIZE_VERTEX_OUTPUT_STEREO(o);
o.pos = UnityObjectToClipPos(v.vertex);
o.uv = v.uv;
return o;

UnityObjectToClipPos moves the corner from the mesh’s own space onto the screen, and the UV comes along (the UNITY_ lines come later). The graphics card then blends the corners’ values across each triangle, giving every pixel its own UV, like in the first lesson.

float4 frag(v2f i) : SV_Target
{
    UNITY_SETUP_STEREO_EYE_INDEX_POST_VERTEX(i);
    docmePixel = length(fwidth(centered(i.uv))) * 0.70710678;
    return float4(shade(i.uv).rgb, 1.0);
}

frag hands each pixel to shade, the demo’s own function. The docmePixel line first measures how big a pixel is, for the soft edges.

Both eyes at once

Headsets need one picture per eye. In Unity’s single pass instanced mode, the graphics card draws each object twice in one go, one copy (instance) per eye, and the UNITY_ lines tell each copy its eye. Without them, the shader shows in one eye only. VRChat’s SDK compiles every shader for this mode on upload, so keep them. The odd one out, UNITY_INITIALIZE_OUTPUT, fills v2f with zeros first.

Taking it to Unity

1. Press Copy for Unity on the demo, or Copy on the file above.
2. In Unity’s Project window, right-click and choose Create > Shader > Unlit Shader. Open it, replace everything with what you copied, and save.
3. Choose Create > Material, and pick DocMe > unity-shader-file > fig_01 in its Shader menu.
4. Add a quad with GameObject > 3D Object > Quad, and drag the material onto it.

Scale the quad to 1.78 in X for the demo’s wide frame, then play with the settings.

The render state around your code

Render state lines set up the graphics card’s own steps around your code. Cull throws away triangles facing the wrong way before frag sees them. The depth buffer remembers how far away the nearest thing on each pixel is: ZTest checks new pixels against it, ZWrite says whether they store their distance there, and Offset nudges their distance a little, so a decal stops flickering on its wall.

ColorMask picks the channels written, and AlphaToMask smooths cutout edges under MSAA. Stencil bends brains a little. It keeps a hidden number on each pixel, for portals and mirrors. Every value waits in the fold-out at the end, where I look them up too.

Mixing with the screen using Blend

Blend mixes the color frag returns, the source (Src), into the color on screen, the destination (Dst). Each is multiplied by one of Blend’s two words, then they’re added:

Here $s$ is the source, $d$ the destination, $S$ and $D$ are Blend’s two words, and $c$ is the result. OneMinus means 1 minus.

Try each Blend linelivein Unity

Turn on JavaScript to run this demo.

BlendWhich Blend line draws the pink bar.TraditionalPremultipliedAdditiveSoft additiveMultiplicative

AlphaThe alpha frag returns with the pink color.

0.60

blend.hlsl draws the demo aboveHLSLGLSL

A see-through material puts it all together:

Tags
{
    "RenderType"="Transparent"
    "Queue"="Transparent"
}
ZWrite Off
Blend SrcAlpha OneMinusSrcAlpha

Its queue draws it after solid things, so they show through, and ZWrite Off keeps it from hiding things drawn later.