A frequent question we get is how to use SilverLining’s alluring Atmosphere::EnableHDR() function. Customers are often confused when they enable this, only to be met with a totally white sky. Although high dynamic range is a great thing, you need to understand what EnableHDR() does before trying to use it. It’s almost never what you actually want to do!

SilverLining IS HDR by default!

First, it’s important to understand that even without calling EnableHDR(true), SilverLining is performing all of its simulation of the sky, sunlight, moonlight, and reflections of that light in the clouds in HDR space no matter what internally. Under the hood, we run a rigorous physical simulation of how sunlight and moonlight is affected by the atmosphere and scattered throughout the sky, and these computations are done in physical units of candelas per square meter. Once it’s time to display the sky to the screen and return sunlight and moonlight information to your application, we apply our own tone-mapping algorithm and gamma correction to get these physical results into a displayable range. That’s exactly how HDR works, and SilverLining does that by default, out of the box. Calling EnableHDR(true) does not switch on some more physically realistic model within SilverLining – you get that no matter what, with no extra work.

So what does EnableHDR() do?

All EnableHDR(true) does is remove all tone mapping and gamma correction from what SilverLining displays, and from the lighting values we return to you via methods such as Atmosphere::GetSunOrMoonColor(). This means it is now up to your application to handle tone mapping and gamma correcting what SilverLining renders, and what it returns for lighting values.

With HDR enabled, you must be rendering to an offscreen floating-point buffer or else the colors we write for the sky will be clamped to white. And you must have your own HDR system for remapping what’s in that buffer to displayable results before you transfer the scene to your final display buffer.

This is all much more complicated than it even sounds (which is already pretty complicated.) Chances are the rest of your scene is not rendered in the same lighting units as SilverLining, which means that obtaining consistent results will mean lots of fiddling with SilverLining’s configuration settings to adjust the overall brightness of the sky, clouds, moon, etc. For example, you’ll probably need to tweak sun-luminance-scale, moon-brightness-hdr, sun-transmission-scale-hdr, sun-scattered-scale-hdr, hosek-wilkie-radiance-scale, and probably more before the sky and clouds match the brightness of the rest of your tone-mapped scene. You might also need to scale the lighting values we return to light the rest of your scene the way you want. Getting all of this right can take weeks of tweaking – and in the end, you’ll just end up with a sky that looks exactly like it would have without EnableHDR(true) if you’ve done things properly.

Simpler alternatives to EnableHDR()

We really don’t recommend calling EnableHDR(true) unless you have a special situation that really warrants it, which is almost never. I bet you think the screenshot attached to this article is with HDR mode enabled – it isn’t, even though it’s being displayed within a graphics engine that does work in HDR space.

Remember SilverLining operates within HDR space itself, and is already tuned to do its own tone mapping and gamma correction in just the right way that’s appropriate for the sky. You probably want to composite SilverLining’s sky into your scene at the final stage of your rendering pipeline when you are working in displayable, non-HDR space, if you’re working within some HDR-based deferred rendering engine.

Sometimes, you just want to get our raw lighting values from Atmosphere::GetSunOrMoonColor (and its variants) without tone mapping and gamma correction applied to it. You can do this by surrounding your call to GetSunOrMoonColor() with EnableHDR(true) and EnableHDR(false) to just switch on HDR mode while you’re retrieving the lighting values, while leaving the actual rendering of the sky unaffected.

If your real goal is just to have finer control over how rich the colors are in SilverLining’s sky, Atmosphere::SetGamma() is probably what you really want to be working with.

In summary: don’t use Atmosphere::EnableHDR() unless you really need to (which usually isn’t the case, even in HDR scenes,) and you have several weeks to tweak it to fit into your engine. After those weeks, you’ll probably just be left with a sky that looks like it did without calling EnableHDR(true), since SilverLining is already HDR under the hood no matter what.