72d875d09609cdc5c4e8b8c96fb178863a7dcbbf
[occt.git] / src / Visual3d / Visual3d_Light.cdl
1 -- Created by: NW,JPB,CAL
2 -- Copyright (c) 1991-1999 Matra Datavision
3 -- Copyright (c) 1999-2012 OPEN CASCADE SAS
4 --
5 -- The content of this file is subject to the Open CASCADE Technology Public
6 -- License Version 6.5 (the "License"). You may not use the content of this file
7 -- except in compliance with the License. Please obtain a copy of the License
8 -- at http://www.opencascade.org and read it completely before using this file.
9 --
10 -- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
11 -- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
12 --
13 -- The Original Code and all software distributed under the License is
14 -- distributed on an "AS IS" basis, without warranty of any kind, and the
15 -- Initial Developer hereby disclaims all such warranties, including without
16 -- limitation, any warranties of merchantability, fitness for a particular
17 -- purpose or non-infringement. Please see the License for the specific terms
18 -- and conditions governing the rights and limitations under the License.
19
20 class Light from Visual3d inherits TShared
21
22         ---Version:
23
24         ---Purpose: This class defines and updates light sources.
25         --          There is no limit to the number of light sources defined.
26         --          Only the number of active sources is limited.
27         --
28         --          TypeOfLightSource = TOLS_AMBIENT
29         --                              TOLS_DIRECTIONAL
30         --                              TOLS_POSITIONAL
31         --                              TOLS_SPOT
32         --
33         --          Angle is a radian value.
34         --          Concentration, Attenuation are in the [0,1] interval.
35         --
36
37         ---Keywords: Light, View, Context, Ambient, Directional, Positional,
38         --           Spot, Angle, Concentration, Attenuation, Color, Shading
39
40         ---Warning:
41         ---References:
42
43 uses
44
45   Color  from Quantity,
46   CLight from Graphic3d,
47   Vector from Graphic3d,
48   Vertex from Graphic3d,
49   TypeOfLightSource from Visual3d
50
51 raises
52
53   LightDefinitionError from Visual3d
54
55 is
56
57         Create
58                 returns mutable Light from Visual3d;
59         ---Level: Public
60         ---Purpose: Creates a light from default values.
61         --          Light sources are created in a visualiser
62         --          and are activated in one of its views.
63         --
64         --          Type        = TOLS_AMBIENT
65         --          Color       = WHITE
66
67         Create ( Color          : Color from Quantity )
68                 returns mutable Light from Visual3d;
69         ---Level: Public
70         ---Purpose: Creates an AMBIENT light source.
71         --          Light sources are created in a visualiser
72         --          and are activated in one of its views.
73
74         Create ( Color          : Color from Quantity;
75                  Direction      : Vector from Graphic3d; 
76                  Headlight      : Boolean  from  Standard  =  Standard_False )
77                 returns mutable Light from Visual3d
78         ---Level: Public
79         ---Purpose: Creates a DIRECTIONAL light source.
80         --          Light sources are created in a visualiser
81         --          and are activated in one of its views.
82         --  Warning: Raises LightDefinitionError if <Direction> is null.
83         raises LightDefinitionError;
84
85         Create ( Color          : Color from Quantity;
86                  Position       : Vertex from Graphic3d;
87                  Fact1, Fact2   : Real from Standard )
88                 returns mutable Light from Visual3d
89         ---Level: Public
90         ---Purpose: Creates a POSITIONAL light source.
91         --          Light sources are created in a visualiser
92         --          and are activated in one of its views.
93         --  Warning: Raises LightDefinitionError 
94         --          if <Fact1> and <Fact2> are null.
95         --          if <Fact1> is a negative value or greater than 1.0.
96         --          if <Fact2> is a negative value or greater than 1.0.
97         raises LightDefinitionError;
98
99         Create ( Color          : Color from Quantity;
100                  Position       : Vertex from Graphic3d;
101                  Direction      : Vector from Graphic3d;
102                  Concentration  : Real from Standard;
103                  Fact1, Fact2   : Real from Standard;
104                  AngleCone      : Real from Standard )
105                 returns mutable Light from Visual3d
106         ---Level: Public
107         ---Purpose: Creates a SPOT light source.
108         --          Light sources are created in a visualiser
109         --          and are activated in one of its views.
110         --          <Concentration> specifies the intensity distribution of 
111         --          the light.
112         --          <AngleCone> specifies the angle (radians) of the cone 
113         --          created by the spot.
114         --          the global attenuation is equal :
115         --          1 / (Fact1 + Fact2 * (norm(ObjectPosition - LightPosition)))
116         --  Warning: Raises LightDefinitionError
117         --          if <Direction> is null.
118         --          if <Concentration> is a negative value or greater than 1.0.
119         --          if <Fact1> and <Fact2> are null.
120         --          if <Fact1> is a negative value or greater than 1.0.
121         --          if <Fact2> is a negative value or greater than 1.0.
122         --          if <AngleCone> is a negative value or greater than PI/2.
123         raises LightDefinitionError;
124
125         ---------------------------------------------------
126         -- Category: Methods to modify the class definition
127         ---------------------------------------------------
128
129         SetAngle ( me           : mutable;
130                    AngleCone    : Real from Standard )
131         ---Level: Public
132         ---Purpose: Modifies the angle (radians) of the cone created by the spot.
133         --          Works only on TOLS_SPOT lights. 
134         --  Category: Methods to modify the class definition
135         --  Warning: Raises LightDefinitionError
136         --          if the type of the light is not TOLS_SPOT.
137         --          if <AngleCone> is a negative value or greater than PI/2.
138         raises LightDefinitionError is static;
139
140         SetAttenuation1 ( me    : mutable;
141                           Fact1 : Real from Standard )
142         ---Level: Public
143         ---Purpose: Modifies the attenuation factor of the light.
144         --          Works only on the TOLS_POSITIONAL and TOLS_SPOT lights.
145         --  Category: Methods to modify the class definition
146         --  Warning: Raises LightDefinitionError
147         --          if the type of the light is not TOLS_SPOT or TOLS_POSITIONAL.
148         --          if <Fact1> is a negative value or greater than 1.0.
149         raises LightDefinitionError is static;
150
151         SetAttenuation2 ( me    : mutable;
152                           Fact2 : Real from Standard )
153         ---Level: Public
154         ---Purpose: Modifies the attenuation factor of the light.
155         --          Works only on the TOLS_POSITIONAL and TOLS_SPOT lights.
156         --  Category: Methods to modify the class definition
157         --  Warning: Raises LightDefinitionError
158         --          if the type of the light is not TOLS_POSITIONAL or TOLS_SPOT.
159         --          if <Fact2> is a negative value or greater than 1.0..
160         raises LightDefinitionError is static;
161
162         SetColor ( me           : mutable;
163                    Color        : Color from Quantity )
164                 is static;
165         ---Level: Public
166         ---Purpose: Modifies the colour of the light.
167         ---Category: Methods to modify the class definition
168
169         SetConcentration ( me                   : mutable;
170                            Concentration        : Real from Standard )
171         ---Level: Public
172         ---Purpose: Modifies the intensity distribution of the light.
173         --          Works only on the TOLS_SPOT lights.
174         --  Category: Methods to modify the class definition
175         --  Warning: Raises LightDefinitionError
176         --          if the type of the light is not TOLS_SPOT.
177         --          if <Concentration> is a negative value or greater than 1.0.
178         raises LightDefinitionError is static;
179
180         SetDirection ( me               : mutable;
181                        Direction        : Vector from Graphic3d )
182         ---Level: Public
183         ---Purpose: Modifies the light direction.
184         --          Works only on the TOLS_DIRECTIONAL and TOLS_SPOT lights.
185         --          Default z
186         --  Category: Methods to modify the class definition
187         --  Warning: Raises LightDefinitionError
188         --          if the type of the light is not TOLS_DIRECTIONAL
189         --          or TOLS_SPOT.
190         --          if <Direction> is null.
191         raises LightDefinitionError is static;
192
193         SetPosition ( me        : mutable;
194                       Position  : Vertex from Graphic3d )
195         ---Level: Public
196         ---Purpose: Modifies the position of the light.
197         --          Works only on the TOLS_POSITIONAL and TOLS_SPOT lights.
198         --  Category: Methods to modify the class definition
199         --  Warning: Raises LightDefinitionError 
200         --          if the type of the light is not TOLS_POSITIONAL or TOLS_SPOT.
201         raises LightDefinitionError is static;
202
203         ----------------------------
204         -- Category: Inquire methods
205         ----------------------------
206
207   Headlight ( me )
208   returns  Boolean  from  Standard  is  static;
209   ---Level: Public
210   ---Purpose:  Returns the headlight  state of the light <me>
211   ---Category: Inquire methods
212
213   SetHeadlight( me : mutable; theValue : Boolean from Standard ) is static;
214   ---Level: Public
215   ---Purpose: Setup headlight flag.
216
217         Color ( me )
218                 returns Color from Quantity is static;
219         ---Level: Public
220         ---Purpose: Returns the colour of the light <me>.
221         ---Category: Inquire methods
222
223         LightType ( me )
224                 returns TypeOfLightSource from Visual3d is static;
225         ---Level: Public
226         ---Purpose: Returns the light type of <me>.
227         --
228         --          TypeOfLightSource = TOLS_AMBIENT
229         --                              TOLS_DIRECTIONAL
230         --                              TOLS_POSITIONAL
231         --                              TOLS_SPOT
232         --
233         ---Category: Inquire methods
234
235         Values ( me;
236                  Color          : out Color from Quantity )
237         ---Level: Public
238         ---Purpose: Returns the definition of <me> if <me> is
239         --          a light source of the TOLS_AMBIENT type.
240         --  Category: Inquire methods
241         --  Warning: Raises LightDefinitionError 
242         --          if the type of the light is not TOLS_AMBIENT.
243         raises LightDefinitionError is static;
244
245         Values ( me;
246                  Color          : out Color from Quantity;
247                  Direction      : out Vector from Graphic3d )
248         ---Level: Public
249         ---Purpose: Returns the definition of <me> if <me> is
250         --          a light source of the TOLS_DIRECTIONAL type.
251         --  Category: Inquire methods
252         --  Warning: Raises LightDefinitionError 
253         --          if the type of the light is not TOLS_DIRECTIONAL.
254         raises LightDefinitionError is static;
255
256         Values ( me;
257                  Color          : out Color from Quantity;
258                  Position       : out Vertex from Graphic3d;
259                  Fact1,Fact2    : out Real from Standard )
260         ---Level: Public
261         ---Purpose: Returns the definition of <me> if <me> is
262         --          a light source of the TOLS_POSITIONAL type.
263         --  Category: Inquire methods
264         --  Warning: Raises LightDefinitionError 
265         --          if the type of the light is not TOLS_POSITIONAL.
266         raises LightDefinitionError is static;
267
268         Values ( me;
269                  Color          : out Color from Quantity;
270                  Position       : out Vertex from Graphic3d;
271                  Direction      : out Vector from Graphic3d;
272                  Concentration  : out Real from Standard;
273                  Fact1,Fact2    : out Real from Standard;
274                  AngleCone      : out Real from Standard )
275         ---Level: Public
276         ---Purpose: Returns the definition of <me> if <me> is
277         --          a light source of the TOLS_SPOT type.
278         --  Category: Inquire methods
279         --  Warning: Raises LightDefinitionError 
280         --          if the type of the light is not TOLS_SPOT.
281         raises LightDefinitionError is static;
282
283   CLight ( me )
284   returns CLight from Graphic3d
285   is static;
286   ---C++: return const &
287   ---Level: Public
288   ---Purpose: Returns the light defintion.
289   ---Category: Inquire methods
290
291         --------------------------
292         -- Category: Class methods
293         --------------------------
294
295         Limit ( myclass )
296                 returns Integer from Standard;
297         ---Level: Internal
298         ---Purpose: Maximum number of activatable light sources.
299         ---Category: Class methods
300
301         ----------------------------
302         -- Category: Private methods
303         ----------------------------
304
305         Identification ( me )
306                 returns Integer from Standard
307                 is static private;
308         ---Level: Internal
309         ---Purpose: Returns the light identification.
310         ---Category: Private methods
311
312         IsValid ( myclass;
313                   AAngle        : Real from Standard )
314                 returns Boolean from Standard
315                 is private;
316         ---Level: Internal
317         ---Purpose: Returns True if <AAngle> is a valid
318         --          spot light spread angle.
319         ---Category: Private methods
320
321 --
322
323 fields
324
325   -- the associated C structure
326   myCLight : CLight from Graphic3d;
327
328 friends
329
330         class View from Visual3d
331
332 end Light;