From 44cce23595619e9191ffc75336e5efb4c4777aec Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= <mosra@centrum.cz>
Date: Sun, 19 Dec 2021 20:33:45 +0100
Subject: [PATCH] SceneTools: hint at MeshTools::transform*D() in
 flattenMeshHierarchy().

---
 doc/snippets/MagnumSceneTools.cpp            | 36 ++++++++++++++++++++
 src/Magnum/MeshTools/Concatenate.h           |  3 +-
 src/Magnum/SceneTools/FlattenMeshHierarchy.h | 16 ++++++---
 3 files changed, 50 insertions(+), 5 deletions(-)

diff --git a/doc/snippets/MagnumSceneTools.cpp b/doc/snippets/MagnumSceneTools.cpp
index 867849ee0..fe5ce4757 100644
--- a/doc/snippets/MagnumSceneTools.cpp
+++ b/doc/snippets/MagnumSceneTools.cpp
@@ -24,17 +24,53 @@
 */
 
 #include <Corrade/Containers/Array.h>
+#include <Corrade/Containers/GrowableArray.h>
 #include <Corrade/Containers/Pair.h>
+#include <Corrade/Containers/Triple.h>
 
+#include "Magnum/Math/Matrix3.h"
 #include "Magnum/Math/Matrix4.h"
+#include "Magnum/MeshTools/Transform.h"
+#include "Magnum/SceneTools/FlattenMeshHierarchy.h"
 #include "Magnum/SceneTools/OrderClusterParents.h"
 #include "Magnum/Trade/SceneData.h"
+#include "Magnum/Trade/MeshData.h"
 
 #define DOXYGEN_ELLIPSIS(...) __VA_ARGS__
 
 using namespace Magnum;
 
 int main() {
+{
+/* [flattenMeshHierarchy2D-transformations] */
+Trade::SceneData scene = DOXYGEN_ELLIPSIS(Trade::SceneData{{}, 0, nullptr, {}});
+Containers::Array<Trade::MeshData> meshes = DOXYGEN_ELLIPSIS({});
+
+/* Since a mesh can be referenced multiple times, we can't operate in-place */
+Containers::Array<Trade::MeshData> flattenedMeshes;
+for(const Containers::Triple<UnsignedInt, Int, Matrix3>& meshTransformation:
+    SceneTools::flattenMeshHierarchy2D(scene))
+{
+    arrayAppend(flattenedMeshes, MeshTools::transform2D(
+        meshes[meshTransformation.first()], meshTransformation.third()));
+}
+/* [flattenMeshHierarchy2D-transformations] */
+} {
+/* [flattenMeshHierarchy3D-transformations] */
+Trade::SceneData scene = DOXYGEN_ELLIPSIS(Trade::SceneData{{}, 0, nullptr, {}});
+Containers::Array<Trade::MeshData> meshes = DOXYGEN_ELLIPSIS({});
+
+/* Since a mesh can be referenced multiple times, we can't operate in-place */
+Containers::Array<Trade::MeshData> flattenedMeshes;
+for(const Containers::Triple<UnsignedInt, Int, Matrix4>& meshTransformation:
+    SceneTools::flattenMeshHierarchy3D(scene))
+{
+    arrayAppend(flattenedMeshes, MeshTools::transform3D(
+        meshes[meshTransformation.first()], meshTransformation.third()));
+}
+/* [flattenMeshHierarchy3D-transformations] */
+}
+
 {
 /* [orderClusterParents-transformations] */
 Trade::SceneData scene = DOXYGEN_ELLIPSIS(Trade::SceneData{{}, 0, nullptr, {}});
diff --git a/src/Magnum/MeshTools/Concatenate.h b/src/Magnum/MeshTools/Concatenate.h
index a2f9230c3..4889db09d 100644
--- a/src/Magnum/MeshTools/Concatenate.h
+++ b/src/Magnum/MeshTools/Concatenate.h
@@ -70,7 +70,8 @@ applying transformations.
 If an index buffer is needed, @ref MeshIndexType::UnsignedInt is always used.
 Call @ref compressIndices(const Trade::MeshData&, MeshIndexType) on the result
 to compress it to a smaller type, if desired.
-@see @ref concatenateInto()
+@see @ref concatenateInto(), @ref SceneTools::flattenMeshHierarchy2D(),
+    @ref SceneTools::flattenMeshHierarchy3D()
 */
 MAGNUM_MESHTOOLS_EXPORT Trade::MeshData concatenate(Containers::ArrayView<const Containers::Reference<const Trade::MeshData>> meshes);
 
diff --git a/src/Magnum/SceneTools/FlattenMeshHierarchy.h b/src/Magnum/SceneTools/FlattenMeshHierarchy.h
index 58e289025..f7eeaa1b5 100644
--- a/src/Magnum/SceneTools/FlattenMeshHierarchy.h
+++ b/src/Magnum/SceneTools/FlattenMeshHierarchy.h
@@ -46,13 +46,17 @@ absolute transformation in the scene with @p globalTransformation prepended.
 The @ref Trade::SceneField::Parent field is expected to be contained in the
 scene, having no cycles or duplicates, and the scene is expected to be 2D. If
 @ref Trade::SceneField::Mesh is not present or is empty, returns an empty
-array.
+array. You can then use @ref MeshTools::transform2D() to apply the
+transformations to actual meshes:
+
+@snippet MagnumSceneTools.cpp flattenMeshHierarchy2D-transformations
 
 The operation is done in an @f$ \mathcal{O}(m + n) @f$ execution time and
 memory complexity, with @f$ m @f$ being size of the @ref Trade::SceneField::Mesh
 field and @f$ n @f$ being @ref Trade::SceneData::mappingBound(). The function
 calls @ref orderClusterParents() internally.
-@see @ref Trade::SceneData::hasField(), @ref Trade::SceneData::is2D()
+@see @ref Trade::SceneData::hasField(), @ref Trade::SceneData::is2D(),
+    @ref MeshTools::concatenate()
 */
 MAGNUM_SCENETOOLS_EXPORT Containers::Array<Containers::Triple<UnsignedInt, Int, Matrix3>> flattenMeshHierarchy2D(const Trade::SceneData& scene, const Matrix3& globalTransformation);
 
@@ -73,13 +77,17 @@ absolute transformation in the scene with @p globalTransformation prepended.
 The @ref Trade::SceneField::Parent field is expected to be contained in the
 scene, having no cycles or duplicates, and the scene is expected to be 3D. If
 @ref Trade::SceneField::Mesh is not present or is empty, returns an empty
-array.
+array. You can then use @ref MeshTools::transform3D() to apply the
+transformations to actual meshes:
+
+@snippet MagnumSceneTools.cpp flattenMeshHierarchy3D-transformations
 
 The operation is done in an @f$ \mathcal{O}(m + n) @f$ execution time and
 memory complexity, with @f$ m @f$ being size of the @ref Trade::SceneField::Mesh
 field and @f$ n @f$ being @ref Trade::SceneData::mappingBound(). The function
 calls @ref orderClusterParents() internally.
-@see @ref Trade::SceneData::hasField(), @ref Trade::SceneData::is3D()
+@see @ref Trade::SceneData::hasField(), @ref Trade::SceneData::is3D(),
+    @ref MeshTools::concatenate()
 */
 MAGNUM_SCENETOOLS_EXPORT Containers::Array<Containers::Triple<UnsignedInt, Int, Matrix4>> flattenMeshHierarchy3D(const Trade::SceneData& scene, const Matrix4& globalTransformation);