src/Quantity/Quantity_Color.hxx

   1 // Created by: NW,JPB,CAL
   2 // Copyright (c) 1991-1999 Matra Datavision
   3 // Copyright (c) 1999-2014 OPEN CASCADE SAS
   4 //
   5 // This file is part of Open CASCADE Technology software library.
   6 //
   7 // This library is free software; you can redistribute it and/or modify it under
   8 // the terms of the GNU Lesser General Public License version 2.1 as published
   9 // by the Free Software Foundation, with special exception defined in the file
  10 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
  11 // distribution for complete text of the license and disclaimer of any warranty.
  12 //
  13 // Alternatively, this file may be used under the terms of Open CASCADE
  14 // commercial license or contractual agreement.
  15
  16 #ifndef _Quantity_Color_HeaderFile
  17 #define _Quantity_Color_HeaderFile
  18
  19 #include <Standard.hxx>
  20 #include <Standard_DefineAlloc.hxx>
  21 #include <Standard_Handle.hxx>
  22
  23 #include <Standard_ShortReal.hxx>
  24 #include <Quantity_NameOfColor.hxx>
  25 #include <Quantity_Parameter.hxx>
  26 #include <Quantity_TypeOfColor.hxx>
  27 #include <Quantity_Rate.hxx>
  28 #include <Standard_Real.hxx>
  29 #include <Standard_Boolean.hxx>
  30 #include <Standard_CString.hxx>
  31 #include <Standard_Integer.hxx>
  32 #include <NCollection_Vec4.hxx>
  33 class Quantity_ColorDefinitionError;
  34
  35
  36 //! This class allows the definition of a colour.
  37 //! The names of the colours are from the X11 specification.
  38 //! color object may be used for numerous applicative purposes.
  39 //! A color is defined by:
  40 //! -   its respective quantities of red, green and blue (R-G-B values), or
  41 //! -   its hue angle and its values of lightness and  saturation (H-L-S values).
  42 //! These two color definition systems are equivalent.
  43 //! Use this class in conjunction with:
  44 //! -   the Quantity_TypeOfColor enumeration
  45 //! which identifies the color definition system you are using,
  46 //! -   the Quantity_NameOfColor enumeration
  47 //! which lists numerous predefined colors and
  48 //! identifies them by their name.
  49 class Quantity_Color
  50 {
  51 public:
  52
  53   DEFINE_STANDARD_ALLOC
  54
  55
  56   //! Creates a colour with the default value of
  57   //! Colour name : YELLOW
  58   Standard_EXPORT Quantity_Color();
  59
  60   //! Creates the colour <AName>.
  61   Standard_EXPORT Quantity_Color(const Quantity_NameOfColor AName);
  62
  63   //! Creates a color according to the definition system theType.
  64   //! Quantity_TOC_RGB:
  65   //!  - theR1 the value of Red   within range [0.0; 1.0]
  66   //!  - theR2 the value of Green within range [0.0; 1.0]
  67   //!  - theR3 the value of Blue  within range [0.0; 1.0]
  68   //!
  69   //! Quantity_TOC_HLS:
  70   //!  - theR1 is the Hue (H) angle in degrees within range [0.0; 360.0], 0.0 being Red.
  71   //!    Value -1.0 is a special value reserved for grayscale color (S should be 0.0).
  72   //!  - theR2 is the Lightness  (L) within range [0.0; 1.0]
  73   //!  - theR3 is the Saturation (S) within range [0.0; 1.0]
  74   Standard_EXPORT Quantity_Color (const Quantity_Parameter   theR1,
  75                                   const Quantity_Parameter   theR2,
  76                                   const Quantity_Parameter   theR3,
  77                                   const Quantity_TypeOfColor theType);
  78
  79   //! Define color from RGB values.
  80   Standard_EXPORT explicit Quantity_Color (const NCollection_Vec3<float>& theRgb);
  81
  82   //! Increases or decreases the contrast by <ADelta>.
  83   //! <ADelta> is a percentage. Any value greater than zero
  84   //! will increase the contrast.
  85   //! The variation is expressed as a percentage of the
  86   //! current value.
  87   //! It is a variation of the saturation.
  88   Standard_EXPORT void ChangeContrast (const Quantity_Rate ADelta);
  89
  90   //! Increases or decreases the intensity by <ADelta>.
  91   //! <ADelta> is a percentage. Any value greater than zero
  92   //! will increase the intensity.
  93   //! The variation is expressed as a percentage of the
  94   //! current value.
  95   //! It is a variation of the lightness.
  96   Standard_EXPORT void ChangeIntensity (const Quantity_Rate ADelta);
  97
  98   //! Updates the colour <me> from the definition of the
  99   //! colour <AName>.
 100   Standard_EXPORT void SetValues (const Quantity_NameOfColor AName);
 101
 102   //! Updates a color according to the mode specified by theType.
 103   //! TOC_RGB:
 104   //!  - theR1 the value of Red   within range [0.0; 1.0]
 105   //!  - theR2 the value of Green within range [0.0; 1.0]
 106   //!  - theR3 the value of Blue  within range [0.0; 1.0]
 107   //!
 108   //! TOC_HLS:
 109   //!  - theR1 is the Hue (H) angle in degrees within range [0.0; 360.0], 0.0 being Red.
 110   //!    -1.0 is a special value reserved for grayscale color (S should be 0.0).
 111   //!  - theR2 is the Lightness  (L) within range [0.0; 1.0]
 112   //!  - theR3 is the Saturation (S) within range [0.0; 1.0]
 113   Standard_EXPORT void SetValues (const Quantity_Parameter   theR1,
 114                                   const Quantity_Parameter   theR2,
 115                                   const Quantity_Parameter   theR3,
 116                                   const Quantity_TypeOfColor theType);
 117
 118   //! Returns the percentage change of contrast and intensity
 119   //! between <me> and <AColor>.
 120   //! <DC> and <DI> are percentages, either positive or negative.
 121   //! The calculation is with respect to the current value of <me>
 122   //! If <DC> is positive then <me> is more contrasty.
 123   //! If <DI> is positive then <me> is more intense.
 124   Standard_EXPORT void Delta (const Quantity_Color& AColor, Quantity_Parameter& DC, Quantity_Parameter& DI) const;
 125
 126   //! Returns the distance between two colours. It's a
 127   //! value between 0 and the square root of 3
 128   //! (the black/white distance)
 129   Standard_EXPORT Standard_Real Distance (const Quantity_Color& AColor) const;
 130
 131   //! Returns the square of distance between two colours.
 132   Standard_EXPORT Standard_Real SquareDistance (const Quantity_Color& AColor) const;
 133
 134   //! Returns the Blue component (quantity of blue) of the color within range [0.0; 1.0].
 135   Standard_EXPORT Quantity_Parameter Blue() const;
 136
 137   //! Returns the Green component (quantity of green) of the color within range [0.0; 1.0].
 138   Standard_EXPORT Quantity_Parameter Green() const;
 139
 140   //! Returns the Hue component (hue angle) of the color
 141   //! in degrees within range [0.0; 360.0], 0.0 being Red.
 142   //! -1.0 is a special value reserved for grayscale color (S should be 0.0)
 143   Standard_EXPORT Quantity_Parameter Hue() const;
 144
 145   //! Returns Standard_True if the distance between <me> and
 146   //! <Other> is greater than Epsilon ().
 147   Standard_EXPORT Standard_Boolean IsDifferent (const Quantity_Color& Other) const;
 148 Standard_Boolean operator != (const Quantity_Color& Other) const
 149 {
 150   return IsDifferent(Other);
 151 }
 152
 153   //! Returns true if the Other color is
 154   //! -   different from, or
 155   //! -   equal to this color.
 156   //! Two colors are considered to be equal if their
 157   //! distance is no greater than Epsilon().
 158   //! These methods are aliases of operator != and operator ==.
 159   Standard_EXPORT Standard_Boolean IsEqual (const Quantity_Color& Other) const;
 160 Standard_Boolean operator == (const Quantity_Color& Other) const
 161 {
 162   return IsEqual(Other);
 163 }
 164
 165   //! Returns the Light component (value of the lightness) of the color within range [0.0; 1.0].
 166   Standard_EXPORT Quantity_Parameter Light() const;
 167
 168   //! Returns the name of the color defined by its
 169   //! quantities of red R, green G and blue B; more
 170   //! precisely this is the nearest color from the
 171   //! Quantity_NameOfColor enumeration.
 172   //! Exceptions
 173   //! Standard_OutOfRange if R, G or B is less than 0. or greater than 1.
 174   Standard_EXPORT Quantity_NameOfColor Name() const;
 175
 176   //! Returns the Red component (quantity of red) of the color within range [0.0; 1.0].
 177   Standard_EXPORT Quantity_Parameter Red() const;
 178
 179   //! Returns the Saturation component (value of the saturation) of the color within range [0.0; 1.0].
 180   Standard_EXPORT Quantity_Parameter Saturation() const;
 181
 182   //! Return the color as vector of 3 float elements.
 183   operator const NCollection_Vec3<float>&() const { return *(const NCollection_Vec3<float>* )this; }
 184
 185   //! Returns in theR1, theR2 and theR3 the components of this color according to the color system definition theType.
 186   //! If theType is Quantity_TOC_RGB:
 187   //!  - theR1 the value of Red   between 0.0 and 1.0
 188   //!  - theR2 the value of Green between 0.0 and 1.0
 189   //!  - theR3 the value of Blue  between 0.0 and 1.0
 190   //! If theType is Quantity_TOC_HLS:
 191   //!  - theR1 is the Hue (H) angle in degrees within range [0.0; 360.0], 0.0 being Red.
 192   //!    -1.0 is a special value reserved for grayscale color (S should be 0.0).
 193   //!  - theR2 is the Lightness  (L) within range [0.0; 1.0]
 194   //!  - theR3 is the Saturation (S) within range [0.0; 1.0]
 195   Standard_EXPORT void Values (Quantity_Parameter& theR1,
 196                                Quantity_Parameter& theR2,
 197                                Quantity_Parameter& theR3,
 198                                const Quantity_TypeOfColor theType) const;
 199
 200   //! Sets the specified value used to compare <me> and
 201   //! an other color in IsDifferent and in IsEqual methods.
 202   //! Warning: The default value is 0.0001
 203   Standard_EXPORT static void SetEpsilon (const Quantity_Parameter AnEpsilon);
 204
 205   //! Returns the specified value used to compare <me> and
 206   //! an other color in IsDifferent and in IsEqual methods.
 207   Standard_EXPORT static Quantity_Parameter Epsilon();
 208
 209   //! Returns the name of the colour for which the RGB components
 210   //! are nearest to <R>, <G> and <B>.
 211   Standard_EXPORT static Quantity_NameOfColor Name (const Quantity_Parameter R, const Quantity_Parameter G, const Quantity_Parameter B);
 212
 213   //! Returns the name of the color identified by
 214   //! AName in the Quantity_NameOfColor enumeration.
 215   //! For example, the name of the color which
 216   //! corresponds to Quantity_NOC_BLACK is "BLACK".
 217   //! Exceptions
 218   //! Standard_OutOfRange if AName in not known
 219   //! in the Quantity_NameOfColor enumeration.
 220   Standard_EXPORT static Standard_CString StringName (const Quantity_NameOfColor AColor);
 221
 222   //! Finds color from predefined names.
 223   //! For example, the name of the color which
 224   //! corresponds to "BLACK" is Quantity_NOC_BLACK.
 225   //! Returns false if name is unknown.
 226   Standard_EXPORT static Standard_Boolean ColorFromName (const Standard_CString theName, Quantity_NameOfColor& theColor);
 227
 228   //! Converts HLS components into RGB ones.
 229   Standard_EXPORT static void HlsRgb (const Quantity_Parameter H, const Quantity_Parameter L, const Quantity_Parameter S, Quantity_Parameter& R, Quantity_Parameter& G, Quantity_Parameter& B);
 230
 231   //! Converts RGB components into HLS ones.
 232   Standard_EXPORT static void RgbHls (const Quantity_Parameter R, const Quantity_Parameter G, const Quantity_Parameter B, Quantity_Parameter& H, Quantity_Parameter& L, Quantity_Parameter& S);
 233
 234   //! Convert the Color value to ARGB integer value.
 235   //! theARGB has Alpha equal to zero, so the output is
 236   //! formatted as 0x00RRGGBB
 237   Standard_EXPORT static void Color2argb (const Quantity_Color& theColor, Standard_Integer& theARGB);
 238
 239   //! Convert integer ARGB value to Color. Alpha bits are ignored
 240   Standard_EXPORT static void Argb2color (const Standard_Integer theARGB, Quantity_Color& theColor);
 241
 242   //! Internal test
 243   Standard_EXPORT static void Test();
 244
 245
 246
 247
 248 protected:
 249
 250
 251
 252
 253
 254 private:
 255
 256
 257   //! Converts HLS components into RGB ones.
 258   Standard_EXPORT static void hlsrgb (const Standard_ShortReal H, const Standard_ShortReal L, const Standard_ShortReal S, Standard_ShortReal& R, Standard_ShortReal& G, Standard_ShortReal& B);
 259
 260   //! Converts RGB components into HLS ones.
 261   Standard_EXPORT static void rgbhls (const Standard_ShortReal R, const Standard_ShortReal G, const Standard_ShortReal B, Standard_ShortReal& H, Standard_ShortReal& L, Standard_ShortReal& S);
 262
 263   //! Returns the values of a predefined colour according to
 264   //! the mode specified by TypeOfColor
 265   //! TOC_RGB : <R1> the value of red between 0. and 1.
 266   //! <R2> the value of green between 0. and 1.
 267   //! <R3> the value of blue between 0. and 1.
 268   //!
 269   //! TOC_HLS : <R1> is the hue angle in degrees, 0. being red
 270   //! <R2> is the lightness between 0. and 1.
 271   //! <R3> is the saturation between 0. and 1.
 272   Standard_EXPORT static void ValuesOf (const Quantity_NameOfColor AName, const Quantity_TypeOfColor AType, Standard_ShortReal& R1, Standard_ShortReal& R2, Standard_ShortReal& R3);
 273
 274
 275   Standard_ShortReal MyRed;
 276   Standard_ShortReal MyGreen;
 277   Standard_ShortReal MyBlue;
 278
 279
 280 };
 281
 282
 283
 284
 285
 286
 287
 288 #endif // _Quantity_Color_HeaderFile