Yotsuba ShaderLearn
Get Started

How a shader is built

22 min read

The journey the data makes from your game to the screen, before you write a single line.

You already know what a shader is: a function the GPU runs a huge number of times at once. But knowing what it is does not tell you how to make one. What does that function receive? What does it have to return? Who calls it, and with what data?

In this chapter you will not write code or install anything. You will follow the complete journey of a drawing, from your game to the screen, one step after another. Take your time with it, because everything you write later in C# is one of these steps. If you understand the journey, the code explains itself.

The drawing we are going to follow is this triangle:

A triangle with one red corner, one green and one blue; inside, the three colors blend little by little

It has a red corner, a green one and a blue one, and inside the colors blend into each other. It does not look like much, but drawing it takes every piece a shader has. Not one less.

1. Everything is drawn with triangles#

The GPU knows how to draw very few shapes, and the one used for almost everything is the triangle. Everything else is built by putting triangles together:

A triangle with 3 vertices, a rectangle made of 2 triangles and a round shape made of 8

A rectangle is two triangles. Something round is many small triangles. A character in a 3D game is thousands.

Each corner of a triangle is called a vertex. It is a word you will read all the time, and it means nothing more than that: a point, a corner.

Look at the rectangle: it has 4 vertices and not 6, because the two triangles share two corners.

2. Your game sends a list of vertices#

To draw the triangle, your game sends the GPU a list with its three vertices. And for each vertex it sends the data you decide. In our case there are two: where it is and what color it is.

VertexPositionColor
The top one(0, 0.8)red
The bottom left one(-0.8, -0.7)green
The bottom right one(0.8, -0.7)blue

There are two things here worth having clear from the start:

  • You decide what data each vertex carries. The GPU does not force you to send a color. You could send only the position, or the position and five more things. You send what your shader is going to need.
  • For the GPU they are just numbers. It does not know that this is "a color". It sees three or four numbers together and nothing else. You give them their meaning inside the shader.

What can a vertex carry?#

Position and color are what this triangle needs, but a vertex can carry any data you want. These are the usual ones:

DataType in C#What it is for
Positionvec2, vec3 or vec4where the vertex is
Colorvec3 or vec4the color of the vertex; vec4 adds opacity
UVvec2which point of a texture belongs to this vertex
Normalvec3where the surface points, used for lighting
Tangentvec4direction along the surface, used for relief effects
Bone indices and weightsvec4 or uintanimate a character
Your own datafloat, int, uint or a vectora temperature, an age, a flag

Each piece of data is a float, an int or a uint, alone or in groups of two, three or four (vec2, vec3, vec4 and their int and uint versions). A matrix is bigger than four numbers, so it takes several slots.

The GPU does not know what any of this means. A vec4 is four numbers, whether you put a color in it or a position. The meaning only exists in how you use it inside the shader.

What do the position numbers mean?#

Your screen may be 1920 pixels wide, or 800, or 4000. So that the same drawing works on all of them, the GPU does not measure the screen in pixels. It uses the same ruler, whatever the screen:

The screen as the GPU sees it: the center is (0, 0), the top left corner is (-1, 1) and the bottom right is (1, -1)

  • The center of the screen is (0, 0).
  • The left edge is -1 and the right edge is 1.
  • The bottom edge is -1 and the top edge is 1.

So the vertex (0, 0.8) is centered horizontally and almost at the very top. And (-0.8, -0.7) is to the left and at the bottom.

3. The Vertex stage: once for each vertex#

This is where the first function you write comes in.

The GPU takes the list and calls your Vertex function once for each vertex. Three vertices, three calls. In each call it hands over the data of a single vertex: it does not see the other two.

That function has two jobs:

  1. Say where that vertex ends up on the screen. This is mandatory. Without a position, the GPU has nothing to draw.
  2. Let through the data the next stage is going to need. This is optional, and you decide which. In our case, the color.

In the triangle it looks like this:

What it receivesWhat it returns
Vertex functionthe position and the color of one vertexthe final position and the color

"If my game already sent the position, why do I return it again?"#

