Rework BaseMaterial3D deep parallax implementation and add new features

[Calinou]

The deep parallax effect now features built-in interpolation to make low layer counts look better. It also integrates Z correction for a more convincing depth effect at oblique angles.

The new features are disabled by default, but allow for greater realism at a performance cost. Each of them can be enabled separately:

• Correct Shadow Receive: This allows the material to receive shadows (and even cast self-shadows) according to the deep parallax effect. Self-shadowing is powered by the existing shadow map system, so it works best with sharp shadows such as the ones cast by OmniLight3D and SpotLight3D, especially when placed at grazing angles. This only has a small performance cost, but it can cause self-shadowing artifacts if lights have a shadow bias that's too low or if the material has a heightmap scale that's too high. Enabling Write Depth at the same time can alleviate those self-shadowing artifacts, with the associated performance cost of that feature.

  • For a self-shadowing implementation that works directly in the shader (without even needing lights to have shadows enabled), Add an option to provide custom light occlusion functions godot-proposals#8671 would have to be implemented first.

• Write Depth: This allows the material to correctly interact with other materials in the scene, regardless of whether the other materials have deep parallax enabled. This has a significant performance cost.

• Trim Edges: This allows the material to have its silhouette affected by the deep parallax effect. This works best with certain UV layouts, but it can have artifacts if the UV layout has visible seams. This has a moderate performance cost.

Thanks to @sphynx-owner who made the initial implementation and Tentabrobpy from the Godot VFX Discord for further assistance 🙂

• This closes Added z-corrected option for parallax #62002 by superseding it and partially addresses Add self-shadowing to parallax occlusion mapping in StandardMaterial3D godot-proposals#1843.

Testing project: https://github.com/Calinou/godot-parallax-test-4.0

Preview

parallax_1.mp4

parallax_2.mp4

Comparison with default settings

8/32 layers (default quality)

Before	After

64/64 layers (maximum quality)

Before	After

Visual impact of each feature being toggled

None	CSR1	WD2

TE3	CSR1 + WD2	CSR1 + TE3

WD2 + TE3	CSR1 + WD2 + TE3

Benchmark

PC specifications

• CPU: Intel Core i9-13900K
• GPU: NVIDIA GeForce RTX 4090
• RAM: 64 GB (2×32 GB DDR5-5800 C30)
• SSD: Solidigm P44 Pro 2 TB
• OS: Linux (Fedora 40)

Measured using the test scene shown in the Before/After comparison before. Materials cover most (but not all) of the view. Using a 3840×2160 viewport.

Features	Performance
None	843 FPS (1.19 mspf)
CSR1	856 FPS (1.17 mspf)
WD2	351 FPS (2.85 mspf)
TE3	689 FPS (1.45 mspf)
CSR1 + WD2	350 FPS (2.86 mspf)
CSR1 + TE3	689 FPS (1.45 mspf)
WD2 + TE3	341 FPS (2.93 mspf)
CSR1 + WD2 + TE3	344 FPS (2.91 mspf)

TODO

• Investigate Correct Shadow Receive not having a visible effect when using the Compatibility rendering method. Is it due to an engine bug?
• Investigate Write Depth being broken when using the Compatibility rendering method. Is it due to an engine bug, or is some kind of specific adjustment needed here?
  • Since this is a demanding feature, it could also always be disabled when using Compatibility.
  • Edit: Possible hint at why it's broken: Add Depth Offset property to BaseMaterial3D and fix collision shape gizmo flicker #100211 (comment)
• When Write Depth is enabled, see if we can disable the depth prepass without having to use discard within if (false). Since Write Depth does not actually require using discard, doing so would probably improve performance a bit. For reference, the Mobile rendering method (which lacks a depth prepass) works fine without this discard statement (although removing it reintroduces the occasional self-shadowing artifacts that occur when Correct Shadow Receive is enabled).
  • Or, better, see if the depth prepass can be kept when Write Depth is enabled, by having the depth prepass shrink the material's vertices (only within the depth prepass), so that it can still be effective and improve performance significantly.
• Check the interactions with the UV Scale property again to ensure Correct Shadow Receive looks as good as possible regardless of the scale. Right now, it can get a bit off when the scale is changed from the default (i.e. when the texture tiles more often), although it's not too noticeable during actual gameplay.
• Consider combining Correct Shadow Receive and Write Depth into a single enum option, since there isn't much point in having Write Depth enabled but not Correct Shadow Receive. This means there would be 3 options provided: Disabled, Correct Shadow Receive, Correct Shadow Receive + Write Depth.

