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         --  Keywords: Material, FillArea, Shininess, Ambient, Color, Diffuse,
  33         --           Specular, Transparency, Emissive, ReflectionMode,
  34         --           BackFace, FrontFace, Reflection, Absorbtion
  35
  36         ---Warning:
  37         ---References:
  38
  39 uses
  40
  41         Color                   from Quantity,
  42
  43         NameOfMaterial          from Graphic3d,
  44         TypeOfReflection        from Graphic3d,
  45         TypeOfMaterial          from Graphic3d,
  46         AsciiString             from TCollection
  47
  48 raises
  49
  50         MaterialDefinitionError from Graphic3d,
  51         OutOfRange from Standard
  52
  53 is
  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   ---C++: return const&
 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;
 259   ---C++: return const&
 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;
 267   ---C++: return const&
 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;
 275   ---C++: return const&
 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;
 283   ---C++: return const&
 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
 408 fields
 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
 489 end MaterialAspect;