1 -- Created by: NW,JPB,CAL
2 -- Copyright (c) 1991-1999 Matra Datavision
3 -- Copyright (c) 1999-2014 OPEN CASCADE SAS
5 -- This file is part of Open CASCADE Technology software library.
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.
13 -- Alternatively, this file may be used under the terms of Open CASCADE
14 -- commercial license or contractual agreement.
16 class Color from Quantity
18 ---Purpose: This class allows the definition of a colour.
19 -- The names of the colours are from the X11 specification.
20 -- color object may be used for numerous applicative purposes.
21 -- A color is defined by:
22 -- - its respective quantities of red, green and blue (R-G-B values), or
23 -- - its hue angle and its values of lightness and saturation (H-L-S values).
24 -- These two color definition systems are equivalent.
25 -- Use this class in conjunction with:
26 -- - the Quantity_TypeOfColor enumeration
27 -- which identifies the color definition system you are using,
28 -- - the Quantity_NameOfColor enumeration
29 -- which lists numerous predefined colors and
30 -- identifies them by their name.
34 NameOfColor from Quantity,
35 Parameter from Quantity,
37 TypeOfColor from Quantity
42 ColorDefinitionError from Quantity
48 ---Purpose: Creates a colour with the default value of
49 -- Colour name : YELLOW
51 raises ColorDefinitionError from Quantity;
52 -- if the maximum number of colours is exceeded
54 Create ( AName : NameOfColor from Quantity )
56 ---Purpose: Creates the colour <AName>.
58 raises ColorDefinitionError from Quantity;
59 -- if the given name is unknown or the maximum number
60 -- of colours is exceeded
62 Create ( R1, R2, R3 : Parameter from Quantity;
63 AType : TypeOfColor from Quantity )
65 ---Purpose: Creates a colour according to the definition system
67 -- TOC_RGB : <R1> the value of red between 0. and 1.
68 -- <R2> the value of green between 0. and 1.
69 -- <R3> the value of blue between 0. and 1.
71 -- TOC_HLS : <R1> is the hue angle in degrees, 0. being red
72 -- <R2> is the lightness between 0. and 1.
73 -- <R3> is the saturation between 0. and 1.
75 raises ColorDefinitionError from Quantity;
76 -- if the values are not in the allowed interval or
77 -- maximum number of colours is exceeded.
79 ---------------------------------------------------
80 -- Category: Methods to modify the class definition
81 ---------------------------------------------------
84 Other : Color from Quantity )
85 returns Color from Quantity is static;
86 ---Purpose: Updates the colour <me> from the definition of the
88 ---Category: Methods to modify the class definition
89 ---C++: alias operator =
92 ChangeContrast ( me : in out;
93 ADelta : Rate from Quantity ) is static;
94 ---Purpose: Increases or decreases the contrast by <ADelta>.
95 -- <ADelta> is a percentage. Any value greater than zero
96 -- will increase the contrast.
97 -- The variation is expressed as a percentage of the
99 -- It is a variation of the saturation.
101 ChangeIntensity ( me : in out;
102 ADelta : Rate from Quantity ) is static;
103 ---Purpose: Increases or decreases the intensity by <ADelta>.
104 -- <ADelta> is a percentage. Any value greater than zero
105 -- will increase the intensity.
106 -- The variation is expressed as a percentage of the
108 -- It is a variation of the lightness.
110 SetValues ( me : in out;
111 AName : NameOfColor from Quantity ) is static;
112 ---Purpose: Updates the colour <me> from the definition of the
114 ---Category: Methods to modify the class definition
116 SetValues ( me : in out;
117 R1, R2, R3 : Parameter from Quantity;
118 AType : TypeOfColor from Quantity )
119 ---Purpose: Updates a colour according to the mode specified by
121 -- TOC_RGB : <R1> the value of red between 0. and 1.
122 -- <R2> the value of green between 0. and 1.
123 -- <R3> the value of blue between 0. and 1.
125 -- TOC_HLS : <R1> is the hue angle in degrees, 0. being red
126 -- <R2> is the lightness between 0. and 1.
127 -- <R3> is the saturation between 0. and 1.
129 raises ColorDefinitionError from Quantity is static;
130 -- if the values do not fall in the allowed interval
131 ---Category: Methods to modify the class definition
133 ------------------------------------------
134 -- Category: Methods to compare two colors
135 ------------------------------------------
138 AColor : Color from Quantity;
139 DC, DI : out Parameter from Quantity ) is static;
140 ---Purpose: Returns the percentage change of contrast and intensity
141 -- between <me> and <AColor>.
142 -- <DC> and <DI> are percentages, either positive or negative.
143 -- The calculation is with respect to the current value of <me>
144 -- If <DC> is positive then <me> is more contrasty.
145 -- If <DI> is positive then <me> is more intense.
146 ---Category: Methods to compare two colors
149 AColor : Color from Quantity )
150 returns Real from Standard is static;
151 ---Purpose: Returns the distance between two colours. It's a
152 -- value between 0 and the square root of 3
153 -- (the black/white distance)
154 ---Category: Methods to compare two colors
157 AColor : Color from Quantity )
158 returns Real from Standard is static;
159 ---Purpose: Returns the square of distance between two colours.
160 ---Category: Methods to compare two colors
162 ----------------------------
163 -- Category: Inquire methods
164 ----------------------------
167 returns Parameter from Quantity is static;
168 ---Purpose: Returns the Blue component (quantity of blue) of the
170 ---Category: Inquire methods
173 returns Parameter from Quantity is static;
174 ---Purpose: Returns the Green component (quantity of green) of the
176 ---Category: Inquire methods
179 returns Parameter from Quantity is static;
180 ---Purpose: Returns the Hue component (hue angle) of the
182 ---Category: Inquire methods
185 Other : Color from Quantity )
186 returns Boolean from Standard is static;
187 ---Purpose: Returns Standard_True if the distance between <me> and
188 -- <Other> is greater than Epsilon ().
189 ---Category: Inquire methods
190 ---C++: alias operator !=
193 Other : Color from Quantity )
194 returns Boolean from Standard is static;
195 ---Purpose: Returns true if the Other color is
196 -- - different from, or
197 -- - equal to this color.
198 -- Two colors are considered to be equal if their
199 -- distance is no greater than Epsilon().
200 -- These methods are aliases of operator != and operator ==.
201 ---C++: alias operator ==
204 returns Parameter from Quantity is static;
205 ---Purpose: Returns the Light component (value of the lightness) of the
207 ---Category: Inquire methods
210 returns NameOfColor from Quantity is static;
211 ---Purpose: Returns the name of the color defined by its
212 -- quantities of red R, green G and blue B; more
213 -- precisely this is the nearest color from the
214 -- Quantity_NameOfColor enumeration.
216 -- Standard_OutOfRange if R, G or B is less than 0. or greater than 1.
219 returns Parameter from Quantity is static;
220 ---Purpose: Returns the Red component (quantity of red) of the
222 ---Category: Inquire methods
225 returns Parameter from Quantity is static;
226 ---Purpose: Returns the Saturation component (value of the saturation)
227 -- of the color <me>.
228 ---Category: Inquire methods
231 R1, R2, R3 : out Parameter from Quantity;
232 AType : TypeOfColor from Quantity )
233 ---Purpose: Returns in R1, R2 and R3 the components of
234 -- this color according to the color system definition AType.
235 -- - if AType is Quantity_TOC_RGB R1 is the
236 -- quantity of red, R2 is the quantity of green and
237 -- R3 is the quantity of blue in this color.
238 -- - if AType is Quantity_TOC_HLS R1 is the
239 -- hue angle in degrees (0 being red), R2 is the
240 -- lightness and R3 is the saturation of this color.
242 -- Raises ColorDefinitionError if the values are not in the allowed interval
244 raises ColorDefinitionError from Quantity is static;
246 --------------------------
247 -- Category: Class methods
248 --------------------------
250 SetEpsilon ( myclass;
251 AnEpsilon : Parameter from Quantity );
252 ---Purpose: Sets the specified value used to compare <me> and
253 -- an other color in IsDifferent and in IsEqual methods.
254 -- Warning: The default value is 0.0001
255 ---Category: Class methods
258 returns Parameter from Quantity;
259 ---Purpose: Returns the specified value used to compare <me> and
260 -- an other color in IsDifferent and in IsEqual methods.
261 ---Category: Class methods
264 R, G, B : Parameter from Quantity )
265 returns NameOfColor from Quantity;
266 ---Purpose: Returns the name of the colour for which the RGB components
267 -- are nearest to <R>, <G> and <B>.
268 ---Category: Class methods
270 StringName ( myclass;
271 AColor : NameOfColor from Quantity )
273 ---Purpose: Returns the name of the color identified by
274 -- AName in the Quantity_NameOfColor enumeration.
275 -- For example, the name of the color which
276 -- corresponds to Quantity_NOC_BLACK is "BLACK".
278 -- Standard_OutOfRange if AName in not known
279 -- in the Quantity_NameOfColor enumeration.
281 ColorFromName ( myclass;
282 theName : CString from Standard;
283 theColor : out NameOfColor from Quantity )
284 returns Boolean from Standard;
285 ---Purpose: Finds color from predefined names.
286 -- For example, the name of the color which
287 -- corresponds to "BLACK" is Quantity_NOC_BLACK.
288 -- Returns false if name is unknown.
291 H, L, S : Parameter from Quantity;
292 R , G , B : out Parameter from Quantity ) ;
293 ---Purpose: Converts HLS components into RGB ones.
294 ---Category: Class methods
297 R, G, B : Parameter from Quantity;
298 H , L , S : out Parameter from Quantity ) ;
299 ---Purpose: Converts RGB components into HLS ones.
300 ---Category: Class methods
302 Color2argb ( myclass; theColor: Color from Quantity;
303 theARGB : out Integer from Standard );
304 ---Purpose: Convert the Color value to ARGB integer value.
305 -- theARGB has Alpha equal to zero, so the output is
306 -- formatted as 0x00RRGGBB
308 Argb2color ( myclass; theARGB : Integer from Standard;
309 theColor: out Color from Quantity );
310 ---Purpose: Convert integer ARGB value to Color. Alpha bits are ignored
312 ----------------------------
313 -- Category: Private methods
314 ----------------------------
317 H, L, S : ShortReal from Standard;
318 R , G , B : out ShortReal from Standard )
320 ---Purpose: Converts HLS components into RGB ones.
321 ---Category: Private methods
324 R, G, B : ShortReal from Standard;
325 H , L , S : out ShortReal from Standard )
327 ---Purpose: Converts RGB components into HLS ones.
328 ---Category: Private methods
331 AName : NameOfColor from Quantity;
332 AType : TypeOfColor from Quantity;
333 R1, R2, R3 : out ShortReal from Standard )
335 ---Purpose: Returns the values of a predefined colour according to
336 -- the mode specified by TypeOfColor
337 -- TOC_RGB : <R1> the value of red between 0. and 1.
338 -- <R2> the value of green between 0. and 1.
339 -- <R3> the value of blue between 0. and 1.
341 -- TOC_HLS : <R1> is the hue angle in degrees, 0. being red
342 -- <R2> is the lightness between 0. and 1.
343 -- <R3> is the saturation between 0. and 1.
344 ---Category: Private methods
347 ---Purpose: Internal test
348 ---Category: Private methods
355 -- Class : Quantity_Color
357 -- Purpose : Declaration of variables specific to colours
359 -- Reminder : A colour is defined, either in RGB or HLS,
360 -- or by a name defined in the X11 specification.
364 MyRed : ShortReal from Standard;
365 MyGreen : ShortReal from Standard;
366 MyBlue : ShortReal from Standard;