ic
/
magnum
mirror of https://github.com/mosra/magnum.git
6
0
Fork 0
Code Issues Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
10355 Commits
21 Branches
19 Tags
70 MiB
Tree: 2c1b64b3df
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '2c1b64b3df'
${ noResults }
magnum/src/Magnum/SceneTools/FlattenMeshHierarchy.h

174 lines
8.4 KiB
Raw Normal View History Unescape

SceneTools: utility to flatten mesh hierarchy. Internals doing a few rather big allocations, will convert that to just a single one in a next step.
4 years ago
#ifndef Magnum_SceneTools_FlattenMeshHierarchy_h
#define Magnum_SceneTools_FlattenMeshHierarchy_h
/*
This file is part of Magnum.
Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019,
Updated copyright year.
4 years ago
2020, 2021, 2022 Vladimír Vondruš <mosra@centrum.cz>
SceneTools: utility to flatten mesh hierarchy. Internals doing a few rather big allocations, will convert that to just a single one in a next step.
4 years ago
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.
*/
/** @file
* @brief Function @ref Magnum::SceneTools::flattenMeshHierarchy2D(), @ref Magnum::SceneTools::flattenMeshHierarchy3D()
* @m_since_latest
*/
#include "Magnum/Magnum.h"
#include "Magnum/SceneTools/visibility.h"
#include "Magnum/Trade/Trade.h"
namespace Magnum { namespace SceneTools {
/**
@brief Flatten a 2D mesh hierarchy
@m_since_latest
SceneTools: pin down current flattenMeshHierarchy() behavior. It doesn't discard meshes that are not a part of the hierarchy, but that was the plan in the beginning. However, over the time I realized that a better property for it is that the output is guaranteed to be in the same order and size as the mesh field in the scene. Because that's what I relied on in every use case, and every time I had to dig that property out of the sources because it was deliberately not documented *because* it was meant to change. No longer. The compatibility with the mesh field ordering is now documented, the behavior regarding loose objects also, and if there's ever a need to discard everything that's not in the reachable hierarchy, it'll probably get its own API. Because it's useful for general asset cleanup and other use cases, not just meshes. I'm still keeping the experimental tag here though, tp be sure.
4 years ago
For all @ref Trade::SceneField::Mesh entries returns a triple of mesh ID,
@ref Trade::SceneField::MeshMaterial and its 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
SceneTools: utility to flatten mesh hierarchy. Internals doing a few rather big allocations, will convert that to just a single one in a next step.
4 years ago
@ref Trade::SceneField::Mesh is not present or is empty, returns an empty
SceneTools: hint at MeshTools::transform*D() in flattenMeshHierarchy().
4 years ago
array. You can then use @ref MeshTools::transform2D() to apply the
transformations to actual meshes:
@snippet MagnumSceneTools.cpp flattenMeshHierarchy2D-transformations
SceneTools: utility to flatten mesh hierarchy. Internals doing a few rather big allocations, will convert that to just a single one in a next step.
4 years ago
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.
SceneTools: mark everything here as experiental. To make people not rely too much on anything here -- I smell some API changes incoming.
4 years ago
SceneTools: pin down current flattenMeshHierarchy() behavior. It doesn't discard meshes that are not a part of the hierarchy, but that was the plan in the beginning. However, over the time I realized that a better property for it is that the output is guaranteed to be in the same order and size as the mesh field in the scene. Because that's what I relied on in every use case, and every time I had to dig that property out of the sources because it was deliberately not documented *because* it was meant to change. No longer. The compatibility with the mesh field ordering is now documented, the behavior regarding loose objects also, and if there's ever a need to discard everything that's not in the reachable hierarchy, it'll probably get its own API. Because it's useful for general asset cleanup and other use cases, not just meshes. I'm still keeping the experimental tag here though, tp be sure.
4 years ago
The returned data are in the same order as the @ref Trade::SceneField::Mesh
attribute. Meshes attached to objects without a @ref Trade::SceneField::Parent
or to objects in loose hierarchy subtrees will have their transformation set to
an unspecified value.
SceneTools: mark everything here as experiental. To make people not rely too much on anything here -- I smell some API changes incoming.
4 years ago
@experimental
SceneTools: add flattenMeshHierarchyInto(). Now that the data order is pinned down, it's possible to hammer a more efficient underlying API from out under the convenience utility.
4 years ago
@see @ref flattenMeshHierarchy2DInto(), @ref flattenMeshHierarchy3D(),
@ref Trade::SceneData::hasField(), @ref Trade::SceneData::is2D(),
SceneTools: hint at MeshTools::transform*D() in flattenMeshHierarchy().
4 years ago
@ref MeshTools::concatenate()
SceneTools: utility to flatten mesh hierarchy. Internals doing a few rather big allocations, will convert that to just a single one in a next step.
4 years ago
*/
SceneTools: no need to leak include-depdency-breaking overloads to docs. It's enough to just show a single overload with a default argument there, like it's done everywhere else.
4 years ago
#ifdef DOXYGEN_GENERATING_OUTPUT
MAGNUM_SCENETOOLS_EXPORT Containers::Array<Containers::Triple<UnsignedInt, Int, Matrix3>> flattenMeshHierarchy2D(const Trade::SceneData& scene, const Matrix3& globalTransformation = {});
#else
/* To avoid including Matrix3 */
SceneTools: utility to flatten mesh hierarchy. Internals doing a few rather big allocations, will convert that to just a single one in a next step.
4 years ago
MAGNUM_SCENETOOLS_EXPORT Containers::Array<Containers::Triple<UnsignedInt, Int, Matrix3>> flattenMeshHierarchy2D(const Trade::SceneData& scene, const Matrix3& globalTransformation);
MAGNUM_SCENETOOLS_EXPORT Containers::Array<Containers::Triple<UnsignedInt, Int, Matrix3>> flattenMeshHierarchy2D(const Trade::SceneData& scene);
SceneTools: no need to leak include-depdency-breaking overloads to docs. It's enough to just show a single overload with a default argument there, like it's done everywhere else.
4 years ago
#endif
SceneTools: utility to flatten mesh hierarchy. Internals doing a few rather big allocations, will convert that to just a single one in a next step.
4 years ago
SceneTools: add flattenMeshHierarchyInto(). Now that the data order is pinned down, it's possible to hammer a more efficient underlying API from out under the convenience utility.
4 years ago
/**
@brief Flatten a 2D mesh hierarchy into an existing array
@param[in] scene Input scene
@param[out] transformations Where to put the calculated transformations
@param[in] globalTransformation Global transformation to prepend
@m_since_latest
A variant of @ref flattenMeshHierarchy2D() that fills existing memory instead
of allocating a new array. The @p transformations array is expected to have the
same size as the @ref Trade::SceneField::Mesh field. Corresponding mesh and
material IDs as well as object ID mapping can be retrieved directly with
@ref Trade::SceneData::meshesMaterialsInto(), as the returned transformations
are matching their order. The snippet below shows retrieving absolute
transformations together with object and mesh IDs, but ignoring materials:
@snippet MagnumSceneTools.cpp flattenMeshHierarchy2DInto
@experimental
*/
#ifdef DOXYGEN_GENERATING_OUTPUT
MAGNUM_SCENETOOLS_EXPORT void flattenMeshHierarchy2DInto(const Trade::SceneData& scene, const Containers::StridedArrayView1D<Matrix3>& transformations, const Matrix3& globalTransformation = {});
#else
/* To avoid including Matrix3 */
MAGNUM_SCENETOOLS_EXPORT void flattenMeshHierarchy2DInto(const Trade::SceneData& scene, const Containers::StridedArrayView1D<Matrix3>& transformations, const Matrix3& globalTransformation);
MAGNUM_SCENETOOLS_EXPORT void flattenMeshHierarchy2DInto(const Trade::SceneData& scene, const Containers::StridedArrayView1D<Matrix3>& transformations);
#endif
SceneTools: utility to flatten mesh hierarchy. Internals doing a few rather big allocations, will convert that to just a single one in a next step.
4 years ago
/**
@brief Flatten a 3D mesh hierarchy
@m_since_latest
SceneTools: pin down current flattenMeshHierarchy() behavior. It doesn't discard meshes that are not a part of the hierarchy, but that was the plan in the beginning. However, over the time I realized that a better property for it is that the output is guaranteed to be in the same order and size as the mesh field in the scene. Because that's what I relied on in every use case, and every time I had to dig that property out of the sources because it was deliberately not documented *because* it was meant to change. No longer. The compatibility with the mesh field ordering is now documented, the behavior regarding loose objects also, and if there's ever a need to discard everything that's not in the reachable hierarchy, it'll probably get its own API. Because it's useful for general asset cleanup and other use cases, not just meshes. I'm still keeping the experimental tag here though, tp be sure.
4 years ago
For all @ref Trade::SceneField::Mesh entries returns a triple of mesh ID,
@ref Trade::SceneField::MeshMaterial and its 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
SceneTools: utility to flatten mesh hierarchy. Internals doing a few rather big allocations, will convert that to just a single one in a next step.
4 years ago
@ref Trade::SceneField::Mesh is not present or is empty, returns an empty
SceneTools: hint at MeshTools::transform*D() in flattenMeshHierarchy().
4 years ago
array. You can then use @ref MeshTools::transform3D() to apply the
transformations to actual meshes:
@snippet MagnumSceneTools.cpp flattenMeshHierarchy3D-transformations
SceneTools: utility to flatten mesh hierarchy. Internals doing a few rather big allocations, will convert that to just a single one in a next step.
4 years ago
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.
SceneTools: mark everything here as experiental. To make people not rely too much on anything here -- I smell some API changes incoming.
4 years ago
SceneTools: pin down current flattenMeshHierarchy() behavior. It doesn't discard meshes that are not a part of the hierarchy, but that was the plan in the beginning. However, over the time I realized that a better property for it is that the output is guaranteed to be in the same order and size as the mesh field in the scene. Because that's what I relied on in every use case, and every time I had to dig that property out of the sources because it was deliberately not documented *because* it was meant to change. No longer. The compatibility with the mesh field ordering is now documented, the behavior regarding loose objects also, and if there's ever a need to discard everything that's not in the reachable hierarchy, it'll probably get its own API. Because it's useful for general asset cleanup and other use cases, not just meshes. I'm still keeping the experimental tag here though, tp be sure.
4 years ago
The returned data are in the same order as the @ref Trade::SceneField::Mesh
attribute. Meshes attached to objects without a @ref Trade::SceneField::Parent
or to objects in loose hierarchy subtrees will have their transformation set to
an unspecified value.
SceneTools: mark everything here as experiental. To make people not rely too much on anything here -- I smell some API changes incoming.
4 years ago
@experimental
SceneTools: add flattenMeshHierarchyInto(). Now that the data order is pinned down, it's possible to hammer a more efficient underlying API from out under the convenience utility.
4 years ago
@see @ref flattenMeshHierarchy3DInto(), @ref flattenMeshHierarchy2D(),
@ref Trade::SceneData::hasField(), @ref Trade::SceneData::is3D(),
SceneTools: hint at MeshTools::transform*D() in flattenMeshHierarchy().
4 years ago
@ref MeshTools::concatenate()
SceneTools: utility to flatten mesh hierarchy. Internals doing a few rather big allocations, will convert that to just a single one in a next step.
4 years ago
*/
SceneTools: no need to leak include-depdency-breaking overloads to docs. It's enough to just show a single overload with a default argument there, like it's done everywhere else.
4 years ago
#ifdef DOXYGEN_GENERATING_OUTPUT
MAGNUM_SCENETOOLS_EXPORT Containers::Array<Containers::Triple<UnsignedInt, Int, Matrix4>> flattenMeshHierarchy3D(const Trade::SceneData& scene, const Matrix4& globalTransformation = {});
#else
/* To avoid including Matrix4 */
SceneTools: utility to flatten mesh hierarchy. Internals doing a few rather big allocations, will convert that to just a single one in a next step.
4 years ago
MAGNUM_SCENETOOLS_EXPORT Containers::Array<Containers::Triple<UnsignedInt, Int, Matrix4>> flattenMeshHierarchy3D(const Trade::SceneData& scene, const Matrix4& globalTransformation);
MAGNUM_SCENETOOLS_EXPORT Containers::Array<Containers::Triple<UnsignedInt, Int, Matrix4>> flattenMeshHierarchy3D(const Trade::SceneData& scene);
SceneTools: no need to leak include-depdency-breaking overloads to docs. It's enough to just show a single overload with a default argument there, like it's done everywhere else.
4 years ago
#endif
SceneTools: utility to flatten mesh hierarchy. Internals doing a few rather big allocations, will convert that to just a single one in a next step.
4 years ago
SceneTools: add flattenMeshHierarchyInto(). Now that the data order is pinned down, it's possible to hammer a more efficient underlying API from out under the convenience utility.
4 years ago
/**
@brief Flatten a 3D mesh hierarchy into an existing array
@param[in] scene Input scene
@param[out] transformations Where to put the calculated transformations
@param[in] globalTransformation Global transformation to prepend
@m_since_latest
A variant of @ref flattenMeshHierarchy3D() that fills existing memory instead
of allocating a new array. The @p transformations array is expected to have the
same size as the @ref Trade::SceneField::Mesh field. Corresponding mesh and
material IDs as well as object ID mapping can be retrieved directly with
@ref Trade::SceneData::meshesMaterialsInto(), as the returned transformations
are matching their order. The snippet below shows retrieving absolute
transformations together with object and mesh IDs, but ignoring materials:
@snippet MagnumSceneTools.cpp flattenMeshHierarchy3DInto
@experimental
*/
#ifdef DOXYGEN_GENERATING_OUTPUT
MAGNUM_SCENETOOLS_EXPORT void flattenMeshHierarchy3DInto(const Trade::SceneData& scene, const Containers::StridedArrayView1D<Matrix4>& transformations, const Matrix4& globalTransformation = {});
#else
/* To avoid including Matrix3 */
MAGNUM_SCENETOOLS_EXPORT void flattenMeshHierarchy3DInto(const Trade::SceneData& scene, const Containers::StridedArrayView1D<Matrix4>& transformations, const Matrix4& globalTransformation);
MAGNUM_SCENETOOLS_EXPORT void flattenMeshHierarchy3DInto(const Trade::SceneData& scene, const Containers::StridedArrayView1D<Matrix4>& transformations);
#endif
SceneTools: utility to flatten mesh hierarchy. Internals doing a few rather big allocations, will convert that to just a single one in a next step.
4 years ago
}}
#endif