################################
Adding Clouds to the Sky Texture
################################

Until now, the sky was empty. In real life, a perfectly clear sky is very rare. We have to add clouds to it!

.. figure:: bk_sm_clouds_empty.jpg
    :align: center
    
    **Empty sky is very rare**

************************
Adding Clouds to the Sky
************************

HOOPS Luminate provides a really simple function to add several types of clouds to the sky texture:

    * ``RED::ISkyLightShape::AddClouds``

This method defines a cloud layer that will be added to the sky texture. It must be called after a sky has been defined and before the texture is created.

.. include:: /tasks/ta_ca/ta_ca_light/tk_adding_clouds.rst

Several cloud layers can be added to the sky. Each one defining a type of cloud (see ``RED::CLOUDS_TYPE`` and later on this page).
To combine multiple layers, simply call ``RED::ISkyLightShape::AddClouds`` as many times as needed layers.
The ``RED::ISkyLightShape::ClearClouds`` function allows to delete all the clouds layers that were previously added.

.. figure:: bk_sm_clouds_types.jpg
    :align: center
    
    **Different kind of layers: cirrus, stratus, cumulus and all three cumulated**

The function parameters allows to parameter the cloud layer by defining:

    * the cloud layer **altitude** (generally between 1000m and 10000m);
    * the **density** (number of cloud particles by cube meters);
    * the lighting **intensity** (how bright will be the clouds?);
    * the **opacity** (opaque clouds or nearly transparent clouds?).

Changing the view height and the sun direction of the sky model affects the clouds visualization. Clouds can be seen from below as well as from top and from inside the layer. The clouds color and intensity change according to the sun direction.

.. figure:: bk_sm_clouds_views.jpg
    :align: center
    
    **Clouds inside view and top view on sunset**

.. note:: 
    
        Cirrus layer is a simple texture. It means that it is always rendered from below. Setting an altitude for this layer type is useless.

***************
Updating Clouds
***************

Once a clouds layer have been created, it can be edited by calling the ``RED::ISkyLightShape::UpdateClouds`` function. Giving the layer index, this function will allow to change the altitude, intensity and opacity of the layer without having to recompute the clouds shape.

***********************************************************
A Few Remarks about HOOPS Luminate Background Clouds System
***********************************************************

    * Contrary to the physical sky, clouds are not really physical. They are build from particles and textures.
    * Adding clouds to the sky texture will not affect the sky lighting.
    * The clouds functionality needs the **REDResources.red** data file. It is provided with HOOPS Luminate and must be placed next to the executable.
    * The clouds layers are spherical and follow the earth curvature.
    * The clouds are build randomly. The random seed must be provided as parameter of the ``RED::ISkyLightShape::AddClouds`` function.
    * Currently, clouds can only be added in the background texture, meaning you can't add objects inside a cloud layer.

**********************************
List of HOOPS Luminate Clouds Type
**********************************

HOOPS Luminate provides different kind of clouds appearance via its ``RED::CLOUDS_TYPE`` enumeration.

*Cumulus*
=========

These are high density puffy clouds with clearly defined edges. They appear at low altitude (less than 2000 m).

.. figure:: bk_sm_clouds_cumulus.jpg
    :align: center
    
    **RED::CT_CUMULUS appearance**

*Stratus*
=========

Stratus are flat hazy clouds with low density. They appear at middle altitude (from 2000 to 7000 m).
The opacity of the clouds layer should be decreased for these types of clouds.

.. figure:: bk_sm_clouds_stratus.jpg
    :align: center
    
    **RED::CT_STRATUS appearance**

*Cirrus*
========

These are thin, wispy clouds at high altitude. In HOOPS Luminate, they are rendered using a simple texture applied to the background sky.

Several cirrus textures are available as shown in the following pictures.

.. figure:: bk_sm_clouds_cirrus1.jpg
    :align: center
    
    **RED::CT_CIRRUS_1 appearance**

.. figure:: bk_sm_clouds_cirrus2.jpg
    :align: center
    
    **RED::CT_CIRRUS_2 appearance**

.. figure:: bk_sm_clouds_cirrus3.jpg
    :align: center
    
    **RED::CT_CIRRUS_3 appearance**

.. figure:: bk_sm_clouds_cirrus4.jpg
    :align: center
    
    **RED::CT_CIRRUS_4 appearance**

.. figure:: bk_sm_clouds_cirrus5.jpg
    :align: center
    
    **RED::CT_CIRRUS_5 appearance**