It is the logical question, because in our triangle the Vertex function does not change anything: it receives a position and returns that same one.

But in a real game the vertices are almost never sent already in place. The shape of a character is sent only once, and it is the Vertex stage that moves it around the map, rotates it, or makes it small when it is far from the camera. That is what it exists for: it is the place where it is decided where each point lands.

That in our example the answer is "where it already was" does not mean nobody has to give it.

The final position has four numbers, not two#

Your game sent the position with two numbers, X and Y. But the GPU asks for the final position with four:

NumberWhat it isWhat we put in 2D
1stX: left or rightyours
2ndY: down or upyours
3rdZ: the depth, that is, how far away it is0
4thW: it is used for perspective in 3D1

The last two only matter in 3D. As long as you draw in 2D, keep this: the first two are your X and your Y, and the other two are 0 and 1.

4. The GPU assembles the triangle#

You do not write this step. The GPU does it by itself.

With the three final positions it now knows where the triangle is on the screen. Then it works out which pixels fall inside:

Three points go through Vertex, form a triangle, the GPU marks the pixels it covers and Fragment colors them

The bigger the shape, the more pixels it covers. A small triangle may cover a few hundred. A rectangle that covers a whole Full HD screen covers the two million.

5. The spreading: from three values to thousands#

Something happens here that is almost never explained, and it is the key to understanding everything else.

The Vertex function returned three colors, one per vertex. But the triangle has thousands of pixels. Which color reaches each one?

The GPU spreads them. It gives each pixel a mix of the three values, depending on how close it is to each vertex:

On the left, three colored dots: what Vertex returned. On the right, the triangle filled with the blended colors: what Fragment receives

  • A pixel right next to the red vertex receives almost all red.
  • A pixel halfway between the red and the green receives half of each.
  • A pixel right in the center receives a third of each.

This is not something special about colors. The GPU does not know they are colors, remember? For it they are numbers, and it spreads any number the Vertex function lets through. If you let a temperature through, each pixel receives its own blended temperature.

From here comes an idea you have to take away from this chapter:

The technical name for this spreading is interpolation. You will read it elsewhere. Here we keep calling it spreading.

6. The Fragment stage: once for each pixel#

This is the second function you write.

The GPU calls it once for each pixel that fell inside the triangle, and in each call it hands over the data already spread for that pixel.

It has a single job: return the color of that pixel.

A color is four numbers, and each one goes from 0 (nothing) to 1 (everything). Not from 0 to 255:

ColorRedGreenBlueOpacity
Red1001
White1111
Black0001
Gray0.50.50.51
Yellow1101

The fourth number is the opacity: 1 is a solid color and 0 is fully transparent.

In our triangle, the Fragment function does the simplest thing there is: it receives the already blended color and returns it as is. The whole gradient was made by the spreading.

But it could do whatever it wanted with it: darken it, ignore it and return red, or calculate another color with a formula. That is what writing shaders consists of, and it is what you will do in the five that come next.

What a Fragment function cannot do#

Since the GPU runs the function for thousands of pixels at the same time, each call lives isolated from the others:

  • It knows nothing about the other pixels. It cannot ask what color the one next to it ended up.
  • It remembers nothing. A variable you create inside the function disappears when it ends. It is of no use for the next pixel or for the next frame.
  • There is no loop going through the pixels. The loop is the GPU. You write what happens with one.

The only thing a pixel knows is what reaches it through the spreading. If it needs something else, like the time that has passed or a photo, your game has to send it. You will see that in shaders 4 and 5.

7. The slots: how each stage knows which data is which#

So far we talked about "the position" and "the color", by name. But the GPU does not understand names. For it the data travels in numbered slots.

Your game says: "I put the position in slot 0 and the color in slot 1". And the Vertex function says: "I read the position from slot 0 and the color from slot 1". They understand each other by the number.

That number is called a location.

