View source for Advanced HDR

Advanced HDR setup.

== [[:Category:Valve Games|Valve games]] with HDR support ==
So far the following titles support HDR:
* [[Day of Defeat: Source]]
* [[Counter-Strike: Source]]
* [[Half-Life 2: Episode One]]
* [[Half-Life 2: Episode Two]]
* [[Half-Life 2: Lost Coast]]
* [[Team Fortress 2]]
* [[Portal]]
* [[Left 4 Dead]]
* Mods based on [[Source SDK Base]] and [[Source SDK Base - Orangebox]]

{{note|Half-Life 2 does not support HDR, so if you want your custom map to have it, then compile and run it under one of the above listed games.}}

== What is HDR? ==
As showcased in Lost Coast - a simple tech demo, HDR is a new lighting method that allows a monitor to go over its ideal brightness. It allows tweaking the player's virtual eyes, changing exposure levels as they go along. With the aid of an [[env_tonemap_controller]], exposure levels can be adjusted, I.E; players stepping into a dark non-lit area after receiving a large exposure from a much brighter area.

=== Lost Coast example ===
[[Image:D2 lostcoast0000.jpg|thumb|250px|Before entering the dark area.]]
[[Image:D2 lostcoast0001.jpg|thumb|250px|Now that the player is in the darkened hall, the outside area appears overly bright due to eye adjustment]]
[[Image:D2 lostcoast0002.jpg|thumb|250px|Wow that's quite bright isn't it?]]
[[Image:D2 lostcoast0003.jpg|thumb|250px|Well that's better! Now the player's virtual eyes have adjusted.]]

The Tonemap Controller's job is to help in oscillations between overly bright areas, and extremely dark areas, and the in-between.

