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