GLTF: Support MultiMesh objects using EXT_mesh_gpu_instancing

[aaronfranke]

Fixes issue #109280, supersedes PR #107866.

Draft because this depends on PR #113202, PR #113206, PR #113245, and PR #113247.

This PR adds support for importing glTF EXT_mesh_gpu_instancing nodes as Godot MultiMesh nodes:

In master, this extension was not supported, which meant that such objects were not imported as multiple instances.

This PR also adds support for exporting MultiMesh nodes as glTF EXT_mesh_gpu_instancing, and configuring the export behavior. Users can choose to use the extension, use plain glTF nodes, or use both:

Note that the dropdown only appears when the scene contains at least one MultiMeshInstance3D node, so it won't clutter the export settings UI in most cases where the user does not have any such nodes in their scene.

The options have the following behavior:

• Optional EXT_mesh_gpu_instancing: Convert MultiMesh nodes into the EXT_mesh_gpu_instancing extension. The extension is marked as not required, so implementations without support can still load the file, but they will see a single mesh instead of multiple instances of meshes.
• Required EXT_mesh_gpu_instancing: Convert MultiMesh nodes into the EXT_mesh_gpu_instancing extension. The extension is marked as required, so implementations without support cannot load the file.
• Multiple Nodes Only: Convert MultiMesh nodes into multiple glTF nodes. This is similar to the existing behavior in master, but there are multiple bugs with the current master, which have been fixed in this PR.
• Multiple Nodes Fallback: Convert MultiMesh nodes into both the EXT_mesh_gpu_instancing extension and multiple nodes, allowing it to be imported as a MultiMesh when supported, or imported as nodes when not supported.

Here's what it looks like when loading a glTF exported with "Multiple Nodes Fallback" into Godot 4.5-stable:

This PR also makes several related changes:

• Add a function to GLTFState to reserve a unique name (previously was private to GLTFDocument).
• Fix a bug where MultiMesh's own transform was multiplied into each instance.
• Fix a bug where 2D MultiMesh transforms were swapping the Y coordinate into Z.
• Fix a bug where the material name was used as the surface name instead of the surface name.

Test files: ext_mesh_gpu_instancing.zip

[fire]

Adding multimesh support to godot engine gltf is a good idea. Need to pick a time to review. Other reviewers are welcome too.

[aaronfranke]

I split this into PR #113202, PR #113206, PR #113245, and PR #113247. These can be merged first, and then I can rebase and undraft this PR.

[fire]

Seems to be blocked on #113247

[mikest]

I gave this branch a go on top of master and it works as advertised. 1440 draw calls down to 1 😎

[fire]

Seems to be ready to go. Some good user testing too!

Does multimesh instancing in gltf support skinned meshes? How does this handle it?

[aaronfranke]

@fire No, skinned meshes are out of the scope which MultiMesh and EXT_mesh_gpu_instancing are meant to cover.

[fire]

I think this is a good idea. Requires QA. #112866 (comment) may be sufficient qa.

Did not test.

[mikest]

Tested against master from 15min ago. Still working well.

[Ansraer]

Hmm, I wonder if it might make more sense to instead import a single mesh resource during import and have multiple MeshInstances that all reference that single mesh resource.
IIRC we automatically batch MeshInstances that share a material and mesh together before they are rendered, so the gpu cost should be almost identical unless the instace count is very high.
With MI we would also get more accurate culling (since MMI are culled based on a combined AABB), which could be important for GPU perf if the meshes are on the heavy side.

I am not convinced that this will necessarily result in better performance. I don't think we support combining multiple MultiMeshInstance, so each of them would end up as an individual draw call. So depending on the scene this might end up resulting in a performance regression compared to using duplicates as we currently do.

e.g.: I have a table asset, which has 4 identical legs and one tabletop. I want to render 200 tables.

Without using any kind of instance import this would result in us rendering each of the table legs once and then the table top, each with 200 instances. So rendering my entire scene would happen with just 5 draw calls.

However, if MultiMeshes are used instead (as implemented by this PR) we could now render a single table using one MeshInstance (top) and one MMI (the four legs). Since MMI can't automatically be combined rendering out entire scene would now take 201 draw calls. (200 * MMI + 1 mesh instance for the batched table tops).

If we instead could use MeshInstances for the leg instances and have all of them reference the same Mesh object we should be able to automatrically combine them when rendering, so the entire scene could be rendered with just two draw calls (one for all the legs, the other for the top).

[mikest]

so the gpu cost should be almost identical unless the instace count is very high.

I have instance counts that can reach tens of thousands (feathers, roof tiling, stone walls, etc). While the server can coalesce the meshes, the MeshInstance3D overhead from that is not negligible even when coalesced.

There is a separate issue with the blender importer not reusing mesh instances (outside of geometry nodes) that should also be fixed at some point, but that seems like a separate issue.

Regardless, the current geometry node behavior is very taxing on performance.

[aaronfranke]

@Ansraer This PR does not automatically combine anything into MultiMesh / MultiMeshInstance3D. It only generates MultiMeshInstance3D where EXT_mesh_gpu_instancing data exists in the glTF file. And that data only exists when the file author explicitly chose to use this technique when making the file.

[mikest]

I have done the following testing:

• Blender 4.5 & 5.1 imported files
• Imported GN nodes with instance counts >10,000

No issues discovered yet.