e4077eed2e2c41b4d9ee14f4a7251415099c8b8e
[occt.git] / src / Graphic3d / Graphic3d_MaterialAspect.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 --        28-07-97 : PCT ; support for texture mapping
17 --        08-04-98 : FGU ; support for emission
18 --        26-03-99 : FMN ; Compatibilite ascendante: Ajout methodes SetColor() et Color()
19 --        09-04-99 : GG ; Compatibilite ascendante:
20 --                         NameOfPhysicalMaterial disparait.
21
22 class MaterialAspect from Graphic3d
23
24         ---Version:
25
26         ---Purpose: This class allows the definition of the type of a surface.
27         --          Aspect attributes of a 3d face.
28         --  Keywords: Material, FillArea, Shininess, Ambient, Color, Diffuse,
29         --           Specular, Transparency, Emissive, ReflectionMode,
30         --           BackFace, FrontFace, Reflection, Absorbtion
31
32         ---Warning:
33         ---References:
34
35 uses
36
37         Color                   from Quantity,
38
39         NameOfMaterial          from Graphic3d,
40         TypeOfReflection        from Graphic3d,
41         TypeOfMaterial          from Graphic3d,
42         AsciiString             from TCollection
43
44 raises
45
46         MaterialDefinitionError from Graphic3d,
47         OutOfRange from Standard
48
49 is
50
51         Create
52                 returns MaterialAspect from Graphic3d;
53         ---Level: Public
54         ---Purpose: Creates a material from default values.
55         ---Material is generic
56
57         Create ( AName  : NameOfMaterial from Graphic3d )
58                  returns MaterialAspect from Graphic3d;
59         ---Level: Public
60         ---Purpose: Creates a generic material calls <AName>
61         
62         ---------------------------------------------------
63         -- Category: Methods to modify the class definition
64         ---------------------------------------------------
65
66         IncreaseShine ( me      : in out;
67                         ADelta  : Real from Standard )
68                 is static;
69         ---Level: Public
70         ---Purpose: Increases or decreases the luminosity of <me>.
71         --          <ADelta> is a signed percentage.
72         ---Category: Methods to modify the class definition
73
74         SetAmbient ( me         : in out;
75                      AValue     : Real from Standard )
76         ---Level: Public
77         ---Purpose: Modifies the reflection properties of the surface.
78         --  Category: Methods to modify the class definition
79         --  Warning: Raises MaterialDefinitionError if <AValue> is
80         --          a negative value or greater than 1.0.
81         raises MaterialDefinitionError from Graphic3d is static;
82
83         SetDiffuse ( me         : in out;
84                      AValue     : Real from Standard )
85         ---Level: Public
86         ---Purpose: Modifies the reflection properties of the surface.
87         --  Category: Methods to modify the class definition
88         --  Warning: Raises MaterialDefinitionError if <AValue> is a
89         --          negative value or greater than 1.0.
90         raises MaterialDefinitionError from Graphic3d is static;
91         
92         SetEmissive ( me                : in out;
93                      AValue     : Real from Standard )
94         ---Level: Public
95         ---Purpose: Modifies the reflection properties of the surface.
96         --  Category: Methods to modify the class definition
97         --  Warning: Raises MaterialDefinitionError if <AValue> is a
98         --          negative value or greater than 1.0.
99         raises MaterialDefinitionError from Graphic3d is static;
100         
101         SetShininess ( me       : in out;
102                       AValue    : Real from Standard )
103         ---Level: Public
104         ---Purpose: Modifies the luminosity of the surface.
105         --  Category: Methods to modify the class definition
106         --  Warning: Raises MaterialDefinitionError if <AValue> is a
107         --          negative value or greater than 1.0.
108         raises MaterialDefinitionError from Graphic3d is static;
109
110         SetSpecular ( me        : in out;
111                       AValue    : Real from Standard )
112         ---Level: Public
113         ---Purpose: Modifies the reflection properties of the surface.
114         --  Category: Methods to modify the class definition
115         --  Warning: Raises MaterialDefinitionError if <AValue> is a
116         --          negative value or greater than 1.0.
117         raises MaterialDefinitionError from Graphic3d is static;
118
119         SetTransparency ( me            : in out;
120                           AValue        : Real from Standard )
121         ---Level: Public
122         ---Purpose:  Modifies the transparency coefficient of the surface.
123         --  <AValue> = 0. opaque. (default)
124         --  <AValue> = 1. transparent.
125         --  Transparency is applicable to materials that have at least
126         --  one of reflection modes (ambient, diffuse, specular or emissive)
127         --  enabled. See also SetReflectionModeOn() and SetReflectionModeOff() methods.
128         --      
129         --  NOTE: In order for transparency specified through this method to 
130         --  take effect, it is necessary to enable transparency 
131         --  in the viewer. This can be done either directly -
132         --  see Visual3d_ViewManager::SetTransparency(Standard_Boolean),
133         --  or indirectly - by calling AIS_InteractiveObject::SetTransparency()
134         --  before an object is added to an interactive context, or by
135         --  calling AIS_InteractiveContext::SetTransparency() for a given 
136         --  interactive object already displayed.
137         --  Category: Methods to modify the class definition
138         --  Warning: Raises MaterialDefinitionError if <AValue> is a
139         --          negative value or greater than 1.0.
140         raises MaterialDefinitionError from Graphic3d is static;
141
142         SetRefractionIndex ( me : in out;
143                       theValue  : Real from Standard )
144         ---Level: Public
145         ---Purpose: Modifies the refraction index of the material.
146         --  Category: Methods to modify the class definition
147         --  Warning: Raises MaterialDefinitionError if <theValue> is a
148         --          lesser than 1.0.
149         raises MaterialDefinitionError from Graphic3d is static;
150
151         SetColor ( me           : in out;
152                    AColor       : Color from Quantity )
153                 is static;
154         ---Level: Public
155         ---Purpose: Modifies the ambient and diffuse colour of the surface.
156         --  Category: Methods to modify the class definition
157         
158         SetAmbientColor ( me            : in out;
159                           AColor        : Color from Quantity )
160                 is static;
161         ---Level: Public
162         ---Purpose: Modifies the ambient colour of the surface.
163         ---Category: Methods to modify the class definition
164         
165         SetDiffuseColor ( me            : in out;
166                           AColor        : Color from Quantity )
167                 is static;
168         ---Level: Public
169         ---Purpose: Modifies the difuse colour of the surface.
170         ---Category: Methods to modify the class definition
171         
172         SetSpecularColor ( me           : in out;
173                           AColor        : Color from Quantity )
174                 is static;
175         ---Level: Public
176         ---Purpose: Modifies the specular colour of the surface.
177         ---Category: Methods to modify the class definition
178         
179         SetEmissiveColor ( me           : in out;
180                           AColor        : Color from Quantity )
181                 is static;
182         ---Level: Public
183         ---Purpose: Modifies the emissive colour of the surface.
184         ---Category: Methods to modify the class definition
185
186         
187         SetReflectionModeOn ( me        : in out;
188                               AType     : TypeOfReflection from Graphic3d )
189                 is static;
190         ---Level: Public
191         ---Purpose: Activates the reflective properties of the surface <AType>.
192         --
193         --          TypeOfReflection : TOR_AMBIENT
194         --                             TOR_DIFFUSE
195         --                             TOR_SPECULAR
196         --                             TOR_EMISSION
197         -- 1, 2, 3 or 4 types of reflection can be set for a given surface.
198         ---Category: Methods to modify the class definition
199
200         SetReflectionModeOff ( me       : in out;
201                                AType    : TypeOfReflection from Graphic3d )
202                 is static;
203         ---Level: Public
204         ---Purpose: Deactivates the reflective properties of
205         --          the surface <AType>.
206         --
207         --          TypeOfReflection : TOR_AMBIENT
208         --                             TOR_DIFFUSE
209         --                             TOR_SPECULAR
210         --                             TOR_EMISSION
211         --  1, 2, 3 or 4 types of reflection can be set off for a given surface.
212         --  Disabling diffuse and specular reflectance is useful for efficient visualization
213         --  of large amounts of data as definition of normals for graphic primitives is not needed
214         --  when only "all-directional" reflectance is active.
215         --
216         --  NOTE: Disabling all four reflection modes also turns off the following effects:
217         --  1. Lighting. Colors of primitives are not affected by the material properties when lighting is off.
218         --  2. Transparency. 
219         ---Category: Methods to modify the class definition
220
221         SetMaterialType ( me    : in out;
222                           AType : TypeOfMaterial from Graphic3d )
223                 is static;
224         ---Level: Public
225         ---Purpose: Set MyMaterialType to the value of parameter <AType>
226         --
227         --          TypeOfMaterial :   MATERIAL_ASPECT
228         --                             MATERIAL_PHYSIC
229         ---Category: Methods to modify the class definition
230
231         SetMaterialName ( me    : in out;
232                           AName : CString from Standard )
233                 is static;
234         ---Level: Public
235         ---Purpose: The current matarial become a "UserDefined" material.
236         --          Set the name of the "UserDefined" material.
237         ---Category: Methods to modify the class definition
238
239         SetEnvReflexion(me  :  in  out; 
240                         AValue  :  ShortReal  from  Standard  );
241
242         Reset(me : out);
243         ---Level: Public
244         ---Purpose: Resets the material with the original values according to
245         -- the material name but leave the current color values untouched 
246         -- for the material of type ASPECT.
247         ---Category: Methods to modify the class definition
248
249         ----------------------------
250         -- Category: Inquire methods
251         ----------------------------
252
253         Color ( me )
254                 returns Color from Quantity
255                 is static;
256   ---C++: return const&
257         ---Level: Public
258         ---Purpose: Returns the diffuse colour of the surface.
259         ---Category: Inquire methods
260
261         AmbientColor ( me )
262                 returns Color from Quantity
263                 is static;
264   ---C++: return const&
265         ---Level: Public
266         ---Purpose: Returns the ambient colour of the surface.
267         ---Category: Inquire methods
268                 
269         DiffuseColor ( me )
270                 returns Color from Quantity
271                 is static;
272   ---C++: return const&
273         ---Level: Public
274         ---Purpose: Returns the diffuse colour of the surface.
275         ---Category: Inquire methods
276         
277         SpecularColor ( me )
278                 returns Color from Quantity
279                 is static;
280   ---C++: return const&
281         ---Level: Public
282         ---Purpose: Returns the specular colour of the surface.
283         ---Category: Inquire methods
284         
285         EmissiveColor ( me )
286                 returns Color from Quantity
287                 is static;
288   ---C++: return const&
289         ---Level: Public
290         ---Purpose: Returns the emissive colour of the surface.
291         ---Category: Inquire methods
292         
293         Ambient ( me )
294                 returns Real from Standard
295                 is static;
296         ---Level: Public
297         ---Purpose: Returns the reflection properties of the surface.
298         ---Category: Inquire methods
299
300         Diffuse ( me )
301                 returns Real from Standard
302                 is static;
303         ---Level: Public
304         ---Purpose: Returns the reflection properties of the surface.
305         ---Category: Inquire methods
306         
307         Specular ( me )
308                 returns Real from Standard
309                 is static;
310         ---Level: Public
311         ---Purpose: Returns the reflection properties of the surface.
312         ---Category: Inquire methods
313
314         Transparency ( me )
315                 returns Real from Standard
316                 is static;
317         ---Level: Public
318         ---Purpose: Returns the transparency coefficient of the surface.
319         ---Category: Inquire methods
320
321         RefractionIndex ( me )
322                 returns Real from Standard
323                 is static;
324         ---Level: Public
325         ---Purpose: Returns the refraction index of the material
326         ---Category: Inquire methods
327
328   Emissive ( me )
329                 returns Real from Standard
330                 is static;
331         ---Level: Public
332         ---Purpose: Returns the emissive coefficient of the surface.
333         ---Category: Inquire methods 
334
335         Shininess ( me )
336                 returns Real from Standard
337                 is static;
338         ---Level: Public
339         ---Purpose: Returns the luminosity of the surface.
340         ---Category: Inquire methods
341
342         ReflectionMode ( me;
343                          AType  : TypeOfReflection from Graphic3d )
344                 returns Boolean from Standard
345                 is static;
346         ---Level: Public
347         ---Purpose: Returns Standard_True if the reflection mode is active,
348         --          Standard_False otherwise.
349         ---Category: Inquire methods
350         
351         MaterialType ( me;
352                        AType    : TypeOfMaterial from Graphic3d )
353                 returns Boolean from Standard
354                 is static;
355         ---Level: Public
356         ---Purpose: Returns Standard_True if MyMaterialType equal the parameter AType,
357         --          Standard_False otherwise.
358         ---Category: Inquire methods
359
360         EnvReflexion(me) 
361                 returns  ShortReal  from  Standard;
362
363         Name(me)
364                 returns NameOfMaterial from Graphic3d;
365         ---Level: Public
366         ---Purpose: Returns the material name.
367         ---Category: Inquire methods
368
369         IsDifferent ( me;
370                       Other     : MaterialAspect from Graphic3d )
371                 returns Boolean from Standard is static;
372         ---Purpose: Returns Standard_True if the materials <me> and
373         --          <Other> are different.
374         ---Category: Inquire methods
375         ---C++: alias operator !=
376
377         IsEqual ( me;
378                       Other     : MaterialAspect from Graphic3d )
379                 returns Boolean from Standard is static;
380         ---Purpose: Returns Standard_True if the materials <me> and
381         --          <Other> are identical.
382         ---Category: Inquire methods
383         ---C++: alias operator ==
384
385         NumberOfMaterials(myclass) returns Integer from Standard;
386         ---Purpose:
387         -- Returns the number of predefined textures.
388         ---Level: Public
389
390         MaterialName(myclass; aRank: Integer from Standard)
391             returns CString from Standard
392         raises OutOfRange from Standard;
393         ---Purpose:
394         -- Returns the name of the predefined material of rank <aRank>
395         --  Trigger: when <aRank> is < 1 or > NumberOfMaterials.
396         ---Level: Public
397
398         MaterialName(me)
399             returns CString from Standard;
400         ---Purpose:
401         -- Returns the name of this material
402         ---Level: Public
403
404         MaterialType(myclass; aRank: Integer from Standard)
405             returns TypeOfMaterial from Graphic3d 
406         raises OutOfRange from Standard;
407         ---Purpose:
408         -- Returns the type of the predefined material of rank <aRank>
409         --  Trigger: when <aRank> is < 1 or > NumberOfMaterials.
410         ---Level: Public
411
412         MaterialFromName (myclass;
413                           theName : CString from Standard)
414         returns NameOfMaterial from Graphic3d;
415         ---Purpose:
416         -- Returns the material for specified name or Graphic3d_NOM_DEFAULT if name is unknown.
417
418         ----------------------------
419         -- Category: Private methods
420         ----------------------------
421
422         Init ( me : out; AName  : NameOfMaterial from Graphic3d) is private;
423
424 --
425
426 fields
427
428 --
429 -- Class        :       Graphic3d_MaterialAspect
430 --
431 -- purpose      :       Declaration of variables specific to the definition
432 --                      of materials.
433 --
434 -- Reminders    :       A material is defines by:
435 --                      - A coefficient of transparency
436 --                      - A coefficient of diffuse reflection
437 --                      - A coefficient of ambiant reflection
438 --                      - A coefficient of specular reflection
439 --                      - A emissive coefficient
440 --
441 --                      Two properties define a material :
442 --                      - its transparency
443 --                      - its reflection which is to say its properties of
444 --                      - absorbtion and diffusion of light
445 --
446 --                      The diffuse reflection is seen as a component
447 --                      of the colour of the object.
448 --                      The specular reflection is seen as a component
449 --                      of the colour of the light source
450 --
451 --                      To determine the three colours of reflection,
452 --                      four things are required:
453 --                      - A coefficient of diffuse reflection
454 --                      - A coefficient of ambiant reflection
455 --                      - A coefficient of specular reflection
456 --
457 --                      ( Under GL, the Silicon graphics interface,
458 --                      we need to determine 3 colours )
459 --
460 -- References   :       Getting started with DEC PHIGS, appendix C
461 --                      Iris Advanced Graphics, unit D
462 --
463 --
464   -- the coefficient of diffuse reflection, the colour, and the activity
465   myDiffuseCoef     : ShortReal from Standard;
466   myDiffuseColor    : Color     from Quantity;
467   myDiffuseActivity : Boolean   from Standard;
468
469   -- the coefficient of ambient reflection, the colour and the activity
470   myAmbientCoef     : ShortReal from Standard;
471   myAmbientColor    : Color     from Quantity;
472   myAmbientActivity : Boolean   from Standard;
473
474   -- the coefficient of specular reflection, the colour and the activity
475   mySpecularCoef     : ShortReal from Standard;
476   mySpecularColor    : Color from Quantity;
477   mySpecularActivity : Boolean from Standard;
478
479   -- the coefficient of emissive reflection
480   myEmissiveCoef     : ShortReal from Standard;
481   myEmissiveColor    : Color     from Quantity;
482   myEmissiveActivity : Boolean   from Standard;
483
484   -- the coefficient of transparency and refraction index
485   myTransparencyCoef  : ShortReal from Standard;
486   myRefractionIndex   : ShortReal from Standard;
487
488   -- the specular exponent
489   myShininess    : ShortReal from Standard;
490
491   -- the coeficient of reflexion for the environment texture
492   myEnvReflexion : ShortReal from Standard;
493
494   -- the type of material
495   myMaterialType : TypeOfMaterial from Graphic3d;
496
497   -- the Name of material
498   myMaterialName          : NameOfMaterial from Graphic3d;
499   myRequestedMaterialName : NameOfMaterial from Graphic3d;
500
501   -- the string name of the material
502   myStringName : AsciiString from TCollection;
503
504 end MaterialAspect;