juce/source/src/gui/graphics/colour/juce_Colour.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_COLOUR_JUCEHEADER__
  27 #define __JUCE_COLOUR_JUCEHEADER__
  28
  29 #include "../colour/juce_PixelFormats.h"
  30
  31
  32 //==============================================================================
  33 /**
  34     Represents a colour, also including a transparency value.
  35
  36     The colour is stored internally as unsigned 8-bit red, green, blue and alpha values.
  37 */
  38 class JUCE_API  Colour
  39 {
  40 public:
  41     //==============================================================================
  42     /** Creates a transparent black colour. */
  43     Colour() noexcept;
  44
  45     /** Creates a copy of another Colour object. */
  46     Colour (const Colour& other) noexcept;
  47
  48     /** Creates a colour from a 32-bit ARGB value.
  49
  50         The format of this number is:
  51             ((alpha << 24) | (red << 16) | (green << 8) | blue).
  52
  53         All components in the range 0x00 to 0xff.
  54         An alpha of 0x00 is completely transparent, alpha of 0xff is opaque.
  55
  56         @see getPixelARGB
  57     */
  58     explicit Colour (uint32 argb) noexcept;
  59
  60     /** Creates an opaque colour using 8-bit red, green and blue values */
  61     Colour (uint8 red,
  62             uint8 green,
  63             uint8 blue) noexcept;
  64
  65     /** Creates an opaque colour using 8-bit red, green and blue values */
  66     static Colour fromRGB (uint8 red,
  67                            uint8 green,
  68                            uint8 blue) noexcept;
  69
  70     /** Creates a colour using 8-bit red, green, blue and alpha values. */
  71     Colour (uint8 red,
  72             uint8 green,
  73             uint8 blue,
  74             uint8 alpha) noexcept;
  75
  76     /** Creates a colour using 8-bit red, green, blue and alpha values. */
  77     static Colour fromRGBA (uint8 red,
  78                             uint8 green,
  79                             uint8 blue,
  80                             uint8 alpha) noexcept;
  81
  82     /** Creates a colour from 8-bit red, green, and blue values, and a floating-point alpha.
  83
  84         Alpha of 0.0 is transparent, alpha of 1.0f is opaque.
  85         Values outside the valid range will be clipped.
  86     */
  87     Colour (uint8 red,
  88             uint8 green,
  89             uint8 blue,
  90             float alpha) noexcept;
  91
  92     /** Creates a colour using 8-bit red, green, blue and float alpha values. */
  93     static Colour fromRGBAFloat (uint8 red,
  94                                  uint8 green,
  95                                  uint8 blue,
  96                                  float alpha) noexcept;
  97
  98     /** Creates a colour using floating point hue, saturation and brightness values, and an 8-bit alpha.
  99
 100         The floating point values must be between 0.0 and 1.0.
 101         An alpha of 0x00 is completely transparent, alpha of 0xff is opaque.
 102         Values outside the valid range will be clipped.
 103     */
 104     Colour (float hue,
 105             float saturation,
 106             float brightness,
 107             uint8 alpha) noexcept;
 108
 109     /** Creates a colour using floating point hue, saturation, brightness and alpha values.
 110
 111         All values must be between 0.0 and 1.0.
 112         Numbers outside the valid range will be clipped.
 113     */
 114     Colour (float hue,
 115             float saturation,
 116             float brightness,
 117             float alpha) noexcept;
 118
 119     /** Creates a colour using floating point hue, saturation and brightness values, and an 8-bit alpha.
 120
 121         The floating point values must be between 0.0 and 1.0.
 122         An alpha of 0x00 is completely transparent, alpha of 0xff is opaque.
 123         Values outside the valid range will be clipped.
 124     */
 125     static Colour fromHSV (float hue,
 126                            float saturation,
 127                            float brightness,
 128                            float alpha) noexcept;
 129
 130     /** Destructor. */
 131     ~Colour() noexcept;
 132
 133     /** Copies another Colour object. */
 134     Colour& operator= (const Colour& other) noexcept;
 135
 136     /** Compares two colours. */
 137     bool operator== (const Colour& other) const noexcept;
 138     /** Compares two colours. */
 139     bool operator!= (const Colour& other) const noexcept;
 140
 141     //==============================================================================
 142     /** Returns the red component of this colour.
 143
 144         @returns a value between 0x00 and 0xff.
 145     */
 146     uint8 getRed() const noexcept                       { return argb.getRed(); }
 147
 148     /** Returns the green component of this colour.
 149
 150         @returns a value between 0x00 and 0xff.
 151     */
 152     uint8 getGreen() const noexcept                     { return argb.getGreen(); }
 153
 154     /** Returns the blue component of this colour.
 155
 156         @returns a value between 0x00 and 0xff.
 157     */
 158     uint8 getBlue() const noexcept                      { return argb.getBlue(); }
 159
 160     /** Returns the red component of this colour as a floating point value.
 161
 162         @returns a value between 0.0 and 1.0
 163     */
 164     float getFloatRed() const noexcept;
 165
 166     /** Returns the green component of this colour as a floating point value.
 167
 168         @returns a value between 0.0 and 1.0
 169     */
 170     float getFloatGreen() const noexcept;
 171
 172     /** Returns the blue component of this colour as a floating point value.
 173
 174         @returns a value between 0.0 and 1.0
 175     */
 176     float getFloatBlue() const noexcept;
 177
 178     /** Returns a premultiplied ARGB pixel object that represents this colour.
 179     */
 180     const PixelARGB getPixelARGB() const noexcept;
 181
 182     /** Returns a 32-bit integer that represents this colour.
 183
 184         The format of this number is:
 185             ((alpha << 24) | (red << 16) | (green << 16) | blue).
 186     */
 187     uint32 getARGB() const noexcept;
 188
 189     //==============================================================================
 190     /** Returns the colour's alpha (opacity).
 191
 192         Alpha of 0x00 is completely transparent, 0xff is completely opaque.
 193     */
 194     uint8 getAlpha() const noexcept                     { return argb.getAlpha(); }
 195
 196     /** Returns the colour's alpha (opacity) as a floating point value.
 197
 198         Alpha of 0.0 is completely transparent, 1.0 is completely opaque.
 199     */
 200     float getFloatAlpha() const noexcept;
 201
 202     /** Returns true if this colour is completely opaque.
 203
 204         Equivalent to (getAlpha() == 0xff).
 205     */
 206     bool isOpaque() const noexcept;
 207
 208     /** Returns true if this colour is completely transparent.
 209
 210         Equivalent to (getAlpha() == 0x00).
 211     */
 212     bool isTransparent() const noexcept;
 213
 214     /** Returns a colour that's the same colour as this one, but with a new alpha value. */
 215     Colour withAlpha (uint8 newAlpha) const noexcept;
 216
 217     /** Returns a colour that's the same colour as this one, but with a new alpha value. */
 218     Colour withAlpha (float newAlpha) const noexcept;
 219
 220     /** Returns a colour that's the same colour as this one, but with a modified alpha value.
 221
 222         The new colour's alpha will be this object's alpha multiplied by the value passed-in.
 223     */
 224     Colour withMultipliedAlpha (float alphaMultiplier) const noexcept;
 225
 226     //==============================================================================
 227     /** Returns a colour that is the result of alpha-compositing a new colour over this one.
 228
 229         If the foreground colour is semi-transparent, it is blended onto this colour
 230         accordingly.
 231     */
 232     Colour overlaidWith (const Colour& foregroundColour) const noexcept;
 233
 234     /** Returns a colour that lies somewhere between this one and another.
 235
 236         If amountOfOther is zero, the result is 100% this colour, if amountOfOther
 237         is 1.0, the result is 100% of the other colour.
 238     */
 239     Colour interpolatedWith (const Colour& other, float proportionOfOther) const noexcept;
 240
 241     //==============================================================================
 242     /** Returns the colour's hue component.
 243         The value returned is in the range 0.0 to 1.0
 244     */
 245     float getHue() const noexcept;
 246
 247     /** Returns the colour's saturation component.
 248         The value returned is in the range 0.0 to 1.0
 249     */
 250     float getSaturation() const noexcept;
 251
 252     /** Returns the colour's brightness component.
 253         The value returned is in the range 0.0 to 1.0
 254     */
 255     float getBrightness() const noexcept;
 256
 257     /** Returns the colour's hue, saturation and brightness components all at once.
 258         The values returned are in the range 0.0 to 1.0
 259     */
 260     void getHSB (float& hue,
 261                  float& saturation,
 262                  float& brightness) const noexcept;
 263
 264     //==============================================================================
 265     /** Returns a copy of this colour with a different hue. */
 266     Colour withHue (float newHue) const noexcept;
 267
 268     /** Returns a copy of this colour with a different saturation. */
 269     Colour withSaturation (float newSaturation) const noexcept;
 270
 271     /** Returns a copy of this colour with a different brightness.
 272         @see brighter, darker, withMultipliedBrightness
 273     */
 274     Colour withBrightness (float newBrightness) const noexcept;
 275
 276     /** Returns a copy of this colour with it hue rotated.
 277
 278         The new colour's hue is ((this->getHue() + amountToRotate) % 1.0)
 279
 280         @see brighter, darker, withMultipliedBrightness
 281     */
 282     Colour withRotatedHue (float amountToRotate) const noexcept;
 283
 284     /** Returns a copy of this colour with its saturation multiplied by the given value.
 285
 286         The new colour's saturation is (this->getSaturation() * multiplier)
 287         (the result is clipped to legal limits).
 288     */
 289     Colour withMultipliedSaturation (float multiplier) const noexcept;
 290
 291     /** Returns a copy of this colour with its brightness multiplied by the given value.
 292
 293         The new colour's saturation is (this->getBrightness() * multiplier)
 294         (the result is clipped to legal limits).
 295     */
 296     Colour withMultipliedBrightness (float amount) const noexcept;
 297
 298     //==============================================================================
 299     /** Returns a brighter version of this colour.
 300
 301         @param amountBrighter   how much brighter to make it - a value from 0 to 1.0 where 0 is
 302                                 unchanged, and higher values make it brighter
 303         @see withMultipliedBrightness
 304     */
 305     Colour brighter (float amountBrighter = 0.4f) const noexcept;
 306
 307     /** Returns a darker version of this colour.
 308
 309         @param amountDarker     how much darker to make it - a value from 0 to 1.0 where 0 is
 310                                 unchanged, and higher values make it darker
 311         @see withMultipliedBrightness
 312     */
 313     Colour darker (float amountDarker = 0.4f) const noexcept;
 314
 315     //==============================================================================
 316     /** Returns a colour that will be clearly visible against this colour.
 317
 318         The amount parameter indicates how contrasting the new colour should
 319         be, so e.g. Colours::black.contrasting (0.1f) will return a colour
 320         that's just a little bit lighter; Colours::black.contrasting (1.0f) will
 321         return white; Colours::white.contrasting (1.0f) will return black, etc.
 322     */
 323     Colour contrasting (float amount = 1.0f) const noexcept;
 324
 325     /** Returns a colour that contrasts against two colours.
 326
 327         Looks for a colour that contrasts with both of the colours passed-in.
 328
 329         Handy for things like choosing a highlight colour in text editors, etc.
 330     */
 331     static Colour contrasting (const Colour& colour1,
 332                                const Colour& colour2) noexcept;
 333
 334     //==============================================================================
 335     /** Returns an opaque shade of grey.
 336
 337         @param brightness the level of grey to return - 0 is black, 1.0 is white
 338     */
 339     static Colour greyLevel (float brightness) noexcept;
 340
 341     //==============================================================================
 342     /** Returns a stringified version of this colour.
 343
 344         The string can be turned back into a colour using the fromString() method.
 345     */
 346     String toString() const;
 347
 348     /** Reads the colour from a string that was created with toString().
 349     */
 350     static Colour fromString (const String& encodedColourString);
 351
 352     /** Returns the colour as a hex string in the form RRGGBB or AARRGGBB. */
 353     String toDisplayString (bool includeAlphaValue) const;
 354
 355 private:
 356     //==============================================================================
 357     PixelARGB argb;
 358 };
 359
 360
 361 #endif   // __JUCE_COLOUR_JUCEHEADER__