TSL: Introduce struct

[sunag]

Related issue: #29908, #29760

Description

PR introduces struct for TSL following the syntax below:

const BoundingBox = struct( {
	min: 'vec3',
	max: 'vec3'
} );

// style 1
const bb = BoundingBox( vec3( 0 ), vec3( 1 ) );

// style 1 - default value
const bb = BoundingBox();

// style 2
const bb = BoundingBox( {
	min: vec3( 0 ), 
	max: vec3( 1 ) 
} );

// style 2 - optional values
const bb = BoundingBox( {
	// min: vec3( 0 ),  // use optional value
	max: vec3( 1 ) 
} );

// assigns in TSL Fn
const bbFn = Fn( () => {

	const bb = BoundingBox();

	const bbMax = bb.get( 'max' );
	bbMax.assign( vec3( 1 ) );
	// or -> bb.get( 'max' ).assign( vec3( 1 ) );

	return bb;

} );

// debug
material.colorNode = bbFn().get( 'max' );

[github-actions]

📦 Bundle size

Full ESM build, minified and gzipped.

	Before	After	Diff
WebGL	336.27 78.29	336.27 78.29	+0 B +0 B
WebGPU	513.63 142.61	516.74 143.47	+3.11 kB +858 B
WebGPU Nodes	513.09 142.51	516.2 143.37	+3.11 kB +857 B

🌳 Bundle size after tree-shaking

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

	Before	After	Diff
WebGL	465.25 112.13	465.25 112.13	+0 B +0 B
WebGPU	587.56 159.27	588.75 159.64	+1.19 kB +364 B
WebGPU Nodes	542.94 148.83	544.13 149.2	+1.19 kB +370 B

[sunag]

I updated webgpu_compute_water, now we can use a single storage buffer to send multiples datas.

Previous

// Sphere Instance Storage
const sphereInstancePositionStorage = instancedArray( spherePositionArray, 'vec3' ).label( 'SpherePosition' );
const sphereVelocityStorage = instancedArray( sphereVelocityArray, 'vec2' ).label( 'SphereVelocity' );

Now

const SphereStruct = struct( {
	position: 'vec3',
	velocity: 'vec2'
} );

// Sphere Instance Storage
const sphereVelocityStorage = instancedArray( sphereArray, SphereStruct ).label( 'SphereData' );

[sunag]

It was somewhat well worked, but it worked, I had to make a lot of changes for this to create a new PR. Currently the struct works in both backends except if it is used in storage().

@Spiri0 I added your example and added you as a co-author. I had to make some small modifications to the example as well.

[cmhhelgeson]

I updated webgpu_compute_water, now we can use a single storage buffer to send multiples datas.

Looks cool. If I have time this week, I think I'll update the helper functions in compute_water to return structs and have defined function layouts as well. The current helper functions for indices work fine, but are more fragile than explicitly defining named WGSL/GLSL functions using setLayout, especially if someone tries to call toVar() and assign the same name to variables.

[Mugen87]

@sunag @Spiri0 Awesome work! 🎉

[Mugen87]

@cmhhelgeson While you are at it: Can you also check why webgpu_compute_water currently breaks with a WebGL 2 backend? The demo reports a runtime error in the vertex shader:

THREE.WebGLProgram: Shader Error 1282 - VALIDATE_STATUS false
Program Info Log: Must have a compiled vertex shader attached:
SHADER_INFO_LOG:
ERROR: 0:53: 'ndefined' : syntax error
VERTEX
ERROR: 0:53: 'ndefined' : syntax error

The ndefined looks suspicious...

[Mugen87]

Nit: It would be great to document this module and StructType 😇 .

[Spiri0]

Ah here we go, very nice. Now threejs is really drawIndirect capable 💪 😊
Maybe I'll do more extensive examples in the future, but these simple ones convey quite a lot.
Docu is a good idea. I admit that I am not yet familiar with the standards. I have to read the threejs wiki.

[cmhhelgeson]

@cmhhelgeson While you are at it: Can you also check why webgpu_compute_water currently breaks with a WebGL 2 backend? The demo reports a runtime error in the vertex shader:

THREE.WebGLProgram: Shader Error 1282 - VALIDATE_STATUS false
Program Info Log: Must have a compiled vertex shader attached:
SHADER_INFO_LOG:
ERROR: 0:53: 'ndefined' : syntax error
VERTEX
ERROR: 0:53: 'ndefined' : syntax error

The ndefined looks suspicious...

I'll see what I can do, but I've been time limited since the fall, so it might be a bit. Still got to get back to subgroupFunctionNode and additional compute samples as well.

[mrdoob]

This breaks in gh-pages:
https://threejs.org/examples/?q=struct#webgpu_struct_drawindirect

[Mugen87]

#30432

[cmhhelgeson]

@cmhhelgeson While you are at it: Can you also check why webgpu_compute_water currently breaks with a WebGL 2 backend? The demo reports a runtime error in the vertex shader:

THREE.WebGLProgram: Shader Error 1282 - VALIDATE_STATUS false
Program Info Log: Must have a compiled vertex shader attached:
SHADER_INFO_LOG:
ERROR: 0:53: 'ndefined' : syntax error
VERTEX
ERROR: 0:53: 'ndefined' : syntax error

The ndefined looks suspicious...

@Mugen87 I just started looking into this issue twenty minutes ago, and it seems like it might be an issue with the getTypeFromAttribute function in GLSLNodeBuilder? In some of the vertex shaders, it appears like the nodeVarying5 variable is correctly assigned a value of float, but in each shader, nodeVarying5 is being assigned to the value of a node buffer attribute. I'm not sure why this would be necessary, as none of the position/vertex shaders are explicitly passing any new varyings to the fragment shader. The water position shader only modifies the existing varying of v_normalView.