1 -- Created by: NW,JPB,CAL
2 -- Copyright (c) 1991-1999 Matra Datavision
3 -- Copyright (c) 1999-2014 OPEN CASCADE SAS
5 -- This file is part of Open CASCADE Technology software library.
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.
13 -- Alternatively, this file may be used under the terms of Open CASCADE
14 -- commercial license or contractual agreement.
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
27 class MaterialAspect from Graphic3d
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
43 NameOfMaterial from Graphic3d,
44 TypeOfReflection from Graphic3d,
45 TypeOfMaterial from Graphic3d,
46 AsciiString from TCollection
50 MaterialDefinitionError from Graphic3d,
51 OutOfRange from Standard
56 returns MaterialAspect from Graphic3d;
58 ---Purpose: Creates a material from default values.
59 ---Material is generic
61 Create ( AName : NameOfMaterial from Graphic3d )
62 returns MaterialAspect from Graphic3d;
64 ---Purpose: Creates a generic material calls <AName>
66 ---------------------------------------------------
67 -- Category: Methods to modify the class definition
68 ---------------------------------------------------
70 IncreaseShine ( me : in out;
71 ADelta : Real from Standard )
74 ---Purpose: Increases or decreases the luminosity of <me>.
75 -- <ADelta> is a signed percentage.
76 ---Category: Methods to modify the class definition
78 SetAmbient ( me : in out;
79 AValue : Real from Standard )
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;
87 SetDiffuse ( me : in out;
88 AValue : Real from Standard )
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;
96 SetEmissive ( me : in out;
97 AValue : Real from Standard )
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;
105 SetShininess ( me : in out;
106 AValue : Real from Standard )
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;
114 SetSpecular ( me : in out;
115 AValue : Real from Standard )
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;
123 SetTransparency ( me : in out;
124 AValue : Real from Standard )
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.
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;
146 SetColor ( me : in out;
147 AColor : Color from Quantity )
150 ---Purpose: Modifies the ambient colour of the surface.
151 -- Category: Methods to modify the class definition
153 SetAmbientColor ( me : in out;
154 AColor : Color from Quantity )
157 ---Purpose: Modifies the ambient colour of the surface.
158 ---Category: Methods to modify the class definition
160 SetDiffuseColor ( me : in out;
161 AColor : Color from Quantity )
164 ---Purpose: Modifies the difuse colour of the surface.
165 ---Category: Methods to modify the class definition
167 SetSpecularColor ( me : in out;
168 AColor : Color from Quantity )
171 ---Purpose: Modifies the specular colour of the surface.
172 ---Category: Methods to modify the class definition
174 SetEmissiveColor ( me : in out;
175 AColor : Color from Quantity )
178 ---Purpose: Modifies the emissive colour of the surface.
179 ---Category: Methods to modify the class definition
182 SetReflectionModeOn ( me : in out;
183 AType : TypeOfReflection from Graphic3d )
186 ---Purpose: Activates the reflective properties of the surface <AType>.
188 -- TypeOfReflection : TOR_AMBIENT
192 -- 1, 2, 3 or 4 types of reflection can be set for a given surface.
193 ---Category: Methods to modify the class definition
195 SetReflectionModeOff ( me : in out;
196 AType : TypeOfReflection from Graphic3d )
199 ---Purpose: Deactivates the reflective properties of
200 -- the surface <AType>.
202 -- TypeOfReflection : TOR_AMBIENT
206 -- 1, 2, 3 or 4 types of reflection can be set off for a given surface.
207 -- Disabling diffuse and specular reflectance is useful for efficient visualization
208 -- of large amounts of data as definition of normals for graphic primitives is not needed
209 -- when only "all-directional" reflectance is active.
211 -- NOTE: Disabling all four reflection modes also turns off the following effects:
212 -- 1. Lighting. Colors of primitives are not affected by the material properties when lighting is off.
214 ---Category: Methods to modify the class definition
216 SetMaterialType ( me : in out;
217 AType : TypeOfMaterial from Graphic3d )
220 ---Purpose: Set MyMaterialType to the value of parameter <AType>
222 -- TypeOfMaterial : MATERIAL_ASPECT
224 ---Category: Methods to modify the class definition
226 SetMaterialName ( me : in out;
227 AName : CString from Standard )
230 ---Purpose: The current matarial become a "UserDefined" material.
231 -- Set the name of the "UserDefined" material.
232 ---Category: Methods to modify the class definition
234 SetEnvReflexion(me : in out;
235 AValue : ShortReal from Standard );
239 ---Purpose: Resets the material with the original values according to
240 -- the material name but leave the current color values untouched
241 -- for the material of type ASPECT.
242 ---Category: Methods to modify the class definition
244 ----------------------------
245 -- Category: Inquire methods
246 ----------------------------
249 returns Color from Quantity
251 ---C++: return const&
253 ---Purpose: Returns the ambient colour of the surface.
254 ---Category: Inquire methods
257 returns Color from Quantity
259 ---C++: return const&
261 ---Purpose: Returns the ambient colour of the surface.
262 ---Category: Inquire methods
265 returns Color from Quantity
267 ---C++: return const&
269 ---Purpose: Returns the diffuse colour of the surface.
270 ---Category: Inquire methods
273 returns Color from Quantity
275 ---C++: return const&
277 ---Purpose: Returns the specular colour of the surface.
278 ---Category: Inquire methods
281 returns Color from Quantity
283 ---C++: return const&
285 ---Purpose: Returns the emissive colour of the surface.
286 ---Category: Inquire methods
289 returns Real from Standard
292 ---Purpose: Returns the reflection properties of the surface.
293 ---Category: Inquire methods
296 returns Real from Standard
299 ---Purpose: Returns the reflection properties of the surface.
300 ---Category: Inquire methods
303 returns Real from Standard
306 ---Purpose: Returns the reflection properties of the surface.
307 ---Category: Inquire methods
310 returns Real from Standard
313 ---Purpose: Returns the transparency coefficient of the surface.
314 ---Category: Inquire methods
317 returns Real from Standard
320 ---Purpose: Returns the emissive coefficient of the surface.
321 ---Category: Inquire methods
324 returns Real from Standard
327 ---Purpose: Returns the luminosity of the surface.
328 ---Category: Inquire methods
331 AType : TypeOfReflection from Graphic3d )
332 returns Boolean from Standard
335 ---Purpose: Returns Standard_True if the reflection mode is active,
336 -- Standard_False otherwise.
337 ---Category: Inquire methods
340 AType : TypeOfMaterial from Graphic3d )
341 returns Boolean from Standard
344 ---Purpose: Returns Standard_True if MyMaterialType equal the parameter AType,
345 -- Standard_False otherwise.
346 ---Category: Inquire methods
349 returns ShortReal from Standard;
352 returns NameOfMaterial from Graphic3d;
354 ---Purpose: Returns the material name.
355 ---Category: Inquire methods
358 Other : MaterialAspect from Graphic3d )
359 returns Boolean from Standard is static;
360 ---Purpose: Returns Standard_True if the materials <me> and
361 -- <Other> are different.
362 ---Category: Inquire methods
363 ---C++: alias operator !=
366 Other : MaterialAspect from Graphic3d )
367 returns Boolean from Standard is static;
368 ---Purpose: Returns Standard_True if the materials <me> and
369 -- <Other> are identical.
370 ---Category: Inquire methods
371 ---C++: alias operator ==
373 NumberOfMaterials(myclass) returns Integer from Standard;
375 -- Returns the number of predefined textures.
378 MaterialName(myclass; aRank: Integer from Standard)
379 returns CString from Standard
380 raises OutOfRange from Standard;
382 -- Returns the name of the predefined material of rank <aRank>
383 -- Trigger: when <aRank> is < 1 or > NumberOfMaterials.
387 returns CString from Standard;
389 -- Returns the name of this material
392 MaterialType(myclass; aRank: Integer from Standard)
393 returns TypeOfMaterial from Graphic3d
394 raises OutOfRange from Standard;
396 -- Returns the type of the predefined material of rank <aRank>
397 -- Trigger: when <aRank> is < 1 or > NumberOfMaterials.
400 ----------------------------
401 -- Category: Private methods
402 ----------------------------
404 Init ( me : out; AName : NameOfMaterial from Graphic3d) is private;
411 -- Class : Graphic3d_MaterialAspect
413 -- purpose : Declaration of variables specific to the definition
416 -- Reminders : A material is defines by:
417 -- - A coefficient of transparency
418 -- - A coefficient of diffuse reflection
419 -- - A coefficient of ambiant reflection
420 -- - A coefficient of specular reflection
421 -- - A emissive coefficient
423 -- Two properties define a material :
424 -- - its transparency
425 -- - its reflection which is to say its properties of
426 -- - absorbtion and diffusion of light
428 -- The diffuse reflection is seen as a component
429 -- of the colour of the object.
430 -- The specular reflection is seen as a component
431 -- of the colour of the light source
433 -- To determine the three colours of reflection,
434 -- four things are required:
435 -- - A coefficient of diffuse reflection
436 -- - A coefficient of ambiant reflection
437 -- - A coefficient of specular reflection
439 -- ( Under GL, the Silicon graphics interface,
440 -- we need to determine 3 colours )
442 -- References : Getting started with DEC PHIGS, appendix C
443 -- Iris Advanced Graphics, unit D
446 -- the coefficient of diffuse reflection, the colour, and the activity
447 MyDiffuseCoef : ShortReal from Standard;
448 MyDiffuseColor : Color from Quantity;
449 MyDiffuseActivity : Boolean from Standard;
451 -- the coefficient of ambient reflection, the colour
453 MyAmbientCoef : ShortReal from Standard;
454 MyAmbientColor : Color from Quantity;
455 MyAmbientActivity : Boolean from Standard;
457 -- the coefficient of specular reflection, the colour
459 MySpecularCoef : ShortReal from Standard;
460 MySpecularColor : Color from Quantity;
461 MySpecularActivity : Boolean from Standard;
463 -- the coefficient of emissive reflection
464 MyEmissiveCoef : ShortReal from Standard;
465 MyEmissiveColor : Color from Quantity;
466 MyEmissiveActivity : Boolean from Standard;
468 -- the coefficient of transparency
469 MyTransparencyCoef : ShortReal from Standard;
471 -- the coefficient of luminosity
472 MyShininess : ShortReal from Standard;
475 -- the coeficient of reflexion for the environment texture
476 MyEnvReflexion : ShortReal from Standard;
478 -- the type of material
479 --MyMaterialType : Boolean from Standard;
480 MyMaterialType : TypeOfMaterial from Graphic3d;
482 -- the Name of material
483 MyMaterialName : NameOfMaterial from Graphic3d;
484 MyRequestedMaterialName : NameOfMaterial from Graphic3d;
486 -- the string name of the material
487 MyStringName : AsciiString from TCollection;