⚠️ This lesson is not yet translated in your language, it will be available soon!

WebGPU is a new web standard that provides a low-level API for rendering graphics and performing computations on the GPU. It is designed to be a successor to WebGL, offering better performance and more advanced features.

Great news, it is now possible to use it with Three.js with minimal changes to the codebase.

In this lesson, we will explore how to use WebGPU with Three.js and React Three Fiber, and how to write shaders using the new Three Shading Language (TSL).

If you are new to shaders, I recommend you to first complete the Shaders chapter before continuing with this one.

WebGPU Renderer

To use WebGPU API instead of the WebGL one, we need to use a WebGPURenderer (No dedicated section on Three.js documentation yet) instead of the WebGLRenderer.

With React Three Fiber, when creating a <Canvas> component, the setup of the renderer is done automatically. However, we can override the default renderer by passing a function to the gl prop of the <Canvas> component.

In App.jsx, we have a <Canvas> component that uses the default WebGLRenderer. Let's modify it to use the WebGPURenderer instead.

First, we need to stop the frameloop until the WebGPURenderer is ready. We can do this by setting the frameloop prop to never.

Copy
// ...
import { useState } from "react";

function App() {
  const [frameloop, setFrameloop] = useState("never");

  return (
    <>
      {/* ... */}
      <Canvas
        // ...
        frameloop={frameloop}
      >
        {/* ... */}
      </Canvas>
    </>
  );
}

export default App;

Next, we need to import the WebGPU version of Three.js:

Copy
import * as THREE from "three/webgpu";

When using WebGPU, we need to use the three/webgpu module instead of the default three module. This is because the WebGPURenderer is not included in the default build of Three.js.

Then, we can use the gl prop to create a new WebGPURenderer instance:

Copy
// ...

function App() {
  const [frameloop, setFrameloop] = useState("never");

  return (
    <>
      {/* ... */}
      <Canvas
        // ...
        gl={(canvas) => {
          const renderer = new THREE.WebGPURenderer({
            canvas,
            powerPreference: "high-performance",
            antialias: true,
            alpha: false,
            stencil: false,
            shadowMap: true,
          });
          renderer.init().then(() => {
            setFrameloop("always");
          });
          return renderer;
        }}
      >
        {/* ... */}
      </Canvas>
    </>
  );
}
// ...

We create a new WebGPURenderer instance and pass the canvas element to it. We also set some options for the renderer, such as powerPreference, antialias, alpha, stencil, and shadowMap. These options are similar to the ones used in the WebGLRenderer.

Finally, we call the init() method of the renderer to initialize it. Once the initialization is complete, we set the frameloop state to "always" to start rendering.

Let's see the result in the browser:

Our cube is now rendered using the WebGPURenderer instead of the WebGLRenderer.

It's as simple as that! We have successfully set up a WebGPURenderer in our React Three Fiber application. You can now use the same Three.js API to create and manipulate 3D objects, just like you would with the WebGLRenderer.

The biggest changes is when it comes to writing shaders. The WebGPU API uses a different shading language than WebGL, which means we need to write our shaders in a different way. In WGSL instead of GLSL.

This is where the Three Shading Language (TSL) comes in.

Three Shading Language

TSL is a new shading language that is designed to be used with Three.js to write shaders in a more user-friendly way using a node-based approach.

A great advantage of TSL is that it is renderer-agnostic, meaning that you can use the same shaders with different renderers, such as WebGL and WebGPU.

This makes it easier to write and maintain shaders, as you don't have to worry about the differences between the two shading languages.

It is also future-proof, as if a new renderer is released, we could use the same shaders without any changes as long as TSL supports it.

The Three Shading Language is still in development, but it is already available in the latest versions of Three.js. The best way to learn it, and to keep track of the changes, is to check the Three Shading Language wiki page. I used it extensively to learn how to use it.

Node based materials

To understand how to create shaders with TSL, we need to understand what it means to be node-based.

In a node-based approach, we create shaders by connecting different nodes together to create a graph. Each node represents a specific operation or function, and the connections between the nodes represent the flow of data.

This approach has many advantages, such as:

