Merge branch 'master' into compatibility

doc/coding-style.dox

@@ -21,6 +21,10 @@ needed. You are encouraged to read it first:
 Headers shouldn't have `using` declarations inside them (unless there is good
 excuse, see Magnum.h).
 
+Headers have `*.h` extension, @ref compilation-speedup-hpp "template implementation headers"
+have `*.hpp` extension (hinting that they are something between `*.h` and
+`*.cpp` files).
+
 @subsection cpp-format Code format
 
 @subsubsection cpp-naming Naming

doc/scenegraph.dox

@@ -47,7 +47,8 @@ needs, see @ref AbstractTransformation-subclassing
 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:
+%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;
@@ -193,6 +194,8 @@ 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.
 
+See @ref AbstractFeature-subclassing-caching for more information.
+
 @section scenegraph-construction-order Construction and destruction order
 
 There aren't any limitations and usage trade-offs of what you can and can't do

src/Context.cpp

@@ -33,6 +33,7 @@ using namespace std;
 
 namespace Magnum {
 
+#ifndef DOXYGEN_GENERATING_OUTPUT
 Debug operator<<(Debug debug, Version value) {
     switch(value) {
         #define _c(value, string) case Version::value: return debug << string;
@@ -56,6 +57,7 @@ Debug operator<<(Debug debug, Version value) {
 
     return debug << "Invalid";
 }
+#endif
 
 const std::vector<Extension>& Extension::extensions(Version version) {
     #define _extension(prefix, vendor, extension)                           \

src/Magnum.h

@@ -54,18 +54,20 @@ namespace Corrade {
 }
 
 namespace Magnum {
-    namespace Math {
-        template<class> class Vector2;
-        template<class> class Vector3;
-        template<class> class Vector4;
-        template<class> class Point2D;
-        template<class> class Point3D;
-        template<class> class Matrix3;
-        template<class> class Matrix4;
-
-        template<class T> constexpr T deg(T value);
-        template<class T> constexpr T rad(T value);
-    }
+
+namespace Math {
+    template<class> class Vector2;
+    template<class> class Vector3;
+    template<class> class Vector4;
+    template<class> class Point2D;
+    template<class> class Point3D;
+    template<class> class Matrix3;
+    template<class> class Matrix4;
+
+    template<class T> constexpr T deg(T value);
+    template<class T> constexpr T rad(T value);
+    template<class T> struct Constants;
+}
 
 /* Bring debugging facility from Corrade::Utility namespace */
 using Corrade::Utility::Debug;
@@ -93,6 +95,10 @@ typedef Math::Matrix3<GLfloat> Matrix3;
 /** @brief 4x4 floating-point matrix */
 typedef Math::Matrix4<GLfloat> Matrix4;
 
+/** @brief Floating-point constants */
+/* Using float instead of GLfloat to not break KDevelop autocompletion */
+typedef Math::Constants<float> Constants;
+
 /* Copying angle converters from Math namespace */
 using Math::deg;
 using Math::rad;
@@ -121,14 +127,16 @@ template<class = GLfloat> class Color4;
 enum class Version: GLint;
 #endif
 class Context;
-class Extension;
-
 class CubeMapTexture;
 
 #ifndef MAGNUM_TARGET_GLES
 class CubeMapTextureArray;
 #endif
 
+/* DebugMarker forward declaration is not needed */
+/* DimensionTraits forward declaration is not needed */
+
+class Extension;
 class Framebuffer;
 
 template<std::uint8_t> class Image;

src/Math/Constants.h

@@ -24,9 +24,10 @@ namespace Magnum { namespace Math {
 /**
 @brief Numeric constants
 
-@internal See MathTypeTraits class for implementation notes.
+@see Magnum::Constants
 */
 template<class T> struct Constants {
+    /* See MathTypeTraits for answer why these are functions and not constants. */
     #ifdef DOXYGEN_GENERATING_OUTPUT
     /**
      * @brief Pi
@@ -63,6 +64,8 @@ Usable for entering e.g. rotation:
 @code
 Matrix4::rotation(deg(30.0f), Vector3::yAxis());
 @endcode
+
+This function (and also rad()) is available also in Magnum namespace itself.
 @see Constants, rad()
  */
 template<class T> inline constexpr T deg(T value) { return value*Constants<T>::pi()/180; }

src/Math/MathTypeTraits.h

@@ -47,13 +47,15 @@ specialization for given types.
 This class and class methods are specialized only for types where it makes
 sense, it has empty implementation for unknown types or types which don't
 support given feature, thus forcing the compilation stop with an error.
-
-@internal The following values are implemented as inline functions, not as
-    static const variables, because the compiler will inline the return values
-    instead of referencing to static data and unlike static const variables
-    the functions can be overloaded, deleted and hidden.
 */
 template<class T> struct MathTypeTraits {
+    /*
+     * The following values are implemented as inline functions, not as
+     * static const variables, because the compiler will inline the return
+     * values instead of referencing to static data and unlike static const
+     * variables the functions can be overloaded, deleted and hidden.
+     */
+
     #ifdef DOXYGEN_GENERATING_OUTPUT
     /**
      * @brief Corresponding numeric type large at least as 32bit integer

src/Math/Matrix3.h

@@ -30,6 +30,7 @@ namespace Magnum { namespace Math {
 
 Provides functions for transformations in 2D. See Matrix4 for 3D
 transformations. See also @ref matrix-vector for brief introduction.
+@see Magnum::Matrix3
 @configurationvalueref{Magnum::Math::Matrix3}
 */
 template<class T> class Matrix3: public Matrix<3, T> {

src/Math/Matrix4.h

@@ -30,6 +30,7 @@ namespace Magnum { namespace Math {
 
 Provides functions for transformations in 3D. See Matrix3 for 2D
 transformations. See also @ref matrix-vector for brief introduction.
+@see Magnum::Matrix4
 @configurationvalueref{Magnum::Math::Matrix4}
 @todo Shearing
 @todo Reflection

src/Math/Point2D.h

@@ -29,7 +29,7 @@ namespace Magnum { namespace Math {
 
 Same as Vector3, except that constructors have default value for Z component
 set to one. See also @ref matrix-vector for brief introduction.
-@see Point3D
+@see Magnum::Point2D, Point3D
 @configurationvalueref{Magnum::Math::Point2D}
 */
 template<class T> class Point2D: public Vector3<T> {

src/Math/Point3D.h

@@ -29,7 +29,7 @@ namespace Magnum { namespace Math {
 
 Same as Vector4, except that constructors have default value for W component
 set to one. See also @ref matrix-vector for brief introduction.
-@see Point2D
+@see Magnum::Point3D, Point2D
 @configurationvalueref{Magnum::Math::Point3D}
 */
 template<class T> class Point3D: public Vector4<T> {

src/Math/Vector2.h

@@ -28,6 +28,7 @@ namespace Magnum { namespace Math {
 @tparam T   Data type
 
 See @ref matrix-vector for brief introduction.
+@see Magnum::Vector2
 @configurationvalueref{Magnum::Math::Vector2}
 */
 template<class T> class Vector2: public Vector<2, T> {

src/Math/Vector3.h

@@ -29,6 +29,7 @@ namespace Magnum { namespace Math {
 
 See @ref matrix-vector for brief introduction. See also Point2D for
 homogeneous two-dimensional coordinates.
+@see Magnum::Vector3
 @configurationvalueref{Magnum::Math::Vector3}
 */
 template<class T> class Vector3: public Vector<3, T> {

src/Math/Vector4.h

@@ -29,6 +29,7 @@ namespace Magnum { namespace Math {
 
 See @ref matrix-vector for brief introduction. See also Point3D for
 homogeneous three-dimensional coordinates.
+@see Magnum::Vector4
 @configurationvalueref{Magnum::Math::Vector4}
 */
 template<class T> class Vector4: public Vector<4, T> {

src/Physics/Capsule.cpp

@@ -30,7 +30,7 @@ namespace Magnum { namespace Physics {
 template<std::uint8_t dimensions> void Capsule<dimensions>::applyTransformation(const typename DimensionTraits<dimensions>::MatrixType& transformation) {
     _transformedA = (transformation*typename DimensionTraits<dimensions>::PointType(_a)).vector();
     _transformedB = (transformation*typename DimensionTraits<dimensions>::PointType(_b)).vector();
-    float scaling = (transformation.rotationScaling()*typename DimensionTraits<dimensions>::VectorType(1/Math::Constants<float>::sqrt3())).length();
+    float scaling = (transformation.rotationScaling()*typename DimensionTraits<dimensions>::VectorType(1/Constants::sqrt3())).length();
     _transformedRadius = scaling*_radius;
 }
 

src/Physics/Sphere.cpp

@@ -31,11 +31,11 @@ namespace {
     template<std::uint8_t dimensions> static typename DimensionTraits<dimensions>::VectorType unitVector();
 
     template<> inline Vector2 unitVector<2>() {
-        return Vector2(1/Math::Constants<float>::sqrt2());
+        return Vector2(1/Constants::sqrt2());
     }
 
     template<> inline Vector3 unitVector<3>() {
-        return Vector3(1/Math::Constants<float>::sqrt3());
+        return Vector3(1/Constants::sqrt3());
     }
 }
 

src/Physics/Test/CapsuleTest.cpp

@@ -38,8 +38,8 @@ void CapsuleTest::applyTransformation() {
     CORRADE_COMPARE(capsule.radius(), 7.0f);
 
     /* Apply average scaling to radius */
-    capsule.applyTransformation(Matrix4::scaling({Math::Constants<GLfloat>::sqrt3(), -Math::Constants<GLfloat>::sqrt2(), 2.0f}));
-    CORRADE_COMPARE(capsule.transformedRadius(), Math::Constants<GLfloat>::sqrt3()*7.0f);
+    capsule.applyTransformation(Matrix4::scaling({Constants::sqrt3(), -Constants::sqrt2(), 2.0f}));
+    CORRADE_COMPARE(capsule.transformedRadius(), Constants::sqrt3()*7.0f);
 }
 
 void CapsuleTest::collisionPoint() {

src/Physics/Test/PlaneTest.cpp

@@ -31,16 +31,16 @@ PlaneTest::PlaneTest() {
 }
 
 void PlaneTest::applyTransformation() {
-    Physics::Plane plane({1.0f, 2.0f, 3.0f}, {Math::Constants<float>::sqrt2(), -Math::Constants<float>::sqrt2(), 0});
+    Physics::Plane plane({1.0f, 2.0f, 3.0f}, {Constants::sqrt2(), -Constants::sqrt2(), 0});
 
     plane.applyTransformation(Matrix4::rotation(deg(90.0f), Vector3::xAxis()));
     CORRADE_COMPARE(plane.transformedPosition(), Vector3(1.0f, -3.0f, 2.0f));
-    CORRADE_COMPARE(plane.transformedNormal(), Vector3(Math::Constants<float>::sqrt2(), 0, -Math::Constants<float>::sqrt2()));
+    CORRADE_COMPARE(plane.transformedNormal(), Vector3(Constants::sqrt2(), 0, -Constants::sqrt2()));
 
     /* The normal should stay normalized */
     plane.applyTransformation(Matrix4::scaling({1.5f, 2.0f, 3.0f}));
     CORRADE_COMPARE(plane.transformedPosition(), Vector3(1.5f, 4.0f, 9.0f));
-    CORRADE_COMPARE(plane.transformedNormal(), Vector3(Math::Constants<float>::sqrt2(), -Math::Constants<float>::sqrt2(), 0));
+    CORRADE_COMPARE(plane.transformedNormal(), Vector3(Constants::sqrt2(), -Constants::sqrt2(), 0));
 }
 
 void PlaneTest::collisionLine() {

src/Physics/Test/SphereTest.cpp

@@ -45,8 +45,8 @@ void SphereTest::applyTransformation() {
     CORRADE_COMPARE(sphere.transformedRadius(), 14.0f);
 
     /* Apply average scaling to radius */
-    sphere.applyTransformation(Matrix4::scaling({Math::Constants<GLfloat>::sqrt3(), -Math::Constants<GLfloat>::sqrt2(), 2.0f}));
-    CORRADE_COMPARE(sphere.transformedRadius(), Math::Constants<GLfloat>::sqrt3()*7.0f);
+    sphere.applyTransformation(Matrix4::scaling({Constants::sqrt3(), -Constants::sqrt2(), 2.0f}));
+    CORRADE_COMPARE(sphere.transformedRadius(), Constants::sqrt3()*7.0f);
 }
 
 void SphereTest::collisionPoint() {

src/Primitives/Capsule.cpp

@@ -27,13 +27,13 @@ Capsule::Capsule(std::uint32_t hemisphereRings, std::uint32_t cylinderRings, std
 
     GLfloat height = 2.0f+length;
     GLfloat hemisphereTextureCoordsVIncrement = 1.0f/(hemisphereRings*height);
-    GLfloat hemisphereRingAngleIncrement = Math::Constants<GLfloat>::pi()/(2*hemisphereRings);
+    GLfloat hemisphereRingAngleIncrement = Constants::pi()/(2*hemisphereRings);
 
     /* Bottom cap vertex */
     capVertex(-height/2, -1.0f, 0.0f);
 
     /* Rings of bottom hemisphere */
-    hemisphereVertexRings(hemisphereRings-1, -length/2, -Math::Constants<GLfloat>::pi()/2+hemisphereRingAngleIncrement, hemisphereRingAngleIncrement, hemisphereTextureCoordsVIncrement, hemisphereTextureCoordsVIncrement);
+    hemisphereVertexRings(hemisphereRings-1, -length/2, -Constants::pi()/2+hemisphereRingAngleIncrement, hemisphereRingAngleIncrement, hemisphereTextureCoordsVIncrement, hemisphereTextureCoordsVIncrement);
 
     /* Rings of cylinder */
     cylinderVertexRings(cylinderRings+1, -length/2, length/cylinderRings, 1.0f/height, length/(cylinderRings*height));
@@ -61,7 +61,7 @@ void Capsule::capVertex(GLfloat y, GLfloat normalY, GLfloat textureCoordsV) {
 }
 
 void Capsule::hemisphereVertexRings(uint32_t count, GLfloat centerY, GLfloat startRingAngle, GLfloat ringAngleIncrement, GLfloat startTextureCoordsV, GLfloat textureCoordsVIncrement) {
-    GLfloat segmentAngleIncrement = 2*Math::Constants<GLfloat>::pi()/segments;
+    GLfloat segmentAngleIncrement = 2*Constants::pi()/segments;
     GLfloat x, y, z;
     for(uint32_t i = 0; i != count; ++i) {
         GLfloat ringAngle = startRingAngle + i*ringAngleIncrement;
@@ -87,7 +87,7 @@ void Capsule::hemisphereVertexRings(uint32_t count, GLfloat centerY, GLfloat sta
 }
 
 void Capsule::cylinderVertexRings(uint32_t count, GLfloat startY, GLfloat yIncrement, GLfloat startTextureCoordsV, GLfloat textureCoordsVIncrement) {
-    GLfloat segmentAngleIncrement = 2*Math::Constants<GLfloat>::pi()/segments;
+    GLfloat segmentAngleIncrement = 2*Constants::pi()/segments;
     for(uint32_t i = 0; i != count; ++i) {
         for(uint32_t j = 0; j != segments; ++j) {
             GLfloat segmentAngle = j*segmentAngleIncrement;

src/Primitives/Cylinder.cpp

@@ -49,7 +49,7 @@ Cylinder::Cylinder(uint32_t rings, uint32_t segments, GLfloat length, Flags flag
 }
 
 void Cylinder::capVertexRing(GLfloat y, GLfloat textureCoordsV, const Vector3& normal) {
-    GLfloat segmentAngleIncrement = 2*Math::Constants<GLfloat>::pi()/segments;
+    GLfloat segmentAngleIncrement = 2*Constants::pi()/segments;
 
     for(uint32_t i = 0; i != segments; ++i) {
         GLfloat segmentAngle = i*segmentAngleIncrement;

src/Primitives/UVSphere.cpp

@@ -27,13 +27,13 @@ UVSphere::UVSphere(uint32_t rings, uint32_t segments, TextureCoords textureCoord
     CORRADE_ASSERT(rings >= 2 && segments >= 3, "UVSphere must have at least two rings and three segments", );
 
     GLfloat textureCoordsVIncrement = 1.0f/rings;
-    GLfloat ringAngleIncrement = Math::Constants<GLfloat>::pi()/rings;
+    GLfloat ringAngleIncrement = Constants::pi()/rings;
 
     /* Bottom cap vertex */
     capVertex(-1.0f, -1.0f, 0.0f);
 
     /* Vertex rings */
-    hemisphereVertexRings(rings-1, 0.0f, -Math::Constants<GLfloat>::pi()/2+ringAngleIncrement, ringAngleIncrement, textureCoordsVIncrement, textureCoordsVIncrement);
+    hemisphereVertexRings(rings-1, 0.0f, -Constants::pi()/2+ringAngleIncrement, ringAngleIncrement, textureCoordsVIncrement, textureCoordsVIncrement);
 
     /* Top cap vertex */
     capVertex(1.0f, 1.0f, 1.0f);

src/SceneGraph/Object.h

@@ -49,6 +49,13 @@ Base of scene graph. Contains specific transformation implementation, takes
 care of parent/children relationship and contains features. See @ref scenegraph
 for introduction.
 
+Common usage is to typedef Object with desired transformation type to save
+unnecessary typing later, along with Scene and possibly other types, e.g.:
+@code
+typedef SceneGraph::Scene<SceneGraph::MatrixTransformation3D<>> Scene3D;
+typedef SceneGraph::Object<SceneGraph::MatrixTransformation3D<>> Object3D;
+@endcode
+
 Uses Corrade::Containers::LinkedList for parent/children relationship.
 Traversing through the list is done like in the following code. It is also
 possible to go in reverse order using lastChild() and previousSibling().