



Documentation
Hx Volumetric Lighting is the easiest way to get high quality volumetric lighting in your Unity scene. Follow this guide to get started, and let us know if you have any questions or comments.
Requirements
Take these requirements under consideration when using Hx Volumetric Lighting:
- Requires Unity 5.1.4 or above
- Needs the linear color space enabled
- Requires DirectX 9/OpenGL3 or above
- Requires shader model 3 or above
- For desktop and console use - mobile is not yet supported
- Supports transparency
- Is not friendly with MSAA in forward rendering mode (yet)
Setup
- Add the HxVolumetricCamera.cs script to each camera you want to render volumetric lighting on.
- Add the HxVolumetricLight.cs script to each light in your scene that you want to be volumetric.
- Adjust the settings in your camera inspector to fit the style of your project.
- (Optional) To vary the air density using particle emitters, put the HxVolumetricParticleSystem.cs script on your emitters and follow the instructions for particle density.
- (Optional) If your scene has objects with transparency, you may need to slightly modify your shaders so they properly render. You can find these instructions in the transparency section.
If you are not using HDR rendering on your camera, the volumetric effect will automatically be converted to LDR. If you are using HDR, It is recommended that you use tone mapping. Otherwise, you can enable the Map To LDR setting in the Advanced Settings section, and it will handle tone mapping for you. However, it is recommended that you use an external tone mapper.
Settings
In your camera's inspector window, you can adjust several parameters to control the volumetric effect.
Light Scattering Settings
These set the default values for the lights. You can overwrite them on a per-light basis by selecting custom settings in the inspector window for each light, although it is recommended to use this sparingly, as conflicting extinction values can cause some artifacts for overlapping lights.
Density
A higher density value will result in more visible light scattering, but will also make your scene more foggy.
Mie Scattering
This value describes the angular light scattering amount. A low value will scatter the light evenly in all directions, while a high value will scatter the light more in the direction of the light. At high values, being in the direct path of the light direction and looking directly at the light source will give you a blown out, staring-into-the-sun effect.
Ambient Lighting Strength
You can use this value to mix the scene's ambient lighting into the volumetric pass. This uses Unity's ambient lighting settings, found in the options under Window->Lighting. This supports all three ambient sources — skybox, gradient, and color — when using deferred rendering mode. Skybox is not currently supported in forward rendering mode.

This is the same scene with ambient lighting turned off. Click on each image to enlarge them and compare.
Extinction
Extinction describes the brightness of the scattered light. A higher extinction value causes the light to fade more as it travels through dense air.
Extinction Effect
This darkens the rendered pixel color based on the air density and the extinction amount. This only works if a volumetric directional light is in the scene.
Sun Size
This value allows you to create a sun-like effect when looking directly at a light source. This effect can look bad if you have a low sample rate or are rendering at quarter resolution.
Back to topFog Height Settings
The height fog feature modifies the fog amount based on height. You can use this to achieve a ground-based fog effect.
Height Fog Enabled
Select this to activate fog height.
Fog Height
The fog above this height is scaled by the Above Fog Percent value.
Fog Transition Height
The fog below this height is equal to the global air density (the same amount as if Height Fog is not activated). The fog between this value and the Fog Height linearly transitions from the global air density to the value scaled by the Above Fog Percent.
Above Fog Percent
This percentage scales the fog amount for fog above the Fog Height. Choose a value between 0 and 1.
Back to topNoise Settings
3D Noise can be added to the air density, which makes the air look less homogeneous.
Noise Enabled
Select this to enable the 3D noise.
Noise Scale
This adjusts the scaling of the noise to alter the amount of detail to the noise.
Noise Velocity
You can add movement to the noise by adjusting this vector, which controls the direction and magnitude of the movement.
Back to topParticle Density Settings
You can control the air density in an area simply by using particle emitters with a HxVolumetricParticleSystem.cs script attached. In that script, you can set the particle density, which uses the alpha channel of the main texture. You can disable the renderer on the emitter if you only want to modulate the fog value without drawing the particle.

The left image shows particle emitters modulating the air density, while the right image has the feature disabled.
Particle Density Support
Check this to enable support for particle density.
Density Resolution
The particle density feature uses a 3D grid that the emitters render into. This setting controls the scale of the 3D grid, letting you make a tradeoff between speed and detail. It will not render out to a higher value than the Resolution setting in General Settings.
Density Distance
This parameter specifies the distance of the last slice of the 3D grid. If you have a 2.5D game without much depth, you can reduce this value to get more detail, since it is not stretched as far.
Back to topTransparency Settings
Objects with transparent shaders can be modified to work with Hx Volumetric Lighting. Like the particle density feature, the volumetric lighting will be rendered into a 3D grid with which transparent objects can sample when compositing. Included in this package are modified versions of the standard Unity shaders that allow for transparency with this system. When you select a shader for your material, you can find the modified standard shader under HxVolumetric->Standard.

