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