SceneTools: hint at MeshTools::transform*D() in flattenMeshHierarchy().

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, {}});

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);
 

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);