[occt.git] / src / Visual3d / Visual3d_Light.cdl

-- Created by: NW,JPB,CAL
-- Copyright (c) 1991-1999 Matra Datavision
-- Copyright (c) 1999-2012 OPEN CASCADE SAS
--
-- The content of this file is subject to the Open CASCADE Technology Public
-- License Version 6.5 (the "License"). You may not use the content of this file
-- except in compliance with the License. Please obtain a copy of the License
-- at http://www.opencascade.org and read it completely before using this file.
--
-- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
-- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
--
-- The Original Code and all software distributed under the License is
-- distributed on an "AS IS" basis, without warranty of any kind, and the
-- Initial Developer hereby disclaims all such warranties, including without
-- limitation, any warranties of merchantability, fitness for a particular
-- purpose or non-infringement. Please see the License for the specific terms
-- and conditions governing the rights and limitations under the License.


class Light from Visual3d inherits TShared

	---Version:

	---Purpose: This class defines and updates light sources.
	--	    There is no limit to the number of light sources defined.
	--	    Only the number of active sources is limited.
	--
	--	    TypeOfLightSource = TOLS_AMBIENT
	--				TOLS_DIRECTIONAL
	--				TOLS_POSITIONAL
	--				TOLS_SPOT
	--
	--	    Angle is a radian value.
	--	    Concentration, Attenuation are in the [0,1] interval.
	--

	---Keywords: Light, View, Context, Ambient, Directional, Positional,
	--	     Spot, Angle, Concentration, Attenuation, Color, Shading

	---Warning:
	---References:

uses

	Color			from Quantity,

	CLight			from Graphic3d,
	Vector			from Graphic3d,
	Vertex			from Graphic3d,

	TypeOfLightSource	from Visual3d

raises

	LightDefinitionError	from Visual3d

