src/Visual3d/Visual3d_Light.cdl

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