Magnum::Trade::LightData class

#include <Magnum/Trade/LightData.h>

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::Point light constructed using a range will have attenuation() implicitly set to {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::Spot light constructed from a constant / linear / quadratic attenuation will have range() implicitly set to Constants::inf():

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::Directional light that doesn't attenuate can be constructed without either, causing attenuation() to be {1.0f, 0.0f, 0.0f} and range() Constants::inf(), cancelling out the attenuation equation:

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::inf():

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_lights_punctual extension, which in turn is based on the UE4 implementation. In this case, attenuation() is set to {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::Directional light is defined by attenuation() set to {1.0f, 0.0f, 0.0f} and range() to Constants::inf() — thus without any attenuation:

Units

To follow physically-based principles in lighting calculation, intensity is assumed to be in in candela (lm/sr) for LightType::Point and LightType::Spot, and in lux (lm/m²) for LightType::Directional. Distance is in meters.

Public types

using Type = LightType deprecated in Git master

Light type.

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