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.

[Spiri0]

I'm looking for the example webgpu_struct_drawindirect
That probably didn't end up in r173. I'm trying to understand why I get the following error message in my app:

127.0.0.1/:1 Error while parsing WGSL: :26:39 error: unresolved type 'DrawBuffer'
fn compute ( drawBuffer: ptr<storage, DrawBuffer, read_write>, )  {
                                      ^^^^^^^^^^


 - While validating [ShaderModuleDescriptor "compute"]
 - While calling [Device].CreateShaderModule([ShaderModuleDescriptor "compute"]).

[sunag]

It looks like the master branch is out of date.

[sunag]

@Spiri0 I updated the master branch.

[Spiri0]

@Spiri0 I updated the master branch.

Ah yes, that was it, thanks sunag. Now I have also found the cause of my error message.
At the end of the structs there must be the name as used in wgslFn. I like it.

Unfortunately it still doesn't work, but I think I understand the reason
It seems like no struct arrays are recognized?

Error while parsing WGSL: :114:185 error: type mismatch for argument 10 in call to 'main_vertex', expected 'ptr<storage, array<ObjectInfo>, read>', got 'ptr<storage, ObjectInfo, read>'
  varyings.Vertex = main_vertex( render.cameraProjectionMatrix, render.cameraViewMatrix, object.nodeUniform2, 0.0, u32( 0.0 ), vertexIndex, instanceIndex, 128.0, &NodeBuffer_572.value, &NodeBuffer_573, &NodeBuffer_574, &NodeBuffer_575 );
                                                                                                                                                                                         ^^^^^^^^^^^^^^^

 - While validating [ShaderModuleDescriptor "vertex"]
 - While calling [Device].CreateShaderModule([ShaderModuleDescriptor "vertex"]).

In my extension, the length of the struct was compared with the length of the StorageBufferAttribute. If the lengths were equal then it was a simple struct
ptr<storage, ObjectInfo, read>
and if the length was an integer multiple then it was a struct array and the WgslNodeBuilder used
ptr<storage, array<ObjectInfo>, read>

const objectInfoStruct = struct( {
	meshID: 'uint',
	meshletID: 'uint',
	padding: 'uvec2',
}, 'ObjectInfo' );

const meshMatrixInfoStruct = struct( {
	modelWorldMatrix: 'mat4',
}, 'MeshMatrixInfo' );

...

//for each meshlet a struct is in the storage array. 
//In this way you can store datas from a large number of meshes excellently

this.objectInfoBuffer = new THREE.StorageBufferAttribute( new Uint32Array( size * this.meshletCount * 4 ), 4 );
this.meshWorldMatrixBuffer = new THREE.StorageBufferAttribute( new Float32Array( size * 16 ) , 16 );
...

I store hundreds or thousands of mesh matrices in one storage. Thanks to the struct arrays,
I can immediately retrieve the data of a specific mesh at any time using just an index.
I use several such struct arrays. Hence the very good performance so that I don't see any frame drops.
struct also doesn't seem to have a .length function with which you can get the number of members.
I didn't use a struct array in the drawIndirect example to keep it simple.
That's probably why it fell by the wayside.

I have to take a closer look at your extension. Maybe you do things differently with the arrays so that I have to explicitly mark struct arrays as struct arrays

[Spiri0]

@sunag For a simple test, I simply intercepted my specific structs in the WGSLNodeBuilder and provided them with an array

if( uniform.node.structTypeNode.name == "MeshMatrixInfo" || uniform.node.structTypeNode.name == "DrawBuffer") {

	bufferSnippets.push( `@binding( ${ uniformIndexes.binding ++ } ) @group( ${ uniformIndexes.group } ) var<${ bufferAccessMode }> ${ uniform.name } : ${ bufferType };` );
					
}
else{

	bufferSnippets.push( `@binding( ${ uniformIndexes.binding ++ } ) @group( ${ uniformIndexes.group } ) var<${ bufferAccessMode }> ${ uniform.name } : array< ${ bufferType }>;` );
}

In addition, I gave the struct a property to be able to read the number of members:

Object.defineProperty( struct, 'length', {
		
	get() {

		  return Object.keys( membersLayout ).length;

	}

} );

And everything is working fine.
So it's just the little thing with the array for array structs, not a big thing. I can take a closer look at it and think about how to neatly incorporate the case distinction if you wish. Unless you already have a clear idea of ​​it.

P.S. I made a PR for this