Add haziness property to fog

[rreusser]

Update: I've updated the following description to match the current state of the PR.

This PR adds a "haziness" property to fog. The requirements of this PR are to:

• improve the visual appearance of a (not-physically-based) atmosphere
• not interfere with fog as currently implemented
• add minimal cost to the rendering

A big additional advantage is that haze is more nicely visible than fog without looking like pea soup. It accomplishes this by simply adding the haze color and then tone-mapping the result to avoid blown out colors. It's too bad this isn't even minimally based on a proper atmospheric model so that it would match time of day with the skybox. It might be possible without excessive computational or implementation cost, but I don't know if that's reasonable to add at this time.

It adds three properties to fog:

• strength: [0, 1]: how strong is the fog? Fog layers on top of haze, and as this goes to zero, you're left with just haze.
• haze-color: Color of the haze
• haze-energy: A multiplicative factor for the fog color. Overlaps with the lightness of haze-color but allows you to change the amount of haze without changing its color.

When the haze color is black, haze disappears. When haze-energy is zero, it exactly reduces to fog.

When fog strength decreases, it multiplies fog opacity by smoothstep to a power. This has the effect of pushing it away from the camera but looks much, much less like it's literally changing the near/far limits, which was very obvious and distracting. Raising the fog opacity to a power has the effect of delaying the onset of fog relative to haze:

Haze is computed with the following algorithm:

