Source/System/State/Base/OSGMultiLightChunk.fcd

   1 <?xml version="1.0"?>
   2
   3 <FieldContainer
   4     name="MultiLightChunk"
   5     parent="ShaderStorageBufferObjStdLayoutChunk"
   6     library="System"
   7     pointerfieldtypes="both"
   8     structure="concrete"
   9     systemcomponent="true"
  10     parentsystemcomponent="true"
  11     decoratable="false"
  12     useLocalIncludes="false"
  13     docGroupBase="GrpSystemState"
  14 >
  15 See \ref PageSystemMultiLightChunk for a description.
  16
  17 This chunk represents a number of lights that are exposed to shader code
  18 in form of a buffer in OpenGL std430 layout format.
  19 A shader, binding a shader storage block to the very same binding point,
  20 is expected to respect the corresponding block layout. The layout is regulated
  21 by the hasXXX fields of the chunk. If one is set to false the corresponding
  22 struct entry is omitted.
  23
  24     struct Light
  25     {
  26         mat4  worldToLightSpaceMatrix;
  27         mat4  lightToWorldSpaceMatrix;
  28         mat4  eyeToLightSpaceMatrix;
  29         mat4  lightToEyeSpaceMatrix;
  30         mat4  lightPerspectiveMatrix;
  31         mat4  invLightPerspectiveMatrix;
  32         vec3  position;
  33         vec3  direction;
  34         vec3  color;
  35         vec3  ambientIntensity;
  36         vec3  diffuseIntensity;
  37         vec3  specularIntensity;
  38         float intensity;
  39         float constantAttenuation;
  40         float linearAttenuation;
  41         float quadraticAttenuation;
  42         float rangeCutOn;
  43         float rangeCutOff;
  44         float rangeNearZone;
  45         float rangeFarZone;
  46         float cosSpotlightAngle;
  47         float spotlightAngle;
  48         float spotExponent;
  49         float innerSuperEllipsesWidth;
  50         float innerSuperEllipsesHeight;
  51         float outerSuperEllipsesWidth;
  52         float outerSuperEllipsesHeight;
  53         float superEllipsesRoundness;
  54         float superEllipsesTwist;
  55         int   type;
  56         bool  enabled;
  57     };
  58
  59     layout (std430) buffer Lights
  60     {
  61         Light light[];
  62     } lights;
  63
  64 The chunk provides a convenient function that allows to adjust the struct layout
  65 for standard OpenGL lights
  66
  67     struct Light
  68     {
  69         vec3  position;
  70         vec3  direction;
  71         vec3  ambientIntensity;
  72         vec3  diffuseIntensity;
  73         vec3  specularIntensity;
  74         float constantAttenuation;
  75         float linearAttenuation;
  76         float quadraticAttenuation;
  77         float cosSpotlightAngle;
  78         float spotExponent;
  79         int   type;
  80         bool  enabled;
  81     };
  82
  83 or for simple range lights:
  84
  85     struct Light
  86     {
  87         vec3  position;
  88         vec3  direction;
  89         vec3  color;
  90         float intensity;
  91         float rangeCutOff;
  92         float cosSpotlightAngle;
  93         int   type;
  94         bool  enabled;
  95     };
  96
  97     <Field
  98         name="hasWorldToLightSpaceMatrix"
  99         type="bool"
 100         cardinality="single"
 101         visibility="external"
 102         access="public"
 103         defaultValue="false"
 104     >
 105         This flag determines if the worldToLightSpaceMatrix attribute is part of
 106         the shader storage block, i.e. if the "mat4  worldToLightSpaceMatrix;"
 107         entry is contained in the shader struct for the Light.
 108     </Field>
 109
 110     <Field
 111         name="hasLightToWorldSpaceMatrix"
 112         type="bool"
 113         cardinality="single"
 114         visibility="external"
 115         access="public"
 116         defaultValue="false"
 117     >
 118         This flag determines if the lightToWorldSpaceMatrix attribute is part of
 119         the shader storage block, i.e. if the "mat4  lightToWorldSpaceMatrix;"
 120         entry is contained in the shader struct for the Light.
 121     </Field>
 122
 123     <Field
 124         name="hasEyeToLightSpaceMatrix"
 125         type="bool"
 126         cardinality="single"
 127         visibility="external"
 128         access="public"
 129         defaultValue="false"
 130     >
 131         This flag determines if the eyeToLightSpaceMatrix attribute is part of
 132         the shader storage block, i.e. if the "mat4  eyeToLightSpaceMatrix;"
 133         entry is contained in the shader struct for the Light.
 134         Attention: If this flag is set the light shader storage block has to
 135         be updated with every redraw operation.
 136     </Field>
 137
 138     <Field
 139         name="hasLightToEyeSpaceMatrix"
 140         type="bool"
 141         cardinality="single"
 142         visibility="external"
 143         access="public"
 144         defaultValue="false"
 145     >
 146         This flag determines if the lightToEyeSpaceMatrix attribute is part of
 147         the shader storage block, i.e. if the "mat4  lightToEyeSpaceMatrix;"
 148         entry is contained in the shader struct for the Light.
 149         Attention: If this flag is set the light shader storage block has to
 150         be updated with every redraw operation.
 151     </Field>
 152
 153     <Field
 154         name="hasLightPerspectiveMatrix"
 155         type="bool"
 156         cardinality="single"
 157         visibility="external"
 158         access="public"
 159         defaultValue="false"
 160     >
 161         This flag determines if the lightPerspectiveMatrix attribute is part of
 162         the shader storage block, i.e. if the "mat4  lightPerspectiveMatrix;"
 163         entry is contained in the shader struct for the Light.
 164     </Field>
 165
 166     <Field
 167         name="hasInvLightPerspectiveMatrix"
 168         type="bool"
 169         cardinality="single"
 170         visibility="external"
 171         access="public"
 172         defaultValue="false"
 173     >
 174         This flag determines if the lightToEyeSpaceMatrix attribute is part of
 175         the shader storage block, i.e. if the "mat4  invLightToEyeSpaceMatrix;"
 176         entry is contained in the shader struct for the Light.
 177     </Field>
 178
 179     <Field
 180         name="hasColor"
 181         type="bool"
 182         cardinality="single"
 183         visibility="external"
 184         access="public"
 185         defaultValue="false"
 186     >
 187         This flag determines if the color attribute is part of the shader storage block, i.e.
 188         if the "vec3  color;" entry is contained in the shader struct for the Light.
 189     </Field>
 190
 191     <Field
 192         name="hasIntensity"
 193         type="bool"
 194         cardinality="single"
 195         visibility="external"
 196         access="public"
 197         defaultValue="false"
 198     >
 199         This flag determines if the intensity attribute is part of the shader storage block, i.e.
 200         if the "float intensity;" entry is contained in the shader struct for the Light.
 201     </Field>
 202
 203     <Field
 204         name="hasSeparateIntensities"
 205         type="bool"
 206         cardinality="single"
 207         visibility="external"
 208         access="public"
 209         defaultValue="true"
 210     >
 211         This flag determines if the color intensity attributes are part of the shader storage block, i.e.
 212         if the "vec3  Ia;", "vec3  Id;" and "vec3 Is;" entries are contained in the shader struct for the Light.
 213     </Field>
 214
 215     <Field
 216         name="hasAttenuation"
 217         type="bool"
 218         cardinality="single"
 219         visibility="external"
 220         access="public"
 221         defaultValue="true"
 222     >
 223         This flag determines if the attenuation attributes are part of the shader storage block, i.e.
 224         if the "float constantAttenuation;", "float linearAttenuation;" and "float quadraticAttenuation;"
 225         entries are contained in the shader struct for the Light.
 226     </Field>
 227
 228     <Field
 229         name="autoCalcRanges"
 230         type="bool"
 231         cardinality="single"
 232         visibility="external"
 233         access="public"
 234         defaultValue="true"
 235     >
 236         If this flag is active and the lights have attenuations, then the cut on and cut off ranges
 237         are automatically calculated. They are, however, not provided automatically to the shader.
 238         For that, you have to set the hasRangeCutOn and hasRangeCutOff flags, respectively.
 239     </Field>
 240
 241     <Field
 242         name="hasRangeCutOn"
 243         type="bool"
 244         cardinality="single"
 245         visibility="external"
 246         access="public"
 247         defaultValue="false"
 248     >
 249         This flag determines if the rangeCutOn attribute is part of the shader storage block, i.e.
 250         if the "float rangeCutOn;" entry is contained in the shader struct for the Light.
 251     </Field>
 252
 253     <Field
 254         name="hasRangeCutOff"
 255         type="bool"
 256         cardinality="single"
 257         visibility="external"
 258         access="public"
 259         defaultValue="false"
 260     >
 261         This flag determines if the hasRangeCutOff attribute is part of the shader storage block, i.e.
 262         if the "float hasRangeCutOff;" entry is contained in the shader struct for the Light.
 263     </Field>
 264
 265     <Field
 266         name="hasRangeNearZone"
 267         type="bool"
 268         cardinality="single"
 269         visibility="external"
 270         access="public"
 271         defaultValue="false"
 272     >
 273         This flag determines if the hasRangeNearZone attribute is part of the shader storage block, i.e.
 274         if the "float hasRangeNearZone;" entry is contained in the shader struct for the Light.
 275     </Field>
 276
 277     <Field
 278         name="hasRangeFarZone"
 279         type="bool"
 280         cardinality="single"
 281         visibility="external"
 282         access="public"
 283         defaultValue="false"
 284     >
 285         This flag determines if the hasRangeFarZone attribute is part of the shader storage block, i.e.
 286         if the "float hasRangeFarZone;" entry is contained in the shader struct for the Light.
 287     </Field>
 288
 289     <Field
 290         name="hasCosSpotlightAngle"
 291         type="bool"
 292         cardinality="single"
 293         visibility="external"
 294         access="public"
 295         defaultValue="true"
 296     >
 297         This flag determines if the cosine of the spot light angle attribute is part of the shader storage block, i.e.
 298         if the "float  cosSpotlightAngle;" entry is contained in the shader struct for the Light. If neither this flag
 299         nor the hasSpotlightAngle flag is true, then this flag is treated as if it has value true.
 300     </Field>
 301
 302     <Field
 303         name="hasSpotlightAngle"
 304         type="bool"
 305         cardinality="single"
 306         visibility="external"
 307         access="public"
 308         defaultValue="false"
 309     >
 310         This flag determines if the spot light angle attribute is part of the shader storage block, i.e.
 311         if the "float  spotlightAngle;" entry is contained in the shader struct for the Light. If neither this flag
 312         nor the hasCosSpotlightAngle flag is true, then the hasCosSpotlightAngle flag is treated as if it has value true.
 313     </Field>
 314
 315     <Field
 316         name="hasSpotExponent"
 317         type="bool"
 318         cardinality="single"
 319         visibility="external"
 320         access="public"
 321         defaultValue="true"
 322     >
 323         This flag determines if the spot expenent attribute is part of the shader storage block, i.e.
 324         if the "float  spotExponent;" entry is contained in the shader struct for the Light.
 325     </Field>
 326
 327     <Field
 328         name="hasCinemaLight"
 329         type="bool"
 330         cardinality="single"
 331         visibility="external"
 332         access="public"
 333         defaultValue="false"
 334     >
 335         This flag determines if the cinema light attributes are part of the shader storage block, i.e.
 336         if the "float innerSuperEllipsesWidth;", ... entries are contained in the shader struct for the Light.
 337         If true this flag overrides the hasRangeCutOn, hasRangeCutOff, hasRangeNearZone and hasRangeFarZone
 338         flags, because cinema lights are described the corresponding attributes.
 339         See: http://http.developer.nvidia.com/GPUGems/gpugems_ch10.html
 340              http://www.yaldex.com/open-gl/ch12lev1sec4.html
 341              https://en.wikipedia.org/wiki/Superellipse
 342     </Field>
 343
 344     <Field
 345         name="position"
 346         type="Pnt3f"
 347         cardinality="multi"
 348         visibility="external"
 349         access="protected"
 350         >
 351         The light's position for point and spotlights in beacon space.
 352     </Field>
 353
 354     <Field
 355         name="direction"
 356         type="Vec3f"
 357         cardinality="multi"
 358         visibility="external"
 359         access="protected"
 360     >
 361     The light's direction for directional and spotlights in beacon space.
 362     </Field>
 363
 364     <Field
 365         name="color"
 366         type="Color3f"
 367         cardinality="multi"
 368         visibility="external"
 369         access="protected"
 370     >
 371     The light's color.
 372     </Field>
 373
 374     <Field
 375         name="intensity"
 376         type="Real32"
 377         cardinality="multi"
 378         visibility="external"
 379         access="protected"
 380     >
 381     The light's intensity.
 382     </Field>
 383
 384     <Field
 385         name="ambientIntensity"
 386         type="Vec3f"
 387         cardinality="multi"
 388         visibility="external"
 389         access="protected"
 390     >
 391     The light's ambient intensity.
 392     </Field>
 393
 394     <Field
 395         name="diffuseIntensity"
 396         type="Vec3f"
 397         cardinality="multi"
 398         visibility="external"
 399         access="protected"
 400     >
 401     The light's diffuse intensity.
 402     </Field>
 403
 404     <Field
 405         name="specularIntensity"
 406         type="Vec3f"
 407         cardinality="multi"
 408         visibility="external"
 409         access="protected"
 410     >
 411     The light's specular intensity.
 412     </Field>
 413
 414     <Field
 415         name="attenuation"
 416         type="Vec3f"
 417         cardinality="multi"
 418         visibility="external"
 419         access="protected"
 420     >
 421     The light's attenuation consiting of the constant, linear and quadratic attenuation parts.
 422     </Field>
 423
 424     <Field
 425         name="spotlightAngle"
 426         type="Real32"
 427         cardinality="multi"
 428         visibility="external"
 429         access="protected"
 430     >
 431     The spot angle in degree.
 432     </Field>
 433
 434     <Field
 435         name="spotExponent"
 436         type="Real32"
 437         cardinality="multi"
 438         visibility="external"
 439         access="protected"
 440     >
 441     The spot angle in degree.
 442     </Field>
 443
 444     <Field
 445         name="innerSuperEllipsesWidth"
 446         type="Real32"
 447         cardinality="multi"
 448         visibility="external"
 449         access="protected"
 450     >
 451     The cinema light is described among others by an inner ellipses. This is
 452     the width of this ellipse.
 453     See: http://http.developer.nvidia.com/GPUGems/gpugems_ch10.html
 454          http://www.yaldex.com/open-gl/ch12lev1sec4.html
 455          https://en.wikipedia.org/wiki/Superellipse
 456     </Field>
 457
 458     <Field
 459         name="innerSuperEllipsesHeight"
 460         type="Real32"
 461         cardinality="multi"
 462         visibility="external"
 463         access="protected"
 464     >
 465     The cinema light is described among others by an inner ellipses. This is
 466     the height of this ellipse.
 467     See: http://http.developer.nvidia.com/GPUGems/gpugems_ch10.html
 468          http://www.yaldex.com/open-gl/ch12lev1sec4.html
 469          https://en.wikipedia.org/wiki/Superellipse
 470     </Field>
 471
 472     <Field
 473         name="outerSuperEllipsesWidth"
 474         type="Real32"
 475         cardinality="multi"
 476         visibility="external"
 477         access="protected"
 478     >
 479     The cinema light is described among others by an outer ellipses. This is
 480     the width of this ellipse.
 481     See: http://http.developer.nvidia.com/GPUGems/gpugems_ch10.html
 482          http://www.yaldex.com/open-gl/ch12lev1sec4.html
 483          https://en.wikipedia.org/wiki/Superellipse
 484     </Field>
 485
 486     <Field
 487         name="outerSuperEllipsesHeight"
 488         type="Real32"
 489         cardinality="multi"
 490         visibility="external"
 491         access="protected"
 492     >
 493     The cinema light is described among others by an outer ellipses. This is
 494     the height of this ellipse.
 495     See: http://http.developer.nvidia.com/GPUGems/gpugems_ch10.html
 496          http://www.yaldex.com/open-gl/ch12lev1sec4.html
 497          https://en.wikipedia.org/wiki/Superellipse
 498     </Field>
 499
 500     <Field
 501         name="superEllipsesRoundness"
 502         type="Real32"
 503         cardinality="multi"
 504         visibility="external"
 505         access="protected"
 506     >
 507     The cinema light is described among others by a roundness parameter.
 508     See: http://http.developer.nvidia.com/GPUGems/gpugems_ch10.html
 509          http://www.yaldex.com/open-gl/ch12lev1sec4.html
 510          https://en.wikipedia.org/wiki/Superellipse
 511     </Field>
 512
 513     <Field
 514         name="superEllipsesTwist"
 515         type="Real32"
 516         cardinality="multi"
 517         visibility="external"
 518         access="protected"
 519     >
 520     The twist angle in degree by which the superellipses is rotatet in the xy-plane.
 521     </Field>
 522
 523     <Field
 524         name="rangeCutOn"
 525         type="Real32"
 526         cardinality="multi"
 527         visibility="external"
 528         access="protected"
 529     >
 530     The cinema light is described among others by a rangeCutOn parameter.
 531     In the interval rangeCutOn to rangeCutOff the lighted fragments are
 532     fully lit.
 533     See: http://http.developer.nvidia.com/GPUGems/gpugems_ch10.html
 534          http://www.yaldex.com/open-gl/ch12lev1sec4.html
 535          https://en.wikipedia.org/wiki/Superellipse
 536     </Field>
 537
 538     <Field
 539         name="rangeCutOff"
 540         type="Real32"
 541         cardinality="multi"
 542         visibility="external"
 543         access="protected"
 544     >
 545     The cinema light is described among others by a rangeCutOff parameter.
 546     In the interval rangeCutOn to rangeCutOff the lighted fragments are
 547     fully lit.
 548     See: http://http.developer.nvidia.com/GPUGems/gpugems_ch10.html
 549          http://www.yaldex.com/open-gl/ch12lev1sec4.html
 550          https://en.wikipedia.org/wiki/Superellipse
 551     </Field>
 552
 553     <Field
 554         name="rangeNearZone"
 555         type="Real32"
 556         cardinality="multi"
 557         visibility="external"
 558         access="protected"
 559     >
 560     The cinema light is described among others by a rangeNearZone parameter.
 561     In the interval rangeCutOn-rangeNearZone to rangeCutOn the lighted fragments are
 562     partly lit.
 563     See: http://http.developer.nvidia.com/GPUGems/gpugems_ch10.html
 564          http://www.yaldex.com/open-gl/ch12lev1sec4.html
 565          https://en.wikipedia.org/wiki/Superellipse
 566     </Field>
 567
 568     <Field
 569         name="rangeFarZone"
 570         type="Real32"
 571         cardinality="multi"
 572         visibility="external"
 573         access="protected"
 574     >
 575     In the interval rangeCutOff to rangeCutOff+rangeFarZone the lighted fragments are
 576     partly lit.
 577     </Field>
 578
 579     <Field
 580         name="type"
 581         type="UInt8"
 582         cardinality="multi"
 583         visibility="external"
 584         access="protected"
 585     >
 586     Stores the light's type. This can be any of the set {POINT_LIGHT, DIRECTIONAL_LIGHT, SPOT_LIGHT, CINEMA_LIGHT}.
 587     </Field>
 588
 589     <Field
 590         name="enabled"
 591         type="bool"
 592         cardinality="multi"
 593         visibility="external"
 594         access="protected"
 595     >
 596     The on/off state of the light.
 597     </Field>
 598
 599     <Field
 600         name="beacon"
 601         type="Node"
 602         category="weakpointer"
 603         cardinality="multi"
 604         visibility="external"
 605         access="protected"
 606     >
 607     The light's beacon determining its position or direction.
 608     </Field>
 609
 610     <Field
 611         name="beaconMatrix"
 612         type="Matrix"
 613         cardinality="multi"
 614         visibility="internal"
 615         access="protected"
 616     >
 617         The beacon matrices used for the last render pass.
 618     </Field>
 619
 620     <Field
 621         name="eyeSpace"
 622         type="bool"
 623         cardinality="single"
 624         visibility="external"
 625         access="public"
 626         defaultValue="false"
 627     >
 628     The lights position and direction are transformed to eye space before loading into the shader.
 629     On default they are provided in world space.
 630     </Field>
 631
 632     <Field
 633         name="lastCamNear"
 634         type="Real32"
 635         cardinality="single"
 636         visibility="internal"
 637         access="protected"
 638         defaultValue="0.f"
 639     >
 640         The camera last near value.
 641     </Field>
 642
 643     <Field
 644         name="lastCamFar"
 645         type="Real32"
 646         cardinality="single"
 647         visibility="internal"
 648         access="protected"
 649         defaultValue="0.f"
 650     >
 651         The camera last far value.
 652     </Field>
 653
 654     <Field
 655         name="lastCamToWorld"
 656         type="Matrix"
 657         cardinality="single"
 658         visibility="internal"
 659         access="protected"
 660     >
 661         The camera last to world matrix.
 662     </Field>
 663
 664     <Field
 665      name="LightBlockName"
 666      type="std::string"
 667      cardinality="single"
 668      visibility="external"
 669      access="public"
 670      defaultValue='"Lights"'
 671      >
 672         The shader storage buffer block name for the light buffer.
 673     </Field>
 674
 675     <Field
 676      name="LightVariableName"
 677      type="std::string"
 678      cardinality="single"
 679      visibility="external"
 680      access="public"
 681      defaultValue='"lights"'
 682      >
 683         The shader variable name for the light buffer.
 684     </Field>
 685
 686 </FieldContainer>