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/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         {
  92         }
  93
  94         virtual ~BColorModifier_gray() override;
  95
  96         // compare operator
  97         virtual bool operator==(const BColorModifier& rCompare) const override;
  98
  99         // compute modified color
 100         virtual ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& aSourceColor) const override;
 101     };
 102
 103     /** invert color
 104
 105         returns a color where red green and blue are inverted using 1.0 - n
 106     */
 107     class SAL_WARN_UNUSED BASEGFX_DLLPUBLIC BColorModifier_invert final : public BColorModifier
 108     {
 109     public:
 110         BColorModifier_invert()
 111         {
 112         }
 113
 114         virtual ~BColorModifier_invert() override;
 115
 116         // compare operator
 117         virtual bool operator==(const BColorModifier& rCompare) const override;
 118
 119         // compute modified color
 120         virtual ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& aSourceColor) const override;
 121     };
 122
 123     /** convert to alpha based on luminance
 124
 125         returns a color where red green and blue are first weighted and added
 126         to build a luminance value which is then inverted and used for red,
 127         green and blue. The weights are  r * 0.2125 + g * 0.7154 + b * 0.0721.
 128         This derivation is used for the svg importer and does exactly what SVG
 129         defines for this needed case.
 130     */
 131     class SAL_WARN_UNUSED BASEGFX_DLLPUBLIC BColorModifier_luminance_to_alpha final : public BColorModifier
 132     {
 133     public:
 134         BColorModifier_luminance_to_alpha()
 135         {
 136         }
 137
 138         virtual ~BColorModifier_luminance_to_alpha() override;
 139
 140         // compare operator
 141         virtual bool operator==(const BColorModifier& rCompare) const override;
 142
 143         // compute modified color
 144         virtual ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& aSourceColor) const override;
 145     };
 146
 147     /** replace color
 148
 149         does not use the source color at all, but always returns the
 150         given color, replacing everything. Useful e.g. for unified shadow
 151         creation
 152     */
 153     class SAL_WARN_UNUSED BASEGFX_DLLPUBLIC BColorModifier_replace final : public BColorModifier
 154     {
 155     private:
 156         ::basegfx::BColor           maBColor;
 157
 158     public:
 159         BColorModifier_replace(const ::basegfx::BColor& rBColor)
 160         :   maBColor(rBColor)
 161         {
 162         }
 163
 164         virtual ~BColorModifier_replace() override;
 165
 166         // data access
 167         const ::basegfx::BColor& getBColor() const { return maBColor; }
 168
 169         // compare operator
 170         virtual bool operator==(const BColorModifier& rCompare) const override;
 171
 172         // compute modified color
 173         virtual ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& aSourceColor) const override;
 174     };
 175
 176     /** interpolate color
 177
 178         returns an interpolated color mixed by the given value (f) in the range
 179         [0.0 .. 1.0] and the given color (col) as follows:
 180
 181         col * (1 - f) + aSourceColor * f
 182     */
 183     class SAL_WARN_UNUSED BASEGFX_DLLPUBLIC BColorModifier_interpolate final : public BColorModifier
 184     {
 185     private:
 186         ::basegfx::BColor           maBColor;
 187         double                      mfValue;
 188
 189     public:
 190         BColorModifier_interpolate(const ::basegfx::BColor& rBColor, double fValue)
 191         :   maBColor(rBColor),
 192             mfValue(fValue)
 193         {
 194         }
 195
 196         virtual ~BColorModifier_interpolate() override;
 197
 198         // compare operator
 199         virtual bool operator==(const BColorModifier& rCompare) const override;
 200
 201         // compute modified color
 202         virtual ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& aSourceColor) const override;
 203     };
 204
 205     /** convert color to black and white
 206
 207         returns black when the luminance of the given color is less than
 208         the given threshold value in the range [0.0 .. 1.0], else white
 209     */
 210     class SAL_WARN_UNUSED UNLESS_MERGELIBS(BASEGFX_DLLPUBLIC) BColorModifier_black_and_white final : public BColorModifier
 211     {
 212     private:
 213         double                      mfValue;
 214
 215     public:
 216         BColorModifier_black_and_white(double fValue)
 217         :   mfValue(fValue)
 218         {
 219         }
 220
 221         virtual ~BColorModifier_black_and_white() override;
 222
 223         // compare operator
 224         virtual bool operator==(const BColorModifier& rCompare) const override;
 225
 226         // compute modified color
 227         virtual ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& aSourceColor) const override;
 228     };
 229
 230     /** gamma correction
 231
 232         Input is a gamma correction value in the range ]0.0 .. 10.0]; the
 233         color values get corrected using
 234
 235         col(r,g,b) = clamp(pow(col(r,g,b), 1.0 / gamma), 0.0, 1.0)
 236     */
 237     class SAL_WARN_UNUSED UNLESS_MERGELIBS(BASEGFX_DLLPUBLIC) BColorModifier_gamma final : public BColorModifier
 238     {
 239     private:
 240         double                      mfValue;
 241         double                      mfInvValue;
 242
 243         bool                        mbUseIt : 1;
 244
 245     public:
 246         BColorModifier_gamma(double fValue);
 247
 248         virtual ~BColorModifier_gamma() override;
 249
 250         // compare operator
 251         virtual bool operator==(const BColorModifier& rCompare) const override;
 252
 253         // compute modified color
 254         virtual ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& aSourceColor) const override;
 255     };
 256
 257     /** Red, Green, Blue, Luminance and Contrast correction
 258
 259         Input are percent values from [-1.0 .. 1-0] which correspond to -100% to 100%
 260         correction of Red, Green, Blue, Luminance or Contrast. 0.0 means no change of
 261         the corresponding channel. All these are combined (but can be used single) to
 262         - be able to cover a bigger change range utilizing the combination
 263         - allow execution by a small, common, precalculated table
 264     */
 265     class SAL_WARN_UNUSED UNLESS_MERGELIBS(BASEGFX_DLLPUBLIC) BColorModifier_RGBLuminanceContrast final : public BColorModifier
 266     {
 267     private:
 268         double                      mfRed;
 269         double                      mfGreen;
 270         double                      mfBlue;
 271         double                      mfLuminance;
 272         double                      mfContrast;
 273
 274         double                      mfContrastOff;
 275         double                      mfRedOff;
 276         double                      mfGreenOff;
 277         double                      mfBlueOff;
 278
 279         bool                        mbUseIt : 1;
 280
 281     public:
 282         BColorModifier_RGBLuminanceContrast(double fRed, double fGreen, double fBlue, double fLuminance, double fContrast);
 283
 284         virtual ~BColorModifier_RGBLuminanceContrast() override;
 285
 286         // compare operator
 287         virtual bool operator==(const BColorModifier& rCompare) const override;
 288
 289         // compute modified color
 290         virtual ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& aSourceColor) const override;
 291     };
 292
 293     /// typedef to allow working with shared instances of BColorModifier
 294     /// for the whole mechanism
 295     typedef std::shared_ptr< BColorModifier > BColorModifierSharedPtr;
 296
 297     /** Class to hold a stack of BColorModifierSharedPtrs and to get the modified color with
 298         applying all existing entry changes as defined in the stack. Instances of BColorModifier
 299         can be pushed and popped to change the stack.
 300
 301         All references to BColorModifier members use shared pointers, thus instances of
 302         BColorModifierStack can be copied by the default mechanisms if needed.
 303     */
 304     class BASEGFX_DLLPUBLIC BColorModifierStack final
 305     {
 306         ::std::vector< BColorModifierSharedPtr >        maBColorModifiers;
 307
 308     public:
 309         sal_uInt32 count() const
 310         {
 311             return maBColorModifiers.size();
 312         }
 313
 314         const BColorModifierSharedPtr& getBColorModifier(sal_uInt32 nIndex) const
 315         {
 316             OSL_ENSURE(nIndex < count(), "BColorModifierStack: Access out of range (!)");
 317             return maBColorModifiers[nIndex];
 318         }
 319
 320         // get the color in its modified form by applying all existing BColorModifiers,
 321         // from back to front (the newest first)
 322         ::basegfx::BColor getModifiedColor(const ::basegfx::BColor& rSource) const;
 323
 324         void push(const BColorModifierSharedPtr& rNew)
 325         {
 326             maBColorModifiers.push_back(rNew);
 327         }
 328
 329         void pop()
 330         {
 331             maBColorModifiers.pop_back();
 332         }
 333     };
 334 } // end of namespace basegfx
 335
 336 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */