diff --git a/Library/BMesh.cs b/Library/BMesh.cs index 3b296b4..b621c87 100644 --- a/Library/BMesh.cs +++ b/Library/BMesh.cs @@ -92,29 +92,56 @@ public BMesh() /////////////////////////////////////////////////////////////////////////// #region [Topology Methods] - /** - * Add a new vertex to the mesh. - */ + /// + /// Adds the specified to the . + /// + /// The to add to the . + /// The that was added. public Vertex AddVertex(Vertex vert) { EnsureVertexAttributes(vert); vertices.Add(vert); return vert; } + + /// + /// Adds a new to the with the specified position. + /// + /// The position of the to + /// create and add to the . + /// The that was created and added. public Vertex AddVertex(Vector3 point) { return AddVertex(new Vertex(point)); } + + /// + /// Adds a new to the with the specified position. + /// + /// The x position of the to create. + /// The y position of the to create. + /// The z position of the to create. + /// The that was created and added. public Vertex AddVertex(float x, float y, float z) { return AddVertex(new Vector3(x, y, z)); } - - /** - * Add a new edge between two vertices. If there is already such edge, - * return it without adding a new one. - * If the vertices are not part of the mesh, the behavior is undefined. - */ + + /// + /// Adds a new comprised of the specified vertices. + /// If there is already an between them, return it + /// without creating a new one. + /// + /// + /// If the vertices are not part of the , + /// the behavior is undefined. + /// + /// The used for one end of the . + /// The used for one end of the . + /// + /// An in the that is comprised of + /// and . + /// public Edge AddEdge(Vertex vert1, Vertex vert2) { Debug.Assert(vert1 != vert2); @@ -161,17 +188,35 @@ public Edge AddEdge(Vertex vert1, Vertex vert2) return edge; } + /// + /// Adds a new comprised of the vertices at the specified indices. + /// If there is already an between them, return it + /// without creating a new one. + /// + /// + /// If the vertices are not part of the , + /// the behavior is undefined. + /// + /// The index of the to use for one end of the . + /// The index of the to use for one end of the . + /// + /// An in the that is comprised of the + /// at index and the + /// at index . + /// public Edge AddEdge(int v1, int v2) { return AddEdge(vertices[v1], vertices[v2]); } - - /** - * Add a new face that connects the array of vertices provided. - * The vertices must be part of the mesh, otherwise the behavior is - * undefined. - * NB: There is no AddLoop, because a loop is an element of a face - */ + + /// + /// Adds a new with loops that is comprised of the specified s. + /// + /// The vertices that are used to create the . + /// The created using the specified vertices. + /// + /// The vertices must be part of the mesh, otherwise the behavior is undefined. + /// public Face AddFace(Vertex[] fVerts) { if (fVerts.Length == 0) return null; @@ -201,41 +246,110 @@ public Face AddFace(Vertex[] fVerts) return f; } + /// + /// Adds a new with loops that is comprised of the specified s. + /// + /// One of the s to use to create the . + /// One of the s to use to create the . + /// The created using the specified vertices. + /// + /// The vertices must be part of the mesh, otherwise the behavior is undefined. + /// public Face AddFace(Vertex v0, Vertex v1) { return AddFace(new Vertex[] { v0, v1 }); } + /// + /// Adds a new with loops that is comprised of the specified s. + /// + /// One of the s to use to create the . + /// One of the s to use to create the . + /// One of the s to use to create the . + /// The created using the specified vertices. + /// + /// The vertices must be part of the mesh, otherwise the behavior is undefined. + /// public Face AddFace(Vertex v0, Vertex v1, Vertex v2) { return AddFace(new Vertex[] { v0, v1, v2 }); } + /// + /// Adds a new with loops that is comprised of the specified s. + /// + /// One of the s to use to create the . + /// One of the s to use to create the . + /// One of the s to use to create the . + /// One of the s to use to create the . + /// The created using the specified vertices. + /// + /// The vertices must be part of the mesh, otherwise the behavior is undefined. + /// public Face AddFace(Vertex v0, Vertex v1, Vertex v2, Vertex v3) { return AddFace(new Vertex[] { v0, v1, v2, v3 }); } + /// + /// Adds a new with loops that is comprised of the specified s. + /// + /// The index of one of the s to use to create the . + /// The index of one of the s to use to create the . + /// The created using the specified vertices. + /// + /// The vertices must be part of the mesh, otherwise the behavior is undefined. + /// public Face AddFace(int i0, int i1) { return AddFace(new Vertex[] { vertices[i0], vertices[i1] }); } + /// + /// Adds a new with loops that is comprised of the specified s. + /// + /// The index of one of the s to use to create the . + /// The index of one of the s to use to create the . + /// The index of one of the s to use to create the . + /// The created using the specified vertices. + /// + /// The vertices must be part of the mesh, otherwise the behavior is undefined. + /// public Face AddFace(int i0, int i1, int i2) { return AddFace(new Vertex[] { vertices[i0], vertices[i1], vertices[i2] }); } + /// + /// Adds a new with loops that is comprised of the specified s. + /// + /// The index of one of the s to use to create the . + /// The index of one of the s to use to create the . + /// The index of one of the s to use to create the . + /// The index of one of the s to use to create the . + /// The created using the specified vertices. + /// + /// The vertices must be part of the mesh, otherwise the behavior is undefined. + /// public Face AddFace(int i0, int i1, int i2, int i3) { return AddFace(new Vertex[] { vertices[i0], vertices[i1], vertices[i2], vertices[i3] }); } - - /** - * Return an edge that links vert1 to vert2 in the mesh (an arbitrary one - * if there are several such edges, which is possible with this structure). - * Return null if there is no edge between vert1 and vert2 in the mesh. - */ + + /// + /// Searches for an that consists of the specified + /// s and returns the first occurence. + /// + /// + /// One of the s that consist the to search for. + /// + /// + /// One of the s that consist the to search for. + /// + /// + /// The first that consists of + /// and , if found; otherwise null. + /// public Edge FindEdge(Vertex vert1, Vertex vert2) { Debug.Assert(vert1 != vert2); @@ -252,12 +366,16 @@ public Edge FindEdge(Vertex vert1, Vertex vert2) } while (e1 != vert1.edge && e2 != vert2.edge); return null; } - - /** - * Remove the provided vertex from the mesh. - * Removing a vertex also removes all the edges/loops/faces that use it. - * If the vertex was not part of this mesh, the behavior is undefined. - */ + + /// + /// Removes the specified from the , + /// also removes all s, s + /// and s that use it. + /// + /// The to remove from the . + /// + /// If the specified is not part of the , the behavior is undefined. + /// public void RemoveVertex(Vertex v) { while (v.edge != null) @@ -268,11 +386,14 @@ public void RemoveVertex(Vertex v) vertices.Remove(v); } - /** - * Remove the provided edge from the mesh. - * Removing an edge also removes all associated loops/faces. - * If the edge was not part of this mesh, the behavior is undefined. - */ + /// + /// Removes the specified from the , + /// also removes all s and s that use it. + /// + /// The to remove from the . + /// + /// If the specified is not part of the , the behavior is undefined. + /// public void RemoveEdge(Edge e) { while (e.loop != null) @@ -329,11 +450,14 @@ void RemoveLoop(Loop l) loops.Remove(l); } - /** - * Remove the provided face from the mesh. - * If the face was not part of this mesh, the behavior is undefined. - * (actually almost ensured to be a true mess, but do as it pleases you :D) - */ + /// + /// Removes the specified from the , + /// also removes all associated s. + /// + /// The to remove from the . + /// + /// If the specified is not part of the , the behavior is undefined. + /// public void RemoveFace(Face f) { Loop l = f.loop; @@ -348,8 +472,7 @@ public void RemoveFace(Face f) faces.Remove(f); } #endregion - - + /////////////////////////////////////////////////////////////////////////// #region [Vertex Attribute Methods] diff --git a/Library/Edge.cs b/Library/Edge.cs index 4cc485f..9814324 100644 --- a/Library/Edge.cs +++ b/Library/Edge.cs @@ -3,26 +3,30 @@ namespace BMeshLib { - /** - * An edge links to vertices together, and may or may not be part of a face. - * An edge can be shared by several faces. - * - * Technical Note: The structure stores a reference to the two vertices. - * Although the role of these two vertices is perfectly symmetrical, this - * makes the iterations over linked list slightly trickier than expected. - * - * The edge is a node of two (double) linked lists at the same time. Let's - * recall that a (simply) linked list of Stuff is made of nodes of the form - * Node { - * Stuff value; - * Node next; - * } - * Here we provide two "next", depending on whether the vertex that we are - * interested in is vertex1 or vertex2. Note that a vertex stored in the - * "vertex1" field for one edge might be stored in the "vertex2" of the - * next one, so the function Next() is provided to return either next1 or - * next2 depending on the vertex of interest. - */ + + // An edge links to vertices together, and may or may not be part of a face. + // An edge can be shared by several faces. + // + // Technical Note: The structure stores a reference to the two vertices. + // Although the role of these two vertices is perfectly symmetrical, this + // makes the iterations over linked list slightly trickier than expected. + // + // The edge is a node of two (double) linked lists at the same time. Let's + // recall that a (simply) linked list of Stuff is made of nodes of the form + // Node { + // Stuff value; + // Node next; + // } + // Here we provide two "next", depending on whether the vertex that we are + // interested in is vertex1 or vertex2. Note that a vertex stored in the + // "vertex1" field for one edge might be stored in the "vertex2" of the + // next one, so the function Next() is provided to return either next1 or + // next2 depending on the vertex of interest. + + /// + /// Links two s together, and may or may not be part of a . + /// + /// Multiple s can share the same . public class Edge { public int id; // [attribute] @@ -35,28 +39,59 @@ public class Edge public Edge prev2; public Loop loop; // first node of the list of faces that use this edge. Navigate list using radial_next - /** - * Tells whether a vertex is one of the extremities of this edge. - */ + /// + /// Whether the specified is one of the vertices that comprise the . + /// + /// The to compare. + /// + /// true if is used by the ; otherwise, false. + /// public bool ContainsVertex(Vertex v) { return v == vert1 || v == vert2; } - /** - * If one gives a vertex of the edge to this function, it returns the - * other vertex of the edge. Otherwise, the behavior is undefined. - */ + /// + /// Returns the other that comprises the . + /// + /// + /// Assumes that the specified is one of the two vertices + /// that comprise the ; otherwise, behavior is undefined. + /// + /// The to get the other of. + /// The other that makes up the edge. public Vertex OtherVertex(Vertex v) { Debug.Assert(ContainsVertex(v)); return v == vert1 ? vert2 : vert1; } - /** - * If one gives a vertex of the edge to this function, it returns the - * next edge in the linked list of edges that use this vertex. - */ + /// + /// Returns the next in the linked list of edges that use + /// the specified . (Opposite of ). + /// + /// + /// Assumes that the specified is one of the vertices that + /// comprise the ; otherwise, behavior is undefined. + /// It is ensured calling Next on each resulting will iterate through + /// all edges that the specified comprises. + /// + /// + /// For instance the following iterates through all edges: + /// + /// Edge firstEdge = edge; + /// do { + /// // do something with `edge` + /// edge = edge.Next(v); + /// } while(edge != firstEdge); + /// + /// + /// + /// The to get the next of. + /// + /// The next in the linked list of edges that uses , + /// both edges having in common. + /// public Edge Next(Vertex v) { Debug.Assert(ContainsVertex(v)); @@ -73,9 +108,32 @@ public void SetNext(Vertex v, Edge other) else next2 = other; } - /** - * Similar to Next() but to go backward in the double-linked list - */ + /// + /// Returns the previous in the linked list of edges that + /// use the specified . (Opposite of ). + /// + /// + /// Assumes that the specified is one of the vertices that + /// comprise the ; otherwise, behavior is undefined. + /// It is ensured calling Prev on each resulting will iterate through + /// all edges that the specified comprises. + /// + /// + /// For instance the following iterates through all edges: + /// + /// Edge firstEdge = edge; + /// do { + /// // do something with `edge` + /// edge = edge.Prev(v); + /// } while(edge != firstEdge); + /// + /// + /// + /// The to get the previous of. + /// + /// The previous in the linked list of edges that uses , + /// bothing edges having in common. + /// public Edge Prev(Vertex v) { Debug.Assert(ContainsVertex(v)); @@ -92,9 +150,10 @@ public void SetPrev(Vertex v, Edge other) else prev2 = other; } - /** - * Return all faces that use this edge as a side. - */ + /// + /// Returns all s that use the as a side. + /// + /// All s that use the as one of it's sides. public List NeighborFaces() { var faces = new List(); @@ -110,9 +169,10 @@ public List NeighborFaces() return faces; } - /** - * Compute the barycenter of the edge's vertices - */ + /// + /// The center of the 's vertices. + /// + /// The center between and . public Vector3 Center() { return (vert1.point + vert2.point) * 0.5f; diff --git a/Library/Face.cs b/Library/Face.cs index b1dab8d..e42ecc6 100644 --- a/Library/Face.cs +++ b/Library/Face.cs @@ -4,11 +4,14 @@ namespace BMeshLib { - /** - * A face is almost nothing more than a loop. Having a different structure - * makes sense only 1. for clarity, because loops are a less intuitive - * object and 2. to store face attributes. - */ + /// + /// Represents a face of a mesh in a . + /// + /// + /// A is little more than a . + /// However it is used since it is more intuitive than a , + /// and stores face s. + /// public class Face { public int id; // [attribute] @@ -16,9 +19,12 @@ public class Face public int vertcount; // stored for commodity, can be recomputed easily public Loop loop; // navigate list using next - /** - * Get the list of vertices used by the face, ordered. - */ + /// + /// Returns the ordered s that comprise the corners of the . + /// + /// + /// The vertices that comprise corners of the . + /// public List NeighborVertices() { var verts = new List(); @@ -34,10 +40,16 @@ public List NeighborVertices() return verts; } - /** - * Assuming the vertex is part of the face, return the loop such that - * loop.vert = v. Return null otherwise. - */ + /// + /// Returns the in the + /// whose matches the specified . + /// + /// The to get the of. + /// + /// The of the + /// whose matches + /// if it is part of the ; otherwise, null. + /// public Loop Loop(Vertex v) { if (this.loop != null) @@ -53,11 +65,14 @@ public Loop Loop(Vertex v) return null; } - /** - * Get the list of edges around the face. - * It is garrantied to match the order of NeighborVertices(), so that - * edge[0] = vert[0]-->vert[1], edge[1] = vert[1]-->vert[2], etc. - */ + /// + /// Returns the ordered s around the . + /// + /// The s that make up the . + /// /// + /// Guarantied to match the order of . + /// So that edge[0] = vert[0]-->vert[1], edge[1] = vert[1]-->vert[2], etc. + /// public List NeighborEdges() { var edges = new List(); @@ -73,9 +88,10 @@ public List NeighborEdges() return edges; } - /** - * Compute the barycenter of the face vertices - */ + /// + /// The center of the vertices that are used by the . + /// + /// The center of . public Vector3 Center() { Vector3 p = Vector3.zero; diff --git a/Library/Loop.cs b/Library/Loop.cs index db14e01..41f1325 100644 --- a/Library/Loop.cs +++ b/Library/Loop.cs @@ -3,21 +3,25 @@ namespace BMeshLib { - /** - * Since a face is basically a list of edges, and the Loop object is a node - * of this list, called so because the list must loop. - * A loop is associated to one and only one face. - * - * A loop can be seen as a list of edges, it also stores a reference to a - * vertex for commodity but technically it could be found through the edge. - * It may also be interpreted as a "face corner", and is hence where one - * typically stores UVs, because one vertex may have different UV - * coordinates depending on the face. - * - * On top of this, the loop is also used as a node of another linked list, - * namely the radial list, that enables iterating over all the faces using - * the same edge. - */ + // Since a face is basically a list of edges, and the Loop object is a node + // of this list, called so because the list must loop. + // A loop is associated to one and only one face. + // + // A loop can be seen as a list of edges, it also stores a reference to a + // vertex for commodity but technically it could be found through the edge. + // It may also be interpreted as a "face corner", and is hence where one + // typically stores UVs, because one vertex may have different UV + // coordinates depending on the face. + // + // On top of this, the loop is also used as a node of another linked list, + // namely the radial list, that enables iterating over all the faces using + // the same edge. + + /// + /// A combination of a , an and a . + /// Meant to provide fast access to neighboring edges, by traversing around the with + /// and . Or by traversing around the with RadialNext and RadialPrev. + /// public class Loop { public Dictionary attributes; // [attribute] (extra attributes) @@ -38,10 +42,10 @@ public Loop(Vertex v, Edge e, Face f) SetFace(f); } - /** - * Insert the loop in the linked list of the face. - * (Used in constructor) - */ + /// + /// Insert the in to the linked list of the specified . + /// + /// The to insert the in to. public void SetFace(Face f) { Debug.Assert(this.face == null); @@ -63,10 +67,10 @@ public void SetFace(Face f) this.face = f; } - /** - * Insert the loop in the radial linked list. - * (Used in constructor) - */ + /// + /// Insert the in to the radial linked list. + /// + /// The to insert the in to. public void SetEdge(Edge e) { Debug.Assert(this.edge == null); diff --git a/Library/Vertex.cs b/Library/Vertex.cs index b05f705..25cf1c0 100644 --- a/Library/Vertex.cs +++ b/Library/Vertex.cs @@ -4,25 +4,35 @@ namespace BMeshLib { - /** - * NB: For all topology types, except for members marked as "attribute", - * all classes only store references to objects allocated by BMesh itself. - * Variables marked as attributes have no impact on the topological - * algorithm applied to the mesh (e.g. finding the neighbors), they are - * only set by calling code. In particuler, the 'id' field has no meaning - * for this class, it is put here purely for commodity, but don't expect it - * to get actually filled unless you explicitely did do. - */ + // NB: For all topology types, except for members marked as "attribute", + // all classes only store references to objects allocated by BMesh itself. + // Variables marked as attributes have no impact on the topological + // algorithm applied to the mesh (e.g. finding the neighbors), they are + // only set by calling code. In particuler, the 'id' field has no meaning + // for this class, it is put here purely for commodity, but don't expect it + // to get actually filled unless you explicitely did do. + // + // + // A vertex corresponds roughly to a position in space. Many primitives + // (edges, faces) can share a given vertex. Several vertices can be located + // at the very same position. + // It references a chained list of the edges that use it, embeded inside the Edge + // structure (see below, and see implementation of NeighborEdges). + // The vertex position does not affect topological algorithms, but is used by + // commodity functions that help finding the center of an edge or a face. - /** - * A vertex corresponds roughly to a position in space. Many primitives - * (edges, faces) can share a given vertex. Several vertices can be located - * at the very same position. - * It references a chained list of the edges that use it, embeded inside the Edge - * structure (see below, and see implementation of NeighborEdges). - * The vertex position does not affect topological algorithms, but is used by - * commodity functions that help finding the center of an edge or a face. - */ + /// + /// Corresponds to a point in space, and is used by + /// and to construct a . + /// + /// + /// Multiple s and s can use + /// a given , and multiple vertices can be located + /// at the exact same position. A references a chained list + /// of the s that use it embedded inside the edge structure. + /// The 's position does not affect topological algorithms, + /// but is used by commodity functions that help finding the center of an edge or a face. + /// public class Vertex { public int id; // [attribute] @@ -35,9 +45,13 @@ public Vertex(Vector3 _point) point = _point; } - /** - * List all edges reaching this vertex. - */ + /// + /// Returns all s that reach the . + /// + /// + /// All s that reach the . Uses + /// from until it reaches again. + /// public List NeighborEdges() { var edges = new List(); @@ -53,9 +67,12 @@ public List NeighborEdges() return edges; } - /** - * Return all faces that use this vertex as a corner. - */ + /// + /// Returns all s that use the as a corner. + /// + /// + /// All s that use the as one of it's corners. + /// public List NeighborFaces() { var faces = new HashSet();