MeshTools: show how generate*NormalsInto() can be used with std::vector.

doc/snippets/CMakeLists.txt

@@ -94,7 +94,8 @@ endif()
 
 if(WITH_MESHTOOLS)
     add_library(snippets-MagnumMeshTools STATIC
-        MagnumMeshTools.cpp)
+        MagnumMeshTools.cpp
+        MagnumMeshTools-gl.cpp)
     target_link_libraries(snippets-MagnumMeshTools PRIVATE MagnumMeshTools)
     set_target_properties(snippets-MagnumMeshTools PROPERTIES FOLDER "Magnum/doc/snippets")
 endif()

doc/snippets/MagnumMeshTools-stl.cpp

@@ -0,0 +1,65 @@
+/*
+    This file is part of Magnum.
+
+    Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019
+              Vladimír Vondruš <mosra@centrum.cz>
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included
+    in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+*/
+
+#include <Corrade/Containers/StridedArrayView.h>
+#include <Corrade/Containers/ArrayViewStl.h>
+
+#include "Magnum/MeshTools/GenerateNormals.h"
+
+using namespace Magnum;
+using namespace Magnum::Math::Literals;
+
+int main() {
+
+{
+/* THe include below is okay as the header guards make it empty */
+/* [generateFlatNormalsInto] */
+#include <Corrade/Containers/ArrayViewStl.h>
+
+// …
+
+std::vector<Vector3> positions;
+
+std::vector<Vector3> normals{positions.size()};
+MeshTools::generateFlatNormalsInto(positions, normals);
+/* [generateFlatNormalsInto] */
+}
+
+{
+/* THe include below is okay as the header guards make it empty */
+/* [generateSmoothNormalsInto] */
+#include <Corrade/Containers/ArrayViewStl.h>
+
+// …
+
+std::vector<UnsignedInt> indices;
+std::vector<Vector3> positions;
+
+std::vector<Vector3> normals{positions.size()};
+MeshTools::generateSmoothNormalsInto<UnsignedInt>(indices, positions, normals);
+/* [generateSmoothNormalsInto] */
+}
+
+}

src/Magnum/MeshTools/GenerateNormals.h

@@ -65,6 +65,13 @@ MAGNUM_MESHTOOLS_EXPORT Containers::Array<Vector3> generateFlatNormals(const Con
 A variant of @ref generateFlatNormals() that fills existing memory instead of
 allocating a new array. The @p normals array is expected to have the same size
 as @p positions.
+
+Useful when you need to interface for example with STL containers --- in that
+case @cpp #include @ce @ref Corrade/Containers/ArrayViewStl.h to get implicit
+conversions:
+
+@snippet MagnumMeshTools-stl.cpp generateFlatNormalsInto
+
 @see @ref generateSmoothNormalsInto()
 */
 MAGNUM_MESHTOOLS_EXPORT void generateFlatNormalsInto(const Containers::StridedArrayView1D<const Vector3>& positions, const Containers::StridedArrayView1D<Vector3>& normals);
@@ -127,6 +134,13 @@ allocating a new array. The @p normals array is expected to have the same size
 as @p positions. Note that even with the output array this function isn't fully
 allocation-free --- it still allocates three additional internal arrays for
 adjacent face calculation.
+
+Useful when you need to interface for example with STL containers --- in that
+case @cpp #include @ce @ref Corrade/Containers/ArrayViewStl.h to get implicit
+conversions:
+
+@snippet MagnumMeshTools-stl.cpp generateSmoothNormalsInto
+
 @see @ref generateFlatNormalsInto()
 */
 template<class T> MAGNUM_MESHTOOLS_EXPORT void generateSmoothNormalsInto(const Containers::StridedArrayView1D<const T>& indices, const Containers::StridedArrayView1D<const Vector3>& positions, const Containers::StridedArrayView1D<Vector3>& normals);