is

	Create
		returns mutable Light from Visual3d;
	---Level: Public
	---Purpose: Creates a light from default values.
	--	    Light sources are created in a visualiser
	--	    and are activated in one of its views.
	--
	--	    Type	= TOLS_AMBIENT
	--	    Color	= WHITE

	Create ( Color		: Color from Quantity )
		returns mutable Light from Visual3d;
	---Level: Public
	---Purpose: Creates an AMBIENT light source.
	--	    Light sources are created in a visualiser
	--	    and are activated in one of its views.

	Create ( Color		: Color from Quantity;
		 Direction	: Vector from Graphic3d; 
    	    	 Headlight      : Boolean  from  Standard  =  Standard_False )
		returns mutable Light from Visual3d
	---Level: Public
	---Purpose: Creates a DIRECTIONAL light source.
	--	    Light sources are created in a visualiser
	--	    and are activated in one of its views.
	--  Warning: Raises LightDefinitionError if <Direction> is null.
	raises LightDefinitionError;

	Create ( Color		: Color from Quantity;
		 Position	: Vertex from Graphic3d;
		 Fact1, Fact2	: Real from Standard )
		returns mutable Light from Visual3d
	---Level: Public
	---Purpose: Creates a POSITIONAL light source.
	--	    Light sources are created in a visualiser
	--	    and are activated in one of its views.
	--  Warning: Raises LightDefinitionError 
	--	    if <Fact1> and <Fact2> are null.
	--	    if <Fact1> is a negative value or greater than 1.0.
	--	    if <Fact2> is a negative value or greater than 1.0.
	raises LightDefinitionError;

	Create ( Color		: Color from Quantity;
		 Position	: Vertex from Graphic3d;
		 Direction	: Vector from Graphic3d;
		 Concentration	: Real from Standard;
		 Fact1, Fact2	: Real from Standard;
		 AngleCone	: Real from Standard )
		returns mutable Light from Visual3d
	---Level: Public
	---Purpose: Creates a SPOT light source.
	--	    Light sources are created in a visualiser
	--	    and are activated in one of its views.
	--	    <Concentration> specifies the intensity distribution of 
	--	    the light.
	--	    <AngleCone> specifies the angle (radians) of the cone 
	--	    created by the spot.
	-- 	    the global attenuation is equal :
	--	    1 / (Fact1 + Fact2 * (norm(ObjectPosition - LightPosition)))
	--  Warning: Raises LightDefinitionError
	--	    if <Direction> is null.
	--	    if <Concentration> is a negative value or greater than 1.0.
	--	    if <Fact1> and <Fact2> are null.
	--	    if <Fact1> is a negative value or greater than 1.0.
	--	    if <Fact2> is a negative value or greater than 1.0.
	--	    if <AngleCone> is a negative value or greater than PI/2.
	raises LightDefinitionError;

	---------------------------------------------------
	-- Category: Methods to modify the class definition
	---------------------------------------------------

	SetAngle ( me		: mutable;
		   AngleCone	: Real from Standard )
	---Level: Public
	---Purpose: Modifies the angle (radians) of the cone created by the spot.
	--	    Works only on TOLS_SPOT lights. 
	--  Category: Methods to modify the class definition
	--  Warning: Raises LightDefinitionError
	--	    if the type of the light is not TOLS_SPOT.
	--	    if <AngleCone> is a negative value or greater than PI/2.
	raises LightDefinitionError is static;

	SetAttenuation1 ( me	: mutable;
			  Fact1	: Real from Standard )
	---Level: Public
	---Purpose: Modifies the attenuation factor of the light.
	--	    Works only on the TOLS_POSITIONAL and TOLS_SPOT lights.
	--  Category: Methods to modify the class definition
	--  Warning: Raises LightDefinitionError
	--	    if the type of the light is not TOLS_SPOT or TOLS_POSITIONAL.
	--	    if <Fact1> is a negative value or greater than 1.0.
	raises LightDefinitionError is static;

	SetAttenuation2 ( me	: mutable;
			  Fact2	: Real from Standard )
	---Level: Public
	---Purpose: Modifies the attenuation factor of the light.
	--	    Works only on the TOLS_POSITIONAL and TOLS_SPOT lights.
	--  Category: Methods to modify the class definition
	--  Warning: Raises LightDefinitionError
	--	    if the type of the light is not TOLS_POSITIONAL or TOLS_SPOT.
	--	    if <Fact2> is a negative value or greater than 1.0..
	raises LightDefinitionError is static;

	SetColor ( me		: mutable;
		   Color	: Color from Quantity )
		is static;
	---Level: Public
	---Purpose: Modifies the colour of the light.
	---Category: Methods to modify the class definition

	SetConcentration ( me			: mutable;
			   Concentration	: Real from Standard )
	---Level: Public
	---Purpose: Modifies the intensity distribution of the light.
	--	    Works only on the TOLS_SPOT lights.
	--  Category: Methods to modify the class definition
	--  Warning: Raises LightDefinitionError
	--	    if the type of the light is not TOLS_SPOT.
	--	    if <Concentration> is a negative value or greater than 1.0.
	raises LightDefinitionError is static;

	SetDirection ( me		: mutable;
		       Direction	: Vector from Graphic3d )
	---Level: Public
	---Purpose: Modifies the light direction.
	--	    Works only on the TOLS_DIRECTIONAL and TOLS_SPOT lights.
	--	    Default z
	--  Category: Methods to modify the class definition
	--  Warning: Raises LightDefinitionError
	--	    if the type of the light is not TOLS_DIRECTIONAL
	--	    or TOLS_SPOT.
	--	    if <Direction> is null.
	raises LightDefinitionError is static;

	SetPosition ( me	: mutable;
		      Position	: Vertex from Graphic3d )
	---Level: Public
	---Purpose: Modifies the position of the light.
	--	    Works only on the TOLS_POSITIONAL and TOLS_SPOT lights.
	--  Category: Methods to modify the class definition
	--  Warning: Raises LightDefinitionError 
	--	    if the type of the light is not TOLS_POSITIONAL or TOLS_SPOT.
	raises LightDefinitionError is static;

	----------------------------
	-- Category: Inquire methods
	----------------------------

        Headlight  ( me ) 
	    	returns  Boolean  from  Standard  is  static; 
	---Level: Public
        ---Purpose:  Returns the headlight  state of the light <me>
        ---Category: Inquire methods
		
	Color ( me )
		returns Color from Quantity is static;
	---Level: Public
	---Purpose: Returns the colour of the light <me>.
	---Category: Inquire methods

	LightType ( me )
		returns TypeOfLightSource from Visual3d is static;
	---Level: Public
	---Purpose: Returns the light type of <me>.
	--
	--	    TypeOfLightSource = TOLS_AMBIENT
	--				TOLS_DIRECTIONAL
	--				TOLS_POSITIONAL
	--				TOLS_SPOT
	--
	---Category: Inquire methods

	Values ( me;
		 Color		: out Color from Quantity )
	---Level: Public
	---Purpose: Returns the definition of <me> if <me> is
	--	    a light source of the TOLS_AMBIENT type.
	--  Category: Inquire methods
	--  Warning: Raises LightDefinitionError 
	--	    if the type of the light is not TOLS_AMBIENT.
	raises LightDefinitionError is static;

	Values ( me;
		 Color		: out Color from Quantity;
		 Direction	: out Vector from Graphic3d )
	---Level: Public
	---Purpose: Returns the definition of <me> if <me> is
	--	    a light source of the TOLS_DIRECTIONAL type.
	--  Category: Inquire methods
	--  Warning: Raises LightDefinitionError 
	--	    if the type of the light is not TOLS_DIRECTIONAL.
	raises LightDefinitionError is static;

	Values ( me;
		 Color		: out Color from Quantity;
		 Position	: out Vertex from Graphic3d;
		 Fact1,Fact2	: out Real from Standard )
	---Level: Public
	---Purpose: Returns the definition of <me> if <me> is
	--	    a light source of the TOLS_POSITIONAL type.
	--  Category: Inquire methods
	--  Warning: Raises LightDefinitionError 
	--	    if the type of the light is not TOLS_POSITIONAL.
	raises LightDefinitionError is static;

	Values ( me;
		 Color		: out Color from Quantity;
		 Position	: out Vertex from Graphic3d;
		 Direction	: out Vector from Graphic3d;
		 Concentration	: out Real from Standard;
		 Fact1,Fact2	: out Real from Standard;
		 AngleCone	: out Real from Standard )
	---Level: Public
	---Purpose: Returns the definition of <me> if <me> is
	--	    a light source of the TOLS_SPOT type.
	--  Category: Inquire methods
	--  Warning: Raises LightDefinitionError 
	--	    if the type of the light is not TOLS_SPOT.
	raises LightDefinitionError is static;

	--------------------------
	-- Category: Class methods
	--------------------------

	Limit ( myclass )
		returns Integer from Standard;
	---Level: Internal
	---Purpose: Maximum number of activatable light sources.
	---Category: Class methods

	----------------------------
	-- Category: Private methods
	----------------------------

	Identification ( me )
		returns Integer from Standard
		is static private;
	---Level: Internal
	---Purpose: Returns the light identification.
	---Category: Private methods

	IsValid ( myclass;
		  AAngle	: Real from Standard )
		returns Boolean from Standard
		is private;
	---Level: Internal
	---Purpose: Returns True if <AAngle> is a valid
	--	    spot light spread angle.
	---Category: Private methods

