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