Material can specify defines for the shader

[mvaligursky]

Fixes #2962

New public API

Material.setDefine(name, value);

This allows to set values to user defines on a shader. The define is then added to both vertex and fragment shader, allowing a user defined behaviour.

Usage:

// set define on the material. This will force all shaders to be recompiled with this define.
material.setDefine('TEST1', true);
material.setDefine('TEST2', true);

// inside the vertex and fragment shaders, lines like this will be automatically added:
#define TEST1
#define TEST2

// allowing user to test against it
#ifdef TEST1
   // do something
#end

StandardMaterial, ShaderMaterial, GSplat materials and LitMaterial support this.

Examples of shader customisations:

[slimbuck]

I don't really understand why you're exposing defines without values?

[mvaligursky]

I don't really understand why you're exposing defines without values?

We don't need values, in shader code we only test if it exists.
And additionally, our preprocessor does not handle expressions in defines either currently.

[slimbuck]

What do you mean by "we don't need values in shader code"?

As you know, defines are very useful as compile time parameters, we use them everywhere.

Here is an example: https://github.com/playcanvas/engine/blob/main/src/scene/shader-lib/chunks/common/frag/reproject.js#L14C8-L14C15

The alternatives (hard-coded value or uniform) are both worse options.

[mvaligursky]

I see your point, but these are more like a boolean switches for shader features.
We simply do not support generic values / expression in preprocessor. Other than a numerical value.
We can add it later, but this PR uses existing functionality.

[slimbuck]

So my is question is why particularly limit it this way?

Adding support later is possible, but that would (presumably) break public API.

I'm also still curious what doesn't work with defines, given we have lots of this in the engine: https://github.com/playcanvas/engine/blob/main/src/scene/shader-lib/chunks/lit/frag/shadowPCSS.js#L10

[mvaligursky]

for example this does not work:

#define XX 3
#if XX == 3
#endif

we do not handle expressions inside ifdef, we only test for the existance.

And if defines would have values, it'd be expected that they can be used this way.

We could add this without breaking API in the future though. setDefine could accept other values than boolean.

[slimbuck]

#define XX 3
#if XX == 3
#endif

What would happen in the case above? WebGL2 shader works because of glsl preprocessor, but WebGPU fails to compile?

[mvaligursky]

Yep, the preprocessor would assert and fail here:

engine/src/core/preprocessor.js

Line 385 in 7355d30

Debug.assert(correct, `Resolving expression like this is not supported: ${expression}`);

[mvaligursky]

actually, even WebGL would fail here, we preprocess WebGL shader the same way.

[slimbuck]

Ok thanks for explaining. This limitation doesn't change or mitigate the usefulness of define values as constants IMO. And the error would help stop developers from trying it quite early on.

So unless it requires major restructuring work or similar, I'd still vote to support arbitrary define values in material, otherwise it seems like a half feature.

[willeastcott]

Yeah, I think I agree with @slimbuck on that.

[mvaligursky]

I'll add it tomorrow, but I'm not sure it's that useful for shaders used by the forward renderer. For example we do not have a single user case like this currently in whole standard material shader generator. This is more useful for postprocessing and similar shader, for which ShaderMaterial is not applicable.

The boolean only format would allow us to easily expose these to the Inspector in the Editor as boolean toggles for material features. Generic data (that user needs to type in) is less ideal here in the Inspector.

[mvaligursky]

Added support for define values. As discussed, what can be done with the values is limited.