--\f

fields

--
-- Class	:	Visual3d_Light
--
-- Purpose	:	Declaration of variables specific to light sources
--
-- Reminder	:	A light source is defined by:
--			- its type
--			- its colour
--			- the attenuation factor ( positional and spot only)
--			- its angle ( spot only )
--			- its concentration ( spot only )
--			- its direction ( directional and spot only )
--			- its position ( positional and spot only )
--
--			It is actived in a context of view.
--

	-- the type
	MyType		:	TypeOfLightSource from Visual3d;

	-- the associated C structure
	MyCLight	:	CLight from Graphic3d;

friends

	class View from Visual3d

end Light;
Commit	Line	Data
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
b311480e	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	20
	21	class Light from Visual3d inherits TShared
	22
	23	---Version:
	24
	25	---Purpose: This class defines and updates light sources.
	26	-- There is no limit to the number of light sources defined.
	27	-- Only the number of active sources is limited.
	28	--
	29	-- TypeOfLightSource = TOLS_AMBIENT
	30	-- TOLS_DIRECTIONAL
	31	-- TOLS_POSITIONAL
	32	-- TOLS_SPOT
	33	--
	34	-- Angle is a radian value.
	35	-- Concentration, Attenuation are in the [0,1] interval.
	36	--
	37
	38	---Keywords: Light, View, Context, Ambient, Directional, Positional,
	39	-- Spot, Angle, Concentration, Attenuation, Color, Shading
	40
	41	---Warning:
	42	---References:
	43
	44	uses
	45
	46	Color from Quantity,
	47
	48	CLight from Graphic3d,
	49	Vector from Graphic3d,
	50	Vertex from Graphic3d,
	51
	52	TypeOfLightSource from Visual3d
	53
	54	raises
	55
	56	LightDefinitionError from Visual3d
	57
	58	is
	59
	60	Create
	61	returns mutable Light from Visual3d;
	62	---Level: Public
	63	---Purpose: Creates a light from default values.
	64	-- Light sources are created in a visualiser
	65	-- and are activated in one of its views.
	66	--
	67	-- Type = TOLS_AMBIENT
	68	-- Color = WHITE
	69
	70	Create ( Color : Color from Quantity )
	71	returns mutable Light from Visual3d;
	72	---Level: Public
	73	---Purpose: Creates an AMBIENT light source.
	74	-- Light sources are created in a visualiser
	75	-- and are activated in one of its views.
	76
	77	Create ( Color : Color from Quantity;
	78	Direction : Vector from Graphic3d;
	79	Headlight : Boolean from Standard = Standard_False )
	80	returns mutable Light from Visual3d
	81	---Level: Public
	82	---Purpose: Creates a DIRECTIONAL light source.
	83	-- Light sources are created in a visualiser
84	-- and are activated in one of its views.
85	-- Warning: Raises LightDefinitionError if <Direction> is null.
86	raises LightDefinitionError;
87
88	Create ( Color : Color from Quantity;
89	Position : Vertex from Graphic3d;
90	Fact1, Fact2 : Real from Standard )
91	returns mutable Light from Visual3d
92	---Level: Public
93	---Purpose: Creates a POSITIONAL light source.
94	-- Light sources are created in a visualiser
95	-- and are activated in one of its views.
96	-- Warning: Raises LightDefinitionError
97	-- if <Fact1> and <Fact2> are null.
98	-- if <Fact1> is a negative value or greater than 1.0.
99	-- if <Fact2> is a negative value or greater than 1.0.
100	raises LightDefinitionError;
101
102	Create ( Color : Color from Quantity;
103	Position : Vertex from Graphic3d;
104	Direction : Vector from Graphic3d;
105	Concentration : Real from Standard;
106	Fact1, Fact2 : Real from Standard;
107	AngleCone : Real from Standard )
108	returns mutable Light from Visual3d
109	---Level: Public
110	---Purpose: Creates a SPOT light source.
111	-- Light sources are created in a visualiser
112	-- and are activated in one of its views.
113	-- <Concentration> specifies the intensity distribution of
114	-- the light.
115	-- <AngleCone> specifies the angle (radians) of the cone
116	-- created by the spot.
117	-- the global attenuation is equal :
118	-- 1 / (Fact1 + Fact2 * (norm(ObjectPosition - LightPosition)))
119	-- Warning: Raises LightDefinitionError
120	-- if <Direction> is null.
121	-- if <Concentration> is a negative value or greater than 1.0.
122	-- if <Fact1> and <Fact2> are null.
123	-- if <Fact1> is a negative value or greater than 1.0.
124	-- if <Fact2> is a negative value or greater than 1.0.
125	-- if <AngleCone> is a negative value or greater than PI/2.
126	raises LightDefinitionError;
127
128	---------------------------------------------------
129	-- Category: Methods to modify the class definition
130	---------------------------------------------------
131
132	SetAngle ( me : mutable;
133	AngleCone : Real from Standard )
134	---Level: Public
135	---Purpose: Modifies the angle (radians) of the cone created by the spot.
136	-- Works only on TOLS_SPOT lights.
137	-- Category: Methods to modify the class definition
138	-- Warning: Raises LightDefinitionError
139	-- if the type of the light is not TOLS_SPOT.
140	-- if <AngleCone> is a negative value or greater than PI/2.
141	raises LightDefinitionError is static;
142
143	SetAttenuation1 ( me : mutable;
144	Fact1 : Real from Standard )
145	---Level: Public
146	---Purpose: Modifies the attenuation factor of the light.
147	-- Works only on the TOLS_POSITIONAL and TOLS_SPOT lights.
148	-- Category: Methods to modify the class definition
149	-- Warning: Raises LightDefinitionError
150	-- if the type of the light is not TOLS_SPOT or TOLS_POSITIONAL.
151	-- if <Fact1> is a negative value or greater than 1.0.
152	raises LightDefinitionError is static;
153
154	SetAttenuation2 ( me : mutable;
155	Fact2 : Real from Standard )
156	---Level: Public
157	---Purpose: Modifies the attenuation factor of the light.
158	-- Works only on the TOLS_POSITIONAL and TOLS_SPOT lights.
159	-- Category: Methods to modify the class definition
160	-- Warning: Raises LightDefinitionError
161	-- if the type of the light is not TOLS_POSITIONAL or TOLS_SPOT.
162	-- if <Fact2> is a negative value or greater than 1.0..
163	raises LightDefinitionError is static;
164
165	SetColor ( me : mutable;
166	Color : Color from Quantity )
167	is static;
168	---Level: Public
169	---Purpose: Modifies the colour of the light.
170	---Category: Methods to modify the class definition
171
172	SetConcentration ( me : mutable;
173	Concentration : Real from Standard )
174	---Level: Public
175	---Purpose: Modifies the intensity distribution of the light.
176	-- Works only on the TOLS_SPOT lights.
177	-- Category: Methods to modify the class definition
178	-- Warning: Raises LightDefinitionError
179	-- if the type of the light is not TOLS_SPOT.
180	-- if <Concentration> is a negative value or greater than 1.0.
181	raises LightDefinitionError is static;
182
183	SetDirection ( me : mutable;
184	Direction : Vector from Graphic3d )
185	---Level: Public
186	---Purpose: Modifies the light direction.
187	-- Works only on the TOLS_DIRECTIONAL and TOLS_SPOT lights.
188	-- Default z
189	-- Category: Methods to modify the class definition
190	-- Warning: Raises LightDefinitionError
191	-- if the type of the light is not TOLS_DIRECTIONAL
192	-- or TOLS_SPOT.
193	-- if <Direction> is null.
194	raises LightDefinitionError is static;
195
196	SetPosition ( me : mutable;
197	Position : Vertex from Graphic3d )
198	---Level: Public
199	---Purpose: Modifies the position of the light.
200	-- Works only on the TOLS_POSITIONAL and TOLS_SPOT lights.
201	-- Category: Methods to modify the class definition
202	-- Warning: Raises LightDefinitionError
203	-- if the type of the light is not TOLS_POSITIONAL or TOLS_SPOT.
204	raises LightDefinitionError is static;
205
206	----------------------------
207	-- Category: Inquire methods
208	----------------------------
209
210	Headlight ( me )
211	returns Boolean from Standard is static;
212	---Level: Public
213	---Purpose: Returns the headlight state of the light <me>
214	---Category: Inquire methods
215
216	Color ( me )
217	returns Color from Quantity is static;
218	---Level: Public
219	---Purpose: Returns the colour of the light <me>.
220	---Category: Inquire methods
221
222	LightType ( me )
223	returns TypeOfLightSource from Visual3d is static;
224	---Level: Public
225	---Purpose: Returns the light type of <me>.
226	--
227	-- TypeOfLightSource = TOLS_AMBIENT
228	-- TOLS_DIRECTIONAL
229	-- TOLS_POSITIONAL
230	-- TOLS_SPOT
231	--
232	---Category: Inquire methods
233
234	Values ( me;
235	Color : out Color from Quantity )
236	---Level: Public
237	---Purpose: Returns the definition of <me> if <me> is
238	-- a light source of the TOLS_AMBIENT type.
239	-- Category: Inquire methods
240	-- Warning: Raises LightDefinitionError
241	-- if the type of the light is not TOLS_AMBIENT.
242	raises LightDefinitionError is static;
243
244	Values ( me;
245	Color : out Color from Quantity;
246	Direction : out Vector from Graphic3d )
247	---Level: Public
248	---Purpose: Returns the definition of <me> if <me> is
249	-- a light source of the TOLS_DIRECTIONAL type.
250	-- Category: Inquire methods
251	-- Warning: Raises LightDefinitionError
252	-- if the type of the light is not TOLS_DIRECTIONAL.
253	raises LightDefinitionError is static;
254
255	Values ( me;
256	Color : out Color from Quantity;
257	Position : out Vertex from Graphic3d;
258	Fact1,Fact2 : out Real from Standard )
259	---Level: Public
260	---Purpose: Returns the definition of <me> if <me> is
261	-- a light source of the TOLS_POSITIONAL type.
262	-- Category: Inquire methods
263	-- Warning: Raises LightDefinitionError
264	-- if the type of the light is not TOLS_POSITIONAL.
265	raises LightDefinitionError is static;
266
267	Values ( me;
268	Color : out Color from Quantity;
269	Position : out Vertex from Graphic3d;
270	Direction : out Vector from Graphic3d;
271	Concentration : out Real from Standard;
272	Fact1,Fact2 : out Real from Standard;
273	AngleCone : out Real from Standard )
274	---Level: Public
275	---Purpose: Returns the definition of <me> if <me> is
276	-- a light source of the TOLS_SPOT type.
277	-- Category: Inquire methods
278	-- Warning: Raises LightDefinitionError
279	-- if the type of the light is not TOLS_SPOT.
280	raises LightDefinitionError is static;
281
282	--------------------------
283	-- Category: Class methods
284	--------------------------
285
286	Limit ( myclass )
287	returns Integer from Standard;
288	---Level: Internal
289	---Purpose: Maximum number of activatable light sources.
290	---Category: Class methods
291
292	----------------------------
293	-- Category: Private methods
294	----------------------------
295
296	Identification ( me )
297	returns Integer from Standard
298	is static private;
299	---Level: Internal
300	---Purpose: Returns the light identification.
301	---Category: Private methods
302
303	IsValid ( myclass;
304	AAngle : Real from Standard )
305	returns Boolean from Standard
306	is private;
307	---Level: Internal
308	---Purpose: Returns True if <AAngle> is a valid
309	-- spot light spread angle.
310	---Category: Private methods
311
312	--\f
313
314	fields
315
316	--
317	-- Class : Visual3d_Light
318	--
319	-- Purpose : Declaration of variables specific to light sources
320	--
321	-- Reminder : A light source is defined by:
322	-- - its type
323	-- - its colour
324	-- - the attenuation factor ( positional and spot only)
325	-- - its angle ( spot only )
326	-- - its concentration ( spot only )
327	-- - its direction ( directional and spot only )
328	-- - its position ( positional and spot only )
329	--
330	-- It is actived in a context of view.
331	--
332
333	-- the type
334	MyType : TypeOfLightSource from Visual3d;
335
336	-- the associated C structure
337	MyCLight : CLight from Graphic3d;
338
339	friends
340
341	class View from Visual3d
342
343	end Light;