diff --git a/doc/coding-style.dox b/doc/coding-style.dox index 81c6a7a10..1e0e96b66 100644 --- a/doc/coding-style.dox +++ b/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 diff --git a/doc/scenegraph.dox b/doc/scenegraph.dox index 3ea52abf2..4c478397b 100644 --- a/doc/scenegraph.dox +++ b/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> Scene3D; typedef SceneGraph::Object> 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 diff --git a/src/Context.cpp b/src/Context.cpp index d931b643a..120538853 100644 --- a/src/Context.cpp +++ b/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::extensions(Version version) { #define _extension(prefix, vendor, extension) \ diff --git a/src/Magnum.h b/src/Magnum.h index aa97045c8..8d74ce976 100644 --- a/src/Magnum.h +++ b/src/Magnum.h @@ -54,18 +54,20 @@ namespace Corrade { } namespace Magnum { - namespace Math { - template class Vector2; - template class Vector3; - template class Vector4; - template class Point2D; - template class Point3D; - template class Matrix3; - template class Matrix4; - - template constexpr T deg(T value); - template constexpr T rad(T value); - } + +namespace Math { + template class Vector2; + template class Vector3; + template class Vector4; + template class Point2D; + template class Point3D; + template class Matrix3; + template class Matrix4; + + template constexpr T deg(T value); + template constexpr T rad(T value); + template struct Constants; +} /* Bring debugging facility from Corrade::Utility namespace */ using Corrade::Utility::Debug; @@ -93,6 +95,10 @@ typedef Math::Matrix3 Matrix3; /** @brief 4x4 floating-point matrix */ typedef Math::Matrix4 Matrix4; +/** @brief Floating-point constants */ +/* Using float instead of GLfloat to not break KDevelop autocompletion */ +typedef Math::Constants Constants; + /* Copying angle converters from Math namespace */ using Math::deg; using Math::rad; @@ -121,14 +127,16 @@ template 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 class Image; diff --git a/src/Math/Constants.h b/src/Math/Constants.h index a4c8a50e5..0b27ae947 100644 --- a/src/Math/Constants.h +++ b/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 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 inline constexpr T deg(T value) { return value*Constants::pi()/180; } diff --git a/src/Math/MathTypeTraits.h b/src/Math/MathTypeTraits.h index 742b728ac..1301b6685 100644 --- a/src/Math/MathTypeTraits.h +++ b/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 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 diff --git a/src/Math/Matrix3.h b/src/Math/Matrix3.h index ae8f3a6a7..1d96ebbbb 100644 --- a/src/Math/Matrix3.h +++ b/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 Matrix3: public Matrix<3, T> { diff --git a/src/Math/Matrix4.h b/src/Math/Matrix4.h index 25df2928b..4a7a7ef4d 100644 --- a/src/Math/Matrix4.h +++ b/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 diff --git a/src/Math/Point2D.h b/src/Math/Point2D.h index 76a775b89..f26552d77 100644 --- a/src/Math/Point2D.h +++ b/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 Point2D: public Vector3 { diff --git a/src/Math/Point3D.h b/src/Math/Point3D.h index 432ea5c0d..339822217 100644 --- a/src/Math/Point3D.h +++ b/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 Point3D: public Vector4 { diff --git a/src/Math/Vector2.h b/src/Math/Vector2.h index b9503b14d..61534e2a8 100644 --- a/src/Math/Vector2.h +++ b/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 Vector2: public Vector<2, T> { diff --git a/src/Math/Vector3.h b/src/Math/Vector3.h index f320272e9..84ff16050 100644 --- a/src/Math/Vector3.h +++ b/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 Vector3: public Vector<3, T> { diff --git a/src/Math/Vector4.h b/src/Math/Vector4.h index be28aa83f..94a680fac 100644 --- a/src/Math/Vector4.h +++ b/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 Vector4: public Vector<4, T> { diff --git a/src/Physics/Capsule.cpp b/src/Physics/Capsule.cpp index 0c9a8882e..422bd12bb 100644 --- a/src/Physics/Capsule.cpp +++ b/src/Physics/Capsule.cpp @@ -30,7 +30,7 @@ namespace Magnum { namespace Physics { template void Capsule::applyTransformation(const typename DimensionTraits::MatrixType& transformation) { _transformedA = (transformation*typename DimensionTraits::PointType(_a)).vector(); _transformedB = (transformation*typename DimensionTraits::PointType(_b)).vector(); - float scaling = (transformation.rotationScaling()*typename DimensionTraits::VectorType(1/Math::Constants::sqrt3())).length(); + float scaling = (transformation.rotationScaling()*typename DimensionTraits::VectorType(1/Constants::sqrt3())).length(); _transformedRadius = scaling*_radius; } diff --git a/src/Physics/Sphere.cpp b/src/Physics/Sphere.cpp index 91caac41d..94b971b3e 100644 --- a/src/Physics/Sphere.cpp +++ b/src/Physics/Sphere.cpp @@ -31,11 +31,11 @@ namespace { template static typename DimensionTraits::VectorType unitVector(); template<> inline Vector2 unitVector<2>() { - return Vector2(1/Math::Constants::sqrt2()); + return Vector2(1/Constants::sqrt2()); } template<> inline Vector3 unitVector<3>() { - return Vector3(1/Math::Constants::sqrt3()); + return Vector3(1/Constants::sqrt3()); } } diff --git a/src/Physics/Test/CapsuleTest.cpp b/src/Physics/Test/CapsuleTest.cpp index 1d11fabc4..698778a90 100644 --- a/src/Physics/Test/CapsuleTest.cpp +++ b/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::sqrt3(), -Math::Constants::sqrt2(), 2.0f})); - CORRADE_COMPARE(capsule.transformedRadius(), Math::Constants::sqrt3()*7.0f); + capsule.applyTransformation(Matrix4::scaling({Constants::sqrt3(), -Constants::sqrt2(), 2.0f})); + CORRADE_COMPARE(capsule.transformedRadius(), Constants::sqrt3()*7.0f); } void CapsuleTest::collisionPoint() { diff --git a/src/Physics/Test/PlaneTest.cpp b/src/Physics/Test/PlaneTest.cpp index 75170f84c..294032de7 100644 --- a/src/Physics/Test/PlaneTest.cpp +++ b/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::sqrt2(), -Math::Constants::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::sqrt2(), 0, -Math::Constants::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::sqrt2(), -Math::Constants::sqrt2(), 0)); + CORRADE_COMPARE(plane.transformedNormal(), Vector3(Constants::sqrt2(), -Constants::sqrt2(), 0)); } void PlaneTest::collisionLine() { diff --git a/src/Physics/Test/SphereTest.cpp b/src/Physics/Test/SphereTest.cpp index 473be576c..f845b942e 100644 --- a/src/Physics/Test/SphereTest.cpp +++ b/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::sqrt3(), -Math::Constants::sqrt2(), 2.0f})); - CORRADE_COMPARE(sphere.transformedRadius(), Math::Constants::sqrt3()*7.0f); + sphere.applyTransformation(Matrix4::scaling({Constants::sqrt3(), -Constants::sqrt2(), 2.0f})); + CORRADE_COMPARE(sphere.transformedRadius(), Constants::sqrt3()*7.0f); } void SphereTest::collisionPoint() { diff --git a/src/Primitives/Capsule.cpp b/src/Primitives/Capsule.cpp index 266be7617..c7d6568c7 100644 --- a/src/Primitives/Capsule.cpp +++ b/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::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::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::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::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; diff --git a/src/Primitives/Cylinder.cpp b/src/Primitives/Cylinder.cpp index ebe23b35c..0d8460107 100644 --- a/src/Primitives/Cylinder.cpp +++ b/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::pi()/segments; + GLfloat segmentAngleIncrement = 2*Constants::pi()/segments; for(uint32_t i = 0; i != segments; ++i) { GLfloat segmentAngle = i*segmentAngleIncrement; diff --git a/src/Primitives/UVSphere.cpp b/src/Primitives/UVSphere.cpp index e82814264..920ac2dd3 100644 --- a/src/Primitives/UVSphere.cpp +++ b/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::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::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); diff --git a/src/SceneGraph/Object.h b/src/SceneGraph/Object.h index a9ea6f48c..a7a2a0b02 100644 --- a/src/SceneGraph/Object.h +++ b/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> Scene3D; +typedef SceneGraph::Object> 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().