=====
Bloom
=====

In the real world, when a scene is viewed through a lens, there inevitably will be some distortion. Normally, these imperfections are not noticeable, but when there is an intensely bright light source, this light appears to bleed beyond its natural borders. Bloom is the graphics effect that mimics this behavior in digitally generated scenes.

Traditionally, when rendered in high dynamic range (HDR) systems, bloom produces feathery light around very bright objects in a scene. As this is an intensive computational process, the effect cannot be exactly reproduced in non-HDR systems. However, |HPSNOW| offers an highly effective approximation of bloom through a post-processing step.

Bloom can be enabled by setting a properly configured ``HPS::PostProcessEffectsKit`` on a window key. Since post-process effects can only be set at the window level, they cannot be selectively enabled for different parts of the scene. You can achieve precise control of the effect by changing the *strength* sub-option, which is a multiplier on the default contribution of the bloom calculation. Note that only light contributions based on specular, emission, or environment map will be blurred in a bloom effect.

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00700_bloom.cpp
		   :start-after: //! [enable_bloom]
		   :end-before: //! [enable_bloom]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_bloom.cs
		   :start-after: //! [enable_bloom]
		   :end-before: //! [enable_bloom]
		   
.. image:: images/bloom.png

*A cylinder shown with bloom enabled (left) and disabled (right). Note this is a composite image - bloom is a window-level effect*

|HPSNOW| also features the ability to specify the number of blur passes performed on the scene via the blur suboption. The more passes performed on a scene widens and smooth the effect. You can also determine the shape of the kernel used in performing the bloom calculation. The default kernel shape is *radial* but you can also choose *star*, which results in a slightly different bloom shape. To do this, specify the shape in your call to ``SetBloom``:

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00700_bloom.cpp
		   :start-after: //! [star_bloom]
		   :end-before: //! [star_bloom]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_bloom.cs
		   :start-after: //! [star_bloom]
		   :end-before: //! [star_bloom]
		   
.. image:: images/star_bloom_a.png

.. image:: images/star_bloom_b.png

*Above, a turbine engine is rendered with the bloom effect using the radial kernel. Below, the same turbine engine is rendered using the star kernel.*


Limitations of Bloom
--------------------

Like all post-processing effects, bloom is only available on the shader-based drivers.
