0024714: Camera integration - difference in behavior of V3d_View::SetSize
[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;
251 ---Level: Public
252 ---Purpose: Returns the ambient colour of the surface.
253 ---Category: Inquire methods
254
255 AmbientColor ( me )
256 returns Color from Quantity
257 is static;
258 ---Level: Public
259 ---Purpose: Returns the ambient colour of the surface.
260 ---Category: Inquire methods
261
262 DiffuseColor ( me )
263 returns Color from Quantity
264 is static;
265 ---Level: Public
266 ---Purpose: Returns the diffuse colour of the surface.
267 ---Category: Inquire methods
268
269 SpecularColor ( me )
270 returns Color from Quantity
271 is static;
272 ---Level: Public
273 ---Purpose: Returns the specular colour of the surface.
274 ---Category: Inquire methods
275
276 EmissiveColor ( me )
277 returns Color from Quantity
278 is static;
279 ---Level: Public
280 ---Purpose: Returns the emissive colour of the surface.
281 ---Category: Inquire methods
282
283 Ambient ( me )
284 returns Real from Standard
285 is static;
286 ---Level: Public
287 ---Purpose: Returns the reflection properties of the surface.
288 ---Category: Inquire methods
289
290 Diffuse ( me )
291 returns Real from Standard
292 is static;
293 ---Level: Public
294 ---Purpose: Returns the reflection properties of the surface.
295 ---Category: Inquire methods
296
297 Specular ( 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 Transparency ( me )
305 returns Real from Standard
306 is static;
307 ---Level: Public
308 ---Purpose: Returns the transparency coefficient of the surface.
309 ---Category: Inquire methods
310
311 Emissive ( me )
312 returns Real from Standard
313 is static;
314 ---Level: Public
315 ---Purpose: Returns the emissive coefficient of the surface.
316 ---Category: Inquire methods
317
318 Shininess ( me )
319 returns Real from Standard
320 is static;
321 ---Level: Public
322 ---Purpose: Returns the luminosity of the surface.
323 ---Category: Inquire methods
324
325 ReflectionMode ( me;
326 AType : TypeOfReflection from Graphic3d )
327 returns Boolean from Standard
328 is static;
329 ---Level: Public
330 ---Purpose: Returns Standard_True if the reflection mode is active,
331 -- Standard_False otherwise.
332 ---Category: Inquire methods
333
334 MaterialType ( me;
335 AType : TypeOfMaterial from Graphic3d )
336 returns Boolean from Standard
337 is static;
338 ---Level: Public
339 ---Purpose: Returns Standard_True if MyMaterialType equal the parameter AType,
340 -- Standard_False otherwise.
341 ---Category: Inquire methods
342
343 EnvReflexion(me)
344 returns ShortReal from Standard;
345
346 Name(me)
347 returns NameOfMaterial from Graphic3d;
348 ---Level: Public
349 ---Purpose: Returns the material name.
350 ---Category: Inquire methods
351
352 IsDifferent ( 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 different.
357 ---Category: Inquire methods
358 ---C++: alias operator !=
359
360 IsEqual ( me;
361 Other : MaterialAspect from Graphic3d )
362 returns Boolean from Standard is static;
363 ---Purpose: Returns Standard_True if the materials <me> and
364 -- <Other> are identical.
365 ---Category: Inquire methods
366 ---C++: alias operator ==
367
368 NumberOfMaterials(myclass) returns Integer from Standard;
369 ---Purpose:
370 -- Returns the number of predefined textures.
371 ---Level: Public
372
373 MaterialName(myclass; aRank: Integer from Standard)
374 returns CString from Standard
375 raises OutOfRange from Standard;
376 ---Purpose:
377 -- Returns the name of the predefined material of rank <aRank>
378 -- Trigger: when <aRank> is < 1 or > NumberOfMaterials.
379 ---Level: Public
380
381 MaterialName(me)
382 returns CString from Standard;
383 ---Purpose:
384 -- Returns the name of this material
385 ---Level: Public
386
387 MaterialType(myclass; aRank: Integer from Standard)
388 returns TypeOfMaterial from Graphic3d
389 raises OutOfRange from Standard;
390 ---Purpose:
391 -- Returns the type of the predefined material of rank <aRank>
392 -- Trigger: when <aRank> is < 1 or > NumberOfMaterials.
393 ---Level: Public
394
395 ----------------------------
396 -- Category: Private methods
397 ----------------------------
398
399 Init ( me : out; AName : NameOfMaterial from Graphic3d) is private;
400
401--\f
402
403fields
404
405--
406-- Class : Graphic3d_MaterialAspect
407--
408-- purpose : Declaration of variables specific to the definition
409-- of materials.
410--
411-- Reminders : A material is defines by:
412-- - A coefficient of transparency
413-- - A coefficient of diffuse reflection
414-- - A coefficient of ambiant reflection
415-- - A coefficient of specular reflection
416-- - A emissive coefficient
417--
418-- Two properties define a material :
419-- - its transparency
420-- - its reflection which is to say its properties of
421-- - absorbtion and diffusion of light
422--
423-- The diffuse reflection is seen as a component
424-- of the colour of the object.
425-- The specular reflection is seen as a component
426-- of the colour of the light source
427--
428-- To determine the three colours of reflection,
429-- four things are required:
430-- - A coefficient of diffuse reflection
431-- - A coefficient of ambiant reflection
432-- - A coefficient of specular reflection
433--
434-- ( Under GL, the Silicon graphics interface,
435-- we need to determine 3 colours )
436--
437-- References : Getting started with DEC PHIGS, appendix C
438-- Iris Advanced Graphics, unit D
439--
440--
441 -- the coefficient of diffuse reflection, the colour, and the activity
442 MyDiffuseCoef : ShortReal from Standard;
443 MyDiffuseColor : Color from Quantity;
444 MyDiffuseActivity : Boolean from Standard;
445
446 -- the coefficient of ambient reflection, the colour
447 -- and the activity
448 MyAmbientCoef : ShortReal from Standard;
449 MyAmbientColor : Color from Quantity;
450 MyAmbientActivity : Boolean from Standard;
451
452 -- the coefficient of specular reflection, the colour
453 -- and the activity
454 MySpecularCoef : ShortReal from Standard;
455 MySpecularColor : Color from Quantity;
456 MySpecularActivity : Boolean from Standard;
457
458 -- the coefficient of emissive reflection
459 MyEmissiveCoef : ShortReal from Standard;
460 MyEmissiveColor : Color from Quantity;
461 MyEmissiveActivity : Boolean from Standard;
462
463 -- the coefficient of transparency
464 MyTransparencyCoef : ShortReal from Standard;
465
466 -- the coefficient of luminosity
467 MyShininess : ShortReal from Standard;
468
469
470 -- the coeficient of reflexion for the environment texture
471 MyEnvReflexion : ShortReal from Standard;
472
473 -- the type of material
474 --MyMaterialType : Boolean from Standard;
475 MyMaterialType : TypeOfMaterial from Graphic3d;
476
477 -- the Name of material
478 MyMaterialName : NameOfMaterial from Graphic3d;
479 MyRequestedMaterialName : NameOfMaterial from Graphic3d;
480
481 -- the string name of the material
482 MyStringName : AsciiString from TCollection;
483
484end MaterialAspect;