diff --git a/doc/snippets/CMakeLists.txt b/doc/snippets/CMakeLists.txt index f433f47fd..d70c44e85 100644 --- a/doc/snippets/CMakeLists.txt +++ b/doc/snippets/CMakeLists.txt @@ -35,6 +35,7 @@ endif() add_library(snippets STATIC Magnum.cpp + MagnumMeshTools.cpp MagnumShaders.cpp MagnumText.cpp) target_link_libraries(snippets PRIVATE Magnum) diff --git a/doc/snippets/MagnumMeshTools.cpp b/doc/snippets/MagnumMeshTools.cpp new file mode 100644 index 000000000..8a4403eb8 --- /dev/null +++ b/doc/snippets/MagnumMeshTools.cpp @@ -0,0 +1,166 @@ +/* + This file is part of Magnum. + + Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 + Vladimír Vondruš + + 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 "Magnum/Buffer.h" +#include "Magnum/Math/Color.h" +#include "Magnum/MeshTools/CombineIndexedArrays.h" +#include "Magnum/MeshTools/CompressIndices.h" +#include "Magnum/MeshTools/Duplicate.h" +#include "Magnum/MeshTools/GenerateFlatNormals.h" +#include "Magnum/MeshTools/Interleave.h" +#include "Magnum/MeshTools/RemoveDuplicates.h" +#include "Magnum/MeshTools/Transform.h" + +using namespace Magnum; +using namespace Magnum::Math::Literals; + +int main() { + +{ +/* [combineIndexedArrays] */ +std::vector vertexIndices; +std::vector positions; +std::vector normalTextureIndices; +std::vector normals; +std::vector textureCoordinates; + +std::vector indices = MeshTools::combineIndexedArrays( + std::make_pair(std::cref(vertexIndices), std::ref(positions)), + std::make_pair(std::cref(normalTextureIndices), std::ref(normals)), + std::make_pair(std::cref(normalTextureIndices), std::ref(textureCoordinates)) +); +/* [combineIndexedArrays] */ +} + +{ +/* [compressIndices] */ +std::vector indices; + +Containers::Array indexData; +Mesh::IndexType indexType; +UnsignedInt indexStart, indexEnd; +std::tie(indexData, indexType, indexStart, indexEnd) = + MeshTools::compressIndices(indices); + +Buffer indexBuffer; +indexBuffer.setData(indexData, BufferUsage::StaticDraw); + +Mesh mesh; +mesh.setCount(indices.size()) + .setIndexBuffer(indexBuffer, 0, indexType, indexStart, indexEnd); +/* [compressIndices] */ +} + +{ +/* [compressIndicesAs] */ +std::vector indices; +Containers::Array indexData = + MeshTools::compressIndicesAs(indices); +/* [compressIndicesAs] */ +} + +{ +/* [generateFlatNormals] */ +std::vector vertexIndices; +std::vector positions; + +std::vector normalIndices; +std::vector normals; +std::tie(normalIndices, normals) = + MeshTools::generateFlatNormals(vertexIndices, positions); +/* [generateFlatNormals] */ +} + +{ +struct MyShader { + typedef Attribute<0, Vector3> Position; + typedef Attribute<0, Vector2> TextureCoordinates; +}; +/* [interleave1] */ +std::vector positions; +std::vector textureCoordinates; + +Buffer vertexBuffer; +vertexBuffer.setData(MeshTools::interleave(positions, textureCoordinates), BufferUsage::StaticDraw); + +Mesh mesh; +mesh.setCount(positions.size()) + .addVertexBuffer(vertexBuffer, 0, MyShader::Position{}, MyShader::TextureCoordinates{}); +/* [interleave1] */ +} + +{ +/* [interleave2] */ +std::vector positions; +std::vector weights; +std::vector vertexColors; + +auto data = MeshTools::interleave(positions, weights, 2, vertexColors, 1); +/* [interleave2] */ +} + +{ +/* [removeDuplicates1] */ +std::vector indices; +std::vector positions; + +indices = MeshTools::duplicate(indices, MeshTools::removeDuplicates(positions)); +/* [removeDuplicates1] */ +} + +{ +/* [removeDuplicates2] */ +std::vector positions; +std::vector texCoords; + +std::vector positionIndices = MeshTools::removeDuplicates(positions); +std::vector texCoordIndices = MeshTools::removeDuplicates(texCoords); + +std::vector indices = MeshTools::combineIndexedArrays( + std::make_pair(std::cref(positionIndices), std::ref(positions)), + std::make_pair(std::cref(texCoordIndices), std::ref(texCoords)) +); +/* [removeDuplicates2] */ +} + +{ +/* [transformVectors] */ +std::vector vectors; +auto transformation = Quaternion::rotation(35.0_degf, Vector3::yAxis()); +MeshTools::transformVectorsInPlace(transformation, vectors); +/* [transformVectors] */ +} + +{ +/* [transformPoints] */ +std::vector points; +auto transformation = + DualQuaternion::rotation(35.0_degf, Vector3::yAxis())* + DualQuaternion::translation({0.5f, -1.0f, 3.0f}); +MeshTools::transformPointsInPlace(transformation, points); +/* [transformPoints] */ +} + +} diff --git a/src/Magnum/MeshTools/CombineIndexedArrays.h b/src/Magnum/MeshTools/CombineIndexedArrays.h index eedea4827..3bdfb8ed1 100644 --- a/src/Magnum/MeshTools/CombineIndexedArrays.h +++ b/src/Magnum/MeshTools/CombineIndexedArrays.h @@ -158,19 +158,7 @@ avoid explicit verbose specification of tuple type, you can write it with help of some STL functions like shown below. Also if one index array is shared by more than one attribute array, just pass the index array more times. Example: -@code{.cpp} -std::vector vertexIndices; -std::vector positions; -std::vector normalTextureIndices; -std::vector normals; -std::vector textureCoordinates; - -std::vector indices = MeshTools::combineIndexedArrays( - std::make_pair(std::cref(vertexIndices), std::ref(positions)), - std::make_pair(std::cref(normalTextureIndices), std::ref(normals)), - std::make_pair(std::cref(normalTextureIndices), std::ref(textureCoordinates)) -); -@endcode +@snippet MagnumMeshTools.cpp combineIndexedArrays See @ref combineIndexArrays() documentation for more information about the procedure. diff --git a/src/Magnum/MeshTools/CompressIndices.h b/src/Magnum/MeshTools/CompressIndices.h index 7546356a9..9e144de2d 100644 --- a/src/Magnum/MeshTools/CompressIndices.h +++ b/src/Magnum/MeshTools/CompressIndices.h @@ -48,21 +48,7 @@ sufficient. Example usage: -@code{.cpp} -std::vector indices; - -Containers::Array indexData; -Mesh::IndexType indexType; -UnsignedInt indexStart, indexEnd; -std::tie(indexData, indexType, indexStart, indexEnd) = MeshTools::compressIndices(indices); - -Buffer indexBuffer; -indexBuffer.setData(indexData, BufferUsage::StaticDraw); - -Mesh mesh; -mesh.setCount(indices.size()) - .setIndexBuffer(indexBuffer, 0, indexType, indexStart, indexEnd); -@endcode +@snippet MagnumMeshTools.cpp compressIndices @see @ref compressIndicesAs() @todo Extract IndexType out of Mesh class @@ -78,10 +64,7 @@ Values in the index array are expected to be representable with given type. Example usage: -@code{.cpp} -std::vector indices; -Containers::Array indexData = MeshTools::compressIndicesAs(indices); -@endcode +@snippet MagnumMeshTools.cpp compressIndicesAs @see @ref compressIndices() */ diff --git a/src/Magnum/MeshTools/GenerateFlatNormals.h b/src/Magnum/MeshTools/GenerateFlatNormals.h index 98c7d1923..f91a60b6f 100644 --- a/src/Magnum/MeshTools/GenerateFlatNormals.h +++ b/src/Magnum/MeshTools/GenerateFlatNormals.h @@ -46,14 +46,7 @@ namespace Magnum { namespace MeshTools { For each face generates one normal vector, removes duplicates before returning. Example usage: -@code{.cpp} -std::vector vertexIndices; -std::vector positions; - -std::vector normalIndices; -std::vector normals; -std::tie(normalIndices, normals) = MeshTools::generateFlatNormals(vertexIndices, positions); -@endcode +@snippet MagnumMeshTools.cpp generateFlatNormals You can then use @ref combineIndexedArrays() to combine normal and vertex array to use the same indices. diff --git a/src/Magnum/MeshTools/Interleave.h b/src/Magnum/MeshTools/Interleave.h index 51895a615..617f6947e 100644 --- a/src/Magnum/MeshTools/Interleave.h +++ b/src/Magnum/MeshTools/Interleave.h @@ -100,30 +100,12 @@ data for each attribute are in continuous place in memory. Example usage: -@code{.cpp} -MeshPrimitive primitive; -std::vector positions; -std::vector textureCoordinates; - -Buffer vertexBuffer; -vertexBuffer.setData(MeshTools::interleave(positions, textureCoordinates), BufferUsage::StaticDraw); - -Mesh mesh; -mesh.setPrimitive(primitive) - .setCount(positions.count()) - .addVertexBuffer(vertexBuffer, 0, MyShader::Position{}, MyShader::TextureCoordinates{}); -@endcode +@snippet MagnumMeshTools.cpp interleave1 It's often desirable to align data for one vertex on 32bit boundaries. To achieve that, you can specify gaps between the attributes: -@code{.cpp} -std::vector positions; -std::vector weights; -std::vector vertexColors; - -auto data = MeshTools::interleave(positions, weights, 2, textureCoordinates, 1); -@endcode +@snippet MagnumMeshTools.cpp interleave2 All gap bytes are set zero. This way vertex stride is 24 bytes, without gaps it would be 21 bytes, causing possible performance loss. diff --git a/src/Magnum/MeshTools/RemoveDuplicates.h b/src/Magnum/MeshTools/RemoveDuplicates.h index 1a364ecba..a417b611d 100644 --- a/src/Magnum/MeshTools/RemoveDuplicates.h +++ b/src/Magnum/MeshTools/RemoveDuplicates.h @@ -66,30 +66,14 @@ If you want to remove duplicate data from already indexed array, first remove duplicates as if the array wasn't indexed at all and then use @ref duplicate() to combine the two index arrays: -@code{.cpp} -std::vector indices; -std::vector positions; - -indices = MeshTools::duplicate(indices, MeshTools::removeDuplicates(positions)); -@endcode +@snippet MagnumMeshTools.cpp removeDuplicates1 Removing duplicates in multiple indcidental arrays is also possible --- first remove duplicates in each array separately and then use @ref combineIndexedArrays() to combine the resulting index arrays to single index array and reorder the data accordingly: -@code{.cpp} -std::vector positions; -std::vector texCoords; - -std::vector positionIndices = MeshTools::removeDuplicates(positions); -std::vector texCoordIndices = MeshTools::removeDuplicates(texCoords); - -std::vector indices = MeshTools::combineIndexedArrays( - std::make_pair(std::cref(positionIndices), std::ref(positions)), - std::make_pair(std::cref(texCoordIndices), std::ref(texCoords)) -); -@endcode +@snippet MagnumMeshTools.cpp removeDuplicates2 */ template std::vector removeDuplicates(std::vector& data, typename Vector::Type epsilon = Math::TypeTraits::epsilon()) { /* Get bounds */ diff --git a/src/Magnum/MeshTools/Transform.h b/src/Magnum/MeshTools/Transform.h index 3d9c25b42..9f748146e 100644 --- a/src/Magnum/MeshTools/Transform.h +++ b/src/Magnum/MeshTools/Transform.h @@ -48,11 +48,7 @@ translation. Example usage: -@code{.cpp} -std::vector vectors; -auto transformation = Quaternion::rotation(35.0_degf, Vector3::yAxis()); -MeshTools::transformVectorsInPlace(rotation, vectors); -@endcode +@snippet MagnumMeshTools.cpp transformVectors @see @ref transformVectors(), @ref Matrix3::transformVector(), @ref Matrix4::transformVector(), @ref Complex::transformVector(), @@ -104,12 +100,7 @@ translation. Example usage: -@code{.cpp} -std::vector points; -auto transformation = DualQuaternion::rotation(35.0_degf, Vector3::yAxis())* - DualQuaternion::translation({0.5f, -1.0f, 3.0f}); -MeshTools::transformPointsInPlace(rotation, points); -@endcode +@snippet MagnumMeshTools.cpp transformPoints @see @ref transformPoints(), @ref Matrix3::transformPoint(), @ref Matrix4::transformPoint(),