Yotsuba ShaderLearn

FNA

16 min read

Draw the shaders you made in the tutorial in a FNA window.

In the Get Started you made your shaders in a library that knows nothing about FNA. They compiled, and you saw the result as text in the console. Here you take the step that was missing: seeing them in a FNA window.

A sunset gradient: pink at the top, orange in the middle and yellow at the bottom

That is what will show up in your window in a few minutes, and the Gradient you wrote yourself is what will draw it.

What you are going to do#

You are going to add one more project to your folder: the game.

Tutorial/
├── MyShaders/       your shaders
├── TryIt/            the console program from the tutorial
└── MyGame/           new: a FNA window that uses your shaders

The path has three parts:

  1. Prepare your shaders for FNA. One command, in step 0.
  2. Create the game. A new project with FNA installed (steps 1 to 3).
  3. See them. You run the game and your shader shows up (steps 4 to 6).

You will see one word a lot: plugin. A plugin is an extension of the yotsuba tool. Without it, yotsuba knows how to prepare shaders for OpenGL, DirectX, Metal and Vulkan, but not for FNA. With the FNA plugin, it learns. You do not write it, and your game does not use it: only yotsuba uses it, while it compiles.

0. Prepare your shaders for FNA#

This step is short, but do not skip it: without it, your game will have no way to ask for the shader.

Your shaders go into yotsuba add, the FNA plugin helps it, and YotsubaShader.g.cs comes out with the ToFNA_FX method. Your game calls that method

The command#

From the Tutorial folder:

dotnet yotsuba add MyShaders/MyShaders.csproj --target spirv --target fna

It is the same command as always, with one more part:

  • --target spirv is what you already used.
  • --target fna means "and prepare them also for FNA".

The first time, yotsuba downloads the FNA plugin from the internet by itself. You do not install anything. The next times it uses the copy it saved.

Check that it worked#

Open MyShaders/YotsubaShader.g.cs. It is a file that the command wrote. Look for ToFNA_FX: there must be one for each of your shader classes. That method is the one your game will use in step 3.

If you cannot find it, the command did not have --target fna. Run it again with it.

What the plugin makes#

The plugin makes an FNA effect, in the .fxb format that XNA always used. You do not need any Windows tool. There is only one version, so you do not choose a platform.

Optional: make it run by itself#

Every time you change a shader you would have to repeat the command. To make it happen on its own when you build, open MyShaders/MyShaders.csproj and add this just before the closing </Project>. The rest of the file stays as it is:

  <Target Name="CompileShaders" BeforeTargets="CoreCompile" Condition="'$(DesignTimeBuild)' != 'true'">
    <Exec Command="dotnet yotsuba add &quot;$(MSBuildProjectFullPath)&quot; --target spirv --target fna" />
    <ItemGroup>
      <Compile Remove="YotsubaShader.g.cs" />
      <Compile Include="YotsubaShader.g.cs" />
    </ItemGroup>
  </Target>

What each part says:

  • BeforeTargets="CoreCompile": "do this right before compiling the C#".
  • Exec: it is the same command you typed by hand.
  • Condition: your editor builds the project in the background while you type. This keeps the command from running on every keystroke.
  • Compile Remove and Compile Include: they add YotsubaShader.g.cs to the build even if it does not exist yet.

From now on, dotnet build MyShaders runs the command for you.

Other plugin commands#

If you want to download the plugin before (for example, to work without internet), use dotnet yotsuba plugin install fna. And dotnet yotsuba plugin list shows which ones you have. There is more in The CLI.

1. Create the game and install the engine#

From the Tutorial folder:

dotnet new console -n MyGame -f net8.0

Install FNA:

dotnet add MyGame package FNA.SDL3

And tell it that it is going to use your shaders:

dotnet add MyGame reference MyShaders/MyShaders.csproj

FNA.SDL3 brings FNA itself and the native libraries it needs (SDL3 and FNA3D) for Windows (x64 and arm64) and macOS. FNA has no Content Pipeline of its own in this guide either: your shader reaches the game as bytes inside your own library.

You did not install any Yotsuba Shader package for FNA.

2. The rectangle that covers the screen#

In the tutorial you saw that a shader does not draw "the screen": it draws a shape, and to paint the whole screen we use a rectangle that covers it. That rectangle has four corners, and each corner carries the two pieces of data you declared in Corner:

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

