0024704: Visualization - inherit OpenGl_Structure from Graphic3d_CStructure
[occt.git] / src / Graphic3d / Graphic3d_MaterialAspect.cdl
CommitLineData
b311480e 1-- Created by: NW,JPB,CAL
2-- Copyright (c) 1991-1999 Matra Datavision
973c2be1 3-- Copyright (c) 1999-2014 OPEN CASCADE SAS
7fd59977 4--
973c2be1 5-- This file is part of Open CASCADE Technology software library.
7fd59977 6--
d5f74e42 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
973c2be1 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.
7fd59977 12--
973c2be1 13-- Alternatively, this file may be used under the terms of Open CASCADE
14-- commercial license or contractual agreement.
b311480e 15
7fd59977 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
27class 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
39uses
40
41 Color from Quantity,
42
43 NameOfMaterial from Graphic3d,
44 TypeOfReflection from Graphic3d,
45 TypeOfMaterial from Graphic3d,
46 AsciiString from TCollection
47
48raises
49
50 MaterialDefinitionError from Graphic3d,
51 OutOfRange from Standard
52
53is
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 SetColor ( me : in out;
147 AColor : Color from Quantity )
148 is static;
149 ---Level: Public
150 ---Purpose: Modifies the ambient colour of the surface.
151 -- Category: Methods to modify the class definition
152
153 SetAmbientColor ( me : in out;
154 AColor : Color from Quantity )
155 is static;
156 ---Level: Public
157 ---Purpose: Modifies the ambient colour of the surface.
158 ---Category: Methods to modify the class definition
159
160 SetDiffuseColor ( me : in out;
161 AColor : Color from Quantity )
162 is static;
163 ---Level: Public
164 ---Purpose: Modifies the difuse colour of the surface.
165 ---Category: Methods to modify the class definition
166
167 SetSpecularColor ( me : in out;
168 AColor : Color from Quantity )
169 is static;
170 ---Level: Public
171 ---Purpose: Modifies the specular colour of the surface.
172 ---Category: Methods to modify the class definition
173
174 SetEmissiveColor ( me : in out;
175 AColor : Color from Quantity )
176 is static;
177 ---Level: Public
178 ---Purpose: Modifies the emissive colour of the surface.
179 ---Category: Methods to modify the class definition
180
181
182 SetReflectionModeOn ( me : in out;
183 AType : TypeOfReflection from Graphic3d )
184 is static;
185 ---Level: Public
186 ---Purpose: Activates the reflective properties of the surface <AType>.
187 --
188 -- TypeOfReflection : TOR_AMBIENT
189 -- TOR_DIFFUSE
190 -- TOR_SPECULAR
191 -- TOR_EMISSION
192 -- 1, 2, 3 or 4 types of reflection can be set for a given surface.
193 ---Category: Methods to modify the class definition
194
195 SetReflectionModeOff ( me : in out;
196 AType : TypeOfReflection from Graphic3d )
197 is static;
198 ---Level: Public
199 ---Purpose: Deactivates the reflective properties of
200 -- the surface <AType>.
201 --
202 -- TypeOfReflection : TOR_AMBIENT
203 -- TOR_DIFFUSE
204 -- TOR_SPECULAR
205 -- TOR_EMISSION
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.
210 --
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.
213 -- 2. Transparency.
214 ---Category: Methods to modify the class definition
215
216 SetMaterialType ( me : in out;
217 AType : TypeOfMaterial from Graphic3d )
218 is static;
219 ---Level: Public
220 ---Purpose: Set MyMaterialType to the value of parameter <AType>
221 --
222 -- TypeOfMaterial : MATERIAL_ASPECT
223 -- MATERIAL_PHYSIC
224 ---Category: Methods to modify the class definition
225
226 SetMaterialName ( me : in out;
227 AName : CString from Standard )
228 is static;
229 ---Level: Public
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
233
234 SetEnvReflexion(me : in out;
235 AValue : ShortReal from Standard );
236
237 Reset(me : out);
238 ---Level: Public
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
243
244 ----------------------------
245 -- Category: Inquire methods
246 ----------------------------
247
248 Color ( me )
249 returns Color from Quantity
250 is static;
63bcc448 251 ---C++: return const&
7fd59977 252 ---Level: Public
253 ---Purpose: Returns the ambient colour of the surface.
254 ---Category: Inquire methods
255
256 AmbientColor ( me )
257 returns Color from Quantity
258 is static;
63bcc448 259 ---C++: return const&
7fd59977 260 ---Level: Public
261 ---Purpose: Returns the ambient colour of the surface.
262 ---Category: Inquire methods
263
264 DiffuseColor ( me )
265 returns Color from Quantity
266 is static;
63bcc448 267 ---C++: return const&
7fd59977 268 ---Level: Public
269 ---Purpose: Returns the diffuse colour of the surface.
270 ---Category: Inquire methods
271
272 SpecularColor ( me )
273 returns Color from Quantity
274 is static;
63bcc448 275 ---C++: return const&
7fd59977 276 ---Level: Public
277 ---Purpose: Returns the specular colour of the surface.
278 ---Category: Inquire methods
279
280 EmissiveColor ( me )
281 returns Color from Quantity
282 is static;
63bcc448 283 ---C++: return const&
7fd59977 284 ---Level: Public
285 ---Purpose: Returns the emissive colour of the surface.
286 ---Category: Inquire methods
287
288 Ambient ( me )
289 returns Real from Standard
290 is static;
291 ---Level: Public
292 ---Purpose: Returns the reflection properties of the surface.
293 ---Category: Inquire methods
294
295 Diffuse ( me )
296 returns Real from Standard
297 is static;
298 ---Level: Public
299 ---Purpose: Returns the reflection properties of the surface.
300 ---Category: Inquire methods
301
302 Specular ( me )
303 returns Real from Standard
304 is static;
305 ---Level: Public
306 ---Purpose: Returns the reflection properties of the surface.
307 ---Category: Inquire methods
308
309 Transparency ( me )
310 returns Real from Standard
311 is static;
312 ---Level: Public
313 ---Purpose: Returns the transparency coefficient of the surface.
314 ---Category: Inquire methods
315
316 Emissive ( me )
317 returns Real from Standard
318 is static;
319 ---Level: Public
320 ---Purpose: Returns the emissive coefficient of the surface.
321 ---Category: Inquire methods
322
323 Shininess ( me )
324 returns Real from Standard
325 is static;
326 ---Level: Public
327 ---Purpose: Returns the luminosity of the surface.
328 ---Category: Inquire methods
329
330 ReflectionMode ( me;
331 AType : TypeOfReflection from Graphic3d )
332 returns Boolean from Standard
333 is static;
334 ---Level: Public
335 ---Purpose: Returns Standard_True if the reflection mode is active,
336 -- Standard_False otherwise.
337 ---Category: Inquire methods
338
339 MaterialType ( me;
340 AType : TypeOfMaterial from Graphic3d )
341 returns Boolean from Standard
342 is static;
343 ---Level: Public
344 ---Purpose: Returns Standard_True if MyMaterialType equal the parameter AType,
345 -- Standard_False otherwise.
346 ---Category: Inquire methods
347
348 EnvReflexion(me)
349 returns ShortReal from Standard;
350
351 Name(me)
352 returns NameOfMaterial from Graphic3d;
353 ---Level: Public
354 ---Purpose: Returns the material name.
355 ---Category: Inquire methods
356
357 IsDifferent ( me;
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 !=
364
365 IsEqual ( me;
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 ==
372
373 NumberOfMaterials(myclass) returns Integer from Standard;
374 ---Purpose:
375 -- Returns the number of predefined textures.
376 ---Level: Public
377
378 MaterialName(myclass; aRank: Integer from Standard)
379 returns CString from Standard
380 raises OutOfRange from Standard;
381 ---Purpose:
382 -- Returns the name of the predefined material of rank <aRank>
383 -- Trigger: when <aRank> is < 1 or > NumberOfMaterials.
384 ---Level: Public
385
386 MaterialName(me)
387 returns CString from Standard;
388 ---Purpose:
389 -- Returns the name of this material
390 ---Level: Public
391
392 MaterialType(myclass; aRank: Integer from Standard)
393 returns TypeOfMaterial from Graphic3d
394 raises OutOfRange from Standard;
395 ---Purpose:
396 -- Returns the type of the predefined material of rank <aRank>
397 -- Trigger: when <aRank> is < 1 or > NumberOfMaterials.
398 ---Level: Public
399
400 ----------------------------
401 -- Category: Private methods
402 ----------------------------
403
404 Init ( me : out; AName : NameOfMaterial from Graphic3d) is private;
405
406--\f
407
408fields
409
410--
411-- Class : Graphic3d_MaterialAspect
412--
413-- purpose : Declaration of variables specific to the definition
414-- of materials.
415--
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
422--
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
427--
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
432--
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
438--
439-- ( Under GL, the Silicon graphics interface,
440-- we need to determine 3 colours )
441--
442-- References : Getting started with DEC PHIGS, appendix C
443-- Iris Advanced Graphics, unit D
444--
445--
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;
450
451 -- the coefficient of ambient reflection, the colour
452 -- and the activity
453 MyAmbientCoef : ShortReal from Standard;
454 MyAmbientColor : Color from Quantity;
455 MyAmbientActivity : Boolean from Standard;
456
457 -- the coefficient of specular reflection, the colour
458 -- and the activity
459 MySpecularCoef : ShortReal from Standard;
460 MySpecularColor : Color from Quantity;
461 MySpecularActivity : Boolean from Standard;
462
463 -- the coefficient of emissive reflection
464 MyEmissiveCoef : ShortReal from Standard;
465 MyEmissiveColor : Color from Quantity;
466 MyEmissiveActivity : Boolean from Standard;
467
468 -- the coefficient of transparency
469 MyTransparencyCoef : ShortReal from Standard;
470
471 -- the coefficient of luminosity
472 MyShininess : ShortReal from Standard;
473
474
475 -- the coeficient of reflexion for the environment texture
476 MyEnvReflexion : ShortReal from Standard;
477
478 -- the type of material
479 --MyMaterialType : Boolean from Standard;
480 MyMaterialType : TypeOfMaterial from Graphic3d;
481
482 -- the Name of material
483 MyMaterialName : NameOfMaterial from Graphic3d;
484 MyRequestedMaterialName : NameOfMaterial from Graphic3d;
485
486 -- the string name of the material
487 MyStringName : AsciiString from TCollection;
488
489end MaterialAspect;