Meshers as resources

[Zylann]

This is a change I'm working on:

How meshers worked

Meshers are what turns voxel data into meshes. They can produce colored cubes, batched models, or smooth meshes like transvoxel does, and they are used from multiple threads at once. So far, these meshers were hardcoded. They were chosen only based on the voxel data. If your voxels had SDF, smooth meshes were produced. If they had TYPE data, batched models would be used (aka "Blocky"). Their parameters were hardcoded as well. Recently, a new mesher for colored cube voxels was added and making it available to the terrain system would have required hardcoding it too, if you put data in the COLOR channel. All those meshers are already available to the script API as standalone classes, but only a few can be used with the terrain system. Furthermore, the way things are going, it might no longer be possible to determine which mesher to use solely from the channels.

The changes

So instead of keeping this pattern, I decided to generalize the way meshers are used. Meshers will now be resources. You'll be able to create them in the inspector, set their parameters, save them as files and re-use them. You'll be able to choose which mesher will be used for a given node. It will also be much easier to introduce a new type of mesher, since all it takes is to derive the VoxelMesher class, and implement methods accordingly. This also brings the module closer to integrating MagicaVoxel models into the terrain system.

The breaking changes

• VoxelTerrain no longer has a VoxelLibrary parameter. Instead, this parameter will only be found in VoxelMesherBlocky, which is where it is actually used. GDScript can still access it by writing terrain.mesher.voxel_library instead of terrain.voxel_library.
• VoxelTerrain will have VoxelMesherBlocky as default mesher, since this is the one used the most with this node. If you want to change it, you'll have to explicitely assign a smooth mesher in the inspector.
• VoxelTerrain can no longer produce meshes from both SDF and TYPE channels at once. It has to be only one type of meshes. However if this is needed, it would be possible to implement a VoxelMesherMulti which would run multiple meshers on the same voxel data.

Usage notes

Note 1: you still need to use voxel data the mesher can handle. For example, a blocky mesher still won't be able to do anything with only SDF data.

Note 2: this change allows you to set a blocky mesher on VoxelTerrainLod. However, it is still not officially supported. So it's possible that this still won't work.

Note 3: this brings back access to the old DMC mesher which was preceding Transvoxel in this module. I still don't plan to maintain this one further though.

Implementation notes

This required to introduce a special pattern in the way meshers are implemented, to allow multithreading to remain safe and fast. Indeed, it's common for a mesher to be constantly churning data in all threads, so if the user changes a parameter at that moment, we don't want the interface to freeze. Every mesher divides its data in two sections:

• Parameters: this section is protected by an RWLock. When building a mesh, a read-only copy of all parameters is quickly made so they dont have to remain locked for the whole period of meshing.
• Cache: this section contains re-usable memory necessary for the meshing process. It's possible to always reallocate, but tests have shown that avoiding allocations speeds up the process a lot. Since this only contains temporary data, it doesn't have to be tied to every instance. So this was moved to a static thread_local, one per class.
• You can see an example of this here: https://github.com/Zylann/godot_voxel/blob/edfc96e4a5507997c4a90c4e27eb3734349eaadc/meshers/cubes/voxel_mesher_cubes.h#L68

Finally, after several changes are made, it's possible the terrain will contain a mishmash of meshes that used old and new parameters. Typically, the user may want to remesh the whole volume once they are done tweaking parameters.

[Zylann]

This got implemented in 791bdafff1e67f783cf8d2287a1ca4ccd9889e11 I'm leaving this open for a moment because there is no docs about it yet, since the docs need to be rewritten anyways

[slapin]

Yay! this one is really cool! Now I think running multiple meshers on same data is important when you implement mesher for terrain and supplemental mesher for grass without need to duplicate stuff and implementing single mesher for terrain + grass...

Thanks a lot for your hard work!

[ex5]

Could you share an example of how to add grass with a custom VoxelMesherTransvoxel or describe in some more details how to do this? Is it possible to do something like this with GD scripting alone, without creating a new mesher (e.g. with MultiMeshInstance by somehow getting access to coords of the surface voxels)? Or, alternatively, is is possible to somehow get access to their coordinates in a particle shader to generate grass and other surface clutter? (my c++ skill are not up to par, and it wasn't clear from the available docs what'd be the most appropriate way to implement this kind of stuff, so apologies for jumbled questions)

P.S. This module is totally awesome, thank you :heart:

[Zylann]

You might be able to put grass geometry from a mesher, but you currently have to modify that mesher to do so, and it has to be a vertex array, it can't be a node. Chaining two meshers would be a cleaner way, but it's not available yet.

There is however another feature I'm working on currently, which may help doing that: https://github.com/Zylann/godot_voxel/issues/223

[Zylann]

Closing as this was done a while ago