glTF KHR_lights_punctual Extension Explained

This article provides an overview of the KHR_lights_punctual extension for glTF 2.0, detailing the analytical lighting setups it introduces to 3D scenes. While the core glTF specification primarily relies on image-based lighting (IBL) for ambient illumination, this standard extension enables engines to incorporate direct, localized light sources. Below is a breakdown of the three punctual light types defined by the extension—directional, point, and spot lights—and the specific properties that govern their behavior.

The Purpose of KHR_lights_punctual

In 3D graphics, punctual lights are parameterized light sources that emit light from a single point or from an infinitely distant source, rather than from an area or environment map. The KHR_lights_punctual extension provides a standardized way to define these light sources directly inside a glTF file, ensuring consistent lighting behavior across different rendering engines and real-time platforms.

Directional Lights

Directional lights simulate light sources that are infinitely far away, such as the sun. Because the light source has no distinct position in space, all emitted light rays travel parallel to each other along a specified direction vector.

  • Behavior: Illuminates all objects in the scene equally along its path, regardless of their distance from the source.
  • Orientation: Controlled by the node hierarchy transformation within the glTF scene, pointing down the local negative Z-axis by default.
  • Measurement Unit: Intensity is measured in lux (lumens per square meter).

Point Lights

Point lights emit light uniformly in all directions from an exact point in 3D space, similar to an omnidirectional bare lightbulb.

  • Behavior: Light radiates outward spherically. The light intensity naturally attenuates over distance following an inverse-square falloff curve.
  • Range Property: Artists can define an optional range value. When defined, it acts as a cutoff distance where the light’s influence smooths to zero, allowing rendering engines to optimize performance by culling objects outside this radius.
  • Measurement Unit: Intensity is measured in candela (lumens per steradian).

Spot Lights

Spot lights emit light in a defined cone shape from a specific point in space, mimicking real-world flashlights, spotlights, or recessed ceiling fixtures.

  • Behavior: Inherits the spatial position and inverse-square falloff characteristics of a point light, but restricts light emission to a directional cone.
  • Angular Falloff: Defined using two angles:
    • Inner Cone Angle (innerConeAngle): The angle from the center of the cone where the light shines at full intensity.
    • Outer Cone Angle (outerConeAngle): The outer boundary angle where light intensity drops completely to zero. The area between the inner and outer angles produces a smooth penumbra falloff.
  • Measurement Unit: Like point lights, spot light intensity is measured in candela.

Shared Light Properties

All three light types share a set of common attributes defined by the extension:

  • Color: Defined as a linear RGB triplet, determining the hue of the emitted light (defaults to white: [1.0, 1.0, 1.0]).
  • Intensity: A scalar value representing the brightness of the light, interpreted according to the light type (lux for directional, candela for point and spot).
  • Node Attachment: Lights are defined in a top-level array within the glTF document and then referenced by individual scene nodes, allowing them to inherit position, rotation, and animation data from the scene graph.