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

In this lesson, we will create hundreds of thousands of floating particles to render 3D models and 3D text using Three Shading Language (TSL) and WebGPU.

Instead of using faces, we use tons of particles, allowing us to smoothly transition between different models.

A 3D model of a fox, a book, and 3D text rendered with GPGPU particles! 🚀

GPGPU Particle System

Before we dive into the code, let's take a moment to understand what GPGPU is and how it can be used in Three.js.

What is GPGPU?

GPGPU (General-Purpose computing on Graphics Processing Units) is a technique that leverages the parallel processing power of GPUs to perform computations typically handled by the CPU.

In Three.js, GPGPU is often used for real-time simulations, particle systems, and physics by storing and updating data in textures instead of relying on CPU-bound calculations.

This technique allows shaders to have memory and compute capabilities, enabling them to perform complex calculations and store results in textures without the need for CPU intervention.

This allows for highly efficient, large-scale computations directly on the GPU.

Thanks to TSL, the process to create GPGPU simulations is much easier and more intuitive. With storage and buffer nodes combined to compute functions, we can create complex simulations with minimal code.

Here are some ideas of projects GPGPU can be used for:

• Particle systems
• Fluid simulations
• Physics simulations
• Boid simulations
• Image processing

Time to switch from Theory to practice! Let's create a GPGPU particle system using TSL and WebGPU.

Particle system

The starter pack is a WebGPU ready template based on the WebGPU/TSL lesson implementation.

Let's replace the pink mesh with a new component named GPGPUParticles. Create a new file named GPGPUParticles.jsx in the src/components folder and add the following code:

Copy
import { extend } from "@react-three/fiber";
import { useMemo } from "react";
import { color, uniform } from "three/tsl";
import { AdditiveBlending, SpriteNodeMaterial } from "three/webgpu";

export const GPGPUParticles = ({ nbParticles = 1000 }) => {
  const { nodes, uniforms } = useMemo(() => {
    // uniforms
    const uniforms = {
      color: uniform(color("white")),
    };

    return {
      uniforms,
      nodes: {
        colorNode: uniforms.color,
      },
    };
  }, []);

  return (
    <>
      <sprite count={nbParticles}>
        <spriteNodeMaterial
          {...nodes}
          transparent
          depthWrite={false}
          blending={AdditiveBlending}
        />
      </sprite>
    </>
  );
};

extend({ SpriteNodeMaterial });

Nothing new here, we are creating a GPGPUParticles component that uses a Sprite with a SpriteNodeMaterial to render the particles.

The benefit of using a Sprite over InstancedMesh is that it is lighter and comes with a billboard effect by default.

Let's add the GPGPUParticles component to the Experience component:

Copy
import { OrbitControls } from "@react-three/drei";
import { GPGPUParticles } from "./GPGPUParticles";

export const Experience = () => {
  return (
    <>
      {/* <Environment preset="warehouse" /> */}
      <OrbitControls />
      <GPGPUParticles />
      {/* <mesh>
        <boxGeometry />
        <meshStandardMaterial color="hotpink" />
      </mesh> */}
    </>
  );
};

We can get rid of the mesh and environment components.

We can see a square in the middle of the screen, this is the white sprite particles. All at the same position.

It's time to setup our particle system!

Buffer / Storage / Instanced Array

For our GPGPU simulation, we need our particles to memorize their position, velocity, age, and color without using the CPU.

A few things won't require us to store data. We can calculate the color based on the age combined to uniforms. And we can generate the velocity randomly using a fixed seed value.

But for the position, as the target position can evolve, we need to store it in a buffer. Same for the age, we want to handle the life cycle of the particles in the GPU.

To store data in the GPU, we can use the storage node. It allows us to store large amounts of structured data that can be updated on the GPU.

To use it with minimal code we will use the InstancedArray TSL function relying on the storage node.

This part of Three.js nodes isn't documented yet, it's by diving in the examples and the source code that we can understand how it works.

Let's prepare our buffer in the useMemo where we put our shader nodes:

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

export const GPGPUParticles = ({ nbParticles = 1000 }) => {
  const { nodes, uniforms } = useMemo(() => {
    // uniforms
    const uniforms = {
      color: uniform(color("white")),
    };

    // buffers
    const spawnPositionsBuffer = instancedArray(nbParticles, "vec3");
    const offsetPositionsBuffer = instancedArray(nbParticles, "vec3");
    const agesBuffer = instancedArray(nbParticles, "float");

    return {
      uniforms,
      nodes: {
        colorNode: uniforms.color,
      },
    };
  }, []);

  // ...
};

// ...

instancedArray is a TSL function that creates a buffer of the specified size and type.

The same code using the storage node would look like this:

Copy
import { storage } from "three/tsl";
import { StorageInstancedBufferAttribute } from "three/webgpu";

const spawnPositionsBuffer = storage(
  new StorageInstancedBufferAttribute(nbParticles, 3),
  "vec3",
  nbParticles
);

With these buffers, we can store the position and age of each particle and update them in the GPU.

To access the data in the buffers, we can use .element(index) to get the value at the specified index.

In our case we will use the instancedIndex of each particle to access the data in the buffers:

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

export const GPGPUParticles = ({ nbParticles = 1000 }) => {
  const { nodes, uniforms } = useMemo(() => {
    // ...

    // buffers
    const spawnPositionsBuffer = instancedArray(nbParticles, "vec3");
    const offsetPositionsBuffer = instancedArray(nbParticles, "vec3");
    const agesBuffer = instancedArray(nbParticles, "float");

    const spawnPosition = spawnPositionsBuffer.element(instanceIndex);
    const offsetPosition = offsetPositionsBuffer.element(instanceIndex);
    const age = agesBuffer.element(instanceIndex);

    return {
      uniforms,
      nodes: {
        colorNode: uniforms.color,
      },
    };
  }, []);

  // ...
};

