SteamVR/Environments/Fog Tutorial

= Adding Fog to your Environments =
SteamVR Home introduces a new fog entity called env_gradient_fog, this entity can be utilised to create different types of fog effects. It's a pretty fancy system allowing dense ground-hugging fog with super-subtle changes in colour or density.
To see examples of this entity in action and used effectively, take a look at the main SteamVR Home map or at the Boxing Ring environment.
In this tutorial we will teach you how to author fog textures and add fog to your pre-existing maps as well as provide a detailed breakdown of this entity's workings.
== Env_Gradient_Fog Texture Guidelines ==
The env_gradient_fog entity is primarily controlled by a gradient texture, this texture's dimensions should be equal to powers of two and the texture should also contain an alpha channel. 
Suggested Image formats are PNG, PSD or TGA.
At first glance, authoring gradient fog textures may seem like a complicated and daunting process, but really once you come to understand how they work it's a pretty straightforward affair.
Image:Fog_tut_example1.png|Example env_gradient_fog setup showing opaque fog. Colour is changing depending on distance and height, but since the fog texture is completely opaque, there is no variation in opacity. Note that the skybox texture is unaffected by the fog - for realistic environments using skyboxes, make sure that the skybox and fog match each other visually.
Image:Fog_tut_example2.png|Example env_gradient_fog setup showing varying fog opacity.
== Distance and Height ==
The gradient fog texture acts as a two-dimensional reference for both distance and height. Left to right in the texture controls the fog's appearance over horizontal distances, while up and down controls the appearance over height, allowing you to create fog that has the illusion of variable properties as you ascend or descend through it.
The distance is controlled by specifying a start and end distance of the fog in the env_gradient fog entity, with these given in world units. The player's eyes are always at a distance of zero - distance fog can never be outrun, it being mapped relative to your eye position. Consider the distance fog as a series of cylinders centred on the player's eyes, moving as the player moves. Thus you can never leave the fog as you would be able to in a volumetric solution. Note that it's not possible to specify different values for different horizontal directions - fog can't be dark one way and bright another.
The fog values are clamped at the left hand side of the texture until it reaches the fog's start distance, at which point it blends over to the rightmost side of the texture at the fog's end distance. After this distance, fog values are clamped at that rightmost value. A good way to understand the blending is to visualise your fog texture being stretched from the start value to the end value.
Conversely, height fog is fixed to the world, being mapped to the world rather than the player's eye position. Those cylinders mentioned earlier - they'll move horizontally relative to the player, but not up and down. This means you can climb out or move above a layer of fog, this functionality being particularly useful if you want low hanging fog in specific areas. The start and end heights are again specified in world units in the env_gradient_fog entity, with the bottom of the texture corresponding to the start height and the top of the texture being the end height. These values do not move with the player - If your floor was at -64 units, you could give -64 units for the Fog Start Height here, and floor-hugging fog will stay close to the floor. Anything below or above these distances gets clamped to the appropriate values.
== The Colour of your Fog ==
The colour in the RGB channels of your texture dictate the distribution of fog colour over distance and height. This is an extremely versatile system that allows for subtle or drastic changes in your fog’s colour to match the artistic needs of your level. Changing fog colour over distance can be used as an effective tool to illustrate the depth of your scene and add atmosphere.
Whilst left to right controls colour over distance, up and down controls the colour over height allowing you to create fog that has the illusion of variable properties as you ascend through it.
== Thickness, Opacity or Density of your Fog ==
Currently we have covered how to create a texture that changes the colour of your fog, but you're probably wondering how to change the opacity or “thickness” of your fog. Well, it's as easy as authoring the colour, except fog opacity is stored in the alpha channel of your texture and not in the RGB channels.
Left to right indicates the fog opacity over distance, and up and down the fog opacity over height. Black represents 0 (fully transparent), and white represents 1 (fully opaque), creating a gradient between the two allows you to have gradual changes in the fogs opacity.
== Creating a VTEX == 
Once you have created your texture make sure you save it to your addon's content folder, we suggest saving it to “materials/effects/”, this is not essential but it's a good idea for organisational purposes.
Next you must create a VTEX file to point at your newly created texture, a VTEX being SteamVR Home's texture definition format. This is a requirement for the engine's resource compiler, the tool that takes raw textures and converts them into the engine’s optimised compiled format. A VTEX is a DME format text file that is essentially a description for the resource compiler, telling it how to process the textures according to your settings.
Click here to find an example VTEX file that is setup to be used with a fog texture. Using a text editor, change the filename in m_fileName to correspond with your fog texture.
Save your VTEX in the same location as your gradient fog texture. While running, the SteamVR Home tools will automatically detect this file and compile your texture.
== Placing an env_gradient_fog entity in your map ==
Follow these instructions to setup the fog entity in your map:
* In Hammer select the entity tool located on the left panel or Shift-E.
* In the Tool properties panel change the entity class to env_gradient_fog.
* Left click in your scene to place this entity.
* Now return to the selection tool Shift-S and select your newly created fog entity.
* In the Object Properties panel on the right, assign start and end distances for both your distance and height fog.
* Whilst in the Object Properties panel make sure to also assign your newly authored gradient fog texture.
Changes to this entity will update in real time in Hammer’s 3D viewports.
You should now have everything required to have fog appear in your level, so build your map, then take a look at what your fog looks like in VR and marvel at its foggy splendour.
== Example Materials ==
To help you get to grips with this system, we will be including an example map that comes in two different variants, the first shows how fog can be setup effectively in a scene, the second is designed as a visual companion to the explanation found earlier in this article.
Some basic props are also included as part of the demo scene, you are free to use these in your own levels.
The image below shows a preview of the example content.
Credit and thanks to Adam Foster (CargoCult) for originally explaining this entity's functionality here on the SteamVR Home discussion boards.
Category:SteamVRCategory:SteamVR Home