WebGPURenderer: Array-Based RenderTarget Refactor #30959

RenaudRohlinger · 2025-04-19T07:07:03Z

Description
This PR refactors the concept of TextureArray and RenderTargetArray, adding capabilities for more advanced use cases such as Multi Render Target Arrays.

Following the same idea behind deprecating WebGLMultipleRenderTargets in favor of RenderTarget using the options.count property, this PR leverages the existing image.depth property in Texture to introduce support for array-like behavior in RenderTarget.

By adding a new options.depth parameter to RenderTarget, it’s now possible to create a RenderTargetArray in a much simpler and more intuitive way:

const fboArray = new THREE.RenderTarget( size.width, size.height, { depth: 2 } ); // fbo array of depth 2

This opens the door for defining multi-layered render targets using both count and depth:

const multifboArray = new THREE.RenderTarget( size.width, size.height, { count: 2, depth: 2 } ); // 2 layouts with an fbo array of depth 2

As a result, redundant classes such as DepthArrayTexture become unnecessary. Equivalent functionality is now achieved more cleanly:

const depthArray = DepthTexture()
depthArray.depth = 2

I made updates to parts of the code that were affected by your multiview PR, @rcabanier. Since I don’t currently have access to an XR device, I’d appreciate it if you could verify whether everything still works as expected with this change.

This contribution is funded by Renaud Rohlinger @ Utsubo

…llow-override

github-actions · 2025-04-19T07:10:18Z

📦 Bundle size

Full ESM build, minified and gzipped.

	Before	After	Diff
WebGL	336.33 78.33	336.29 78.32	-36 B -8 B
WebGPU	547.85 151.9	547.44 151.78	-407 B -122 B
WebGPU Nodes	547.2 151.74	546.79 151.62	-407 B -122 B

🌳 Bundle size after tree-shaking

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

	Before	After	Diff
WebGL	466.15 112.56	466.23 112.58	+77 B +20 B
WebGPU	623.1 168.69	622.26 168.48	-836 B -203 B
WebGPU Nodes	577.97 157.98	577.14 157.79	-836 B -193 B

Mugen87 · 2025-04-19T09:13:59Z

Are you okay if we move this PR to the r177 target? The release is already next week and this PR implements a quite substantial refactoring. I would prefer to have more time on dev to test/verify the changes.

Mugen87 · 2025-04-23T09:54:08Z

src/renderers/common/Textures.js

