Math: compile forgotten code snippets.

doc/snippets/MagnumMath.cpp

@@ -857,6 +857,37 @@ static_cast<void>(startPoint);
 static_cast<void>(endPoint);
 }
 
+{
+/* [Dual-conversion] */
+Math::Dual<Float> floatingPoint{1.3f, 2.7f};
+Math::Dual<Byte> 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<void>(quotient);
+static_cast<void>(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<UnsignedShort>{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<void>(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<void>(sinAngle);
+static_cast<void>(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<void>(sinAngle);
+static_cast<void>(tanAngleSqPlusOne);
+}
+
+{
+/* [Matrix-conversion] */
+Matrix2x2 floatingPoint{Vector2{1.3f, 2.7f}, Vector2{-15.0f, 7.0f}};
+Math::Matrix2x2<Byte> 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<void>(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<void>(a);
+}
+
 {
 /* [StrictWeakOrdering] */
 std::set<Vector2, Math::StrictWeakOrdering> mySet;
@@ -949,4 +1040,69 @@ static_cast<void>(myMap);
 static_cast<void>(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<void>(vec);
+}
+
+{
+Float a{}, b{};
+/* [TypeTraits-equalsZero] */
+Math::TypeTraits<Float>::equals(a, b);
+Math::TypeTraits<Float>::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] */
+}
+
 }

src/Magnum/Math/Dual.h

@@ -104,11 +104,7 @@ template<class T> class Dual {
          * Performs only default casting on the values, no rounding or anything
          * else. Example usage:
          *
-         * @code{.cpp}
+         * @snippet MagnumMath.cpp Dual-conversion
-         * Dual<Float> floatingPoint(1.3f, 2.7f);
-         * Dual<Byte> integral(floatingPoint);
-         * // integral == {1, 2}
-         * @endcode
          */
         template<class U> constexpr explicit Dual(const Dual<U>& other) noexcept: _real{T(other._real)}, _dual{T(other._dual)} {}
 

src/Magnum/Math/Functions.h

@@ -106,17 +106,11 @@ template<class T> inline T exp(T exponent) { return std::exp(exponent); }
 
 Example usage:
 
-@code{.cpp}
+@snippet MagnumMath.cpp div
-Int quotient, remainder;
-std::tie(quotient, remainder) = Math::div(57, 6); // {9, 3}
-@endcode
 
 Equivalent to the following, but possibly done in a single CPU instruction:
 
-@code{.cpp}
+@snippet MagnumMath.cpp div-equivalent
-Int quotient = 57/6;
-Int remainder = 57%6;
-@endcode
 */
 template<class Integral> inline std::pair<Integral, Integral> div(Integral x, Integral y) {
     static_assert(std::is_integral<Integral>{}, "Math::div(): not an integral type");
@@ -438,9 +432,7 @@ template<class T, std::size_t size> inline std::pair<T, T> 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}
+@snippet MagnumMath.cpp clamp
-Math::min(Math::max(value, min), max)
-@endcode
 
 <em>NaN</em>s passed in @p value parameter are propagated.
 @see @ref min(), @ref max()

src/Magnum/Math/Intersection.h

@@ -236,11 +236,9 @@ template<class T> bool pointCone(const Vector3<T>& point, const Vector3<T>& 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}
+@snippet MagnumMath.cpp Intersection-tanAngleSqPlusOne
-Math::pow<2>(Math::tan(angle*T(0.5))) + T(1)
-@endcode
 */
 template<class T> bool pointCone(const Vector3<T>& point, const Vector3<T>& coneOrigin, const Vector3<T>& coneNormal, T tanAngleSqPlusOne);
 
@@ -269,9 +267,7 @@ template<class T> bool pointDoubleCone(const Vector3<T>& point, const Vector3<T>
 
 The @p tanAngleSqPlusOne parameter can be precomputed like this:
 
-@code{.cpp}
+@snippet MagnumMath.cpp Intersection-tanAngleSqPlusOne
-T tanAngleSqPlusOne = Math::pow<2>(Math::tan(angle*T(0.5))) + T(1);
-@endcode
 */
 template<class T> bool pointDoubleCone(const Vector3<T>& point, const Vector3<T>& coneOrigin, const Vector3<T>& coneNormal, T tanAngleSqPlusOne);
 
@@ -301,12 +297,9 @@ template<class T> bool sphereConeView(const Vector3<T>& 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}
+@snippet MagnumMath.cpp Intersection-sinAngle-tanAngle
-T sinAngle = Math::sin(angle*T(0.5));
-T tanAngle = Math::tan(angle*T(0.5));
-@endcode
 */
 template<class T> bool sphereConeView(const Vector3<T>& sphereCenter, T sphereRadius, const Matrix4<T>& 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}
+@snippet MagnumMath.cpp Intersection-sinAngle-tanAngleSqPlusOne
-T sinAngle = Math::sin(angle*T(0.5));
-T tanAngleSqPlusOne = Math::pow<2>(Math::tan(angle*T(0.5))) + T(1);
-@endcode
 */
 template<class T> bool sphereCone(const Vector3<T>& sphereCenter, T sphereRadius, const Vector3<T>& coneOrigin, const Vector3<T>& 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}
+@snippet MagnumMath.cpp Intersection-tanAngleSqPlusOne
-T tanAngleSqPlusOne = Math::pow<2>(Math::tan(angle*T(0.5))) + T(1);
-@endcode
 */
 template<class T> bool aabbCone(const Vector3<T>& aabbCenter, const Vector3<T>& aabbExtents, const Vector3<T>& coneOrigin, const Vector3<T>& coneNormal, T tanAngleSqPlusOne);
 
@@ -422,11 +410,10 @@ template<class T> bool rangeCone(const Range3D<T>& range, const Vector3<T>& cone
     otherwise
 
 Converts the range into center/extents representation and passes it on to
-@ref aabbCone(const Vector3<T>&, const Vector3<T>&, const Vector3<T>&, const Vector3<T>&, T) "aabbCone()". The @p tanAngleSqPlusOne parameter can be precomputed like this:
+@ref aabbCone(const Vector3<T>&, const Vector3<T>&, const Vector3<T>&, const Vector3<T>&, T) "aabbCone()".
+The @p tanAngleSqPlusOne parameter can be precomputed like this:
 
-@code{.cpp}
+@snippet MagnumMath.cpp Intersection-tanAngleSqPlusOne
-T tanAngleSqPlusOne = Math::pow<2>(Math::tan(angle*T(0.5))) + T(1);
-@endcode
 */
 template<class T> bool rangeCone(const Range3D<T>& range, const Vector3<T>& coneOrigin, const Vector3<T>& coneNormal, const T tanAngleSqPlusOne);
 

src/Magnum/Math/Matrix.h

@@ -108,12 +108,7 @@ template<std::size_t size, class T> class Matrix: public RectangularMatrix<size,
          * Performs only default casting on the values, no rounding or
          * anything else. Example usage:
          *
-         * @code{.cpp}
+         * @snippet MagnumMath.cpp Matrix-conversion
-         * Matrix2x2<Float> floatingPoint({1.3f, 2.7f},
-         *                                {-15.0f, 7.0f});
-         * Matrix2x2<Byte> integral(floatingPoint);
-         * // integral == {{1, 2}, {-15, 7}}
-         * @endcode
          */
         template<class U> constexpr explicit Matrix(const RectangularMatrix<size, size, U>& other) noexcept: RectangularMatrix<size, size, T>(other) {}
 

src/Magnum/Math/Range.h

@@ -134,10 +134,7 @@ template<UnsignedInt dimensions, class T> class Range {
          * Performs only default casting on the values, no rounding or
          * anything else. Example usage:
          *
-         * @code{.cpp}
+         * @snippet MagnumMath.cpp Range-conversion
-         * Range2D<Float> floatingPoint({1.3f, 2.7f}, {-15.0f, 7.0f});
-         * Range2D<Byte> integral(floatingPoint); // {{1, 2}, {-15, 7}}
-         * @endcode
          */
         template<class U> constexpr explicit Range(const Range<dimensions, U>& other) noexcept: _min(other._min), _max(other._max) {}
 

src/Magnum/Math/RectangularMatrix.h

@@ -142,11 +142,7 @@ template<std::size_t cols, std::size_t rows, class T> class RectangularMatrix {
          * Performs only default casting on the values, no rounding or
          * anything else. Example usage:
          *
-         * @code{.cpp}
+         * @snippet MagnumMath.cpp RectangularMatrix-conversion
-         * 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
          */
         template<class U> constexpr explicit RectangularMatrix(const RectangularMatrix<cols, rows, U>& other) noexcept: RectangularMatrix(typename Implementation::GenerateSequence<cols>::Type(), other) {}
 
@@ -177,10 +173,7 @@ template<std::size_t cols, std::size_t rows, class T> class RectangularMatrix {
          * Particular elements can be accessed using @ref Vector::operator[](),
          * e.g.:
          *
-         * @code{.cpp}
+         * @snippet MagnumMath.cpp RectangularMatrix-access
-         * RectangularMatrix<4, 3, Float> m;
-         * Float a = m[2][1];
-         * @endcode
          *
          * @see @ref row(), @ref data()
          */

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}
+@snippet MagnumMath.cpp swizzle
-Vector4i original(-1, 2, 3, 4);
-
-auto vec = swizzle<'w', '1', '0', 'x', 'y', 'z'>(original);
-// vec == { 4, 1, 0, -1, 2, 3 }
-@endcode
 
 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

src/Magnum/Math/TypeTraits.h

@@ -147,11 +147,7 @@ template<class T> struct TypeTraits: Implementation::TypeTraitsDefault<T> {
      * the magnitude of original values so the epsilon can be properly scaled.
      * In other words, the following lines are equivalent:
      *
-     * @code{.cpp}
+     * @snippet MagnumMath.cpp TypeTraits-equalsZero
-     * Float a, b;
-     * Math::TypeTraits<Float>::equals(a, b);
-     * Math::TypeTraits<Float>::equalsZero(a - b, Math::max(Math::abs(a), Math::abs(b)));
-     * @endcode
      */
     static bool equalsZero(T a, T magnitude);
     #endif

src/Magnum/Math/Vector.h

@@ -183,11 +183,7 @@ template<std::size_t size, class T> class Vector {
          * Performs only default casting on the values, no rounding or
          * anything else. Example usage:
          *
-         * @code{.cpp}
+         * @snippet MagnumMath.cpp Vector-conversion
-         * Vector<4, Float> floatingPoint(1.3f, 2.7f, -15.0f, 7.0f);
-         * Vector<4, Byte> integral(floatingPoint);
-         * // integral == {1, 2, -15, 7}
-         * @endcode
          */
         template<class U> constexpr explicit Vector(const Vector<size, U>& other) noexcept: Vector(typename Implementation::GenerateSequence<size>::Type(), other) {}
 
@@ -509,9 +505,7 @@ template<std::size_t size, class T> class Vector {
          * this function is faster than the obvious way of sizing
          * a @ref normalized() vector. Enabled only for floating-point types.
          *
-         * @code{.cpp}
+         * @snippet MagnumMath.cpp Vector-resized
-         * vec*(vec.lengthInverted()*length) // the parentheses are important
-         * @endcode
          *
          * @see @ref normalized()
          */

src/Magnum/Math/Vector2.h

@@ -67,9 +67,7 @@ template<class T> class Vector2: public Vector<2, T> {
          *
          * Usable for translation in given axis, for example:
          *
-         * @code{.cpp}
+         * @snippet MagnumMath.cpp Vector2-xAxis
-         * Matrix3::translation(Vector2::xAxis(5.0f)); // same as Matrix3::translation({5.0f, 0.0f});
-         * @endcode
          *
          * @see @ref yAxis(), @ref xScale(), @ref Matrix3::right()
          */
@@ -88,9 +86,7 @@ template<class T> class Vector2: public Vector<2, T> {
          *
          * Usable for scaling along given direction, for example:
          *
-         * @code{.cpp}
+         * @snippet MagnumMath.cpp Vector2-xScale
-         * Matrix3::scaling(Vector2::xScale(-2.0f)); // same as Matrix3::scaling({-2.0f, 1.0f});
-         * @endcode
          *
          * @see @ref yScale(), @ref xAxis()
          */

src/Magnum/Math/Vector3.h

@@ -71,10 +71,7 @@ template<class T> class Vector3: public Vector<3, T> {
          *
          * Usable for translation or rotation along given axis, for example:
          *
-         * @code{.cpp}
+         * @snippet MagnumMath.cpp 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 Matrix::rotation(30.0_degf, {1.0f, 0.0f, 0.0f});
-         * @endcode
          *
          * @see @ref yAxis(), @ref zAxis(), @ref xScale(), @ref Color3::red(),
          *      @ref Matrix4::right()
@@ -102,9 +99,7 @@ template<class T> class Vector3: public Vector<3, T> {
          *
          * Usable for scaling along given direction, for example:
          *
-         * @code{.cpp}
+         * @snippet MagnumMath.cpp Vector3-xScale
-         * Matrix4::scaling(Vector3::xScale(-2.0f)); // same as Matrix4::scaling({-2.0f, 1.0f, 1.0f});
-         * @endcode
          *
          * @see @ref yScale(), @ref zScale(), @ref Color3::cyan(), @ref xAxis()
          */