Shapes: updated and cleaned up the documentation.

doc/shapes.dox

@@ -77,9 +77,9 @@ is least efficient.
 @section shapes-composition Creating shape compositions
 
 %Shapes can be composed together using one of three available logical
-operations: AND, OR and NOT. These operations are mapped to operator&&(),
-operator||() and operator!(), so for example creating negation of logical OR
-of line segment and point is simple as this:
+operations: AND, OR and NOT. These operations are mapped to `&&`, `||` and `!`
+operators, so for example creating negation of logical OR of line segment and
+point is simple as this:
 @code
 Shapes::LineSegment3D segment;
 Shapes::Point3D point;
@@ -97,9 +97,9 @@ If there are many shapes composed together, it might hurt performance of
 collision detection, because it might be testing collision with more shapes
 than necessary. It's then good to specify simplified version of such shape,
 so the collision detection is done on the complex one if and only if collision
-was detected with the simplified shape. It is in fact logical AND using
-operator&&() - the collision is initially detected on first (simplified) shape
-and then on the other:
+was detected with the simplified shape. It is in fact logical AND using the
+`&&` operator -- the collision is initially detected on first (simplified)
+shape and then on the other:
 @code
 Shapes::Sphere3D sphere;
 Shapes::Box3D box;
@@ -111,7 +111,7 @@ Shapes::Composition3D composition = simplified && (sphere || box);
 @section shapes-collisions Detecting shape collisions
 
 %Shape pairs which have collision occurence detection implemented can be tested
-for collision using operator%(). The operator returns boolean describing
+for collision using the `%` operator. The operator returns boolean describing
 whether the collision happened or not. Example:
 @code
 Shapes::Point3D point;
@@ -123,12 +123,12 @@ bool collide = point % sphere;
 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 `operator/()`, which returns @ref Collision
-object. Note that unlike with `operator%()` mentioned above, this operation is
-not commutative. See @ref Collision class documentation for more information
-about the returned data. Example:
+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:
 @code
