# class RED::VolumetricEffect

This class defines volumetric effects in a scene. More...

`#include <REDVolumetricEffect.h>`

Inherits: IChunkSaver and Object.

Inherited by: VolumetricEffectBoxVolume, VolumetricEffectClouds and VolumetricEffectLightVolume.

## Public functions:

virtual void * | As ( const RED::CID & iCID ) |

virtual const void * | As ( const RED::CID & iCID ) const |

template< class T_As > const T_As * | As ( ) const |

template< class T_As > T_As * | As ( ) |

virtual double | GetDensity ( const double iPosition[3] ) const = 0 |

virtual void | GetEmission ( double oEmission[3], const double iPosition[3] ) const = 0 |

virtual void | GetPhase ( double oPhase[3], const double iPosition[3], const double iDirection1[3], const double iDirection2[3] ) const = 0 |

virtual void | GetSigmaA ( double oSigmaA[3], const double iPosition[3] ) const = 0 |

virtual void | GetSigmaSIn ( double oSigmaS[3], const double iPosition[3] ) const = 0 |

virtual void | GetSigmaSOut ( double oSigmaS[3], const double iPosition[3] ) const = 0 |

virtual RED_RC | GetVolumeIntervals ( RED::Vector< double > & oIntervals, const double iE[3], const double iP[3], const RED::ISoftRenderingContext & iRenderCtx ) const = 0 |

virtual bool | IsHomogeneous ( ) const = 0 |

## Public static functions:

static RED::CID | GetClassID ( ) |

## Detailed description:

This class defines volumetric effects in a scene.

Stores all the parameters defining a volumetric effect. Volumetric effects are used by the RED::IVolumeShape interface, implemented by the CID_REDVolumeShape object class.

Volumetric effects are all sub-classes of this base class. This class contained only abstract methods and cannot be used directly. The sub-classes define specific volumetric effect properties and should be used instead.

A volumetric effect represents a scene medium. It is defined by several properties:

- Absorption coefficient
**sigma a**: defines how much the medium will attenuate the light. - Scattering coefficient
**sigma s**: defines how much the medium will in-scatter the light (i.e. the amount of surrounding lights which will enlighten it) and out-scatter the light (i.e. the amount of light dissipated in all directions).

To allow more flexibility, the sigma s coefficient has been split into 'sigma s in' and 'sigma s out' to control independently the in-scattering coefficient and the out-scattering one.

To be physically correct, 'sigma s in' and 'sigma s out' should have the same value.

**Phase function**: describes how the light will be scattered into the viewing direction.**Density**: describes the amount of particles in the media which will affect its brightness and opacity.**Emission**: radiance emitted by the medium in all directions. The gain comes from the conversion of other forms of energy into visible light.

To activate the rendering of volumetric effects in a scene, the RED::OPTIONS_RAY_VOLUME option must be set to 1 at least. To take into account the volumetric effects during globlal illumination process, the RED::OPTIONS_RAY_GI_ENABLE_VOLUME must be activated.

Independently, lights can be taken into account or not in the in-scattering part. They can be enabled or disabled with the RED::RM_ENLIGHTEN_VOLUME render mode. By default, all lights are sampled.

## Functions documentation

public static RED::CID RED::VolumetricEffect::GetClassID | ( | ) |

Reimplements: RED::IChunkSaver::GetClassID.

Reimplemented by: RED::VolumetricEffectBoxVolume::GetClassID, RED::VolumetricEffectClouds::GetClassID and RED::VolumetricEffectLightVolume::GetClassID.

public virtual void * RED::VolumetricEffect::As | ( | const RED::CID & | iCID | ) |

Converts the object to an instance of the given type.

Parameters:

iCID: | Requested class. |

Returns:

Reimplements: RED::Object::As.

Reimplemented by: RED::VolumetricEffectBoxVolume::As, RED::VolumetricEffectClouds::As and RED::VolumetricEffectLightVolume::As.

public virtual const void * RED::VolumetricEffect::As | ( | const RED::CID & | iCID | ) const |

Converts the object to an instance of the given type.

Parameters:

iCID: | Requested class. |

Returns:

Reimplements: RED::Object::As.

