src/Visual3d/Visual3d_Light.cdl

   1 --
   2 -- File:        Visual3d_Light.cdl
   3 -- Created:     Jeudi 22 Aout 1991
   4 -- Author:      NW,JPB,CAL
   5 --
   6 ---Copyright:   MatraDatavision 1991,1992,1993,1994
   7 --
   8
   9 class Light from Visual3d inherits TShared
  10
  11         ---Version:
  12
  13         ---Purpose: This class defines and updates light sources.
  14         --          There is no limit to the number of light sources defined.
  15         --          Only the number of active sources is limited.
  16         --
  17         --          TypeOfLightSource = TOLS_AMBIENT
  18         --                              TOLS_DIRECTIONAL
  19         --                              TOLS_POSITIONAL
  20         --                              TOLS_SPOT
  21         --
  22         --          Angle is a radian value.
  23         --          Concentration, Attenuation are in the [0,1] interval.
  24         --
  25
  26         ---Keywords: Light, View, Context, Ambient, Directional, Positional,
  27         --           Spot, Angle, Concentration, Attenuation, Color, Shading
  28
  29         ---Warning:
  30         ---References:
  31
  32 uses
  33
  34         Color                   from Quantity,
  35
  36         CLight                  from Graphic3d,
  37         Vector                  from Graphic3d,
  38         Vertex                  from Graphic3d,
  39
  40         TypeOfLightSource       from Visual3d
  41
  42 raises
  43
  44         LightDefinitionError    from Visual3d
  45
  46 is
  47
  48         Create
  49                 returns mutable Light from Visual3d;
  50         ---Level: Public
  51         ---Purpose: Creates a light from default values.
  52         --          Light sources are created in a visualiser
  53         --          and are activated in one of its views.
  54         --
  55         --          Type        = TOLS_AMBIENT
  56         --          Color       = WHITE
  57
  58         Create ( Color          : Color from Quantity )
  59                 returns mutable Light from Visual3d;
  60         ---Level: Public
  61         ---Purpose: Creates an AMBIENT light source.
  62         --          Light sources are created in a visualiser
  63         --          and are activated in one of its views.
  64
  65         Create ( Color          : Color from Quantity;
  66                  Direction      : Vector from Graphic3d;
  67                  Headlight      : Boolean  from  Standard  =  Standard_False )
  68                 returns mutable Light from Visual3d
  69         ---Level: Public
  70         ---Purpose: Creates a DIRECTIONAL light source.
  71         --          Light sources are created in a visualiser
  72         --          and are activated in one of its views.
  73         --  Warning: Raises LightDefinitionError if <Direction> is null.
  74         raises LightDefinitionError;
  75
  76         Create ( Color          : Color from Quantity;
  77                  Position       : Vertex from Graphic3d;
  78                  Fact1, Fact2   : Real from Standard )
  79                 returns mutable Light from Visual3d
  80         ---Level: Public
  81         ---Purpose: Creates a POSITIONAL light source.
  82         --          Light sources are created in a visualiser
  83         --          and are activated in one of its views.
  84         --  Warning: Raises LightDefinitionError
  85         --          if <Fact1> and <Fact2> are null.
  86         --          if <Fact1> is a negative value or greater than 1.0.
  87         --          if <Fact2> is a negative value or greater than 1.0.
  88         raises LightDefinitionError;
  89
  90         Create ( Color          : Color from Quantity;
  91                  Position       : Vertex from Graphic3d;
  92                  Direction      : Vector from Graphic3d;
  93                  Concentration  : Real from Standard;
  94                  Fact1, Fact2   : Real from Standard;
  95                  AngleCone      : Real from Standard )
  96                 returns mutable Light from Visual3d
  97         ---Level: Public
  98         ---Purpose: Creates a SPOT light source.
  99         --          Light sources are created in a visualiser
 100         --          and are activated in one of its views.
 101         --          <Concentration> specifies the intensity distribution of
 102         --          the light.
 103         --          <AngleCone> specifies the angle (radians) of the cone
 104         --          created by the spot.
 105         --          the global attenuation is equal :
 106         --          1 / (Fact1 + Fact2 * (norm(ObjectPosition - LightPosition)))
 107         --  Warning: Raises LightDefinitionError
 108         --          if <Direction> is null.
 109         --          if <Concentration> is a negative value or greater than 1.0.
 110         --          if <Fact1> and <Fact2> are null.
 111         --          if <Fact1> is a negative value or greater than 1.0.
 112         --          if <Fact2> is a negative value or greater than 1.0.
 113         --          if <AngleCone> is a negative value or greater than PI/2.
 114         raises LightDefinitionError;
 115
 116         ---------------------------------------------------
 117         -- Category: Methods to modify the class definition
 118         ---------------------------------------------------
 119
 120         SetAngle ( me           : mutable;
 121                    AngleCone    : Real from Standard )
 122         ---Level: Public
 123         ---Purpose: Modifies the angle (radians) of the cone created by the spot.
 124         --          Works only on TOLS_SPOT lights.
 125         --  Category: Methods to modify the class definition
 126         --  Warning: Raises LightDefinitionError
 127         --          if the type of the light is not TOLS_SPOT.
 128         --          if <AngleCone> is a negative value or greater than PI/2.
 129         raises LightDefinitionError is static;
 130
 131         SetAttenuation1 ( me    : mutable;
 132                           Fact1 : Real from Standard )
 133         ---Level: Public
 134         ---Purpose: Modifies the attenuation factor of the light.
 135         --          Works only on the TOLS_POSITIONAL and TOLS_SPOT lights.
 136         --  Category: Methods to modify the class definition
 137         --  Warning: Raises LightDefinitionError
 138         --          if the type of the light is not TOLS_SPOT or TOLS_POSITIONAL.
 139         --          if <Fact1> is a negative value or greater than 1.0.
 140         raises LightDefinitionError is static;
 141
 142         SetAttenuation2 ( me    : mutable;
 143                           Fact2 : Real from Standard )
 144         ---Level: Public
 145         ---Purpose: Modifies the attenuation factor of the light.
 146         --          Works only on the TOLS_POSITIONAL and TOLS_SPOT lights.
 147         --  Category: Methods to modify the class definition
 148         --  Warning: Raises LightDefinitionError
 149         --          if the type of the light is not TOLS_POSITIONAL or TOLS_SPOT.
 150         --          if <Fact2> is a negative value or greater than 1.0..
 151         raises LightDefinitionError is static;
 152
 153         SetColor ( me           : mutable;
 154                    Color        : Color from Quantity )
 155                 is static;
 156         ---Level: Public
 157         ---Purpose: Modifies the colour of the light.
 158         ---Category: Methods to modify the class definition
 159
 160         SetConcentration ( me                   : mutable;
 161                            Concentration        : Real from Standard )
 162         ---Level: Public
 163         ---Purpose: Modifies the intensity distribution of the light.
 164         --          Works only on the TOLS_SPOT lights.
 165         --  Category: Methods to modify the class definition
 166         --  Warning: Raises LightDefinitionError
 167         --          if the type of the light is not TOLS_SPOT.
 168         --          if <Concentration> is a negative value or greater than 1.0.
 169         raises LightDefinitionError is static;
 170
 171         SetDirection ( me               : mutable;
 172                        Direction        : Vector from Graphic3d )
 173         ---Level: Public
 174         ---Purpose: Modifies the light direction.
 175         --          Works only on the TOLS_DIRECTIONAL and TOLS_SPOT lights.
 176         --          Default z
 177         --  Category: Methods to modify the class definition
 178         --  Warning: Raises LightDefinitionError
 179         --          if the type of the light is not TOLS_DIRECTIONAL
 180         --          or TOLS_SPOT.
 181         --          if <Direction> is null.
 182         raises LightDefinitionError is static;
 183
 184         SetPosition ( me        : mutable;
 185                       Position  : Vertex from Graphic3d )
 186         ---Level: Public
 187         ---Purpose: Modifies the position of the light.
 188         --          Works only on the TOLS_POSITIONAL and TOLS_SPOT lights.
 189         --  Category: Methods to modify the class definition
 190         --  Warning: Raises LightDefinitionError
 191         --          if the type of the light is not TOLS_POSITIONAL or TOLS_SPOT.
 192         raises LightDefinitionError is static;
 193
 194         ----------------------------
 195         -- Category: Inquire methods
 196         ----------------------------
 197
 198         Headlight  ( me )
 199                 returns  Boolean  from  Standard  is  static;
 200         ---Level: Public
 201         ---Purpose:  Returns the headlight  state of the light <me>
 202         ---Category: Inquire methods
 203
 204         Color ( me )
 205                 returns Color from Quantity is static;
 206         ---Level: Public
 207         ---Purpose: Returns the colour of the light <me>.
 208         ---Category: Inquire methods
 209
 210         LightType ( me )
 211                 returns TypeOfLightSource from Visual3d is static;
 212         ---Level: Public
 213         ---Purpose: Returns the light type of <me>.
 214         --
 215         --          TypeOfLightSource = TOLS_AMBIENT
 216         --                              TOLS_DIRECTIONAL
 217         --                              TOLS_POSITIONAL
 218         --                              TOLS_SPOT
 219         --
 220         ---Category: Inquire methods
 221
 222         Values ( me;
 223                  Color          : out Color from Quantity )
 224         ---Level: Public
 225         ---Purpose: Returns the definition of <me> if <me> is
 226         --          a light source of the TOLS_AMBIENT type.
 227         --  Category: Inquire methods
 228         --  Warning: Raises LightDefinitionError
 229         --          if the type of the light is not TOLS_AMBIENT.
 230         raises LightDefinitionError is static;
 231
 232         Values ( me;
 233                  Color          : out Color from Quantity;
 234                  Direction      : out Vector from Graphic3d )
 235         ---Level: Public
 236         ---Purpose: Returns the definition of <me> if <me> is
 237         --          a light source of the TOLS_DIRECTIONAL type.
 238         --  Category: Inquire methods
 239         --  Warning: Raises LightDefinitionError
 240         --          if the type of the light is not TOLS_DIRECTIONAL.
 241         raises LightDefinitionError is static;
 242
 243         Values ( me;
 244                  Color          : out Color from Quantity;
 245                  Position       : out Vertex from Graphic3d;
 246                  Fact1,Fact2    : out Real from Standard )
 247         ---Level: Public
 248         ---Purpose: Returns the definition of <me> if <me> is
 249         --          a light source of the TOLS_POSITIONAL type.
 250         --  Category: Inquire methods
 251         --  Warning: Raises LightDefinitionError
 252         --          if the type of the light is not TOLS_POSITIONAL.
 253         raises LightDefinitionError is static;
 254
 255         Values ( me;
 256                  Color          : out Color from Quantity;
 257                  Position       : out Vertex from Graphic3d;
 258                  Direction      : out Vector from Graphic3d;
 259                  Concentration  : out Real from Standard;
 260                  Fact1,Fact2    : out Real from Standard;
 261                  AngleCone      : out Real from Standard )
 262         ---Level: Public
 263         ---Purpose: Returns the definition of <me> if <me> is
 264         --          a light source of the TOLS_SPOT type.
 265         --  Category: Inquire methods
 266         --  Warning: Raises LightDefinitionError
 267         --          if the type of the light is not TOLS_SPOT.
 268         raises LightDefinitionError is static;
 269
 270         --------------------------
 271         -- Category: Class methods
 272         --------------------------
 273
 274         Limit ( myclass )
 275                 returns Integer from Standard;
 276         ---Level: Internal
 277         ---Purpose: Maximum number of activatable light sources.
 278         ---Category: Class methods
 279
 280         ----------------------------
 281         -- Category: Private methods
 282         ----------------------------
 283
 284         Identification ( me )
 285                 returns Integer from Standard
 286                 is static private;
 287         ---Level: Internal
 288         ---Purpose: Returns the light identification.
 289         ---Category: Private methods
 290
 291         IsValid ( myclass;
 292                   AAngle        : Real from Standard )
 293                 returns Boolean from Standard
 294                 is private;
 295         ---Level: Internal
 296         ---Purpose: Returns True if <AAngle> is a valid
 297         --          spot light spread angle.
 298         ---Category: Private methods
 299
 300 --\f
 301
 302 fields
 303
 304 --
 305 -- Class        :       Visual3d_Light
 306 --
 307 -- Purpose      :       Declaration of variables specific to light sources
 308 --
 309 -- Reminder     :       A light source is defined by:
 310 --                      - its type
 311 --                      - its colour
 312 --                      - the attenuation factor ( positional and spot only)
 313 --                      - its angle ( spot only )
 314 --                      - its concentration ( spot only )
 315 --                      - its direction ( directional and spot only )
 316 --                      - its position ( positional and spot only )
 317 --
 318 --                      It is actived in a context of view.
 319 --
 320
 321         -- the type
 322         MyType          :       TypeOfLightSource from Visual3d;
 323
 324         -- the associated C structure
 325         MyCLight        :       CLight from Graphic3d;
 326
 327 friends
 328
 329         class View from Visual3d
 330
 331 end Light;