diff --git a/doc/matrix-vector.dox b/doc/matrix-vector.dox index 70e629b48..fef01297e 100644 --- a/doc/matrix-vector.dox +++ b/doc/matrix-vector.dox @@ -98,6 +98,14 @@ Vector3i fill(10); // {10, 10, 10} auto diag2 = Matrix3::fromDiagonal({3.0f, 2.0f, 1.0f}); @endcode +There are also shortcuts to create a vector with all but one component set to +zero or one, useful for transformations: +@code +auto x = Vector3::xAxis(); // {1.0f, 0.0f, 0.0f} +auto y = Vector2::yAxis(3.0f); // {0.0f, 3.0f} +auto z = Vector3::zScale(3.0f); // {1.0f, 1.0f, 3.0f} +@endcode + It is possible to create matrices from other matrices and vectors with the same row count; vectors from vector and scalar: @code @@ -121,6 +129,30 @@ Math::Matrix2x3::from(mat) *= 2; // mat == { 4, 8, 12, 2, 6, 10 } Note that, unlike constructors, this function has no way to check whether the array is long enough to contain all elements, so use with caution. +To make handling of colors easier, their behavior is a bit different with a +richer feature set. Implicit construction of @ref Color4 from @ref Color3 will +set the alpha to full value (thus `1.0f` for @ref Color4 and `255` for +@ref Color4ub): +@code +Color4 a = Color3{0.2f, 0.7f, 0.5f}; // {0.2f, 0.7f, 0.5f, 1.0f} +Color4ub b = Color3ub{0x33, 0xb2, 0x7f}; // {0x33, 0xb2, 0x7f, 0xff} +@endcode + +Similarly to axes in vectors, you can create single color shades too, or create +a RGB color from HSV representation: +@code +auto green = Color3::green(); // {0.0f, 1.0f, 0.0f} +auto cyan = Color4::cyan(0.5f, 0.95f); // {0.5f, 1.0f, 1.0f, 0.95f} +auto fadedRed = Color3::fromHSV(219.0_degf, 0.50f, 0.57f) +@endcode + +Lastly, namespace @ref Math::Literals provides convenient `_rgb`/`_rgbf` and +`_rgba`/`_rgbaf` literals for entering colors in hex representation: +@code +Color3ub a = 0x33b27f_rgb; // {0x33, 0xb2, 0x7f} +Color4 b = 0x33b27fcc_rgbaf; // {0.2f, 0.7f, 0.5f, 0.8f} +@endcode + @section matrix-vector-component-access Accessing matrix and vector components Column vectors of matrices and vector components can be accessed using square diff --git a/src/Magnum/Math/Color.h b/src/Magnum/Math/Color.h index 963cfb34e..137ccc121 100644 --- a/src/Magnum/Math/Color.h +++ b/src/Magnum/Math/Color.h @@ -151,7 +151,8 @@ 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 range @f$ [0.0, 1.0] @f$. -@see @ref Color4, @ref Magnum::Color3, @ref Magnum::Color3ub +@see @link operator""_rgb() @endlink, @link operator""_rgbf() @endlink, + @ref Color4, @ref Magnum::Color3, @ref Magnum::Color3ub */ /* Not using template specialization because some internal functions are impossible to explicitly instantiate */ @@ -352,7 +353,8 @@ MAGNUM_VECTORn_OPERATOR_IMPLEMENTATION(3, Color3) @brief Four-component (RGBA) color See @ref Color3 for more information. -@see @ref Magnum::Color4, @ref Magnum::Color4ub +@see @link operator""_rgba() @endlink, @link operator""_rgbaf() @endlink, + @ref Magnum::Color4, @ref Magnum::Color4ub */ /* Not using template specialization because some internal functions are impossible to explicitly instantiate */ @@ -532,6 +534,62 @@ class Color4: public Vector4 { MAGNUM_VECTORn_OPERATOR_IMPLEMENTATION(4, Color4) #endif +namespace Literals { + +/** @relatesalso Magnum::Math::Color3 +@brief 8bit-per-channel RGB literal + +Example usage: +@code +Color3ub a = 0x33b27f_rgb; // {0x33, 0xb2, 0x7f} +@endcode +@see @link operator""_rgba() @endlink, @link operator""_rgbf() @endlink +*/ +constexpr Color3 operator "" _rgb(unsigned long long value) { + return {UnsignedByte(value >> 16), UnsignedByte(value >> 8), UnsignedByte(value)}; +} + +/** @relatesalso Magnum::Math::Color4 +@brief 8bit-per-channel RGBA literal + +Example usage: +@code +Color4ub a = 0x33b27fcc_rgba; // {0x33, 0xb2, 0x7f, 0xcc} +@endcode +@see @link operator""_rgb() @endlink, @link operator""_rgbaf() @endlink +*/ +constexpr Color4 operator "" _rgba(unsigned long long value) { + return {UnsignedByte(value >> 24), UnsignedByte(value >> 16), UnsignedByte(value >> 8), UnsignedByte(value)}; +} + +/** @relatesalso Magnum::Math::Color3 +@brief Float RGB literal + +Example usage: +@code +Color3 a = 0x33b27f_rgbf; // {0.2f, 0.7f, 0.5f} +@endcode +@see @link operator""_rgbaf() @endlink, @link operator""_rgb() @endlink +*/ +inline Color3 operator "" _rgbf(unsigned long long value) { + return Math::normalize>(Color3{UnsignedByte(value >> 16), UnsignedByte(value >> 8), UnsignedByte(value)}); +} + +/** @relatesalso Magnum::Math::Color4 +@brief Float RGBA literal + +Example usage: +@code +Color4 a = 0x33b27fcc_rgbaf; // {0.2f, 0.7f, 0.5f, 0.8f} +@endcode +@see @link operator""_rgbf() @endlink, @link operator""_rgbaf() @endlink +*/ +inline Color4 operator "" _rgbaf(unsigned long long value) { + return Math::normalize>(Color4{UnsignedByte(value >> 24), UnsignedByte(value >> 16), UnsignedByte(value >> 8), UnsignedByte(value)}); +} + +} + /** @debugoperator{Magnum::Math::Color3} */ template inline Corrade::Utility::Debug& operator<<(Corrade::Utility::Debug& debug, const Color3& value) { return debug << static_cast&>(value); diff --git a/src/Magnum/Math/Test/ColorTest.cpp b/src/Magnum/Math/Test/ColorTest.cpp index f393416c1..378f8d567 100644 --- a/src/Magnum/Math/Test/ColorTest.cpp +++ b/src/Magnum/Math/Test/ColorTest.cpp @@ -44,6 +44,8 @@ struct ColorTest: Corrade::TestSuite::Tester { void constructNormalization(); void constructCopy(); + void literals(); + void colors(); void fromHue(); @@ -73,6 +75,8 @@ typedef Math::Color4 Color4ub; typedef Math::Deg Deg; +using namespace Literals; + ColorTest::ColorTest() { addTests({&ColorTest::construct, &ColorTest::constructDefault, @@ -84,6 +88,8 @@ ColorTest::ColorTest() { &ColorTest::constructNormalization, &ColorTest::constructCopy, + &ColorTest::literals, + &ColorTest::colors, &ColorTest::fromHue, @@ -217,6 +223,20 @@ void ColorTest::constructCopy() { CORRADE_COMPARE(d, Color4(1.0f, 0.5f, 0.75f, 0.25f)); } +void ColorTest::literals() { + using namespace Literals; + + constexpr Color3ub a = 0x33b27f_rgb; + CORRADE_COMPARE(a, (Color3ub{0x33, 0xb2, 0x7f})); + + constexpr Color4ub b = 0x33b27fcc_rgba; + CORRADE_COMPARE(b, (Color4ub{0x33, 0xb2, 0x7f, 0xcc})); + + /* Not constexpr yet */ + CORRADE_COMPARE(0x33b27f_rgbf, (Color3{0.2f, 0.7f, 0.5f})); + CORRADE_COMPARE(0x33b27fcc_rgbaf, (Color4{0.2f, 0.7f, 0.5f, 0.8f})); +} + void ColorTest::colors() { CORRADE_COMPARE(Color3ub::red(75), Color3ub(75, 0, 0)); CORRADE_COMPARE(Color3ub::green(75), Color3ub(0, 75, 0));