Improve lightight source light values documentation

[nicopap]

Problem

PointLight has an intensity field, while DirectionalLight has illuminance field.

Solution

either use intensity or illuminance but not both (I personally am in favor of intensity because it's easier to spell)

[mockersf]

It is willingly that they don't have the same name: illuminance of DirectionalLight is in lux, while intensity of PointLight / SpotLight is in lumens

While lumens measure the amount of light emitted by a source, luxes determine the same amount of light, but are projected onto a surface

illuminance is the amount of light a surface will receive, or be illuminated by the directional light, while intensity is the intensity of a spotlight / point light

[nicopap]

Oohh I see. So for a summary:

• lumens is property of light emitter.
• luxes is property of lighted surface.

1lx = 1 lm/m²

Since point light/spot lights fall-off with distance, the amount of lumens is constant, but the luxes can change depending on how distant the lighted surface is.

Since the DirectionalLight lights every surface the same way, the field we set is in lux and express illuminance of the surface being lighted.

The difference between the units lumen and lux is that the lux takes into account the area over which the luminous flux is spread. A flux of 1,000 lumens, concentrated into an area of one square metre, lights up that square metre with an illuminance of 1,000 lux. The same 1,000 lumens, spread out over ten square metres, produces a dimmer illuminance of only 100 lux. Mathematically, 1 lx = 1 lm/m².

Well, it's just a documentation issue then.

[mockersf]

it has been slightly improved very recently by moving a doc comment from the default impl on the field to the field itself in #9724 so that at least both mention their unit now