Footnotes

1. Correct Shadow Receive ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸

2. Write Depth ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸

3. Trim Edges ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸

[Calinou]

I've pushed an update that makes use of @tetrapod00's suggested fix for Compatibility. However, it causes a shader compilation error:

SHADER ERROR: Tokenizer: Unknown character #35: '#'
          at: (null) (:96)
ERROR: Shader compilation failed.
   at: set_code (./drivers/gles3/storage/material_storage.cpp:2983)

For some reason, preprocessor macros don't work in the shader generated in BaseMaterial3D, even though it doesn't use #pragma disable_preprocessor. They start working if you convert it to a ShaderMaterial.

[solitaryurt]

MacOS x86_64 (Forward+), looks like its not working:
Deep Parallax disabled:

Deep Parallax enabled:

Used build from: Calinou@1f6e871

Same shader compile error from above.

[Calinou]

MacOS x86_64 (Forward+), looks like its not working:

This is expected for now until we fix BaseMaterial3D to allow using shader preprocessor within its generated code. This should be done in a separate PR.

[solitaryurt]

MacOS x86_64 (Forward+), looks like its not working:

This is expected for now until we fix BaseMaterial3D to allow using shader preprocessor within its generated code. This should be done in a separate PR.

Is there an older hash I could build without the shader compilation issue?

[Calinou]

Is there an older hash I could build without the shader compilation issue?

No, but you can remove the uses of the shader preprocessor within the PR's changes if you only intend to use Forward+/Mobile in your project.

[solitaryurt]

None:

Correct Shadows:

Write Depth:

Correct Shadows + Write Depth:

Unfortunately the mesh I'm using isn't happy with Trim Edges:

[solitaryurt]

I'm sure Trim Edges and Write Depth will meet the needs of many people who desired displacement mapping.

I will note that I believe the addition of these features makes godotengine/godot-proposals#2455 even more relevant now.

[Calinou]

Unfortunately the mesh I'm using isn't happy with Trim Edges:

It doesn't work well with repeating textures unfortunately, since UV will go outside the [0; 1] range. I'm not aware of a way to make it work with repeating textures (unless the number of texture repetitions is known in advance and configured in the material - which is how it can work with the UV Offset/Scale property).

[fire]

Where uvs go outside the range I have discovered a cutting method described by Steve Steeting (Sinbad of Ogre3D) https://github.com/sinbad/FbxUdimUnpack?tab=readme-ov-file#fbx-udim-unpacker

[solitaryurt]

I noticed that when "Deep Parallax" is enabled both "Flip Tangent" and "Flip Binormal" don't appear to have an effect. Is that intended?

[solitaryurt]

Is there any possibility of anti-aliasing the edges Trim Edges or Write Depth?

I noticed some aliasing:

[Calinou]

Is there any possibility of anti-aliasing the edges Trim Edges or Write Depth?

Not by MSAA, because the edges are created by a shader and not by geometry. However, all other antialiasing methods that are based on post-processing (TAA, FXAA, FSR2, SSAA, SMAA) will work.

[Calinou]

Rebased and tested again on Linux + GeForce RTX 5090 (NVIDIA 580.119.02), I get a driver crash when enabling Deep Parallax on a material. --accurate-breadcrumbs doesn't tell me much:

ERROR: Condition "err != VK_SUCCESS" is true. Returning: FAILED
   at: fence_wait (drivers/vulkan/rendering_device_driver_vulkan.cpp:2962)
ERROR: Printing last known breadcrumbs in reverse order (last executed first).
   at: print_lost_device_info (drivers/vulkan/rendering_device_driver_vulkan.cpp:6861)
ERROR: Searching last breadcrumb. We've sent up to ID: 39
ERROR: Last breadcrumb ID found: 37
ERROR: Last known breadcrumb: BLIT_PASS
ERROR: Last known breadcrumb: UI_PASS
ERROR: Last known breadcrumb: BLIT_PASS
ERROR: Last known breadcrumb: UI_PASS
ERROR: Last known breadcrumb: BLIT_PASS
ERROR: Last known breadcrumb: UI_PASS
ERROR: Last known breadcrumb: BLIT_PASS
ERROR: Last known breadcrumb: UI_PASS

[Foyezes]

Enabling Deep Parallax with heightmap crashes for me.

crash_log_d3d12.txt
crash_log_vulkan.txt