Add more information about Ubershader to ProjectSettings documentation

[ztc0611]

Your Godot version: 3.5.stable

Issue description: Upon launching the project after tweaking settings related to Asynchronous Shader Compilation with/without caching, the Editor can report the message Async. shader compilation: OFF (enabled for project, but not supported) on launch. There is no information about what this means or what platforms/types of hardware are supported in the docs. (Is it just Windows? Does it work on Intel MacOS but just not ARM Based M1 devices?) I presume this is a hardware issue that Godot can't change, but maybe this is not the case...? I've been trying to understand this for hours and it was even difficult to find the code in the engine that prints this message.

Updating this documentation with more information feels like it could avoid headaches for developers who expect this feature to "just work" because there are no specific warnings to cases where it will be disabled in the docs, besides for mobile and 2D projects. In general I think the "Ubershader"/Async Shader is really lacking in documentation currently, considering how major a feature it can be.

URL to the documentation page (if already existing): https://docs.godotengine.org/en/stable/classes/class_projectsettings.html?highlight=ubershader#class-projectsettings-property-rendering-gles3-shaders-shader-compilation-mode

[Calinou]

Does it work on Intel MacOS but just not ARM Based M1 devices?

Ubershaders require the GL_PROGRAM_BINARY extension to be supported. This is not available on HTML5 for instance. I don't remember the status on macOS/iOS, but I wouldn't be surprised if it's not supported or is broken there (since Apple stopped updating OpenGL past 4.1).

I presume this is a hardware issue that Godot can't change, but maybe this is not the case...?

This is a hardware (or driver) issue that won't change over time.

In general I think the "Ubershader"/Async Shader is really lacking in documentation currently, considering how major a feature it can be.

Unfortunately, I wouldn't expect too much from ubershaders in Godot. It's more of a bandaid than a real fix, due to OpenGL support being so spotty across platforms. Ubershaders didn't turn out to be as effective as we initially hoped. The manual approach to shader caching (showing all objects for 1 frame at game start and ensuring they're not freed) will still give players a better experience, as it'll result in no performance penalty while shaders are compiling in the background and will work on all platforms. The approach can also be used in GLES2 where shader compilation stutter is less of an issue (as shaders are less complex), but it can still be noticed on low-end mobile.

For reference, UE4/5 also struggle with shader compilation stutter (example), and the manual Godot fix is also the best way to fix this in UE4/5. Only consoles can really avoid this problem by having unique hardware configurations, which allow compiled program binaries to be distributed with the game. (Compiled program binaries are not compatible across GPU brands, or even different models or driver versions.)

See godotengine/godot-proposals#4754 and godotengine/godot#64528 for details.

[ztc0611]

The manual approach to shader caching (showing all objects for 1 frame at game start and ensuring they're not freed) will still give players a better experience, as it'll result in no performance penalty while shaders are compiling in the background and will work on all platforms.

I've been trying to get this working for a few days now, and have had no luck. Is there any tutorial for the proper setup for this? I've put them all in an autoload, shown those objects with a camera for 10 frames, then swapped to the full scene (without unloading the autoload, all objects appear in the remote node list after the swap) and still the first copy of an object that appears in that autoload scene causes a shader lag spike.

Also, does Godot 4's Vulkan rendering fix this? If so maybe it isn't worth bothering. I'm likely going to port to it once it comes out, and I severely doubt this game will be finished before 4 is.

[Calinou]

I've been trying to get this working for a few days now, and have had no luck. Is there any tutorial for the proper setup for this? I've put them all in an autoload, shown those objects with a camera for 10 frames, then swapped to the full scene (without unloading the autoload, all objects appear in the remote node list after the swap) and still the first copy of an object that appears in that autoload scene causes a shader lag spike.

This is likely due to the effective shader version being different due to the autoload not having the same configuration (lights, GI).

Also, does Godot 4's Vulkan rendering fix this?

The Vulkan renderer features shader caching, but not ubershaders: godotengine/godot#61233

[TokisanGames]

Both gd3 and gd4 stutter, even with caching, when there are a lot of assets. You need to force precompilation of shaders by showing the materials on screen, not the objects, behind a loading screen.

godotengine/godot#53411 (comment)

godotengine/godot#46330 (comment)

[akien-mga]

Fixed by godotengine/godot#76321.