1. convert the color from srgb -> linear rgb
2. add haze opacity * haze color
3. tone-map the result (see: https://www.desmos.com/calculator/vb9fax8pc2 )
4. convert the result from linear rgb -> srgb
5. mix the tone-mapped result with the original input color so that unaffected regions are not tone-mapped (bright spots like glaciers otherwise get slightly darkened by tone-mapping)
6. compute fog by mixing colors with the previous algorithm

haze-energy=0, fog-strength=1:

haze-energy=1, fog-strength=0:

[rreusser]

Also:

• I considered a redundant property (haze-magnitude?) that would scale the color contribution instead of making the color lighter or darker to accomplish that. Color feels somewhat overloaded currently since it has two effects: the color and the magnitude of the haze contribution.
• I also considered haze-start or some other property so that fog and haze simply scale separately. The downside is just having to compute two fog opacities rather than using one for both. I don't have strong feelings. haziness instead just adjust the balance between fog and haze. It feels a bit too clever, I think.
• Tests won't pass, but I think that's from the fog-implementation branch and not this branch.

[karimnaaji]

Tests won't pass, but I think that's from the fog-implementation branch and not this branch.

Could you rebase the branch? CI has been unreliable in triggering in the branch, so this would be a good sanity check if we get it to pass in this branch. I fixed most of the issues locally but there might be a few left.

[rreusser]

I don't like this factor of 1.5 (totally arbitrary, chosen to put colors in a reasonable magnitude range), and would not be against just making this the mentioned additional style property (haze-magnitude, haze-amount, haze-intensity or something) so that you don't have to change the haze color in order to change the amount.

This is different than haziness, which is more of a selector knob for whether fog acts like pure fog or includes haze. I wouldn't actually mind removing that and just adding haze-start for that control instead (haze end is presumably the same as fog end). The reason I didn't is the discrepancy between fog-range (both limits) and haze-start (only one) which seemed a bit inconsistent.

[rreusser]

Oh, there's alpha as a way to specify the amount of haze, I suppose. The only downside there is that you're still clipped to kind of an arbitrary range since alpha = [0, 1]. What is "normal" haze? alpha = 0.2??

[karimnaaji]

Thanks for the rebase, I think we get more meaningful errors now.

lint

/home/circleci/mapbox-gl-js/debug/fog.html
  40:26  error  A space is required after ','  comma-spacing
  40:30  error  A space is required after ','  comma-spacing

✖ 2 problems (2 errors, 0 warnings)
  2 errors and 0 warnings potentially fixable with the `--fix` option.

flow

Error ------------------------------------------------------------------------------------- src/render/painter.js:853:50

Cannot call `program.setFogUniformValues` with `uniforms` bound to `fogUniformsValues` because array type [1] has an
unknown number of elements, so is incompatible with tuple type [2] in property `u_haze_color_linear`.

 src/render/painter.js:853:50
 853|             program.setFogUniformValues(context, uniforms);
                                                       ^^^^^^^^

References:
 /tmp/flow/flowlib_211a3b78/core.js:251:89
 251|     map<U>(callbackfn: (value: T, index: number, array: Array<T>) => U, thisArg?: any): Array<U>;
                                                                                              ^^^^^^^^ [1]
 src/render/uniform_binding.js:66:33
  66| class Uniform3f extends Uniform<[number, number, number]> {
                                      ^^^^^^^^^^^^^^^^^^^^^^^^ [2]

[karimnaaji]

The constant evaluation of the second exp2 call seems to get optimized away. I'm not confident that's always the case, but I hope most shader compiler would make this static evaluation.

[karimnaaji]

(e.g. exp2(-k) constant evaluated as 1/256 -> 0.00390625)

[rreusser]

Ah, thanks for checking. I considered hard-coding this, but was hoping even the most basic, rudimentary, minimal constant folding would catch this. Also wasn't 100% certain 8.0 is the right constant and thought I'd wait before hard-coding it. Glad to though if it's a more sure thing.

[karimnaaji]

nit: Remove extraneous comment (can be left in PR description for archiving).

Suggested change

	// Cubic smooth min (works well)
	//const float k = 0.8;
	//vec3 h = max(k - abs(color - 1.0), vec3(0)) / k;
	//return max(vec3(0), min(color, vec3(1)) - h * h * h * k * (1.0 / 6.0));
	// Cubic smooth min (works well)
	//const float k = 0.8;
	//vec3 h = max(k - abs(color - 1.0), vec3(0)) / k;
	//return max(vec3(0), min(color, vec3(1)) - h * h * h * k * (1.0 / 6.0));

[rreusser]

The functions are almost visually indistinguishable. Thought I might double-check if we have a good way to micro-benchmark before definitely removing.

[karimnaaji]

For this code path, we may investigate adding a variant for haze disabled (by adding an extra define FOG_HAZE) that would make this code path the simplified expression return mix(color, u_fog_color, fog_opacity(pos)); when haze == 0.

This may seem extraneous, but since we're adding these new shader statements on every possible rendered fragment, there may be a non-negligible cost to these new function calls (sqrt and pow may be expensive function evaluations).

[rreusser]

You read my mind. I definitely support this since it's so easy and probably does result in some small but measurable performance boost.

[karimnaaji]

On linux (ubuntu firefox), I noticed possible NaNs evaluations.

I can look into this issue as I have a clear repro of that (it does not seem to happen in the fog-implementation branch, only visible from this one).

The linux driver might be more finicky and less grateful about handling undefined behavior so we should double-check to make sure we don't have division by zero or possible infinite function evaluation.

[rreusser]

@karimnaaji does the bug increase with haziness? If so, that's a strong argument that the culprit is the large power of a number in [0, 1] (which I semi-suspect is a bad idea in the first place)

[rreusser]

In case they're needed later: I tried a couple smooth min functions for tonemapping—which here is just a smooth min between y=x and y=1. They worked fine. I went with exponential, though I have no particular reason to prefer it. I haven't benchmarked, but I suspect the difference is probably a bit below what we can meaningfully micro-benchmark.

const float k = 8.0;
return -log2(exp2(-k * color) + exp2(-k)) * (1.0 / k); 

const float k = 0.8;
vec3 h = max(k - abs(color - 1.0), vec3(0)) / k;
return max(vec3(0), min(color, vec3(1)) - h * h * h * k * (1.0 / 6.0));

[rreusser]

@karimnaaji I've updated the PR with what I think are greatly improved parameters and have fixed the culling and cpu opacity calculations to match.

Haze and fog are now mostly independent:

• Adjust fog.strength to change how strong the pure fog is
• Adjust fog.haze-energy to adjust the multiplicative factor of haze

I'd even consider changing haze-energy to haze-strength so that the two are closely aligned since they're the basic two knobs to turn. I'd describe it more, but if you give it a try, it'll hopefully make sense right away.

[karimnaaji]

Could you rearrange this code to be wrapping the shader expresion (length(pos) - u_fog_range.x) / (u_fog_range.y - u_fog_range.x), otherwise it's evaluated twice: for t and within the call to fog_opacity (maybe in a function or by passing t to fog_opacity directly?).

[rreusser]

The short answer is not cleanly, no, I don't think so. The statement is duplicated so that the operations are not repeated. I instead added a note in 62f0ac2 pointing out that fog_opacity(vec3) is only rarely called (e.g. heatmap) while all other fog opacity computations go through fog_opacity(float) via fog_apply.

[rreusser]

I can't promise a property name or a constant won't change before production, but other than that, I don't anticipate further structural changes, so I don't have anything else to add to this PR.