0022958: Redundant assignment
[occt.git] / src / Quantity / Quantity_Color.cdl
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
9 class Color from Quantity
10 inherits  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         
26 uses
27
28         NameOfColor     from Quantity,
29         Parameter       from Quantity,
30         Rate            from Quantity,
31         TypeOfColor     from Quantity
32
33
34 raises
35
36         ColorDefinitionError    from Quantity
37
38 is
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
337 fields
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
353 end Color;