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
+@note All classes in @ref SceneGraph are templated on underlying type. However,
-    most cases Float is used and thus nearly all classes have convenience
+    in most cases @ref Magnum::Float "Float" is used and thus nearly all
-    aliases so you don't have to explicitly specify it.
+    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
+%Scene hierarchy is skeleton part of scene graph. In the root there is
-and its children are Object instances. The hierarchy has some transformation
+@ref Scene and its children are @ref Object instances. The hierarchy has some
-type, identical for all objects (because for example having part of the tree
+transformation type, identical for all objects (because for example having part
-in 2D and part in 3D just wouldn't make sense). Common usage is to typedef
+of the tree in 2D and part in 3D just wouldn't make sense). Common usage is to
-%Scene and %Object with desired transformation type to save unnecessary typing
+typedef %Scene and %Object with desired transformation type to save unnecessary
-later:
+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 children can be accessed using @ref Object::firstChild() and
-Object::lastChild(), then you can traverse siblings (objects with the same
+@ref Object::lastChild(), then you can traverse siblings (objects with the same
-parent) with Object::previousSibling() and Object::nextSibling(). For example
+parent) with @ref Object::previousSibling() and @ref Object::nextSibling(). For
-all children of an object can be traversed the following way:
+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
+Features of an object can be accessed using @ref Object::firstFeature() and
-Object::lastFeature(), then you can traverse the features using
+@ref Object::lastFeature(), then you can traverse the features using
-AbstractFeature::previousFeature() and AbstractFeature::nextFeature(),
+@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
+transformation, changing parent or explicitly calling @ref Object::setDirty().
-the object is marked as dirty, all its children are marked as dirty too and
+If the object is marked as dirty, all its children are marked as dirty too and
-AbstractFeature::markDirty() is called on every feature. Calling
+@ref AbstractFeature::markDirty() is called on every feature. Calling
-Object::setClean() cleans the dirty object and all its dirty parents.
+@ref Object::setClean() cleans the dirty object and all its dirty parents.
-The function goes through all object features and calls AbstractFeature::clean()
+The function goes through all object features and calls @ref AbstractFeature::clean()
-or AbstractFeature::cleanInverted() depending on which caching is enabled on
+or @ref AbstractFeature::cleanInverted() depending on which caching is enabled
-given feature. If the object is already clean, Object::setClean() does nothing.
+on given feature. If the object is already clean, @ref 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
+Most probably you will need caching in @ref Object itself -- which doesn't
-implement it using AbstractFeature. In order to have caching, you must enable
+support it on its own -- however you can take advantage of multiple inheritance
-it first, because by default the caching is disabled. You can enable it using
+and implement it using @ref AbstractFeature. In order to have caching, you must
-AbstractFeature::setCachedTransformations() and then implement corresponding
+enable it first, because by default the caching is disabled. You can enable it
-cleaning function(s):
+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
+by calling @ref Object::setClean(). @ref Camera3D "Camera", for example, calls
-before it starts rendering, as it needs its own inverse transformation to
+it automatically before it starts rendering, as it needs its own inverse
-properly draw the objects.
+transformation to properly draw the objects.
 
 See @ref AbstractFeature-subclassing-caching for more information.