// ...

instanceIndex is a built-in TSL function that returns the index of the current instance being processed.

This allows us to access the data in the buffers for each particle.

We won't need it for this project, but by being able to access the data of another instance, we can create complex interactions between particles. For example, we could create a flock of birds that follow each other.

Initial compute

To setup the position and age of the particles, we need to create a compute function that will be executed on the GPU at the beginning of the simulation.

To create a compute function with TSL, we need to use the Fn node, to call it, and use the compute method it returns with the number of particles:

Copy
// ...
import { Fn } from "three/src/nodes/TSL.js";

export const GPGPUParticles = ({ nbParticles = 1000 }) => {
  const { nodes, uniforms } = useMemo(() => {
    // ...
    const spawnPosition = spawnPositionsBuffer.element(instanceIndex);
    const offsetPosition = offsetPositionsBuffer.element(instanceIndex);
    const age = agesBuffer.element(instanceIndex);

    // init Fn
    const lifetime = randValue({ min: 0.1, max: 6, seed: 13 });

    const computeInit = Fn(() => {
      spawnPosition.assign(
        vec3(
          randValue({ min: -3, max: 3, seed: 0 }),
          randValue({ min: -3, max: 3, seed: 1 }),
          randValue({ min: -3, max: 3, seed: 2 })
        )
      );
      offsetPosition.assign(0);
      age.assign(randValue({ min: 0, max: lifetime, seed: 11 }));
    })().compute(nbParticles);

    // ...
  }, []);

  // ...
};

// ...

We create a computeInit function that assign our buffers with random values.

The randValue function doesn't exist, we need to create it ourselves.

The functions at our disposal are:

• hash(seed): To generate a random value based on a seed between 0 and 1.
• range(min, max): To generate a random value between min and max.

More info on the Three.js Shading Language Wiki.

But the range function defines an attribute and stores the value of it. Not what we want.

Let's create a randValue function that will return a random value between min and max based on a seed:

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

const randValue = /*#__PURE__*/ Fn(({ min, max, seed = 42 }) => {
  return hash(instanceIndex.add(seed)).mul(max.sub(min)).add(min);
});

export const GPGPUParticles = ({ nbParticles = 1000 }) => {
  // ...
};
// ...

The randValue function takes a min, max, and seed value and returns a random value between min and max based on the seed.

/*#__PURE__*/ is a comment used for tree-shaking. It tells the bundler to remove the function if it's not used. More details here.

Now we need to call our computeInit function. This is a job for the renderer. Let's import it with useThree and call it right after its declaration:

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

export const GPGPUParticles = ({ nbParticles = 1000 }) => {
  const gl = useThree((state) => state.gl);

  const { nodes, uniforms } = useMemo(() => {
    // ...
    const computeInit = Fn(() => {
      // ...
    })().compute(nbParticles);

    gl.computeAsync(computeInit);

    // ...
  }, []);

  // ...
};

// ...

To be able to visualize it, we need to change the positionNode of the SpriteNodeMaterial to use the spawnPosition and offsetPosition buffers.

Copy
// ...

export const GPGPUParticles = ({ nbParticles = 1000 }) => {
  // ...

  const { nodes, uniforms } = useMemo(() => {
    // ...

    return {
      uniforms,
      nodes: {
        positionNode: spawnPosition.add(offsetPosition),
        colorNode: uniforms.color,
      },
    };
  }, []);

  // ...
};

// ...

We set the positionNode to the sum of the spawnPosition and offsetPosition vectors.

Does it work? Let's check it out!

Mayday! It's all white! ⬜️

Zoom-out a little bit?

Phew, we can see the particles, they are just too big it painted the whole screen! 😮‍💨

Let's fix that by setting the scaleNode with a random value:

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

// ...

export const GPGPUParticles = ({ nbParticles = 1000 }) => {
  // ...

  const { nodes, uniforms } = useMemo(() => {
    // ...

    const scale = vec3(range(0.001, 0.01));

    return {
      uniforms,
      nodes: {
        positionNode: spawnPosition.add(offsetPosition),
        colorNode: uniforms.color,
        scaleNode: scale,
      },
    };
  }, []);

  return (
    <>
      <sprite count={nbParticles}>
        <spriteNodeMaterial
          {...nodes}
          transparent
          depthWrite={false}
          blending={AdditiveBlending}
        />
      </sprite>
    </>
  );
};

// ...

In this scenario, we can use the range function to generate a random value between 0.001 and 0.01.

Perfect, we have our particles with different sizes and positions! 🎉

It's a bit static though, we need to add some movement to it.

Update compute

Like we did for the init compute function let's create an update compute function that will be executed on each frame.

In this function, we will update the position and age of the particles:

Copy
// ...
import { deltaTime, If } from "three/tsl";

export const GPGPUParticles = ({ nbParticles = 1000 }) => {
  // ...

  const { nodes, uniforms } = useMemo(() => {
    // ...

    const instanceSpeed = randValue({ min: 0.01, max: 0.05, seed: 12 });

    // update Fn
    const computeUpdate = Fn(() => {
      age.addAssign(deltaTime);

      If(age.greaterThan(lifetime), () => {
        age.assign(0);
        offsetPosition.assign(0);
      });

      offsetPosition.addAssign(vec3(instanceSpeed));
    })().compute(nbParticles);

    // ...
  }, []);

  // ...
};

// ...