Hello Triangle 🟢¶

With webgpu.hpp

Resulting code: step030

Vanilla webgpu.h

Resulting code: step030-vanilla

In its overall outline, drawing a triangle is as simple as this:

With webgpu.hpp

// Select which render pipeline to use
renderPass.setPipeline(pipeline);
// Draw 1 instance of a 3-vertices shape
renderPass.draw(3, 1, 0, 0);

Vanilla webgpu.h

// Select which render pipeline to use
wgpuRenderPassEncoderSetPipeline(renderPass, pipeline);
// Draw 1 instance of a 3-vertices shape
wgpuRenderPassEncoderDraw(renderPass, 3, 1, 0, 0);

What is a bit verbose is the configuration of the render pipeline, and the creation of shaders. This is done only once when initializing the application.

Shaders¶

Both the vertex and fragment programmable stages use the same shader module, that we must first create. This module is kind of a dynamic library (like a .dll, .so or .dylib file), except that it talks the binary language of your GPU rather than your CPU’s.

Like any compiled program, the shader is first written in a human-writable programming language, then compiled into low-level machine code. However, the low-level code is highly hardware-dependent, and often not publicly documented. So the application is distributed with the source code of the shaders, which is compiled on the fly when initializing the application.

Shader code¶

The shader language officially used by WebGPU is called WGSL, namely the WebGPU Shading Language. Any implementation of WebGPU must support it, and the JavaScript version of the API only supports WGSL, but the native header webgpu.h also offers the possibility to provide shaders written in SPIR-V or GLSL (wgpu-native only).

Tip

SPIR-V is more of an intermediate representation, i.e., a bytecode, than something that one would write manually. It is the shader language used by the Vulkan API and a lot of tools exist to cross-compile code from other common shader languages (HLSL, GLSL) so it is an interesting choice when one needs to reuse existing shader code bases.

Note

Also note that WGSL was originally designed to be a human-editable version of SPIR-V programming model, so transpilation from SPIR-V to WGSL is in theory efficient and lossless (use Naga or Tint for this).

In this guide, we will only use WGSL. Its syntax may seem a bit unfamiliar if you are used to C/C++ so let us start with a very simple function and its equivalent in C++:

// In WGSL
fn my_addition(x: f32, y: f32) -> f32 {
    let z = x + y;
    return z;
}

// In C++
float my_addition(float x, float y) {
    auto z = x + y;
    return z;
}

Notice how the types are specified after instead of before the argument names. The type of z is automatically inferred, though we could have forced it using let z: f32 = .... The return type is specified after the arguments, using the arrow ->.

Note

The keyword let defines a constant, i.e., a variable that cannot be reassigned. A regular variable is defined using the var keyword.

Now here is the shader for our triangle:

@vertex
fn vs_main(@builtin(vertex_index) in_vertex_index: u32) -> @builtin(position) vec4f {
    var p = vec2f(0.0, 0.0);
    if (in_vertex_index == 0u) {
        p = vec2f(-0.5, -0.5);
    } else if (in_vertex_index == 1u) {
        p = vec2f(0.5, -0.5);
    } else {
        p = vec2f(0.0, 0.5);
    }
    return vec4f(p, 0.0, 1.0);
}

@fragment
fn fs_main() -> @location(0) vec4f {
    return vec4f(0.0, 0.4, 1.0, 1.0);
}

The function names vs_main (resp. fs_main) must have the very same name as what was specified as entryPoint in the vertex (resp. fragment) state.

Note

Shader languages natively support vector and matrix types up to size 4. The type vec2f is a vector of 2 floats, and an alias for the templated type vec2<f32>. As another example, the type vec4<u32> is a vector of 4 unsigned integers and has alias vec4u.

Tokens that start with an @ are called attributes and decorate the object that comes afterward with various information. For instance, @builtin(vertex_index) tells that the argument in_vertex_index will be populated by the built-in input vertex attribute that is the vertex index. Note that the argument in_vertex_index could have had any other name: as long as it is decorated with the same built-in attribute, it has the same semantics.

We use this vertex index to set the output value of the shader. This output is labelled with the @builtin(position) attribute to mean that it must be interpreted by the rasterizer as the vertex position.