Transparency support is enabled in the left image, allowing for proper rendering of the windows. When compositing transparent objects into the scene, extra information needs to be rendered out in a 3D texture, otherwise it doesn't know how much volumetric lighting is in front and behind it.
Transparency Support
Check this to activate support for transparency.
Transparency Distance
This is the distance of the last slice in the grid. Like the particle density grid, if you have a 2.5 game without much depth, you can reduce this value to get more detail.
Blur Transparency
This setting blurs transparent areas, removing grainy effects. It will introduce some bleeding. The recommended setting is 1.
Enabling transparency support in custom shaders
If you are using a custom shader, you will need to make some minor modifications in it to get transparency working. Modified versions of the Unity shaders are included in this package, which you can find under HxVolumetric->Standard.
Modify your shader by adding this line to the top:
Add this line to each transparent pass:
You will need data to reconstruct the world position. If you don't have it, add this definition to the vertex shader struct, substituting n for the number of the next free TEXCOORD in your vertex struct:
Then add this to your vertex shader:
In your fragment shader, in the first pass, modify your final output with this code:
In any additional passes, use this code:
General Settings
Resolution
This is the resolution that the volumetric lighting is rendered at. Quarter resolution is recommended for a mid-range GPU.
Sample Count
You can adjust the amount of samples used in the raymarching step of the lighting system. Higher values will give better signal fidelity, although with a tradeoff in framerate.
Directional Sample Count
This controls the raymarching sample count for direction lights, since you generally want a higher sample count for a directional light compared to a spot or point light.
Max Directional Ray
This is the maximum distance from the camera that should be sampled for directional lights. Limiting this distance can reduce over-fogging at large distances.
Max Light Distance
This is maximum distance that point lights and spot lights are rendered. Their intensity fades out near the edge of this distance. You can adjust this to disable the volumetric effect on distant lights for a performance increase, although distant lights are already much cheaper to render than closer lights.
Back to topAdvanced Settings
Blur Count
This is the amount of depth-aware blur passes. More passes will give better results, but it is an expensive operation. One to two is normally enough.
Blur Depth Falloff
This value is used in the depth-aware blur passes. A lower value will give more even results but will cause bleeding over the edges, giving a bloom-like effect. A higher value will retain object silhouettes, but will result in harsher artifacts. Choose a value appropriate for your art style.
Downsampled Blur Depth
If you are rendering at lower resolutions, this value will be used as the depth falloff.
Upsampled Blur Count
If you are rendering at lower resolutions, it will do a final blur pass to clean up edge artifacts. It's a bit computationally expensive, so set it to 0 if you are okay with edge artifacts.
Depth Threshold
If the depth is within this threshold when upsampling, the result will be bilinearly sampled.
Gaussian Weights
Select this to use a Gaussian weighted blur. This will make the volumetric effect less blurry, but can also make it more splotchy.
Map to LDR
If you are not using HDR on your camera, this option will handle tone mapping for you, although it is recommended that you use an external tone mapper.
Back to topTips
Here are some best practices for improving your run-time performance.
- The first time building may take an extra minute, since a lot of shader variations need to be created. Unity will cache these results so they won't need to be rebuilt.
- We recommend rendering at half resolution, for the best balance of visual quality to speed. Change to quarter resolution for the best speed.
- Lower the sample count to the lowest acceptable value. For a top-down game or a 2.5D game, you can get away a sample count as low as 8 (when rendering at full resolution). For a first-person shooter, you will need a higher sample count, with 16-32 recommended on the low end.
- Find the right balance between the sample count and blur passes - adding more blur passes can alleviate the artifacts from a low sample count. For example, a low sample count with four blur passes may look better than a high sample count with only one blur pass.
- When rendering at half resolution, you will be sampling 4x less than at full resolution. With quarter resolution, it's 16x less. That's a lot less work!
- If you do not need transparency support or particle density support, make sure the feature is disabled.
- Shadow casting lights are more expensive than non-shadow casting lights.
- The performance is not highly impacted by the number of lights: rather, it's mostly determined by the amount of the screen space rendering volumetric light.
Road Map
These are features which we plan to add in the future:
- Colored light cookie support
- Downsampling depth speed improvements
- Better depth downsampling
- Various speed improvements
- Refactoring of existing code
- VR support (untested, may already work)
About
Hx Volumetric Lighting is created by Hitbox Team. It is part of the lighting system used in the upcoming game, Spire. You can contact us in the following ways:
Websitehitboxteam.com
Emailcontact@hitboxteam.com
Twitter@hitboxteam
Facebookfacebook.com/hitboxteam