{note| With the Release of the Orange Box Engine, Valve has improved Tonemap oscillations for smaller and less immediate sources of exposure. Small sources like sprites, spotlights, and even self-illuminating materials.

Now when the player walks into the tunnel he triggers a [[trigger_multiple]] Brush based entity. Its outputs are as follows:

* <code>SetAutoExposureMax: 6.0</code>
* <code>SetAutoExposureMin: 2.0</code>
* <code>SetAutoBloomScale: &nbsp;1.6</code>

All these settings cause the tonemap controller to change different parameters and cause the suns brightness and mainly the HDR lighting to be more brighter than before, and keeps the settings at that rate for a while till the player leaves the brush based trigger area.

The effects are applied in this way with the use of the <code>OnStartTouch</code> and <code>OnEndTouch</code> outputs.

When the player enters the trigger area the [[env_tonemap_controller]] is triggered with the new settings by the output <code>OnStartTouch</code> and then set back to the previous settings 
with the <code>OnEndTouch</code> output.

In the third screenshot the player walks out of the tunnel and then sees the large amount of light being casted. At this time the players "virtual eyes" are being adjusted, and then finally in the final screenshot return back to normal.

The tonemap controller is mainly commanded by a [[trigger_multiple]] and given its default settings by the [[logic_auto]] entity. When the map begins, outputs can be sent to the tonemap controller and at that time the tonemap controller changes the lighting parameters. Also throughout the Lost Coast map there are other many riggers the player walks through that cause the ideal brightness to change and rearrange all the exposure settings around. However if a map does not contain a <code>env_tonemap_controller</code> then really the HDR effect will be a bit random. Continuously dimming the screen and brightening it up at random times or even when the player steps into a area thats just a tad brighter than the past one. In other words the HDR settings end up acting funny towards the map and HDR is set to its default settings of <code>0</code> on all exposure and bloom parameters.

On a main note though, each map requires different settings even if using the same [[skybox]] material. Of course changing the settings and keeping them the same is okay. Mainly though the only reason you might need to change the settings are to really attain or create a certain effect towards the area the player is in currently. Even if it is just for a few seconds. Depending on the amount of over bright effects in your map or even having HDR seem very low still require parameters, so in turn the best idea is really to tinker around with your map till you get just the right setting that fits and once again if the settings don't seem to fit in a certain area you can always create [[trigger_multiple]] volumes around the areas the player needs to travel into that will change the settings and correct any mistakes, or get the lighting just right. The tonemap controller, however does not add more brightness to the area though, those controls still need to be set to the current light entity. In fact it just gives lighting the HDR effect or really a brighter glow but as mentioned does ''not'' add more brightness or lighting towards the area. Each light entity has its own HDR brightness parameter which must be set as the overall HDR brightness.

Here is a little example of the effects of a tone map controller in a different environment:
[[Image:Ep1 citadel 000001.jpg|thumb|left|250px|With the tonemap controller settings on.]]
[[Image:Ep1 citadel 000002.jpg|thumb|left|250px|With the settings off.]]
<br clear="left" />

Valve implemented the <code>env_tonemap_controller</code> to better control the ideal bright effect of the sun so it's not overly bright, i.e. unrealistic. Also, they gave the sun an effect with the existing fog in the map, by changing a few settings and giving a bit of a more-than-normal brightness to appear layered by the fog.

One other thing is mainly the inside corridors of the Citadel which also use the [[env_tonemap_controller]] to adjust the sensitivity levels seen in a screenshot below located in Material lighting.

If you are a bit foggy on the [[I/O]] system, the following section covers this process through a step by step guide.

== Creating a HDR map ==
[[Image:Hammer-env_tonemap_controll.gif|thumb|250px| All required entities are placed near the player. Note, [[env_fog_controller]] isn't needed.]]
[[Image:Logic auto.gif|thumb|250px|A <code>logic_auto</code> to control the [[env_tonemap_controller]].]]
Now as to creating a map with HDR in it isn't too hard yet requires some entity's as well as customization towards the [[env_tonemap_controller]] as noted above with the [[Logic_auto]] entity.
*First things first. Place a [[env_tonemap_controller]] in the map. The entity needs to be in the map but as location does not effect anything. Mainly some mappers as well as some of valves maps tend to have the [[env_tonemap_controller]] at the start of the level near the player included with the main entities for better organization purposes and clarity.
*Now at this point the best thing to do is give the the [[env_tonemap_controller]] a name. It does not really matter what the name is but for the example map shown above it was named <code>tonemap_controller</code>
*Next step is creating a [[Logic_auto]]. Once placed open up its properties and go straight to the "Outputs" tab.
*One of the main things needed for the [[env_tonemap_controller]] to work is outputs sent towards it then received as inputs by the <code>tonemap_controller</code>. Take a look at the picture to the right with the [[logic_auto]] selected in it. These are the settings that were set as outputs, however for your map you might require different settings.
*With the [[Logic_auto]] placed in you map and now with the outputs tab open create a new output.

The first output is going to send a message to the <code>tonemap_controller</code> about the max auto exposure and here is how it goes. The second output is going to send a message concerning the minimum auto exposure.

<table>
<tr>
 <th>My Output</th>
 <th>Target Entity</th>
 <th>Target Input</th>
 <th>Parameter</th>
 <th>Delay</th>
 <th>Only Once</th>
</tr>
<tr>
 <td>OnMapSpawn &nbsp;</td>
 <td>tonemap_controller &nbsp;</td>
 <td>SetAutoExposureMax &nbsp;</td>
 <td>4 &nbsp;</td>
 <td>0.00 &nbsp;</td>
 <td>No &nbsp;</td>
</tr>
</table>
{{note|In the above example, remember to replace the entity names with your own.}}

Although not the simplest thing, HDR isn't a very hard technique to work with however it deals a large amount of time to the compile process. In fact, <code>vrad</code> must run twice. Once for LDR and the second time for HDR. The first thing in creating an HDR map is of course a HDR sky texture. See this page [[Sky_List|here]] for a list of sky's in HDR as well as ideal parameters for them.

Once you've picked one out open the map menu located on the top right of Hammer then go to map properties. On the properties panel set the skybox material name to the skybox texture name field. Now click apply.

Mainly aside from that HDR maps aren't to hard to create. In fact you need to fill in the HDR brightness field on a light entity's properties panel and that's about it. Mainly because HDR is brighter and adds a glow to the world its wise to set the brightness value a bit lower the the regular LDR brightness. In example if LDR brightness is <code>100</code> then HDR should be set to <code>50</code>. Mainly it really depends though on the lights source and effect that your going for. Mainly though never have both the same. You have to take in to consideration players who don't have HDR capable video cards. Therefore the brightness must be equivalent to that in-game of LDR. Once you're done setting up the values click apply on the properties panel and well that's it. Now go ahead and run your map. Make sure you have HDR checked in the compile window checked. If you're compiling under the advanced window then simply set the compile type to HDR <code>-final</code> or HDR <code>-final -fast</code>. If you're just testing then fast might be a good idea to run and create a quick build version of lighting in your map. When you complete your map fully then go for the final compile but note, it takes quite a long time depending on the size, number of lights, and complexity of lightmaps used in your map!

{{note|Don't forget to adjust the <code>HDR Brightness</code> property of your <code>light_environment</code> entity.}}

== Running a HDR map ==
Now that the compile process has finished in-game open up your console and type in <code>buildcubemaps</code>. In order to really get the lighting right you need to build cubemaps twice. Once for LDR and once for HDR. Once building the cubemaps have finished type in <code>mat_hdr_enable 0</code> in the console to disable HDR and return to LDR. Now simply <code>buildcubemaps</code> again. You're done! The game will return automatically to HDR so theres no more console commands needed. Through the console however you can change around the exposure levels of the <code>env_tonemap_controller</code>. 

The following console commands are currently available for HDR:
<table>
<tr>
 <th>Prefix</th>
 <th>Location</th>
</tr>
<tr>
 <td><code>mat_autoexposure_min</code></td>
 <td>Minimum exposure settings.</td>
</tr>
<tr>
 <td><code>mat_autoexposure_max</code></td>
 <td>Maximum exposure settings.</td>
</tr>
<tr>
 <td><code>mat_hdr_enable 0/1</code></td>
 <td>0 Turns off HDR, 1 turns HDR on.</td>
</tr>
<tr>
 <td><code>mat_hdr_level 0/1/2</code></td>
 <td>Adjusts the overall bright effect of HDR.</td>
</tr>
<tr>
 <td><code>mat_hdr_manual_tonemap_rate 0.000000</code></td>
 <td>Sets the tonemap rate.</td>
</tr>
<tr>
 <td><code>mat_hdr_tonemapscale 0.00000</code></td>
 <td>Sets the tonemap scale</td>
</tr>
<tr>
 <td><code>mat_hdr_tonemapscaleMax 1-16</code></td>
 <td>Sets the maximum scale</td>
</tr>
<tr>
 <td><code>mat_hdr_overbrightrange</code></td>
 <td>Sets an override parameter on HDR level for added adjustment.</td>
</tr>
</table>

{{note|When building cubemaps in HDR it might take a bit longer due to the HDR lightmaps. Thats completely normal so just be patient!}}

== HDR effects ==
Seen not only in stock but also custom maps, some of these effects are used to trick the player or add even more detail toward an area.

=== Sprite glow ===
[[Env_sprite]] used to be for just lights. Really its main purpose was to add a small glow effect toward lights. Also, the old method of getting a glow was using env_glow which didn't work all too well. Now a new method to show light beaming in toward an area is using [[env_sprite]] like this:

Here it is used to multiply the amount of light preceding out of the lamp without having the main [[Light]] entity have a high brightness setting. 

Another use for <code>env_sprite</code> is to simulate the effects of strong amounts of light pouring from the outside into a closed in area. This tends to work great with dark areas as well.

[[Image:C17 city day 020000.jpg|thumb|left|250px|An env_sprite from far away.]]
[[Image:C17 city day 020002.jpg|thumb|left|250px|Used as the light pouring in from outside.]]
[[Image:C17 city day 020001.jpg|thumb|left|250px|The env_sprite up close.]]
<br clear="left" />

=== Texture lighting ===
[[Image:Ep1 citadel 010003.jpg|thumb|right|250px|Inside the Citadel.]]
Another one of a HDR tech is mainly using textures that support or give off ambient light. This was used quite a lot in Episode 1 within the Citadel and acts as Bright white lighting within the citadel. Mainly the texture is <code>lights/white004_nochop</code>. Mainly this texture can give off a nice glow with the aid of HDR. Heres how it looks:

=== Prop lighting ===
A few props now have been able to reflect and even cast light for an added effect. Many of them now don't even require lights any more to give off an effect that they are on. Now using HDR the light models glow and require less light entities. Meaning neither <code>env_sprite</code> nor regular [[light]] entities are required anymore.

== See also ==
* [[HDR Lighting Basics]] - general information on the subject.
* [[Sky List]] - a list of HDR-supported skyboxes, with their optimal settings.

[[Category:Level Design]]