HDR Lighting Basics

Overview

The Source Engine supports two independent sets of light maps in one compiled map: one for HDR (High Dynamic Range) and one for LDR (Low Dynamic Range). With LDR lighting, mappers have to supplement dark areas with additional point and texture lights to help make these areas visible. HDR light maps alleviate this with auto-exposure calculations, removing the need for "fake" lights. Having both LDR and HDR lighting can more than double the size of the light map data in the final BSP file.

Note:Mods made using the pre-August 2006 SDK code or pre- Source 2006 don't support HDR. Some skyboxes on Source 2006, such as Half-Life 2, does not support HDR until Source 2007 or later.

LDR has been dropped with the release of Left 4 Dead engine branch and above. While Portal 2 does unofficially support LDR lighting, the game defaults to HDR.

Some games or mods, such as Black Mesa, only support HDR lighting.

Basic compiling of a HDR map

The simplest thing to get HDR working immediately is to recompile your existing map with the latest VRAD.

If you're using the compiler built-in to Hammer, compiling your map with HDR is very simple:

1. Open the .VMF file in the Hammer editor.
2. Choose Run Map from the File Menu.
3. Set BSP, VIS, and RAD options to Normal.
4. Under the RAD section, check the HDR check box.
5. Click OK to start the map compiling.

Note:You will notice in the compile log window that VRAD will run twice when HDR is enabled. This is correct. VRAD needs to build separate lighting for LDR and HDR modes, except on games running Left 4 Dead engine branch or later.

VRAD command-line arguments for HDR

If you don't use the Hammer built-in compiler, you can use the following commands with VRAD for use on the command-line: -both, -ldr, -hdr, and -final. Now a .BSP file can contain two sets of lightmaps for both LDR and HDR. To compile both add the command -both to VRAD. If you want to compile just the LDR version add -ldr, and for HDR only add -hdr. Another new command that was added for this release is -final which is used to increase the quality of skylight and indirect light by spending more CPU time firing rays.

Warning:the use of -final can dramatically increase the compile time for VRAD, and so it is mainly intended for final map compiles. The biggest quality impact of this option is the reduction of lighting artifacts that are commonly found in indoor spaces lit primarily from light_environment.

Running HDR in the Source Engine

Set the engine HDR mode in the shortcut. Click to enlarge.

The Source engine can be run in both HDR and LDR modes. If a map has been compiled with HDR lightmaps, and HDR is enabled (set to "Full") in the Video Settings for the game, HDR will be automatically enabled when the map is loaded. Due to the separate lightmaps that are created for HDR and LDR, cubemaps must be built for both HDR and LDR modes.

HDR can also be enabled or disabled via the command-line when launching the game with the following command:

+mat_hdr_level 0/1/2

• Set to 0 for LDR, 1 for LDR with bloom on HDR maps and 2 for full HDR and bloom on HDR maps. The lightmaps for the level will be reloaded if the value is changed while a map is loaded.

Note:In multiplayer games and/or if the background map (e.g. background01) is loaded, the map will not be reloaded.

Note: Black Mesa has a third option, called "HDR Expanded", which set the mat_hdr_level value to "3". The "HDR Expanded" option can be only selected through the old game UI (VGUI, using -oldgameui launch option) or said console command.

Note:In Source 2006 games, after run the command above, you may also need to set mat_hdr_enable to 1 to enable HDR, and 0 to disable HDR.

Launching the game with HDR enabled

To force HDR and blooming to be enabled when running the game, add +mat_hdr_level 2 via one of the following methods:

• In the Hammer Run Map dialog, adding the command to the Additional game parameters.
• Right-clicking the game in the Steam Library and choosing Properties..., and entering the command into the Launch Options.
• Creating a shortcut to the game on your desktop, then adding the command in the Windows Properties dialog.
• If you use a .BAT batch file to run the engine, add the command to your batch file.

Note:This will not enable HDR rendering on video cards that cannot support HDR features.

Building HDR and LDR cubemaps

To build cubemaps for both LDR + HDR, see Cubemaps - Building cubemaps section.

You must do this every time you compile the map or the cubemaps will not appear correctly.

Selecting an HDR skybox

Select a HDR skybox using Map Properties. Click to enlarge.

Another thing you can do easily to improve the quality of the HDR effects is to select an HDR skybox.

To select an HDR skybox in Hammer:

1. Select Map properties from the Map menu.
2. Enter the name of an HDR skybox in the Skybox Texture Name field (e.g. sky_example_hdr). See List of skies for a list of available skyboxes.
3. Recompile the map with the new skybox.

The sample map sdk_hdr_example.vmf in the SDK samples includes the entities for this demonstration.

Note:The file is located in the 'dod' map folder under sourcesdk_content.

For a description on how to create new HDR skyboxes, see HDR Skybox Creation.

See also

• HDR Lighting Settings - for more information on how to customize HDR settings.
• HDR Skybox Creation
• env_tonemap_controller
• Advanced HDR