Add custom shader support to SpriteBase3D

[chocola-mint]

Closes godotengine/godot-proposals#3266

godot-sprite3d-custom-shader-demo.mp4

This PR lets custom shaders (via Material Override) access the sprite texture used by SpriteBase3D. (and its child classes Sprite3D and AnimatedSprite3D by extension)

Validation is implemented to warn the user if a Material Override without the necessary uniforms (namely uniform sampler2D texture_albedo and uniform ivec2 albedo_texture_size) is being used. The "Flags" group properties of SpriteBase3D are also hidden when a Material Override is being used, as those properties are used in the default automatic material generation. (StandardMaterial3D::get_material_for_2d()) The user can reimplement those features in the custom shader code anyway, so they have been hidden.

Side note: This pattern of requiring the shader to have uniforms of specific names and types can be turned into a reusable "shader interface/trait" system if needed. Users could make their own high-level 3D nodes that send data to shaders like SpriteBase3D does. (Maybe a more advanced version of Sprite3D that assigns normal maps and SDF texture maps as uniforms) The main benefit of such a system would be to reduce the amount of builtin shader types, though. (No need to add a new sprite_3d shader type) Though this probably would have to be a separate proposal.

---

This PR was originally made to add custom shader support for AnimatedSprite3D in particular, but it is evident that implementing the support for SpriteBase3D makes more sense here.

[Calinou]

Tested locally, it works as expected.

Testing project: test_pr_103274.zip

Some feedback:

• There should be a Sprite3D shader template you can choose from, with the correct uniforms already in place:

The shader template could also have render_mode unshaded; below shader_mode spatial;, as most Sprite3Ds are used in an unshaded manner (this is their default property).

Note that if #103312 is merged before this PR, the cache key should vary depending on the custom shader used. It should be possible for meshes with the same ShaderMaterial resource to be reused, but different shaders will require a different cache key.

[chocola-mint]

Tested locally, it works as expected.

Testing project: test_pr_103274.zip

Some feedback:

• There should be a Sprite3D shader template you can choose from, with the correct uniforms already in place:

The shader template could also have render_mode unshaded; below shader_mode spatial;, as most Sprite3Ds are used in an unshaded manner (this is their default property).

godot-sprite3d-custom-shader-template.mp4

• The Sprite3D shader template is only shown when the shader mode is set to Spatial.
• A minimal example that uses vertex color (thus supporting SpriteBase3D.modulate) and the albedo texture is attached.
• The required uniforms are properly commented as such.

Note that ShaderCreateDialog doesn't seem to support adding custom shader templates in the first place, so I've taken the liberty to make it a bit easier to add hardcoded shader templates. Perhaps a future feature proposal could expand on this and make it more similar to script templates in terms of ergonomics.

[BastiaanOlij]

Just looking at this because it came up during the rendering meeting, with clay on holiday don't want to make an in-depth judgement call.

But my question would be, why make this work with a special uniform? Why not make this work with the normal albedo color hint so the code is the same as with normal geometry? What makes this a different situation?

[chocola-mint]

Just looking at this because it came up during the rendering meeting, with clay on holiday don't want to make an in-depth judgement call.

But my question would be, why make this work with a special uniform? Why not make this work with the normal albedo color hint so the code is the same as with normal geometry? What makes this a different situation?

Oh, I was admittedly not aware of the source_color hint's existence.

The design here was so the code path is consistent between both cases. texture_albedo and texture_albedo_size are both uniforms that are configured for the default Sprite3D material. (StandardMaterial3D::get_material_for_2d)

I see how it's possible to replace texture_albedo by looking for a sampler2D uniform with HINT_SOURCE_COLOR instead. There isn't an equivalent hint for texture_albedo_size, however.

Though texture_albedo_size is only used to calculate the MSDF and is technically optional. (My example there didn't use it either) So we could just not set texture_albedo_size for custom materials. What do you think?

[chocola-mint]

@BastiaanOlij

(Rebased to fix conflict with ad9b661 )

Follow up: I think there's an actual argument against using HINT_SOURCE_COLOR (corresponding to the source_color hint) here.

• A quick search into the engine's source code shows that there's no existing code that looks for a uniform with a specific hint and assigns values to it.
• HINT_SOURCE_COLOR is mostly used so Godot knows to make a texture work as a color texture.
  • It's not even possible to retrieve this information at the moment. ShaderLanguage::uniform_to_property_info (used by RenderingServer::get_shader_parameter_list) is unable to include this information and we can't tell if a sampler2D uniform is source_color, hint_normal, or some other hint.
  • Even if we could, this would mean that uniform order now matters and if someone has multiple source_color uniforms, they must be aware that the first will be assigned the sprite texture by Sprite3D.

As such, I think the current approach is fine as-is.