export clear_faceviews & update FaceView docstring

Author: ffreyer

docs/src/meshes.md

@@ -53,7 +53,7 @@ As a minimal example consider a mesh that is just one triangle, i.e. 3 position
 Let's say we want to add a flat color to the triangle.
 In this case we only have one color, but our face refers to 3 different vertices (3 different positions).
 To avoid duplicating the color data, we can instead define a new triangle face `TriangleFace(1)` and add the color attribute as a `FaceView([color], [TriangleFace(1)])`.
-If we ever need the mesh to be defined with just one common set of faces, i.e. no FaceView and appropriately duplicated vertex data, we can use `GeometryBasics.clear_faceviews(mesh)` to generate it.
+If we ever need the mesh to be defined with just one common set of faces, i.e. no FaceView and appropriately duplicated vertex data, we can use `clear_faceviews(mesh)` to generate it.
 
 On a larger scale this can be useful for memory and performance reason, e.g. when you do calculations with vertex attributes.
 It can also simplify some definitions, like for example `Rect3`.

src/GeometryBasics.jl

@@ -41,6 +41,7 @@ export AbstractFace, TriangleFace, QuadFace, GLTriangleFace
 export OffsetInteger, ZeroIndex, OneIndex, GLIndex
 export decompose, coordinates, faces, normals, decompose_uv, decompose_normals,
        texturecoordinates, vertex_attributes
+export clear_faceviews
 export face_normals
 export Tesselation, Normal, UV, UVW
 export AbstractMesh, Mesh, MetaMesh, FaceView

src/basic_types.jl

@@ -382,10 +382,20 @@ Base.length(mpt::MultiPoint) = length(mpt.points)
 """
     FaceView(data, faces)
 
-A FaceView is alternative to passing a vertex attribute directly to a mesh. It 
-bundles `data` with a different set of `faces` which replace the default faces
-of a mesh. Doing this allows you to have the `data` in a different order from 
-vertices in the mesh, potentially avoiding duplication.
+A FaceView is an alternative to passing a vertex attributes directly to a mesh. 
+It bundles `data` with a new set of `faces` which may index that data differently
+from the faces defined in a mesh. This can be useful to avoid duplication of data.
+
+For example, `data` can be defined per face by giving each face just one (repeated)
+index:
+```julia
+per_face_normals = FaceView(
+    normals,                 # one per face
+    FT.(eachindex(normals))  # with FT = facetype(mesh)
+)
+```
+
+To remove `FaceView`s from a mesh, e.g. for rendering, use `clear_faceviews(mesh)`.
 
 You can get the data of a FaceView with `values(faceview)` and the faces with
 `faces(faceview)`.