Which number goes with which data is up to you. Slot 0 is not the position by rule: you could put the color in slot 0 and the position in slot 1, as long as your game does the same. The GPU only sees the number and the type: slot 0, two floats; slot 1, four floats. Each slot holds up to four numbers, and every GPU offers at least 16 of them for the vertex data. If you get a number wrong no error appears: the shader reads the wrong data and the drawing comes out wrong.

In HLSL the slot is written as a semantic, TEXCOORD0 and TEXCOORD1 in our triangle. It is the same idea with another name.

Up to there it is easy. What confuses almost everyone is this: there is not a single row of slots. There are three.

On the triangle's journey the data crosses three doors, and each door has its own row:

The complete path: your game, door A, Vertex, door B, Fragment, door C and the screen. Each door has its slots numbered from 0

DoorWhat crosses itSlot 0Slot 1
AWhat your game sends to Vertexthe positionthe color
BWhat Vertex lets through to Fragmentthe colornothing
CWhat Fragment returnsthe pixel colornothing

Each door starts counting from 0 on its own. That is why "slot 0" appears three times, and all three times it carries a different thing: at door A it is the position, at B it is the color, and at C it is the final color of the pixel.

Think of three buildings on the same street. All three have an apartment number 1, and none has anything to do with the other two. To find someone you need the building and the number.

There are three rules:

  1. Within the same door a number is not repeated. There cannot be two pieces of data in slot 0 of door A.
  2. Both sides of a door have to agree. If Vertex leaves the color in slot 0 of door B, Fragment has to read the color from slot 0 of door B. The number and the type of data have to match. The name does not matter.
  3. Between different doors, the numbers have no relation at all.

And the final position? Why does it not have a number?#

Look at door B in the drawing. Besides the color there is something else, marked with a star instead of a number: the final position.

It has no slot because it is not data for your Fragment function. It is data for the GPU itself, which needs it in step 4 to assemble the triangle. Since it is always needed and always for the same thing, it does not get a number: it is marked with a special name that the GPU recognizes.

So there are two kinds of data leaving Vertex:

  • The special one, the final position. The GPU keeps it.
  • Yours, the ones with a slot number. Those are the ones that are spread and reach Fragment.

Why does door C have a number, if only one color comes out?#

Because a shader can paint on several images at once, and the number says which one. It is something advanced that you will not need in this tutorial. Almost always you paint on a single one, and that is number 0.

Five styles: you choose#

The number between brackets, location, is how GLSL names a slot. GLSL is the language of OpenGL and Vulkan. HLSL, the language of DirectX, names the same thing with a word and an index, such as TEXCOORD0. Metal, WebGPU and SPIR-V have their own words too. So which one do you write? The one you already know. Yotsuba Shader has five styles: GLSL, HLSL, MSL (Metal), WGSL (WebGPU) and SPIR-V. Only the words of the interface change; the math and the C# stay exactly the same. Use the Style dropdown at the top right of this page to see every example in the style you prefer.

Our Corner in the five styles:

public struct Corner
{
    [location(0)] public vec2 Position;
    [location(1)] public vec4 Color;
}

They look different, but each language has its own words for the same concepts, and the compiler knows the concept behind each word. Here are the ones you have met so far:

ConceptGLSLHLSLMSLWGSLSPIR-V
A channel of vertex data[location(0)][TEXCOORD(0)][attribute(0)][location(0)][Location(0)]
The final position[gl_Position][SV_Position][position][builtin_position][BuiltIn_Position]
Where the color goes (door C)[return: location(0)][return: SV_Target][return: color(0)][return: location(0)][return: Location(0)]

There is one difference worth knowing. With a number such as location(0) you choose the number. With a semantic such as TEXCOORD, the compiler can choose the number for you, and it connects the two stages by the name: the TEXCOORD(0) that leaves Vertex is the one Fragment receives. The final result is the same kind of slot.

The rest of this chapter writes the number in the neutral way: "slot 0". Whatever your style is, that is the slot you write with its own words.

8. The complete blueprint#

You have made the whole journey. To build any shader, not just this triangle, you have to decide five things:

