WebGPURenderer: Build - three.webgpu.js

[sunag]

Related issue: #28328, #28328 (comment)

Description

TSL

I did some tests to include TSL in the build, the first attempt was THREE.TSL and use const { .. } = to import, which works well but is incompatible with tree shaking, the second attempt was to preserve three/tls but that would prevent having a single build file for everything. I think that since TSL will be part of the agnostic rendering system, it seems correct for it to be an essential central part of the file, just like other materials are.

To import a TSL, just use:

import { float, vec3, color } from 'three/tsl';

For class creation this is more familiar:

const material = THREE.MeshStandardNodeMaterial();

Renderer

Using the Renderer has become simpler too with THREE.:

const renderer = new THREE.WebGPURenderer();

One possibility is that we can keep a WebGLRenderer class using forceWebGL automatically.

PMREMGenerator

Previously it was necessary to reimport PMREMGenerator from a new path for webgpu, now it is possible to use the original THREE.PMREMGenerator syntax.

const sceneRT = new THREE.PMREMGenerator( renderer ).fromScene( scene );

RectAreaLightTexturesLib

I created a base LTC for use on WebGPU, WebGLRenderer also relies on this same class.

QuadMesh, PostProcessing

QuadMesh and PostProcessing can be used with THREE.QuadMesh and THREE.PostProcessing.

Lines2

We have a separate jsm/lines/webgpu class now to handle just TSL, previously we had a lot of GLSL mixed in between the class extensions.

Imports

{
	"imports": {
		"three": "../build/three.webgpu.js",
		"three/debug": "../src/Three.WebGPU.js",
		"three/addons/": "./jsm/"
	}
}

If you want to edit the files without having to recompile them, you can use the imports above.

Next steps

This simplifies the process for creating the tree shaking that will come with the next PR. Do you just need to update from three.webgpu.js to three.webgpu.nodes.js or three.nodes.js?

[github-actions]

📦 Bundle size

Full ESM build, minified and gzipped.

Filesize dev	Filesize PR	Diff
682.2 kB (169 kB)	682.2 kB (169 kB)	+0 B

🌳 Bundle size after tree-shaking

Minimal build including a renderer, camera, empty scene, and dependencies.

Filesize dev	Filesize PR	Diff
459.4 kB (110.9 kB)	459.4 kB (110.9 kB)	+0 B

[sunag]

Seems that an update in puppeteer will be necessary.

[RenaudRohlinger]

Could we also use this PR to move the WebGPURenderer and TSL files to a directory like /webgpu/? 😄

It feels a bit odd to point to the addons such as examples/jsm/renderers/webgpu/Three.js for the build. This change would also make it easier for maintainers to work on new the Renderer by separate the TSL and WebGPURenderer files from the hundreds of existing WebGLRenderer examples blended in.

The import map would then look like this:

{
	"imports": {
		"three": "../build/three.webgpu.js",
		"three/debug": "./webgpu/renderers/webgpu/Three.js",
		"three/addons/": "./jsm/"
	}
}

/cc @mrdoob @sunag @Mugen87

[Mugen87]

It wouldn't be examples/jsm/renderers/webgpu/Three.js but three/addons/renderers/webgpu/Three.js when importing from the npm package.

TBH, I did not have the impression so far that import paths containing addons are an issue.

This change would also make it easier for maintainers to work on new the Renderer by separate the TSL and WebGPURenderer files from the hundreds of existing WebGLRenderer examples blended in.

Um, I'm not sure I agree. What would be exactly easier?

[RenaudRohlinger]

TBH, I did not have the impression so far that import paths containing addons are an issue.

It's a matter of best practice and trying to organize the repository more effectively. Why should the new Renderer and Node System be under the "examples/jsm" folder?
I understand that historically it was done this way, and while I don't mind maintaining that approach, it does seem counterintuitive.

It feels like anything that is not the WebGLRenderer is placed under examples/jsm by default.

I just feel that this PR will bring some fresh air to the repository and maybe we could take that opportunity to reorganize a bit! 😄

[Mugen87]

It feels like anything that is not the WebGLRenderer is placed under examples/jsm by default.

Um, why not moving Renderer, WebGPURenderer and TSL related modules into src? Wouldn't be that the more obvious approach?

The directory size of src or its number of files is not the critical metric. It's the size of the build files that matters. However, it should be possible to manage more code in src while keeping the sizes of files like three.module.js, three.module.min.js and three.cjs consistent.

[RenaudRohlinger]

Indeed, even better! 👍

[WestLangley]

debug does not appear to be needed. Should we have an example in which it is?

[sunag]

I purposely put it in sandbox because I thought it could convey the idea of ​​debug since I can't make simple comments in the JSON, maybe there is a more suitable way to do this...

[WestLangley]

Your choice... I'd vote to merge this PR ASAP if @Mugen87 approves.

[mrdoob]

Let me think about the naming for all this for a couple of days 🙏

[sunag]

I replaced three/nodes to three/webgpu in package. I imagined that developers could use three alias in vite like:

// vite.config.js

import { defineConfig } from 'vite';

export default defineConfig({
  resolve: {
    alias: {
      'three': 'three/webgpu'
    }
  }
});

[mrdoob]

I did some tests to include TSL in the build, the first attempt was THREE.TSL and use const { .. } = to import, which works well but is incompatible with tree shaking

Hmm, that would definitely more clean than import { float, vec3, color } from 'three';...

Why is it incompatible with tree shaking?

[sunag]

Why is it incompatible with tree shaking?

I created a mini example in the link below, when I used const { .. } = , it imports all the values ​​from TSL, unlike when I use THREE.TSL.vec3() for example.

https://shorturl.at/x6AKZ

[sunag]

I created a mini example in the link below, when I used const { .. } = , it imports all the values ​​from TSL, unlike when I use THREE.TSL.vec3() for example.

Same thing with vite.

Maybe we could add a three/tsl alias and advance? I'm a little worried about revisiting this PR every time we merge some PR, it feels like it's going to break at some point.

[mrdoob]

Maybe we could add a three/tsl alias and advance?

Yes, let's try that first 👍

[RenaudRohlinger]

For documentation purpose here is the correct way to use the new build:

// vite.config.js

import { defineConfig } from 'vite';

export default defineConfig({
  resolve: {
    alias: {
       'three/addons': 'three/examples/jsm',
       'three/tsl': 'three/webgpu',
       'three': 'three/webgpu',
    }
  }
});

The order is important otherwise three/tsl will try to resolve three/webgpu/tsl for example.

/cc @sunag