[][src]Crate lyon_tessellation

Tessellation of 2D fill and stroke operations.

This crate is reexported in lyon.

Overview

The most interesting types and traits of this crate are:

  • FillTessellator - Tessellator for complex path fill operations.
  • StrokeTessellator - Tessellator for complex path stroke operations.
  • GeometryBuilder - (See the documentation of the geometry_builder module) which the above two are built on. This trait provides an interface for types that help with building and assembling the vertices and triangles that form the tessellation, usually in the form of arbitrary vertex and index buffers.
  • The various specialized tessellators in the basic_shapes modules.

The tessellation pipeline

FillTessellator GeometryBuilder output VertexConstructor Iterator<PathEvent> builder.add_vertex(FillVertex) -> VertexId;builder.add_triangle(VertexId, VertexId, VertexId); FillVertex -> CustomVertex MoveTo(Point)LineTo(Point)Close

The figure above shows a simplified summary of each step of the fill tessellation pipeline.

The input: iterators

The path tessellators are not tied to a particular data structure. Instead they consume iterators of flattened path events. A Path struct in the crate lyon_path is provided for convenience (but is optional).

The output: geometry builders

The tessellators are parametrized over a type implementing the GeometryBuilder trait. This trait provides some simple methods to add vertices and triangles, without enforcing any particular representation for the resulting geometry. This is important because each application will usually want to work with its own vertex type tailored a certain rendering model.

Applications can implement the GeometryBuilder<Point> trait in order to generate vertex buffers and index buffers with custom vertex types.

The structs VertexBuffers and geometry_buider::BuffersBuilder are provided for convenience. VertexBuffers<T> is contains a Vec<T> for the vertices and a Vec<u16> for the indices.

BuffersBuilder is generic over a VertexConstructor<InputVertex, OutputVertex> trait which creates the application's output vertices from the tessellator input vertices (either FillVertex or StrokeVertex).

Rendering the tessellated geometry

The tessellators produce geometry in the form of vertex and index buffers which are expected to be rendered using the equivalent of OpenGL's glDrawElements with mode GL_TRIANGLES available under various names in the different graphics APIs. There is an example showing how it can be done with wgpu.

Flattening and tolerance

Most tessellators in this crate currently operate on flattened paths (paths or shapes represented by sequences of line segments). when paths contain bézier curves or arcs, the latter need to be approximated with sequences of line segments. This approximation depends on a tolerance parameter which represents the maximum distance between a curve and its flattened approximation.

More explanation about flattening and tolerance in the lyon_geom crate.

Examples

Re-exports

pub use lyon_path as path;
pub use crate::path::geom;

Modules

basic_shapes

Tessellation routines for simple shapes.

geometry_builder

Tools to help with generating vertex and index buffers.

math

Basic types that are used everywhere. Most other lyon crates reexport them.

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.

FillAttributes

Extra vertex information from the FillTessellator, accessible when building vertices.

FillOptions

Parameters for the fill tessellator.

FillTessellator

A Context object that can tessellate fill operations for complex paths.

StrokeAttributes

Extra vertex information from the StrokeTessellator accessible when building vertices.

StrokeBuilder

A builder that tessellates a stroke directly without allocating any intermediate data structure.

StrokeOptions

Parameters for the tessellator.

StrokeTessellator

A Context object that can tessellate stroke operations for complex paths.

VertexBuffers

Structure that holds the vertex and index data.

VertexId

A virtual vertex offset in a geometry.

VertexSourceIterator

An iterator over the sources of a given vertex.

Enums

FillRule

The fill rule defines how to determine what is inside and what is outside of the shape.

GeometryBuilderError

An error that can happen while generating geometry.

InternalError

Describes an unexpected error happening during tessellation.

LineCap

Line cap as defined by the SVG specification.

LineJoin

Line join as defined by the SVG specification.

Order

Before or After. Used to describe position relative to a join.

Orientation

Vertical or Horizontal.

Side

Left or right.

TessellationError

The fill tessellator's error enumeration.

VertexSource

Where a vertex produced by a tessellator comes from in the original path.

Traits

BasicGeometryBuilder

A Geometry builder to interface with some of the basic tessellators.

BasicVertexConstructor

A trait specifying how to create vertex values.

FillGeometryBuilder

A Geometry builder to interface with the FillTessellator.

FillVertexConstructor

A trait specifying how to create vertex values.

GeometryBuilder

An interface separating tessellators and other geometry generation algorithms from the actual vertex construction.

GeometryReceiver

An interface with similar goals to GeometryBuilder for algorithms that pre-build the vertex and index buffers.

StrokeGeometryBuilder

A Geometry builder to interface with the StrokeTessellator.

StrokeVertexConstructor

A trait specifying how to create vertex values.

Type Definitions

TessellationResult

The fill tessellator's result type.