gfx_draping/
lib.rs

1//! A library for rendering polygons onto 3d terrain.
2//!
3//! This crate uses a screen-space algorithm; it uses your GPU's stencil buffer to detect pixels
4//! where the polygon lies on terrain unoccluded. In addition, this crate is meant for drawing
5//! multiple polygons at once. If you have a collection of polygons which may need to be drawn
6//! simultaneously, put them all in a `PolygonBuffer`. You can choose which of those polygons to
7//! render by combining their respective `PolygonBufferIndices`.
8//!
9//! Typically, usage of this crate will look something like:
10//!
11//! ```rust,compile_fail
12//! extern crate geo;
13//! extern crate gfx_draping;
14//!
15//! use gfx_draping::{DrapingRenderer, PolygonBuffer, PolygonBufferIndices};
16//!
17//! // Let's say you're using `geo` (a Rust GIS crate) to construct polygons.
18//! let polygons: Vec<geo::Polygon> = a_vec_of_polygons();
19//!
20//! // Prepare assets for rendering.
21//! let mut buffer = PolygonBuffer::new();
22//! let mut indices = PolygonBufferIndices::new();
23//! for polygon in polygons {
24//!     indices.extend(buffer.add(polygon.into()));
25//! }
26//!
27//! let renderer = DrapingRenderer::new();
28//! let renderable_buffer = buffer.as_renderable(&mut window.factory);
29//! let renderable_indices = indices.as_renderable(&mut window.factory);
30//!
31//! while your_event_loop() {
32//!     // Render your 3d terrain
33//!     render_terrain();
34//!
35//!     // At this point, your depth stencil should be the result of drawing the terrain. Your
36//!     // stencil buffer should be all zeroes.
37//!     renderer.render(
38//!         window.encoder,
39//!         window.output_color,
40//!         window.output_stencil,
41//!         // See docs for `DrapingRenderer::render` for a caveat about what `mvp` should be.
42//!         your_scaled_mvp(),
43//!         // R - G - B - A
44//!         [1.0, 0.0, 1.0, 0.5],
45//!         &renderable_buffer,
46//!         &renderable_indices,
47//!     );
48//!
49//!     // Now you can clear / clean-up as you do usually.
50//! }
51//! ```
52
53extern crate geo;
54#[macro_use]
55extern crate gfx;
56
57mod polygon;
58mod render;
59mod vertex;
60
61pub use polygon::{Polygon, PolygonBuffer, PolygonBufferIndices};
62pub use render::{DrapingRenderer, RenderablePolygonBuffer, RenderablePolygonIndices};
gfx_draping/lib.rs

gfx_draping/
lib.rs
