diff --git a/doc/snippets/MagnumMath.cpp b/doc/snippets/MagnumMath.cpp index db637a61f..92a91ae5f 100644 --- a/doc/snippets/MagnumMath.cpp +++ b/doc/snippets/MagnumMath.cpp @@ -593,4 +593,244 @@ static_cast(q1); static_cast(q2); } +{ +/* [Deg-usage] */ +using namespace Math::Literals; + +auto degrees = 60.0_degf; // type is Deg +auto radians = 1.047_rad; // type is Rad +/* [Deg-usage] */ +static_cast(degrees); +static_cast(radians); +} + +{ +/* [Deg-usage-convert] */ +Double foo(); + +Deg degrees{35.0f}; +Radd radians{foo()}; +//degrees = 60.0f; // error, no implicit conversion +/* [Deg-usage-convert] */ +static_cast(degrees); +static_cast(radians); +} + +{ +/* [Deg-usage-operations] */ +auto a = 60.0_degf + 17.35_degf; +auto b = -a + 23.0_degf*4; +//auto c = 60.0_degf*45.0_degf; // error, undefined resulting unit +/* [Deg-usage-operations] */ +static_cast(b); +} + +{ +Double foo(); +/* [Deg-usage-comparison] */ +Rad angle(); + +Deg x = angle(); // convert to degrees for easier comparison +if(x < 30.0_degf) foo(); +//if(x > 1.57_radf) bar(); // error, both need to be of the same type +/* [Deg-usage-comparison] */ +} + +{ +/* [Deg-usage-conversion] */ +Float sine(Rad angle); +Float a = sine(60.0_degf); // the same as sine(1.047_radf) +Degd b = 1.047_rad; // the same as 60.0_deg +Double c = Double(b); // 60.0 +//Float d = a; // error, no implicit conversion +/* [Deg-usage-conversion] */ +static_cast(a); +static_cast(c); +} + +{ +Float sine(Rad angle); +Float a = 60.0f; +Deg b; +/* [Deg-usage-explicit-conversion] */ +//sine(a); // compilation error +sine(Deg{a}); // explicitly specifying unit + +//std::sin(b); // compilation error +std::sin(Float(Rad{b})); // required explicit conversion hints to user + // that this case needs special attention + // (i.e., conversion to radians) +/* [Deg-usage-explicit-conversion] */ +} + +{ +/* [_deg] */ +using namespace Math::Literals; +Double cos1 = Math::cos(60.0_deg); // cos1 = 0.5 +Double cos2 = Math::cos(1.047_rad); // cos2 = 0.5 +/* [_deg] */ +static_cast(cos1); +static_cast(cos2); +} + +{ +/* [_degf] */ +using namespace Math::Literals; +Float tan1 = Math::tan(60.0_degf); // tan1 = 1.732f +Float tan2 = Math::tan(1.047_radf); // tan2 = 1.732f +/* [_degf] */ +static_cast(tan1); +static_cast(tan2); +} + +{ +/* [Color3-pack] */ +Color3 a{1.0f, 0.5f, 0.75f}; +auto b = Math::pack(a); // b == {255, 127, 191} +/* [Color3-pack] */ +static_cast(b); +} + +{ +/* [Color3-fromSrgb] */ +Math::Vector3 srgb; +auto rgb = Color3::fromSrgb(srgb); +/* [Color3-fromSrgb] */ +static_cast(rgb); +} + +{ +Color3 color; +/* [Color3-toHsv] */ +Deg hue; +Float saturation, value; +std::tie(hue, saturation, value) = color.toHsv(); +/* [Color3-toHsv] */ +} + +{ +/* [Color3-toSrgb] */ +Color3 color; +Math::Vector3 srgb = color.toSrgb(); +/* [Color3-toSrgb] */ +static_cast(srgb); +} + +{ +/* [Color4-fromSrgbAlpha] */ +Math::Vector4 srgbAlpha; +auto rgba = Color4::fromSrgbAlpha(srgbAlpha); +/* [Color4-fromSrgbAlpha] */ +static_cast(rgba); +} + +{ +/* [Color4-fromSrgb] */ +Math::Vector3 srgb; +auto rgba = Color4::fromSrgb(srgb); +/* [Color4-fromSrgb] */ +static_cast(rgba); +} + +{ +Color4 color; +/* [Color4-toHsv] */ +Deg hue; +Float saturation, value; +std::tie(hue, saturation, value) = color.toHsv(); +/* [Color4-toHsv] */ +} + +{ +/* [Color4-toSrgbAlpha] */ +Color4 color; +Math::Vector4 srgbAlpha = color.toSrgbAlpha(); +/* [Color4-toSrgbAlpha] */ +static_cast(srgbAlpha); +} + +{ +/* [_rgb] */ +using namespace Math::Literals; +Color3ub a = 0x33b27f_rgb; // {0x33, 0xb2, 0x7f} +/* [_rgb] */ +static_cast(a); +} + +{ +/* [_srgb] */ +using namespace Math::Literals; +Math::Vector3 a = 0x33b27f_srgb; // {0x33, 0xb2, 0x7f} +/* [_srgb] */ +static_cast(a); +} + +{ +/* [_rgba] */ +using namespace Math::Literals; +Color4ub a = 0x33b27fcc_rgba; // {0x33, 0xb2, 0x7f, 0xcc} +/* [_rgba] */ +static_cast(a); +} + +{ +/* [_srgba] */ +using namespace Math::Literals; +Math::Vector4 a = 0x33b27fcc_srgba; // {0x33, 0xb2, 0x7f, 0xcc} +/* [_srgba] */ +static_cast(a); +} + +{ +/* [_rgbf] */ +using namespace Math::Literals; +Color3 a = 0x33b27f_rgbf; // {0.2f, 0.698039f, 0.498039f} +/* [_rgbf] */ +static_cast(a); +} + +{ +/* [_srgbf] */ +using namespace Math::Literals; +Color3 a = 0x33b27f_srgbf; // {0.0331048f, 0.445201f, 0.212231f} +/* [_srgbf] */ +static_cast(a); +} + +{ +/* [_rgbaf] */ +using namespace Math::Literals; +Color4 a = 0x33b27fcc_rgbaf; // {0.2f, 0.698039f, 0.498039f, 0.8f} +/* [_rgbaf] */ +static_cast(a); +} + +{ +/* [_srgbaf] */ +using namespace Math::Literals; +Color4 a = 0x33b27fcc_srgbaf; // {0.0331048f, 0.445201f, 0.212231f, 0.8f} +/* [_srgbaf] */ +static_cast(a); +} + +{ +/* [Half-usage] */ +using namespace Math::Literals; + +Half a = 3.14159_h; +Debug{} << a; // Prints 3.14159 +Debug{} << Float(a); // Prints 3.14159 +Debug{} << UnsignedShort(a); // Prints 25675 +/* [Half-usage] */ +} + +{ +/* [Half-usage-vector] */ +Math::Vector3 a{3.14159_h, -1.4142_h, 1.618_h}; +Vector3 b{a}; // converts to 32-bit floats +Debug{} << a; // prints {3.14159, -1.4142, 1.618} +Debug{} << Math::Vector3{a}; // prints {16968, 48552, 15993} +/* [Half-usage-vector] */ +} + } diff --git a/src/Magnum/Math/Angle.h b/src/Magnum/Math/Angle.h index c02449728..1ee7c3489 100644 --- a/src/Magnum/Math/Angle.h +++ b/src/Magnum/Math/Angle.h @@ -49,65 +49,38 @@ and conversion less error-prone. You can enter the value either by using a literal: -@code{.cpp} -using namespace Literals; - -auto degrees = 60.0_degf; // type is Deg -auto radians = 1.047_rad; // type is Rad -@endcode +@snippet MagnumMath.cpp Deg-usage Or explicitly convert a unitless value (such as output from some function) to either degrees or radians: -@code{.cpp} -Double foo(); - -Deg degrees(35.0f); -Rad radians(foo()); -//degrees = 60.0f; // error, no implicit conversion -@endcode +@snippet MagnumMath.cpp Deg-usage-convert The classes support all arithmetic operations, such as addition, subtraction or multiplication/division by a unitless number: -@code{.cpp} -auto a = 60.0_degf + 17.35_degf; -auto b = -a + 23.0_degf*4; -//auto c = 60.0_degf*45.0_degf; // error, undefined resulting unit -@endcode +@snippet MagnumMath.cpp Deg-usage-operations It is also possible to compare angles with all comparison operators, but comparison of degrees and radians is not possible without explicit conversion to common type: -@code{.cpp} -Rad angle(); - -Deg x = angle(); // convert to degrees for easier comparison -if(x < 30.0_degf) foo(); -//if(x > 1.57_radf) bar(); // error, both need to be of the same type -@endcode +@snippet MagnumMath.cpp Deg-usage-comparison It is possible to seamlessly convert between degrees and radians and explicitly convert the value back to the underlying type: -@code{.cpp} -Float sine(Rad angle); -Float a = sine(60.0_degf); // the same as sine(1.047_radf) -Deg b = 1.047_rad; // the same as 60.0_deg -Float d = Double(b); // 60.0 -//Float e = b; // error, no implicit conversion -@endcode +@snippet MagnumMath.cpp Deg-usage-conversion @section Math-Angle-explicit-conversion Requirement of explicit conversion The requirement of explicit conversions from and to unitless types helps to -reduce unit-based errors. Consider following example with implicit conversions -allowed: +reduce unit-based errors. Consider the following example that would compile +only if implicit conversions were allowed: @code{.cpp} namespace std { float sin(float angle); } -Float sine(Rad angle); +Float sine(Rad angle); Float a = 60.0f; // degrees sine(a); // silent error, sine() expected radians @@ -118,15 +91,7 @@ std::sin(b); // silent error, std::sin() expected radians These silent errors are easily avoided by requiring explicit conversions: -@code{.cpp} -//sine(a); // compilation error -sine(Deg{a}); // explicitly specifying unit - -//std::sin(b); // compilation error -std::sin(Float(Rad(b)); // required explicit conversion hints to user - // that this case needs special attention - // (i.e., conversion to radians) -@endcode +@snippet MagnumMath.cpp Deg-usage-explicit-conversion @see @ref Magnum::Deg, @ref Magnum::Degd */ @@ -175,10 +140,7 @@ namespace Literals { Example usage: -@code{.cpp} -Double cosine = Math::cos(60.0_deg); // cosine = 0.5 -Double cosine = Math::cos(1.047_rad); // cosine = 0.5 -@endcode +@snippet MagnumMath.cpp _deg @see @link operator""_degf() @endlink, @link operator""_rad() @endlink */ @@ -189,10 +151,7 @@ constexpr Deg operator "" _deg(long double value) { return Deg(D Example usage: -@code{.cpp} -Float tangent = Math::tan(60.0_degf); // tangent = 1.732f -Float tangent = Math::tan(1.047_radf); // tangent = 1.732f -@endcode +@snippet MagnumMath.cpp _degf @see @link operator""_deg() @endlink, @link operator""_radf() @endlink */ diff --git a/src/Magnum/Math/Color.h b/src/Magnum/Math/Color.h index 0c2f3ccbd..f4f48b8b2 100644 --- a/src/Magnum/Math/Color.h +++ b/src/Magnum/Math/Color.h @@ -219,10 +219,7 @@ Note that constructor conversion between different types (like in @ref Vector classes) doesn't do any (de)normalization, you should use @ref pack) and @ref unpack() instead, for example: -@code{.cpp} -Color3 a{1.0f, 0.5f, 0.75f}; -auto b = pack(a); // b == {255, 127, 191} -@endcode +@snippet MagnumMath.cpp Color3-pack Conversion from and to HSV is done always using floating-point types, so hue is always in range in range @f$ [0.0, 360.0] @f$, saturation and value in @@ -383,10 +380,7 @@ template class Color3: public Vector3 { * representation and want to create a floating-point linear RGB color * out of it: * - * @code{.cpp} - * Math::Vector3 srgb; - * auto rgb = Color3::fromSrgb(srgb); - * @endcode + * @snippet MagnumMath.cpp Color3-fromSrgb */ /* Input is a Vector3 to hint that it doesn't have any (additive, multiplicative) semantics of a linear RGB color */ @@ -475,11 +469,7 @@ template class Color3: public Vector3 { * * Example usage: * - * @code{.cpp} - * Deg hue; - * Float saturation, value; - * std::tie(hue, saturation, value) = color.toHsv(); - * @endcode + * @snippet MagnumMath.cpp Color3-toHsv * * @see @ref hue(), @ref saturation(), @ref value(), @ref fromHsv() */ @@ -547,10 +537,7 @@ template class Color3: public Vector3 { * Useful in cases where you have a floating-point linear RGB color and * want to create for example an 8-bit sRGB representation out of it: * - * @code{.cpp} - * Color3 color; - * Math::Vector3 srgb = color.toSrgb(); - * @endcode + * @snippet MagnumMath.cpp Color3-toSrgb */ template Vector3 toSrgb() const { return Implementation::toSrgbIntegral(*this); @@ -752,10 +739,7 @@ class Color4: public Vector4 { * representation and want to create a floating-point linear RGBA color * out of it: * - * @code{.cpp} - * Math::Vector4 srgbAlpha; - * auto rgba = Color4::fromSrgbAlpha(srgbAlpha); - * @endcode + * @snippet MagnumMath.cpp Color4-fromSrgbAlpha */ /* Input is a Vector4 to hint that it doesn't have any (additive, multiplicative) semantics of a linear RGB color */ @@ -774,10 +758,7 @@ class Color4: public Vector4 { * representation and want to create a floating-point linear RGBA color * out of it: * - * @code{.cpp} - * Math::Vector3 srgb; - * auto rgba = Color4::fromSrgb(srgb); - * @endcode + * @snippet MagnumMath.cpp Color4-fromSrgb */ /* Input is a Vector3 to hint that it doesn't have any (additive, multiplicative) semantics of a linear RGB color */ @@ -878,11 +859,7 @@ class Color4: public Vector4 { * The alpha channel is not subject to any conversion, so it is * ignored. Example usage: * - * @code{.cpp} - * Deg hue; - * Float saturation, value; - * std::tie(hue, saturation, value) = color.toHsv(); - * @endcode + * @snippet MagnumMath.cpp Color4-toHsv * * @see @ref hue(), @ref saturation(), @ref value(), @ref fromHsv() */ @@ -933,10 +910,7 @@ class Color4: public Vector4 { * and want to create for example an 8-bit sRGB + alpha representation * out of it: * - * @code{.cpp} - * Color4 color; - * Math::Vector4 srgbAlpha = color.toSrgbAlpha(); - * @endcode + * @snippet MagnumMath.cpp Color4-toSrgbAlpha */ template Vector4 toSrgbAlpha() const { return Implementation::toSrgbAlphaIntegral(*this); @@ -1012,9 +986,7 @@ namespace Literals { Unpacks the literal into three 8-bit values. Example usage: -@code{.cpp} -Color3ub a = 0x33b27f_rgb; // {0x33, 0xb2, 0x7f} -@endcode +@snippet MagnumMath.cpp _rgb @attention 8bit-per-channel colors are commonly treated as being in sRGB color space, which is not directly usable in calculations and has to be converted @@ -1035,9 +1007,7 @@ Behaves identically to @link operator""_rgb() @endlink though it doesn't return a @ref Color3 type to indicate that the resulting value is not linear RGB. Use this literal to document that given value is in sRGB. Example usage: -@code{.cpp} -Math::Vector3 a = 0x33b27f_srgb; // {0x33, 0xb2, 0x7f} -@endcode +@snippet MagnumMath.cpp _srgb @attention Note that colors in sRGB representation should not be used directly in calculations --- they should be converted to linear RGB, calculation @@ -1058,9 +1028,7 @@ constexpr Vector3 operator "" _srgb(unsigned long long value) { Unpacks the literal into four 8-bit values. Example usage: -@code{.cpp} -Color4ub a = 0x33b27fcc_rgba; // {0x33, 0xb2, 0x7f, 0xcc} -@endcode +@snippet MagnumMath.cpp _rgba @attention 8bit-per-channel colors are commonly treated as being in sRGB color space, which is not directly usable in calculations and has to be converted @@ -1082,9 +1050,7 @@ return a @ref Color4 type to indicate that the resulting value is not linear RGBA. Use this literal to document that given value is in sRGB + alpha. Example usage: -@code{.cpp} -Math::Vector4 a = 0x33b27fcc_srgba; // {0x33, 0xb2, 0x7f, 0xcc} -@endcode +@snippet MagnumMath.cpp _srgba @attention Note that colors in sRGB representation should not be used directly in calculations --- they should be converted to linear RGB, calculation @@ -1105,9 +1071,7 @@ constexpr Vector4 operator "" _srgba(unsigned long long value) { Unpacks the 8-bit values into three floats. Example usage: -@code{.cpp} -Color3 a = 0x33b27f_rgbf; // {0.2f, 0.698039f, 0.498039f} -@endcode +@snippet MagnumMath.cpp _rgbf @attention 8bit-per-channel colors are commonly treated as being in sRGB color space, which is not directly usable in calculations and has to be converted @@ -1127,9 +1091,7 @@ Unpacks the 8-bit values into three floats and converts the color space from sRGB to linear RGB. See @ref Color3::fromSrgb() for more information. Example usage: -@code{.cpp} -Color3 a = 0x33b27f_srgbf; // {0.0331048f, 0.445201f, 0.212231f} -@endcode +@snippet MagnumMath.cpp _srgbf @see @link operator""_srgbaf() @endlink, @link operator""_srgb() @endlink, @link operator""_rgbf() @endlink @@ -1143,9 +1105,7 @@ inline Color3 operator "" _srgbf(unsigned long long value) { Unpacks the 8-bit values into four floats. Example usage: -@code{.cpp} -Color4 a = 0x33b27fcc_rgbaf; // {0.2f, 0.698039f, 0.498039f, 0.8f} -@endcode +@snippet MagnumMath.cpp _rgbaf @attention 8bit-per-channel colors are commonly treated as being in sRGB color space, which is not directly usable in calculations and has to be converted @@ -1165,9 +1125,7 @@ Unpacks the 8-bit values into four floats and converts the color space from sRGB + alpha to linear RGBA. See @ref Color4::fromSrgbAlpha() for more information. Example usage: -@code{.cpp} -Color4 a = 0x33b27fcc_srgbaf; // {0.0331048f, 0.445201f, 0.212231f, 0.8f} -@endcode +@snippet MagnumMath.cpp _srgbaf @see @link operator""_srgbf() @endlink, @link operator""_srgba() @endlink, @link operator""_rgbaf() @endlink diff --git a/src/Magnum/Math/Half.h b/src/Magnum/Math/Half.h index 7f3738a8d..afb3cb70f 100644 --- a/src/Magnum/Math/Half.h +++ b/src/Magnum/Math/Half.h @@ -49,25 +49,13 @@ negation operator, an @link Literals::operator""_h() operator""_h() @endlink literal and an @ref operator<<(Debug&, Half) debug operator. Internally the class uses @ref packHalf() and @ref unpackHalf(). Example usage: -@code{.cpp} -using namespace Math::Literals; - -Half a = 3.14159_h; -Debug{} << a; // Prints 3.14159 -Debug{} << Float(a); // Prints 3.14159 -Debug{} << UnsignedShort(a); // Prints 25675 -@endcode +@snippet MagnumMath.cpp Half-usage Note that it is also possible to use this type inside @ref Vector classes, though, again, only for passing data around and converting them, without any arithmetic operations: -@code{.cpp} -Math::Vector3 a{3.14159_h, -1.4142_h, 1.618_h}; -Vector3 b{a}; // converts to 32-bit floats -Debug{} << a; // prints {3.14159, -1.4142, 1.618} -Debug{} << Math::Vector3{a}; // prints {16968, 48552, 15993} -@endcode +@snippet MagnumMath.cpp Half-usage-vector @see @ref Magnum::Half */