0022958: Redundant assignment
[occt.git] / src / Quantity / Quantity_Color.cdl
CommitLineData
7fd59977 1--
2-- File: Quantity_Color.cdl
3-- Created: Jeudi 22 Aout 1991
4-- Author: NW,JPB,CAL
5--
6---Copyright: MatraDatavision 1991,1992
7--
8
9class Color from Quantity
10inherits Storable
11
12 ---Purpose: This class allows the definition of a colour.
13 -- The names of the colours are from the X11 specification.
14 -- color object may be used for numerous applicative purposes.
15 -- A color is defined by:
16 -- - its respective quantities of red, green and blue (R-G-B values), or
17 -- - its hue angle and its values of lightness and saturation (H-L-S values).
18 -- These two color definition systems are equivalent.
19 -- Use this class in conjunction with:
20 -- - the Quantity_TypeOfColor enumeration
21 -- which identifies the color definition system you are using,
22 -- - the Quantity_NameOfColor enumeration
23 -- which lists numerous predefined colors and
24 -- identifies them by their name.
25
26uses
27
28 NameOfColor from Quantity,
29 Parameter from Quantity,
30 Rate from Quantity,
31 TypeOfColor from Quantity
32
33
34raises
35
36 ColorDefinitionError from Quantity
37
38is
39
40 Create
41 returns Color
42 ---Purpose: Creates a colour with the default value of
43 -- Colour name : YELLOW
44 --
45 raises ColorDefinitionError from Quantity;
46 -- if the maximum number of colours is exceeded
47
48 Create ( AName : NameOfColor from Quantity )
49 returns Color
50 ---Purpose: Creates the colour <AName>.
51 --
52 raises ColorDefinitionError from Quantity;
53 -- if the given name is unknown or the maximum number
54 -- of colours is exceeded
55
56 Create ( R1, R2, R3 : Parameter from Quantity;
57 AType : TypeOfColor from Quantity )
58 returns Color
59 ---Purpose: Creates a colour according to the definition system
60 -- TypeOfColor.
61 -- TOC_RGB : <R1> the value of red between 0. and 1.
62 -- <R2> the value of green between 0. and 1.
63 -- <R3> the value of blue between 0. and 1.
64 --
65 -- TOC_HLS : <R1> is the hue angle in degrees, 0. being red
66 -- <R2> is the lightness between 0. and 1.
67 -- <R3> is the saturation between 0. and 1.
68 --
69 raises ColorDefinitionError from Quantity;
70 -- if the values are not in the allowed interval or
71 -- maximum number of colours is exceeded.
72
73 ---------------------------------------------------
74 -- Category: Methods to modify the class definition
75 ---------------------------------------------------
76
77 Assign ( me : in out;
78 Other : Color from Quantity )
79 returns Color from Quantity is static;
80 ---Purpose: Updates the colour <me> from the definition of the
81 -- colour <Other>.
82 ---Category: Methods to modify the class definition
83 ---C++: alias operator =
84 ---C++: return &
85
86 ChangeContrast ( me : in out;
87 ADelta : Rate from Quantity ) is static;
88 ---Purpose: Increases or decreases the contrast by <ADelta>.
89 -- <ADelta> is a percentage. Any value greater than zero
90 -- will increase the contrast.
91 -- The variation is expressed as a percentage of the
92 -- current value.
93 -- It is a variation of the saturation.
94
95 ChangeIntensity ( me : in out;
96 ADelta : Rate from Quantity ) is static;
97 ---Purpose: Increases or decreases the intensity by <ADelta>.
98 -- <ADelta> is a percentage. Any value greater than zero
99 -- will increase the intensity.
100 -- The variation is expressed as a percentage of the
101 -- current value.
102 -- It is a variation of the lightness.
103
104 SetValues ( me : in out;
105 AName : NameOfColor from Quantity ) is static;
106 ---Purpose: Updates the colour <me> from the definition of the
107 -- colour <AName>.
108 ---Category: Methods to modify the class definition
109
110 SetValues ( me : in out;
111 R1, R2, R3 : Parameter from Quantity;
112 AType : TypeOfColor from Quantity )
113 ---Purpose: Updates a colour according to the mode specified by
114 -- TypeOfColor
115 -- TOC_RGB : <R1> the value of red between 0. and 1.
116 -- <R2> the value of green between 0. and 1.
117 -- <R3> the value of blue between 0. and 1.
118 --
119 -- TOC_HLS : <R1> is the hue angle in degrees, 0. being red
120 -- <R2> is the lightness between 0. and 1.
121 -- <R3> is the saturation between 0. and 1.
122 --
123 raises ColorDefinitionError from Quantity is static;
124 -- if the values do not fall in the allowed interval
125 ---Category: Methods to modify the class definition
126
127 ------------------------------------------
128 -- Category: Methods to compare two colors
129 ------------------------------------------
130
131 Delta ( me;
132 AColor : Color from Quantity;
133 DC, DI : out Parameter from Quantity ) is static;
134 ---Purpose: Returns the percentage change of contrast and intensity
135 -- between <me> and <AColor>.
136 -- <DC> and <DI> are percentages, either positive or negative.
137 -- The calculation is with respect to the current value of <me>
138 -- If <DC> is positive then <me> is more contrasty.
139 -- If <DI> is positive then <me> is more intense.
140 ---Category: Methods to compare two colors
141
142 Distance ( me;
143 AColor : Color from Quantity )
144 returns Real from Standard is static;
145 ---Purpose: Returns the distance between two colours. It's a
146 -- value between 0 and the square root of 3
147 -- (the black/white distance)
148 ---Category: Methods to compare two colors
149
150 SquareDistance ( me;
151 AColor : Color from Quantity )
152 returns Real from Standard is static;
153 ---Purpose: Returns the square of distance between two colours.
154 ---Category: Methods to compare two colors
155
156 ----------------------------
157 -- Category: Inquire methods
158 ----------------------------
159
160 Blue ( me )
161 returns Parameter from Quantity is static;
162 ---Purpose: Returns the Blue component (quantity of blue) of the
163 -- color <me>.
164 ---Category: Inquire methods
165
166 Green ( me )
167 returns Parameter from Quantity is static;
168 ---Purpose: Returns the Green component (quantity of green) of the
169 -- color <me>.
170 ---Category: Inquire methods
171
172 Hue ( me )
173 returns Parameter from Quantity is static;
174 ---Purpose: Returns the Hue component (hue angle) of the
175 -- color <me>.
176 ---Category: Inquire methods
177
178 IsDifferent ( me;
179 Other : Color from Quantity )
180 returns Boolean from Standard is static;
181 ---Purpose: Returns Standard_True if the distance between <me> and
182 -- <Other> is greater than Epsilon ().
183 ---Category: Inquire methods
184 ---C++: alias operator !=
185
186 IsEqual ( me;
187 Other : Color from Quantity )
188 returns Boolean from Standard is static;
189 ---Purpose: Returns true if the Other color is
190 -- - different from, or
191 -- - equal to this color.
192 -- Two colors are considered to be equal if their
193 -- distance is no greater than Epsilon().
194 -- These methods are aliases of operator != and operator ==.
195 ---C++: alias operator ==
196
197 Light ( me )
198 returns Parameter from Quantity is static;
199 ---Purpose: Returns the Light component (value of the lightness) of the
200 -- color <me>.
201 ---Category: Inquire methods
202
203 Name ( me )
204 returns NameOfColor from Quantity is static;
205 ---Purpose: Returns the name of the color defined by its
206 -- quantities of red R, green G and blue B; more
207 -- precisely this is the nearest color from the
208 -- Quantity_NameOfColor enumeration.
209 -- Exceptions
210 -- Standard_OutOfRange if R, G or B is less than 0. or greater than 1.
211
212 Red ( me )
213 returns Parameter from Quantity is static;
214 ---Purpose: Returns the Red component (quantity of red) of the
215 -- color <me>.
216 ---Category: Inquire methods
217
218 Saturation ( me )
219 returns Parameter from Quantity is static;
220 ---Purpose: Returns the Saturation component (value of the saturation)
221 -- of the color <me>.
222 ---Category: Inquire methods
223
224 Values ( me;
225 R1, R2, R3 : out Parameter from Quantity;
226 AType : TypeOfColor from Quantity )
227 ---Purpose: Returns in R1, R2 and R3 the components of
228 -- this color according to the color system definition AType.
229 -- - if AType is Quantity_TOC_RGB R1 is the
230 -- quantity of red, R2 is the quantity of green and
231 -- R3 is the quantity of blue in this color.
232 -- - if AType is Quantity_TOC_HLS R1 is the
233 -- hue angle in degrees (0 being red), R2 is the
234 -- lightness and R3 is the saturation of this color.
235 --Exception
236 -- Raises ColorDefinitionError if the values are not in the allowed interval
237
238 raises ColorDefinitionError from Quantity is static;
239
240 --------------------------
241 -- Category: Class methods
242 --------------------------
243
244 SetEpsilon ( myclass;
245 AnEpsilon : Parameter from Quantity );
246 ---Purpose: Sets the specified value used to compare <me> and
247 -- an other color in IsDifferent and in IsEqual methods.
248 -- Warning: The default value is 0.0001
249 ---Category: Class methods
250
251 Epsilon ( myclass )
252 returns Parameter from Quantity;
253 ---Purpose: Returns the specified value used to compare <me> and
254 -- an other color in IsDifferent and in IsEqual methods.
255 ---Category: Class methods
256
257 Name ( myclass;
258 R, G, B : Parameter from Quantity )
259 returns NameOfColor from Quantity;
260 ---Purpose: Returns the name of the colour for which the RGB components
261 -- are nearest to <R>, <G> and <B>.
262 ---Category: Class methods
263
264 StringName ( myclass;
265 AColor : NameOfColor from Quantity )
266 returns CString;
267 ---Purpose: Returns the name of the color identified by
268 -- AName in the Quantity_NameOfColor enumeration.
269 -- For example, the name of the color which
270 -- corresponds to Quantity_NOC_BLACK is "BLACK".
271 -- Exceptions
272 -- Standard_OutOfRange if AName in not known
273 -- in the Quantity_NameOfColor enumeration.
274
275 HlsRgb ( myclass;
276 H, L, S : Parameter from Quantity;
277 R , G , B : out Parameter from Quantity ) ;
278 ---Purpose: Converts HLS components into RGB ones.
279 ---Category: Class methods
280
281 RgbHls ( myclass;
282 R, G, B : Parameter from Quantity;
283 H , L , S : out Parameter from Quantity ) ;
284 ---Purpose: Converts RGB components into HLS ones.
285 ---Category: Class methods
286
287 Color2argb ( myclass; theColor: Color from Quantity;
288 theARGB : out Integer from Standard );
289 ---Purpose: Convert the Color value to ARGB integer value.
290 -- theARGB has Alpha equal to zero, so the output is
291 -- formatted as 0x00RRGGBB
292
293 Argb2color ( myclass; theARGB : Integer from Standard;
294 theColor: out Color from Quantity );
295 ---Purpose: Convert integer ARGB value to Color. Alpha bits are ignored
296
297 ----------------------------
298 -- Category: Private methods
299 ----------------------------
300
301 hlsrgb ( myclass;
302 H, L, S : ShortReal from Standard;
303 R , G , B : out ShortReal from Standard )
304 is private ;
305 ---Purpose: Converts HLS components into RGB ones.
306 ---Category: Private methods
307
308 rgbhls ( myclass;
309 R, G, B : ShortReal from Standard;
310 H , L , S : out ShortReal from Standard )
311 is private ;
312 ---Purpose: Converts RGB components into HLS ones.
313 ---Category: Private methods
314
315 ValuesOf ( myclass;
316 AName : NameOfColor from Quantity;
317 AType : TypeOfColor from Quantity;
318 R1, R2, R3 : out ShortReal from Standard )
319 is private;
320 ---Purpose: Returns the values of a predefined colour according to
321 -- the mode specified by TypeOfColor
322 -- TOC_RGB : <R1> the value of red between 0. and 1.
323 -- <R2> the value of green between 0. and 1.
324 -- <R3> the value of blue between 0. and 1.
325 --
326 -- TOC_HLS : <R1> is the hue angle in degrees, 0. being red
327 -- <R2> is the lightness between 0. and 1.
328 -- <R3> is the saturation between 0. and 1.
329 ---Category: Private methods
330
331 Test ( myclass );
332 ---Purpose: Internal test
333 ---Category: Private methods
334
335--\f
336
337fields
338
339--
340-- Class : Quantity_Color
341--
342-- Purpose : Declaration of variables specific to colours
343--
344-- Reminder : A colour is defined, either in RGB or HLS,
345-- or by a name defined in the X11 specification.
346--
347
348 -- RGB components
349 MyRed : ShortReal from Standard;
350 MyGreen : ShortReal from Standard;
351 MyBlue : ShortReal from Standard;
352
353end Color;