include/tools/color.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19 #ifndef INCLUDED_TOOLS_COLOR_HXX
  20 #define INCLUDED_TOOLS_COLOR_HXX
  21
  22 #include <sal/types.h>
  23 #include <tools/toolsdllapi.h>
  24 #include <com/sun/star/uno/Any.hxx>
  25 #include <config_global.h>
  26 #include <basegfx/color/bcolor.hxx>
  27 #include <osl/endian.h>
  28
  29 namespace color
  30 {
  31
  32 constexpr sal_uInt32 extractRGB(sal_uInt32 nColorNumber)
  33 {
  34     return nColorNumber & 0x00FFFFFF;
  35 }
  36
  37 constexpr sal_uInt8 ColorChannelMerge(sal_uInt8 nDst, sal_uInt8 nSrc, sal_uInt8 nSrcTrans)
  38 {
  39     return sal_uInt8(((sal_Int32(nDst) - nSrc) * nSrcTrans + ((nSrc << 8) | nDst)) >> 8);
  40 }
  41
  42 }
  43
  44 /** used to deliberately select the right constructor */
  45 enum ColorTransparencyTag { ColorTransparency = 0 };
  46 enum ColorAlphaTag { ColorAlpha = 0 };
  47
  48 // Color
  49
  50 class SAL_WARN_UNUSED TOOLS_DLLPUBLIC Color
  51 {
  52     union
  53     {
  54         sal_uInt32 mValue;
  55         struct
  56         {
  57 #ifdef OSL_BIGENDIAN
  58                 sal_uInt8 T;
  59                 sal_uInt8 R;
  60                 sal_uInt8 G;
  61                 sal_uInt8 B;
  62 #else
  63                 sal_uInt8 B;
  64                 sal_uInt8 G;
  65                 sal_uInt8 R;
  66                 sal_uInt8 T;
  67 #endif
  68         };
  69     };
  70
  71 public:
  72     constexpr Color()
  73         : mValue(0) // black
  74     {}
  75
  76 #if HAVE_CPP_CONSTEVAL
  77     consteval
  78 #else
  79     constexpr
  80 #endif
  81     Color(const sal_uInt32 nColor)
  82         : mValue(nColor)
  83     {
  84         assert(nColor <= 0xffffff && "don't pass transparency to this constructor, use the Color(ColorTransparencyTag,...) or Color(ColorAlphaTag,...) constructor to make it explicit");
  85     }
  86
  87     constexpr Color(enum ColorTransparencyTag, sal_uInt32 nColor)
  88         : mValue(nColor)
  89     {
  90     }
  91
  92     constexpr Color(enum ColorAlphaTag, sal_uInt32 nColor)
  93         : mValue((nColor & 0xffffff) | ((255 - (nColor >> 24)) << 24))
  94     {
  95     }
  96
  97     constexpr Color(enum ColorTransparencyTag, sal_uInt8 nTransparency, sal_uInt8 nRed, sal_uInt8 nGreen, sal_uInt8 nBlue)
  98         : mValue(sal_uInt32(nBlue) | (sal_uInt32(nGreen) << 8) | (sal_uInt32(nRed) << 16) | (sal_uInt32(nTransparency) << 24))
  99     {}
 100
 101     constexpr Color(enum ColorAlphaTag, sal_uInt8 nAlpha, sal_uInt8 nRed, sal_uInt8 nGreen, sal_uInt8 nBlue)
 102         : Color(ColorTransparency, 255 - nAlpha, nRed, nGreen, nBlue)
 103     {}
 104
 105     constexpr Color(sal_uInt8 nRed, sal_uInt8 nGreen, sal_uInt8 nBlue)
 106         : Color(ColorTransparency, 0, nRed, nGreen, nBlue)
 107     {}
 108
 109     // constructor to create a tools-Color from ::basegfx::BColor
 110     explicit Color(const basegfx::BColor& rBColor)
 111         : Color(ColorTransparency, 0,
 112                 sal_uInt8(std::lround(rBColor.getRed() * 255.0)),
 113                 sal_uInt8(std::lround(rBColor.getGreen() * 255.0)),
 114                 sal_uInt8(std::lround(rBColor.getBlue() * 255.0)))
 115     {}
 116
 117     /** Casts the color to corresponding uInt32.
 118       * Primarily used when passing Color objects to UNO API
 119       * @return corresponding sal_uInt32
 120       */
 121     constexpr explicit operator sal_uInt32() const
 122     {
 123         return mValue;
 124     }
 125
 126     /** Casts the color to corresponding iInt32.
 127       * If there is no transparency, will be positive.
 128       * @return corresponding sal_Int32
 129       */
 130     constexpr explicit operator sal_Int32() const
 131     {
 132         return sal_Int32(mValue);
 133     }
 134
 135     /* Basic RGBA operations */
 136
 137     /** Gets the red value.
 138       * @return R
 139       */
 140     sal_uInt8 GetRed() const
 141     {
 142         return R;
 143     }
 144
 145     /** Gets the green value.
 146       * @return G
 147       */
 148     sal_uInt8 GetGreen() const
 149     {
 150         return G;
 151     }
 152
 153     /** Gets the blue value.
 154       * @return B
 155       */
 156     sal_uInt8 GetBlue() const
 157     {
 158         return B;
 159     }
 160
 161     /** Gets the alpha value.
 162       * @return A
 163       */
 164     sal_uInt8 GetAlpha() const
 165     {
 166         return 255 - T;
 167     }
 168
 169     /** Is the color transparent?
 170      */
 171     bool IsTransparent() const
 172     {
 173         return GetAlpha() != 255;
 174     }
 175
 176     /** Is the color fully transparent i.e. 100% transparency ?
 177      */
 178     bool IsFullyTransparent() const
 179     {
 180         return T == 255;
 181     }
 182
 183     /** Sets the red value.
 184       * @param nRed
 185       */
 186     void SetRed(sal_uInt8 nRed)
 187     {
 188         R = nRed;
 189     }
 190
 191     /** Sets the green value.
 192       * @param nGreen
 193       */
 194     void SetGreen(sal_uInt8 nGreen)
 195     {
 196         G = nGreen;
 197     }
 198
 199     /** Sets the blue value.
 200       * @param nBlue
 201       */
 202     void SetBlue(sal_uInt8 nBlue)
 203     {
 204         B = nBlue;
 205     }
 206
 207     /** Sets the alpha value.
 208       * @param nAlpha
 209       */
 210     void SetAlpha(sal_uInt8 nAlpha)
 211     {
 212         T = 255 - nAlpha;
 213     }
 214
 215     /** Returns the same color but ignoring the transparency value.
 216       * @return RGB version
 217       */
 218     Color GetRGBColor() const
 219     {
 220         return {R, G, B};
 221     }
 222
 223     /* Comparison and operators */
 224
 225     /** Check if the color RGB value is equal than rColor.
 226       * @param rColor
 227       * @return is equal
 228       */
 229     bool IsRGBEqual( const Color& rColor ) const
 230     {
 231         return ( mValue & 0x00FFFFFF ) == ( rColor.mValue & 0x00FFFFFF );
 232     }
 233
 234     /** Check if the color value is lower than aCompareColor.
 235       * @param aCompareColor
 236       * @return is lower
 237       */
 238     bool operator<(const Color& aCompareColor) const
 239     {
 240         return mValue < aCompareColor.mValue;
 241     }
 242
 243     /** Check if the color value is greater than aCompareColor.
 244       * @param aCompareColor
 245       * @return is greater
 246       */
 247     bool operator>(const Color& aCompareColor) const
 248     {
 249         return mValue > aCompareColor.mValue;
 250     }
 251
 252     /** Check if the color value is equal than rColor.
 253       * @param rColor
 254       * @return is equal
 255       */
 256     bool operator==(const Color& rColor) const
 257     {
 258         return mValue == rColor.mValue;
 259     }
 260
 261     /** Check if the color value is unequal than rColor.
 262       * @param rColor
 263       * @return is unequal
 264       */
 265     bool operator!=(const Color& rColor) const
 266     {
 267         return mValue != rColor.mValue;
 268     }
 269
 270     /** Gets the color error compared to another.
 271       * It describes how different they are.
 272       * It takes the abs of differences in parameters.
 273       * @param rCompareColor
 274       * @return error
 275       */
 276     sal_uInt16 GetColorError(const Color& rCompareColor) const
 277     {
 278     return static_cast<sal_uInt16>(
 279         abs(static_cast<int>(GetBlue()) - rCompareColor.GetBlue()) +
 280         abs(static_cast<int>(GetGreen()) - rCompareColor.GetGreen()) +
 281         abs(static_cast<int>(GetRed()) - rCompareColor.GetRed()));
 282     }
 283
 284     /* Light and contrast */
 285
 286     /** Gets the color luminance. It means perceived brightness.
 287       * @return luminance
 288       */
 289     sal_uInt8 GetLuminance() const
 290     {
 291         return sal_uInt8((B * 29UL + G * 151UL + R * 76UL) >> 8);
 292     }
 293
 294     /** Increases the color luminance by cLumInc.
 295       * @param cLumInc
 296       */
 297     void IncreaseLuminance(sal_uInt8 cLumInc);
 298
 299     /** Decreases the color luminance by cLumDec.
 300       * @param cLumDec
 301       */
 302     void DecreaseLuminance(sal_uInt8 cLumDec);
 303
 304     /** Decreases color contrast with white by cContDec.
 305       * @param cContDec
 306       */
 307     void DecreaseContrast(sal_uInt8 cContDec);
 308
 309     /** Comparison with luminance thresholds.
 310       * @return is dark
 311       */
 312     bool IsDark() const
 313     {
 314         // 62 is the number that means it also triggers on Ubuntu in dark mode
 315         return GetLuminance() <= 62;
 316     }
 317
 318     /** Comparison with luminance thresholds.
 319       * @return is dark
 320       */
 321     bool IsBright() const
 322     {
 323         return GetLuminance() >= 245;
 324     }
 325
 326     /* Color filters */
 327
 328     /**
 329      * Apply tint or shade to a color.
 330      *
 331      * The input value is the percentage (in 100th of percent) of how much the
 332      * color changes towards the black (shade) or white (tint). If the value
 333      * is positive, the color is tinted, if the value is negative, the color is
 334      * shaded.
 335      **/
 336     void ApplyTintOrShade(sal_Int16 n100thPercent);
 337
 338     /**
 339      * Apply luminance offset and/or modulation.
 340      *
 341      * The input values are in percentages (in 100th percents). 100% modulation and 0% offset
 342      * results in no change.
 343      */
 344     void ApplyLumModOff(sal_Int16 nMod, sal_Int16 nOff);
 345
 346     /** Inverts color. 1 and 0 are switched.
 347       * Note that the result will be the complementary color.
 348       * For example, if you have red, you will get cyan: FF0000 -> 00FFFF.
 349       */
 350     void Invert()
 351     {
 352         R = ~R;
 353         G = ~G;
 354         B = ~B;
 355     }
 356
 357     /** Merges color with rMergeColor.
 358       * Allows to get resulting color when superposing another.
 359       * @param rMergeColor
 360       * @param cTransparency
 361       */
 362     void Merge(const Color& rMergeColor, sal_uInt8 cTransparency)
 363     {
 364         R = color::ColorChannelMerge(R, rMergeColor.R, cTransparency);
 365         G = color::ColorChannelMerge(G, rMergeColor.G, cTransparency);
 366         B = color::ColorChannelMerge(B, rMergeColor.B, cTransparency);
 367     }
 368
 369     /* Change of format */
 370
 371     /** Color space conversion tools
 372       * The range for h/s/b is:
 373       *   - Hue: 0-360 degree
 374       *   - Saturation: 0-100%
 375       *   - Brightness: 0-100%
 376       * @param nHue
 377       * @param nSaturation
 378       * @param nBrightness
 379       * @return rgb color
 380       */
 381     static Color HSBtoRGB(sal_uInt16 nHue, sal_uInt16 nSaturation, sal_uInt16 nBrightness);
 382
 383     /** Converts a string into a color. Supports:
 384       * #RRGGBB
 385       * #rrggbb
 386       * #RGB
 387       * #rgb
 388       * RRGGBB
 389       * rrggbb
 390       * RGB
 391       * rgb
 392       * If fails returns Color().
 393       */
 394     static Color STRtoRGB(std::u16string_view colorname);
 395
 396     /** Color space conversion tools
 397       * @param nHue
 398       * @param nSaturation
 399       * @param nBrightness
 400       */
 401     void RGBtoHSB(sal_uInt16& nHue, sal_uInt16& nSaturation, sal_uInt16& nBrightness) const;
 402
 403     /* Return color as RGB hex string: rrggbb
 404      * for example "00ff00" for green color
 405      * @return hex string
 406      */
 407     OUString AsRGBHexString() const;
 408
 409     /* Return color as RGB hex string: RRGGBB
 410      * for example "00FF00" for green color
 411      * @return hex string
 412      */
 413     OUString AsRGBHEXString() const;
 414
 415     /* get ::basegfx::BColor from this color
 416      * @return basegfx color
 417      */
 418     basegfx::BColor getBColor() const
 419     {
 420         return basegfx::BColor(R / 255.0, G / 255.0, B / 255.0);
 421     }
 422 };
 423
 424 // to reduce the noise when moving these into and out of Any
 425 inline bool operator >>=( const css::uno::Any & rAny, Color & value )
 426 {
 427   sal_Int32 nTmp = {}; // spurious -Werror=maybe-uninitialized
 428   if (!(rAny >>= nTmp))
 429       return false;
 430   value = Color(ColorTransparency, nTmp);
 431   return true;
 432 }
 433
 434 inline void operator <<=( css::uno::Any & rAny, Color value )
 435 {
 436     rAny <<= sal_Int32(value);
 437 }
 438
 439 namespace com::sun::star::uno {
 440     template<> inline Any::Any(Color const & value): Any(sal_Int32(value)) {}
 441 }
 442
 443 // Test compile time conversion of Color to sal_uInt32
 444
 445 static_assert (sal_uInt32(Color(ColorTransparency, 0x00, 0x12, 0x34, 0x56)) == 0x00123456);
 446 static_assert (sal_uInt32(Color(0x12, 0x34, 0x56)) == 0x00123456);
 447
 448 // Color types
 449
 450 inline constexpr ::Color COL_TRANSPARENT             ( ColorTransparency, 0xFF, 0xFF, 0xFF, 0xFF );
 451 inline constexpr ::Color COL_AUTO                    ( ColorTransparency, 0xFF, 0xFF, 0xFF, 0xFF );
 452 inline constexpr ::Color COL_BLACK                   ( 0x00, 0x00, 0x00 );
 453 inline constexpr ::Color COL_BLUE                    ( 0x00, 0x00, 0x80 );
 454 inline constexpr ::Color COL_GREEN                   ( 0x00, 0x80, 0x00 );
 455 inline constexpr ::Color COL_CYAN                    ( 0x00, 0x80, 0x80 );
 456 inline constexpr ::Color COL_RED                     ( 0x80, 0x00, 0x00 );
 457 inline constexpr ::Color COL_MAGENTA                 ( 0x80, 0x00, 0x80 );
 458 inline constexpr ::Color COL_BROWN                   ( 0x80, 0x80, 0x00 );
 459 inline constexpr ::Color COL_GRAY                    ( 0x80, 0x80, 0x80 );
 460 inline constexpr ::Color COL_GRAY3                   ( 0xCC, 0xCC, 0xCC );
 461 inline constexpr ::Color COL_GRAY7                   ( 0x66, 0x66, 0x66 );
 462 inline constexpr ::Color COL_LIGHTGRAY               ( 0xC0, 0xC0, 0xC0 );
 463 inline constexpr ::Color COL_LIGHTBLUE               ( 0x00, 0x00, 0xFF );
 464 inline constexpr ::Color COL_LIGHTGREEN              ( 0x00, 0xFF, 0x00 );
 465 inline constexpr ::Color COL_LIGHTCYAN               ( 0x00, 0xFF, 0xFF );
 466 inline constexpr ::Color COL_LIGHTRED                ( 0xFF, 0x00, 0x00 );
 467 inline constexpr ::Color COL_LIGHTMAGENTA            ( 0xFF, 0x00, 0xFF );
 468 inline constexpr ::Color COL_LIGHTGRAYBLUE           ( 0xE0, 0xE0, 0xFF );
 469 inline constexpr ::Color COL_YELLOW                  ( 0xFF, 0xFF, 0x00 );
 470 inline constexpr ::Color COL_WHITE                   ( 0xFF, 0xFF, 0xFF );
 471 inline constexpr ::Color COL_AUTHOR1_DARK            ( 0xC6, 0x92, 0x00 );
 472 inline constexpr ::Color COL_AUTHOR1_NORMAL          ( 0xFF, 0xFF, 0x9E );
 473 inline constexpr ::Color COL_AUTHOR1_LIGHT           ( 0xFF, 0xFF, 0xC3 );
 474 inline constexpr ::Color COL_AUTHOR2_DARK            ( 0x06, 0x46, 0xA2 );
 475 inline constexpr ::Color COL_AUTHOR2_NORMAL          ( 0xD8, 0xE8, 0xFF );
 476 inline constexpr ::Color COL_AUTHOR2_LIGHT           ( 0xE9, 0xF2, 0xFF );
 477 inline constexpr ::Color COL_AUTHOR3_DARK            ( 0x57, 0x9D, 0x1C );
 478 inline constexpr ::Color COL_AUTHOR3_NORMAL          ( 0xDA, 0xF8, 0xC1 );
 479 inline constexpr ::Color COL_AUTHOR3_LIGHT           ( 0xE2, 0xFA, 0xCF );
 480 inline constexpr ::Color COL_AUTHOR4_DARK            ( 0x69, 0x2B, 0x9D );
 481 inline constexpr ::Color COL_AUTHOR4_NORMAL          ( 0xE4, 0xD2, 0xF5 );
 482 inline constexpr ::Color COL_AUTHOR4_LIGHT           ( 0xEF, 0xE4, 0xF8 );
 483 inline constexpr ::Color COL_AUTHOR5_DARK            ( 0xC5, 0x00, 0x0B );
 484 inline constexpr ::Color COL_AUTHOR5_NORMAL          ( 0xFE, 0xCD, 0xD0 );
 485 inline constexpr ::Color COL_AUTHOR5_LIGHT           ( 0xFF, 0xE3, 0xE5 );
 486 inline constexpr ::Color COL_AUTHOR6_DARK            ( 0x00, 0x80, 0x80 );
 487 inline constexpr ::Color COL_AUTHOR6_NORMAL          ( 0xD2, 0xF6, 0xF6 );
 488 inline constexpr ::Color COL_AUTHOR6_LIGHT           ( 0xE6, 0xFA, 0xFA );
 489 inline constexpr ::Color COL_AUTHOR7_DARK            ( 0x8C, 0x84, 0x00 );
 490 inline constexpr ::Color COL_AUTHOR7_NORMAL          ( 0xED, 0xFC, 0xA3 );
 491 inline constexpr ::Color COL_AUTHOR7_LIGHT           ( 0xF2, 0xFE, 0xB5 );
 492 inline constexpr ::Color COL_AUTHOR8_DARK            ( 0x35, 0x55, 0x6B );
 493 inline constexpr ::Color COL_AUTHOR8_NORMAL          ( 0xD3, 0xDE, 0xE8 );
 494 inline constexpr ::Color COL_AUTHOR8_LIGHT           ( 0xE2, 0xEA, 0xF1 );
 495 inline constexpr ::Color COL_AUTHOR9_DARK            ( 0xD1, 0x76, 0x00 );
 496 inline constexpr ::Color COL_AUTHOR9_NORMAL          ( 0xFF, 0xE2, 0xB9 );
 497 inline constexpr ::Color COL_AUTHOR9_LIGHT           ( 0xFF, 0xE7, 0xC7 );
 498 inline constexpr ::Color COL_AUTHOR_TABLE_INS        ( 0xE1, 0xF2, 0xFA );
 499 inline constexpr ::Color COL_AUTHOR_TABLE_DEL        ( 0xFC, 0xE6, 0xF4 );
 500
 501 template<typename charT, typename traits>
 502 inline std::basic_ostream<charT, traits>& operator <<(std::basic_ostream<charT, traits>& rStream, const Color& rColor)
 503 {
 504     std::ios_base::fmtflags nOrigFlags = rStream.flags();
 505     rStream << "rgba[" << std::hex << std::setfill ('0')
 506             << std::setw(2) << static_cast<int>(rColor.GetRed())
 507             << std::setw(2) << static_cast<int>(rColor.GetGreen())
 508             << std::setw(2) << static_cast<int>(rColor.GetBlue())
 509             << std::setw(2) << static_cast<int>(rColor.GetAlpha()) << "]";
 510     rStream.setf(nOrigFlags);
 511     return rStream;
 512 }
 513
 514 #endif
 515
 516 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */