[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

  SetHeadlight( me : mutable; theValue : Boolean from Standard ) is static;
  ---Level: Public
  ---Purpose: Setup headlight flag.

	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;

  CLight ( me )
  returns CLight from Graphic3d
  is static;
  ---C++: return const &
  ---Level: Public
  ---Purpose: Returns the light defintion.
  ---Category: Inquire methods

	--------------------------
	-- Category: Class 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

--

fields

  -- 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	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
12381341	45	Color from Quantity,
	46	CLight from Graphic3d,
	47	Vector from Graphic3d,
	48	Vertex from Graphic3d,
	49	TypeOfLightSource from Visual3d
7fd59977	50
	51	raises
	52
12381341	53	LightDefinitionError from Visual3d
7fd59977	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
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	--
7fd59977	305
12381341	306	fields
7fd59977	307
12381341	308	-- the associated C structure
12381341	309	myCLight : CLight from Graphic3d;
7fd59977	310
	311	friends
	312
	313	class View from Visual3d
	314
	315	end Light;