lyon/lib.rs
1#![doc(html_logo_url = "https://nical.github.io/lyon-doc/lyon-logo.svg")]
2#![deny(bare_trait_objects)]
3
4//! GPU-based 2D graphics rendering tools in Rust using path tessellation.
5//!
6//! 
7//!
8//! [](https://crates.io/crates/lyon)
9//! [](https://github.com/nical/lyon/actions)
10//!
11//! # Crates
12//!
13//! This meta-crate (`lyon`) reexports the following sub-crates for convenience:
14//!
15//! * [](https://crates.io/crates/lyon_tessellation)
16//! [](https://docs.rs/lyon_tessellation) -
17//! **lyon_tessellation** - Path tessellation routines.
18//! * [](https://crates.io/crates/lyon_path)
19//! [](https://docs.rs/lyon_path) -
20//! **lyon_path** - Tools to build and iterate over paths.
21//! * [](https://crates.io/crates/lyon_algorithms)
22//! [](https://docs.rs/lyon_algorithms) -
23//! **lyon_algorithms** - Various 2d path related algorithms.
24//! * [](https://crates.io/crates/lyon_geom)
25//! [](https://docs.rs/lyon_geom) -
26//! **lyon_geom** - 2d utilities for cubic and quadratic bézier curves, arcs and more.
27//! * [](https://crates.io/crates/lyon_extra)
28//! [](https://docs.rs/lyon_extra) -
29//! **lyon_extra** - Additional testing and debugging tools.
30//!
31//! Each `lyon_<name>` crate is reexported as a `<name>` module in `lyon`. For example:
32//!
33//! ```ignore
34//! extern crate lyon_tessellation;
35//! use lyon_tessellation::FillTessellator;
36//! ```
37//!
38//! Is equivalent to:
39//!
40//! ```ignore
41//! extern crate lyon;
42//! use lyon::tessellation::FillTessellator;
43//! ```
44//!
45//! # Feature flags
46//!
47//! serialization using serde can be enabled on each crate using the
48//! `serialization` feature flag (disabled by default).
49//!
50//! When using the main crate `lyon`, `lyon_extra` dependencies is disabled by default.
51//! It can be added with the feature flags `extra`.
52//!
53//! # Additional documentation and links
54//!
55//! * [wgpu example](https://github.com/nical/lyon/tree/main/examples/wgpu).
56//! * [wgpu_svg example](https://github.com/nical/lyon/tree/main/examples/wgpu_svg) similar to the first example,
57//! can render a very small subset of SVG.
58//! * There is some useful documentation on the project's [wiki](https://github.com/nical/lyon/wiki).
59//! * The source code is available on the project's [git repository](https://github.com/nical/lyon).
60//! * Interested in contributing? Pull requests are welcome. If you would like to help but don't know
61//! what to do specifically, have a look at the [github issues](https://github.com/nical/lyon/issues),
62//! some of which are tagged as [easy](https://github.com/nical/lyon/issues?q=is%3Aissue+is%3Aopen+label%3Aeasy).
63//!
64//! # Examples
65//!
66//! ## Tessellating a rounded rectangle
67//!
68//! The `lyon_tessellation` crate provides a collection of tessellation routines
69//! for common shapes such as rectangles and circles. Let's have a look at how
70//! to obtain the fill tessellation a rectangle with rounded corners:
71//!
72//! ```
73//! use lyon::math::{Box2D, Point, point};
74//! use lyon::path::{Winding, builder::BorderRadii};
75//! use lyon::tessellation::{FillTessellator, FillOptions, VertexBuffers};
76//! use lyon::tessellation::geometry_builder::simple_builder;
77//!
78//! fn main() {
79//! let mut geometry: VertexBuffers<Point, u16> = VertexBuffers::new();
80//! let mut geometry_builder = simple_builder(&mut geometry);
81//! let options = FillOptions::tolerance(0.1);
82//! let mut tessellator = FillTessellator::new();
83//!
84//! let mut builder = tessellator.builder(
85//! &options,
86//! &mut geometry_builder,
87//! );
88//!
89//! builder.add_rounded_rectangle(
90//! &Box2D { min: point(0.0, 0.0), max: point(100.0, 50.0) },
91//! &BorderRadii {
92//! top_left: 10.0,
93//! top_right: 5.0,
94//! bottom_left: 20.0,
95//! bottom_right: 25.0,
96//! },
97//! Winding::Positive,
98//! );
99//!
100//! builder.build();
101//!
102//! // The tessellated geometry is ready to be uploaded to the GPU.
103//! println!(" -- {} vertices {} indices",
104//! geometry.vertices.len(),
105//! geometry.indices.len()
106//! );
107//! }
108//!
109//! ```
110//!
111//! ## Building and tessellating an arbitrary path
112//!
113//! ```
114//! extern crate lyon;
115//! use lyon::math::{point, Point};
116//! use lyon::path::Path;
117//! use lyon::path::builder::*;
118//! use lyon::tessellation::*;
119//!
120//! fn main() {
121//! // Build a Path.
122//! let mut builder = Path::builder();
123//! builder.begin(point(0.0, 0.0));
124//! builder.line_to(point(1.0, 0.0));
125//! builder.quadratic_bezier_to(point(2.0, 0.0), point(2.0, 1.0));
126//! builder.cubic_bezier_to(point(1.0, 1.0), point(0.0, 1.0), point(0.0, 0.0));
127//! builder.close();
128//! let path = builder.build();
129//!
130//! // Let's use our own custom vertex type instead of the default one.
131//! #[derive(Copy, Clone, Debug)]
132//! struct MyVertex { position: [f32; 2] };
133//!
134//! // Will contain the result of the tessellation.
135//! let mut geometry: VertexBuffers<MyVertex, u16> = VertexBuffers::new();
136//!
137//! let mut tessellator = FillTessellator::new();
138//!
139//! {
140//! // Compute the tessellation.
141//! tessellator.tessellate_path(
142//! &path,
143//! &FillOptions::default(),
144//! &mut BuffersBuilder::new(&mut geometry, |vertex: FillVertex| {
145//! MyVertex {
146//! position: vertex.position().to_array(),
147//! }
148//! }),
149//! ).unwrap();
150//! }
151//!
152//! // The tessellated geometry is ready to be uploaded to the GPU.
153//! println!(" -- {} vertices {} indices",
154//! geometry.vertices.len(),
155//! geometry.indices.len()
156//! );
157//! }
158//! ```
159//!
160//! ## What is the tolerance variable in these examples?
161//!
162//! The tessellator operates on flattened paths (that only contains line segments)
163//! so we have to approximate the curves segments with sequences of line segments.
164//! To do so we pick a tolerance threshold which is the maximum distance allowed
165//! between the curve and its approximation.
166//! The documentation of the [lyon_geom](https://docs.rs/lyon_geom) crate provides
167//! more detailed explanations about this tolerance parameter.
168//!
169//! ## Rendering the tessellated geometry
170//!
171//! Lyon does not provide with any GPU abstraction or rendering backend (for now).
172//! It is up to the user of this crate to decide whether to use OpenGL, vulkan, gfx-rs,
173//! wgpu, glium, or any low level graphics API and how to render it.
174//! The [wgpu example](https://github.com/nical/lyon/tree/main/examples/wgpu)
175//! can be used to get an idea of how to render the geometry (in this case
176//! using wgpu).
177
178pub extern crate lyon_algorithms;
179#[cfg(feature = "extra")]
180pub extern crate lyon_extra;
181pub extern crate lyon_tessellation;
182
183pub use lyon_algorithms as algorithms;
184#[cfg(feature = "extra")]
185pub use lyon_extra as extra;
186pub use lyon_tessellation as tessellation;
187pub use tessellation::geom;
188pub use tessellation::path;
189
190pub use path::math;