+ Topological,\n P::Vertex: Copy + Hash + Integer + Unsigned,\n Vec: IndexBuffer
,\n{\n type Facet = ();\n type Key = ();\n\n fn insert_facet(&mut self, keys: T, _: U) -> Result\n where\n Self::Facet: FromGeometry,\n T: AsRef<[P::Vertex]>,\n {\n let arity = keys.as_ref().len();\n P::try_from_slice(keys)\n .ok_or(BufferError::ArityConflict {\n expected: P::ARITY.into_interval().0,\n actual: arity,\n })\n .map(|polygon| self.indices.push(polygon))\n }\n}\n\nimpl MeshBuilder for BufferBuilder\nwhere\n Self: SurfaceBuilder,\n R: Grouping,\n VertexKey: Hash,\n Vec: IndexBuffer,\n{\n type Builder = Self;\n\n type Vertex = G;\n type Facet = ();\n\n fn surface_with(&mut self, f: F) -> Result\n where\n Self::Error: From,\n F: FnOnce(&mut Self::Builder) -> Result,\n {\n f(self).map_err(|error| error.into())\n }\n}\n\nimpl SurfaceBuilder for BufferBuilder\nwhere\n Self: FacetBuilder, Facet = ()>,\n Self::Error: From, // TODO: Why is this necessary?\n R: Grouping,\n VertexKey: Hash + NumCast,\n Vec: IndexBuffer,\n{\n type Builder = Self;\n type Key = VertexKey;\n\n type Vertex = G;\n type Facet = ();\n\n fn facets_with(&mut self, f: F) -> Result\n where\n Self::Error: From,\n F: FnOnce(&mut Self::Builder) -> Result,\n {\n f(self).map_err(|error| error.into())\n }\n\n fn insert_vertex(&mut self, data: T) -> Result\n where\n Self::Vertex: FromGeometry,\n {\n let key = as NumCast>::from(self.vertices.len())\n .ok_or(BufferError::IndexOverflow)?;\n self.vertices.push(data.into_geometry());\n Ok(key)\n }\n}\n\nimpl Transact<::Input> for BufferBuilder\nwhere\n R: Grouping,\n Vec: IndexBuffer,\n{\n type Commit = MeshBuffer;\n type Abort = ();\n type Error = BufferError;\n\n fn commit(self) -> Result {\n let BufferBuilder { indices, vertices } = self;\n Ok(MeshBuffer::from_raw_buffers_unchecked(indices, vertices))\n }\n\n fn abort(self) -> Self::Abort {}\n}\n"
},
{
"path": "plexus/src/buffer/mod.rs",
"content": "//! Linear representations of polygonal meshes.\n//!\n//! This module provides types and traits that describe polygonal meshes as\n//! buffers of vertex data and buffers of indices into that vertex data. These\n//! buffers are called the _vertex buffer_ and _index buffer_, respectively, and\n//! are typically used for indexed drawing. The [`MeshBuffer`] type unifies\n//! vertex and index buffers and maintains their consistency.\n//!\n//! Note that only _composite_ vertex buffers are supported, in which each\n//! element of a vertex buffer completely describes all attributes of a vertex.\n//! Plexus does not support _component_ buffers, in which each attribute of a\n//! vertex is stored in a dedicated buffer.\n//!\n//! Plexus refers to independent vertex and index buffers as _raw buffers_. For\n//! example, a [`Vec`] of index data is a raw buffer and can be modified without\n//! regard to consistency with any particular vertex buffer. The\n//! [`FromRawBuffers`] trait provides a way to construct mesh data structures\n//! from such raw buffers.\n//!\n//! Index buffers may contain either _flat_ or _structured_ data. See the\n//! [`index`] module for more about these buffers and how they are defined.\n//!\n//! # Examples\n//!\n//! Generating a flat [`MeshBuffer`] from a [$uv$-sphere][`UvSphere`]:\n//!\n//! ```rust\n//! # extern crate decorum;\n//! # extern crate nalgebra;\n//! # extern crate plexus;\n//! #\n//! use decorum::R32;\n//! use nalgebra::Point3;\n//! use plexus::buffer::MeshBuffer3;\n//! use plexus::prelude::*;\n//! use plexus::primitive::generate::Position;\n//! use plexus::primitive::sphere::UvSphere;\n//!\n//! let buffer: MeshBuffer3> = UvSphere::new(16, 16)\n//! .polygons::>>()\n//! .triangulate()\n//! .collect();\n//! let indices = buffer.as_index_slice();\n//! let positions = buffer.as_vertex_slice();\n//! ```\n//!\n//! Converting a [`MeshGraph`] to a structured [`MeshBuffer`]:\n//!\n//! ```rust\n//! # extern crate decorum;\n//! # extern crate nalgebra;\n//! # extern crate plexus;\n//! #\n//! use decorum::R64;\n//! use nalgebra::Point3;\n//! use plexus::buffer::MeshBufferN;\n//! use plexus::graph::MeshGraph;\n//! use plexus::prelude::*;\n//! use plexus::primitive::cube::Cube;\n//! use plexus::primitive::generate::Position;\n//!\n//! type E3 = Point3;\n//!\n//! let graph: MeshGraph = Cube::new().polygons::>().collect();\n//! let buffer: MeshBufferN = graph.to_mesh_by_vertex().unwrap();\n//! ```\n//!\n//! [`Vec`]: std::vec::Vec\n//! [`FromRawBuffers`]: crate::buffer::FromRawBuffers\n//! [`MeshBuffer`]: crate::buffer::MeshBuffer\n//! [`MeshGraph`]: crate::graph::MeshGraph\n//! [`index`]: crate::index\n//! [`UvSphere`]: crate::primitive::sphere::UvSphere\n\n// `MeshBuffer`s must convert and sum indices into their vertex data. Some of\n// these conversions may fail, but others are never expected to fail, because of\n// invariants enforced by `MeshBuffer`.\n//\n// Index types require `Unsigned` and `Vec` capacity is limited by word size\n// (the width of `usize`). An overflow cannot occur in some contexts, because a\n// consistent `MeshBuffer` cannot index into a `Vec` with an index larger than\n// its maximum addressable capacity (the maximum value that `usize` can\n// represent).\n\n// TODO: More consistently `expect` or `ok_or` index conversions and sums.\n\nmod builder;\n\nuse itertools::Itertools;\nuse num::{Integer, NumCast, Unsigned};\nuse std::fmt::Debug;\nuse std::hash::Hash;\nuse std::iter::FromIterator;\nuse std::vec;\nuse theon::adjunct::Map;\nuse thiserror::Error;\nuse typenum::{self, NonZero, Unsigned as _, U3, U4};\n\nuse crate::buffer::builder::BufferBuilder;\nuse crate::builder::{Buildable, MeshBuilder};\nuse crate::constant::{Constant, ToType, TypeOf};\nuse crate::encoding::{FaceDecoder, FromEncoding, VertexDecoder};\nuse crate::geometry::{FromGeometry, IntoGeometry};\nuse crate::index::{\n BufferOf, Flat, Flat3, Flat4, FromIndexer, Grouping, HashIndexer, IndexBuffer, IndexOf,\n IndexVertices, Indexer, Push,\n};\nuse crate::primitive::decompose::IntoVertices;\nuse crate::primitive::{\n BoundedPolygon, IntoIndexed, IntoPolygons, Polygonal, Tetragon, Topological, Trigon,\n UnboundedPolygon,\n};\nuse crate::{Arity, DynamicArity, MeshArity, Monomorphic, StaticArity, TryFromIterator};\n\n/// Errors concerning raw buffers and [`MeshBuffer`]s.\n///\n/// [`MeshBuffer`]: crate::buffer::MeshBuffer\n#[derive(Debug, Eq, Error, PartialEq)]\npub enum BufferError {\n /// An index into vertex data is out of bounds.\n ///\n /// This error occurs when an index read from an index buffer is out of\n /// bounds of the vertex buffer it indexes.\n #[error(\"index into vertex data out of bounds\")]\n IndexOutOfBounds,\n /// The computation of an index causes an overflow.\n ///\n /// This error occurs if the result of computing an index overflows the type\n /// used to represent indices. For example, if the elements of an index\n /// buffer are `u8`s and an operation results in indices greater than\n /// [`u8::MAX`], then this error will occur.\n ///\n /// [`u8::MAX`]: std::u8::MAX\n #[error(\"index overflow\")]\n IndexOverflow,\n #[error(\"index buffer conflicts with arity\")]\n /// The number of indices in a flat index buffer is incompatible with the\n /// arity of the buffer.\n ///\n /// This error may occur if a flat index buffer contains a number of indices\n /// that is indivisible by the arity of the topology it represents. For\n /// example, this may error occur if a triangular index buffer contains a\n /// number of indices that is not divisible by three.\n IndexUnaligned,\n /// The arity of a buffer or other data structure is not compatible with an\n /// operation.\n #[error(\"conflicting arity; expected {expected}, but got {actual}\")]\n ArityConflict {\n /// The expected arity.\n expected: usize,\n /// The incompatible arity that was encountered.\n actual: usize,\n },\n}\n\n/// Triangular [`MeshBuffer`].\n///\n/// The index buffer for this type contains [`Trigon`]s. For applications where\n/// a flat index buffer is necessary, consider [`IntoFlatIndex`] or the\n/// [`Flat3`] meta-grouping.\n///\n/// [`IntoFlatIndex`]: crate::buffer::IntoFlatIndex\n/// [`MeshBuffer`]: crate::buffer::MeshBuffer\n/// [`Flat3`]: crate::index::Flat3\n/// [`Trigon`]: crate::primitive::Trigon\npub type MeshBuffer3 = MeshBuffer, G>;\n\n/// Quadrilateral [`MeshBuffer`].\n///\n/// The index buffer for this type contains [`Tetragon`]s. For applications\n/// where a flat index buffer is necessary, consider [`IntoFlatIndex`] or the\n/// [`Flat4`] meta-grouping.\n///\n/// [`IntoFlatIndex`]: crate::buffer::IntoFlatIndex\n/// [`MeshBuffer`]: crate::buffer::MeshBuffer\n/// [`Flat4`]: crate::index::Flat4\n/// [`Tetragon`]: crate::primitive::Tetragon\npub type MeshBuffer4 = MeshBuffer, G>;\n\n/// [`MeshBuffer`] that supports polygons with arbitrary [arity][`Arity`].\n///\n/// [`MeshBuffer`]: crate::buffer::MeshBuffer\n/// [`Arity`]: crate::Arity\npub type MeshBufferN = MeshBuffer, G>;\n\n/// Conversion from raw buffers.\npub trait FromRawBuffers: Sized {\n type Error: Debug;\n\n /// Creates a type from raw buffers.\n ///\n /// # Errors\n ///\n /// Returns an error if the raw buffers are inconsistent or the implementor\n /// cannot be constructed from the buffers. The latter typically occurs if\n /// the given topology is unsupported.\n fn from_raw_buffers(indices: I, vertices: J) -> Result\n where\n I: IntoIterator- ,\n J: IntoIterator
- ;\n}\n\n/// Conversion from raw buffers that do not encode their arity.\npub trait FromRawBuffersWithArity: Sized {\n type Error: Debug;\n\n /// Creates a type from raw buffers with the given arity.\n ///\n /// # Errors\n ///\n /// Returns an error if the raw buffers are inconsistent, the raw buffers\n /// are incompatible with the given arity, or the implementor cannot be\n /// constructed from the buffers. The latter typically occurs if the given\n /// topology is unsupported.\n fn from_raw_buffers_with_arity(\n indices: I,\n vertices: J,\n arity: usize,\n ) -> Result\n where\n I: IntoIterator
- ,\n J: IntoIterator
- ;\n}\n\n// TODO: Provide a similar trait for index buffers instead. `MeshBuffer` could\n// use such a trait to provide this API.\npub trait IntoFlatIndex\nwhere\n Constant: ToType,\n TypeOf: NonZero,\n{\n type Item: Copy + Integer + Unsigned;\n\n fn into_flat_index(self) -> MeshBuffer, G>;\n}\n\n// TODO: Provide a similar trait for index buffers instead. `MeshBuffer` could\n// use such a trait to provide this API.\npub trait IntoStructuredIndex\nwhere\n ::Vertex: Copy + Integer + Unsigned,\n{\n type Item: Polygonal;\n\n fn into_structured_index(self) -> MeshBuffer;\n}\n\n/// Polygonal mesh composed of vertex and index buffers.\n///\n/// A `MeshBuffer` is a linear representation of a polygonal mesh that is\n/// composed of two separate but related linear buffers: an _index buffer_ and a\n/// _vertex buffer_. The index buffer contains ordered indices into the data in\n/// the vertex buffer and describes the topology of the mesh. The vertex buffer\n/// contains arbitrary data that describes each vertex.\n///\n/// `MeshBuffer` only explicitly respresents vertices via the vertex buffer and\n/// surfaces via the index buffer. There is no explicit representation of\n/// structures like edges and faces.\n///\n/// The `R` type parameter specifies the [`Grouping`] of the index buffer. See\n/// the [`index`] module documention for more information.\n///\n/// [`Grouping`]: crate::index::Grouping\n/// [`index`]: crate::index\n#[derive(Debug)]\npub struct MeshBuffer\nwhere\n R: Grouping,\n{\n indices: Vec,\n vertices: Vec,\n}\n\nimpl MeshBuffer\nwhere\n R: Grouping,\n Vec: IndexBuffer,\n{\n pub(in crate::buffer) fn from_raw_buffers_unchecked(\n indices: Vec,\n vertices: Vec,\n ) -> Self {\n MeshBuffer { indices, vertices }\n }\n\n /// Creates an empty `MeshBuffer`.\n ///\n /// # Examples\n ///\n /// ```rust\n /// use plexus::buffer::MeshBuffer;\n /// use plexus::index::Flat3;\n ///\n /// let buffer = MeshBuffer::, (f64, f64, f64)>::new();\n /// ```\n pub fn new() -> Self {\n Self::default()\n }\n}\n\nimpl MeshBuffer\nwhere\n R: Grouping,\n{\n /// Converts a `MeshBuffer` into its index and vertex buffers.\n pub fn into_raw_buffers(self) -> (Vec, Vec) {\n let MeshBuffer { indices, vertices } = self;\n (indices, vertices)\n }\n\n /// Maps over the vertex data in a `MeshBuffer`.\n ///\n /// # Examples\n ///\n /// Translating the position data in a buffer:\n ///\n /// ```rust\n /// # extern crate decorum;\n /// # extern crate nalgebra;\n /// # extern crate plexus;\n /// #\n /// use decorum::R64;\n /// use nalgebra::{Point3, Vector3};\n /// use plexus::buffer::MeshBuffer3;\n /// use plexus::prelude::*;\n /// use plexus::primitive::generate::Position;\n /// use plexus::primitive::sphere::UvSphere;\n ///\n /// let buffer: MeshBuffer3> = UvSphere::new(16, 8)\n /// .polygons::>>()\n /// .triangulate()\n /// .collect();\n /// // Translate the positions.\n /// let translation = Vector3::::x() * 2.0;\n /// let buffer = buffer.map_vertices(|position| position + translation);\n /// ```\n pub fn map_vertices(self, f: F) -> MeshBuffer\n where\n F: FnMut(G) -> H,\n {\n let (indices, vertices) = self.into_raw_buffers();\n MeshBuffer {\n indices,\n vertices: vertices.into_iter().map(f).collect::>(),\n }\n }\n\n /// Gets a slice over the index data.\n pub fn as_index_slice(&self) -> &[R::Group] {\n self.indices.as_slice()\n }\n\n /// Gets a slice over the vertex data.\n pub fn as_vertex_slice(&self) -> &[G] {\n self.vertices.as_slice()\n }\n}\n\n/// Exposes a [`MeshBuilder`] that can be used to construct a [`MeshBuffer`]\n/// incrementally from _surfaces_ and _facets_.\n///\n/// Note that the facet data for [`MeshBuffer`] is always the unit type `()`.\n///\n/// See the documentation for the [`builder`] module.\n///\n/// # Examples\n///\n/// Creating a [`MeshBuffer`] from a triangle:\n///\n/// ```rust\n/// # extern crate nalgebra;\n/// # extern crate plexus;\n/// #\n/// use nalgebra::Point2;\n/// use plexus::buffer::MeshBuffer3;\n/// use plexus::builder::Buildable;\n/// use plexus::prelude::*;\n///\n/// let mut builder = MeshBuffer3::>::builder();\n/// let buffer = builder\n/// .surface_with(|builder| {\n/// let a = builder.insert_vertex((0.0, 0.0))?;\n/// let b = builder.insert_vertex((1.0, 0.0))?;\n/// let c = builder.insert_vertex((0.0, 1.0))?;\n/// builder.facets_with(|builder| builder.insert_facet(&[a, b, c], ()))\n/// })\n/// .and_then(|_| builder.build())\n/// .unwrap();\n/// ```\n///\n/// [`MeshBuffer`]: crate::buffer::MeshBuffer\n/// [`MeshBuilder`]: crate::builder::MeshBuilder\n/// [`builder`]: crate::builder\nimpl Buildable for MeshBuffer\nwhere\n R: Grouping,\n Vec: IndexBuffer,\n BufferBuilder: MeshBuilder,\n{\n type Builder = BufferBuilder;\n type Error = BufferError;\n\n type Vertex = G;\n type Facet = ();\n\n fn builder() -> Self::Builder {\n BufferBuilder::default()\n }\n}\n\nimpl Default for MeshBuffer\nwhere\n R: Grouping,\n Vec: IndexBuffer,\n{\n fn default() -> Self {\n MeshBuffer {\n indices: Default::default(),\n vertices: Default::default(),\n }\n }\n}\n\nimpl DynamicArity for MeshBuffer, G>\nwhere\n Constant: ToType,\n TypeOf: NonZero,\n T: Copy + Integer + Unsigned,\n{\n type Dynamic = as StaticArity>::Static;\n\n fn arity(&self) -> Self::Dynamic {\n Flat::::ARITY\n }\n}\n\nimpl DynamicArity for MeshBuffer\nwhere\n P: Grouping + Monomorphic + Polygonal,\n P::Vertex: Copy + Integer + Unsigned,\n{\n type Dynamic =
::Static;\n\n fn arity(&self) -> Self::Dynamic {\n P::ARITY\n }\n}\n\nimpl DynamicArity for MeshBuffer, G>\nwhere\n N: Copy + Integer + Unsigned,\n{\n type Dynamic = MeshArity;\n\n fn arity(&self) -> Self::Dynamic {\n MeshArity::from_components::, _>(self.indices.iter())\n }\n}\n\nimpl DynamicArity for MeshBuffer, G>\nwhere\n N: Copy + Integer + Unsigned,\n{\n type Dynamic = MeshArity;\n\n fn arity(&self) -> Self::Dynamic {\n MeshArity::from_components::, _>(self.indices.iter())\n }\n}\n\nimpl Monomorphic for MeshBuffer where R: Grouping + Monomorphic {}\n\nimpl StaticArity for MeshBuffer\nwhere\n R: Grouping,\n{\n type Static = ::Static;\n\n const ARITY: Self::Static = R::ARITY;\n}\n\nimpl MeshBuffer, G>\nwhere\n Constant: ToType,\n TypeOf: NonZero,\n T: Copy + Integer + NumCast + Unsigned,\n{\n /// Appends the contents of a flat `MeshBuffer` into another `MeshBuffer`.\n /// The source buffer is drained.\n ///\n /// # Errors\n ///\n /// Returns an error if an index overflows.\n pub fn append(&mut self, buffer: &mut MeshBuffer) -> Result<(), BufferError>\n where\n G: FromGeometry,\n R: Grouping,\n R::Group: Into< as Grouping>::Group>,\n {\n let offset = T::from(self.vertices.len()).ok_or(BufferError::IndexOverflow)?;\n self.vertices.extend(\n buffer\n .vertices\n .drain(..)\n .map(|vertex| vertex.into_geometry()),\n );\n self.indices\n .extend(buffer.indices.drain(..).map(|index| index.into() + offset));\n Ok(())\n }\n}\n\nimpl MeshBuffer\nwhere\n P: Grouping + Polygonal,\n P::Vertex: Copy + Integer + NumCast + Unsigned,\n{\n /// Appends the contents of a structured `MeshBuffer` into another\n /// `MeshBuffer`. The source buffer is drained.\n ///\n /// # Errors\n ///\n /// Returns an error if an index overflows.\n pub fn append(&mut self, buffer: &mut MeshBuffer) -> Result<(), BufferError>\n where\n G: FromGeometry,\n R: Grouping,\n R::Group: Into<::Group>,\n
::Group:\n Map
![\"Plexus\"](\"https://raw.githubusercontent.com/olson-sean-k/plexus/master/doc/plexus.svg?sanitize=true\")
\n