0024322: TKOpenGl - light sources management inconsistency
[occt.git] / src / Visual3d / Visual3d_Light.cdl
CommitLineData
b311480e 1-- Created by: NW,JPB,CAL
2-- Copyright (c) 1991-1999 Matra Datavision
3-- Copyright (c) 1999-2012 OPEN CASCADE SAS
7fd59977 4--
b311480e 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.
7fd59977 9--
b311480e 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.
7fd59977 12--
b311480e 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
7fd59977 20class 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
43uses
44
12381341 45 Color from Quantity,
46 CLight from Graphic3d,
47 Vector from Graphic3d,
48 Vertex from Graphic3d,
49 TypeOfLightSource from Visual3d
7fd59977 50
51raises
52
12381341 53 LightDefinitionError from Visual3d
7fd59977 54
55is
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
12381341 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
7fd59977 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
12381341 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
7fd59977 291 --------------------------
292 -- Category: Class methods
293 --------------------------
294
7fd59977 295 IsValid ( myclass;
296 AAngle : Real from Standard )
297 returns Boolean from Standard
298 is private;
299 ---Level: Internal
300 ---Purpose: Returns True if <AAngle> is a valid
301 -- spot light spread angle.
302 ---Category: Private methods
303
7fd59977 304--
305
12381341 306fields
7fd59977 307
12381341 308 -- the associated C structure
309 myCLight : CLight from Graphic3d;
7fd59977 310
311friends
312
313 class View from Visual3d
314
315end Light;