ComputeSharp 2.0.0-alpha.1

Major update in the works! 🚀

The currently available NuGet package refers to the 1.x version of ComputeSharp, with the codebase from the master branch. I'm currently working on a new major update targeting .NET 5, featuring a completely rewritten backend using native DirectX bindings and the use of C# source generators to prepare the shader code. This will greatly improve the performance of the library (especially cold start performance, which is over 10x faster already) and use much less memory at runtime. I also plan to introduce support for a number of new features, such as the ability to use custom struct types in shaders. The current status of this work can be seen from the development branches.

Thank you for the support!

What is it?

ComputeSharp is a .NET Standard 2.1 library to run C# code in parallel on the GPU through DX12 and dynamically generated HLSL compute shaders. The available APIs let you allocate GPU buffers and write compute shaders as simple lambda expressions or local methods, with all the captured variables being handled automatically and passed to the running shader.

Table of Contents

• Installing from NuGet
• Quick start
  • Capturing variables
  • Advanced usage
• Requirements
• Special thanks

Installing from NuGet

To install ComputeSharp, run the following command in the Package Manager Console

Install-Package ComputeSharp

More details available here.

Quick start

ComputeSharp exposes a Gpu class that acts as entry point for all public APIs. It exposes the Gpu.Default property that lets you access the main GPU device on the current machine, which can be used to allocate buffers and perform operations.

The following sample shows how to allocate a writeable buffer, populate it with a compute shader, and read it back.

// Define a simple shader
public readonly struct MyShader : IComputeShader
{
    public readonly ReadWriteBuffer<float> buffer;

    public MyShader(ReadWriteBuffer<float> buffer)
    {
        this.buffer = buffer;
    }

    public void Execute(ThreadIds ids)
    {
        buffer[ids.X] = ids.X;
    }
}

// Allocate a writeable buffer on the GPU, with the contents of the array
using ReadWriteBuffer<float> buffer = Gpu.Default.AllocateReadWriteBuffer<float>(1000);

// Run the shader
Gpu.Default.For(1000, new MyShader(buffer));

// Get the data back
float[] array = buffer.GetData();

Capturing variables

If the shader in C# is capturing some local variable, those will be automatically copied over to the GPU, so that the HLSL shader will be able to access them just like you'd expect. Additionally, ComputeSharp can also resolve static fields being used in a shader. The captured variables need to be convertible to valid HLSL types: either scalar types (int, uint, float, etc.) or known HLSL structs (eg. Vector3). Here is a list of the variable types currently supported by the library:

✅ .NET scalar types: bool, int, uint, float, double

✅ .NET vector types: System.Numerics.Vector2, Vector3, Vector4

✅ HLSL types: Bool, Bool2, Bool3, Bool4, Float2, Float3, Float4, Int2, Int3, Int4, UInt2, Uint3, etc.

✅ static fields of both scalar, vector or buffer types

✅ static properties, same as with fields

✅ Func<T>s or delegates with a valid HLSL signature, with the target method being static

✅ Func<T>s, local methods or delegates with no captured variables

✅ static fields and properties with a supported delegate type

Allocating GPU buffers

There are a number of extension APIs for the GraphicsDevice class that can be used to allocate GPU buffers of three types: ConstantBuffer<T>, ReadOnlyBuffer<T> and ReadWriteBuffer<T>. The first is packed to 16 bytes and provides the fastest possible access for buffer elements, but it has a limited maximum size (around 64KB) and requires additional overhead when copying data to and from it if the size of each element is not a multiple of 16. The other buffer types are tightly packed and work great for all kinds of operations, and can be thought of the HLSL equivalent of T[] arrays in C#. If you're in doubt about which buffer type to use, just use either ReadOnlyBuffer<T> or ReadWriteBuffer<T>, depending on whether or not you also need write access to that buffer on the GPU side.

NOTE: although the APIs to allocate buffers are simply generic methods with a T : unmanaged constrain, they should only be used with C# types that are fully mapped to HLSL types. That means either int, uint, float, double, .NET vector types or HLSL types. The bool type should not be used in buffers due to C#/HLSL differences: use the Bool type instead.

Advanced usage

ComputeSharp lets you dispatch compute shaders over thread groups from 1 to 3 dimensions, includes supports for constant and readonly buffers, and more. Additionally, most of the HLSL intrinsic functions are available through the Hlsl class. Here is a more advanced sample showcasing all these features.

// Define a class with some utility static functions
public static class Activations
{
    public static float Sigmoid(float x) => 1 / (1 + Hlsl.Exp(-x));
}

// Define the shader
public readonly struct ActivationShader : IComputeShader
{
    private readonly int width;

    public readonly ReadOnlyBuffer<float> x;
    public readonly ReadWriteBuffer<float> y;

    public ActivationShader(
        int width,
        ReadOnlyBuffer<float> x,
        ReadWriteBuffer<float> y)
    {
        this.width = width;
        this.x = x;
        this.y = y;
    }

    public void Execute(ThreadIds ids)
    {
        int offset = ids.X + ids.Y * width;
        float pow = Hlsl.Pow(x[offset], 2);
        y[offset] = Activations.Sigmoid(pow);
    }
}

int height = 10, width = 10;
float[] x = new float[height * width]; // Array to sum to y
float[] y = new float[height * width]; // Result array (assume both had some values)

using ReadOnlyBuffer<float> xBuffer = Gpu.Default.AllocateReadOnlyBuffer(x); 
using ReadWriteBuffer<float> yBuffer = Gpu.Default.AllocateReadWriteBuffer(y);

// Run the shader
Gpu.Default.For(width, height, new ActivationShader(width, xBuffer, yBuffer));

// Get the data back and write it to the y array
yBuffer.GetData(y);

Requirements

The ComputeSharp library requires .NET Standard 2.1 support, and it is available for applications targeting:

• .NET Core >= 3.0
• Windows (x86 or x64)

Additionally, you need an IDE with .NET Core 3.1 and C# 8.0 support to compile the library and samples on your PC.

Special thanks

The ComputeSharp library is based on some of the code from the DX12GameEngine repository by Amin Delavar. Additionally, ComputeSharp uses NuGet packages from the following repositories (excluding those from Microsoft):

• Vortice.Windows
• ILSpy
• Stubble