Add Mesh::merge

[Jondolf]

Objective

It can sometimes be useful to combine several meshes into one. This allows constructing more complex meshes out of simple primitives without needing to use a 3D modeling program or entity hierarchies.

This could also be used internally to increase code reuse by using existing mesh generation logic for e.g. circles and using that in cylinder mesh generation logic to add the top and bottom of the cylinder.

Note: This is not implementing CSGs (Constructive Solid Geometry) or any boolean operations, as that is much more complex. This is simply adding the mesh data of another mesh to a mesh.

Solution

Add a merge method to Mesh. It appends the vertex attributes and indices of other to self, resulting in a Mesh that is the combination of the two.

For example, you could do this:

let mut cuboid = Mesh::from(shape::Box::default());
let mut cylinder = Mesh::from(shape::Cylinder::default());
let mut torus = Mesh::from(shape::Torus::default());

cuboid.merge(cylinder);
cuboid.merge(torus);

This would result in cuboid being a Mesh that also has the cylinder mesh and torus mesh. In this case, they would just be placed on top of each other, but by utilizing #11454 we can transform the cylinder and torus to get a result like this:

2024-01-21.14-31-30.mp4

This is just a single entity and a single mesh.

[Jondolf]

We might want to return some error instead? I'm not sure how common it would be to reach this panic since I'd expect e.g. position attributes to almost always be Float32x3

[SkiFire13]

From what I can see, if self and other's attributes don't match up:

• if self has an attribute but other doesn't, it is kept (note that this means future's self.count_vertices() will report the old vertices count);
• if other has an attribute but self doesn't, it is silently ignored.

Which could be kinda surprising. I don't see much better ways to handle this (other than error), in both cases it should be documented.

[Jondolf]

For now, I just added a short mention in the doc comment that attributes of other that don't exist on self will be ignored

[SkiFire13]

Note that (from count_vertices's documentation):

If the attributes have different vertex counts, the smallest is returned.

So it may be silently wrong (for your usecase) if that's the case. Might also be something to document.

[Jondolf]

I changed it to just use the vertex position attribute length for now, although I'm not entirely sure if that's fully correct either

[Adamkob12]

I think it would be better to panic if the attributes don't match (maybe only in debug mode?). Merging meshes seems very non-arbitrary, so catching the error will be easy.

Maybe a 'force_merge' method to ignore? Seems overkill though.

[alice-i-cecile]

IMO we should just return a Result and then let the user decide how to handle the errors.

[Shatur]

I applied this PR as a patch and tested in my game, works great!

I would add mention in the docs that if self have a missing attribute or indices, they will be ignored when merging.

Since it's a very small, yet useful PR, I added it to the milestone. Feel free to remove if you think it won't fit.

[Jondolf]

I would add mention in the docs that if self have a missing attribute or indices, they will be ignored when merging.

This is already kinda mentioned:

/// Note that attributes of `other` that don't exist on `self` will be ignored.

[Shatur]

Ah, sorry, I somehow missed it.

[alice-i-cecile]

Not a great milestone candidate at this stage (it's not vital), but I'm happy to merge it regardless.