For more flexibility, the shader code should be loaded from a file, but for now we simply store it in a multi-line string literal in our main.cpp:

const char* shaderSource = R"(
{{The WGSL shader source code}}
)";

{{Includes}}
{{Global declarations}}
{{Application class}}
{{Main function}}
{{Application implementation}}

{{Shader source literal}}

Creation of a shader module¶

The creation of the shader module starts as usual:

With webgpu.hpp

ShaderModuleDescriptor shaderDesc;
{{Describe shader module}}
ShaderModule shaderModule = device.createShaderModule(shaderDesc);

Vanilla webgpu.h

WGPUShaderModuleDescriptor shaderDesc{};
{{Describe shader module}}
WGPUShaderModule shaderModule = wgpuDeviceCreateShaderModule(device, &shaderDesc);

At first glance, this descriptor seems to have only an array of compilation “hints” to fill, which we leave empty (and even nothing at all when using Dawn):

#ifdef WEBGPU_BACKEND_WGPU
shaderDesc.hintCount = 0;
shaderDesc.hints = nullptr;
#endif

But this time, we do not set nextInChain to nullptr!

The nextInChain pointer is the entry point of WebGPU’s extension mechanism. It is either null, or pointing to a structure of type WGPUChainedStruct. This structure is very simple. First it may recursively have a next element (again, either null or pointing to some WGPUChainedStruct). Second, it has a struct type sType, which is an enum telling in which struct the chain element can be cast. Each struct whose definition starts with a field WGPUChainedStruct chain has an associated SType.

To create a shader module from WGSL code, we use the ShaderModuleWGSLDescriptor SType. A SPIR-V shader can similarly be created using the WGPUShaderModuleSPIRVDescriptor.

The field shaderCodeDesc.chain corresponds to the chained struct when cast as a simple WGPUChainedStruct, which must be set to the corresponding SType enum value:

With webgpu.hpp

ShaderModuleWGSLDescriptor shaderCodeDesc;
// Set the chained struct's header
shaderCodeDesc.chain.next = nullptr;
shaderCodeDesc.chain.sType = SType::ShaderModuleWGSLDescriptor;
// Connect the chain
shaderDesc.nextInChain = &shaderCodeDesc.chain;

Vanilla webgpu.h

WGPUShaderModuleWGSLDescriptor shaderCodeDesc{};
// Set the chained struct's header
shaderCodeDesc.chain.next = nullptr;
shaderCodeDesc.chain.sType = WGPUSType_ShaderModuleWGSLDescriptor;
// Connect the chain
shaderDesc.nextInChain = &shaderCodeDesc.chain;

Finally we can setup the actual payload of the shader code descriptor:

shaderCodeDesc.code = shaderSource;

Dawn

The Dawn implementation of WebGPU does not include the hints/hintCount in the shader module descriptor.

Pipeline layout¶

One last thing before we can run our code: the shaders might need to access input and output resources (buffers and/or textures). These resources are made available to the pipeline by configuring a memory layout. Our first example does not use any resource:

pipelineDesc.layout = nullptr;

Note

Actually, setting the pipeline layout to nullptr does not mean that there is no input/output resources. It rather asks the backend to figure out the layout by itself by inspecting the shader (which in this very case is equivalent).

Wrapping up¶

We can now connect the dots! I suggest we initialize our render pipeline in a dedicated method:

{{InitializePipeline method}}

With webgpu.hpp

void Application::InitializePipeline() {
    {{Create Shader Module}}
    {{Create Render Pipeline}}

    // We no longer need to access the shader module
    shaderModule.release();
}

Vanilla webgpu.h

void Application::InitializePipeline() {
    {{Create Shader Module}}
    {{Create Render Pipeline}}

    // We no longer need to access the shader module
    wgpuShaderModuleRelease(shaderModule);
}

As a consequence, we move the declaration of pipeline to the class attributes. We also do the same for the surfaceFormat, that was defined during the surface configuration:

With webgpu.hpp

// In Application class
private:
    RenderPipeline pipeline;
    TextureFormat surfaceFormat = TextureFormat::Undefined;

