gfx-rs / genmesh

A library of mesh generation utilities.

Genmesh

genmesh is a library for building vertex pipelines. The goal is help facilitate polygon assembly. This is done by building on top of the of the Iterator trait. A pipeline stage is a lazy iterator the consumes the input, and produces a new polygon based on the stage.

This also provides some generators for creating primitives at runtime.

Currently supported stages

• vertex maps a function to each vertex in a polygon
• triangulate triangles Quads to Triangles
• vertices turns a poly pipeline into a vertices pipeline

Primitive generators

• Cone
• Cube
• Cylinder
• Plane
• SphereUV
• Torus

Vertex attributes

• pos: position
• normal: normal

Utility

• LruIndexer translate a vertex into a index, emitting a new vertex if the current vertex is not in the Lru cache.
• Neighbors work with mesh as a whole by querying normals and neighbors on either vertex or polygon levels.

Primitives

• Triangle
• Quad
• Polygon an enum of both Triangle and Quad

Example

    let vertex_data: Vec<MyVertex> = Cube::new()
        .vertex(|v| MyVertex::new(v.pos, [0., 0.]))
        .map(|Quad{x: v0, y: v1, z: v2, w: v3}| {
            Quad::new(MyVertex::new(v0.a_Pos, [0., 0.]),
                      MyVertex::new(v1.a_Pos, [1., 0.]),
                      MyVertex::new(v2.a_Pos, [1., 1.]),
                      MyVertex::new(v3.a_Pos, [0., 1.]))
        })
        .triangulate()
        .vertices()
        .collect();

Here Cube generates six faces, one per side this is presented as a Quad<Vertex3<f32>>.

vertex maps a function to each vertex in each face, in this case we want to convert from genmes's internal vertex format to our own. We now have a Quad<MyVertex>>.

We can do a polygon level transform and modify the polygon as a whole. In the example we add a valid texture coordinate to each face. Since genmesh is just an extension of iterators we can do a polygon level transform using just map.

triangulate will convert the Quad<MyVertex> to a Triangle<MyVertex>>. This will produce two polygons and six vertices. Some of the verticies are cloned in order to complete this operation.

verticies now unwraps each triangle and returns the vertices in-order. This will obviously produce 3 results for each polygon.

collect is a standard Iterator operation.

genmesh's Issues

Common vertex format

Considering #25 and #26 to generate more vertex data, we may end up with too much (partially redundant) code if we want the generators to support various combinations like vertex + normal, vertex, vertex + tex-coords.

We might want to consider a single vertex format to be used by all generators, potentially also covering #27. The user should still be able to map the vertex to its own format and drop some of the generated data.

The main problem I see here is the complexity of shared vertex generation. For example, a cube would no longer be able to share any vertices, since each face has a different normal (unless we smooth normals over the cube, which doesn't make much sense).

Generate tangents

As part of applying normal maps to generated meshes, it would be useful to have genmesh generate tangent vectors in addition to normal vectors for each vertex.

Implement Torus

It's a nice object that can occlude itself and looks beautiful when rotating.

Add scaling options

The primitives right now just produce a primitive that is close to a unit vector. The original idea was that people would scale the primitives using the .vertex() trait. There are a few cases where I don't think this is satisfactory. The cone primitive for example has different normals based on these values, so for the sake of our uses we should add them.

Generate texture coordinates

updated rust nightly does not like old/explicit closure syntax

issue with obsolete syntax

$ cargo build
   Compiling genmesh v0.0.12
/home/chris/.cargo/registry/src/github.com-1ecc6299db9ec823/genmesh-0.0.12/src/sphere.rs:108:18: 108:22 error: obsolete syntax: `:`, `&mut:`, or `&:`
/home/chris/.cargo/registry/src/github.com-1ecc6299db9ec823/genmesh-0.0.12/src/sphere.rs:108         let f = |&: u: usize, v: usize| {
                                                                                                              ^~~~
note: rely on inference instead
error: aborting due to previous error
Build failed, waiting for other jobs to finish...
Could not compile `genmesh`.

Update crates.io version

Could you please update the crates.io version of this crate? Looks like it hasn't been updated in 3 years.

Use `nalgebra` instead of `cgmath`

Heya, since most other gamedev related libraries are on nalgebra, I'd like to update this library to use that as well.

Another reason is that the current version on crates.io (0.6.2) depends on cgmath 0.16.1, which depends on rand v0.4.6. By swapping to nalgebra, at least for the amethyst game engine, we get to remove at least both the cgmath and rand crate compilations (there may be others, but I haven't done a thorough check).

I'm thinking in the future, if ultraviolet becomes the standard, we could put the relevant math library choice behind feature flags, though that's something in the future future.

Is it possible to generate indices and vertices separately?

Instead of generating duplicate vertices, one could generate indices and share vertices.

Investigate ncollide_procedural

The crate name is off, but essentially this is the direct alternative to genmesh:
http://ncollide.org/rustdoc/ncollide_procedural/

It's used in kiss3d. Would be interesting to look inside and see what we can learn.

Automated testing

The library needs some sort of testing. For example, we could compare the output of Iterator implementation for each generator versus SharedVertex + IndexedPolygon data.

n-gons (w. holes) support?

Are you planning to add support for geometry used outside a realtime context?

Vertices does not implement `ExactSizeIterator`

Most if not all of the generators in genmesh emit a set number of vertices on .vertices. Yet, this iterator does not implement ExactSizeIterator.

This can be unergonomic when working with crates that expect an iterator of a fixed length. For example, when you create a buffer in Vulkano and you want to fill it with values, it expects an ExactSizeIterator.

How to fix this

Vertices internally uses EmitVertices. The issue with this is that EmitVertices is not an Iterator, and thus the amount of vertices it will emit is not set.

The best way to fix this is likely to implement Vertices directly on every generator, and leave EmitVertices around for backwards compatibility.

Generate unit cubes.

Cube generates a cube centered at the origin with sides of length two. Just as Sphere generates a unit sphere, maybe Cube should generate a unit cube with sides of length one?

Add docs

The library is almost without docs.

Move to fixed sized arrays.

We have used tuples because of the history problems with fixed sized arrays in rust. These days fixed sized arrays are much easier to work with, so we should look at migrating some of the types to use arrays.

See Quad and Triangle.

[META] Common Meshes

List of Meshes genmesh should be able to generate:

• Plane
• Cube
• SphereUV
• Sphere Icosahedron
• Torus #23
• Cone #48
• Cylinder #40
• Rust Logo

Hard normals option

I need the smoothing to be configurable by a flag. Currently, normals of cylinder and sphere are smoothed.

Generate normals

Categories:

• As part of the mesh generators (sphere, plane, cube)
• Computed based on the vertices supplied (flat shading)
• Averaged based on the faces shared supplied

Cube SharedVertex/IndexedPolygon creates 24 vertices

Shouldn't it create only 8 vertices?

Consider moving under Gfx?

The recent rust breakage showed how genmesh could be a weak link of the ecosystem. gfx-rs breaks on it, glium does as well. We'd have to temporarily avoid using genmesh for the time of your absence. Perhaps, share some push access, or even move the repo under Gfx or PistonDevelopers?
Personally, I'd like to see gfx-rs/mesh_gen ;)