diff --git a/doc/snippets/MagnumMath.cpp b/doc/snippets/MagnumMath.cpp index f9d3d9a80..6f2349762 100644 --- a/doc/snippets/MagnumMath.cpp +++ b/doc/snippets/MagnumMath.cpp @@ -857,6 +857,37 @@ static_cast(startPoint); static_cast(endPoint); } +{ +/* [Dual-conversion] */ +Math::Dual floatingPoint{1.3f, 2.7f}; +Math::Dual integral{floatingPoint}; // {1, 2} +/* [Dual-conversion] */ +} + +{ +/* [div] */ +Int quotient, remainder; +std::tie(quotient, remainder) = Math::div(57, 6); // {9, 3} +/* [div] */ +} + +{ +/* [div-equivalent] */ +Int quotient = 57/6; +Int remainder = 57%6; +/* [div-equivalent] */ +static_cast(quotient); +static_cast(remainder); +} + +{ +Float value{}, min{}, max{}; +/* [clamp] */ +Math::min(Math::max(value, min), max) +/* [clamp] */ +; +} + { /* [Half-usage] */ using namespace Math::Literals; @@ -877,6 +908,44 @@ Debug{} << Math::Vector3{a}; // prints {16968, 48552, 15993} /* [Half-usage-vector] */ } +{ +Rad angle{}; +typedef Float T; +/* [Intersection-tanAngleSqPlusOne] */ +T tanAngleSqPlusOne = Math::pow<2>(Math::tan(angle*T(0.5))) + T(1); +/* [Intersection-tanAngleSqPlusOne] */ +static_cast(tanAngleSqPlusOne); +} + +{ +Rad angle{}; +typedef Float T; +/* [Intersection-sinAngle-tanAngle] */ +T sinAngle = Math::sin(angle*T(0.5)); +T tanAngle = Math::tan(angle*T(0.5)); +/* [Intersection-sinAngle-tanAngle] */ +static_cast(sinAngle); +static_cast(tanAngle); +} + +{ +Rad angle{}; +typedef Float T; +/* [Intersection-sinAngle-tanAngleSqPlusOne] */ +T sinAngle = Math::sin(angle*T(0.5)); +T tanAngleSqPlusOne = Math::pow<2>(Math::tan(angle*T(0.5))) + T(1); +/* [Intersection-sinAngle-tanAngleSqPlusOne] */ +static_cast(sinAngle); +static_cast(tanAngleSqPlusOne); +} + +{ +/* [Matrix-conversion] */ +Matrix2x2 floatingPoint{Vector2{1.3f, 2.7f}, Vector2{-15.0f, 7.0f}}; +Math::Matrix2x2 integral{floatingPoint}; // {{1, 2}, {-15, 7}} +/* [Matrix-conversion] */ +} + { /* [unpack-template-explicit] */ // Literal type is (signed) char, but we assumed unsigned char, a != 1.0f @@ -940,6 +1009,28 @@ auto filterArea = Range2Di::fromSize(center, Vector2i{1}).padded(filterRadius); static_cast(filterArea); } +{ +/* [Range-conversion] */ +Range2D floatingPoint{{1.3f, 2.7f}, {-15.0f, 7.0f}}; +Range2Di integral{floatingPoint}; // {{1, 2}, {-15, 7}} +/* [Range-conversion] */ +} + +{ +/* [RectangularMatrix-conversion] */ +Math::RectangularMatrix<4, 1, Float> floatingPoint{1.3f, 2.7f, -15.0f, 7.0f}; +Math::RectangularMatrix<4, 1, Byte> integral{floatingPoint}; // {1, 2, -15, 7} +/* [RectangularMatrix-conversion] */ +} + +{ +/* [RectangularMatrix-access] */ +Matrix4x3 m; +Float a = m[2][1]; +/* [RectangularMatrix-access] */ +static_cast(a); +} + { /* [StrictWeakOrdering] */ std::set mySet; @@ -949,4 +1040,69 @@ static_cast(myMap); static_cast(mySet); } +{ +/* [swizzle] */ +Vector4i original(-1, 2, 3, 4); + +auto vec = Math::swizzle<'w', '1', '0', 'x', 'y', 'z'>(original); + // vec == { 4, 1, 0, -1, 2, 3 } +/* [swizzle] */ +static_cast(vec); +} + +{ +Float a{}, b{}; +/* [TypeTraits-equalsZero] */ +Math::TypeTraits::equals(a, b); +Math::TypeTraits::equalsZero(a - b, + Math::max(Math::abs(a), Math::abs(b))); +/* [TypeTraits-equalsZero] */ +} + +{ +/* [Vector-conversion] */ +Vector4 floatingPoint{1.3f, 2.7f, -15.0f, 7.0f}; +Vector4i integral{floatingPoint}; // {1, 2, -15, 7} +/* [Vector-conversion] */ +} + +{ +Vector2 vec; +Float length{}; +/* [Vector-resized] */ +vec*(vec.lengthInverted()*length) // the parentheses are important +/* [Vector-resized] */ +; +} + +{ +/* [Vector2-xAxis] */ +Matrix3::translation(Vector2::xAxis(5.0f)); + // same as Matrix3::translation({5.0f, 0.0f}); +/* [Vector2-xAxis] */ +} + +{ +/* [Vector2-xScale] */ +Matrix3::scaling(Vector2::xScale(-2.0f)); + // same as Matrix3::scaling({-2.0f, 1.0f}); +/* [Vector2-xScale] */ +} + +{ +/* [Vector3-xAxis] */ +Matrix4::translation(Vector3::xAxis(5.0f)); + // same as Matrix4::translation({5.0f, 0.0f, 0.0f}); +Matrix4::rotation(30.0_degf, Vector3::xAxis()); + // same as Matrix4::rotation(30.0_degf, {1.0f, 0.0f, 0.0f}); +/* [Vector3-xAxis] */ +} + +{ +/* [Vector3-xScale] */ +Matrix4::scaling(Vector3::xScale(-2.0f)); + // same as Matrix4::scaling({-2.0f, 1.0f, 1.0f}); +/* [Vector3-xScale] */ +} + } diff --git a/src/Magnum/Math/Dual.h b/src/Magnum/Math/Dual.h index de03f041f..ac06f6766 100644 --- a/src/Magnum/Math/Dual.h +++ b/src/Magnum/Math/Dual.h @@ -104,11 +104,7 @@ template class Dual { * Performs only default casting on the values, no rounding or anything * else. Example usage: * - * @code{.cpp} - * Dual floatingPoint(1.3f, 2.7f); - * Dual integral(floatingPoint); - * // integral == {1, 2} - * @endcode + * @snippet MagnumMath.cpp Dual-conversion */ template constexpr explicit Dual(const Dual& other) noexcept: _real{T(other._real)}, _dual{T(other._dual)} {} diff --git a/src/Magnum/Math/Functions.h b/src/Magnum/Math/Functions.h index afd4af50f..d64e17652 100644 --- a/src/Magnum/Math/Functions.h +++ b/src/Magnum/Math/Functions.h @@ -106,17 +106,11 @@ template inline T exp(T exponent) { return std::exp(exponent); } Example usage: -@code{.cpp} -Int quotient, remainder; -std::tie(quotient, remainder) = Math::div(57, 6); // {9, 3} -@endcode +@snippet MagnumMath.cpp div Equivalent to the following, but possibly done in a single CPU instruction: -@code{.cpp} -Int quotient = 57/6; -Int remainder = 57%6; -@endcode +@snippet MagnumMath.cpp div-equivalent */ template inline std::pair div(Integral x, Integral y) { static_assert(std::is_integral{}, "Math::div(): not an integral type"); @@ -438,9 +432,7 @@ template inline std::pair minmax(const T(&array Values smaller than @p min are set to @p min, values larger than @p max are set to @p max. Equivalent to: -@code{.cpp} -Math::min(Math::max(value, min), max) -@endcode +@snippet MagnumMath.cpp clamp NaNs passed in @p value parameter are propagated. @see @ref min(), @ref max() diff --git a/src/Magnum/Math/Intersection.h b/src/Magnum/Math/Intersection.h index 8707a4fcd..a8ca655b8 100644 --- a/src/Magnum/Math/Intersection.h +++ b/src/Magnum/Math/Intersection.h @@ -236,11 +236,9 @@ template bool pointCone(const Vector3& point, const Vector3& cone @return @cpp true @ce if the point is inside the cone, @cpp false @ce otherwise -The @p tanAngleSqPlusOne parameter can be calculated as: +The @p tanAngleSqPlusOne parameter can be precomputed like this: -@code{.cpp} -Math::pow<2>(Math::tan(angle*T(0.5))) + T(1) -@endcode +@snippet MagnumMath.cpp Intersection-tanAngleSqPlusOne */ template bool pointCone(const Vector3& point, const Vector3& coneOrigin, const Vector3& coneNormal, T tanAngleSqPlusOne); @@ -269,9 +267,7 @@ template bool pointDoubleCone(const Vector3& point, const Vector3 The @p tanAngleSqPlusOne parameter can be precomputed like this: -@code{.cpp} -T tanAngleSqPlusOne = Math::pow<2>(Math::tan(angle*T(0.5))) + T(1); -@endcode +@snippet MagnumMath.cpp Intersection-tanAngleSqPlusOne */ template bool pointDoubleCone(const Vector3& point, const Vector3& coneOrigin, const Vector3& coneNormal, T tanAngleSqPlusOne); @@ -301,12 +297,9 @@ template bool sphereConeView(const Vector3& sphereCenter, T sphereRa Transforms the sphere center into cone space (using the cone view matrix) and performs sphere-cone intersection with the zero-origin -Z axis-aligned cone. -The @p sinAngle, @p cosAngle, @p tanAngle can be precomputed like this: +The @p sinAngle and @p tanAngle can be precomputed like this: -@code{.cpp} -T sinAngle = Math::sin(angle*T(0.5)); -T tanAngle = Math::tan(angle*T(0.5)); -@endcode +@snippet MagnumMath.cpp Intersection-sinAngle-tanAngle */ template bool sphereConeView(const Vector3& sphereCenter, T sphereRadius, const Matrix4& coneView, T sinAngle, T tanAngle); @@ -345,10 +338,7 @@ normal direction), and behind the plane, where the test is equivalent to testing whether the origin of the original cone intersects the sphere. The @p sinAngle and @p tanAngleSqPlusOne parameters can be precomputed like this: -@code{.cpp} -T sinAngle = Math::sin(angle*T(0.5)); -T tanAngleSqPlusOne = Math::pow<2>(Math::tan(angle*T(0.5))) + T(1); -@endcode +@snippet MagnumMath.cpp Intersection-sinAngle-tanAngleSqPlusOne */ template bool sphereCone(const Vector3& sphereCenter, T sphereRadius, const Vector3& coneOrigin, const Vector3& coneNormal, T sinAngle, T tanAngleSqPlusOne); @@ -392,9 +382,7 @@ cone's axis and are tested for intersection with the cone using The @p tanAngleSqPlusOne parameter can be precomputed like this: -@code{.cpp} -T tanAngleSqPlusOne = Math::pow<2>(Math::tan(angle*T(0.5))) + T(1); -@endcode +@snippet MagnumMath.cpp Intersection-tanAngleSqPlusOne */ template bool aabbCone(const Vector3& aabbCenter, const Vector3& aabbExtents, const Vector3& coneOrigin, const Vector3& coneNormal, T tanAngleSqPlusOne); @@ -422,11 +410,10 @@ template bool rangeCone(const Range3D& range, const Vector3& cone otherwise Converts the range into center/extents representation and passes it on to -@ref aabbCone(const Vector3&, const Vector3&, const Vector3&, const Vector3&, T) "aabbCone()". The @p tanAngleSqPlusOne parameter can be precomputed like this: +@ref aabbCone(const Vector3&, const Vector3&, const Vector3&, const Vector3&, T) "aabbCone()". +The @p tanAngleSqPlusOne parameter can be precomputed like this: -@code{.cpp} -T tanAngleSqPlusOne = Math::pow<2>(Math::tan(angle*T(0.5))) + T(1); -@endcode +@snippet MagnumMath.cpp Intersection-tanAngleSqPlusOne */ template bool rangeCone(const Range3D& range, const Vector3& coneOrigin, const Vector3& coneNormal, const T tanAngleSqPlusOne); diff --git a/src/Magnum/Math/Matrix.h b/src/Magnum/Math/Matrix.h index d19ebf392..c86f6fe88 100644 --- a/src/Magnum/Math/Matrix.h +++ b/src/Magnum/Math/Matrix.h @@ -108,12 +108,7 @@ template class Matrix: public RectangularMatrix floatingPoint({1.3f, 2.7f}, - * {-15.0f, 7.0f}); - * Matrix2x2 integral(floatingPoint); - * // integral == {{1, 2}, {-15, 7}} - * @endcode + * @snippet MagnumMath.cpp Matrix-conversion */ template constexpr explicit Matrix(const RectangularMatrix& other) noexcept: RectangularMatrix(other) {} diff --git a/src/Magnum/Math/Range.h b/src/Magnum/Math/Range.h index 43894f82b..4f2200151 100644 --- a/src/Magnum/Math/Range.h +++ b/src/Magnum/Math/Range.h @@ -134,10 +134,7 @@ template class Range { * Performs only default casting on the values, no rounding or * anything else. Example usage: * - * @code{.cpp} - * Range2D floatingPoint({1.3f, 2.7f}, {-15.0f, 7.0f}); - * Range2D integral(floatingPoint); // {{1, 2}, {-15, 7}} - * @endcode + * @snippet MagnumMath.cpp Range-conversion */ template constexpr explicit Range(const Range& other) noexcept: _min(other._min), _max(other._max) {} diff --git a/src/Magnum/Math/RectangularMatrix.h b/src/Magnum/Math/RectangularMatrix.h index 3279fd494..ed0dff6da 100644 --- a/src/Magnum/Math/RectangularMatrix.h +++ b/src/Magnum/Math/RectangularMatrix.h @@ -142,11 +142,7 @@ template class RectangularMatrix { * Performs only default casting on the values, no rounding or * anything else. Example usage: * - * @code{.cpp} - * RectangularMatrix<4, 1, Float> floatingPoint(1.3f, 2.7f, -15.0f, 7.0f); - * RectangularMatrix<4, 1, Byte> integral(floatingPoint); - * // integral == {1, 2, -15, 7} - * @endcode + * @snippet MagnumMath.cpp RectangularMatrix-conversion */ template constexpr explicit RectangularMatrix(const RectangularMatrix& other) noexcept: RectangularMatrix(typename Implementation::GenerateSequence::Type(), other) {} @@ -177,10 +173,7 @@ template class RectangularMatrix { * Particular elements can be accessed using @ref Vector::operator[](), * e.g.: * - * @code{.cpp} - * RectangularMatrix<4, 3, Float> m; - * Float a = m[2][1]; - * @endcode + * @snippet MagnumMath.cpp RectangularMatrix-access * * @see @ref row(), @ref data() */ diff --git a/src/Magnum/Math/Swizzle.h b/src/Magnum/Math/Swizzle.h index 3ca372373..1c71f6bca 100644 --- a/src/Magnum/Math/Swizzle.h +++ b/src/Magnum/Math/Swizzle.h @@ -62,16 +62,11 @@ namespace Implementation { } /** -@brief Swizzle Vector components +@brief Swizzle @ref Vector components Creates new vector from given components. Example: -@code{.cpp} -Vector4i original(-1, 2, 3, 4); - -auto vec = swizzle<'w', '1', '0', 'x', 'y', 'z'>(original); -// vec == { 4, 1, 0, -1, 2, 3 } -@endcode +@snippet MagnumMath.cpp swizzle You can use letters @cpp 'x' @ce, @cpp 'y' @ce, @cpp 'z' @ce, @cpp 'w' @ce and @cpp 'r' @ce, @cpp 'g' @ce, @cpp 'b' @ce, @cpp 'a' @ce for addressing diff --git a/src/Magnum/Math/TypeTraits.h b/src/Magnum/Math/TypeTraits.h index 3170d31a7..7ac1134b3 100644 --- a/src/Magnum/Math/TypeTraits.h +++ b/src/Magnum/Math/TypeTraits.h @@ -147,11 +147,7 @@ template struct TypeTraits: Implementation::TypeTraitsDefault { * the magnitude of original values so the epsilon can be properly scaled. * In other words, the following lines are equivalent: * - * @code{.cpp} - * Float a, b; - * Math::TypeTraits::equals(a, b); - * Math::TypeTraits::equalsZero(a - b, Math::max(Math::abs(a), Math::abs(b))); - * @endcode + * @snippet MagnumMath.cpp TypeTraits-equalsZero */ static bool equalsZero(T a, T magnitude); #endif diff --git a/src/Magnum/Math/Vector.h b/src/Magnum/Math/Vector.h index f5ab1ea22..ceac3d632 100644 --- a/src/Magnum/Math/Vector.h +++ b/src/Magnum/Math/Vector.h @@ -183,11 +183,7 @@ template class Vector { * Performs only default casting on the values, no rounding or * anything else. Example usage: * - * @code{.cpp} - * Vector<4, Float> floatingPoint(1.3f, 2.7f, -15.0f, 7.0f); - * Vector<4, Byte> integral(floatingPoint); - * // integral == {1, 2, -15, 7} - * @endcode + * @snippet MagnumMath.cpp Vector-conversion */ template constexpr explicit Vector(const Vector& other) noexcept: Vector(typename Implementation::GenerateSequence::Type(), other) {} @@ -509,9 +505,7 @@ template class Vector { * this function is faster than the obvious way of sizing * a @ref normalized() vector. Enabled only for floating-point types. * - * @code{.cpp} - * vec*(vec.lengthInverted()*length) // the parentheses are important - * @endcode + * @snippet MagnumMath.cpp Vector-resized * * @see @ref normalized() */ diff --git a/src/Magnum/Math/Vector2.h b/src/Magnum/Math/Vector2.h index 514d87af7..813bb5cb0 100644 --- a/src/Magnum/Math/Vector2.h +++ b/src/Magnum/Math/Vector2.h @@ -67,9 +67,7 @@ template class Vector2: public Vector<2, T> { * * Usable for translation in given axis, for example: * - * @code{.cpp} - * Matrix3::translation(Vector2::xAxis(5.0f)); // same as Matrix3::translation({5.0f, 0.0f}); - * @endcode + * @snippet MagnumMath.cpp Vector2-xAxis * * @see @ref yAxis(), @ref xScale(), @ref Matrix3::right() */ @@ -88,9 +86,7 @@ template class Vector2: public Vector<2, T> { * * Usable for scaling along given direction, for example: * - * @code{.cpp} - * Matrix3::scaling(Vector2::xScale(-2.0f)); // same as Matrix3::scaling({-2.0f, 1.0f}); - * @endcode + * @snippet MagnumMath.cpp Vector2-xScale * * @see @ref yScale(), @ref xAxis() */ diff --git a/src/Magnum/Math/Vector3.h b/src/Magnum/Math/Vector3.h index 4aef3e6e3..4bc0ce0b3 100644 --- a/src/Magnum/Math/Vector3.h +++ b/src/Magnum/Math/Vector3.h @@ -71,10 +71,7 @@ template class Vector3: public Vector<3, T> { * * Usable for translation or rotation along given axis, for example: * - * @code{.cpp} - * Matrix4::translation(Vector3::xAxis(5.0f)); // same as Matrix4::translation({5.0f, 0.0f, 0.0f}); - * Matrix4::rotation(30.0_degf, Vector3::xAxis()); // same as Matrix::rotation(30.0_degf, {1.0f, 0.0f, 0.0f}); - * @endcode + * @snippet MagnumMath.cpp Vector3-xAxis * * @see @ref yAxis(), @ref zAxis(), @ref xScale(), @ref Color3::red(), * @ref Matrix4::right() @@ -102,9 +99,7 @@ template class Vector3: public Vector<3, T> { * * Usable for scaling along given direction, for example: * - * @code{.cpp} - * Matrix4::scaling(Vector3::xScale(-2.0f)); // same as Matrix4::scaling({-2.0f, 1.0f, 1.0f}); - * @endcode + * @snippet MagnumMath.cpp Vector3-xScale * * @see @ref yScale(), @ref zScale(), @ref Color3::cyan(), @ref xAxis() */