@@ -147,7 +138,6 @@ class Textures extends DataMap {

 				const texture = textures[ i ];

-				texture.isTextureArray = renderTarget.multiview === true && size.depth > 1;


I fear this removal breaks multiview. When rendering in XR, the framebuffer render target is resized with a depth value larger 1.

three.js/src/renderers/common/Renderer.js

Line 1246 in 6e56458

frameBufferTarget.setSize( width, height, outputRenderTarget !== null ? outputRenderTarget.depth : 1 );

But since the isTextureArray /isArrayTexture is only set in the ctor, the flag isn't set correctly. So there are two options: Restore this line or make sure Texture.isArrayTexture is also set in RenderTarget.setSize() for all render target textures.

make sure Texture.isArrayTexture is also set in RenderTarget.setSize() for all render target textures.

I think this option makes a lot more sense I will try.

src/textures/Texture.js

src/core/RenderTarget.js

sunag · 2025-04-27T02:02:25Z

src/textures/DepthTexture.js

 	 */
-	constructor( width, height, type = UnsignedIntType, mapping, wrapS, wrapT, magFilter = NearestFilter, minFilter = NearestFilter, anisotropy, format = DepthFormat ) {
+	constructor( width, height, type = UnsignedIntType, mapping, wrapS, wrapT, magFilter = NearestFilter, minFilter = NearestFilter, anisotropy, format = DepthFormat, depth = 1 ) {


It's at times like these that I think that object-based function parameters are better for optional values, functions with more than 4 parameters start to get confusing for me.

We could just remove the parameter and leave it as in the example below?

const depthMap = new THREE.DepthTexture( ... ); depthMap.depth = value;

If we go this route we would need to apply the isArrayTexture patch later in the code, for example in the Textures class, but I don't even think it would work.

I know we are dealing with limitations but the function signature is inappropriate. Until we adopt a convention we can make this more explicit perhaps even with DepthArrayTexture again. The class name and parameters also has the function of making the code easier to read.

sunag · 2025-04-27T02:08:49Z

I think the webgpu_compute_texture example is broken

…ture

RenaudRohlinger · 2025-04-27T12:17:43Z

All good except:

We could just remove the parameter and leave it as in the example below?

const depthMap = new THREE.DepthTexture( ... );
depthMap.depth = value;

However, I think we should have gone for an object as the argument from the start just like RenderTarget.
If we want to continue expanding Three.js features, we'll inevitably need to add many more parameters in the future. For instance, just for the depth settings alone:

This leads me to think that maybe we should define a clear convention:

Use a new property layers for array formats
Use depth for cube formats

This way, we avoid future confusion.
Adding a new class for every small feature (like layers or depth), as we're currently doing, feels unnecessary and confusing especially since WebGL and WebGPU don't work like this. (Cubes are a different story, so I think that exception is fine.)

sunag · 2025-04-27T15:32:50Z

I think that face is for cube, depth for mipmaps and count for array. But to not change too much depth could be used for array, while face is for cube formats.

RenaudRohlinger · 2025-04-28T03:14:11Z

I think we can revisit these specific details in a separate PR. For now, this PR focuses on cleaning up some confusing parts of the code. By simply adding an extra depth argument, it not only simplifies the logic but also unlocks support for very advanced features like Multi Render Target Arrays. All that while removing some code, which is a nice demonstration of how necessary this refactor is.

@Mugen87 It would be great if you could confirm that XR is still working, as I currently don't have access to a device for testing.

Mugen87 · 2025-04-28T08:47:04Z

Do you mind temporarily updating the builds so I can test with the following URL?

https://rawcdn.githack.com/mrdoob/three.js/596833465197d377a447b0819afd77e954fb5cf3/examples/index.html

RenaudRohlinger · 2025-04-28T11:33:18Z

I pushed the build files @Mugen87 👍

Mugen87 · 2025-04-29T08:30:51Z

The example does not work anymore with the new build. It's not even related to multiview. XR does not work in general.

I have to debug so I can extract the error message.

Mugen87 · 2025-04-29T08:40:20Z

Okay, the error is:

Uncaught (in promise) Error: DepthTexture format must be either THREE.DepthFormat or THREE.DepthStencilFormat
at new DepthTexture (three.core.js:29668:10)
at XRManager.setSession (three.webgpu.js:49492:26)
at async onSessionStarted (XRButton.js:38:5)
DepthTexture @ three.core.js:29668
setSession @ three.webgpu.js:49492

src/renderers/common/XRManager.js

Mugen87

If you remove the build files from the PR, it is ready to be merged.

RenaudRohlinger added 10 commits April 6, 2025 22:29

ShadowNode: Inherit camera.layers only if shadow.layers is not set

7ccb258

Merge remote-tracking branch 'upstream/dev' into utsubo/feat/shadow-a…

3080fd3

…llow-override

Fix layers check

6ad7180

invert condition

5176f75

restore after render

1bb3e29

move array creation to module scope

2d0a54d

WebGPURenderer: Refactor Texture Arrays

0ad11ef

merge with multiview

b4714e6

fix conflicts

7919acd

cleanup and fix multiview

564ef5b

RenaudRohlinger requested review from Mugen87 and sunag April 19, 2025 07:07

RenaudRohlinger added this to the r176 milestone Apr 19, 2025

revert webgpu pipeline utils

c70f8a4

RenaudRohlinger modified the milestones: r176, r177 Apr 19, 2025

Mugen87 reviewed Apr 23, 2025

View reviewed changes

src/textures/Texture.js Show resolved Hide resolved

Mugen87 reviewed Apr 23, 2025

View reviewed changes

src/core/RenderTarget.js Show resolved Hide resolved

sunag reviewed Apr 27, 2025

View reviewed changes

RenaudRohlinger added 3 commits April 27, 2025 20:21

Merge remote-tracking branch 'upstream/dev' into utsubo/feat/arraytex…

6f8555b

…ture

Fix StorageTexture depth

79efef8

fix fbo setSize

ca79f2b

update build

ca48a40

Mugen87 reviewed Apr 29, 2025

View reviewed changes

src/renderers/common/XRManager.js Outdated Show resolved Hide resolved

RenaudRohlinger added 2 commits April 29, 2025 18:20

fix xrmanager depth missing arg

6441b9a

bump build

5968334

Mugen87 approved these changes Apr 29, 2025

View reviewed changes

revert build

2087d85

RenaudRohlinger merged commit 84b6feb into mrdoob:dev Apr 30, 2025
12 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

WebGPURenderer: Array-Based RenderTarget Refactor #30959

WebGPURenderer: Array-Based RenderTarget Refactor #30959

RenaudRohlinger commented Apr 19, 2025 •

edited

Loading

github-actions bot commented Apr 19, 2025 •

edited

Loading

Mugen87 commented Apr 19, 2025

Mugen87 Apr 23, 2025 •

edited

Loading

RenaudRohlinger Apr 27, 2025 •

edited

Loading

sunag Apr 27, 2025 •

edited

Loading

sunag Apr 27, 2025 •

edited

Loading

RenaudRohlinger Apr 27, 2025 •

edited

Loading

sunag Apr 27, 2025

sunag commented Apr 27, 2025

RenaudRohlinger commented Apr 27, 2025

sunag commented Apr 27, 2025 •

edited

Loading

RenaudRohlinger commented Apr 28, 2025

Mugen87 commented Apr 28, 2025 •

edited

Loading

RenaudRohlinger commented Apr 28, 2025

Mugen87 commented Apr 29, 2025 •

edited

Loading

Mugen87 commented Apr 29, 2025

Mugen87 left a comment

		@@ -147,7 +138,6 @@ class Textures extends DataMap {

		const texture = textures[ i ];

		texture.isTextureArray = renderTarget.multiview === true && size.depth > 1;

WebGPURenderer: Array-Based RenderTarget Refactor #30959

WebGPURenderer: Array-Based RenderTarget Refactor #30959

Conversation

RenaudRohlinger commented Apr 19, 2025 • edited Loading

github-actions bot commented Apr 19, 2025 • edited Loading

📦 Bundle size

🌳 Bundle size after tree-shaking

Mugen87 commented Apr 19, 2025

Mugen87 Apr 23, 2025 • edited Loading

Choose a reason for hiding this comment

RenaudRohlinger Apr 27, 2025 • edited Loading

Choose a reason for hiding this comment

sunag Apr 27, 2025 • edited Loading

Choose a reason for hiding this comment

sunag Apr 27, 2025 • edited Loading

Choose a reason for hiding this comment

RenaudRohlinger Apr 27, 2025 • edited Loading

Choose a reason for hiding this comment

sunag Apr 27, 2025

Choose a reason for hiding this comment

sunag commented Apr 27, 2025

RenaudRohlinger commented Apr 27, 2025

sunag commented Apr 27, 2025 • edited Loading

RenaudRohlinger commented Apr 28, 2025

Mugen87 commented Apr 28, 2025 • edited Loading

RenaudRohlinger commented Apr 28, 2025

Mugen87 commented Apr 29, 2025 • edited Loading

Mugen87 commented Apr 29, 2025

Mugen87 left a comment

Choose a reason for hiding this comment

RenaudRohlinger commented Apr 19, 2025 •

edited

Loading

github-actions bot commented Apr 19, 2025 •

edited

Loading

Mugen87 Apr 23, 2025 •

edited

Loading

RenaudRohlinger Apr 27, 2025 •

edited

Loading

sunag Apr 27, 2025 •

edited

Loading

sunag Apr 27, 2025 •

edited

Loading

RenaudRohlinger Apr 27, 2025 •

edited

Loading

sunag commented Apr 27, 2025 •

edited

Loading

Mugen87 commented Apr 28, 2025 •

edited

Loading

Mugen87 commented Apr 29, 2025 •

edited

Loading