Implement Instancer LODs

[laurentsenta]

Admin edit
Fixes #617

• Adds support for up to 10 LODs to the instancer
• Adds the ability to hide all instances rendering/show_instances
• Adds the ability disable MMI generation for individual meshes

---

Contributes to #43
Introduce four levels of LODs for multimesh instances and min / max shadow lods.

See thread in Discord

Task list:

• Decide on using an array or hardcoded floats for the distances
• Actually use the LOD'd mesh in the instancer
• Shadow LOD
• figure out the visibility margin thingy
• Fix the "everything resets on loading" issue
• Remove visibility range, and figure out upgrade path
• Field validation
• Update
• Cleanup
• Shadow min / max config
• Field validation (bis)
• Update the doc
• Also update the notes on "in the future we'll chunk MMIs" this is already implemented

Regarding validation:

This PR introduces a bunch of fields that are related to each other:

• maximum lod value is valid if the scene is loaded and must be less than mesh count
• maximum shadow lod is valid if <= maximum lod and >= minimum shadow lod (and vice versa for minimum shadow lod)
• Cast Shadows validity depends on the shadow lods:
  • if cast shadow is double-sided or shadows only, it will interact weirdly with min/max shadow lods

Checking values in the setters will be super annoying to use, as in "I'm trying to lower the maximum lod, but nothing happens" > "yes, you need to lower the minimum shadow lod first".

This is a perfect use case for configuration warning, which is a work in progress:

• [4.4] Configuration warnings may change implementation #321
• Rework the Configuration Warning system godotengine/godot#90049

[Xtarsia]

Very nice work overall.

Cory will be along asking for a good squash no doubt..

The demo changes can likley be dropped unless you want to spend time tidying them up.

Docs effort is stellar!

[TokisanGames]

Cory will be along asking for a good squash no doubt..

It can be squashed down to 3 commits: code, docs, demo changes.

I'll review in a couple of days after Xtarsia is satisfied and I get more progress on my collision commit.

[Saul2022]

Looking great, just one curiosity, so to add lods, we do it like we usually do with visibility ranges and hlod.

[TokisanGames]

@Saul2022 Should be able to setup lods in your mesh scene like this, and that's it. Or adjust defaults if desired.

[TokisanGames]

Alright, very good work on this. Thank you for the effort. Please rebase it as you address the notes.

• Playing with the options and thinking about the names, I think they can use some adjustments to be clearer. I'd prefer to move away from "higher, lower, minimum, maximum" because lods numbers are a reverse scale, where higher/better is a lower number. The docs say "lods above this...", does "above" mean "larger number / lower detail"? Or "higher detail / lower number"? Does "maximum lod" mean "maximum distance / lowest detail" or "maximum detail / lowest distance"? I think "last" is not only shorter, but more universal in meaning lowest detail, farthest away.

  • maximum_lod means "don't show lods lower than this lod". I think last_lod is a little better. It's also lod_count-1.
  • maximum_shadow_lod means "show shadows for this lod and higher(0) - ie don't show shadows for lods lower than this value". This would be better named last_shadow_lod.
  • minimum_shadow_lod means "use this shadow impostor lod or lower(3) - ie when showing a lod higher(0) than this lod, use this one as its shadow impostor". This would be better named max_shadow_imposter_lod, or max_shadow_lod.

• If minimum_shadow_lod is > maximum_shadow_lod, the latter doesn't work. Or more clearly, if max_shadow_imposter_lod > last_shadow_lod, then it shows shadows beyond the last_shadow_lod. Given the above descriptions it should not. It should only show shadows for lods up to last_shadow_lod.

• I actually don't think we need a maximum_shadow_lod. Lights already have a shadow distance. We don't need to cull it ourselves. Having it prevents us from needing to create and store the MMI, but that generation is quick and only on start, and the memory should be shared with my related note elsewhere.

In my specifications here on discord I expressed the need for maximum_lod(last_lod) and shadow_lod. The lods should show shadows at all distances that the user has configured their Lights for, it just may be at a lower level LOD.

• MeshAsset/Cast Shadows / shadows only doesn't work. Shadows Off does work.

• MeshAsset set_scene_file doesn't do any filtering or sorting on meshes named LOD0-LOD3. It happens that sometimes the LODS might be out of order for an artist or an engine reason. I would look for all of the mesh instances that end in LOD#, then sort them and use the first 4. If I couldn't find any LODs, then just take the first original 4. Maybe print some messages saying, "found 8 lods, using the first 4." or "Meshes don't end with LOD#, assuming first 4 are LOD0-LOD3".

• MeshAsset set_scene_file - You could also fix a bug where if they provide a scene with a MeshInstance3D as the root node, it won't use it. Probably because the find_child starts looking at the children and ignores the scene root.

[TokisanGames]

I'll take this over from here. Thanks for all of your efforts.

[TokisanGames]

This PR is ready for final testing and code review. After that I'm going to reorder the code and merge it in.

[TokisanGames]

Alright this is finished.

@laurentsenta Thank you very much for the first implementation and excellent effort on the docs. Both gave us a solid base to improve on.

@Xtarsia thanks for the reviews and testing.