Feature guide » Using scene graph

Transformations

Transformation handles object position, rotation etc. and its basic property is dimension count (2D or 3D) and underlying floating-point type. All classes in SceneGraph are templated on underlying type. However, in most cases Float is used and thus nearly all classes have convenience aliases so you don't have to explicitly specify it.

Scene graph has various transformation implementations for both 2D and 3D. Each implementation has its own advantages and disadvantages — for example when using matrices you can have nearly arbitrary transformations, but composing transformations, computing their inverse and accounting for floating-point drift is rather costly operation. On the other hand quaternions won't allow you to scale or shear objects, but have far better performance characteristics.

It's also possible to implement your own transformation class for specific needs, see source of builtin transformation classes for more information.

Magnum provides the following transformation classes. See documentation of each class for more detailed information:

• SceneGraph::MatrixTransformation2D — arbitrary 2D transformations but with slow inverse transformations and no floating-point drift reduction
• SceneGraph::MatrixTransformation3D — arbitrary 3D transformations but with slow inverse transformations and no floating-point drift reduction
• SceneGraph::RigidMatrixTransformation2D — 2D translation, rotation and reflection (no scaling), with relatively fast inverse transformations and floating-point drift reduction
• SceneGraph::RigidMatrixTransformation3D — 3D translation, rotation and reflection (no scaling), with relatively fast inverse transformations and floating-point drift reduction
• SceneGraph::DualComplexTransformation — 2D translation and rotation with fast inverse transformations and floating-point drift reduction
• SceneGraph::DualQuaternionTransformation — 3D translation and rotation with fast inverse transformation and floating-point drift reduction
• SceneGraph::TranslationTransformation*D — Just 2D/3D translation (no rotation, scaling or anything else)

Common usage of transformation classes is to typedef Scene and Object with desired transformation type to save unnecessary typing later:

typedef SceneGraph::Scene<SceneGraph::MatrixTransformation3D> Scene3D;
typedef SceneGraph::Object<SceneGraph::MatrixTransformation3D> Object3D;

The object type is subclassed from the transformation type and so the Object3D type will then contain all members from both SceneGraph::Object and SceneGraph::MatrixTransformation3D. For convenience you can use method chaining:

Scene3D scene;

Object3D object;
object.setParent(&scene)
    .rotateY(15.0_degf)
    .translate(Vector3::xAxis(5.0f));

Scene hierarchy

Scene hierarchy is skeleton part of scene graph. In the root there is SceneGraph::Scene and its children are SceneGraph::Object instances. Whole hierarchy has one transformation type, identical for all objects (because for example having part of the tree in 2D and part in 3D just wouldn't make sense).

Then you can start building the hierarchy by parenting one object to another. Parent object can be either passed in constructor or set using SceneGraph::Object::setParent(). Scene is always root object, so it naturally cannot have parent object. Parent and children relationships can be observed through SceneGraph::Object::parent() and SceneGraph::Object::children().

Scene3D scene;

Object3D* first = new Object3D{&scene};
Object3D* second = new Object3D{first};

The hierarchy takes care of memory management — when an object is destroyed, all its children are destroyed too. See detailed explanation of construction and destruction order below for information about possible issues. To reflect the implicit memory management in the code better, you can use SceneGraph::Object::addChild() instead of the naked new call in the code above:

Scene3D scene;

Object3D& first = scene.addChild<Object3D>();
Object3D& second = first.addChild<Object3D>();

Object features

The object itself handles only parent/child relationship and transformation. To make the object renderable, animable, add collision shape to it etc., you have to add a feature to it.

Magnum provides the following builtin features. See documentation of each class for more detailed information and usage examples:

• SceneGraph::Camera*D — Handles projection matrix, aspect ratio correction etc.. Used for rendering parts of the scene.
• SceneGraph::Drawable*D — Adds drawing functionality to given object. Group of drawables can be then rendered using the camera feature.
• SceneGraph::Animable*D — Adds animation functionality to given object. Group of animables can be then controlled using SceneGraph::AnimableGroup*D.
• Shapes::Shape — Adds collision shape to given object. Group of shapes can be then controlled using Shapes::ShapeGroup*D. See Collision detection for more information.
• DebugTools::ObjectRenderer*D, DebugTools::ShapeRenderer*D, DebugTools::ForceRenderer*D — Visualize object properties, object shape or force vector for debugging purposes. See Debugging helpers for more information.

Each feature takes reference to holder object in constructor, so adding a feature to an object might look just like the following, as in some cases you don't even need to keep the pointer to it. List of object features is accessible through SceneGraph::Object::features().

Object3D& o;
new MyFeature{o, ...};

Some features are passive, some active. Passive features can be just added to an object, with no additional work except for possible configuration (for example collision shape). Active features require the user to implement some virtual function (for example to draw the object on screen or perform animation step). To make things convenient, features can be added directly to object itself using multiple inheritance, so you can conveniently add all the active features you want and implement needed functions in your own SceneGraph::Object subclass without having to subclass each feature individually (and making the code overly verbose). Simplified example:

class BouncingBall: public Object3D, SceneGraph::Drawable3D, SceneGraph::Animable3D {
    public:
        explicit BouncingBall(Object3D* parent): Object3D{parent}, SceneGraph::Drawable3D{*this}, SceneGraph::Animable3D{*this} {}

    private:
        // drawing implementation for Drawable feature
        void draw(...) override;

        // animation step for Animable feature
        void animationStep(...) override;
};

From the outside there is no difference between features added "at runtime" and features added using multiple inheritance, they can be both accessed from feature list.

Similarly to object hierarchy, when destroying object, all its features (both member and inherited) are destroyed. See detailed explanation of construction and destruction order for information about possible issues. Also, there is a SceneGraph::AbstractObject::addFeature() counterpart to SceneGraph::Object::addChild():

Object3D& o;
o.addFeature<MyFeature>(...);

class CachingObject: public Object3D, SceneGraph::AbstractFeature3D {
    public:
        explicit CachingObject(Object3D* parent): Object3D{parent}, SceneGraph::AbstractFeature3D{*this} {
            setCachedTransformations(SceneGraph::CachedTransformation::Absolute);
        }

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

    private:
        Vector3 _absolutePosition;
};

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

    private:
        SceneGraph::AbstractTranslationRotation3D& transformation;
};

Construction and destruction order

There aren't any limitations and usage trade-offs of what you can and can't do when working with objects and features, but there are two issues which you should be aware of:

{
    Scene3D scene;
    Object3D object(&scene);
}

{
    Object3D object;
    Scene3D scene;

    object.setParent(&scene);
} // crash!

class MyObject: public Object3D, MyFeature {
    public:
        MyObject(Object3D* parent): Object3D(parent), MyFeature(*this) {}
};

class MyObject: MyFeature, public Object3D {
    public:
        MyObject(Object3D* parent): MyFeature(*this), Object3D(parent) {} // crash!
};

class MyObject: MyFeature, public Object3D {
    public:
        MyObject(Object3D* parent): Object3D(parent), MyFeature(*this) {}

        // crash on destruction!
};