SpotLight

Represents a light that emits in a specific direction with a cone-shaped area of influence.

A spotlight combines directional and point light behavior: intensity follows physical inverse-square falloff with distance and diminishes with the angle from the central axis of the cone. This is commonly used to simulate focused light sources such as flashlights or stage spotlights.

When the target parameter is set to nullptr, the light will point toward the world origin. The target must belong to the same Scene as this object. Attaching or referencing a target from a different scene results in undefined behavior and is not supported.

my_scene->Add(vglx::SpotLight::Create({
  .color = 0xFFFFFF,
  .intensity = 25.0f,
  .angle = vglx::math::DegToRad(10.0f),
  .penumbra = 0.3f,
  .target = nullptr,
  .range = 0.0f
}));

INFO

Derives from Light and inherits all public properties and methods.

Construction

Constructors

SpotLight()

Constructs a spotlight.

SpotLight::SpotLight(const Parameters& params);

Parameter	Description
params	Initialization parameters for constructing the light.

Factories preferred

SpotLight::Create() std::unique_ptr<SpotLight>

Creates an instance of SpotLight with default parameters.

static std::unique_ptr<SpotLight> SpotLight::Create();

SpotLight::Create() std::unique_ptr<SpotLight>

Creates an instance of SpotLight.

static std::unique_ptr<SpotLight> SpotLight::Create(const Parameters& params);

Parameter	Description
params	Initialization parameters for constructing the light.

Types

SpotLight::Parameters struct

Parameters for constructing a SpotLight object.

Parameter	Description
color Color	Light color.
intensity float	Light intensity multiplier.
angle float	Cone angle (in radians) for spotlight cutoff.
penumbra float	Softness of the spotlight edge.
target Node*	Node the light is directed toward.
range float	Maximum range of influence. 0 = unbounded.
cast_shadow bool	Enables shadow casting for this light.

Properties

angle float

Cone angle, in radians, of the spotlight.

float angle {};

cast_shadow bool

When true this light casts shadows.

bool cast_shadow {false};

penumbra float

Penumbra controlling the softness of the spotlight’s edge.

float penumbra {};

range float

Maximum range of influence in world units.

Falloff is smoothly windowed to reach zero at this distance. A value of 0 disables the cutoff, leaving pure inverse-square falloff.

float range {0.0f};

shadow Shadow

Shadow configuration used when cast_shadow is enabled.

Shadow shadow {};

target Node*

Node that the light is oriented toward.

Node* target {nullptr};

Functions

Direction() Vector3

Returns the normalized direction vector of the light.

The direction is derived from the light’s position and its target node. If no target is set, the light will point toward the origin.

Vector3 SpotLight::Direction();

GetPower() float

Returns the light's luminous power in lumens.

Uses the convention , where is intensity in candela, so power is independent of the cone angle. This matches the three.js convention rather than the exact solid-angle integral.

float SpotLight::GetPower() const;

GetType() Light::Type virtual

Identifies this light as Light::Type::Spot.

Type vglx::SpotLight::GetType() const override;

OnUpdate() void virtual

Called once per frame to update the light state.

Currently used to generate or dispose of debug geometry when debug mode is enabled.

void SpotLight::OnUpdate(float delta) override;

Parameter	Description
delta	Time in seconds since the last frame.

SetDebugMode() void virtual

Enables or disables debug visualization for this light.

When enabled, the renderer will visualize the spotlight cone and influence region using helper line geometry.

void SpotLight::SetDebugMode(bool is_debug_mode) override;

Parameter	Description
is_debug_mode	true to enable debug mode; false to disable.

SetPower() void

Sets intensity from luminous power in lumens.

void SpotLight::SetPower(float power);

Parameter	Description
power	Luminous power in lumens.