Vanilla webgpu.h

// In Application class
private:
    WGPURenderPipeline pipeline;
    WGPUTextureFormat surfaceFormat = WGPUTextureFormat_Undefined;

Warning

Make sure not to locally shadow the class-level declaration of pipeline and surfaceFormat by re-declaring them when calling createRenderPipeline and getPreferredFormat respectively.

RenderPipelineDescriptor pipelineDesc;
{{Describe render pipeline}}
pipeline = device.createRenderPipeline(pipelineDesc);

WGPURenderPipelineDescriptor pipelineDesc{};
pipelineDesc.nextInChain = nullptr;
{{Describe render pipeline}}
pipeline = wgpuDeviceCreateRenderPipeline(device, &pipelineDesc);

surfaceFormat = surface.getPreferredFormat(adapter);
config.format = surfaceFormat;
// And we do not need any particular view format:
config.viewFormatCount = 0;
config.viewFormats = nullptr;

surfaceFormat = wgpuSurfaceGetPreferredFormat(surface, adapter);
config.format = surfaceFormat;
// And we do not need any particular view format:
config.viewFormatCount = 0;
config.viewFormats = nullptr;

We also declare our initialization method in the Application declaration:

// In Application class
private:
    void InitializePipeline();

We call it at the end of the Initialize() method:

// At the end of Initialize()
InitializePipeline();

And reciprocally we release the pipeline at the beginning of the Terminate() method:

With webgpu.hpp

// At the beginning of Terminate()
pipeline.release();

Vanilla webgpu.h

// At the beginning of Terminate()
wgpuRenderPipelineRelease(pipeline);

Finally, we insert in the main loop the two lines that this chapter started with, just after creating the renderPass object:

With webgpu.hpp

// Select which render pipeline to use
renderPass.setPipeline(pipeline);
// Draw 1 instance of a 3-vertices shape
renderPass.draw(3, 1, 0, 0);

Vanilla webgpu.h

// Select which render pipeline to use
wgpuRenderPassEncoderSetPipeline(renderPass, pipeline);
// Draw 1 instance of a 3-vertices shape
wgpuRenderPassEncoderDraw(renderPass, 3, 1, 0, 0);

{{Draw a triangle}}

And tadaam! You should finally see a triangle!

../_images/hello-triangle.png — Our first triangle rendered using WebGPU.¶

Dawn

When using Dawn, you may see different colors (more saturated), because the target surface use a different color space. More on this later on.

Conclusion¶

This chapter introduced the core skeleton for rendering triangle-based shapes on the GPU. For now these are 2D graphics, but once everything will be in place, switching to 3D will be straightforward. We have seen two very important concepts:

The render pipeline, which is based on the way the hardware actually works, with some parts fixed, for the sake of efficiency, and some parts are programmable.
The shaders, which are the GPU-side programs driving the programmable stages of the pipeline.

What’s next?¶

The key algorithms and techniques of computer graphics used for 3D rendering are for a large part implemented in the shaders code. What we still miss at this point though is ways to communicate between the C++ code (CPU) and the shaders (GPU).

The next two chapters focus on two ways to feed input to this render pipeline: vertex attributes, where there is one value per vertex, and uniforms, which define variable that are common to all vertices and fragments for a given call.

We then take a break away from pipeline things with the switch to 3D meshes, which is in the end less about code and more about math. We also introduce a bit of interaction with a basic camera controller. We then introduce a 3rd way to provide input resource, namely textures, and how to map them onto meshes.

Storage textures, which are used the other way around, to get data out of the render pipeline, will be presented only in advanced chapters. Instead, the last chapter of this section is fully dedicated to the computer graphics matter of lighting and material modeling.

With webgpu.hpp

Resulting code: step030

Vanilla webgpu.h

Resulting code: step030-vanilla

Hello Triangle 🟢¶

Render Pipeline¶

Vertex pipeline state¶

Primitive pipeline state¶

Fragment shader¶

Stencil/Depth state¶

Blending¶

Multi-sampling¶

Shaders¶

Shader code¶

Creation of a shader module¶

Pipeline layout¶

Wrapping up¶

Conclusion¶

What’s next?¶