Meshes from primitives

[Jondolf]

What problem does this solve or what need does it fill?

Meshes can currently be created from the shapes in bevy_render::mesh::shape. These are shapes that are specific to rendering and contain information about things like how a sphere should be subdivided.

Now that primitive shapes have been added in #10466, it should be possible to have a more unified shape API for meshes, gizmos, colliders and so on. It should be possible to create meshes from the primitive shapes in bevy_math::primitives.

What solution would you like?

Implement mesh generation for primitive shapes, and maybe remove duplicate shapes from bevy_render::mesh::shape.

For some shapes, it's as straightforward as this:

let cube = Mesh::from(Cuboid::new(1.0, 1.0, 1.0)); // or just call .mesh()?

However, for many other shapes it's not as straightforward. For example, the current Capsule shape used for rendering has properties such as rings, latitudes, longitudes and uv_profile. This would not work with a simple impl From<Capsule> for Mesh.

Some options include:

1. Keep separate types for rendering specifics, and create meshes from them like Mesh::from(UvSphere::new(Sphere::new(1.0), longitudes, latitudes)).
   • Similar to what we have now, pretty explicit and also familiar
   • Quite verbose and repeats Sphere
   • Annoying to have separate rendering shapes when one of the main ideas of shape primitives is to unify things
   • Rendering configuration is stored in a separate struct (good or bad depending on the use case)
2. Have methods like mesh that are different for each primitive, like Sphere::new(1.0).uv_mesh(longitudes, latitudes)
   • Can be nice and concise
   • Shape primitives can be used directly instead of intermediary types
   • No shared trait for all types of meshes because of different requirements
   • No information about the rendering configuration is stored (good or bad depending on the use case)
3. Hard-code a global default configuration for mesh quality / subdivision count
   • Very easy API, just Mesh::from(Sphere::new(1.0))
   • Very inflexible; there would still need to be a way to specify it manually as needed
   • Shapes don't always have a single subdivision property, but can have multiple like longitudes/latitudes

We don't want 3 by itself, but I'm personally leaning on a combination of 2 and 3. We could have hard-coded default implementations for From and maybe a Meshable trait that has a mesh method with some default mesh configuration implemented, as suggested by the original RFC, but also give primitives custom mesh construction methods like .uv_mesh(...) where necessary. This would provide a nice API with good defaults, without having many different shape types for the same core shapes (like spheres), while still allowing full control for subdivisions and other configuration as needed.

Ideas and suggestions are welcome!

[Kanabenki]

2. Have methods like mesh that are different for each primitive, like Sphere::new(1.0).uv_mesh(longitudes, latitudes)

Wouldn't that make bevy_math depends on bevy_render for the Mesh definition, which I guess isn't desirable ? (unless this is done through extension traits in bevy_render)

[Jondolf]

Yep it'd be traits in bevy_render. Same concept applies to using primitives for gizmos, colliders and so on. bevy_math should only contain the primitives themselves, and the various things using them should be in their respective crates.

[IQuick143]

Could we simplify the syntax of option 1. by having constructor methods on the primite shapes, which would return the desired rendering shape, ie:

// instead of
let mesh: Mesh = UvSphere::new(Sphere::new(radius), longitudes, latitudes).into();
let mesh: Mesh = IcoSphere::new(Sphere::new(radius), subdivisions).into();
// one would use
let mesh: Mesh = Sphere::new(radius).uv(longitudes, latitudes).into();
let mesh: Mesh = Sphere::new(radius).ico(subdivisions).into();

This would simplify the syntax for people who ultimately aim for a mesh (like option 2.), but it would still expose the UvSphere and similar types, if they were needed (are they needed?).

[Jondolf]

I'm attempting to implement mesh construction for primitives now, and I think I have found quite a nice approach that provides a unified API with both ergonomics and configurability. It's fairly similar to the suggestion by @IQuick143 above.

We can have a single Meshable trait like the original RFC suggests, but have the mesh output be an associated type:

pub trait Meshable {
    type Output;

    fn mesh(&self) -> Self::Output;
}

This way, something like Cuboid::mesh can directly return a mesh:

impl Meshable for Cuboid {
    type Output = Mesh;

    fn mesh(&self) -> Mesh {
        // ...
    }
}

But for e.g. a sphere, we can instead return a SphereBuilder:

pub enum SphereKind {
    Ico {
        subdivisions: usize,
    },
    Uv {
        sectors: usize,
        stacks: usize,
    },
}

pub struct SphereBuilder {
    pub sphere: Sphere,
    pub kind: SphereKind,
}

impl SphereBuilder {
    pub fn build(&self) -> Mesh { ... } // uses default configuration
    pub fn ico(&self, subdivisions: usize) -> Result<Mesh, IcosphereError> { ... }
    pub fn uv(&self, sectors: usize, stacks: usize) -> Mesh { ... }
}

impl Meshable for Sphere {
    type Output = SphereBuilder;

    fn mesh(&self) -> Self::Output {
        SphereBuilder {
            sphere: *self,
            kind: SphereKind::Ico { subdivisions: 5 }, // default config
        }
    }
}

If desired, you could even impl From<MyShape> for Mesh for the primitives and their builders so that you can still do Mesh::from(shape) or shape.into().

Using it would look like this:

let cube = Cuboid::new(1.0, 1.0, 1.0).mesh(); // or .into() if we implement that
let icosphere = Sphere { radius: 0.5 }.mesh().ico(10);
let uv_sphere = Sphere { radius: 0.5 }.mesh().uv(6, 8);
let circle = Circle { radius: 50.0 }.mesh().vertices(32);
let flipped_rectangle = Rectangle::new(100.0, 100.0).mesh().flipped();

I still need to implement this for some more shapes, but I should have a PR ready relatively soon.

[james7132]

This seems to be implemented as of 0.13. If there's still missing primitives, we can handle them in new PRs or issues, but this overall looks resolved.