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 colour according to the definition system
  64   //! TypeOfColor.
  65   //! TOC_RGB : <R1> the value of red between 0. and 1.
  66   //! <R2> the value of green between 0. and 1.
  67   //! <R3> the value of blue between 0. and 1.
  68   //!
  69   //! TOC_HLS : <R1> is the hue angle in degrees, 0. being red
  70   //! <R2> is the lightness between 0. and 1.
  71   //! <R3> is the saturation between 0. and 1.
  72   Standard_EXPORT Quantity_Color(const Quantity_Parameter R1, const Quantity_Parameter R2, const Quantity_Parameter R3, const Quantity_TypeOfColor AType);
  73
  74   //! Define color from RGB values.
  75   Standard_EXPORT explicit Quantity_Color (const NCollection_Vec3<float>& theRgb);
  76
  77   //! Increases or decreases the contrast by <ADelta>.
  78   //! <ADelta> is a percentage. Any value greater than zero
  79   //! will increase the contrast.
  80   //! The variation is expressed as a percentage of the
  81   //! current value.
  82   //! It is a variation of the saturation.
  83   Standard_EXPORT void ChangeContrast (const Quantity_Rate ADelta);
  84
  85   //! Increases or decreases the intensity by <ADelta>.
  86   //! <ADelta> is a percentage. Any value greater than zero
  87   //! will increase the intensity.
  88   //! The variation is expressed as a percentage of the
  89   //! current value.
  90   //! It is a variation of the lightness.
  91   Standard_EXPORT void ChangeIntensity (const Quantity_Rate ADelta);
  92
  93   //! Updates the colour <me> from the definition of the
  94   //! colour <AName>.
  95   Standard_EXPORT void SetValues (const Quantity_NameOfColor AName);
  96
  97   //! Updates a colour according to the mode specified by
  98   //! TypeOfColor
  99   //! TOC_RGB : <R1> the value of red between 0. and 1.
 100   //! <R2> the value of green between 0. and 1.
 101   //! <R3> the value of blue between 0. and 1.
 102   //!
 103   //! TOC_HLS : <R1> is the hue angle in degrees, 0. being red
 104   //! <R2> is the lightness between 0. and 1.
 105   //! <R3> is the saturation between 0. and 1.
 106   Standard_EXPORT void SetValues (const Quantity_Parameter R1, const Quantity_Parameter R2, const Quantity_Parameter R3, const Quantity_TypeOfColor AType);
 107
 108   //! Returns the percentage change of contrast and intensity
 109   //! between <me> and <AColor>.
 110   //! <DC> and <DI> are percentages, either positive or negative.
 111   //! The calculation is with respect to the current value of <me>
 112   //! If <DC> is positive then <me> is more contrasty.
 113   //! If <DI> is positive then <me> is more intense.
 114   Standard_EXPORT void Delta (const Quantity_Color& AColor, Quantity_Parameter& DC, Quantity_Parameter& DI) const;
 115
 116   //! Returns the distance between two colours. It's a
 117   //! value between 0 and the square root of 3
 118   //! (the black/white distance)
 119   Standard_EXPORT Standard_Real Distance (const Quantity_Color& AColor) const;
 120
 121   //! Returns the square of distance between two colours.
 122   Standard_EXPORT Standard_Real SquareDistance (const Quantity_Color& AColor) const;
 123
 124   //! Returns the Blue component (quantity of blue) of the
 125   //! color <me>.
 126   Standard_EXPORT Quantity_Parameter Blue() const;
 127
 128   //! Returns the Green component (quantity of green) of the
 129   //! color <me>.
 130   Standard_EXPORT Quantity_Parameter Green() const;
 131
 132   //! Returns the Hue component (hue angle) of the
 133   //! color <me>.
 134   Standard_EXPORT Quantity_Parameter Hue() const;
 135
 136   //! Returns Standard_True if the distance between <me> and
 137   //! <Other> is greater than Epsilon ().
 138   Standard_EXPORT Standard_Boolean IsDifferent (const Quantity_Color& Other) const;
 139 Standard_Boolean operator != (const Quantity_Color& Other) const
 140 {
 141   return IsDifferent(Other);
 142 }
 143
 144   //! Returns true if the Other color is
 145   //! -   different from, or
 146   //! -   equal to this color.
 147   //! Two colors are considered to be equal if their
 148   //! distance is no greater than Epsilon().
 149   //! These methods are aliases of operator != and operator ==.
 150   Standard_EXPORT Standard_Boolean IsEqual (const Quantity_Color& Other) const;
 151 Standard_Boolean operator == (const Quantity_Color& Other) const
 152 {
 153   return IsEqual(Other);
 154 }
 155
 156   //! Returns the Light component (value of the lightness) of the
 157   //! color <me>.
 158   Standard_EXPORT Quantity_Parameter Light() const;
 159
 160   //! Returns the name of the color defined by its
 161   //! quantities of red R, green G and blue B; more
 162   //! precisely this is the nearest color from the
 163   //! Quantity_NameOfColor enumeration.
 164   //! Exceptions
 165   //! Standard_OutOfRange if R, G or B is less than 0. or greater than 1.
 166   Standard_EXPORT Quantity_NameOfColor Name() const;
 167
 168   //! Returns the Red component (quantity of red) of the
 169   //! color <me>.
 170   Standard_EXPORT Quantity_Parameter Red() const;
 171
 172   //! Returns the Saturation component (value of the saturation)
 173   //! of the color <me>.
 174   Standard_EXPORT Quantity_Parameter Saturation() const;
 175
 176   //! Return the color as vector of 3 float elements.
 177   operator const NCollection_Vec3<float>&() const { return *(const NCollection_Vec3<float>* )this; }
 178
 179   //! Returns in R1, R2 and R3 the components of
 180   //! this color according to the color system definition AType.
 181   //! -   if AType is Quantity_TOC_RGB R1 is the
 182   //! quantity of red, R2 is the quantity of green and
 183   //! R3 is the quantity of blue in this color.
 184   //! -   if AType is Quantity_TOC_HLS R1 is the
 185   //! hue angle in degrees (0 being red), R2 is the
 186   //! lightness and R3 is the saturation of this color.
 187   Standard_EXPORT void Values (Quantity_Parameter& R1, Quantity_Parameter& R2, Quantity_Parameter& R3, const Quantity_TypeOfColor AType) const;
 188
 189   //! Sets the specified value used to compare <me> and
 190   //! an other color in IsDifferent and in IsEqual methods.
 191   //! Warning: The default value is 0.0001
 192   Standard_EXPORT static void SetEpsilon (const Quantity_Parameter AnEpsilon);
 193
 194   //! Returns the specified value used to compare <me> and
 195   //! an other color in IsDifferent and in IsEqual methods.
 196   Standard_EXPORT static Quantity_Parameter Epsilon();
 197
 198   //! Returns the name of the colour for which the RGB components
 199   //! are nearest to <R>, <G> and <B>.
 200   Standard_EXPORT static Quantity_NameOfColor Name (const Quantity_Parameter R, const Quantity_Parameter G, const Quantity_Parameter B);
 201
 202   //! Returns the name of the color identified by
 203   //! AName in the Quantity_NameOfColor enumeration.
 204   //! For example, the name of the color which
 205   //! corresponds to Quantity_NOC_BLACK is "BLACK".
 206   //! Exceptions
 207   //! Standard_OutOfRange if AName in not known
 208   //! in the Quantity_NameOfColor enumeration.
 209   Standard_EXPORT static Standard_CString StringName (const Quantity_NameOfColor AColor);
 210
 211   //! Finds color from predefined names.
 212   //! For example, the name of the color which
 213   //! corresponds to "BLACK" is Quantity_NOC_BLACK.
 214   //! Returns false if name is unknown.
 215   Standard_EXPORT static Standard_Boolean ColorFromName (const Standard_CString theName, Quantity_NameOfColor& theColor);
 216
 217   //! Converts HLS components into RGB ones.
 218   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);
 219
 220   //! Converts RGB components into HLS ones.
 221   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);
 222
 223   //! Convert the Color value to ARGB integer value.
 224   //! theARGB has Alpha equal to zero, so the output is
 225   //! formatted as 0x00RRGGBB
 226   Standard_EXPORT static void Color2argb (const Quantity_Color& theColor, Standard_Integer& theARGB);
 227
 228   //! Convert integer ARGB value to Color. Alpha bits are ignored
 229   Standard_EXPORT static void Argb2color (const Standard_Integer theARGB, Quantity_Color& theColor);
 230
 231   //! Internal test
 232   Standard_EXPORT static void Test();
 233
 234
 235
 236
 237 protected:
 238
 239
 240
 241
 242
 243 private:
 244
 245
 246   //! Converts HLS components into RGB ones.
 247   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);
 248
 249   //! Converts RGB components into HLS ones.
 250   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);
 251
 252   //! Returns the values of a predefined colour according to
 253   //! the mode specified by TypeOfColor
 254   //! TOC_RGB : <R1> the value of red between 0. and 1.
 255   //! <R2> the value of green between 0. and 1.
 256   //! <R3> the value of blue between 0. and 1.
 257   //!
 258   //! TOC_HLS : <R1> is the hue angle in degrees, 0. being red
 259   //! <R2> is the lightness between 0. and 1.
 260   //! <R3> is the saturation between 0. and 1.
 261   Standard_EXPORT static void ValuesOf (const Quantity_NameOfColor AName, const Quantity_TypeOfColor AType, Standard_ShortReal& R1, Standard_ShortReal& R2, Standard_ShortReal& R3);
 262
 263
 264   Standard_ShortReal MyRed;
 265   Standard_ShortReal MyGreen;
 266   Standard_ShortReal MyBlue;
 267
 268
 269 };
 270
 271
 272
 273
 274
 275
 276
 277 #endif // _Quantity_Color_HeaderFile