template<UnsignedInt dimensions, class T>
Magnum::SceneGraph::AbstractFeature class

Base for object features.

Contents

Contained in Object, takes care of transformation caching. See Using scene graph for introduction.

Uses Corrade::Containers::LinkedList for accessing holder object and sibling features.

Subclassing

Feature is templated on dimension count and underlying transformation type, so it can be used only on object having transformation with the same dimension count and type.

Caching transformations in features

Features can cache absolute transformation of the object instead of computing it from scratch every time to achieve better performance. See Transformation caching in features for introduction.

In order to have caching, you must enable it first, because by default the caching is disabled. You can enable it using setCachedTransformations() and then implement corresponding cleaning function(s) — either clean(), cleanInverted() or both. Example:

class CachingFeature: public SceneGraph::AbstractFeature3D {
    public:
        explicit CachingFeature(SceneGraph::AbstractObject3D& object): SceneGraph::AbstractFeature3D{object} {
            setCachedTransformations(CachedTransformation::Absolute);
        }

    private:
        void clean(const Matrix4& absoluteTransformationMatrix) override {
            _absolutePosition = absoluteTransformationMatrix.translation();
        }

        Vector3 _absolutePosition;
};

Before using the cached value explicitly request object cleaning by calling object()->setClean().

Accessing object transformation

The feature has by default only access to AbstractObject, which doesn't know about any used transformation. By using small template trick in the constructor it is possible to gain access to transformation interface in the constructor:

class TransformingFeature: public SceneGraph::AbstractFeature3D {
    public:
        template<class T> explicit TransformingFeature(SceneGraph::Object<T>& object):
            SceneGraph::AbstractFeature3D{object}, _transformation{object} {}

    private:
        SceneGraph::AbstractTranslationRotation3D& _transformation;
};

See Polymorphic access to object transformation for more detailed information.

Explicit template specializations

The following specializations are explicitly compiled into SceneGraph library. For other specializations (e.g. using Double type) you have to use AbstractFeature.hpp implementation file to avoid linker errors. See also Template headers and implementation files for more information.

Derived classes

template<UnsignedInt dimensions, class Derived, class T>
class AbstractGroupedFeature
Base for grouped features.
template<UnsignedInt dimensions, class Derived, class T>
class AbstractGroupedFeature
Base for grouped features.
class Magnum::BulletIntegration::MotionState
Bullet Physics motion state.
class Magnum::DartIntegration::Object
DART Physics BodyNode or ShapeNode.
template<UnsignedInt dimensions, class Derived, class T>
class AbstractGroupedFeature
Base for grouped features.
template<UnsignedInt dimensions, class T>
class Camera
Camera.

Constructors, destructors, conversion operators

AbstractFeature(AbstractObject<dimensions, T>& object) explicit
Constructor.

Public functions

auto object() -> AbstractObject<dimensions, T>&
Object holding this feature.
auto object() const -> const AbstractObject<dimensions, T>&
auto previousFeature() -> AbstractFeature<dimensions, T>*
Previous feature or nullptr, if this is first feature.
auto previousFeature() const -> const AbstractFeature<dimensions, T>*
auto nextFeature() -> AbstractFeature<dimensions, T>*
Next feature or nullptr, if this is last feature.
auto nextFeature() const -> const AbstractFeature<dimensions, T>*

Transformation caching

See Transformation caching in features for more information.

auto cachedTransformations() const -> CachedTransformations
Which transformations are cached.
void setCachedTransformations(CachedTransformations transformations) protected
Set transformations to be cached.
void markDirty() protected virtual
Mark feature as dirty.
void clean(const MatrixTypeFor<dimensions, T>& absoluteTransformationMatrix) protected virtual
Clean data based on absolute transformation.
void cleanInverted(const MatrixTypeFor<dimensions, T>& invertedAbsoluteTransformationMatrix) protected virtual
Clean data based on inverted absolute transformation.

Function documentation

template<UnsignedInt dimensions, class T>
Magnum::SceneGraph::AbstractFeature<dimensions, T>::AbstractFeature(AbstractObject<dimensions, T>& object) explicit

Constructor.

Parameters
object Object holding this feature

template<UnsignedInt dimensions, class T>
const AbstractObject<dimensions, T>& Magnum::SceneGraph::AbstractFeature<dimensions, T>::object() const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<UnsignedInt dimensions, class T>
const AbstractFeature<dimensions, T>* Magnum::SceneGraph::AbstractFeature<dimensions, T>::previousFeature() const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<UnsignedInt dimensions, class T>
const AbstractFeature<dimensions, T>* Magnum::SceneGraph::AbstractFeature<dimensions, T>::nextFeature() const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<UnsignedInt dimensions, class T>
CachedTransformations Magnum::SceneGraph::AbstractFeature<dimensions, T>::cachedTransformations() const

Which transformations are cached.

template<UnsignedInt dimensions, class T>
void Magnum::SceneGraph::AbstractFeature<dimensions, T>::setCachedTransformations(CachedTransformations transformations) protected

Set transformations to be cached.

Based on which transformation types are enabled, clean() or cleanInverted() is called when cleaning absolute object transformation.

Nothing is enabled by default.

template<UnsignedInt dimensions, class T>
void Magnum::SceneGraph::AbstractFeature<dimensions, T>::markDirty() virtual protected

Mark feature as dirty.

Reimplement only if you want to invalidate some external data when object is marked as dirty. All expensive computations should be done in clean() and cleanInverted().

Default implementation does nothing.

template<UnsignedInt dimensions, class T>
void Magnum::SceneGraph::AbstractFeature<dimensions, T>::clean(const MatrixTypeFor<dimensions, T>& absoluteTransformationMatrix) virtual protected

Clean data based on absolute transformation.

When object is cleaned and CachedTransformation::Absolute is enabled in setCachedTransformations(), this function is called to recalculate data based on absolute object transformation.

Default implementation does nothing.

template<UnsignedInt dimensions, class T>
void Magnum::SceneGraph::AbstractFeature<dimensions, T>::cleanInverted(const MatrixTypeFor<dimensions, T>& invertedAbsoluteTransformationMatrix) virtual protected

Clean data based on inverted absolute transformation.

When object is cleaned and CachedTransformation::InvertedAbsolute is enabled in setCachedTransformations(), this function is called to recalculate data based on inverted absolute object transformation.

Default implementation does nothing.