#################
Volumetric Shapes
#################


HOOPS Luminate supports volumetric effects. Volumetric effects have no mesh representation and are only drawn dynamically during the software ray-tracing of an image. Volumetric effects have no default GPU representation, and therefore are ignored for the GPU rendering of a frame.

HOOPS Luminate has a scene graph shape for the representation of volumetric effects. It's created using the ``CID_REDVolumeShape`` identifier and the created object implements the following interfaces:

+----------------------------+--------------------------------------------+
| Interface                  | Description                                |
+============================+============================================+
| ``RED::IVolumeShape``      | API dedicated to the setup of volumetric   |
|                            | effects.                                   |
+----------------------------+--------------------------------------------+
| ``RED::IShape``            | Global shape API. Controls shape tree      |
|                            | navigation and shape attributes.           |
+----------------------------+--------------------------------------------+
| ``RED::IUserData``         | User data API to store application custom  |
|                            | data associated to a shape.                |
+----------------------------+--------------------------------------------+
| ``RED::IChunkSaver``       | Shape serialization interface.             |
+----------------------------+--------------------------------------------+
| ``RED::IReferenceSolving`` | Shape serialization interface.             |
+----------------------------+--------------------------------------------+

A volumetric shape that implements the ``RED::IVolumeShape`` interface uses a number of ``RED::VolumetricEffect`` objects to produce a visible effect in the generated image. All the volumetric effects to consider in a scene graph should be gathered in a single volume shape.

The ``RED::VolumetricEffect`` and its derived classes are in charge of the definition of the type of medium that is to be rendered by the software ray-tracer. However, the quality and performance of the sampling is defined at the ``RED::IVolumeShape`` interface level:

  * ``RED::IVolumeShape:``:SetRayMarchingStep: defines the distance between two samples. The smaller the distance, the better the resulting quality. Of course, this parameter has a significant impact on performances.
  * ``RED::IVolumeShape:``:SetScatteringSamples: defines the number of samples taken for the calculation of scattering effects. Of course more samples mean a better resulting quality and a corresponding rendering time.

More details on rendering with volumes can be found following the related links on the right side of this page.


**********************
Built-In Light Volumes
**********************

HOOPS Luminate offers two built-in volumetric effects:

  * ``RED::VolumetricEffectLightVolume``: Define a volumetric effect in the effect area of a light source. Useful for light shafts.
  * ``RED::VolumetricEffectBoxVolume``: Specify a volumetric effect in a limited region of space. Surprisingly, a box.


*************************
Custom Volumetric Effects
*************************

User defined volumetric effects can be defined and used in a HOOPS Luminate application. These should be made by inheriting from the ``RED::VolumetricEffect`` class. All details can be found in the tutorial linked here: :doc:`/tutorials/workflows/wf_rendering/wf_custom_volumetric_effect`.

