256 lines
9.7 KiB
C
256 lines
9.7 KiB
C
|
/*
|
||
|
|
* Copyright (C) 2017 The Android Open Source Project
|
||
|
|
*
|
||
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
||
|
|
* you may not use this file except in compliance with the License.
|
||
|
|
* You may obtain a copy of the License at
|
||
|
|
*
|
||
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
||
|
|
*
|
||
|
|
* Unless required by applicable law or agreed to in writing, software
|
||
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
||
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||
|
|
* See the License for the specific language governing permissions and
|
||
|
|
* limitations under the License.
|
||
|
|
*/
|
||
|
|
|
||
|
|
#ifndef TNT_FILAMENT_TRANSFORMMANAGER_H
|
||
|
|
#define TNT_FILAMENT_TRANSFORMMANAGER_H
|
||
|
|
|
||
|
|
#include <filament/FilamentAPI.h>
|
||
|
|
|
||
|
|
#include <utils/compiler.h>
|
||
|
|
#include <utils/EntityInstance.h>
|
||
|
|
|
||
|
|
#include <math/mathfwd.h>
|
||
|
|
|
||
|
|
#include <iterator>
|
||
|
|
|
||
|
|
|
||
|
|
namespace utils {
|
||
|
|
class Entity;
|
||
|
|
} // namespace utils
|
||
|
|
|
||
|
|
namespace filament {
|
||
|
|
|
||
|
|
class FTransformManager;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* TransformManager is used to add transform components to entities.
|
||
|
|
*
|
||
|
|
* A Transform component gives an entity a position and orientation in space in the coordinate
|
||
|
|
* space of its parent transform. The TransformManager takes care of computing the world-space
|
||
|
|
* transform of each component (i.e. its transform relative to the root).
|
||
|
|
*
|
||
|
|
* Creation and destruction
|
||
|
|
* ========================
|
||
|
|
*
|
||
|
|
* A transform component is created using TransformManager::create() and destroyed by calling
|
||
|
|
* TransformManager::destroy().
|
||
|
|
*
|
||
|
|
* ~~~~~~~~~~~{.cpp}
|
||
|
|
* filament::Engine* engine = filament::Engine::create();
|
||
|
|
* utils::Entity object = utils::EntityManager.get().create();
|
||
|
|
*
|
||
|
|
* auto& tcm = engine->getTransformManager();
|
||
|
|
*
|
||
|
|
* // create the transform component
|
||
|
|
* tcm.create(object);
|
||
|
|
*
|
||
|
|
* // set its transform
|
||
|
|
* auto i = tcm.getInstance(object);
|
||
|
|
* tcm.setTransform(i, mat4f::translation({ 0, 0, -1 }));
|
||
|
|
*
|
||
|
|
* // destroy the transform component
|
||
|
|
* tcm.destroy(object);
|
||
|
|
* ~~~~~~~~~~~
|
||
|
|
*
|
||
|
|
*/
|
||
|
|
class UTILS_PUBLIC TransformManager : public FilamentAPI {
|
||
|
|
public:
|
||
|
|
using Instance = utils::EntityInstance<TransformManager>;
|
||
|
|
|
||
|
|
class children_iterator : std::iterator<std::forward_iterator_tag, Instance> {
|
||
|
|
friend class FTransformManager;
|
||
|
|
TransformManager const& mManager;
|
||
|
|
Instance mInstance;
|
||
|
|
children_iterator(TransformManager const& mgr, Instance instance) noexcept
|
||
|
|
: mManager(mgr), mInstance(instance) { }
|
||
|
|
public:
|
||
|
|
children_iterator& operator++();
|
||
|
|
|
||
|
|
children_iterator operator++(int) { // NOLINT
|
||
|
|
children_iterator ret(*this);
|
||
|
|
++(*this);
|
||
|
|
return ret;
|
||
|
|
}
|
||
|
|
|
||
|
|
bool operator == (const children_iterator& other) const noexcept {
|
||
|
|
return mInstance == other.mInstance;
|
||
|
|
}
|
||
|
|
|
||
|
|
bool operator != (const children_iterator& other) const noexcept {
|
||
|
|
return mInstance != other.mInstance;
|
||
|
|
}
|
||
|
|
|
||
|
|
value_type operator*() const { return mInstance; }
|
||
|
|
};
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns whether a particular Entity is associated with a component of this TransformManager
|
||
|
|
* @param e An Entity.
|
||
|
|
* @return true if this Entity has a component associated with this manager.
|
||
|
|
*/
|
||
|
|
bool hasComponent(utils::Entity e) const noexcept;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Gets an Instance representing the transform component associated with the given Entity.
|
||
|
|
* @param e An Entity.
|
||
|
|
* @return An Instance object, which represents the transform component associated with the Entity e.
|
||
|
|
* @note Use Instance::isValid() to make sure the component exists.
|
||
|
|
* @see hasComponent()
|
||
|
|
*/
|
||
|
|
Instance getInstance(utils::Entity e) const noexcept;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Creates a transform component and associate it with the given entity.
|
||
|
|
* @param entity An Entity to associate a transform component to.
|
||
|
|
* @param parent The Instance of the parent transform, or Instance{} if no parent.
|
||
|
|
* @param localTransform The transform to initialize the transform component with.
|
||
|
|
* This is always relative to the parent.
|
||
|
|
*
|
||
|
|
* If this component already exists on the given entity, it is first destroyed as if
|
||
|
|
* destroy(utils::Entity e) was called.
|
||
|
|
*
|
||
|
|
* @see destroy()
|
||
|
|
*/
|
||
|
|
void create(utils::Entity entity, Instance parent, const math::mat4f& localTransform);
|
||
|
|
void create(utils::Entity entity, Instance parent = {});
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Destroys this component from the given entity, children are orphaned.
|
||
|
|
* @param e An entity.
|
||
|
|
*
|
||
|
|
* @note If this transform had children, these are orphaned, which means their local
|
||
|
|
* transform becomes a world transform. Usually it's nonsensical. It's recommended to make
|
||
|
|
* sure that a destroyed transform doesn't have children.
|
||
|
|
*
|
||
|
|
* @see create()
|
||
|
|
*/
|
||
|
|
void destroy(utils::Entity e) noexcept;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Re-parents an entity to a new one.
|
||
|
|
* @param i The instance of the transform component to re-parent
|
||
|
|
* @param newParent The instance of the new parent transform
|
||
|
|
* @attention It is an error to re-parent an entity to a descendant and will cause undefined behaviour.
|
||
|
|
* @see getInstance()
|
||
|
|
*/
|
||
|
|
void setParent(Instance i, Instance newParent) noexcept;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns the parent of a transform component, or the null entity if it is a root.
|
||
|
|
* @param i The instance of the transform component to query.
|
||
|
|
*/
|
||
|
|
utils::Entity getParent(Instance i) const noexcept;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns the number of children of a transform component.
|
||
|
|
* @param i The instance of the transform component to query.
|
||
|
|
* @return The number of children of the queried component.
|
||
|
|
*/
|
||
|
|
size_t getChildCount(Instance i) const noexcept;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Gets a list of children for a transform component.
|
||
|
|
*
|
||
|
|
* @param i The instance of the transform component to query.
|
||
|
|
* @param children Pointer to array-of-Entity. The array must have at least "count" elements.
|
||
|
|
* @param count The maximum number of children to retrieve.
|
||
|
|
* @return The number of children written to the pointer.
|
||
|
|
*/
|
||
|
|
size_t getChildren(Instance i, utils::Entity* children, size_t count) const noexcept;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns an iterator to the Instance of the first child of the given parent.
|
||
|
|
*
|
||
|
|
* @param parent Instance of the parent
|
||
|
|
* @return A forward iterator pointing to the first child of the given parent.
|
||
|
|
*
|
||
|
|
* A child_iterator can only safely be dereferenced if it's different from getChildrenEnd(parent)
|
||
|
|
*/
|
||
|
|
children_iterator getChildrenBegin(Instance parent) const noexcept;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns an undreferencable iterator representing the end of the children list
|
||
|
|
*
|
||
|
|
* @param parent Instance of the parent
|
||
|
|
* @return A forward iterator.
|
||
|
|
*
|
||
|
|
* This iterator cannot be dereferenced
|
||
|
|
*/
|
||
|
|
children_iterator getChildrenEnd(Instance parent) const noexcept;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Sets a local transform of a transform component.
|
||
|
|
* @param ci The instance of the transform component to set the local transform to.
|
||
|
|
* @param localTransform The local transform (i.e. relative to the parent).
|
||
|
|
* @see getTransform()
|
||
|
|
* @attention This operation can be slow if the hierarchy of transform is too deep, and this
|
||
|
|
* will be particularly bad when updating a lot of transforms. In that case,
|
||
|
|
* consider using openLocalTransformTransaction() / commitLocalTransformTransaction().
|
||
|
|
*/
|
||
|
|
void setTransform(Instance ci, const math::mat4f& localTransform) noexcept;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns the local transform of a transform component.
|
||
|
|
* @param ci The instance of the transform component to query the local transform from.
|
||
|
|
* @return The local transform of the component (i.e. relative to the parent). This always
|
||
|
|
* returns the value set by setTransform().
|
||
|
|
* @see setTransform()
|
||
|
|
*/
|
||
|
|
const math::mat4f& getTransform(Instance ci) const noexcept;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Return the world transform of a transform component.
|
||
|
|
* @param ci The instance of the transform component to query the world transform from.
|
||
|
|
* @return The world transform of the component (i.e. relative to the root). This is the
|
||
|
|
* composition of this component's local transform with its parent's world transform.
|
||
|
|
* @see setTransform()
|
||
|
|
*/
|
||
|
|
const math::mat4f& getWorldTransform(Instance ci) const noexcept;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Opens a local transform transaction. During a transaction, getWorldTransform() can
|
||
|
|
* return an invalid transform until commitLocalTransformTransaction() is called. However,
|
||
|
|
* setTransform() will perform significantly better and in constant time.
|
||
|
|
*
|
||
|
|
* This is useful when updating many transforms and the transform hierarchy is deep (say more
|
||
|
|
* than 4 or 5 levels).
|
||
|
|
*
|
||
|
|
* @note If the local transform transaction is already open, this is a no-op.
|
||
|
|
*
|
||
|
|
* @see commitLocalTransformTransaction(), setTransform()
|
||
|
|
*/
|
||
|
|
void openLocalTransformTransaction() noexcept;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Commits the currently open local transform transaction. When this returns, calls
|
||
|
|
* to getWorldTransform() will return the proper value.
|
||
|
|
*
|
||
|
|
* @attention failing to call this method when done updating the local transform will cause
|
||
|
|
* a lot of rendering problems. The system never closes the transaction
|
||
|
|
* automatically.
|
||
|
|
*
|
||
|
|
* @note If the local transform transaction is not open, this is a no-op.
|
||
|
|
*
|
||
|
|
* @see openLocalTransformTransaction(), setTransform()
|
||
|
|
*/
|
||
|
|
void commitLocalTransformTransaction() noexcept;
|
||
|
|
};
|
||
|
|
|
||
|
|
} // namespace filament
|
||
|
|
|
||
|
|
|
||
|
|
#endif // TNT_TRANSFORMMANAGER_H
|