View source for HDR Skybox Creation

{{LanguageBar}}

[[File:Skybox ldr hdr.jpg|thumb|250px|HDR skyboxes (left) benefit from a wider range of brightness values.]]

Unlike most textures in a game, a [[skybox]] typically represents a collection of very large and very bright objects. This makes the need for [[high dynamic range]] imaging far more pressing.

[[VTF]] textures used for HDR skyboxes store their colors either lightly compressed in 16-bit [[Float|floating point]] (RGBA16161616f) or heavily compressed as 8-bit [[integer]] values (BGRA8888). In either case, they are created by [[Vtex (Source 1)|VTEX]] from uncompressed 32-bit floating point Portable Float Map (.pfm) files.

{{tip|Uncompressed HDR VTFs can be converted back PFMs by [[VTF2TGA|vtf2tga]] (despite the name).<br>Compressed HDR VTFs can be decompressed to EXRs by {{no_vtf|3.1}}.}}
{{todo|Create {{src2}} version of this page's information}}

== Creating PFMs ==
=== Creating Proper PFMs With Photoshop ===
Creating HDR PFMs is very easy, but the way of doing this is not stated anywhere:

#Obtain a common format HDR file, like .hdr or .exr (the most popular one). It could have any bit-depth you like: both 16 and 32 bit should work fine.
#Import it to Photoshop (Adobe srgb 1998 or REC709 should work fine) and make sure that the Photoshop file is set to 32/16 bit-depth (Image --> Mode --> 32 Bits/Channel OR 16 Bits/Channel).
#Go to File --> Save As or Press ctrl + shift + s (or alt + ctrl + s).
#From the dropdown of available formats choose "Portable Bit Map", change the .pbm in the file name to .pfm and click "Save". You now have a proper .pfm file for further use with VTEX.
{{Warning|There's a thing called "Endianess" or "Byte order", for VTEX to properly convert your 16/32 bit HDR files it has to be set to little endian, not big endian. (This doesn't seem to apply to 8 bit non-hdr files, like .png, .jpg, .tga and so on).
{{tip|To set the endianness when converting using ImageMagick, use the {{code|-endian LSB}} parameter.}}}}


{{tip|[[File:Skybox half.jpg|thumb|240px|Half the size, all of the (actually visible) image]] Since the lower halves of skybox sides generally aren't seen, it's often wise to cut away that area. For this trick to work, you must compile the side VTFs with these extra commands:

<source lang=php>
clamps 1
clampt 1
</source>

And add this command to the materials:

<source lang=php>
$basetexturetransform "center 0 0 scale 1 2 rotate 0 translate 0 0"
</source>

See [[#Creating the materials]] for details on how to use the commands.

Additionally, an unseen bottom skybox face can be made a single color and a small resolution, such as 4x4.
}}

=== Skies at different exposures ===

Before creating a HDR skybox we need to know what the sky looks like at different exposures:

[[File:hdr_sky_reference.jpg|700px|center|Photos of the sky at various exposures.]]

As you can see, the captured image changes as the exposure is altered. A single 8-bit image could never be used to create those effects: at 8-bit white is white, and the sun would only stand out if it was literally a different colour from the rest of the sky.

=== Create a Base Skybox ===
First you need to create a basic skybox cube, as you would for an LDR skybox. See [[Skybox (2D)]]. 

With your images ready, arrange them in one large file as seen below. This step is required only if you are using the [[splitskybox]] tool. If you aren't then you are quite free to handle each texture separately.

[[File:hdr_skybox_sides.jpg|center|Recommended skybox layout (labelled)]]

Save this assembled image as a TGA file. If you are prompted, do ''not'' use RLE compression and ''do'' place the origin at the bottom left.

=== Adding HDR Data ===
The following will demonstrate the basic steps for painting a "sun" effect into the different exposures and saving the file as a [[PFM]]. We'll use [https://vgl.ict.usc.edu/HDRShop HDR Shop] for this demonstration.

{{warning|HDR Shop is free for non-commercial use, but commercial usage requires a pricey license. You will have to search the internet for the freeware version.}}

After it is installed, launch the application, and then open the above [[TGA]] you created above. When this window appears leave the default settings and Select '''OK''''.

[[File:hdrshop_curvedialog.png]]

[[File:hdrshop_adjustedsky.jpg|thumb|250px|The skybox after the response curve has been adjusted in HDR Shop. Click to enlarge.]]

HDR Shop works by taking files created by other [[Image Manipulation Programs|image editors]] for different exposures and merging them together at 32-bit floating point. To paint the "sun" into the skybox you must first choose an exposure to edit. The {{key|+}} and {{key|-}} keys are used to adjust the image exposure up and down. The lower right hand corner of the screen indicates the exposure level, {{code|+0.00 stops}} indicates the base exposure level that was imported into HDR Shop. Adjust the exposure level so it reads {{code|-3.00 stops}} Then, go to the menu: {{code|File -> Edit in Image Editor}}. The [[image editor|image-editing program]] you have associated with [[BMP]] format will automatically open up this file as a 24-bit {{file|HDRShopTEMP|bmp}}. Now paint the sun into this file.

When finished save the image and return to HDR Shop.{{clr}}

After clicking '''OK''' in this dialog, the current exposure level will be updated with the image that was just painted with the image-editing program.

[[File:hdrshop_OKdialog.png]]

[[File:hdrshop_saveas.png|right|150px]]

Try adjusting the exposure up and down in HDR Shop with the {{key|+}} and {{key|-}} keys and you'll see that the sun is now integrated into the other exposures. Continue editing the different exposures until the desired result is achieved. It will be a good idea to spend some time emulating the blown-out effects around the sun and the highlights on the clouds as seen in the photographic reference.

When finished go to the {{code|File}} menu and choose {{code|Save as&#8230;}} and Select {{code|Portable Floatmap (.PFM)}} Save this file into your {{path|materialsrc}} content directory (e.g. {{path|steamapps\common\[[Day of Defeat: Source|Day of Defeat Source]]\dod\materialsrc\skybox}}).

{{note|There is a more detailed tutorial [https://web.archive.org/web/20130514222309/http://gl.ict.usc.edu/HDRShop/tutorial/tutorial07.php available on HDR Shop's website].}}{{clr}}

==== {{mono|sdk_sky_exampleup}} ====

[[File:Sdk sky exampleup.jpg|right|thumb|200px|sdk_sky_exampleup]]

Let's do this with {{file|sourcesdk_content\dod\materialsrc\skybox\sdk_sky_exampleup|tga}}. Open it up and adjust the exposure to -3 stops, then edit the image externally. Now paint in a sun.

After returning to HDR Shop and OKing the dialogue, the current exposure level will be updated with the image that you just painted.

Try adjusting the exposure up and down and you'll see that the sun is now integrated into the other exposures as well. Continue editing the different exposures until the desired result is achieved. It will be a good idea to spend some time emulating the blown-out effects around the sun and the highlights on the clouds as seen in the photographic reference.{{clr}}

=== Split the Skybox ===
If you created your skyboxes in a single file as in the above image, you will need to use {{code|splitskybox.exe}} to split it into six. Just drag the PFM onto it.

{{note|[[splitskybox]] Ep1 does not currently function. However, the OB version will work with either version of the engine.}}
{{note|In {{l4d2|4}}, Splitskybox is not a required step. And in fact will not work without lots of retyping of suffixes of multiple files. ''Left 4 Dead 2'''s iteration of [[Vtex (Source 1)|VTEX]] is able to take your "T" image array (both tga into LDR and pfm into HDR) and process it directly into the proper <name_bk>vtf format. In order to do this, create your "T" array as above. Recommended simply for the sake of sanity to get proper orientation for the top (and bottom if needed) images in your custom skybox. Create your txt file as normal and drag it onto Left 4 Dead 2's Vtex. Create materials and use in game as normal. A caveat here is, although the vtf files are compiled properly for LDR, if you are opting out of an HDR skybox and plan to use a LDR skybox only, the supplied LDR material template in the [[Skybox (2D)]] tutorial does not work. You will get the checkerboard pattern.
If you are trying to import an HDR skybox (meaning, if you rendered out a set of skybox textures in your external software, and then used HDRShop to create the hdr data) of a night sky, you will experience extreme banding in the darker areas which resemble dx compression. This banding is actually a result of the way HDRShop handles color information and can be observed directly in HDRShop if you adjust down the exposure and inspect your image.}}

== Creating the Materials ==
At this stage you should have six files:

*{{file|<skyname>_hdr'''ft'''|pfm}}
*{{file|<skyname>_hdr'''lf'''|pfm}}
*{{file|<skyname>_hdr'''bk'''|pfm}}
*{{file|<skyname>_hdr'''rt'''|pfm}}
*{{file|<skyname>_hdr'''up'''|pfm}}
*{{file|<skyname>_hdr'''dn'''|pfm}}

Make sure they are under {{path|your_mod\materialsrc\skybox\}}. You now need to create '''six corresponding TXT files''' (e.g. {{file|<nowiki><skyname>_hdrft</nowiki>|txt}}) alongside them, in order to compile to VTF. Each must contain:

<source lang=php>
pfm 1 // tells vtex to load a a .pfm file instead of a .tga file
pfmscale 1 // brightness multiplier
nonice 1 // prevent seams appearing at low texture detail
skybox 1 // alternative to nonice, if NICE filtering is desired
nocompress 1 // optional; removing halves file size, but causes color banding under close inspection
</source>

Drag these text files onto VTEX and it will compile them (unfortunately [[VTFEdit]] doesn't import PFMs, nor properly handle other formats when HDR). The VTFs will appear in the corresponding materials subfolder (e.g., {{file|your_mod\materials\skybox\}}).

Now you just need to '''create six VMTs named {{file|<nowiki><skyname>_hdr<face></nowiki>|vmt}}'''. These should read:

<source lang=php>
Sky
{
	// if you compiled with nocompress:
	$hdrbasetexture		"skybox/sdk_sky_example_hdrft"

	// if you didn't:
	$hdrcompressedtexture	"skybox/sdk_sky_example_hdrft"

	// LDR fallback
	$basetexture		"skybox/sdk_sky_exampleft"
}
</source>
{{bug|If an {{code|$hdrbasetexture}} or an {{code|$hdrcompressedtexture}} is not specified, the skybox will appear as missing texture with HDR enabled. If you don't have an HDR version of the skybox you can use the LDR version as a {{code|$hdrbasetexture}}.}}

=== Creating LDR Fallbacks ===
{{tip|{{l4d2|since}} LDR fallbacks aren't necessary for games that are normally HDR-only.}}
You must also create standard dynamic range VTFs (LDR fallbacks) for users who do not play in HDR. Compile with these settings:

<source lang=php>
nonice 1
dxt5 1 // or nocompress
</source>
{{clarify|Why is DXT5 necessary? Skyboxes aren't translucent, so shouldn't DXT1 be sufficient? The LDR skyboxes in {{hls}} are BGR888, with no alpha channel. The "hint DXT5" flag may be sufficient, if that even does anything.}}

These are ordinary textures, so you can use [[VTFEdit]] if you prefer. There is no need to create new materials for LDR users; they will load the {{code|_hdr}} ones.

=== Additional creation notes ===
{{modernImportant|To avoid seams appearing at the edges of skies, open the resulting VTFs in {{vtfedit|4}}, then add the Clamp S + Clamp T flags and/or the "no mipmaps" flag. For compressed LDR skyboxes, use the "hint DXT5" flag.}}
{{tip|If an LDR fallback is present, the HDR skybox is compressed, and mipmaps are disabled, then open the compressed HDR skybox in VTFEdit, export as TGA, and reimport the exported images back into VTFEdit with mipmaps disabled. This will remove mipmaps from the file, saving a significant amount of space. {{note|This does not work properly for uncompressed HDR, as VTFLib doesn't properly handle import and export of HDR formats. Additionally, mipmaps should be left in the LDR fallback, so that the skybox materials display correctly in Hammer's texture browser.}} }}

== Usage ==
In {{hammer4|4.1}}, go to ''Main Menu > Map > Map Properties > Skybox Texture Name'' and type the name of your skybox, relative to {{path|materials\skybox\}} and without any of the face suffixes. (e.g., {{code|mysky_hdr}} if the VMTs are {{file|materials\skybox\mysky_hdrXX|vmt}}.)

If there is an underscore before the face names, then these must be included as well (ex: {{code|mysky_hdr_}} if the VMTs are {{file|materials\skybox\mysky_hdr_XX|vmt}}.)

{{note|Skybox selection is based on the VMT names, not the VTF names. Multiple faces of the same skybox can share a VTF, provided they have separate VMTs, and multiple skyboxes can use the same VTFs.}}
{{bug|Skyboxes may fail to load if placed in a subfolder of {{path|materials\skybox\}}; use a prefix if organization is necessary.}}

== See also ==
* [[HDR Lighting Basics]] - How to add basic HDR lighting effects.
* [[HDR Lighting Settings]] - Information on customizing HDR lighting settings.
* [[Sky (shader)]]
* [[Skybox (2D)]]
* [[Sky Writer]] - 3ds Max tool that renders your scene into PFM and compiles to VTF.
* [[Material]]
{{envart}}
[[Category:HDR]][[Category:Material System]]