From 897d1002c3789f7ff8ab9a199fe6d7e30e74b38d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Wed, 8 Feb 2023 16:23:19 +0100 Subject: [PATCH] Math: rename Color[34]::fromSrgb*(UnsignedInt) to fromSrgb*Int(). For consistency with toSrgb*Int(), and to avoid confusion or accidental uses with a wrong type. --- doc/changelog.dox | 7 +++ doc/snippets/MagnumMath.cpp | 14 ++--- src/Magnum/Math/Color.h | 88 +++++++++++++++++++++--------- src/Magnum/Math/Test/ColorTest.cpp | 14 ++--- 4 files changed, 82 insertions(+), 41 deletions(-) diff --git a/doc/changelog.dox b/doc/changelog.dox index f0bdfcbe1..dd9e083c8 100644 --- a/doc/changelog.dox +++ b/doc/changelog.dox @@ -905,6 +905,13 @@ See also: @relativeref{Magnum,BitVector3} and @relativeref{Magnum,BitVector4} to not imply storing the 8-bit @cpp bool @ce type and for consistency with the new @relativeref{Corrade,Containers::BitArray} types +- @cpp Math::Color3::fromSrgb() @ce, @cpp Math::Color4::fromSrgb() @ce and + @cpp Math::Color4::fromSrgbAlpha() @ce taking a 32-bit integer are + deprecated in favor of @ref Math::Color3::fromSrgbInt(), + @ref Math::Color4::fromSrgbInt() and @ref Math::Color4::fromSrgbAlphaInt() + for consistency with @relativeref{Math::Color3,toSrgbInt()} and + @relativeref{Math::Color4,toSrgbAlphaInt()} and to prevent accidental type + mismatches - Markup styling for Emscripten application was switched to prefer using CSS classes instead of the @cb{.css} #container @ce, @cb{.css} #sizer @ce, @cb{.css} #expander @ce, @cb{.css} #listener @ce, @cb{.css} #canvas @ce, diff --git a/doc/snippets/MagnumMath.cpp b/doc/snippets/MagnumMath.cpp index fdfb1ff6c..b79e5a8c6 100644 --- a/doc/snippets/MagnumMath.cpp +++ b/doc/snippets/MagnumMath.cpp @@ -126,7 +126,7 @@ static_cast(cyan); { /* [matrix-vector-construct-color-colorspace] */ auto fadedRed = Color3::fromHsv({219.0_degf, 0.50f, 0.57f}); -auto linear = Color3::fromSrgb(0x33b27f); // {0.2f, 0.7f, 0.5f} +auto linear = Color3::fromSrgbInt(0x33b27f); // {0.2f, 0.7f, 0.5f} auto white = Color3::fromXyz({0.950456f, 1.0f, 1.08906f}); UnsignedInt srgb = linear.toSrgbInt(); // 0x33b27f /* [matrix-vector-construct-color-colorspace] */ @@ -765,10 +765,10 @@ static_cast(rgb); } { -/* [Color3-fromSrgb-int] */ -Color3 a = Color3::fromSrgb(0xff3366); +/* [Color3-fromSrgbInt] */ +Color3 a = Color3::fromSrgbInt(0xff3366); Color3 b = 0xff3366_srgbf; -/* [Color3-fromSrgb-int] */ +/* [Color3-fromSrgbInt] */ static_cast(a); static_cast(b); } @@ -810,10 +810,10 @@ static_cast(rgba); } { -/* [Color4-fromSrgbAlpha-int] */ -Color4 a = Color4::fromSrgbAlpha(0xff336680); +/* [Color4-fromSrgbAlphaInt] */ +Color4 a = Color4::fromSrgbAlphaInt(0xff336680); Color4 b = 0xff336680_srgbaf; -/* [Color4-fromSrgbAlpha-int] */ +/* [Color4-fromSrgbAlphaInt] */ static_cast(a); static_cast(b); } diff --git a/src/Magnum/Math/Color.h b/src/Magnum/Math/Color.h index 3ec0cbf2e..cce3d842f 100644 --- a/src/Magnum/Math/Color.h +++ b/src/Magnum/Math/Color.h @@ -230,17 +230,18 @@ template<> constexpr long double fullChannel() { return 1.0l; } @brief Color in linear RGB color space The class can store either a floating-point or an integral representation of a -linear RGB color. Colors in sRGB color space should not beused directly in -calculations --- they should be converted to linear RGB using @ref fromSrgb(), -calculation done on the linear representation and then converted back to sRGB -using @ref toSrgb(). +linear RGB color. Colors in sRGB color space should not be used directly in +calculations --- they should be converted to linear RGB using @ref fromSrgb() +/ @ref fromSrgbInt(), calculation done on the linear representation and then +converted back to sRGB using @ref toSrgb() / @ref toSrgbInt(). Integral colors are assumed to be in a packed representation where the @f$ [0.0, 1.0] @f$ range is mapped to @f$ [0, 2^b - 1] @f$ with @f$ b @f$ being bit count of given integer type. Note that constructor conversion between different types (like in @ref Vector classes) doesn't do any (un)packing, you -need to use either @ref pack() / @ref unpack() or the integer variants of -@ref toSrgb() / @ref fromSrgb() instead: +need to use either @ref pack() / @ref unpack(), the integer variants of +@ref toSrgb() / @ref fromSrgb() or @ref toSrgbInt() / @ref fromSrgbInt() +instead: @snippet MagnumMath.cpp Color3-pack @@ -375,7 +376,7 @@ template class Color3: public Vector3 { * \left( \dfrac{\boldsymbol{c}_\mathrm{sRGB} + a}{1 + a} \right)^{2.4}, & \boldsymbol{c}_\mathrm{sRGB} > 0.04045 * \end{cases} * @f] - * @see @ref fromSrgb(const Vector3&), @ref fromSrgb(UnsignedInt), + * @see @ref fromSrgb(const Vector3&), @ref fromSrgbInt(), * @link operator""_srgbf() @endlink, @ref toSrgb(), * @ref Color4::fromSrgbAlpha() */ @@ -400,7 +401,7 @@ template class Color3: public Vector3 { * * @snippet MagnumMath.cpp Color3-unpack * - * @see @ref fromSrgb(UnsignedInt), @link operator""_srgbf() @endlink, + * @see @ref fromSrgbInt(), @link operator""_srgbf() @endlink, * @ref Color4::fromSrgbAlpha(const Vector4&) */ /* Input is a Vector3 to hint that it doesn't have any (additive, @@ -409,29 +410,40 @@ template class Color3: public Vector3 { return Implementation::fromSrgbIntegral(srgb); } - /** @overload + /** * @brief Create linear RGB color from 24-bit sRGB representation * @param srgb 24-bit sRGB color + * @m_since_latest * * See @ref fromSrgb() for more information and @ref toSrgbInt() for an * inverse operation. There's also a @link operator""_srgbf() @endlink * that does this conversion directly from hexadecimal literals. The * following two statements are equivalent: * - * @snippet MagnumMath.cpp Color3-fromSrgb-int + * @snippet MagnumMath.cpp Color3-fromSrgbInt * * Note that the integral value is endian-dependent (the red channel * being in the *last* byte on little-endian platforms), for conversion * from endian-independent sRGB / linear representation use * @ref fromSrgb(const Vector3&) / @ref unpack(). - * @see @ref Color4::fromSrgbAlpha(UnsignedInt) + * @see @ref Color4::fromSrgbAlphaInt() */ - static Color3 fromSrgb(UnsignedInt srgb) { + static Color3 fromSrgbInt(UnsignedInt srgb) { return fromSrgb({UnsignedByte(srgb >> 16), UnsignedByte(srgb >> 8), UnsignedByte(srgb)}); } + #ifdef MAGNUM_BUILD_DEPRECATED + /** + * @copybrief fromSrgbInt() + * @m_deprecated_since_latest Use @ref fromSrgbInt() instead. + */ + CORRADE_DEPRECATED("use fromSrgInt() instead") static Color3 fromSrgb(UnsignedInt srgb) { + return fromSrgbInt(srgb); + } + #endif + /** * @brief Create RGB color from [CIE XYZ representation](https://en.wikipedia.org/wiki/CIE_1931_color_space) * @param xyz Color in CIE XYZ color space @@ -786,7 +798,7 @@ class Color4: public Vector4 { * * @snippet MagnumMath.cpp Color4-unpack * - * @see @ref fromSrgbAlpha(UnsignedInt) + * @see @ref fromSrgbAlphaInt(UnsignedInt) */ /* Input is a Vector4 to hint that it doesn't have any (additive, multiplicative) semantics of a linear RGB color */ @@ -802,7 +814,7 @@ class Color4: public Vector4 { * types * * Same as above, but with alpha as a separate parameter. - * @see @ref fromSrgb(UnsignedInt, T) + * @see @ref fromSrgbInt(UnsignedInt, T) */ /* Input is a Vector3 to hint that it doesn't have any (additive, multiplicative) semantics of a linear RGB color */ @@ -810,31 +822,42 @@ class Color4: public Vector4 { return {Implementation::fromSrgbIntegral(srgb), a}; } - /** @overload + /** * @brief Create linear RGBA color from 32-bit sRGB + alpha representation * @param srgbAlpha 32-bit sRGB color with linear alpha + * @m_since_latest * - * See @ref Color3::fromSrgb() for more information and + * See @ref Color3::fromSrgbInt() for more information and * @ref toSrgbAlphaInt() for an inverse operation. There's also a * @link operator""_srgbaf() @endlink that does this conversion * directly from hexadecimal literals. The following two statements are * equivalent: * - * @snippet MagnumMath.cpp Color4-fromSrgbAlpha-int + * @snippet MagnumMath.cpp Color4-fromSrgbAlphaInt * * Note that the integral value is endian-dependent (the red channel * being in the *last* byte on little-endian platforms), for conversion * from an endian-independent sRGB / linear representation use * @ref fromSrgbAlpha(const Vector4&) / @ref unpack(). */ - static Color4 fromSrgbAlpha(UnsignedInt srgbAlpha) { + static Color4 fromSrgbAlphaInt(UnsignedInt srgbAlpha) { return fromSrgbAlpha({UnsignedByte(srgbAlpha >> 24), UnsignedByte(srgbAlpha >> 16), UnsignedByte(srgbAlpha >> 8), UnsignedByte(srgbAlpha)}); } - /** @overload + #ifdef MAGNUM_BUILD_DEPRECATED + /** + * @copybrief fromSrgbAlphaInt() + * @m_deprecated_since_latest Use @ref fromSrgbAlphaInt() instead. + */ + CORRADE_DEPRECATED("use fromSrgInt() instead") static Color4 fromSrgbAlpha(UnsignedInt srgb) { + return fromSrgbAlphaInt(srgb); + } + #endif + + /** * @brief Create linear RGBA color from 32-bit sRGB + alpha representation * @param srgb 24-bit sRGB color * @param a Linear alpha value, defaults to @cpp 1.0 @ce for @@ -843,12 +866,22 @@ class Color4: public Vector4 { * * Same as above, but with alpha as a separate parameter. */ - static Color4 fromSrgb(UnsignedInt srgb, T a = Implementation::fullChannel()) { + static Color4 fromSrgbInt(UnsignedInt srgb, T a = Implementation::fullChannel()) { return fromSrgb({UnsignedByte(srgb >> 16), UnsignedByte(srgb >> 8), UnsignedByte(srgb)}, a); } + #ifdef MAGNUM_BUILD_DEPRECATED + /** + * @copybrief fromSrgbInt() + * @m_deprecated_since_latest Use @ref fromSrgbInt() instead. + */ + CORRADE_DEPRECATED("use fromSrgInt() instead") static Color4 fromSrgb(UnsignedInt srgb, T a = Implementation::fullChannel()) { + return fromSrgbInt(srgb, a); + } + #endif + /** * @brief Create RGBA color from [CIE XYZ representation](https://en.wikipedia.org/wiki/CIE_1931_color_space) * @param xyz Color in CIE XYZ color space @@ -1209,7 +1242,8 @@ RGB. Use this literal to document that given value is in sRGB. Example usage: in calculations --- they should be converted to linear RGB, calculation done on the linear representation and then converted back to sRGB. Use the @link operator""_srgbf() @endlink literal if you want to get a linear RGB - representation directly or convert the value using @ref Color3::fromSrgb(). + representation directly or convert the value using @ref Color3::fromSrgb() + / @ref Color3::fromSrgbInt(). @see @link operator""_srgba() @endlink, @link operator""_rgb() @endlink @m_keywords{_srgb srgb} @@ -1254,7 +1288,8 @@ usage: in calculations --- they should be converted to linear RGB, calculation done on the linear representation and then converted back to sRGB. Use the @link operator""_srgbaf() @endlink literal if you want to get a linear RGBA - representation directly or convert the value using @ref Color4::fromSrgbAlpha(). + representation directly or convert the value using + @ref Color4::fromSrgbAlpha() / @ref Color4::fromSrgbAlphaInt(). @see @link operator""_srgb() @endlink, @link operator""_rgba() @endlink @m_keywords{_srgba srgba} @@ -1287,7 +1322,7 @@ inline Color3 operator "" _rgbf(unsigned long long value) { /** @relatesalso Magnum::Math::Color3 @brief Float sRGB literal -Calls @ref Color3::fromSrgb(UnsignedInt) on the literal value. Example usage: +Calls @ref Color3::fromSrgbInt() on the literal value. Example usage: @snippet MagnumMath.cpp _srgbf @@ -1296,7 +1331,7 @@ Calls @ref Color3::fromSrgb(UnsignedInt) on the literal value. Example usage: @m_keywords{_srgbf srgbf} */ inline Color3 operator "" _srgbf(unsigned long long value) { - return Color3::fromSrgb(UnsignedInt(value)); + return Color3::fromSrgbInt(UnsignedInt(value)); } /** @relatesalso Magnum::Math::Color4 @@ -1321,8 +1356,7 @@ inline Color4 operator "" _rgbaf(unsigned long long value) { /** @relatesalso Magnum::Math::Color4 @brief Float sRGB + alpha literal -Calls @ref Color4::fromSrgbAlpha(UnsignedInt) on the literal value. Example -usage: +Calls @ref Color4::fromSrgbAlphaInt() on the literal value. Example usage: @snippet MagnumMath.cpp _srgbaf @@ -1331,7 +1365,7 @@ usage: @m_keywords{_srgbaf srgbaf} */ inline Color4 operator "" _srgbaf(unsigned long long value) { - return Color4::fromSrgbAlpha(UnsignedInt(value)); + return Color4::fromSrgbAlphaInt(UnsignedInt(value)); } } diff --git a/src/Magnum/Math/Test/ColorTest.cpp b/src/Magnum/Math/Test/ColorTest.cpp index d48f9b733..b7e4c79c3 100644 --- a/src/Magnum/Math/Test/ColorTest.cpp +++ b/src/Magnum/Math/Test/ColorTest.cpp @@ -874,11 +874,11 @@ void ColorTest::fromIntegralSrgb() { Color4 linear{0.896269f, 0.0231534f, 0.215861f, 0.137255f}; CORRADE_COMPARE(Color3::fromSrgb(srgb.rgb()), linear.rgb()); - CORRADE_COMPARE(Color3::fromSrgb(0xf32a80), linear.rgb()); + CORRADE_COMPARE(Color3::fromSrgbInt(0xf32a80), linear.rgb()); CORRADE_COMPARE(Color4::fromSrgbAlpha(srgb), linear); - CORRADE_COMPARE(Color4::fromSrgbAlpha(0xf32a8023), linear); + CORRADE_COMPARE(Color4::fromSrgbAlphaInt(0xf32a8023), linear); CORRADE_COMPARE(Color4::fromSrgb(srgb.rgb(), 0.175f), (Color4{linear.rgb(), 0.175f})); - CORRADE_COMPARE(Color4::fromSrgb(0xf32a80, 0.175f), (Color4{linear.rgb(), 0.175f})); + CORRADE_COMPARE(Color4::fromSrgbInt(0xf32a80, 0.175f), (Color4{linear.rgb(), 0.175f})); CORRADE_COMPARE(linear.rgb().toSrgb(), srgb.rgb()); CORRADE_COMPARE(linear.rgb().toSrgbInt(), 0xf32a80); @@ -891,12 +891,12 @@ void ColorTest::integralSrgbToIntegral() { Math::Color4 linear{58737, 1517, 14146, 8995}; CORRADE_COMPARE(Math::Color3::fromSrgb(srgb.rgb()), linear.rgb()); - CORRADE_COMPARE(Math::Color3::fromSrgb(0xf32a80), linear.rgb()); + CORRADE_COMPARE(Math::Color3::fromSrgbInt(0xf32a80), linear.rgb()); CORRADE_COMPARE(Math::Color4::fromSrgbAlpha(srgb), linear); - CORRADE_COMPARE(Math::Color4::fromSrgbAlpha(0xf32a8023), linear); + CORRADE_COMPARE(Math::Color4::fromSrgbAlphaInt(0xf32a8023), linear); CORRADE_COMPARE(Math::Color4::fromSrgb(srgb.rgb(), 15299), (Math::Color4{linear.rgb(), 15299})); - CORRADE_COMPARE(Math::Color4::fromSrgb(0xf32a80, 15299), + CORRADE_COMPARE(Math::Color4::fromSrgbInt(0xf32a80, 15299), (Math::Color4{linear.rgb(), 15299})); CORRADE_COMPARE(linear.rgb().toSrgb(), srgb.rgb()); CORRADE_COMPARE(linear.rgb().toSrgbInt(), 0xf32a80); @@ -921,7 +921,7 @@ void ColorTest::srgbMonotonic() { } void ColorTest::srgb8bitRoundtrip() { - CORRADE_COMPARE(Color3::fromSrgb(testCaseRepeatId()).toSrgbInt(), testCaseRepeatId()); + CORRADE_COMPARE(Color3::fromSrgbInt(testCaseRepeatId()).toSrgbInt(), testCaseRepeatId()); } void ColorTest::srgbLiterals() {