LightUnits¶

class LightUnits¶

The photometric convention of the PBR shader, and helpers to follow it.

A light’s intensity (Light::set_intensity) is in the unit of its kind, and its colour is a linear Rec. 709 tint; the shader receives their product:

DirectionalLight illuminance at normal incidence, lux (lm/m^2) PointLight luminous intensity, candela (lm/sr) Spotlight luminous intensity on the axis, candela AmbientLight uniform sky luminance, nits (cd/m^2); lights through the diffuse lobe only

The photometric value of a light is the luminance (0.2126 R + 0.7152 G + 0.0722 B) of its colour times its intensity, so a tint of luminance 1 (as these helpers set) makes it the intensity itself. Luminous power converts to intensity as Frostbite and Filament do: I = phi / 4 pi for a point light, I = phi / pi for a spotlight (so that narrowing the cone does not brighten it).

Point lights and spotlights fall off as the inverse square of the distance, windowed to reach zero at their range (Karis 2013): E = I / max(d^2, 1e-4) * saturate(1 - (d / range)^4)^2 The range is the light’s max_distance, or, if that is infinite, get_auto_range(): the distance where the light drops to shading-light-cutoff lux.

Inheritance diagram

digraph inheritance4434017960 { bgcolor=transparent; rankdir=BT; size="8.0, 12.0"; "DTOOL_SUPER_BASE" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style=""]; "LightUnits" [URL="acron.shading.LightUnits.html#acron.shading.LightUnits",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="",target="_top",tooltip="/**"]; "DTOOL_SUPER_BASE" -> "LightUnits" [arrowsize=0.75,style=""]; }

LightUnits.__init__()¶

static LightUnits.get_auto_range()¶: The range a light of candela gets when it has no max_distance: the distance at which it gives cutoff_lux (by default shading-light-cutoff), sqrt(I / cutoff). The shader computes the same.

static LightUnits.get_illuminance()¶: A directional light’s illuminance in lux (its colour’s luminance times its intensity).

static LightUnits.get_luminance()¶: An ambient light’s luminance in nits.

static LightUnits.get_luminous_intensity()¶

A point light’s luminous intensity in candela.

A spotlight’s luminous intensity on the axis, in candela.

static LightUnits.luminance()¶: The Rec. 709 luminance of a linear colour.

static LightUnits.point_lumens_to_candela()¶: lumens / 4 pi.

static LightUnits.scale_to_luminance()¶: The colour with the chromaticity of color and the given luminance. A black colour counts as white.

static LightUnits.set_illuminance()¶: Makes a directional light give lux lux at normal incidence: its intensity becomes lux and its colour the tint color, scaled to a luminance of 1.

static LightUnits.set_luminance()¶: Makes an ambient light a uniform sky of nits luminance.

static LightUnits.set_luminous_intensity()¶

Makes a point light’s luminous intensity candela: its intensity becomes candela and its colour the tint color, scaled to a luminance of 1.

Makes a spotlight’s luminous intensity on the axis candela, as for a point light.

static LightUnits.set_luminous_power()¶

Sets a point light from its luminous power: I = lumens / 4 pi.

Sets a spotlight from its luminous power: I = lumens / pi, whatever the cone (Frostbite’s convention: the cone shapes the light, it does not focus it).

static LightUnits.spot_cone()¶: The cone the shader applies to a spotlight angle degrees off its axis, for an inner cone of inner_angle degrees (Spotlight’s inner_cone_angle) and an outer one of outer_angle (half its lens’s field of view): saturate(cos * scale + offset)^2, with scale = 1 / max(cos inner - cos outer, 1e-4) and offset = -cos outer * scale (Filament’s form of KHR_lights_punctual’s smooth edge).

static LightUnits.spot_lumens_to_candela()¶: lumens / pi.

static LightUnits.windowed_falloff()¶: The falloff the shader applies to a point light or spotlight at distance metres, for a range of range metres: saturate(1 - (d/r)^4)^2 / max(d^2, 1e-4). Multiply by the intensity in candela for the illuminance in lux.