From 9b679bd1bae24dd17c3f8a2c02fe6bb36019099b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Tue, 28 Oct 2014 14:00:41 +0100 Subject: [PATCH] doc: have all references in docs relative to root namespace. --- doc/platform.dox | 29 ++++++++------- doc/scenegraph.dox | 93 ++++++++++++++++++++++++---------------------- doc/shapes.dox | 10 ++--- 3 files changed, 68 insertions(+), 64 deletions(-) diff --git a/doc/platform.dox b/doc/platform.dox index aec3216ed..e080b0e4e 100644 --- a/doc/platform.dox +++ b/doc/platform.dox @@ -23,7 +23,7 @@ DEALINGS IN THE SOFTWARE. */ -namespace Magnum { namespace Platform { +namespace Magnum { /** @page platform Platform support @brief Integration into windowing toolkits and creation of windowless contexts. @@ -48,9 +48,9 @@ Windowed applications provide a window and keyboard and mouse handling. The de-facto standard and most widely used toolkit is SDL2, which is implemented in @ref Platform::Sdl2Application. As said above, the usage is similar for all toolkits, you must provide one-argument constructor and implement at least -@ref Sdl2Application::drawEvent() "drawEvent()" function. The class can be then -used directly in `main()`, but for convenience and portability it's better to -use @ref MAGNUM_SDL2APPLICATION_MAIN() macro. +@ref Platform::Sdl2Application::drawEvent() "drawEvent()" function. The class +can be then used directly in `main()`, but for convenience and portability it's +better to use @ref MAGNUM_SDL2APPLICATION_MAIN() macro. To simplify the porting, the library provides `Platform::Application` typedef and `MAGNUM_APPLICATION_MAIN()` macro (but only if only one application header @@ -103,8 +103,8 @@ MAGNUM_APPLICATION_MAIN(MyApplication) By default the application doesn't respond to window size changes in any way, as the window has fixed size in most cases. To respond to size change for example by resizing the default framebuffer, you need to reimplement -@ref Sdl2Application::viewportEvent() "viewportEvent()" function and pass the -new size to the framebuffer: +@ref Platform::Sdl2Application::viewportEvent() "viewportEvent()" function and +pass the new size to the framebuffer: @code class MyApplication: public Platform::Application { // ... @@ -130,7 +130,7 @@ Windows. To make things simple, as an example we will use only @ref Platform::WindowlessGlxApplication, see link for bootstrap application below for fully portable example. -You need to implement just @ref WindowlessGlxApplication::exec() "exec()" +You need to implement just @ref Platform::WindowlessGlxApplication::exec() "exec()" function. The class can be then used directly in `main()`, but again, for convenience and portability it's better to use @ref MAGNUM_WINDOWLESSGLXAPPLICATION_MAIN() macro. @@ -211,8 +211,9 @@ target_link_libraries(myapplication By default the application is created with some reasonable defaults (e.g. window size 800x600 pixels). If you want something else, you can pass -@ref Sdl2Application::Configuration "Configuration" instance to application -constructor. Using method chaining it can be done conveniently like this: +@ref Platform::Sdl2Application::Configuration "Configuration" instance to +application constructor. Using method chaining it can be done conveniently like +this: @code MyApplication::MyApplication(int& argc, char** argv): Platform::Application(argc, argv, Configuration() @@ -225,8 +226,8 @@ MyApplication::MyApplication(int& argc, char** argv): However, sometimes you would need to configure the application based on some configuration file or system introspection. In that case you can pass `nullptr` -instead of @ref Sdl2Application::Configuration "Configuration" instance and -then specify it later with @ref Sdl2Application::createContext() "createContext()": +instead of @ref Platform::Sdl2Application::Configuration "Configuration" +instance and then specify it later with @ref Platform::Sdl2Application::createContext() "createContext()": @code MyApplication::MyApplication(int& argc, char** argv): Platform::Application(argc, argv, nullptr) { // ... @@ -239,9 +240,9 @@ MyApplication::MyApplication(int& argc, char** argv): Platform::Application(argc } @endcode -If the context creation in constructor or @ref Sdl2Application::createContext() "createContext()" +If the context creation in constructor or @ref Platform::Sdl2Application::createContext() "createContext()" fails, the application exits. However, it is also possible to negotiate the -context using @ref Sdl2Application::tryCreateContext() "tryCreateContext()". +context using @ref Platform::Sdl2Application::tryCreateContext() "tryCreateContext()". The only difference is that this function returns `false` instead of exiting. You can for example try enabling MSAA and if the context creation fails, fall back to no-AA rendering: @@ -319,4 +320,4 @@ target_link_libraries(myapplication - Next page: @ref types */ -}} +} diff --git a/doc/scenegraph.dox b/doc/scenegraph.dox index a145ed4d0..7a36d9e39 100644 --- a/doc/scenegraph.dox +++ b/doc/scenegraph.dox @@ -23,7 +23,7 @@ DEALINGS IN THE SOFTWARE. */ -namespace Magnum { namespace SceneGraph { +namespace Magnum { /** @page scenegraph Using scene graph @brief Overview of scene management capabilities. @@ -59,9 +59,8 @@ 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 @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. + in most cases @ref 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 @@ -77,19 +76,20 @@ 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 -@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: +@ref SceneGraph::Scene and its children are @ref SceneGraph::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 Scene3D; typedef SceneGraph::Object 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 @ref Object::setParent(). -Scene is always root object, so it naturally cannot have parent object. +Parent object can be either passed in constructor or using +@ref SceneGraph::Object::setParent(). Scene is always root object, so it +naturally cannot have parent object. @code Scene3D scene; @@ -97,10 +97,11 @@ auto first = new Object3D(&scene); auto second = new Object3D(first); @endcode -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: +Object children can be accessed using @ref SceneGraph::Object::firstChild() and +@ref SceneGraph::Object::lastChild(), then you can traverse siblings (objects +with the same parent) with @ref SceneGraph::Object::previousSibling() and +@ref SceneGraph::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()) { @@ -138,10 +139,11 @@ Object3D* o; new MyFeature(o); @endcode -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: +Features of an object can be accessed using @ref SceneGraph::Object::firstFeature() +and @ref SceneGraph::Object::lastFeature(), then you can traverse the features +using @ref SceneGraph::AbstractFeature::previousFeature() and +@ref SceneGraph::AbstractFeature::nextFeature(), similarly to traversing object +children: @code Object3D* o; for(Object3D::FeatureType feature = o->firstFeature(); feature; feature = feature->nextFeature()) { @@ -150,14 +152,14 @@ for(Object3D::FeatureType feature = o->firstFeature(); feature; feature = featur @endcode Some features are passive, some active. Passive features can be just added to -an object like above, without any additional work (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 @ref Object subclass without having to -subclass each feature individually (and making the code overly verbose). -Simplified example: +an object like above, without any additional work (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 @ref SceneGraph::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 { public: @@ -190,21 +192,22 @@ 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 @ref Object::setDirty(). +transformation, changing parent or explicitly calling @ref SceneGraph::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): +@ref SceneGraph::AbstractFeature::markDirty() is called on every feature. +Calling @ref SceneGraph::Object::setClean() cleans the dirty object and all its +dirty parents. The function goes through all object features and calls +@ref SceneGraph::AbstractFeature::clean() or +@ref SceneGraph::AbstractFeature::cleanInverted() depending on which caching is +enabled on given feature. If the object is already clean, +@ref SceneGraph::Object::setClean() does nothing. + +Most probably you will need caching in @ref SceneGraph::Object itself -- which +doesn't support it on its own -- however you can take advantage of multiple +inheritance and implement it using @ref SceneGraph::AbstractFeature. In order +to have caching, you must enable it first, because by default the caching is +disabled. You can enable it using @ref SceneGraph::AbstractFeature::setCachedTransformations() +and then implement corresponding cleaning function(s): @code class CachingObject: public Object3D, SceneGraph::AbstractFeature3D { public: @@ -223,9 +226,9 @@ class CachingObject: public Object3D, SceneGraph::AbstractFeature3D { @endcode When you need to use the cached value, you can explicitly request the cleanup -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. +by calling @ref SceneGraph::Object::setClean(). @ref SceneGraph::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 SceneGraph-AbstractFeature-subclassing-caching for more information. @@ -308,4 +311,4 @@ program didn't already crash) destructor of MyFeature is called (again). - Previous page: @ref plugins - Next page: @ref shapes */ -}} +} diff --git a/doc/shapes.dox b/doc/shapes.dox index 664897de0..dd4f4fba5 100644 --- a/doc/shapes.dox +++ b/doc/shapes.dox @@ -23,7 +23,7 @@ DEALINGS IN THE SOFTWARE. */ -namespace Magnum { namespace Shapes { +namespace Magnum { /** @page shapes Collision detection @brief Collection of simple shapes for high performance collision detection. @@ -124,9 +124,9 @@ As this is useful for e.g. menu handling and simple particle systems, for serious physics you often need more information like contact point, separation normal and penetration depth. For shape pairs which have implemented this detailed collision detection you can use the `/` operator, which returns -@ref Collision object. Note that unlike with the `%` operator mentioned above, -this operation is not commutative. See @ref Collision class documentation for -more information about the returned data. Example: +@ref Shapes::Collision object. Note that unlike with the `%` operator mentioned +above, this operation is not commutative. See @ref Shapes::Collision class +documentation for more information about the returned data. Example: @code const Shapes::Collision3D c = point/sphere; if(c) { @@ -173,4 +173,4 @@ debugging purposes. See also @ref scenegraph for introduction. - Next page: @ref debug-tools */ -}}} +}