0024927: Getting rid of "Persistent" functionality -- Storable
[occt.git] / src / Quantity / Quantity_Color.cdl
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 class Color from Quantity
17
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.
31         
32 uses
33
34         NameOfColor     from Quantity,
35         Parameter       from Quantity,
36         Rate            from Quantity,
37         TypeOfColor     from Quantity
38
39
40 raises
41
42         ColorDefinitionError    from Quantity
43
44 is
45
46         Create
47                 returns Color
48         ---Purpose: Creates a colour with the default value of
49         --          Colour name : YELLOW
50         --
51         raises ColorDefinitionError from Quantity;
52         -- if the maximum number of colours is exceeded
53
54         Create ( AName  : NameOfColor from Quantity )
55                 returns Color
56         ---Purpose: Creates the colour <AName>.
57         --
58         raises ColorDefinitionError from Quantity;
59         -- if the given name is unknown or the maximum number
60         -- of colours is exceeded
61
62         Create ( R1, R2, R3     : Parameter from Quantity;
63                  AType          : TypeOfColor from Quantity )
64                 returns Color
65         ---Purpose: Creates a colour according to the definition system
66         --          TypeOfColor.
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.
70         --
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.
74         --
75         raises ColorDefinitionError from Quantity;
76         -- if the values are not in the allowed interval or
77         -- maximum number of colours is exceeded.
78
79         ---------------------------------------------------
80         -- Category: Methods to modify the class definition
81         ---------------------------------------------------
82
83         Assign ( me     : in out;
84                  Other  : Color from Quantity )
85                 returns Color from Quantity is static;
86         ---Purpose: Updates the colour <me> from the definition of the
87         --          colour <Other>.
88         ---Category: Methods to modify the class definition
89         ---C++: alias operator =
90         ---C++: return &
91
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
98         --          current value.
99         --          It is a variation of the saturation.
100
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
107         --          current value.
108         --          It is a variation of the lightness.
109
110         SetValues ( me          : in out;
111                     AName       : NameOfColor from Quantity ) is static;
112         ---Purpose: Updates the colour <me> from the definition of the
113         --          colour <AName>.
114         ---Category: Methods to modify the class definition
115
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
120         --          TypeOfColor
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.
124         --
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.
128         --
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
132
133         ------------------------------------------
134         -- Category: Methods to compare two colors
135         ------------------------------------------
136
137         Delta ( me;
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
147
148         Distance ( me;
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
155
156         SquareDistance ( me;
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
161
162         ----------------------------
163         -- Category: Inquire methods
164         ----------------------------
165
166         Blue ( me )
167                 returns Parameter from Quantity is static;
168         ---Purpose: Returns the Blue component (quantity of blue) of the
169         --          color <me>.
170         ---Category: Inquire methods
171
172         Green ( me )
173                 returns Parameter from Quantity is static;
174         ---Purpose: Returns the Green component (quantity of green) of the
175         --          color <me>.
176         ---Category: Inquire methods
177
178         Hue ( me )
179                 returns Parameter from Quantity is static;
180         ---Purpose: Returns the Hue component (hue angle) of the
181         --          color <me>.
182         ---Category: Inquire methods
183
184         IsDifferent ( me;
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 !=
191
192         IsEqual ( me;
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 ==
202
203         Light ( me )
204                 returns Parameter from Quantity is static;
205         ---Purpose: Returns the Light component (value of the lightness) of the
206         --          color <me>.
207         ---Category: Inquire methods
208
209         Name ( me )
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.
215         -- Exceptions
216         -- Standard_OutOfRange if R, G or B is less than 0. or greater than 1.
217
218         Red ( me )
219                 returns Parameter from Quantity is static;
220         ---Purpose: Returns the Red component (quantity of red) of the
221         --          color <me>.
222         ---Category: Inquire methods
223
224         Saturation ( me )
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
229
230         Values ( me;
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.
241         --Exception
242         -- Raises ColorDefinitionError if the values are not in the allowed interval
243
244         raises ColorDefinitionError from Quantity is static;
245         
246         --------------------------
247         -- Category: Class methods
248         --------------------------
249
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
256
257         Epsilon ( myclass )
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
262
263         Name ( myclass;
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
269
270         StringName ( myclass;
271                      AColor     : NameOfColor from Quantity )
272                 returns CString;
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".
277         -- Exceptions
278         -- Standard_OutOfRange if AName in not known
279         -- in the Quantity_NameOfColor enumeration.
280
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.
289
290         HlsRgb ( myclass;
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
295
296         RgbHls ( myclass;
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
301
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
307
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
311
312         ----------------------------
313         -- Category: Private methods
314         ----------------------------
315
316         hlsrgb ( myclass;
317                  H, L, S        : ShortReal from Standard;
318                  R , G , B      : out ShortReal from Standard )
319                 is private ;
320         ---Purpose: Converts HLS components into RGB ones.
321         ---Category: Private methods
322
323         rgbhls ( myclass;
324                  R, G, B        : ShortReal from Standard;
325                  H , L , S      : out ShortReal from Standard )
326                 is private ;
327         ---Purpose: Converts RGB components into HLS ones.
328         ---Category: Private methods
329
330         ValuesOf ( myclass;
331                   AName         : NameOfColor from Quantity;
332                   AType         : TypeOfColor from Quantity;
333                   R1, R2, R3    : out ShortReal from Standard )
334                 is private;
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.
340         --
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
345
346         Test ( myclass );
347         ---Purpose: Internal test
348         ---Category: Private methods
349
350 --
351
352 fields
353
354 --
355 -- Class        :       Quantity_Color
356 --
357 -- Purpose      :       Declaration of variables specific to colours
358 --
359 -- Reminder     :       A colour is defined, either in RGB or HLS,
360 --                      or by a name defined in the X11 specification.
361 --
362
363         -- RGB components
364         MyRed           :       ShortReal from Standard;
365         MyGreen         :       ShortReal from Standard;
366         MyBlue          :       ShortReal from Standard;
367
368 end Color;