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