• Visual representation: It is easier to understand and visualize the flow of data and operations in a shader.
• Reusability: We can create reusable nodes that can be used in different shaders.
• Flexibility: We can easily modify and change the behavior of a shader by adding or removing nodes.
• Extensibility: Adding/Customizing features from existing materials is now a breeze.
• Agnostic: TSL will generate the appropriate code for the target renderer, whether it is WebGL (GLSL) or WebGPU (WGSL).

Before we start coding our first node-based material, we can use the online Three.js playground to experiment with the node-system visually.

Open the Three.js playground and on the top, click on the Examples button, and choose the basic > fresnel one.

You should see a node-based material editor with two color nodes and a float node attached to a fresnel node. (Color A, Color B, and Fresnel Factor)

The fresnel node is connected to the color of the Basic Material resulting in coloring the Teapot with a fresnel effect.

Use the Splitscreen button to preview the result on the right.

Let's say we want to affect the oppacity of the Basic Material based on the time. We can add a Timer node and connect it to a Fract node to reset the time to 0 once it reaches 1. Then we connect it to the opacity input of the Basic Material.

Our teapot is now fading in before disappearing and fading in again.

Take the time to play with the different nodes and see how they affect the material.

Now we have a basic understanding of how the node-based material works, let's see how to use the new node-based material from Three.js in React Three Fiber.

React Three Fiber implementation

Until now, with WebGL, we have been using the MeshBasicMaterial, MeshStandardMaterial, or even custom ShaderMaterial to create our materials.

When using WebGPU we need to use new materials that are compatible with TSL. Their names are the sames as the ones we used before with Node before Material:

• MeshBasicMaterial -> MeshBasicNodeMaterial
• MeshStandardMaterial -> MeshStandardNodeMaterial
• MeshPhysicalMaterial -> MeshPhysicalNodeMaterial
• ...

To use them declaratively with React Three Fiber, we need to extend them. In App.jsx:

Copy
// ...
import { extend } from "@react-three/fiber";

extend({
  MeshBasicNodeMaterial: THREE.MeshBasicNodeMaterial,
  MeshStandardNodeMaterial: THREE.MeshStandardNodeMaterial,
});
// ...

In the future versions of React Three Fiber, this might be done automatically.

Now we can use the new MeshBasicNodeMaterial and MeshStandardNodeMaterial in our components.

Let's replace the MeshStandardMaterial from the cube in our Experience component with the MeshStandardNodeMaterial:

Copy
<mesh>
  <boxGeometry args={[1, 1, 1]} />
  <meshStandardNodeMaterial color="pink" />
</mesh>

We can use the MeshStandardNodeMaterial just like we would use the MeshStandardMaterial.

Our cube is now relying on the MeshStandardNodeMaterial instead of the MeshStandardMaterial. We can now use nodes to customize the material.

Color Node

Let's learn how to create custom nodes to personalize our materials with TSL.

First, let's create a new component named PracticeNodeMaterial.jsx in the src/components folder.

Copy
export const PracticeNodeMaterial = ({
  colorA = "white",
  colorB = "orange",
}) => {
  return <meshStandardNodeMaterial color={colorA} />;
};

And in Experience.jsx, replace our cube with a plane using the PracticeNodeMaterial:

Copy
// ...
import { PracticeNodeMaterial } from "./PracticeNodeMaterial";

export const Experience = () => {
  return (
    <>
      {/* ... */}

      <mesh rotation-x={-Math.PI / 2}>
        <planeGeometry args={[2, 2, 200, 200]} />
        <PracticeNodeMaterial />
      </mesh>
    </>
  );
};

We have a plane with the PracticeNodeMaterial.

To customize our material, we can now alter the different nodes at our disposal using different nodes. The list of the available ones can be found in the wiki page.

Let's simply start with the colorNode node to change the color of our material. In PracticeNodeMaterial.jsx:

Copy
import { color } from "three/tsl";

export const PracticeNodeMaterial = ({
  colorA = "white",
  colorB = "orange",
}) => {
  return <meshStandardNodeMaterial colorNode={color(colorA)} />;
};

We set the colorNode prop using the color node from the three/tsl module. The color node takes a color as an argument and returns a color node that can be used in the material.

This gives us the same result as before, but now we can add more nodes to customize our material.

