April 10, 2023
This tutorial is an updated version of my previous one and updates the code listing to match the finalizing WebGPU APIs. If you’ve read the previous version of this tutorial you can skim through the code listings to get up to date. For an easy way to get started, I recommend grabbing my WebGPU + webpack starter template which includes the code from this tutorial. You can start by deleting the code there and rewriting it following this tutorial, or follow along in the code as you read this page. The code for the blog series is also available on GitHub.
WebGPU is a modern graphics API for the web, in development by the major browser vendors. When compared to WebGL, WebGPU provides more direct control over the GPU to allow applications to leverage the hardware more efficiently, similar to Vulkan and DirectX 12. WebGPU also exposes additional GPU capabilities not available in WebGL, such as compute shaders and storage buffers, enabling powerful GPU compute applications to run on the web. As with the switch from OpenGL to Vulkan, WebGPU exposes more complexity to the user than WebGL, though the API strikes a good balance between complexity and usability, and overall is quite nice to work with. In this series, we’ll learn the key aspects of WebGPU from the ground up, with the goal of going from zero to a basic glTF model renderer. This post marks our initial step on this journey, where we’ll setup a WebGPU context and get a triangle on the screen.
The first step to working with WebGPU is to setup a browser with it enabled. Chrome, Firefox, and Safari’s implementations are still in progress, and as such we need to use the corresponding nightly browsers provided by the vendors. At the time of writing, I’ve found that Chrome Canary has the most complete implementation, and recommend using it for development. You’ll also need to enable the WebGPU feature in the nightly browser, following the guides here. Since browser support is still in progress, you’ll want to disable WebGPU during regular web browsing. You can check if you’ve got WebGPU enabled by jumping to the bottom of this post, where you should see the triangle we’re going to be rendering. If WebGPU isn’t enabled, you’ll see an error message instead. There will be an origin trial starting in Chrome 94, which you can register your domain to use to run WebGPU applications on official Chrome releases.
The triangle renderer we’ll implement in this post will work in both Chrome Canary and Firefox Nightly; however, the WebGPU implementation in Safari Technology Preview looks to possibly be on an older version of the spec, and has some differences in default parameters and the vertex buffer specificiation APIs. Thus, the code we discuss here will not work in Safari for now, but can be made to work with some smaller tweaks.
The initial setup of our WebGPU rendering context is similar to WebGL.
Our webpage will have a canvas to display our rendered image,
and load our rendering code from
A number of the APIs used to interact with the GPU are
we’ll place our rendering code inside an
function which is executed when the script is loaded.
Our first step is to get a
from the WebGPU API. Each adapter represents a GPU on the machine
and the browser’s implementation of WebGPU on top of that GPU.
We can then request a
from the adapter, which gives us a context to work with the hardware.
GPUDevice provides APIs to create GPU objects such as buffers and textures, and
execute commands on the device. The distinction between the
GPUDevice is similar to that of
VkDevice in Vulkan.
As with WebGL, we need a context for the canvas which will
be used to display our rendered image. To use WebGPU with the
canvas, we request a
webgpu context (Safari calls it a
After this setup, we can load our shaders and vertex
data, configure our render targets, and build our render pipeline, to draw
The WebGPU rendering pipeline consists of two programmable stages: the vertex shader and the fragment shader, similar to WebGL. WebGPU also adds support for compute shaders, which exist outside the rendering pipeline.
To render our triangle, we’ll need to configure such a pipeline,
specifying our shaders, vertex attribute configuration, etc.
In WebGPU, this pipeline takes the form of a concrete object, the
which specifies the different pieces of the pipeline.
The configuration of the components of this pipeline (e.g., the shaders,
vertex state, render output state, etc.) are fixed, allowing the GPU
to better optimize rendering for the pipeline. The buffers
or textures bound to the corresponding inputs or outputs can be changed;
however, the number of inputs and outputs, and their types, etc. cannot be changed.
This is in contrast to WebGL, where the pipeline state for a draw
is implicitly specified through modifying a global state machine,
and the shaders, vertex state, etc., can be swapped out at any time
between draw calls, making it challenging to optimize the pipeline.
Our first step in creating the pipeline is to create the vertex and fragment shader modules, which will be executed in the pipeline. WebGPU shaders are written in WGSL. Our shader for this application is relatively simple. We define a struct for our vertex data input and output format and pass through positions and colors from the input to the outputs.
We pass a string containing our WGSL code to the
method to compile them. We can check the compilation info of the resulting
shader module to see if any error occured that caused the shader to fail to
Next, we’ll specify the vertex data for our triangle.
We’ll specify both the vertex positions and colors in a single
buffer, with the positions and colors interleaved with each other.
Each position and color will be stored as a
First, we allocate and map a buffer on the device with enough
room to store the vertex data, using
This method takes the size (in bytes) of the buffer we want
to create and a set of flags or’d together specifying the
desired usage modes of the buffer.
We specify the buffer should be mapped when it’s created by setting the
createBuffer returns the
GPUBuffer and an
we can use to upload data into the buffer.
To write our vertex data we create a
Float32Array view of the array buffer
and set the data through this view.
Finally, we have to unmap the buffer before using it later in rendering.
To tell the GPU how to pass the vertex data to our shader, we’ll
as part of the rendering pipeline when we create it.
This object specifies both the shader we want to run and how the attribute
inputs to this shader should be filled with data from our vertex buffers.
We specify how the vertex buffers should be interpreted by passing
an array of
objects. Each entry describes the vertex attributes to be read from
the vertex buffer bound to the corresponding slot at render time.
In this example, we have a single buffer containing the interleaved
attributes of each vertex. Thus, the stride between elements is 32 bytes (2
and the buffer specifies two
The first attribute is the position, and is sent to shader input location 0.
The second is the color, and is sent to shader input location 1.
WebGPU’s model for specifying vertex buffers and attributes follows that of D3D12 and Vulkan,
where vertex buffers are bound to input slots and provide some set of vertex attributes,
From a D3D12 view, the
vertexBuffers member maps to the array of
structures passed through the
when creating a graphics pipeline.
From a Vulkan view, the
vertexBuffers member maps directly to the
structure passed when creating a graphics pipeline.
Next we’ll create a swap chain and specify where the results output from our fragment
shader should be written.
To display the images on our canvas, we need a swap chain associated with its context.
The swap chain will let us rotate through the images being displayed on the canvas,
rendering to a buffer which is not visible while another is shown (i.e., double-buffering).
We create a swap chain by specifying the desired image format and texture usage.
The swap chain will create one or more textures for us, sized to match the canvas
they’ll be displayed on.
Since we’ll be rendering directly to the swap chain textures, we specify that
they’ll be used as output attachments.
The swap chain is no longer an explicit object in WebGPU, but is managed internally
by the context. To set up the swap chain we call
configure, and pass
the swap chain parameters.
Although in this example we’re just drawing a single triangle, we’ll still create and use a depth texture since we’ll need it later on. The depth texture is created as a regular texture, specifying the size, format, and usage. As before, we’ll be rendering directly to this texture and thus specify it will be used as an output attachment.
The analog to our GPUVertexState for the fragment shader stage is
This object specifies the fragment shader to be run and what format the
textures it will write its outputs to will be in. The render targets are
specified in order to match the output locations in the shader,
similar to how the vertex inputs and buffer slots were specified previously.
We’ll be rendering directly to the swap chain, so we have just one render
target whose format is the swap chain format.
Finally, we can create the rendering pipeline that combines our
shaders, vertex attributes, and output configuration, which we can
use to render our triangle. The rendering pipeline description is
passed through a
object, passed to
The final pieces we need for our rendering pipeline are
the pipeline layout, which specifies the bind group layouts used by the pipeline;
and the depth/stencil state.
The primitive topology is also be specified in this structure; however, the default
triangle-list, which is already what we need.
Rendering in WebGPU takes place during a Render Pass, which is
described through a
The render pass descriptor specifies the images to bind to the targets
that will be written to in the fragment shader, and optionally a depth buffer
and the occlusion query set. The color and depth attachments specified must
match the color and depth states specified for the render pipelines used in the render pass.
Our fragment shader writes to a single output slot, the object color, which we’ll write
to the current swap chain image. As the image will change each frame
to the current swap chain image, we don’t set it just yet.
All that’s left to do is write our rendering loop, and pass it to
to call it each frame to update the image.
To record and submit GPU commands, we use a
The command encoder can be used to prerecord and command buffers that can
be submitted multiple times to the GPU, or rerecord and submit each frame.
As we’ll be changing the render pass color attachment each frame, we’ll be
rerecording and submitting the command buffer each frame.
For each frame, we get the latest swap chain image which we should write rendering outputs
to and set this as our output color attachment image.
We then create a command encoder to record our rendering commands.
We begin the render pass by calling
beginRenderPass and passing our render pass descriptor
to get back a
that will allow us to record rendering commands.
We can then set the render pipeline to use, bind our vertex buffers to the
corresponding input slots, draw the triangle, and end the render pass.
To get a command buffer which can be submitted to the GPU for execution
finish on the command encoder. The returned command buffer
is then passed to the device for execution. After the command buffer is run
our triangle will be written to the swap chain image and displayed on the
canvas as shown below!
With our first triangle on screen, we’re well on our way to getting a basic glTF model viewer together. In the next post, we’ll look at how to pass additional data to our shaders (e.g., uniform buffers), using bind groups. If you run into issues getting the example to work, check out the code for rendering the triangle in Figure 3, or get in touch via Twitter or email.
Although WebGPU is in its early stages, here are a few useful resources which are also worth checking out: