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