Let's import the mix and uv nodes from the three/tsl module and use them to mix two colors based on the UV coordinates of the plane.

Copy
import { color, mix, uv } from "three/tsl";

export const PracticeNodeMaterial = ({
  colorA = "white",
  colorB = "orange",
}) => {
  return (
    <meshStandardNodeMaterial
      colorNode={mix(color(colorA), color(colorB), uv())}
    />
  );
};

It will execute the different nodes to get the final color of the material. The mix node takes two colors and a factor (in this case, the UV coordinates) and returns a color that is a mix of the two colors based on the factor.

It's exactly the same as using the mix function in GLSL, but now we can use it in a node-based approach. (Much more readable!)

We can now see the two colors mixed based on the UV coordinates of the plane.

What is incredible, is that we are not starting from scratch. We are using the existing MeshStandardNodeMaterial and just adding our custom nodes to it. Which means the shadows, lights, and all the other features of the MeshStandardNodeMaterial are still available.

Declaring inline nodes is ok for very simple node logic, but for more complex logic, I recommend you to declare the nodes (and later uniforms, and more) in a useMemo hook:

Copy
// ...
import { useMemo } from "react";

export const PracticeNodeMaterial = ({
  colorA = "white",
  colorB = "orange",
}) => {
  const { nodes } = useMemo(() => {
    return {
      nodes: {
        colorNode: mix(color(colorA), color(colorB), uv()),
      },
    };
  }, []);

  return <meshStandardNodeMaterial {...nodes} />;
};

This does the exact same thing as before, but now we can add more nodes to the nodes object and pass them to the meshStandardNodeMaterial in a more organized/generic way.

By changing the colorA and colorB props, it won't cause a recompilation of the shader thanks to the useMemo hook.

Let's add controls to change the colors of the material. In Experience.jsx:

Copy
// ...
import { useControls } from "leva";

export const Experience = () => {
  const { colorA, colorB } = useControls({
    colorA: { value: "skyblue" },
    colorB: { value: "blueviolet" },
  });
  return (
    <>
      {/* ... */}

      <mesh rotation-x={-Math.PI / 2}>
        <planeGeometry args={[2, 2, 200, 200]} />
        <PracticeNodeMaterial colorA={colorA} colorB={colorB} />
      </mesh>
    </>
  );
};

The default color is working correctly, but updating the colors has no effect.

This is because we need to pass the colors as uniforms to the meshStandardNodeMaterial.

Uniforms

To declare uniforms in TSL, we can use the uniform node from the three/tsl module. The uniform node takes a value as an argument (it can be of different types such as float, vec3, vec4, etc.) and returns a uniform node that can be used in the different nodes while being updated from our component code.

Let's switch the hardcoded colors to uniforms in PracticeNodeMaterial.jsx:

Copy
// ...
import { uniform } from "three/tsl";

export const PracticeNodeMaterial = ({
  colorA = "white",
  colorB = "orange",
}) => {
  const { nodes, uniforms } = useMemo(() => {
    const uniforms = {
      colorA: uniform(color(colorA)),
      colorB: uniform(color(colorB)),
    };

    return {
      nodes: {
        colorNode: mix(uniforms.colorA, uniforms.colorB, uv()),
      },
      uniforms,
    };
  }, []);

  return <meshStandardNodeMaterial {...nodes} />;
};

We declare a uniforms object for better code organization, and we use the uniform values instead of the default value we got at the creation of our nodes.

By returning them in the useMemo we now have access to the uniforms in our component.

In a useFrame we can update the uniforms:

Copy
// ...
import { useFrame } from "@react-three/fiber";

export const PracticeNodeMaterial = ({
  colorA = "white",
  colorB = "orange",
}) => {
  // ...

  useFrame(() => {
    uniforms.colorA.value.set(colorA);
    uniforms.colorB.value.set(colorB);
  });

  return <meshStandardNodeMaterial {...nodes} />;
};

Use value.set method when you update an object uniform. For example, color or vec3 uniforms. For float uniforms, you need to set the value directly: uniforms.opacity.value = opacity;

The colors are now updating correctly in real-time.

Before doing more to the color, let's see how we can affect the position of the vertices of our plane using the positionNode.

Position Node

The positionNode node allows us to affect the position of the vertices of our geometry.