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