0028316: Coding Rules - Elimilate confusing aliases of Standard_Real type in V3d_View
[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>
22
23#include <Standard_ShortReal.hxx>
24#include <Quantity_NameOfColor.hxx>
42cf5bc1 25#include <Quantity_TypeOfColor.hxx>
26#include <Quantity_Rate.hxx>
27#include <Standard_Real.hxx>
28#include <Standard_Boolean.hxx>
29#include <Standard_CString.hxx>
30#include <Standard_Integer.hxx>
b6472664 31#include <NCollection_Vec4.hxx>
42cf5bc1 32class 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.
48class Quantity_Color
49{
50public:
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
82cf4904 62 //! Creates a color according to the definition system theType.
63 //! Quantity_TOC_RGB:
64 //! - theR1 the value of Red within range [0.0; 1.0]
65 //! - theR2 the value of Green within range [0.0; 1.0]
66 //! - theR3 the value of Blue within range [0.0; 1.0]
42cf5bc1 67 //!
82cf4904 68 //! Quantity_TOC_HLS:
69 //! - theR1 is the Hue (H) angle in degrees within range [0.0; 360.0], 0.0 being Red.
70 //! Value -1.0 is a special value reserved for grayscale color (S should be 0.0).
71 //! - theR2 is the Lightness (L) within range [0.0; 1.0]
72 //! - theR3 is the Saturation (S) within range [0.0; 1.0]
ee2be2a8 73 Standard_EXPORT Quantity_Color (const Standard_Real theR1,
74 const Standard_Real theR2,
75 const Standard_Real theR3,
82cf4904 76 const Quantity_TypeOfColor theType);
b6472664 77
78 //! Define color from RGB values.
79 Standard_EXPORT explicit Quantity_Color (const NCollection_Vec3<float>& theRgb);
80
42cf5bc1 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
82cf4904 101 //! Updates a color according to the mode specified by theType.
102 //! TOC_RGB:
103 //! - theR1 the value of Red within range [0.0; 1.0]
104 //! - theR2 the value of Green within range [0.0; 1.0]
105 //! - theR3 the value of Blue within range [0.0; 1.0]
42cf5bc1 106 //!
82cf4904 107 //! TOC_HLS:
108 //! - theR1 is the Hue (H) angle in degrees within range [0.0; 360.0], 0.0 being Red.
109 //! -1.0 is a special value reserved for grayscale color (S should be 0.0).
110 //! - theR2 is the Lightness (L) within range [0.0; 1.0]
111 //! - theR3 is the Saturation (S) within range [0.0; 1.0]
ee2be2a8 112 Standard_EXPORT void SetValues (const Standard_Real theR1,
113 const Standard_Real theR2,
114 const Standard_Real theR3,
82cf4904 115 const Quantity_TypeOfColor theType);
42cf5bc1 116
117 //! Returns the percentage change of contrast and intensity
118 //! between <me> and <AColor>.
119 //! <DC> and <DI> are percentages, either positive or negative.
120 //! The calculation is with respect to the current value of <me>
121 //! If <DC> is positive then <me> is more contrasty.
122 //! If <DI> is positive then <me> is more intense.
ee2be2a8 123 Standard_EXPORT void Delta (const Quantity_Color& AColor, Standard_Real& DC, Standard_Real& DI) const;
42cf5bc1 124
125 //! Returns the distance between two colours. It's a
126 //! value between 0 and the square root of 3
127 //! (the black/white distance)
128 Standard_EXPORT Standard_Real Distance (const Quantity_Color& AColor) const;
129
130 //! Returns the square of distance between two colours.
131 Standard_EXPORT Standard_Real SquareDistance (const Quantity_Color& AColor) const;
132
82cf4904 133 //! Returns the Blue component (quantity of blue) of the color within range [0.0; 1.0].
ee2be2a8 134 Standard_EXPORT Standard_Real Blue() const;
42cf5bc1 135
82cf4904 136 //! Returns the Green component (quantity of green) of the color within range [0.0; 1.0].
ee2be2a8 137 Standard_EXPORT Standard_Real Green() const;
42cf5bc1 138
82cf4904 139 //! Returns the Hue component (hue angle) of the color
140 //! in degrees within range [0.0; 360.0], 0.0 being Red.
141 //! -1.0 is a special value reserved for grayscale color (S should be 0.0)
ee2be2a8 142 Standard_EXPORT Standard_Real Hue() const;
42cf5bc1 143
144 //! Returns Standard_True if the distance between <me> and
145 //! <Other> is greater than Epsilon ().
146 Standard_EXPORT Standard_Boolean IsDifferent (const Quantity_Color& Other) const;
147Standard_Boolean operator != (const Quantity_Color& Other) const
148{
149 return IsDifferent(Other);
150}
151
152 //! Returns true if the Other color is
153 //! - different from, or
154 //! - equal to this color.
155 //! Two colors are considered to be equal if their
156 //! distance is no greater than Epsilon().
157 //! These methods are aliases of operator != and operator ==.
158 Standard_EXPORT Standard_Boolean IsEqual (const Quantity_Color& Other) const;
159Standard_Boolean operator == (const Quantity_Color& Other) const
160{
161 return IsEqual(Other);
162}
163
82cf4904 164 //! Returns the Light component (value of the lightness) of the color within range [0.0; 1.0].
ee2be2a8 165 Standard_EXPORT Standard_Real Light() const;
42cf5bc1 166
167 //! Returns the name of the color defined by its
168 //! quantities of red R, green G and blue B; more
169 //! precisely this is the nearest color from the
170 //! Quantity_NameOfColor enumeration.
171 //! Exceptions
172 //! Standard_OutOfRange if R, G or B is less than 0. or greater than 1.
173 Standard_EXPORT Quantity_NameOfColor Name() const;
174
82cf4904 175 //! Returns the Red component (quantity of red) of the color within range [0.0; 1.0].
ee2be2a8 176 Standard_EXPORT Standard_Real Red() const;
42cf5bc1 177
82cf4904 178 //! Returns the Saturation component (value of the saturation) of the color within range [0.0; 1.0].
ee2be2a8 179 Standard_EXPORT Standard_Real Saturation() const;
b6472664 180
181 //! Return the color as vector of 3 float elements.
182 operator const NCollection_Vec3<float>&() const { return *(const NCollection_Vec3<float>* )this; }
183
82cf4904 184 //! Returns in theR1, theR2 and theR3 the components of this color according to the color system definition theType.
185 //! If theType is Quantity_TOC_RGB:
186 //! - theR1 the value of Red between 0.0 and 1.0
187 //! - theR2 the value of Green between 0.0 and 1.0
188 //! - theR3 the value of Blue between 0.0 and 1.0
189 //! If theType is Quantity_TOC_HLS:
190 //! - theR1 is the Hue (H) angle in degrees within range [0.0; 360.0], 0.0 being Red.
191 //! -1.0 is a special value reserved for grayscale color (S should be 0.0).
192 //! - theR2 is the Lightness (L) within range [0.0; 1.0]
193 //! - theR3 is the Saturation (S) within range [0.0; 1.0]
ee2be2a8 194 Standard_EXPORT void Values (Standard_Real& theR1,
195 Standard_Real& theR2,
196 Standard_Real& theR3,
82cf4904 197 const Quantity_TypeOfColor theType) const;
42cf5bc1 198
199 //! Sets the specified value used to compare <me> and
200 //! an other color in IsDifferent and in IsEqual methods.
201 //! Warning: The default value is 0.0001
ee2be2a8 202 Standard_EXPORT static void SetEpsilon (const Standard_Real AnEpsilon);
42cf5bc1 203
204 //! Returns the specified value used to compare <me> and
205 //! an other color in IsDifferent and in IsEqual methods.
ee2be2a8 206 Standard_EXPORT static Standard_Real Epsilon();
42cf5bc1 207
208 //! Returns the name of the colour for which the RGB components
209 //! are nearest to <R>, <G> and <B>.
ee2be2a8 210 Standard_EXPORT static Quantity_NameOfColor Name (const Standard_Real R, const Standard_Real G, const Standard_Real B);
42cf5bc1 211
212 //! Returns the name of the color identified by
213 //! AName in the Quantity_NameOfColor enumeration.
214 //! For example, the name of the color which
215 //! corresponds to Quantity_NOC_BLACK is "BLACK".
216 //! Exceptions
217 //! Standard_OutOfRange if AName in not known
218 //! in the Quantity_NameOfColor enumeration.
219 Standard_EXPORT static Standard_CString StringName (const Quantity_NameOfColor AColor);
220
221 //! Finds color from predefined names.
222 //! For example, the name of the color which
223 //! corresponds to "BLACK" is Quantity_NOC_BLACK.
224 //! Returns false if name is unknown.
225 Standard_EXPORT static Standard_Boolean ColorFromName (const Standard_CString theName, Quantity_NameOfColor& theColor);
226
227 //! Converts HLS components into RGB ones.
ee2be2a8 228 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 229
230 //! Converts RGB components into HLS ones.
ee2be2a8 231 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 232
233 //! Convert the Color value to ARGB integer value.
234 //! theARGB has Alpha equal to zero, so the output is
235 //! formatted as 0x00RRGGBB
236 Standard_EXPORT static void Color2argb (const Quantity_Color& theColor, Standard_Integer& theARGB);
237
238 //! Convert integer ARGB value to Color. Alpha bits are ignored
239 Standard_EXPORT static void Argb2color (const Standard_Integer theARGB, Quantity_Color& theColor);
240
241 //! Internal test
242 Standard_EXPORT static void Test();
243
42cf5bc1 244private:
245
42cf5bc1 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
42cf5bc1 268};
269
42cf5bc1 270#endif // _Quantity_Color_HeaderFile