include/basegfx/color/bcolormodifier.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
  20 #pragma once
  21
  22 #include <config_options.h>
  23 #include <basegfx/basegfxdllapi.h>
  24 #include <basegfx/matrix/b3dhommatrix.hxx>
  25 #include <basegfx/color/bcolor.hxx>
  26 #include <rtl/ustring.hxx>
  27
  28 #include <osl/diagnose.h>
  29
  30 #include <memory>
  31 #include <vector>
  32
  33 namespace basegfx
  34 {
  35     enum class BColorModifierType : sal_uInt16 {
  36         BCMType_gray,
  37         BCMType_invert,
  38         BCMType_luminance_to_alpha,
  39         BCMType_replace,
  40         BCMType_interpolate,
  41         BCMType_saturate,
  42         BCMType_matrix,
  43         BCMType_hueRotate,
  44         BCMType_black_and_white,
  45         BCMType_gamma,
  46         BCMType_RGBLuminanceContrast,
  47         BCMType_randomize
  48     };
  49
  50     /** base class to define color modifications
  51
  52         The basic idea is to have instances of color modifiers where each
  53         of these can be asked to get a modified version of a color. This
  54         can be as easy as to return a fixed color, but may also do any
  55         other computation based on the given source color and the local
  56         algorithm to apply.
  57
  58         This base implementation defines the abstract base class. Every
  59         derivation offers another color blending effect, when needed with
  60         parameters for that blending defined as members.
  61
  62         As long as aw080 is not applied, an operator== is needed to implement
  63         the operator== of the primitive based on this instances.
  64
  65         For the exact definitions of the color blending applied refer to the
  66         implementation of the method getModifiedColor
  67
  68         BColorModifier is not copyable (no copy constructor, no assignment
  69         operator); local values cannot be changed after construction. The
  70         instances are cheap and the idea is to create them on demand. To
  71         be able to reuse these as much as possible, a define for a
  72         std::shared_ptr named BColorModifierSharedPtr exists below.
  73         All usages should handle instances of BColorModifier encapsulated
  74         into these shared pointers.
  75     */
  76     class SAL_WARN_UNUSED BASEGFX_DLLPUBLIC BColorModifier
  77     {
  78     private:
  79         BColorModifierType  maType;
  80         BColorModifier(const BColorModifier&) = delete;
  81         BColorModifier& operator=(const BColorModifier&) = delete;
  82     protected:
  83         // no one is allowed to incarnate the abstract base class
  84         // except derivations
  85         BColorModifier(BColorModifierType aType)
  86         : maType(aType)
  87         {
  88         }
  89
  90     public:
  91         // no one should directly destroy it; all incarnations should be
  92         // handled in a std::shared_ptr of type BColorModifierSharedPtr
  93         virtual ~BColorModifier();
  94
  95         // compare operator
  96         virtual bool operator==(const BColorModifier& rCompare) const
  97         {
  98             if (maType != rCompare.maType)
  99                 return false;
 100
 101             return true;
 102         }
 103
 104         bool operator!=(const BColorModifier& rCompare) const
 105         {
 106             if (maType != rCompare.maType)
 107                 return true;
 108
 109             return !(operator==(rCompare));
 110         }
 111
 112         // compute modified color
 113         virtual ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& aSourceColor) const = 0;
 114
 115         virtual OUString getModifierName() const = 0;
 116
 117         // return type
 118         BColorModifierType getBColorModifierType() const { return maType; }
 119     };
 120
 121     /** convert color to gray
 122     */
 123     class SAL_WARN_UNUSED BASEGFX_DLLPUBLIC BColorModifier_gray final : public BColorModifier
 124     {
 125     public:
 126         BColorModifier_gray()
 127         : BColorModifier(basegfx::BColorModifierType::BCMType_gray)
 128         {
 129         }
 130
 131         virtual ~BColorModifier_gray() override;
 132
 133         // compute modified color
 134         SAL_DLLPRIVATE virtual ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& aSourceColor) const override;
 135         SAL_DLLPRIVATE virtual OUString getModifierName() const override;
 136     };
 137
 138     /** invert color
 139
 140         returns a color where red green and blue are inverted using 1.0 - n
 141     */
 142     class SAL_WARN_UNUSED BASEGFX_DLLPUBLIC BColorModifier_invert final : public BColorModifier
 143     {
 144     public:
 145         BColorModifier_invert()
 146         : BColorModifier(basegfx::BColorModifierType::BCMType_invert)
 147         {
 148         }
 149
 150         virtual ~BColorModifier_invert() override;
 151
 152         // compute modified color
 153         SAL_DLLPRIVATE virtual ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& aSourceColor) const override;
 154         SAL_DLLPRIVATE virtual OUString getModifierName() const override;
 155     };
 156
 157     /** convert to alpha based on luminance
 158
 159         returns a color where red green and blue are first weighted and added
 160         to build a luminance value which is then inverted and used for red,
 161         green and blue. The weights are  r * 0.2125 + g * 0.7154 + b * 0.0721.
 162         This derivation is used for the svg importer and does exactly what SVG
 163         defines for this needed case.
 164     */
 165     class SAL_WARN_UNUSED BASEGFX_DLLPUBLIC BColorModifier_luminance_to_alpha final : public BColorModifier
 166     {
 167     public:
 168         BColorModifier_luminance_to_alpha()
 169         : BColorModifier(basegfx::BColorModifierType::BCMType_luminance_to_alpha)
 170         {
 171         }
 172
 173         virtual ~BColorModifier_luminance_to_alpha() override;
 174
 175         // compute modified color
 176         SAL_DLLPRIVATE virtual ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& aSourceColor) const override;
 177         SAL_DLLPRIVATE virtual OUString getModifierName() const override;
 178     };
 179
 180     /** replace color
 181
 182         does not use the source color at all, but always returns the
 183         given color, replacing everything. Useful e.g. for unified shadow
 184         creation
 185     */
 186     class SAL_WARN_UNUSED BASEGFX_DLLPUBLIC BColorModifier_replace final : public BColorModifier
 187     {
 188     private:
 189         ::basegfx::BColor           maBColor;
 190
 191     public:
 192         BColorModifier_replace(const ::basegfx::BColor& rBColor)
 193         : BColorModifier(basegfx::BColorModifierType::BCMType_replace)
 194         , maBColor(rBColor)
 195         {
 196         }
 197
 198         virtual ~BColorModifier_replace() override;
 199
 200         // data access
 201         const ::basegfx::BColor& getBColor() const { return maBColor; }
 202
 203         // compare operator
 204         SAL_DLLPRIVATE virtual bool operator==(const BColorModifier& rCompare) const override;
 205
 206         // compute modified color
 207         SAL_DLLPRIVATE virtual ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& aSourceColor) const override;
 208         SAL_DLLPRIVATE virtual OUString getModifierName() const override;
 209     };
 210
 211     /** interpolate color
 212
 213         returns an interpolated color mixed by the given value (f) in the range
 214         [0.0 .. 1.0] and the given color (col) as follows:
 215
 216         col * (1 - f) + aSourceColor * f
 217     */
 218     class SAL_WARN_UNUSED BASEGFX_DLLPUBLIC BColorModifier_interpolate final : public BColorModifier
 219     {
 220     private:
 221         ::basegfx::BColor           maBColor;
 222         double                      mfValue;
 223
 224     public:
 225         BColorModifier_interpolate(const ::basegfx::BColor& rBColor, double fValue)
 226         : BColorModifier(basegfx::BColorModifierType::BCMType_interpolate)
 227         , maBColor(rBColor)
 228         , mfValue(fValue)
 229         {
 230         }
 231
 232         virtual ~BColorModifier_interpolate() override;
 233
 234         // compare operator
 235         SAL_DLLPRIVATE virtual bool operator==(const BColorModifier& rCompare) const override;
 236
 237         // compute modified color
 238         SAL_DLLPRIVATE virtual ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& aSourceColor) const override;
 239         SAL_DLLPRIVATE virtual OUString getModifierName() const override;
 240     };
 241
 242     /** Apply saturation
 243         This derivation is used for the svg importer and does exactly what SVG
 244         defines for this needed case.
 245
 246         See:
 247         https://www.w3.org/TR/filter-effects/#elementdef-fecolormatrix
 248     */
 249     class SAL_WARN_UNUSED BASEGFX_DLLPUBLIC BColorModifier_saturate final : public BColorModifier
 250     {
 251     private:
 252         basegfx::B3DHomMatrix       maSatMatrix;
 253
 254     public:
 255         BColorModifier_saturate(double fValue);
 256
 257         virtual ~BColorModifier_saturate() override;
 258
 259         // compare operator
 260         SAL_DLLPRIVATE virtual bool operator==(const BColorModifier& rCompare) const override;
 261
 262         // compute modified color
 263         SAL_DLLPRIVATE virtual ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& aSourceColor) const override;
 264         SAL_DLLPRIVATE virtual OUString getModifierName() const override;
 265     };
 266
 267     /** Apply matrix
 268         This derivation is used for the svg importer and does exactly what SVG
 269         defines for this needed case.
 270
 271         See:
 272         https://www.w3.org/TR/filter-effects/#elementdef-fecolormatrix
 273     */
 274     class SAL_WARN_UNUSED BASEGFX_DLLPUBLIC BColorModifier_matrix final : public BColorModifier
 275     {
 276     private:
 277         std::vector<double>       maVector;
 278
 279     public:
 280         BColorModifier_matrix(std::vector<double> aVector)
 281         : BColorModifier(basegfx::BColorModifierType::BCMType_matrix)
 282         , maVector(std::move(aVector))
 283         {
 284         }
 285
 286         virtual ~BColorModifier_matrix() override;
 287
 288         // compare operator
 289         SAL_DLLPRIVATE virtual bool operator==(const BColorModifier& rCompare) const override;
 290         // compute modified color
 291         SAL_DLLPRIVATE virtual ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& aSourceColor) const override;
 292         SAL_DLLPRIVATE virtual OUString getModifierName() const override;
 293     };
 294
 295     /** Apply hueRotate
 296         This derivation is used for the svg importer and does exactly what SVG
 297         defines for this needed case.
 298
 299         See:
 300         https://www.w3.org/TR/filter-effects/#elementdef-fecolormatrix
 301     */
 302     class SAL_WARN_UNUSED BASEGFX_DLLPUBLIC BColorModifier_hueRotate final : public BColorModifier
 303     {
 304     private:
 305         basegfx::B3DHomMatrix       maHueMatrix;
 306
 307     public:
 308         BColorModifier_hueRotate(double fRad);
 309
 310         virtual ~BColorModifier_hueRotate() override;
 311
 312         // compare operator
 313         SAL_DLLPRIVATE virtual bool operator==(const BColorModifier& rCompare) const override;
 314
 315         // compute modified color
 316         SAL_DLLPRIVATE virtual ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& aSourceColor) const override;
 317         SAL_DLLPRIVATE virtual OUString getModifierName() const override;
 318     };
 319
 320     /** convert color to black and white
 321
 322         returns black when the luminance of the given color is less than
 323         the given threshold value in the range [0.0 .. 1.0], else white
 324     */
 325     class SAL_WARN_UNUSED BASEGFX_DLLPUBLIC BColorModifier_black_and_white final : public BColorModifier
 326     {
 327     private:
 328         double                      mfValue;
 329
 330     public:
 331         BColorModifier_black_and_white(double fValue)
 332         : BColorModifier(basegfx::BColorModifierType::BCMType_black_and_white)
 333         , mfValue(fValue)
 334         {
 335         }
 336
 337         virtual ~BColorModifier_black_and_white() override;
 338
 339         // compare operator
 340         SAL_DLLPRIVATE virtual bool operator==(const BColorModifier& rCompare) const override;
 341
 342         // compute modified color
 343         SAL_DLLPRIVATE virtual ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& aSourceColor) const override;
 344         SAL_DLLPRIVATE virtual OUString getModifierName() const override;
 345     };
 346
 347     /** gamma correction
 348
 349         Input is a gamma correction value in the range ]0.0 .. 10.0]; the
 350         color values get corrected using
 351
 352         col(r,g,b) = clamp(pow(col(r,g,b), 1.0 / gamma), 0.0, 1.0)
 353     */
 354     class SAL_WARN_UNUSED UNLESS_MERGELIBS(BASEGFX_DLLPUBLIC) BColorModifier_gamma final : public BColorModifier
 355     {
 356     private:
 357         double                      mfValue;
 358         double                      mfInvValue;
 359
 360         bool                        mbUseIt : 1;
 361
 362     public:
 363         BColorModifier_gamma(double fValue);
 364
 365         virtual ~BColorModifier_gamma() override;
 366
 367         // compare operator
 368         SAL_DLLPRIVATE virtual bool operator==(const BColorModifier& rCompare) const override;
 369
 370         // compute modified color
 371         virtual ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& aSourceColor) const override;
 372         SAL_DLLPRIVATE virtual OUString getModifierName() const override;
 373     };
 374
 375     /** Red, Green, Blue, Luminance and Contrast correction
 376
 377         Input are percent values from [-1.0 .. 1-0] which correspond to -100% to 100%
 378         correction of Red, Green, Blue, Luminance or Contrast. 0.0 means no change of
 379         the corresponding channel. All these are combined (but can be used single) to
 380         - be able to cover a bigger change range utilizing the combination
 381         - allow execution by a small, common, precalculated table
 382     */
 383     class SAL_WARN_UNUSED UNLESS_MERGELIBS(BASEGFX_DLLPUBLIC) BColorModifier_RGBLuminanceContrast final : public BColorModifier
 384     {
 385     private:
 386         double                      mfRed;
 387         double                      mfGreen;
 388         double                      mfBlue;
 389         double                      mfLuminance;
 390         double                      mfContrast;
 391
 392         double                      mfContrastOff;
 393         double                      mfRedOff;
 394         double                      mfGreenOff;
 395         double                      mfBlueOff;
 396
 397         bool                        mbUseIt : 1;
 398
 399     public:
 400         BColorModifier_RGBLuminanceContrast(double fRed, double fGreen, double fBlue, double fLuminance, double fContrast);
 401
 402         virtual ~BColorModifier_RGBLuminanceContrast() override;
 403
 404         // compare operator
 405         SAL_DLLPRIVATE virtual bool operator==(const BColorModifier& rCompare) const override;
 406
 407         // compute modified color
 408         SAL_DLLPRIVATE virtual ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& aSourceColor) const override;
 409         SAL_DLLPRIVATE virtual OUString getModifierName() const override;
 410     };
 411
 412     /** mix a part of the original color with randomized color (mainly for debug visualizations)
 413     */
 414     class SAL_WARN_UNUSED UNLESS_MERGELIBS(BASEGFX_DLLPUBLIC) BColorModifier_randomize final : public BColorModifier
 415     {
 416     private:
 417         // [0.0 .. 1.0] where 0.0 is no randomize, 1.0 is all random and in-between
 418         // describes the mixed part. Default is 0.1 which means to mix with 10% random color
 419         double                      mfRandomPart;
 420
 421     public:
 422         BColorModifier_randomize(double fRandomPart = 0.1);
 423
 424         virtual ~BColorModifier_randomize() override;
 425
 426         // compare operator
 427         SAL_DLLPRIVATE virtual bool operator==(const BColorModifier& rCompare) const override;
 428
 429         // compute modified color
 430         SAL_DLLPRIVATE virtual ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& aSourceColor) const override;
 431         SAL_DLLPRIVATE virtual OUString getModifierName() const override;
 432     };
 433
 434     /// typedef to allow working with shared instances of BColorModifier
 435     /// for the whole mechanism
 436     typedef std::shared_ptr< BColorModifier > BColorModifierSharedPtr;
 437
 438     /** Class to hold a stack of BColorModifierSharedPtrs and to get the modified color with
 439         applying all existing entry changes as defined in the stack. Instances of BColorModifier
 440         can be pushed and popped to change the stack.
 441
 442         All references to BColorModifier members use shared pointers, thus instances of
 443         BColorModifierStack can be copied by the default mechanisms if needed.
 444     */
 445     class BASEGFX_DLLPUBLIC BColorModifierStack final
 446     {
 447         ::std::vector< BColorModifierSharedPtr >        maBColorModifiers;
 448
 449     public:
 450         sal_uInt32 count() const
 451         {
 452             return maBColorModifiers.size();
 453         }
 454
 455         const BColorModifierSharedPtr& getBColorModifier(sal_uInt32 nIndex) const
 456         {
 457             OSL_ENSURE(nIndex < count(), "BColorModifierStack: Access out of range (!)");
 458             return maBColorModifiers[nIndex];
 459         }
 460
 461         // get the color in its modified form by applying all existing BColorModifiers,
 462         // from back to front (the newest first)
 463         ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& rSource) const;
 464
 465         void push(const BColorModifierSharedPtr& rNew)
 466         {
 467             maBColorModifiers.push_back(rNew);
 468         }
 469
 470         void pop()
 471         {
 472             maBColorModifiers.pop_back();
 473         }
 474
 475         bool operator==(const BColorModifierStack& rComp) const;
 476     };
 477 } // end of namespace basegfx
 478
 479 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */