#
class
#include <Magnum/Trade/LightData.h>

LightData Light data.

### Contents

## 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 Type::`{1.0f, 0.0f, 1.0f}`

and cone angles to `360.0_degf`

:

Trade::LightData data{Trade::LightData::Type::Point, 0xfff3d6_srgbf, 1.0f, 15.0f};

Or, a Type::

Trade::LightData data{Trade::LightData::Type::Spot, 0xf3d6ff_srgbf, 10.0f, {0.01f, 0.5f, 2.0f}, 25.0_degf, 55.0_degf};

And a Type::`{1.0f, 0.0f, 0.0f}`

and range() Constants::

Trade::LightData data{Trade::LightData::Type::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 Type::`{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 Type::*lux* (lm/m^{2}) for Type::

## Public types

- enum class Type: UnsignedByte { Ambient = 1 new in Git master, Directional new in Git master, Infinite = Directional deprecated in Git master, Point, Spot }
- Light type.

## Constructors, destructors, conversion operators

- LightData(Type 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(Type 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(Type 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(Type 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(Type 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(Type 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(Type 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(Type 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 -> Type
- 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.

## Enum documentation

###
enum class Magnum::Trade::LightData::Type: UnsignedByte

Light type.

Enumerators | |
---|---|

Ambient new in Git master |
Ambient light, without any position, direction or attenuation. Meant to be added to ambient color in Phong workflows, has no use in physically based workflows. |

Directional new in Git master |
Light at a position that is infinitely far away, emitted in a direction of negative Z axis. The rotation is inherited from absolute object transformation; scale and position don't affect the light in any way. Because the light is at infinite distance, it's not attenuated in any way. |

Infinite |
Directional light. |

Point |
Point light, emitting light in all directions. The position is inherited from absolute object transformation; scale and rotation don't affect the light in any way. Brightness attenuates depending on the range() value. |

Spot |
Spot light, emitting light in a cone in direction of local negative Z axis. The position and rotation is inherited from absolute object transformation; scale doesn't affect the light in any way. The angle and falloff of the cone is defined using innerConeAngle() and outerConeAngle() and brightness attenuates depending on the range() value. |

## Function documentation

###
Magnum::Trade::LightData:: LightData(Type 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 Type:: |

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 Type::`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 Type::`360.0_degf` otherwise. |

importerState | Importer-specific state |

This is a combined constructor including both attenuation and range parameters. Use LightData(Type, const Color3&, Float, const Vector3&, Rad, Rad, const void*) for light data defined by just attenuation parameters and LightData(Type, const Color3&, Float, Float, Rad, Rad, const void*) for light data defined by a range alone, and LightData(Type, 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(Type, const Color3&, Float, const Vector3&, Float, const void*) and friends instead.

###
Magnum::Trade::LightData:: LightData(Type 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 Type:: |

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(Type, const Color3&, Float, const Vector3&, const void*) for light data defined by just attenuation parameters and LightData(Type, const Color3&, Float, Float, const void*) for light data defined by a range alone, and LightData(Type, const Color3&, Float, const void*) for an implicit inverse square attenuation. See Attenuation calculation for more information.

For a Type::`0.0_degf`

and outerConeAngle() to `90.0_degf`

, and both are `360.0_degf`

otherwise. Use LightData(Type, const Color3&, Float, const Vector3&, Float, Rad, Rad, const void*) in order to specify cone angles as well.

###
Magnum::Trade::LightData:: LightData(Type 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 Type:: |

innerConeAngle | Inner cone angle. Expected to be greater than or equal to `0.0_degf` and less than or equal to `outerConeAngle` for a Type::`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 Type::`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(Type, const Color3&, Float, const Vector3&, const void*) instead.

###
Magnum::Trade::LightData:: LightData(Type 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 Type:: |

importerState | Importer-specific state |

The range() is implicitly set to Constants::

For a Type::`0.0_degf`

and outerConeAngle() to `90.0_degf`

, and both are `360.0_degf`

otherwise. Use LightData(Type, const Color3&, Float, const Vector3&, Rad, Rad, const void*) in order to specify cone angles as well.

###
Magnum::Trade::LightData:: LightData(Type 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 Type::`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 Type::`360.0_degf` otherwise. |

importerState | Importer-specific state |

The attenuation() is implicitly set to `{1.0f, 0.0f, 1.0f}`

for a Type::`{1.0f, 0.0f, 0.0f}`

for an Type::

For lights other than spot it may be more convenient to use LightData(Type, const Color3&, Float, Float, const void*) instead.

###
Magnum::Trade::LightData:: LightData(Type 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 Type::`{1.0f, 0.0f, 0.0f}`

for an Type::

For a Type::`0.0_degf`

and outerConeAngle() to `90.0_degf`

, and both are `360.0_degf`

otherwise. Use LightData(Type, const Color3&, Float, Float, Rad, Rad, const void*) in order to specify cone angles as well.

###
Magnum::Trade::LightData:: LightData(Type 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 Type::`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 Type::`360.0_degf` otherwise. |

importerState | Importer-specific state |

The attenuation() is implicitly set to `{1.0f, 0.0f, 1.0f}`

for a Type::`{1.0f, 0.0f, 0.0f}`

for an Type::

For lights other than spot it may be more convenient to use LightData(Type, const Color3&, Float, const void*) instead.

###
Magnum::Trade::LightData:: LightData(Type 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 Type::`{1.0f, 0.0f, 0.0f}`

for an Type::

For a Type::`0.0_degf`

and outerConeAngle() to `90.0_degf`

, and both are `360.0_degf`

otherwise. Use LightData(Type, 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 Type::*lux* (lm/m^{2}) for Type::

###
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 Type::`{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 Type::

###
Rad Magnum::Trade::LightData:: innerConeAngle() const new in Git master

Inner cone angle.

For a Type::`360.0_degf`

.

###
Rad Magnum::Trade::LightData:: outerConeAngle() const new in Git master

Outer cone angle.

For a Type::`90.0_degf`

. For a Type::`360.0_degf`

.

###
const void* Magnum::Trade::LightData:: importerState() const

Importer-specific state.

See AbstractImporter::

###
Debug& operator<<(Debug& debug,
LightData::Type value)

Debug output operator.