Now it is the game's turn to send those corners. For that, FNA asks for a struct that says how each one is made. Create MyGame/ScreenCorner.cs:

MyGame/ScreenCorner.cs
using Microsoft.Xna.Framework;
using Microsoft.Xna.Framework.Graphics;

public readonly struct ScreenCorner(Vector2 position, Vector2 uv) : IVertexType
{
    private static readonly VertexDeclaration Declaration = new(
        new VertexElement(0, VertexElementFormat.Vector2, VertexElementUsage.TextureCoordinate, 0),
        new VertexElement(8, VertexElementFormat.Vector2, VertexElementUsage.TextureCoordinate, 1));

    public readonly Vector2 Position = position;
    public readonly Vector2 Uv = uv;

    VertexDeclaration IVertexType.VertexDeclaration => Declaration;
}

(FNA keeps the XNA names, so the using lines say Microsoft.Xna.Framework even though you are not using Microsoft's XNA.)

The two fields are the same ones as in Corner: the position and the Uv. What is new is the VertexDeclaration, which is FNA's way of explaining to the GPU what is in each corner. Each line describes one field:

new VertexElement(0, VertexElementFormat.Vector2, VertexElementUsage.TextureCoordinate, 0),
  • The first 0 is the byte where the field starts. Position comes first, so it starts at 0.
  • Vector2 is its type: two float.
  • TextureCoordinate and the last 0 are the slot. This is the important part.

And the second line, the one for Uv, starts at byte 8 because the two float of Position come first, and they take 4 bytes each.

IVertexType is the interface that lets FNA ask your struct for that declaration. And readonly struct with a primary constructor is just a short way to write a struct whose fields are set once.

From [location] to TextureCoordinate#

In your shader the slots have only a number: [location(0)], [location(1)]. In FNA they have a name and a number. Yotsuba Shader makes the translation like this:

In your shaderIn FNA
[location(0)]TextureCoordinate, number 0
[location(1)]TextureCoordinate, number 1
[location(2)]TextureCoordinate, number 2

That is: the name is always TextureCoordinate, and the number is the one from your location.

3. The game#

Delete what MyGame/Program.cs has and leave only this, which creates the game and starts it:

MyGame/Program.cs
using var game = new MyGame();
game.Run();

Now create MyGame/MyGame.cs:

MyGame/MyGame.cs
using Microsoft.Xna.Framework;
using Microsoft.Xna.Framework.Graphics;
using MyShaders;
using YotsubaShader;

public class MyGame : Game
{
    private readonly GraphicsDeviceManager _graphics;
    private Effect _shader = null!;

    private readonly ScreenCorner[] _screen =
    [
        new(new Vector2(-1f,  1f), new Vector2(0f, 0f)),
        new(new Vector2( 1f,  1f), new Vector2(1f, 0f)),
        new(new Vector2(-1f, -1f), new Vector2(0f, 1f)),
        new(new Vector2( 1f, -1f), new Vector2(1f, 1f)),
    ];

    public MyGame()
    {
        _graphics = new GraphicsDeviceManager(this)
        {
            PreferredBackBufferWidth = 800,
            PreferredBackBufferHeight = 800,
        };
    }

    protected override void LoadContent()
    {
        byte[] compiled = new Gradient().ToFNA_FX();
        _shader = new Effect(GraphicsDevice, compiled);
    }

    protected override void Draw(GameTime gameTime)
    {
        GraphicsDevice.RasterizerState = RasterizerState.CullNone;

        _shader.CurrentTechnique.Passes[0].Apply();
        GraphicsDevice.DrawUserPrimitives(PrimitiveType.TriangleStrip, _screen, 0, 2);

        base.Draw(gameTime);
    }
}

The first lines say where each thing comes from: Microsoft.Xna.Framework has Game, Vector2 and GameTime; ...Graphics has Effect, GraphicsDevice and the drawing types; MyShaders is your library; and YotsubaShader is the namespace of the generated file (where ToFNA_FX lives).

There are three parts that matter for Yotsuba Shader. After them, a section explains what each FNA piece does.

The four corners#

_screen is the rectangle. Each line is a corner, with its position and its Uv:

new(new Vector2(-1f,  1f), new Vector2(0f, 0f)),   // top left
new(new Vector2( 1f,  1f), new Vector2(1f, 0f)),   // top right
new(new Vector2(-1f, -1f), new Vector2(0f, 1f)),   // bottom left
new(new Vector2( 1f, -1f), new Vector2(1f, 1f)),   // bottom right

For the GPU the screen goes from -1 to 1, with (0, 0) in the center and the 1 of Y at the top. That is why the positions are -1 and 1: they are the edges of the screen. The Uv are the ones you saw in the tutorial: (0, 0) at the top left and (1, 1) at the bottom right.

Loading the shader#

This is the part that joins the two worlds:

byte[] compiled = new Gradient().ToFNA_FX();
_shader = new Effect(GraphicsDevice, compiled);

new Gradient() is your shader, the class you wrote. ToFNA_FX is the method that add put on your class for FNA. It returns the shader already compiled, in the format FNA reads. That is why Effect accepts it directly.

There is no .fx file, no Content folder and no separate step to compile. The shader already comes inside your library.

Drawing#

GraphicsDevice.RasterizerState = RasterizerState.CullNone;

_shader.CurrentTechnique.Passes[0].Apply();
GraphicsDevice.DrawUserPrimitives(PrimitiveType.TriangleStrip, _screen, 0, 2);
  • Apply() tells the GPU: "from now on, draw with this shader".
  • DrawUserPrimitives sends the four corners. The GPU does not know how to draw rectangles, only triangles, so the rectangle goes as two triangles glued together. That is TriangleStrip, and the 2 at the end is how many triangles there are.
  • CullNone asks the GPU not to discard any triangle. Normally it discards the ones that "face backwards", which in a 3D game are the faces you cannot see. Here there is nothing to hide.

What each FNA piece does#

This part is about FNA, not about Yotsuba Shader, but without it the game above is a block you copy without understanding. Read it once.

Game and its cycle. Your class inherits from Game. When Program.cs calls Run(), FNA opens the window and repeats a cycle until the window closes. You do not call the steps: you override the ones you need.

Run starts the game; Initialize and LoadContent run once; then Update and Draw repeat every frame until the window closes

protected override void Initialize()  { /* once, before the window shows */ base.Initialize(); }
protected override void LoadContent() { /* once, when the graphics are ready */ }
protected override void Update(GameTime gameTime) { /* every frame: logic */ base.Update(gameTime); }
protected override void Draw(GameTime gameTime)   { /* every frame: drawing */ base.Draw(gameTime); }
MethodWhen it runsIn this guide
InitializeOnce, at the start.Not used.
LoadContentOnce, right after the graphics device exists.We create the Effect here, because it needs the GraphicsDevice.
UpdateEvery frame, before drawing. Usually 60 times per second.Not used yet.
DrawEvery frame, after Update.We draw the rectangle.

base.Draw(gameTime) calls the original version of Draw that Game has. Here it does nothing visible, but it is good to keep it: it is what draws any component you add to the game later.

GraphicsDeviceManager. It is the object that creates and configures the window and the graphics card connection. You build it in the constructor, passing the game (this). The two PreferredBackBuffer... lines set the size of the drawing area: 800 by 800 pixels. If you do not set them, FNA uses 800 by 480.

GraphicsDevice. It is a property that Game has once the manager has created it. It represents the graphics card: everything you draw goes through it. That is why new Effect(GraphicsDevice, ...) asks for it, and why you cannot create the Effect in the constructor (the device does not exist yet): that is the reason for LoadContent.

Effect. It is a compiled shader that FNA can use. It holds the vertex and fragment code, together, and its parameters. The three things you use:

_shader.CurrentTechnique          // the set of steps that draws with this effect
_shader.CurrentTechnique.Passes[0] // the first (and, here, only) step
_shader.Parameters["Name"]         // a value you can change from C#

An effect can have several techniques with several passes. The ones Yotsuba Shader generates have one technique with one pass, so Passes[0] is always the one.

GameTime. It is what FNA passes to Update and Draw to tell you about time. gameTime.TotalGameTime is how long the game has been open, and gameTime.ElapsedGameTime is how long the last frame took. In step 6 you use the first one.

DrawUserPrimitives. It sends vertices from an array in memory straight to the GPU, and draws them. It is the simplest way to draw, and it is perfect for four corners. For thousands of vertices, FNA has VertexBuffer and IndexBuffer, which keep the data in the GPU memory so it is not sent every frame. For a rectangle you do not need them.

Closing the window. Your game has no way to close except the window's own button. If you want Esc to close it, add an Update:

protected override void Update(GameTime gameTime)
{
    if (Keyboard.GetState().IsKeyDown(Keys.Escape))
    {
        Exit();
    }

    base.Update(gameTime);
}

Keyboard and Keys are in Microsoft.Xna.Framework.Input, so you also add that using.

What you will not need. FNA also has SpriteBatch (for drawing 2D images, with its own shader), Content.Load (to read files from the Content Pipeline) and Texture2D. This guide uses none of them: you draw the rectangle yourself, and the shader is already in memory. When textures work in the compiler, Texture2D will come in.

4. Run it#

dotnet run --project MyGame

A window opens with the sunset. That color was calculated by your Fragment method, pixel by pixel, on the GPU.

5. Change the shader#

Changing shader means changing one word. In LoadContent, where it says Gradient, put Mandelbrot:

byte[] compiled = new Mandelbrot().ToFNA_FX();

Run again:

dotnet run --project MyGame

The Mandelbrot set: a black figure shaped like a heart with a circle attached, surrounded by a bright border over a dark blue background

The same rectangle, the same four corners, and a completely different drawing. Everything that changed is inside the shader.

6. A shader that moves#

Until here the window shows a still image. For something to move, the game has to send the shader a value that changes: the time. In the tutorial you saw it in Shader 4: that data is called a uniform.

You are going to make a strip of light that crosses the screen from left to right:

Second 0.3Second 1Second 1.7
An orange vertical strip near the left edge, over a blue backgroundThe same strip, in the centerThe same strip, near the right edge

The shader#

Create MyShaders/Sweep.cs:

MyShaders/Sweep.cs
using YotsubaShader.GlslSyntax;
using YotsubaShader.GlslSyntax.Resources;
using YotsubaShader.GlslSyntax.Types;
using YotsubaShader.Language;

namespace MyShaders;

public struct Stopwatch
{
    public float Seconds;
}

public class Sweep
{
    [uniform, layout(0, 0)]
    public Stopwatch Time;

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

    [ShaderStage(Stage.Fragment)]
    [return: location(0)]
    public vec4 Fragment(PixelIn pixel)
    {
        float center = Time.Seconds * 0.5f;

        float distance = pixel.Uv.X - center;
        if (distance < 0f)
        {
            distance = -distance;
        }

        float brightness = 1f - distance * 5f;
        if (brightness < 0f)
        {
            brightness = 0f;
        }

        return Make.Vec4(brightness, brightness * 0.5f, 0.15f + 0.35f * pixel.Uv.Y, 1f);
    }
}

The Vertex method is the usual one. What is new:

  • Stopwatch is a normal struct with the piece of data the game is going to send.
  • [uniform, layout(0, 0)] public Stopwatch Time; declares that data inside the shader.
  • In Fragment, center is where the strip is right now, from 0 (left edge) to 1 (right edge). distance is how far this pixel is from the strip, and the if removes the sign. The farther away, the less brightness.

Build it with add, like in the tutorial, asking for the plugin as in step 0:

dotnet yotsuba add MyShaders/MyShaders.csproj --target spirv --target fna

If you added the Target from step 0, you do not need to: it runs when you build the game.

The game sends it the time#

In MyGame/MyGame.cs two things change: which shader is loaded, and two new lines in Draw. The complete file looks like this:

MyGame/MyGame.cs
using Microsoft.Xna.Framework;
using Microsoft.Xna.Framework.Graphics;
using MyShaders;
using YotsubaShader;

public class MyGame : Game
{
    private readonly GraphicsDeviceManager _graphics;
    private Effect _shader = null!;

    private readonly ScreenCorner[] _screen =
    [
        new(new Vector2(-1f,  1f), new Vector2(0f, 0f)),
        new(new Vector2( 1f,  1f), new Vector2(1f, 0f)),
        new(new Vector2(-1f, -1f), new Vector2(0f, 1f)),
        new(new Vector2( 1f, -1f), new Vector2(1f, 1f)),
    ];

    public MyGame()
    {
        _graphics = new GraphicsDeviceManager(this)
        {
            PreferredBackBufferWidth = 800,
            PreferredBackBufferHeight = 800,
        };
    }

    protected override void LoadContent()
    {
        byte[] compiled = new Sweep().ToFNA_FX();
        _shader = new Effect(GraphicsDevice, compiled);
    }

    protected override void Draw(GameTime gameTime)
    {
        GraphicsDevice.RasterizerState = RasterizerState.CullNone;

        float seconds = (float)(gameTime.TotalGameTime.TotalSeconds % 2.0);
        _shader.Parameters["Time_Seconds"].SetValue(seconds);

        _shader.CurrentTechnique.Passes[0].Apply();
        GraphicsDevice.DrawUserPrimitives(PrimitiveType.TriangleStrip, _screen, 0, 2);

        base.Draw(gameTime);
    }
}

The two new lines:

float seconds = (float)(gameTime.TotalGameTime.TotalSeconds % 2.0);
_shader.Parameters["Time_Seconds"].SetValue(seconds);

The first one gets how many seconds the game has been open. The % 2.0 makes it go back to 0 every two seconds, so the strip starts again from the left.

The second one hands that number to the shader. The name "Time_Seconds" is not made up, it comes from your code: it is the name of the field, an underscore and the name of the data.

In your shaderIn FNA
public Stopwatch Time; with a Seconds piece of dataParameters["Time_Seconds"]

It has to be done before Apply(), because Apply() is the moment when the data travels to the GPU.

SetValue has a version for each type you can have in a struct:

In your shaderWhat you pass to SetValue
floatA float
intAn int
vec2A Vector2
vec3A Vector3
vec4A Vector4
mat4A Matrix

If the name does not match any parameter, Parameters["..."] gives you null, and the line fails with a NullReferenceException. When you are not sure the shader uses that value (for example, a shader that does not read the time), write ?.SetValue(...) and the line is skipped instead.

Run:

dotnet run --project MyGame

The strip crosses the screen again and again.

The native libraries of FNA#

FNA is a C# layer on top of native libraries (SDL3 for the window and the keyboard, FNA3D for the graphics). If those libraries are not next to your program, the game stops at the start with a DllNotFoundException.

SystemWhat you need
Windows x64 / arm64Nothing: FNA.SDL3 already brings them.
macOSNothing: FNA.SDL3 already brings them.
LinuxThe fnalibs that FNA publishes, copied next to your program.

If you use the official FNA instead of FNA.SDL3, you need the fnalibs on every system.

If something fails#

What you seeWhat it meansWhat to do
ToFNA_FX does not existThe generated file does not have it: add ran without the plugin.Run add with --target fna (step 0), or add it to the Target of the .csproj.
add fails with a message about a shaderOne of your shaders cannot be compiled for the GPU yet (for example Neon, Plasma or Underwater from the tutorial).Move that file out of the MyShaders folder for now.
add finishes, but running the game throws NotSupportedExceptionThe plugin could not compile that shader. add does not fail, it leaves the method ready to report the reason.Run add again and read what it prints: it says which shader and why.
The rectangle is deformed or does not show upThe corners use VertexElementUsage.Position.Use TextureCoordinate with the number of your location (step 2).
NullReferenceException in Parameters[...].SetValueThe name does not exist in the shader.The name is Field_Data: check both against your struct (step 6).
The window opens and stays blackApply() or DrawUserPrimitives are missing, or the shader returns black.Check step 3 and make sure the Fragment returns a color with 1 in the last value.
The first add with the plugin fails with a network errorThe CLI is downloading the plugin and cannot reach NuGet.Check your connection, or use dotnet yotsuba plugin install fna when you are online.

What is not possible yet#

Summary#

Of everything you did, what belongs to FNA is this:

The plugin (for the CLI)fna
The add commanddotnet yotsuba add MyShaders/MyShaders.csproj --target spirv --target fna
The package (for the game)FNA.SDL3
The methodToFNA_FX()

The rest is the same in MonoGame, KNI and FNA, because the three share the same way of programming:

  • The corners are declared with TextureCoordinate and the number of your [location].
  • The shader is loaded with new Effect(GraphicsDevice, bytes).
  • The data of a uniform is sent with Parameters["Field_Data"].SetValue(...), before Apply().

And your MyShaders library did not change at all to work here, except for asking for the plugin when you build it.