struct mrpt::viz::TLightParameters

Overview

Lighting model parameters for a viewport.

Contains an array of light sources (up to MAX_LIGHTS) plus global settings (ambient, shadow tuning, gamma correction).

Shadow mapping is only performed for the first directional light in the array (the “primary” directional light).

See also:

TLight, Viewport

#include <mrpt/viz/TLightParameters.h>

struct TLightParameters
{
    // fields

    bool ssao_enabled = false;
    float ssao_radius = 0.5f;
    float ssao_bias = 0.025f;
    float ssao_power = 1.0f;
    float ssao_ambient_floor = 0.3f;
    uint8_t ssao_kernel_size = 32;
    bool fog_enabled = false;
    mrpt::img::TColorf fog_color {0.7f, 0.7f, 0.7f};
    float fog_near = 20.0f;
    float fog_far = 100.0f;
    uint8_t fog_mode = 0;
    float fog_density = 0.015f;
    std::vector<TLight> lights;
    float ambient = 0.2f;
    mrpt::img::TColorf ambientSkyColor {1.0f, 1.0f, 1.0f};
    mrpt::img::TColorf ambientGroundColor {1.0f, 1.0f, 1.0f};
    float shadow_bias = 1e-5f;
    float shadow_bias_cam2frag = 1e-5f;
    float shadow_bias_normal = 1e-4f;
    double eyeDistance2lightShadowExtension = 2.0;
    float minimum_shadow_map_extension_ratio = 0.03f;
    uint8_t shadow_cascades = 4;
    float shadow_cascade_lambda = 0.75f;
    bool gamma_correction = true;

    // construction

    TLightParameters();

    // methods

    mrpt::math::TVector3Df primaryDirectionalDirection() const;
    void writeToStream(mrpt::serialization::CArchive& out) const;
    void readFromStream(mrpt::serialization::CArchive& in);
};

Fields

bool ssao_enabled = false

Enable SSAO (default: false).

float ssao_radius = 0.5f

Hemisphere sampling radius in world units (default: 0.5).

float ssao_bias = 0.025f

Depth comparison bias to avoid self-occlusion (default: 0.025).

float ssao_power = 1.0f

Exponent applied to the AO factor; >1 darkens, <1 lightens (default: 1.0).

float ssao_ambient_floor = 0.3f

Minimum AO ambient multiplier 0,1.

SSAO remaps the AO factor from [0,1] to [ssao_ambient_floor, 1] before multiplying the ambient term. Without a floor, fully-occluded surfaces that face away from all lights become pitch-black (ambient × 0 = 0). A value of 0.3 means even the most occluded surfaces retain 30% of their ambient contribution, keeping them dark but visible.

uint8_t ssao_kernel_size = 32

Number of hemisphere samples: 16, 32, or 64 (default: 32).

bool fog_enabled = false

Enable distance fog (default: disabled).

mrpt::img::TColorf fog_color {0.7f, 0.7f, 0.7f}

Fog blend color (typically matches background).

float fog_near = 20.0f

Distance at which fog begins (linear mode).

float fog_far = 100.0f

Distance at which fog fully obscures geometry (linear mode).

uint8_t fog_mode = 0

Fog mode: 0=linear, 1=exponential, 2=exponential-squared.

float fog_density = 0.015f

Density for exponential fog modes.

std::vector<TLight> lights

The individual light sources (up to MAX_LIGHTS).

float ambient = 0.2f

Global ambient intensity [0,1].

Used as a fallback when hemisphere ambient is not enabled (i.e. sky==ground==white).

mrpt::img::TColorf ambientSkyColor {1.0f, 1.0f, 1.0f}

Hemisphere ambient: sky (up-facing) color.

Default white, which together with ambientGroundColor=white falls back to flat ambient.

mrpt::img::TColorf ambientGroundColor {1.0f, 1.0f, 1.0f}

Hemisphere ambient: ground (down-facing) color.

float shadow_bias = 1e-5f

Shadow tuning parameters (“anti shadow acne”).

Applied to the primary directional light only.

double eyeDistance2lightShadowExtension = 2.0

Multiplier from eye distance to the length size of the squared area in which to evaluate shadow casting by the primary directional light.

Unitless (meter/meter).

float minimum_shadow_map_extension_ratio = 0.03f

Minimum extension (in [0,1] ratio of the light distance) of the shadow map square ortho frustum.

uint8_t shadow_cascades = 4

Number of cascaded shadow map splits (1-4).

Default 4. More cascades concentrate shadow-map resolution near the camera, dramatically improving quality for close-up scenes (1–10 m). 1 = single shadow map (legacy behavior).

float shadow_cascade_lambda = 0.75f

PSSM split scheme blend factor [0,1].

0 = uniform splits, 1 = logarithmic splits. Default 0.75. Higher values (toward 1) push more resolution toward the near camera range; 0.75 is a good balance for robot-scale scenes.

bool gamma_correction = true

If true (default), enables physically-correct gamma correction via the GPU sRGB pipeline.

Methods

mrpt::math::TVector3Df primaryDirectionalDirection() const

Returns the direction of the first directional light, or a fallback if none exists.

Used for shadow mapping.