What you decideIn the triangle
1What data each vertex carries (door A)The position in slot 0 and the color in slot 1.
2What Vertex lets through to Fragment (door B)The final position, which is the special one, and the color in slot 0.
3What the Vertex function doesIt copies the position and the color.
4What the Fragment function doesIt returns the color it receives.
5Where the color goes (door C)To slot 0.

And this is how the work is split among the three that take part:

WhoWhat it does
Your gameSends the list of vertices with their data.
You, in the shaderYou write the Vertex function and the Fragment function, and declare the three doors.
The GPUCalls your functions, assembles the triangles, finds the pixels and spreads the data.

Notice what you do not have to write: not the loop over the vertices, not the loop over the pixels, not the spreading. The GPU already does all of that.

9. The whole shader, and what the compiler generates#

This is the complete triangle shader, written in the five styles. Pick yours in the Style dropdown. (Make.Vec4 is the small helper from the first-shader chapter.)

using YotsubaShader.GlslSyntax;
using YotsubaShader.GlslSyntax.Types;
using YotsubaShader.Language;

namespace MyShaders;

public class Triangle
{
    public struct Corner
    {
        [location(0)] public vec2 Position;
        [location(1)] public vec4 Color;
    }

    public struct Pixel
    {
        [gl_Position] public vec4 Position;
        [location(0)] public vec4 Color;
    }

    public struct PixelIn
    {
        [location(0)] public vec4 Color;
    }

    [ShaderStage(Stage.Vertex)]
    public Pixel Vertex(Corner corner)
    {
        Pixel pixel;
        pixel.Position = Make.Vec4(corner.Position.X, corner.Position.Y, 0f, 1f);
        pixel.Color = corner.Color;
        return pixel;
    }

    [ShaderStage(Stage.Fragment)]
    [return: location(0)]
    public vec4 Fragment(PixelIn pixel)
    {
        return pixel.Color;
    }
}

Whichever style you choose, Yotsuba Shader generates the same outputs from it: GLSL and GLSL ES, HLSL, Metal, SPIR-V and C++. We compiled the shader with the compiler of this project. These are the Vertex stage results; the Fragment stage works the same way.

using YotsubaShader.GlslSyntax;
using YotsubaShader.GlslSyntax.Types;
using YotsubaShader.Language;

namespace MyShaders;

public class Triangle
{
    public struct Corner
    {
        [location(0)] public vec2 Position;
        [location(1)] public vec4 Color;
    }

    public struct Pixel
    {
        [gl_Position] public vec4 Position;
        [location(0)] public vec4 Color;
    }

    public struct PixelIn
    {
        [location(0)] public vec4 Color;
    }

    [ShaderStage(Stage.Vertex)]
    public Pixel Vertex(Corner corner)
    {
        Pixel pixel;
        pixel.Position = Make.Vec4(corner.Position.X, corner.Position.Y, 0f, 1f);
        pixel.Color = corner.Color;
        return pixel;
    }

    [ShaderStage(Stage.Fragment)]
    [return: location(0)]
    public vec4 Fragment(PixelIn pixel)
    {
        return pixel.Color;
    }
}

We also compiled the same shader written in each of the five styles: the GLSL, GLSL ES, Metal and C++ files come out identical, character by character. HLSL and SPIR-V keep the names you wrote, so in those two the only differences are the names you chose, for example the "TEXCOORD0" that SPIR-V remembers in a UserSemantic line when you write in the HLSL style.

What you learned#

  • Everything is drawn with triangles, and each corner is a vertex.
  • Your game sends the vertices, each with the data you decide.
  • For the GPU the screen goes from -1 to 1, with (0, 0) in the center and Y pointing up.
  • The Vertex function runs once per vertex. It returns the final position and lets data through.
  • The GPU spreads that data among the pixels. That is why each pixel receives a different value.
  • The Fragment function runs once per pixel and returns its color: four numbers from 0 to 1.
  • The data travels in numbered slots, and each of the three doors has its own, starting at 0.

In the next chapter you get the project ready, and in the one after that you write these five things in C#. You will see that each one is very few lines.

Next: Set up your project.