Reimplemented by: RED::VolumetricEffectBoxVolume::As, RED::VolumetricEffectClouds::As and RED::VolumetricEffectLightVolume::As.

template< class T_As > public const T_As * RED::VolumetricEffect::As | ( | ) const |

Template version of the as const method.

Simply set *T* to be the class you want to retrieve an interface to.

Returns:

Reimplements: RED::Object::As.

Reimplemented by: RED::VolumetricEffectBoxVolume::As, RED::VolumetricEffectClouds::As and RED::VolumetricEffectLightVolume::As.

template< class T_As > public T_As * RED::VolumetricEffect::As | ( | ) |

Template version of the as method.

Simply set *T* to be the class you want to retrieve an interface to.

Returns:

Reimplements: RED::Object::As.

public virtual double RED::VolumetricEffect::GetDensity | ( | const double | iPosition[3] | ) const = 0 |

Returns the volume density at a given position.

The density represents the amount of particles contained in a sample of the volume. It has an effect on the opacity and brightness of the media.

The density can take any value between 0 and 1. 0 means that the media have no particles and is therefore fully tranparent. 1 means that the media will have many particles but will not be fully opaque because it will still depend on its absorption and scattering properties.

Parameters:

iPosition: | position in the volume. |

Returns:

Implemented by: RED::VolumetricEffectBoxVolume::GetDensity, RED::VolumetricEffectClouds::GetDensity and RED::VolumetricEffectLightVolume::GetDensity.

public virtual void RED::VolumetricEffect::GetEmission | ( | double | oEmission[3], |

const double | iPosition[3] | ||

) | const = 0 |

Returns the emission coefficient at a given position.

Emission is the property of the medium to emit light.

This coefficient can take any value greater than 0 and don't have an upper limit. It can be different for each color channel.

Parameters:

oEmission: | returned emission coefficient at the volume position. |

iPosition: | position in the volume. |

Implemented by: RED::VolumetricEffectBoxVolume::GetEmission, RED::VolumetricEffectClouds::GetEmission and RED::VolumetricEffectLightVolume::GetEmission.

public virtual void RED::VolumetricEffect::GetPhase | ( | double | oPhase[3], |

const double | iPosition[3], | ||

const double | iDirection1[3], | ||

const double | iDirection2[3] | ||

) | const = 0 |

Returns the phase at a given position.

The phase function describes the amount of light from an incident light direction that is scattered into the viewing direction at a given volume position.

It takes as input the position in the volume where the phase have to be computed, the direction of the incident light and the viewing direction from the volume point. The two directions have to be normalized and can be transmitted independently via the two input parameters iDirection1 and iDirection2.

The phase function can be isotropic: light is equally scattered in all direction; or anisotropic (as illustrated): light scattering is directionally dependent. As shown in the previous illustration, given a phase function, the amount of light scattered in the view direction depends on the light direction. The more the eye is in front of the light direction, the more it receives light.

Parameters:

oPhase: | returned phase value at the given position. |

iPosition: | position in the volume. |

iDirection1: | first direction. |

iDirection2: | second direction. |

Implemented by: RED::VolumetricEffectBoxVolume::GetPhase, RED::VolumetricEffectClouds::GetPhase and RED::VolumetricEffectLightVolume::GetPhase.

public virtual void RED::VolumetricEffect::GetSigmaA | ( | double | oSigmaA[3], |

const double | iPosition[3] | ||

) | const = 0 |

Returns the absorption coefficient at a given position.

Sigma a is the property of the medium to absorb light. It describes the probability that light will be absorded at a given point in the volume.

The sigma unit is inverse length: model unit^{-1}. So it really depends on the scene size and units and must be adjusted consequently. Generally speaking, if the scene unit is the meter, the sigma coefficients should be comprised between 0 and 1m^{-1}. If the scene unit is the centimeter, the sigma coefficients should be comprised between 0 and 0.01m^{-1}.

This coefficient can take any value greater than 0 and don't have an upper limit. It can be different for each color channel.

An absorption coefficient of 0 means that light is transmitted without attenuation inside the medium: it is totally transparent. With a high value of absorption, light is totally attenuated through the volume: it becomes opaque.

Parameters:

oSigmaA: | returned absorption coefficient at the volume position. |

iPosition: | position in the volume. |

