SceneGraph: doc++

doc/scenegraph.dox

@@ -57,9 +57,10 @@ three main components:
 Transformation handles object position, rotation etc. and its basic property
 is dimension count (2D or 3D) and underlying floating-point type.
 
-@note 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.
+@note All classes in @ref SceneGraph are templated on underlying type. However,
+    in most cases @ref Magnum::Float "Float" is used and thus nearly all
+    classes have convenience aliases so you don't have to explicitly specify
+    it.
 
 %Scene graph has implementation of transformations in both 2D and 3D, using
 either matrices or combination of position and rotation. Each implementation
@@ -74,19 +75,19 @@ needs, see source of other transformation classes for more information.
 
 @section scenegraph-hierarchy Scene hierarchy
 
-%Scene hierarchy is skeleton part of scene graph. In the root there is Scene
-and its children are Object instances. The hierarchy has some 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). Common usage is to typedef
-%Scene and %Object with desired transformation type to save unnecessary typing
-later:
+%Scene hierarchy is skeleton part of scene graph. In the root there is
+@ref Scene and its children are @ref Object instances. The hierarchy has some
+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). Common usage is to
+typedef %Scene and %Object with desired transformation type to save unnecessary
+typing later:
 @code
 typedef SceneGraph::Scene<SceneGraph::MatrixTransformation3D> Scene3D;
 typedef SceneGraph::Object<SceneGraph::MatrixTransformation3D> Object3D;
 @endcode
 
 Then you can start building the hierarchy by *parenting* one object to another.
-Parent object can be either passed in constructor or using Object::setParent().
+Parent object can be either passed in constructor or using @ref Object::setParent().
 %Scene is always root object, so it naturally cannot have parent object.
 @code
 Scene3D scene;
@@ -95,10 +96,10 @@ auto first = new Object3D(&scene);
 auto second = new Object3D(first);
 @endcode
 
-%Object children can be accessed using Object::firstChild() and
-Object::lastChild(), then you can traverse siblings (objects with the same
-parent) with Object::previousSibling() and Object::nextSibling(). For example
-all children of an object can be traversed the following way:
+%Object children can be accessed using @ref Object::firstChild() and
+@ref Object::lastChild(), then you can traverse siblings (objects with the same
+parent) with @ref Object::previousSibling() and @ref Object::nextSibling(). For
+example all children of an object can be traversed the following way:
 @code
 Object3D* o;
 for(Object3D* child = o->firstChild(); child; child = child->nextSibling()) {
@@ -136,9 +137,9 @@ Object3D* o;
 new MyFeature(o);
 @endcode
 
-Features of an object can be accessed using Object::firstFeature() and
-Object::lastFeature(), then you can traverse the features using
-AbstractFeature::previousFeature() and AbstractFeature::nextFeature(),
+Features of an object can be accessed using @ref Object::firstFeature() and
+@ref Object::lastFeature(), then you can traverse the features using
+@ref AbstractFeature::previousFeature() and @ref AbstractFeature::nextFeature(),
 similarly to traversing object children:
 @code
 Object3D* o;
@@ -153,11 +154,11 @@ 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 Object subclass without having to
+implement needed functions in your own @ref Object subclass without having to
 subclass each feature individually (and making the code overly verbose).
 Simplified example:
 @code
-class Bomb: public Object3D, SceneGraph::Drawable3D, SceneGraph:.Animable3D {
+class Bomb: public Object3D, SceneGraph::Drawable3D, SceneGraph::Animable3D {
     public:
         Bomb(Object3D* parent): Object3D(parent), SceneGraph::Drawable3D(*this), SceneGraph::Animable3D(*this) {}
 
@@ -188,20 +189,21 @@ objects etc. To avoid computing the transformations from scratch every time,
 the feature can cache them.
 
 The cached data stay until the object is marked as dirty - that is by changing
-transformation, changing parent or explicitly calling Object::setDirty(). If
-the object is marked as dirty, all its children are marked as dirty too and
-AbstractFeature::markDirty() is called on every feature. Calling
-Object::setClean() cleans the dirty object and all its dirty parents.
-The function goes through all object features and calls AbstractFeature::clean()
-or AbstractFeature::cleanInverted() depending on which caching is enabled on
-given feature. If the object is already clean, Object::setClean() does nothing.
-
-Most probably you will need caching in Object itself -- which doesn't support
-it on its own -- however you can take advantage of multiple inheritance and
-implement it using AbstractFeature. In order to have caching, you must enable
-it first, because by default the caching is disabled. You can enable it using
-AbstractFeature::setCachedTransformations() and then implement corresponding
-cleaning function(s):
+transformation, changing parent or explicitly calling @ref Object::setDirty().
+If the object is marked as dirty, all its children are marked as dirty too and
+@ref AbstractFeature::markDirty() is called on every feature. Calling
+@ref Object::setClean() cleans the dirty object and all its dirty parents.
+The function goes through all object features and calls @ref AbstractFeature::clean()
+or @ref AbstractFeature::cleanInverted() depending on which caching is enabled
+on given feature. If the object is already clean, @ref Object::setClean() does
+nothing.
+
+Most probably you will need caching in @ref Object itself -- which doesn't
+support it on its own -- however you can take advantage of multiple inheritance
+and implement it using @ref AbstractFeature. In order to have caching, you must
+enable it first, because by default the caching is disabled. You can enable it
+using @ref AbstractFeature::setCachedTransformations() and then implement
+corresponding cleaning function(s):
 @code
 class CachingObject: public Object3D, SceneGraph::AbstractFeature3D {
     public:
@@ -220,9 +222,9 @@ class CachingObject: public Object3D, SceneGraph::AbstractFeature3D {
 @endcode
 
 When you need to use the cached value, you can explicitly request the cleanup
-by calling Object::setClean(). Camera, for example, calls it automatically
-before it starts rendering, as it needs its own inverse transformation to
-properly draw the objects.
+by calling @ref Object::setClean(). @ref Camera3D "Camera", for example, calls
+it automatically before it starts rendering, as it needs its own inverse
+transformation to properly draw the objects.
 
 See @ref AbstractFeature-subclassing-caching for more information.