-Shapes::Collision3D c = point/sphere;
+const Shapes::Collision3D c = point/sphere;
 if(c) {
     Vector3 translation = c.separationNormal()*c.separationDistance();
     // translate point by translation...
@@ -137,15 +137,37 @@ if(c) {
 
 @section shapes-scenegraph Integration with scene graph
 
-%Shape can be attached to object in the scene using Shapes::Shape feature and
-then used for collision detection. You can also use DebugTools::ShapeRenderer
-to visualize the shape for debugging purposes.
+%Shape can be attached to object in the scene using @ref Shapes::Shape feature.
+In conjunction with @ref Shapes::ShapeGroup you can use
+@ref Shapes::Shape::collides() and @ref Shapes::Shape::collision() similarly to
+the `%` and `/` operators above. Please note that the shape group caches the
+absolute transformations of all shapes and thus you need to explicitly call
+@ref Shapes::ShapeGroup::setClean() before computing the collisions if you did
+any modifications to the objects in the scene.
+
+Scenegraph-flavored equivalent to the above code:
 @code
-Object3D object;
-auto shape = Shapes::Shape<Shapes::Sphere3D>(object, {{}, 23.0f});
+Shapes::ShapeGroup3D shapes;
+Object3D& a;
+auto aShape = new Shapes::Shape<Shapes::Sphere3D>(a, {{}, 23.0f}, &shapes);
+
+Object3D& b;
+auto bShape = new Shapes::Shape<Shapes::Point3D>(b, {{1.0f, 0.2f, 3.0f}}, &shapes);
+
+// Translate point so the objects no longer collide
+shapes.setClean();
+if(aShape->collides(*bShape)) {
+    const Shapes::Collision3D c = aShape->collision(*bShape);
+    b.translate(c.separationNormal()*c.separationDistance());
+}
 @endcode
 
-See also @ref scenegraph for introduction.
+There is also @ref Shapes::ShapeGroup::firstCollision() function which returns
+arbitrary first collision for given shape in whole group (or `nullptr`, if
+there isn't any collision).
+
+You can also use @ref DebugTools::ShapeRenderer to visualize the shapes for
+debugging purposes. See also @ref scenegraph for introduction.
 
 -   Previous page: @ref scenegraph
 -   Next page: @ref debug-tools

src/Magnum/Shapes/AbstractShape.h

@@ -26,7 +26,7 @@
 */
 
 /** @file
- * @brief Class Magnum::Shapes::AbstractShape, typedef Magnum::Shapes::AbstractShape2D, Magnum::Shapes::AbstractShape3D
+ * @brief Class @ref Magnum::Shapes::AbstractShape, typedef @ref Magnum::Shapes::AbstractShape2D, @ref Magnum::Shapes::AbstractShape3D
  */
 
 #include "Magnum/Magnum.h"
@@ -46,9 +46,9 @@ namespace Implementation {
 /**
 @brief Base class for object shapes
 
-This class is not directly instantiable, see Shape instead. See @ref shapes for
-brief introduction.
-@see AbstractShape2D, AbstractShape3D
+This class is not directly instantiable, use @ref Shape instead. See
+@ref shapes for brief introduction.
+@see @ref AbstractShape2D, @ref AbstractShape3D
 */
 template<UnsignedInt dimensions> class MAGNUM_SHAPES_EXPORT AbstractShape: public SceneGraph::AbstractGroupedFeature<dimensions, AbstractShape<dimensions>, Float> {
     friend const Implementation::AbstractShape<dimensions>& Implementation::getAbstractShape<>(const AbstractShape<dimensions>&);
@@ -90,9 +90,7 @@ template<UnsignedInt dimensions> class MAGNUM_SHAPES_EXPORT AbstractShape: publi
         ShapeGroup<dimensions>* group();
         const ShapeGroup<dimensions>* group() const; /**< @overload */
 
-        /**
-         * @brief Shape type
-         */
+        /** @brief Shape type */
         Type type() const;
 
         /**

src/Magnum/Shapes/AxisAlignedBox.h

@@ -26,7 +26,7 @@
 */
 
 /** @file
- * @brief Class Magnum::Shapes::AxisAlignedBox, typedef Magnum::Shapes::AxisAlignedBox2D, Magnum::Shapes.:AxisAlignedBox3D
+ * @brief Class @ref Magnum::Shapes::AxisAlignedBox, typedef @ref Magnum::Shapes::AxisAlignedBox2D, @ref Magnum::Shapes.:AxisAlignedBox3D
  */
 
 #include "Magnum/DimensionTraits.h"
@@ -40,7 +40,7 @@ namespace Magnum { namespace Shapes {
 @brief Axis-aligned box
 
 See @ref shapes for brief introduction.
-@see AxisAlignedBox2D, AxisAlignedBox3D
+@see @ref AxisAlignedBox2D, @ref AxisAlignedBox3D
 @todo Assert for rotation
 */
 template<UnsignedInt dimensions> class MAGNUM_SHAPES_EXPORT AxisAlignedBox {

src/Magnum/Shapes/Box.h

@@ -26,7 +26,7 @@
 */
 
 /** @file
- * @brief Class Magnum::Shapes::Box, typedef Magnum::Shapes::Box2D, Magnum::Shapes::Box3D
+ * @brief Class @ref Magnum::Shapes::Box, typedef @ref Magnum::Shapes::Box2D, @ref Magnum::Shapes::Box3D
  */
 
 #include "Magnum/DimensionTraits.h"
@@ -41,8 +41,8 @@ namespace Magnum { namespace Shapes {
 
 Unit-size means that half extents are equal to 1, equivalent to e.g. sphere
 radius. See @ref shapes for brief introduction.
+@see @ref Box2D, @ref Box3D
 @todo Use quat + position + size instead?
-@see Box2D, Box3D
 @todo Assert for skew
 */
 template<UnsignedInt dimensions> class MAGNUM_SHAPES_EXPORT Box {

src/Magnum/Shapes/Capsule.h

@@ -26,7 +26,7 @@
 */
 
 /** @file
- * @brief Class Magnum::Shapes::Capsule, typedef Magnum::Shapes::Capsule2D, Magnum::Shapes::Capsule3D
+ * @brief Class @ref Magnum::Shapes::Capsule, typedef @ref Magnum::Shapes::Capsule2D, @ref Magnum::Shapes::Capsule3D
  */
 
 #include "Magnum/DimensionTraits.h"
@@ -41,7 +41,7 @@ namespace Magnum { namespace Shapes {
 
 Unlike other elements the capsule expects uniform scaling. See @ref shapes for
 brief introduction.
-@see Capsule2D, Capsule3D, Cylinder
+@see @ref Capsule2D, @ref Capsule3D, @ref Cylinder
 @todo Store the radius as squared value to avoid sqrt/pow? Will complicate
     collision detection with sphere.
 */

src/Magnum/Shapes/Collision.h

@@ -26,7 +26,7 @@
 */
 
 /** @file
- * @brief Class @ref Magnum::Shapes::Collision
+ * @brief Class @ref Magnum::Shapes::Collision, typedef @ref Magnum::Shapes::Collision2D, @ref Magnum::Shapes::Collision3D
  */
 
 #include "Magnum/DimensionTraits.h"

src/Magnum/Shapes/Composition.h

@@ -26,7 +26,7 @@
 */
 
 /** @file
- * @brief Class Magnum::Shapes::Composition, enum Magnum::Shapes::CompositionOperation
+ * @brief Class @ref Magnum::Shapes::Composition, typedef @ref Magnum::Shapes::Composition2D, @ref Magnum::Shapes::Composition3D, enum @ref Magnum::Shapes::CompositionOperation
  */
 
 #include <type_traits>
@@ -95,7 +95,7 @@ template<UnsignedInt dimensions> class MAGNUM_SHAPES_EXPORT Composition {
         /**
          * @brief Default constructor
          *
-         * Creates empty hierarchy.
+         * Creates empty composition.
          */
         explicit Composition() {}
 
@@ -187,10 +187,10 @@ template<UnsignedInt dimensions> class MAGNUM_SHAPES_EXPORT Composition {
         Containers::Array<Node> _nodes;
 };
 
-/** @brief Two-dimensional shape hierarchy */
+/** @brief Two-dimensional shape composition */
 typedef Composition<2> Composition2D;
 
-/** @brief Three-dimensional shape hierarchy */
+/** @brief Three-dimensional shape composition */
 typedef Composition<3> Composition3D;
 
 #ifdef DOXYGEN_GENERATING_OUTPUT
@@ -199,7 +199,7 @@ template<UnsignedInt dimensions> Debug operator<<(Debug debug, typename Composit
 #endif
 
 /** @relates Composition
-@brief Collision of shape with Composition
+@brief Collision of shape with @ref Composition
 */
 #ifdef DOXYGEN_GENERATING_OUTPUT
 template<UnsignedInt dimensions, class T> inline bool operator%(const T& a, const Composition<dimensions>& b) {

src/Magnum/Shapes/Cylinder.h

@@ -26,7 +26,7 @@
 */
 
 /** @file
- * @brief Class Magnum::Shapes::Cylinder, typedef Magnum::Shapes::Cylinder2D, Magnum::Shapes::Cylinder3D
+ * @brief Class @ref Magnum::Shapes::Cylinder, typedef @ref Magnum::Shapes::Cylinder2D, @ref Magnum::Shapes::Cylinder3D
  */
 
 #include "Magnum/DimensionTraits.h"

src/Magnum/Shapes/Line.h

@@ -26,7 +26,7 @@
 */
 
 /** @file
- * @brief Class Magnum::Shapes::Line, typedef Magnum::Shapes::Line2D, Magnum::Shapes::Line3D
+ * @brief Class @ref Magnum::Shapes::Line, typedef @ref Magnum::Shapes::Line2D, @ref Magnum::Shapes::Line3D
  */
 
 #include "Magnum/DimensionTraits.h"
@@ -39,8 +39,8 @@ namespace Magnum { namespace Shapes {
 @brief Infinite line, defined by two points
 
 See @ref shapes for brief introduction.
-@see Line2D, Line3D
-@todo collision detection of two Line2D
+@see @ref Line2D, @ref Line3D
+@todo collision detection of two @ref Line2D
 */
 template<UnsignedInt dimensions> class MAGNUM_SHAPES_EXPORT Line {
     public:

src/Magnum/Shapes/LineSegment.h

@@ -26,7 +26,7 @@
 */
 
 /** @file
- * @brief Class Magnum::Shapes::LineSegment, typedef Magnum::Shapes::LineSegment2D, Magnum::Shapes::LineSegment3D
+ * @brief Class @ref Magnum::Shapes::LineSegment, typedef @ref Magnum::Shapes::LineSegment2D, @ref Magnum::Shapes::LineSegment3D
  */
 
 #include "Magnum/Shapes/Line.h"
@@ -37,7 +37,7 @@ namespace Magnum { namespace Shapes {
 @brief %Line segment, defined by starting and ending point
 
 See @ref shapes for brief introduction.
-@see LineSegment2D, LineSegment3D
+@see @ref LineSegment2D, @ref LineSegment3D
 */
 template<UnsignedInt dimensions> class LineSegment: public Line<dimensions> {
     public:

src/Magnum/Shapes/Plane.h

@@ -26,7 +26,7 @@
 */
 
 /** @file
- * @brief Class Magnum::Shapes::Plane
+ * @brief Class @ref Magnum::Shapes::Plane
  */
 
 #include "Magnum/Magnum.h"

src/Magnum/Shapes/Point.h

@@ -26,7 +26,7 @@
 */
 
 /** @file
- * @brief Class Magnum::Shapes::Point, typedef Magnum::Shapes::Point2D, Magnum::Shapes::Point3D
+ * @brief Class @ref Magnum::Shapes::Point, typedef @ref Magnum::Shapes::Point2D, @ref Magnum::Shapes::Point3D
  */
 
 #include "Magnum/DimensionTraits.h"
@@ -39,7 +39,7 @@ namespace Magnum { namespace Shapes {
 @brief %Point
 
 See @ref shapes for brief introduction.
-@see Point2D, Point3D
+@see @ref Point2D, @ref Point3D
 */
 template<UnsignedInt dimensions> class MAGNUM_SHAPES_EXPORT Point {
     public:

src/Magnum/Shapes/Shape.h

@@ -26,7 +26,7 @@
 */
 
 /** @file
- * @brief Class Magnum::Shapes::Shape
+ * @brief Class @ref Magnum::Shapes::Shape
  */
 
 #include "Magnum/Shapes/AbstractShape.h"
@@ -43,16 +43,17 @@ namespace Implementation {
 @brief Object shape
 
 Adds shape for collision detection to object. Each %Shape is part of
-some ShapeGroup, which essentially maintains a set of objects which can
+some @ref ShapeGroup, which essentially maintains a set of objects which can
 collide with each other. See @ref shapes for brief introduction.
 
-The shape contains original shape with relative transformation under shape()
-and also caches a shape with absolute transformation under transformedShape(),
-which can be used for collision detection. To conveniently use collision
-detection among many object, you need to add the shape to ShapeGroup, which
-then provides collision detection for given group of shapes. You can also use
-ShapeGroup::add() and ShapeGroup::remove() later to manage e.g. collision
-islands.
+The shape contains original shape with relative transformation under
+@ref shape() and also caches a shape with absolute transformation under
+@ref transformedShape(), which can be used for collision detection. To
+conveniently use collision detection among many objects, you need to add the
+shape to @ref ShapeGroup, which then provides collision detection for given
+group of shapes using either @ref collides(), @ref collision() or
+@ref ShapeGroup::firstCollision(). You can also use @ref ShapeGroup::add() and
+@ref ShapeGroup::remove() later to manage e.g. collision islands.
 @code
 Shapes::ShapeGroup3D shapes;
 
@@ -62,8 +63,8 @@ auto shape = new Shapes::Shape<Shapes::Sphere3D>(object, {{}, 0.75f}, &shapes);
 Shapes::AbstractShape3D* firstCollision = shapes.firstCollision(shape);
 @endcode
 
-@see @ref scenegraph, ShapeGroup2D, ShapeGroup3D,
-    DebugTools::ShapeRenderer
+@see @ref scenegraph, @ref ShapeGroup2D, @ref ShapeGroup3D,
+    @ref DebugTools::ShapeRenderer
 */
 template<class T> class Shape: public AbstractShape<T::Dimensions> {
     friend struct Implementation::ShapeHelper<T>;

src/Magnum/Shapes/ShapeGroup.h

@@ -26,7 +26,7 @@
 */
 
 /** @file
- * @brief Class Magnum::Shapes::ShapeGroup, typedef Magnum::Shapes::ShapeGroup2D, Magnum::Shapes::ShapeGroup3D
+ * @brief Class @ref Magnum::Shapes::ShapeGroup, typedef @ref Magnum::Shapes::ShapeGroup2D, @ref Magnum::Shapes::ShapeGroup3D
  */
 
 #include <vector>
@@ -40,8 +40,8 @@ namespace Magnum { namespace Shapes {
 /**
 @brief Group of shapes
 
-See Shape for more information. See @ref shapes for brief introduction.
-@see @ref scenegraph, ShapeGroup2D, ShapeGroup3D
+See @ref Shape for more information. See @ref shapes for brief introduction.
+@see @ref scenegraph, @ref ShapeGroup2D, @ref ShapeGroup3D
 */
 template<UnsignedInt dimensions> class MAGNUM_SHAPES_EXPORT ShapeGroup: public SceneGraph::FeatureGroup<dimensions, AbstractShape<dimensions>, Float> {
     friend class AbstractShape<dimensions>;
@@ -66,8 +66,7 @@ template<UnsignedInt dimensions> class MAGNUM_SHAPES_EXPORT ShapeGroup: public S
          * If some body in the group changes its transformation, it sets dirty
          * status also on the group to indicate that the body and maybe also
          * group state needs to be cleaned before computing collisions.
-         *
-         * @see setClean()
+         * @see @ref setClean()
          */
         void setDirty() { dirty = true; }
 
@@ -83,7 +82,7 @@ template<UnsignedInt dimensions> class MAGNUM_SHAPES_EXPORT ShapeGroup: public S
          * @brief First collision of given shape with other shapes in the group
          *
          * Returns first shape colliding with given one. If there aren't any
-         * collisions, returns `nullptr`. Calls setClean() before the
+         * collisions, returns `nullptr`. Calls @ref setClean() before the
          * operation.
          */
         AbstractShape<dimensions>* firstCollision(const AbstractShape<dimensions>& shape);
@@ -93,18 +92,18 @@ template<UnsignedInt dimensions> class MAGNUM_SHAPES_EXPORT ShapeGroup: public S
 };
 
 /**
-@brief Group of two-dimensional shaped objects
+@brief Group of two-dimensional shapes
 
-See Shape for more information.
-@see ShapeGroup3D
+See @ref Shape for more information.
+@see @ref ShapeGroup3D
 */
 typedef ShapeGroup<2> ShapeGroup2D;
 
 /**
-@brief Group of three-dimensional shaped objects
+@brief Group of three-dimensional shapes
 
-See Shape for more information.
-@see ShapeGroup2D
+See @ref Shape for more information.
+@see @ref ShapeGroup2D
 */
 typedef ShapeGroup<3> ShapeGroup3D;
 

src/Magnum/Shapes/Shapes.h

@@ -26,7 +26,7 @@
 */
 
 /** @file
- * @brief Forward declarations for Magnum::Shapes namespace
+ * @brief Forward declarations for @ref Magnum::Shapes namespace
  */
 
 #include "Magnum/Types.h"

src/Magnum/Shapes/Sphere.h

@@ -26,7 +26,7 @@
 */
 
 /** @file
- * @brief Class Magnum::Shapes::Sphere, typedef Magnum::Shapes::Sphere2D, Magnum::Shapes::Sphere3D
+ * @brief Class @ref Magnum::Shapes::Sphere, typedef @ref Magnum::Shapes::Sphere2D, @ref Magnum::Shapes::Sphere3D
  */
 
 #include "Magnum/DimensionTraits.h"
@@ -42,7 +42,7 @@ namespace Magnum { namespace Shapes {
 
 Unlike other elements the sphere expects uniform scaling. See @ref shapes for
 brief introduction.
-@see Sphere2D, Sphere3D
+@see @ref Sphere2D, @ref Sphere3D
 @todo Store the radius as squared value to avoid sqrt/pow? Will complicate
     collision detection with another sphere.
 */