From 30809a86f3b920d2504c2da1d3e12e5f52a58b70 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Wed, 12 Mar 2014 17:36:42 +0100 Subject: [PATCH] Shapes: updated and cleaned up the documentation. --- doc/shapes.dox | 58 ++++++++++++++++++++---------- src/Magnum/Shapes/AbstractShape.h | 12 +++---- src/Magnum/Shapes/AxisAlignedBox.h | 4 +-- src/Magnum/Shapes/Box.h | 4 +-- src/Magnum/Shapes/Capsule.h | 4 +-- src/Magnum/Shapes/Collision.h | 2 +- src/Magnum/Shapes/Composition.h | 10 +++--- src/Magnum/Shapes/Cylinder.h | 2 +- src/Magnum/Shapes/Line.h | 6 ++-- src/Magnum/Shapes/LineSegment.h | 4 +-- src/Magnum/Shapes/Plane.h | 2 +- src/Magnum/Shapes/Point.h | 4 +-- src/Magnum/Shapes/Shape.h | 23 ++++++------ src/Magnum/Shapes/ShapeGroup.h | 23 ++++++------ src/Magnum/Shapes/Shapes.h | 2 +- src/Magnum/Shapes/Sphere.h | 4 +-- 16 files changed, 92 insertions(+), 72 deletions(-) diff --git a/doc/shapes.dox b/doc/shapes.dox index 2da04df93..b52c0ed0b 100644 --- a/doc/shapes.dox +++ b/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(object, {{}, 23.0f}); +Shapes::ShapeGroup3D shapes; +Object3D& a; +auto aShape = new Shapes::Shape(a, {{}, 23.0f}, &shapes); + +Object3D& b; +auto bShape = new Shapes::Shape(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 diff --git a/src/Magnum/Shapes/AbstractShape.h b/src/Magnum/Shapes/AbstractShape.h index fdcb3a75c..50c1c5303 100644 --- a/src/Magnum/Shapes/AbstractShape.h +++ b/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 class MAGNUM_SHAPES_EXPORT AbstractShape: public SceneGraph::AbstractGroupedFeature, Float> { friend const Implementation::AbstractShape& Implementation::getAbstractShape<>(const AbstractShape&); @@ -90,9 +90,7 @@ template class MAGNUM_SHAPES_EXPORT AbstractShape: publi ShapeGroup* group(); const ShapeGroup* group() const; /**< @overload */ - /** - * @brief Shape type - */ + /** @brief Shape type */ Type type() const; /** diff --git a/src/Magnum/Shapes/AxisAlignedBox.h b/src/Magnum/Shapes/AxisAlignedBox.h index 900af0669..bb2d1076e 100644 --- a/src/Magnum/Shapes/AxisAlignedBox.h +++ b/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 class MAGNUM_SHAPES_EXPORT AxisAlignedBox { diff --git a/src/Magnum/Shapes/Box.h b/src/Magnum/Shapes/Box.h index c83822700..e6b785cd6 100644 --- a/src/Magnum/Shapes/Box.h +++ b/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 class MAGNUM_SHAPES_EXPORT Box { diff --git a/src/Magnum/Shapes/Capsule.h b/src/Magnum/Shapes/Capsule.h index 42556e019..e760327fc 100644 --- a/src/Magnum/Shapes/Capsule.h +++ b/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. */ diff --git a/src/Magnum/Shapes/Collision.h b/src/Magnum/Shapes/Collision.h index 0ee1528ff..74f2f9d88 100644 --- a/src/Magnum/Shapes/Collision.h +++ b/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" diff --git a/src/Magnum/Shapes/Composition.h b/src/Magnum/Shapes/Composition.h index 1583971e1..a81fa02ad 100644 --- a/src/Magnum/Shapes/Composition.h +++ b/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 @@ -95,7 +95,7 @@ template class MAGNUM_SHAPES_EXPORT Composition { /** * @brief Default constructor * - * Creates empty hierarchy. + * Creates empty composition. */ explicit Composition() {} @@ -187,10 +187,10 @@ template class MAGNUM_SHAPES_EXPORT Composition { Containers::Array _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 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 inline bool operator%(const T& a, const Composition& b) { diff --git a/src/Magnum/Shapes/Cylinder.h b/src/Magnum/Shapes/Cylinder.h index 6730c8e0b..04a311a71 100644 --- a/src/Magnum/Shapes/Cylinder.h +++ 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" diff --git a/src/Magnum/Shapes/Line.h b/src/Magnum/Shapes/Line.h index da4d98bf8..553beec0c 100644 --- a/src/Magnum/Shapes/Line.h +++ b/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 class MAGNUM_SHAPES_EXPORT Line { public: diff --git a/src/Magnum/Shapes/LineSegment.h b/src/Magnum/Shapes/LineSegment.h index 6a27e6712..da20b31b5 100644 --- a/src/Magnum/Shapes/LineSegment.h +++ b/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 class LineSegment: public Line { public: diff --git a/src/Magnum/Shapes/Plane.h b/src/Magnum/Shapes/Plane.h index 8cac28180..70d6ec18c 100644 --- a/src/Magnum/Shapes/Plane.h +++ b/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" diff --git a/src/Magnum/Shapes/Point.h b/src/Magnum/Shapes/Point.h index b0c6790f6..b2358ade3 100644 --- a/src/Magnum/Shapes/Point.h +++ b/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 class MAGNUM_SHAPES_EXPORT Point { public: diff --git a/src/Magnum/Shapes/Shape.h b/src/Magnum/Shapes/Shape.h index e1c70e8ed..dafa95226 100644 --- a/src/Magnum/Shapes/Shape.h +++ b/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(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 Shape: public AbstractShape { friend struct Implementation::ShapeHelper; diff --git a/src/Magnum/Shapes/ShapeGroup.h b/src/Magnum/Shapes/ShapeGroup.h index 0b8295a4d..83ca485d9 100644 --- a/src/Magnum/Shapes/ShapeGroup.h +++ b/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 @@ -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 class MAGNUM_SHAPES_EXPORT ShapeGroup: public SceneGraph::FeatureGroup, Float> { friend class AbstractShape; @@ -66,8 +66,7 @@ template 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 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* firstCollision(const AbstractShape& shape); @@ -93,18 +92,18 @@ template 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; diff --git a/src/Magnum/Shapes/Shapes.h b/src/Magnum/Shapes/Shapes.h index 5773f0aac..0c5382b09 100644 --- a/src/Magnum/Shapes/Shapes.h +++ b/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" diff --git a/src/Magnum/Shapes/Sphere.h b/src/Magnum/Shapes/Sphere.h index 42960ca66..0b02115d8 100644 --- a/src/Magnum/Shapes/Sphere.h +++ b/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. */