class
#include <Magnum/Trade/LightData.h>
LightData Light data.
Usage
The class exposes light parameters in a way that makes sense as a whole, allowing to reduce branching in application code — e.g., a light defined by just its range has the quadratic attenuation factor set to one, with constant and linear attenuation being zero, or spot cone angles are the full circle everything except spotlights.
Populating an instance
You can choose a constructor overload that matches the subset of input parameters and let the class set the rest implicitly. For example, a LightType::{1.0f, 0.0f, 1.0f}
and cone angles to 360.0_degf
:
Trade::LightData data{Trade::LightType::Point, 0xfff3d6_srgbf, 1.0f, 15.0f};
Or, a LightType::
Trade::LightData data{Trade::LightType::Spot, 0xf3d6ff_srgbf, 10.0f, {0.01f, 0.5f, 2.0f}, 25.0_degf, 55.0_degf};
And a LightType::{1.0f, 0.0f, 0.0f}
and range() Constants::
Trade::LightData data{Trade::LightType::Directional, 0xd6fff3_srgbf, 0.25f};
Attenuation calculation
To support all common lighting calculations, the class exposes parameters in a combined equation containing both constant / linear / quadratic attenuation / / and a range parameter over a distance :
In most cases you'll have the light data using either one or the other approach. The classic constant/linear/quadratic equation allows for most control, but because the attenuated intensity never really reaches zero, it makes light culling optimizations hard to perform. In this case the range() is set to Constants::
The range-based equation approaches zero when and provides a good tradeoff for performance while staying mostly physically-based. This is modelled after the glTF KHR_{1.0f, 0.0f, 1.0f}
, the constant factor is present in order to prevent the function from exploding to infinity when .
If as well, the equation reduces down to a simple inverse square:
As a special case, a LightType::{1.0f, 0.0f, 0.0f}
and range() to Constants::
Units
To follow physically-based principles in lighting calculation, intensity is assumed to be in in candela (lm/sr) for LightType::
Public types
Constructors, destructors, conversion operators
- LightData(LightType type, const Color3& color, Float intensity, const Vector3& attenuation, Float range, Rad innerConeAngle, Rad outerConeAngle, const void* importerState = nullptr) explicit noexcept new in Git master
- Constructor.
- LightData(LightType type, const Color3& color, Float intensity, const Vector3& attenuation, Float range, const void* importerState = nullptr) explicit noexcept new in Git master
- Construct with implicit cone angles.
- LightData(LightType type, const Color3& color, Float intensity, const Vector3& attenuation, Rad innerConeAngle, Rad outerConeAngle, const void* importerState = nullptr) explicit noexcept new in Git master
- Construct attenuation-based light data.
- LightData(LightType type, const Color3& color, Float intensity, const Vector3& attenuation, const void* importerState = nullptr) explicit noexcept new in Git master
- Construct attenuation-based light data with implicit cone angles.
- LightData(LightType type, const Color3& color, Float intensity, Float range, Rad innerConeAngle, Rad outerConeAngle, const void* importerState = nullptr) explicit noexcept new in Git master
- Construct range-based light data.
- LightData(LightType type, const Color3& color, Float intensity, Float range, const void* importerState = nullptr) explicit noexcept new in Git master
- Construct range-based light data with implicit cone angles.
- LightData(LightType type, const Color3& color, Float intensity, Rad innerConeAngle, Rad outerConeAngle, const void* importerState = nullptr) explicit noexcept new in Git master
- Construct light data with implicit attenuation.
- LightData(LightType type, const Color3& color, Float intensity, const void* importerState = nullptr) explicit noexcept
- Construct light data with implicit attenuation and cone angles.
- LightData(const LightData&) deleted
- Copying is not allowed.
- LightData(LightData&&) defaulted noexcept
- Move constructor.
Public functions
- auto operator=(const LightData&) -> LightData& deleted
- Copying is not allowed.
- auto operator=(LightData&&) -> LightData& defaulted noexcept
- Move assignment.
- auto type() const -> LightType
- Light type.
- auto color() const -> Color3
- Light color.
- auto intensity() const -> Float
- Light intensity.
- auto attenuation() const -> Vector3 new in Git master
- Constant, linear and quadratic light attenuation.
- auto range() const -> Float new in Git master
- Light range.
- auto innerConeAngle() const -> Rad new in Git master
- Inner cone angle.
- auto outerConeAngle() const -> Rad new in Git master
- Outer cone angle.
- auto importerState() const -> const void*
- Importer-specific state.
Typedef documentation
Function documentation
Magnum:: Trade:: LightData:: LightData(LightType type,
const Color3& color,
Float intensity,
const Vector3& attenuation,
Float range,
Rad innerConeAngle,
Rad outerConeAngle,
const void* importerState = nullptr) explicit noexcept new in Git master
Constructor.
Parameters | |
---|---|
type | Light type |
color | Light color |
intensity | Light intensity |
attenuation | Constant, linear and quadratic light attenuation factor. Expected to be {1.0f, 0.0f, 0.0f} for an LightType:: |
range | Light range, after which the intensity is considered to be zero. Expected to be Constants:: |
innerConeAngle | Inner cone angle. Expected to be greater than or equal to 0.0_degf and less than or equal to outerConeAngle for a LightType::360.0_degf otherwise. |
outerConeAngle | Outer cone angle. Expected to be greater than or equal to innerConeAngle and less than or equal to 360.0_degf for a LightType::360.0_degf otherwise. |
importerState | Importer-specific state |
This is a combined constructor including both attenuation and range parameters. Use LightData(LightType, const Color3&, Float, const Vector3&, Rad, Rad, const void*) for light data defined by just attenuation parameters and LightData(LightType, const Color3&, Float, Float, Rad, Rad, const void*) for light data defined by a range alone, and LightData(LightType, const Color3&, Float, Rad, Rad, const void*) for an implicit inverse square attenuation. See Attenuation calculation for more information.
For lights other than spot it may be more convenient to use LightData(LightType, const Color3&, Float, const Vector3&, Float, const void*) and friends instead.
Magnum:: Trade:: LightData:: LightData(LightType type,
const Color3& color,
Float intensity,
const Vector3& attenuation,
Float range,
const void* importerState = nullptr) explicit noexcept new in Git master
Construct with implicit cone angles.
Parameters | |
---|---|
type | Light type |
color | Light color |
intensity | Light intensity |
attenuation | Constant, linear and quadratic light attenuation factor. Expected to be {1.0f, 0.0f, 0.0f} for an LightType:: |
range | Light range, after which the intensity is considered to be zero. Expected to be Constants:: |
importerState | Importer-specific state |
This is a combined constructor including both attenuation and range parameters. Use LightData(LightType, const Color3&, Float, const Vector3&, const void*) for light data defined by just attenuation parameters and LightData(LightType, const Color3&, Float, Float, const void*) for light data defined by a range alone, and LightData(LightType, const Color3&, Float, const void*) for an implicit inverse square attenuation. See Attenuation calculation for more information.
For a LightType::0.0_degf
and outerConeAngle() to 90.0_degf
, and both are 360.0_degf
otherwise. Use LightData(LightType, const Color3&, Float, const Vector3&, Float, Rad, Rad, const void*) in order to specify cone angles as well.
Magnum:: Trade:: LightData:: LightData(LightType type,
const Color3& color,
Float intensity,
const Vector3& attenuation,
Rad innerConeAngle,
Rad outerConeAngle,
const void* importerState = nullptr) explicit noexcept new in Git master
Construct attenuation-based light data.
Parameters | |
---|---|
type | Light type |
color | Light color |
intensity | Light intensity |
attenuation | Constant, linear and quadratic light attenuation factor. Expected to be {1.0f, 0.0f, 0.0f} for an LightType:: |
innerConeAngle | Inner cone angle. Expected to be greater than or equal to 0.0_degf and less than or equal to outerConeAngle for a LightType::360.0_degf otherwise. |
outerConeAngle | Inner cone angle. Expected to be greater than or equal to innerConeAngle and less than or equal to 360.0_degf for a LightType::360.0_degf otherwise. |
importerState | Importer-specific state |
The range() is implicitly set to Constants::
For lights other than spot it may be more convenient to use LightData(LightType, const Color3&, Float, const Vector3&, const void*) instead.
Magnum:: Trade:: LightData:: LightData(LightType type,
const Color3& color,
Float intensity,
const Vector3& attenuation,
const void* importerState = nullptr) explicit noexcept new in Git master
Construct attenuation-based light data with implicit cone angles.
Parameters | |
---|---|
type | Light type |
color | Light color |
intensity | Light intensity |
attenuation | Constant, linear and quadratic light attenuation factor. Expected to be {1.0f, 0.0f, 0.0f} for an LightType:: |
importerState | Importer-specific state |
The range() is implicitly set to Constants::
For a LightType::0.0_degf
and outerConeAngle() to 90.0_degf
, and both are 360.0_degf
otherwise. Use LightData(LightType, const Color3&, Float, const Vector3&, Rad, Rad, const void*) in order to specify cone angles as well.
Magnum:: Trade:: LightData:: LightData(LightType type,
const Color3& color,
Float intensity,
Float range,
Rad innerConeAngle,
Rad outerConeAngle,
const void* importerState = nullptr) explicit noexcept new in Git master
Construct range-based light data.
Parameters | |
---|---|
type | Light type |
color | Light color |
intensity | Light intensity |
range | Light range, after which the intensity is considered to be zero. Expected to be Constants:: |
innerConeAngle | Inner cone angle. Expected to be greater than or equal to 0.0_degf and less than or equal to outerConeAngle for a LightType::360.0_degf otherwise. |
outerConeAngle | Outer cone angle. Expected to be greater than or equal to innerConeAngle and less than or equal to 360.0_degf for a LightType::360.0_degf otherwise. |
importerState | Importer-specific state |
The attenuation() is implicitly set to {1.0f, 0.0f, 1.0f}
for a LightType::{1.0f, 0.0f, 0.0f}
for an LightType::
For lights other than spot it may be more convenient to use LightData(LightType, const Color3&, Float, Float, const void*) instead.
Magnum:: Trade:: LightData:: LightData(LightType type,
const Color3& color,
Float intensity,
Float range,
const void* importerState = nullptr) explicit noexcept new in Git master
Construct range-based light data with implicit cone angles.
Parameters | |
---|---|
type | Light type |
color | Light color |
intensity | Light intensity |
range | Light range, after which the intensity is considered to be zero. Expected to be Constants:: |
importerState | Importer-specific state |
The attenuation() is implicitly set to {1.0f, 0.0f, 1.0f}
for a LightType::{1.0f, 0.0f, 0.0f}
for an LightType::
For a LightType::0.0_degf
and outerConeAngle() to 90.0_degf
, and both are 360.0_degf
otherwise. Use LightData(LightType, const Color3&, Float, Float, Rad, Rad, const void*) in order to specify cone angles as well.
Magnum:: Trade:: LightData:: LightData(LightType type,
const Color3& color,
Float intensity,
Rad innerConeAngle,
Rad outerConeAngle,
const void* importerState = nullptr) explicit noexcept new in Git master
Construct light data with implicit attenuation.
Parameters | |
---|---|
type | Light type |
color | Light color |
intensity | Light intensity |
innerConeAngle | Inner cone angle. Expected to be greater than or equal to 0.0_degf and less than or equal to outerConeAngle for a LightType::360.0_degf otherwise. |
outerConeAngle | Outer cone angle. Expected to be greater than or equal to innerConeAngle and less than or equal to 360.0_degf for a LightType::360.0_degf otherwise. |
importerState | Importer-specific state |
The attenuation() is implicitly set to {1.0f, 0.0f, 1.0f}
for a LightType::{1.0f, 0.0f, 0.0f}
for an LightType::
For lights other than spot it may be more convenient to use LightData(LightType, const Color3&, Float, const void*) instead.
Magnum:: Trade:: LightData:: LightData(LightType type,
const Color3& color,
Float intensity,
const void* importerState = nullptr) explicit noexcept
Construct light data with implicit attenuation and cone angles.
Parameters | |
---|---|
type | Light type |
color | Light color |
intensity | Light intensity |
importerState | Importer-specific state |
The attenuation() is implicitly set to {1.0f, 0.0f, 1.0f}
for a LightType::{1.0f, 0.0f, 0.0f}
for an LightType::
For a LightType::0.0_degf
and outerConeAngle() to 90.0_degf
, and both are 360.0_degf
otherwise. Use LightData(LightType, const Color3&, Float, Rad, Rad, const void*) in order to specify cone angles as well.
Float Magnum:: Trade:: LightData:: intensity() const
Light intensity.
Defined in candela (lm/sr) for LightType::
Vector3 Magnum:: Trade:: LightData:: attenuation() const new in Git master
Constant, linear and quadratic light attenuation.
Values of , and in the attenuation equation. Always {1.0f, 0.0f, 0.0f}
for an LightType::{1.0f, 0.0f, 1.0f}
for range-based attenuation — and if range() is Constants::
Float Magnum:: Trade:: LightData:: range() const new in Git master
Light range.
Value of in the attenuation equation. If set to Constants::
- if attenuation() is
{1.0f, 0.0f, 1.0f}
, the attenuation equation is ; - if attenuation() is
{1.0f, 0.0f, 0.0f}
, the attenuation equation is .
The latter is always the case for a LightType::
Rad Magnum:: Trade:: LightData:: innerConeAngle() const new in Git master
Inner cone angle.
For a LightType::360.0_degf
.
Rad Magnum:: Trade:: LightData:: outerConeAngle() const new in Git master
Outer cone angle.
For a LightType::90.0_degf
. For a LightType::360.0_degf
.
const void* Magnum:: Trade:: LightData:: importerState() const
Importer-specific state.
See AbstractImporter::