Add support for storing Shader Material parameters in external resources

[dougVanny]

As per the instructions in the repo home, despite having a good idea of how an API for this proposal could work, I wouldn't be able to implement it myself at the present time, and also would rather open up to discussion with people who actually understand of the inner works of the engine before making an official proposal. Please let me know if there are any issues

Describe the project you are working on

A game with heavy use of custom shaders with parameters that are shared across multiple materials

Describe the problem or limitation you are having in your project

In my project, many materials from different shaders share similar effects. Effects include dimming the material if it's far away, dithering it if it's between the player and the camera, as well as some other project specific effects. Currently I am able to use ShaderIncludes to share the code, the behavior itself:

// color_distance.gdshaderinc

group_uniforms ColorDistance;
  uniform float max_distance = 10.0;
  uniform float dim_intensity = 0.5;
group_uniforms;

vec3 apply_distance_to_color(vec3 original_color, float fragment_distance)
{
  return original_color * max(0.0, 1.0 - (fragment_distance/max_distance)) * dim_intensity;
}

// example_shader.gdshader

shader_type spatial;

#include "color_distance.gdshaderinc"

uniform vec3 base_color: source_color = vec3(1.0);

void fragment()
{
	ALBEDO = apply_distance_to_color(base_color, length(VERTEX));
}

By doing this, on your material you would end up with the following interface

While this solves the problem of sharing the behavior, this doesn't help with the parameters themselves. If I have many different materials all referencing color_distance.gdshaderinc, I am left with no option but to guarantee manually that the values are the same across all materials. A global uniform could help in a case similar to this, but if I have different use cases such as, wanting different paremeters for large and for small objects, globals are no longer an option. Similarly, I'll also have issues if I ever want to change those values.

Describe the feature / enhancement and how it helps to overcome the problem or limitation

The solution for this problem is not so different from how it's handled in GDScript. By having a thing such as an GDShaderResource, the ShaderMaterial would need only to reference that resource, and all parameters would be immediately shared across all materials that make use of it

A similar proposal exists on #3569 but it focuses on allowing structs to be used as uniforms. This helps in terms of usability, but it does not solve the issues presented on this proposal. Also, despite any similarities, I don't believe this supersedes it in any way as GDShaderResources would as different from a GDShader structs as regular GDScript Resources are from regular GDScript structs

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

GDShaderResource

The way I imagine this being implemented, it would be needed to create a GDShaderResource that would contain nothing but the structure of one single Shader Resource type. For example:

// color_distance.gdshaderres

resource ColorDistance
{
  float max_distance = 10.0;
  float dim_intensity = 0.5;
}

This GDShaderResource could then be referenced from any GDShader or GDShaderInclude, and that would allow for the use of that resource type as any other type, but also allow it's use as an uniform. For example:

// color_distance.gdshaderinc

#using "color_distance.gdshaderres"

uniform ColorDistance color_distance

vec3 apply_distance_to_color(vec3 original_color, float fragment_distance)
{
  return original_color * max(0.0, 1.0 - (fragment_distance/color_distance.max_distance)) * color_distance.dim_intensity;
}

by doing this, the material interface would look like something as follows

Now we only need a way to assign something to that empty field

ShaderResource

A ShaderResource would be a type of regular Resource very similar to the ShaderMaterial. Where the ShaderMaterial references a GDShader and then enables storing all shader uniforms in that resource as parameters, a ShaderResource would do the same by referencing a GDShaderResource. That would theoretically allow the user to create Shader Resources as needed, and possibly save them in the FileSystem to share it across multiple materials.

If this enhancement will not be used often, can it be worked around with a few lines of script?

There are possible workarounds but they hardly escalate well. You could make a script to copy a previously configured selection of parameters from one material to the other, and also have a similar script that will know of all materials in the project that make use of those parameters and update them whenever needed. These solutions are very error prone and become more and more nonviable as the project grows. They also require all materials to be stored as an external resource so they can be referenced intuitively

Is there a reason why this should be core and not an add-on in the asset library?

I don't believe it's possible to implement changes to how shader files are parsed and handled just with an addon

[dougVanny]

Commenting on a few issues that I foresee with this idea

---

Subresources and cyclic references

I believe it should be possible to store resources within resources. For example, having a big Shader Resource to store information about the atmosphere of an area, and within it have resources for smaller operations such as dimming based on distance, as used as an example in the main proposal

This of course leads to an issue where Resource A could reference Resource B, which could then reference Resource A. I don't think this should be supported, as I'm working with the assumption that shaders simply don't support references. The entire content of the resource should be available, it's size being always the same

---

Supported types within a resource

The two main types that I think could be problematic with resources are samplers and arrays

I could see someone wishing they could store a reference to a texture inside a shader resource, and with simple resources I don't see why it shouldn't work

I also see people wanting to use arrays inside resources, and as long as their length is fixed, I think it should be possible, not unlike with regular uniforms

What would cause a problem would be an array of resources. While this doesn't change much for an array of floats, for example, it does conflict with the possibility of adding samplers to an resource

Between arrays or resources and sampler support inside resources, I would be personally inclined to go with the later

---

Leaving resource fields empty

Unless I'm mistaken, shaders don't work with references, so you couldn't easily to something like resource_field == null

In this case, I would assume all the fields of the resource would always be accessible. Maybe they'll have default values, or maybe pure garbage

It would be good, however, to have a way of testing if the field is empty or not. I would consider an auxiliary function for that, something like an is_valid(resource_field). Under the hood, I imagine a single bool being sent within the resource just to record if there is a real resource in that field or not.

---

Handling resources of the wrong type

Being the ShaderResource a resource like any other, the user could end up changing the referenced GDShaderResource, therefore making that resource not match the expected type at all. Even with plenty guardrails, the chance still exists

An warning would be welcome in this case, of course, but other than that, in terms of what actually happens with that material, I believe we could use the same is_valid(resource_field) function proposed in the topic above to let the shader handle such case the same way as if the field were empty

---

#include "gdshaderres"

Unless there is another solution I'm not seeing. I believe that each GDShaderResource file would need to store just the descriptor of a single resource struct. Using #include would, however, expand that file wherever it is used, leading to a file having multiple resource struct definitions

Unless this isn't an issue, I would see two options. Either to treat #include a different way when referencing a gdshaderres, or having a new keyword just for resources. I was imagining something such as #using, but other options may exist

This becomes less of an issue if we ignore the usage of subresources, as described in the first section of this comment

---

Storing functions inside a GDShaderResource

Something I expect a lot of people to consider a possibility at first, specially if they think of resources as classes. Even looking at the example at the main post, it looks like the function from the Shader Include and the Shader Resource descriptor could live in the same file

I don't currently have a good solution for this, but then, this looks like an use case that could be made into a proposal of its own, once and if this one goes forward

---

Modifying a GDShaderResource in runtime

This is mostly a concern from someone who doesn't fully understand the whole shader pipeline, but I would guess that, if a GDShaderResource is updated in runtime, it could lead up to many, many materials being updated at the same time. If this is an issue, we might need to consider how to handle it, be it with documentation, warnings or by removing the setters from such resources

---

These are the issues I could think of so far. I'm sure there are many others that are beyond my comprehension, which is why I thought this might require more discussion before being formalized as a proposal