Implemented by: RED::VolumetricEffectBoxVolume::GetSigmaA, RED::VolumetricEffectClouds::GetSigmaA and RED::VolumetricEffectLightVolume::GetSigmaA.

public virtual void RED::VolumetricEffect::GetSigmaSIn | ( | double | oSigmaS[3], |

const double | iPosition[3] | ||

) | const = 0 |

Returns the in-scattering coefficient at a given position.

Sigma s is the property of the medium to scatter light. It describes the probability that light will be in-scattered at a given point in the volume.

The sigma unit is inverse length: model unit^{-1}. So it really depends on the scene size and units and must be adjusted consequently. Generally speaking, if the scene unit is the meter, the sigma coefficients should be comprised between 0 and 1m^{-1}. If the scene unit is the centimeter, the sigma coefficients should be comprised between 0 and 0.01m^{-1}.

This coefficient can take any value greater than 0 and don't have an upper limit. It can be different for each color channel.

An in-scattering coefficient of 0 means that light passing through the medium is not in-scattered (i.e. the volume is not enlightened by surrounding lights).

For physically correct medium and effect, in and out scattering coefficients should be the same.

Parameters:

oSigmaS: | returned scattering coefficient at the volume position. |

iPosition: | position in the volume. |

Implemented by: RED::VolumetricEffectBoxVolume::GetSigmaSIn, RED::VolumetricEffectClouds::GetSigmaSIn and RED::VolumetricEffectLightVolume::GetSigmaSIn.

public virtual void RED::VolumetricEffect::GetSigmaSOut | ( | double | oSigmaS[3], |

const double | iPosition[3] | ||

) | const = 0 |

Returns the out-scattering coefficient at a given position.

Sigma s is the property of the medium to scatter light. It describes the probability that light will be out-scattered at a given point in the volume.

The sigma unit is inverse length: model unit^{-1}. So it really depends on the scene size and units and must be adjusted consequently. Generally speaking, if the scene unit is the meter, the sigma coefficients should be comprised between 0 and 1m^{-1}. If the scene unit is the centimeter, the sigma coefficients should be comprised between 0 and 0.01m^{-1}.

An out-scattering coefficient of 0 means that light passing through the medium is not out-scattered (i.e. the volume does not attenuate the light).

For physically correct medium and effect, in and out scattering coefficients should be the same.

Parameters:

oSigmaS: | returned scattering coefficient at the volume position. |

iPosition: | position in the volume. |

Implemented by: RED::VolumetricEffectBoxVolume::GetSigmaSOut, RED::VolumetricEffectClouds::GetSigmaSOut and RED::VolumetricEffectLightVolume::GetSigmaSOut.

public virtual RED_RC RED::VolumetricEffect::GetVolumeIntervals | ( | RED::Vector< double > & | oIntervals, |

const double | iE[3], | ||

const double | iP[3], | ||

const RED::ISoftRenderingContext & | iRenderCtx | ||

) | const = 0 |

Returns the intervals of a ray intersecting the volume.

Given a ray, this method returns the parametric intervals along this ray where it intersects the volume.

The returned intervals are contained in a RED::Vector as a series of in and out parametric distances from the ray starting point: [in_1, out_1, in_2, out_2, ..., in_n, out_n]. Therefore, the returned array is always of size 2n.

The returned intervals do not intersect each other and are not sorted in any way.

The method clears the intervals RED:Vector before filling it.

Parameters:

oIntervals: | returned intervals. |

iE: | ray starting point. |

iP: | ray end point. |

iRenderCtx: | rendering context. |

Returns:

Implemented by: RED::VolumetricEffectBoxVolume::GetVolumeIntervals, RED::VolumetricEffectClouds::GetVolumeIntervals and RED::VolumetricEffectLightVolume::GetVolumeIntervals.

public virtual bool RED::VolumetricEffect::IsHomogeneous | ( | ) const = 0 |

Indicates if the medium is homogeneous.

This method returns true is the medium has the same properties (sigma, density and phase function) for all positions inside its volume.

Returns:

Implemented by: RED::VolumetricEffectBoxVolume::IsHomogeneous, RED::VolumetricEffectClouds::IsHomogeneous and RED::VolumetricEffectLightVolume::IsHomogeneous.