Add a clipping plane property to SpatialMaterial

[qaptoR]

Describe the project you are working on

I am developing a 'euclidean hole' plugin (aka. portals).

This proposed feature works in tandem with my previous PR: godotengine/godot#56664

Using the most common strategies implemented by Valve and detailed in Sebastian Lague's tutorial, the original and duplicate mesh which pass through the portal to create the illusion of a single body must be clipped by the portal to complete the effect.

Describe the problem or limitation you are having in your project

Shader code (used in this completed feature) discards any vertex behind the provided plane.

However, converting all mesh materials to a shader and injecting the code is time consuming and limits the flexibility of making quick adjustments to a regular spatial material.

This complexity increases with the number of meshes chosen to be able to pass through a portal.

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

by baking in the shader code, which does not effect any other shader options, we benefit from the flexibility to turn on and off the clipping portion of the shader through scripts.

Additionally, any mesh with a spatial material can be clipped by a plane. Which improves the pipeline for importing assets that require this feature.

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

Clipping plane turned off

Clipping plane turned on (default (0, 0, 0, 0))

The clipping plane data can be update like any other spatial material property using gdscript.

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

and editor script could likely be written to convert materials from spatial to shader, and inject/remove the code for the effect, but it would have to access editor features, as at the time this material feature was developed there was no way I had found to convert materials using gdscript.

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

such an editor script would be more resource intensive and less intuitive. However, that assessment comes a priori of having written any plugins.

[Calinou]

Related to #1779, #3021 and #3922.

I think it's better to focus on making the default materials extensible, as their default implementation can't grow forever without bound. This is especially the case for features that won't be used in most projects. Otherwise, performance will inevitably go down as more shader variants need to be compiled (or as more branching is done).

PS: discard is slow compared to actual stencil clipping. It's not recommended to use it to discard large parts of a mesh's rendering, especially when the mesh occupies a lot of pixels on screen.

as at the time this material feature was developed there was no way I had found to convert materials using gdscript.

BaseMaterial3D -> ShaderMaterial conversion could be exposed to scripting, but it would only work within editor builds, not in exported projects. That said, in the master branch, it should be possible to implement the same conversion functionality with a script that works in exported project, since Material._get_shader_rid() and RenderingServer.shader_get_code() are both exposed.

In 3.x, VisualServer.shader_get_code() is exposed, but Material.get_shader_rid() isn't. Feel free to open a pull request for that 🙂

[qaptoR]

@Calinou You are so right! That is a far better idea to expose the material for easier custom shader injection.

Also, grazi for the heads up about discard being inefficient. The shader code I used was provided by someone who translated the Unity shader Sebastian lague wrote for his tutorial.

I feel like I've heard it around the Godot doesn't yet have stencil buffering, or that it's slated for 4.0? (wondering if I should look into taking a stab at implemening it, or focus on more pressing features of my game, and wait for more graphics savvy developers figure that out)

and thank-you for all the resources to look up!

[Calinou]

I feel like I've heard it around the Godot doesn't yet have stencil buffering, or that it's slated for 4.0? (wondering if I should look into taking a stab at implemening it, or focus on more pressing features of my game, and wait for more graphics savvy developers figure that out)

Stencil support isn't planned for 4.0, but it could happen in a future 4.x release. For more information, there's also an old discussion about this (back when Godot only had OpenGL renderers): godotengine/godot#23721

See also #1753, which is a very similar proposal.