============================
Hemispheric ambient lighting
============================

To create a photorealistic effect in 3D scenes, HOOPS uses a combination of lighting algorithms to help determine the color of each pixel. To approximate the global illumination in a scene, HOOPS takes into account direct light sources, as discussed in :doc:`lighting interpolation </prog_guide/3dgs/06_3_rendering_lighting_and_color_interpolation>`, as well as indirect sources of light. In real-time 3D graphics, the calculation used to determine the contribution from indirect sources of light can be extremely expensive. An more efficient way to approximate this number is through ambient lighting.

Although ambient lighting is subtle relative to direct lighting, the addition of ambient lighting can create a significantly more realistic effect in a 3D scene. HOOPS provides the ability to create an ambient effect in a scene via the following steps. The ambient lighting model used in HOOPS assumes that light coming from below would pick up some of the ground color as it is reflected. As a result, it would be a different color than ambient light coming from above. Thus, HOOPS provides the ability to set the "ambient up" color separate from the "ambient down" color as seen in the sample code below.

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../../hoops_3df/demo/common/sanity/0700_docs_0025.cpp
		   :start-after: //! [ambient_lighting1]
		   :end-before: //! [ambient_lighting1]
		   
.. image:: images/069a_dragon_hemi.png

*A model of a dragon with hemispheric ambient lightning set so that the ambient up is blue and ambient down is brown.*

After you have set the up and down colors, use the "ambient up vector" setting in ``Set_Rendering_Options``. Using this setting, HOOPS determines that the ambient lighting component would be light brown for a point whose surface's normal is directly opposite to the defined up vector.  One the other hand, if the surface normal is the same as the up vector, the ambient lighting component would be blue. Any point with surface normals in between would get a ambient term that is interpolated between blue and light brown. The sample code below sets the up vector directly into the y direction.

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../../hoops_3df/demo/common/sanity/0700_docs_0025.cpp
		   :start-after: //! [ambient_lighting2]
		   :end-before: //! [ambient_lighting2]
		   
In addition to these two main settings, there is a system wide option that determines another characteristic of ambient light. In ``Define_System_Options``, you can set the "ambient materials" property on or off. When this option is enabled, HOOPS takes into account the material properties of the surface when calculating the ambient term treating it similar to diffuse light. However, because ambient lighting is so subtle, this can result in the the ambient light having little or no effect on the scene.  When this option is turned off, the ambient term is calculated without material properties factors much like how specular light is calculated.
