Skip to content

Commit d897f3a

Browse files
Mugen87vincentfretin
Mugen87
and
vincentfretin
authored
Manual: Add basic guide about WebGPURenderer. (#32260)
Co-authored-by: Vincent Fretin <[email protected]>
1 parent 55c095d commit d897f3a

File tree

2 files changed

+182
-0
lines changed

2 files changed

+182
-0
lines changed

‎manual/en/webgpurenderer.html‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
<!DOCTYPE html><html lang="en"><head>
2+
<meta charset="utf-8">
3+
<title>WebGPURenderer</title>
4+
<meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
5+
<meta name="twitter:card" content="summary_large_image">
6+
<meta name="twitter:site" content="@threejs">
7+
<meta name="twitter:title" content="Three.js – WebGPURenderer">
8+
<meta property="og:image" content="https://threejs.org/files/share.png">
9+
<link rel="shortcut icon" href="../../files/favicon_white.ico" media="(prefers-color-scheme: dark)">
10+
<link rel="shortcut icon" href="../../files/favicon.ico" media="(prefers-color-scheme: light)">
11+
12+
<link rel="stylesheet" href="../resources/lesson.css">
13+
<link rel="stylesheet" href="../resources/lang.css">
14+
<script type="importmap">
15+
{
16+
"imports": {
17+
"three": "../../build/three.module.js"
18+
}
19+
}
20+
</script>
21+
</head>
22+
<body>
23+
<div class="container">
24+
<div class="lesson-title">
25+
<h1>WebGPURenderer</h1>
26+
</div>
27+
<div class="lesson">
28+
<div class="lesson-main">
29+
30+
<p>
31+
The new `WebGPURenderer` is the next-generation renderer for three.js. This article provides a short overview about the new
32+
renderer and basic guidelines about the usage.
33+
</p>
34+
35+
<h2>Overview</h2>
36+
37+
<p>
38+
`WebGPURenderer` is designed to be the modern alternative to the long-standing `WebGLRenderer`.
39+
Its primary goal is to use WebGPU, which is a modern, high-performance graphics and compute 3D API. However, it's built to be a
40+
universal renderer. If a device/browser doesn't support WebGPU, the renderer can automatically fall back to using a WebGL 2 backend.
41+
</p>
42+
<p>
43+
Providing a WebGL 2 backend as a fallback is a crucial design decision since it allows applications to benefit from WebGPU but without
44+
sacrificing the support for devices which only support WebGL 2.
45+
</p>
46+
47+
<p>
48+
Apart from the fact that `WebGPURenderer` enables access to WebGPU, it offers an exciting feature set:
49+
<p>
50+
51+
<ul>
52+
<li>
53+
`WebGPURenderer` comes with a new node-based material system which allows to develop custom materials with greater flexibility and
54+
more robustness.
55+
</li>
56+
<li>
57+
The renderer supports TSL, the three.js shading language. With TSL, developers can write shader code with JavaScript in a
58+
platform-independent manner. Shader code written in TSL can be transpiled to WGSL or GLSL depending on the available backend.
59+
</li>
60+
<li>
61+
`WebGPURenderer` comes with a new post-processing stack with built-in Multiple Render Targets (MRT) support and automatic pass combination thanks to the
62+
node material.
63+
</li>
64+
</ul>
65+
66+
Let's find out how to integrate `WebGPURenderer` in three.js applications.
67+
68+
<h2>Usage</h2>
69+
70+
<p>
71+
`WebGPURenderer` has different build files so the way you import three.js changes:
72+
</p>
73+
74+
<pre class="prettyprint showlinemods notranslate lang-js" translate="no">
75+
- import * as THREE from 'three';
76+
+ import * as THREE from 'three/webgpu';
77+
</pre>
78+
79+
<p>
80+
If you are using an import map, it's recommended to change it to the following (the paths differ depending on your setup):
81+
</p>
82+
<pre class="prettyprint showlinemods notranslate lang-js" translate="no">
83+
&lt;script type="importmap"&gt;
84+
{
85+
"imports": {
86+
"three": "../build/three.webgpu.js",
87+
"three/webgpu": "../build/three.webgpu.js",
88+
"three/tsl": "../build/three.tsl.js",
89+
"three/addons/": "./jsm/"
90+
}
91+
}
92+
&lt;/script&gt;
93+
</pre>
94+
95+
<p>
96+
You can create an instance of the renderer just like with `WebGLRenderer`:
97+
</p>
98+
99+
<pre class="prettyprint showlinemods notranslate lang-js" translate="no">
100+
const renderer = new THREE.WebGPURenderer( { antialias: true } );
101+
renderer.setPixelRatio( window.devicePixelRatio );
102+
renderer.setSize( window.innerWidth, window.innerHeight );
103+
renderer.setAnimationLoop( render );
104+
document.body.appendChild( renderer.domElement );
105+
</pre>
106+
<p>
107+
It's important to understand that WebGPU is initialized in an asynchronous fashion. Hence, it is recommended to use
108+
`setAnimationLoop()` to define the animation loop of your app since this approach will automatically ensure the renderer
109+
is initialized when rendering the first frame. If you prefer to manage your animation loop via `window.requestAnimationFrame()` or
110+
if you have to use to the renderer in your init routine, you need an additional line in the above code section.
111+
</p>
112+
<pre class="prettyprint showlinemods notranslate lang-js" translate="no">
113+
const renderer = new THREE.WebGPURenderer( { antialias: true } );
114+
renderer.setPixelRatio( window.devicePixelRatio );
115+
renderer.setSize( window.innerWidth, window.innerHeight );
116+
renderer.setAnimationLoop( render );
117+
document.body.appendChild( renderer.domElement );
118+
119+
+ await renderer.init();
120+
</pre>
121+
<p>
122+
Most common methods known from `WebGLRenderer` like `clear()`, `setRenderTarget()`or `dispose()` are also present in `WebGPURenderer`.
123+
Please have a look at the <a href="https://threejs.org/docs/#Renderer" target="_blank">API documentation</a> for a full overview of the renderer's public interface.
124+
</p>
125+
126+
<p>
127+
Like mentioned in the initial part of the guide, `WebGPURenderer` uses a WebGPU backend by default and a WebGL 2 backend as a fallback.
128+
If you want to force the usage of WebGL 2 for testing purposes or if you want to exclude the usage of WebGPU for certain reasons, you can
129+
make use of the `forceWebGL` parameter.
130+
</p>
131+
<pre class="prettyprint showlinemods notranslate lang-js" translate="no">
132+
- const renderer = new THREE.WebGPURenderer( { antialias: true } );
133+
+ const renderer = new THREE.WebGPURenderer( { antialias: true, forceWebGL: true } );
134+
</pre>
135+
136+
<h2>Migration</h2>
137+
138+
<p>
139+
If you want to give `WebGPURenderer` a try, you have to be aware of the following.
140+
</p>
141+
142+
<ul>
143+
<li>
144+
Custom materials based on `ShaderMaterial`, `RawShaderMaterial` and modifications of built-in materials via `onBeforeCompile()`
145+
are not supported in `WebGPURenderer`. This part of your application must be ported to node materials and TSL.
146+
</li>
147+
<li>
148+
`EffectComposer` with its effect passes are not supported because `WebGPURenderer` comes with a new, more modern
149+
post-processing stack. Similar to materials, post-processing effects are now written in TSL and the effect chain is expressed
150+
as a node composition. All common effects have already been ported to `WebGPURenderer` and exist in a more performant version
151+
as a node class. We have also added new effects like SSGI, SSS or a better DoF exclusively for the new renderer. Check out the
152+
<a href="https://threejs.org/examples/?q=webgpu%20postprocessing" target="_blank">official examples</a> to get an overview of
153+
the current supported effects.
154+
</li>
155+
<li>
156+
The renderer itself is still in an experimental state although its maturity level has been greatly improved in the last years.
157+
Still, depending on your application and scene setup, you will encounter missing features or a better performance with `WebGLRenderer`.
158+
Feel free to file an issue at GitHub so we are aware of open tasks. We are improving `WebGPURenderer` with each release so it's
159+
recommended to upgrade to the latest version whenever possible.
160+
</li>
161+
</ul>
162+
163+
<h2>State of WebGLRenderer</h2>
164+
165+
<p>Although in the meanwhile a lot of work happens in context of `WebGPURenderer`, the node material and TSL, `WebGLRenderer` is still maintained
166+
and the recommended choice for pure WebGL 2 applications. However, keep in mind that there are no plans to add larger new features to
167+
the renderer since the project's focus is now on `WebGPURenderer` which you can easily see at the latest release notes. That said,
168+
we are currently investigating the possibility to add limited node material support to `WebGLRenderer` in order to make the transition to
169+
`WebGPURenderer` easier for certain projects.
170+
</p>
171+
172+
</div>
173+
</div>
174+
</div>
175+
176+
<script src="../resources/prettify.js"></script>
177+
<script src="../resources/lesson.js"></script>
178+
</body>
179+
</html>

‎manual/list.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,9 @@
7272
"Making Voxel Geometry (Minecraft)": "en/voxel-geometry",
7373
"Start making a Game": "en/game"
7474
},
75+
"WebGPU": {
76+
"WebGPURenderer": "en/webgpurenderer"
77+
},
7578
"WebXR": {
7679
"VR - Basics": "en/webxr-basics",
7780
"VR - Look To Select": "en/webxr-look-to-select",

0 commit comments

Comments
 (0)