Add a lumens overlay and make lights environmental

[kwvanderlinde]

Identify the Bug or Feature request

Implements #3817
Addresses #3755

Description of the Change

The new lumens overlay is a visualization of the light strength at each point of a map. The strength of the light is determined by its lumens and - as always - darkness obscures light of equal or lesser lumens. The lumens overlay treats lumens less than zero as darkness and renders dark areas as black. On the other end, lumens of 100 or greater are treated as bright areas, and are rendered as a nearly transparent white. The final special case is lumens equal to zero, which is a representation of daylight and is not included in the lumens overlay. Any other lumens values are drawn as shades of grey, with low levels being nearly black, and with higher levels being closer to white.

The environmental lights are an improvement to the aesthetics of lights. Lights now blend with one another "additively" (technically according to the Screen blend mode) so that they get brighter when they overlap. After blending the lights, the results are blended with the map using a blend operation that brightens the map while preserving details (similar to overlay blend mode and soft lighting). This make lights look more like they illuminate the map rather than sit on top of it.

Both of these features can be toggled in the View menu depending on user preferences and game requirements. The lumens overlay can also have its opacity configured in the Preferences dialog, and the older light and darkness opacities have been removed. Lights no longer have an opacity congiguration since they are conceptually part of the map and not a layer rendered on top.

In order to make the lumens overlay as useful as possible, the lumens values are now attached to individual light ranges rather than to entire light sources. Existing campaigns will have their light sources' lumens values copied to each range. The Campaign Properties dialog's Light tab represents per-range lumens as by appending the lumens after the optional range color. So these are now valid ranges:

r#ff0000+100
r#aa0000-50
r+100

These define, respectively, a saturated red light range at 100 lumens, a desaturated red darkness range at 50 lumens, and a colourless range at 100 lumens.

Some refactoring has also been done, particularly for Light and LightSource. In addition to what was necessary to upgrade existing campaigns, we now ensure (in constructors and readResolve()) that fields are only null if it actually make sense for them to be that way. Together with that, nullability annotations have been added to most methods and fields in those classes. Light is also now immutable so that LightSource and others can rely on the values not changing unexpectedly.

Possible Drawbacks

Since the lumens overlay is rendered as shades of gray, and even black, some of its areas could be confused for soft FoW which is rendered as translucent black.

Lighting syntax is changed, which means existing documentation and guides will be out of date.

Documentation Notes

Lighting syntax has changed to include lumens information for each light range. For example, the following is a torch definition that models the D&D 5e mechanics of bright (lumens=100) and dim (lumens=50), along with a color:

Torch: circle 20#bf973f+100 40#bf973f+50

The lumens information can now be visualized with the lumens overlay, which can be enabled via the Show Lumens Overlay option in the View menu. This is what the above light looks like when equipped to two nearby tokens:

The lights themselves can also be visualized as part of the environment. This can also be enabled via the View menu using the Show Lights option. This is what the same situation looks like with the environmental aspect of lights enabled:

A more complete example of what lights can look like when used throughout a map is this demo:

Release Notes

• A lumens overlay has been added for visualizing lumens levels on a map. It can be toggled in the View menu.
• The light and darkness overlays have been replaced by environmental lighting. Lights now add together and illuminate the map rather than being rendered on top of the map. The new lights can be toggled in the View menu.

---

This change is 

[Phergus]

Reviewed 19 of 19 files at r1, all commit messages.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on @kwvanderlinde)