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 #ifndef INCLUDED_BASEGFX_COLOR_BCOLORMODIFIER_HXX
  21 #define INCLUDED_BASEGFX_COLOR_BCOLORMODIFIER_HXX
  22
  23 #include <basegfx/basegfxdllapi.h>
  24 #include <basegfx/color/bcolor.hxx>
  25
  26 #include <osl/diagnose.h>
  27
  28 #include <memory>
  29 #include <vector>
  30
  31 namespace basegfx
  32 {
  33     /** base class to define color modifications
  34
  35         The basic idea is to have instances of color modifiers where each
  36         of these can be asked to get a modified version of a color. This
  37         can be as easy as to return a fixed color, but may also do any
  38         other computation based on the given source color and the local
  39         algorithm to apply.
  40
  41         This base implementation defines the abstract base class. Every
  42         derivation offers another color blending effect, when needed with
  43         parameters for that blending defined as members.
  44
  45         As long as aw080 is not applied, an operator== is needed to implement
  46         the operator== of the primitive based on this instances.
  47
  48         For the exact definitions of the color blending applied refer to the
  49         implementation of the method getModifiedColor
  50
  51         BColorModifier is not copyable (no copy constructor, no assignment
  52         operator); local values cannot be changed after construction. The
  53         instances are cheap and the idea is to create them on demand. To
  54         be able to reuse these as much as possible, a define for a
  55         std::shared_ptr named BColorModifierSharedPtr exists below.
  56         All usages should handle instances of BColorModifier encapsulated
  57         into these shared pointers.
  58     */
  59     class SAL_WARN_UNUSED BASEGFX_DLLPUBLIC BColorModifier
  60     {
  61     private:
  62         BColorModifier(const BColorModifier&) = delete;
  63         BColorModifier& operator=(const BColorModifier&) = delete;
  64     protected:
  65         // no one is allowed to incarnate the abstract base class
  66         // except derivations
  67         BColorModifier() {}
  68
  69     public:
  70         // no one should directly destroy it; all incarnations should be
  71         // handled in a std::shared_ptr of type BColorModifierSharedPtr
  72         virtual ~BColorModifier();
  73
  74         // compare operator
  75         virtual bool operator==(const BColorModifier& rCompare) const = 0;
  76         bool operator!=(const BColorModifier& rCompare) const
  77         {
  78             return !(operator==(rCompare));
  79         }
  80
  81         // compute modified color
  82         virtual ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& aSourceColor) const = 0;
  83     };
  84
  85     /** convert color to gray
  86     */
  87     class SAL_WARN_UNUSED BASEGFX_DLLPUBLIC BColorModifier_gray final : public BColorModifier
  88     {
  89     public:
  90         BColorModifier_gray()
  91         :   BColorModifier()
  92         {
  93         }
  94
  95         virtual ~BColorModifier_gray() override;
  96
  97         // compare operator
  98         virtual bool operator==(const BColorModifier& rCompare) const override;
  99
 100         // compute modified color
 101         virtual ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& aSourceColor) const override;
 102     };
 103
 104     /** invert color
 105
 106         returns a color where red green and blue are inverted using 1.0 - n
 107     */
 108     class SAL_WARN_UNUSED BASEGFX_DLLPUBLIC BColorModifier_invert final : public BColorModifier
 109     {
 110     public:
 111         BColorModifier_invert()
 112         :   BColorModifier()
 113         {
 114         }
 115
 116         virtual ~BColorModifier_invert() override;
 117
 118         // compare operator
 119         virtual bool operator==(const BColorModifier& rCompare) const override;
 120
 121         // compute modified color
 122         virtual ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& aSourceColor) const override;
 123     };
 124
 125     /** convert to alpha based on luminance
 126
 127         returns a color where red green and blue are first weighted and added
 128         to build a luminance value which is then inverted and used for red,
 129         green and blue. The weights are  r * 0.2125 + g * 0.7154 + b * 0.0721.
 130         This derivation is used for the svg importer and does exactly what SVG
 131         defines for this needed case.
 132     */
 133     class SAL_WARN_UNUSED BASEGFX_DLLPUBLIC BColorModifier_luminance_to_alpha final : public BColorModifier
 134     {
 135     public:
 136         BColorModifier_luminance_to_alpha()
 137         :   BColorModifier()
 138         {
 139         }
 140
 141         virtual ~BColorModifier_luminance_to_alpha() override;
 142
 143         // compare operator
 144         virtual bool operator==(const BColorModifier& rCompare) const override;
 145
 146         // compute modified color
 147         virtual ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& aSourceColor) const override;
 148     };
 149
 150     /** replace color
 151
 152         does not use the source color at all, but always returns the
 153         given color, replacing everything. Useful e.g. for unified shadow
 154         creation
 155     */
 156     class SAL_WARN_UNUSED BASEGFX_DLLPUBLIC BColorModifier_replace final : public BColorModifier
 157     {
 158     private:
 159         ::basegfx::BColor           maBColor;
 160
 161     public:
 162         BColorModifier_replace(const ::basegfx::BColor& rBColor)
 163         :   BColorModifier(),
 164             maBColor(rBColor)
 165         {
 166         }
 167
 168         virtual ~BColorModifier_replace() override;
 169
 170         // data access
 171         const ::basegfx::BColor& getBColor() const { return maBColor; }
 172
 173         // compare operator
 174         virtual bool operator==(const BColorModifier& rCompare) const override;
 175
 176         // compute modified color
 177         virtual ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& aSourceColor) const override;
 178     };
 179
 180     /** interpolate color
 181
 182         returns an interpolated color mixed by the given value (f) in the range
 183         [0.0 .. 1.0] and the given color (col) as follows:
 184
 185         col * (1 - f) + aSourceColor * f
 186     */
 187     class SAL_WARN_UNUSED BASEGFX_DLLPUBLIC BColorModifier_interpolate final : public BColorModifier
 188     {
 189     private:
 190         ::basegfx::BColor           maBColor;
 191         double                      mfValue;
 192
 193     public:
 194         BColorModifier_interpolate(const ::basegfx::BColor& rBColor, double fValue)
 195         :   BColorModifier(),
 196             maBColor(rBColor),
 197             mfValue(fValue)
 198         {
 199         }
 200
 201         virtual ~BColorModifier_interpolate() override;
 202
 203         // data access
 204         const ::basegfx::BColor& getBColor() const { return maBColor; }
 205         double getValue() const { return mfValue; }
 206
 207         // compare operator
 208         virtual bool operator==(const BColorModifier& rCompare) const override;
 209
 210         // compute modified color
 211         virtual ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& aSourceColor) const override;
 212     };
 213
 214     /** convert color to black and white
 215
 216         returns black when the luminance of the given color is less than
 217         the given threshold value in the range [0.0 .. 1.0], else white
 218     */
 219     class SAL_WARN_UNUSED BASEGFX_DLLPUBLIC BColorModifier_black_and_white final : public BColorModifier
 220     {
 221     private:
 222         double                      mfValue;
 223
 224     public:
 225         BColorModifier_black_and_white(double fValue)
 226         :   BColorModifier(),
 227             mfValue(fValue)
 228         {
 229         }
 230
 231         virtual ~BColorModifier_black_and_white() override;
 232
 233         // data access
 234         double getValue() const { return mfValue; }
 235
 236         // compare operator
 237         virtual bool operator==(const BColorModifier& rCompare) const override;
 238
 239         // compute modified color
 240         virtual ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& aSourceColor) const override;
 241     };
 242
 243     /** gamma correction
 244
 245         Input is a gamma correction value in the range ]0.0 .. 10.0]; the
 246         color values get corrected using
 247
 248         col(r,g,b) = clamp(pow(col(r,g,b), 1.0 / gamma), 0.0, 1.0)
 249     */
 250     class SAL_WARN_UNUSED BASEGFX_DLLPUBLIC BColorModifier_gamma final : public BColorModifier
 251     {
 252     private:
 253         double                      mfValue;
 254         double                      mfInvValue;
 255
 256         bool                        mbUseIt : 1;
 257
 258     public:
 259         BColorModifier_gamma(double fValue);
 260
 261         virtual ~BColorModifier_gamma() override;
 262
 263         // data access
 264         double getValue() const { return mfValue; }
 265
 266         // compare operator
 267         virtual bool operator==(const BColorModifier& rCompare) const override;
 268
 269         // compute modified color
 270         virtual ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& aSourceColor) const override;
 271     };
 272
 273     /** Red, Green, Blue, Luminance and Contrast correction
 274
 275         Input are percent values from [-1.0 .. 1-0] which correspond to -100% to 100%
 276         correction of Red, Green, Blue, Luminance or Contrast. 0.0 means no change of
 277         the corresponding channel. All these are combined (but can be used single) to
 278         - be able to cover a bigger change range utilizing the combination
 279         - allow execution by a small, common, precalculated table
 280     */
 281     class SAL_WARN_UNUSED BASEGFX_DLLPUBLIC BColorModifier_RGBLuminanceContrast final : public BColorModifier
 282     {
 283     private:
 284         double                      mfRed;
 285         double                      mfGreen;
 286         double                      mfBlue;
 287         double                      mfLuminance;
 288         double                      mfContrast;
 289
 290         double                      mfContrastOff;
 291         double                      mfRedOff;
 292         double                      mfGreenOff;
 293         double                      mfBlueOff;
 294
 295         bool                        mbUseIt : 1;
 296
 297     public:
 298         BColorModifier_RGBLuminanceContrast(double fRed, double fGreen, double fBlue, double fLuminance, double fContrast);
 299
 300         virtual ~BColorModifier_RGBLuminanceContrast() override;
 301
 302         // data access
 303         double getRed() const { return mfRed; }
 304         double getGreen() const { return mfGreen; }
 305         double getBlue() const { return mfBlue; }
 306         double getLuminance() const { return mfLuminance; }
 307         double getContrast() const { return mfContrast; }
 308
 309         // compare operator
 310         virtual bool operator==(const BColorModifier& rCompare) const override;
 311
 312         // compute modified color
 313         virtual ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& aSourceColor) const override;
 314     };
 315
 316     /// typedef to allow working with shared instances of BColorModifier
 317     /// for the whole mechanism
 318     typedef std::shared_ptr< BColorModifier > BColorModifierSharedPtr;
 319
 320     /** Class to hold a stack of BColorModifierSharedPtrs and to get the modified color with
 321         applying all existing entry changes as defined in the stack. Instances of BColorModifier
 322         can be pushed and popped to change the stack.
 323
 324         All references to BColorModifier members use shared pointers, thus instances of
 325         BColorModifierStack can be copied by the default mechanisms if needed.
 326     */
 327     class BASEGFX_DLLPUBLIC BColorModifierStack final
 328     {
 329         ::std::vector< BColorModifierSharedPtr >        maBColorModifiers;
 330
 331     public:
 332         sal_uInt32 count() const
 333         {
 334             return maBColorModifiers.size();
 335         }
 336
 337         const BColorModifierSharedPtr& getBColorModifier(sal_uInt32 nIndex) const
 338         {
 339             OSL_ENSURE(nIndex < count(), "BColorModifierStack: Access out of range (!)");
 340             return maBColorModifiers[nIndex];
 341         }
 342
 343         // get the color in its modified form by applying all existing BColorModifiers,
 344         // from back to front (the newest first)
 345         ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& rSource) const;
 346
 347         void push(const BColorModifierSharedPtr& rNew)
 348         {
 349             maBColorModifiers.push_back(rNew);
 350         }
 351
 352         void pop()
 353         {
 354             maBColorModifiers.pop_back();
 355         }
 356     };
 357 } // end of namespace basegfx
 358
 359
 360 #endif // INCLUDED_BASEGFX_COLOR_BCOLORMODIFIER_HXX
 361
 362 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */