Module lyon_tessellation::geometry_builder [−] [src]

Geometry builder

Tools to help with generating geometry to send to the GPU.

Overview

While it would be possible for the tessellation algorithms to manually generate vertex and index buffers with a certain layout, it would mean that most code using the tessellators would need to copy and convert all generated vertices in order to have their own vertex layout, or even several vertex layouts, which is a very common use-case.

In order to provide flexibility with the generation of geometry, this module provides with the GeometryBuilder and its extension the BezierGeometryBuilder trait. The former exposes the methods to facilitate adding vertices and triangles. The latter adds a method to specifically handle quadratic bezier curves. Quadratic bezier curves have interesting properties that make them a lot easier to render than most types of curves and we want to have the option to handle them separately in the renderer.

See the Rendering curves section in the project's wiki for more details about the advantages of handling quadratic bezier curves separately in the tessellator and the renderer.

This modules provides with a basic implementation of these traits through the following types:

The struct VertexBuffers is a simple pair of vectors of u16 indices and T (generic parameter) vertices.
The struct BuffersBuilder which implements BezierGeometryBuilder and writes into a VertexBuffers.
The trait VertexConstructor used by BuffersBuilder in order to generate any vertex type. In the example below, a struct WithColor implements the VertexConstructor trait in order to create vertices composed of a 2d position and a color value from an input 2d position. This separates the construction of vertex values from the assembly of the vertex buffers. Another, simpler example of vertex constructor is the Identity constructor which just returns its input, untransformed.

Geometry builders are a practical way to add one last step to the tessellation pipeline, such as applying a transform or clipping the geometry.

While this is module designed to facilitate the generation of vertex buffers and index buffers, nothing prevents a given GeometryBuilder implementation to only generate a vertex buffer without indices, or write into a completely different format. These builder traits are at the end of the tessellation pipelines and are meant for users of this crate to be able to adapt the output of the tessellators to their own needs.

Examples

This example sets up a simple function that generates the vertices and indices for colored quads, using some of the tools provided in this crate. Note that for simplicity in this example we use [f32; 2] to represent positions, while most of the more advanced tessellator code use euclid points.

use lyon_tessellation::geometry_builder::*;

// Define our vertex type.
#[derive(Copy, Clone, PartialEq, Debug)]
struct Vertex2d {
  position: [f32; 2],
  color: [f32; 4],
}

// The vertex constructor. This is the object that will be used to create vertices from
// a position provided by the geometry builder. In this specific case the vertex constructor
// stores a constant color which will be applied to all vertices.
struct WithColor([f32; 4]);

// Implement the VertexConstructor trait accordingly. WithColor takes a [f32; 2] position as
// input and returns a Vertex2d.
impl VertexConstructor<[f32; 2], Vertex2d> for WithColor {
    fn new_vertex(&mut self, pos: [f32; 2]) -> Vertex2d {
        Vertex2d {
            position: pos,
            color: self.0
        }
    }
}

// A typical "algortihm" that generates some geometry, in this case a simple axis-aligned quad.
// Returns a structure containing the number of vertices and number of indices allocated during
// the execution of this method.
fn make_quad<Builder: GeometryBuilder<[f32; 2]>>(
    top_left: [f32; 2],
    size: [f32; 2],
    builder: &mut Builder
) -> Count {
    builder.begin_geometry();
    // Create the vertices...
    let a = builder.add_vertex(top_left);
    let b = builder.add_vertex([top_left[0] + size[0], top_left[1]]);
    let c = builder.add_vertex([top_left[0] + size[0], top_left[1] + size[1]]);
    let d = builder.add_vertex([top_left[0], top_left[1] + size[1]]);
    // ...and create triangle form these points. a, b, c, and d are relative offsets in the
    // vertex buffer.
    builder.add_triangle(a, b, c);
    builder.add_triangle(a, c, d);
    return builder.end_geometry();
}

// Allocate a vertex buffer and an index buffer. This is typically what we would want to
// send to the GPU for rendering.
let mut buffers: VertexBuffers<Vertex2d> = VertexBuffers::new();

// Finally, generate the geometry using the function we created above to make a red square...
let red = [1.0, 0.0, 0.0, 1.0];
make_quad([0.0, 0.0], [1.0, 1.0], &mut BuffersBuilder::new(&mut buffers, WithColor(red)));

// ...an a green one.
let green = [0.0, 1.0, 0.0, 1.0];
make_quad([2.0, 0.0], [1.0, 1.0], &mut BuffersBuilder::new(&mut buffers, WithColor(green)));

println!("The generated vertices are: {:?}.", &buffers.vertices[..]);
println!("The generated indices are: {:?}.", &buffers.indices[..]);

Structs

BuffersBuilder	A temporary view on a VertexBuffers object which facilitate the population of vertex and index data.
Count	Number of vertices and indices added during the tessellation.
Identity	A dummy vertex constructor that just forwards its inputs.
VertexBuffers	Structure that holds the vertex and index data.
VertexId	A virtual vertex offset in a geometry.

Traits

BezierGeometryBuilder	An extension to GeometryBuilder that can handle quadratic bezier segments.
GeometryBuilder	An interface separating tessellators and other geometry generation algorithms from the actual vertex construction.
VertexConstructor	A trait specifying how to create vertex values.

Functions

simple_builder	Creates a SimpleBuffersBuilder.
vertex_builder	Creates a BuffersBuilder.

Type Definitions

Index
SimpleBuffersBuilder	A BuffersBuilder that takes the actual vertex type as input.