class RED::IVolumeShape

Main interface of the volume shape, that display volumic shapes in a scene. More...

#include <REDIVolumeShape.h>

Inherits: IREDObject.

Public functions:

virtual RED_RC	AddVolumetricEffect ( const RED::VolumetricEffect * iEffect, const RED::State & iState ) = 0
virtual RED_RC	ClearVolumetricEffects ( const RED::State & iState ) = 0
virtual RED_RC	GetLightRayMarchingStepIncrease ( double & oStepIncrease, int iStateNumber = -1 ) const = 0
virtual RED_RC	GetLightRayMaxSamples ( unsigned int & oSamples, int iStateNumber = -1 ) const = 0
virtual RED_RC	GetRayCutoff ( double & oRayCutoff, int iStateNumber = -1 ) const = 0
virtual RED_RC	GetRayMarchingStep ( double & oStep, int iStateNumber = -1 ) const = 0
virtual RED_RC	GetScatteringSamples ( unsigned int & oSamples, int iStateNumber = -1 ) const = 0
virtual RED_RC	GetVolumetricEffect ( const RED::VolumetricEffect *& oEffect, int iNumber, int iStateNumber = -1 ) const = 0
virtual RED_RC	GetVolumetricEffectsCount ( int & oCount, int iStateNumber = -1 ) const = 0
virtual RED_RC	RemoveVolumetricEffect ( int iNumber, const RED::State & iState ) = 0
virtual RED_RC	SetLightRayMarchingStepIncrease ( double iStepIncrease, const RED::State & iState ) = 0
virtual RED_RC	SetLightRayMaxSamples ( unsigned int iSamples, const RED::State & iState ) = 0
virtual RED_RC	SetRayCutoff ( double iRayCutoff, const RED::State & iState ) = 0
virtual RED_RC	SetRayMarchingStep ( double iStep, const RED::State & iState ) = 0
virtual RED_RC	SetScatteringSamples ( unsigned int iSamples, const RED::State & iState ) = 0
virtual RED_RC	SetVolumetricEffect ( int iNumber, const RED::VolumetricEffect * iEffect, const RED::State & iState ) = 0

Detailed description:

Main interface of the volume shape, that display volumic shapes in a scene.

The CID_REDVolumeShape is the object to create to instantiate all volumetric effects in a scene. One volume shape instance is needed for an entire scene graph. The volume shape instance internally setups its own material. Therefore, the material of a volume shape should not be overriden.

The material of the shape will evaluate all the volumetric effects declared through this interface to compute the resulting color influence of all volumetric effects declared in the class.

In software rendering, the volume shape has no effective presence in a scene in the sense that no geometry is being associated to it. However, it gets shaded thanks to the shape material. For every ray propagated in the scene, the volume shape is evaluated and its influence over the lighting and shadowing is taken into consideration.

In hardware rendering, volume shapes are ignored for now.

The volume shape has no bounding sphere. If a bounding sphere is set on a volume shape, it's ignored.

The volume shape is a state sensitive object.

If more than one volume shape is found in a scene graph, the last shape found during the scene graph parsing will be considered and other shapes will be ignored.

Functions documentation

public static RED::CID RED::IVolumeShape::GetClassID

(

)

public virtual RED_RC RED::IVolumeShape::AddVolumetricEffect	(	const RED::VolumetricEffect *	iEffect,
		const RED::State &	iState
	)	= 0

Adds a volumetric effect to the list of volumetric effects to process for the scene.

The user is responsible for deleting the volumetric effect when the engine doesn't use it anymore.

Parameters:

iEffect:	The volumetric effect.
iState:	The current transaction parameter.

Returns:

RED_OK if the operation has succeeded,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_ALLOC_FAILURE if a memory allocation error has failed.

public virtual RED_RC RED::IVolumeShape::ClearVolumetricEffects

(

const RED::State &

iState

) = 0

Removes all volumetric effects from the scene.

Parameters:

iState:

The current transaction parameter.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_ALLOC_FAILURE if a memory allocation error has failed.

public virtual RED_RC RED::IVolumeShape::GetLightRayMarchingStepIncrease	(	double &	oStepIncrease,
		int	iStateNumber = -1
	)	const = 0

Gets the increasing rate of the sampling step used during ray marching to the lights.

See RED::IVolumeShape::SetLightRayMarchingStepIncrease.

Parameters:

oStepIncrease:	Returned increase rate of the sampling step.
iStateNumber:	The queried transaction number.

Returns:

RED_OK if the operation has succeeded,
RED_FAIL otherwise.

public virtual RED_RC RED::IVolumeShape::GetLightRayMaxSamples	(	unsigned int &	oSamples,
		int	iStateNumber = -1
	)	const = 0

Gets the maximum number of samples used during ray marching to the lights.

Parameters:

oSamples:	Returned maximum number of samples.
iStateNumber:	The queried transaction number.

Returns:

RED_OK if the operation has succeeded,
RED_FAIL otherwise.

public virtual RED_RC RED::IVolumeShape::GetRayCutoff	(	double &	oRayCutoff,
		int	iStateNumber = -1
	)	const = 0

Gets the ray cutoff under which ray marching is stopped during volume shading.

Parameters:

oRayCutoff:	Returned ray cutoff.
iStateNumber:	The queried transaction number.

Returns:

RED_OK if the operation has succeeded,
RED_FAIL otherwise.

public virtual RED_RC RED::IVolumeShape::GetRayMarchingStep	(	double &	oStep,
		int	iStateNumber = -1
	)	const = 0

Gets the ray marching step size used during volume shading.

Parameters:

oStep:	Returned ray marching step size.
iStateNumber:	The queried transaction number.

Returns:

RED_OK if the operation has succeeded,
RED_FAIL otherwise.

public virtual RED_RC RED::IVolumeShape::GetScatteringSamples	(	unsigned int &	oSamples,
		int	iStateNumber = -1
	)	const = 0

Gets the number of samples used for volume lighting in case of scattering events.

Parameters:

oSamples:	Returned scattering samples count.
iStateNumber:	The queried transaction number.

Returns:

RED_OK if the operation has succeeded,
RED_FAIL otherwise.

public virtual RED_RC RED::IVolumeShape::GetVolumetricEffect	(	const RED::VolumetricEffect *&	oEffect,
		int	iNumber,
		int	iStateNumber = -1
	)	const = 0

Retrieves a given volumetric effect.

Modifying a registered volumetric effect requires a RED::IVolumeShape::SetVolumetricEffect call to be issued with the modified volumetric effect value.

Parameters:

oEffect:	The retrieved effect.
iNumber:	The number of the effect in the class's list.
iStateNumber:	The queried transaction number.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.

public virtual RED_RC RED::IVolumeShape::GetVolumetricEffectsCount	(	int &	oCount,
		int	iStateNumber = -1
	)	const = 0

Returns the number of effects declared.

Parameters:

oCount:	The number of volumetric effects stored in the class.
iStateNumber:	The queried transaction number.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.

public virtual RED_RC RED::IVolumeShape::RemoveVolumetricEffect	(	int	iNumber,
		const RED::State &	iState
	)	= 0

Removes a volumetric effect from the list of effects declared in the scene.

Parameters:

iNumber:	Number of the effect to remove in the shape's list.
iState:	The current transaction parameter.

Returns:

public virtual RED_RC RED::IVolumeShape::SetLightRayMarchingStepIncrease	(	double	iStepIncrease,
		const RED::State &	iState
	)	= 0

Sets the increase rate of the sampling step used during ray marching to the lights.

The iStepIncrease parameter is used to increase the step size during ray marching to the lights in case of scattering events. This parameter is used to speed up the ray marching by assuming that the sampling needs to be more precise near the lighted point and less and less precise by moving away from it. It allows to decrease the number of samples needed to cross the volume shape.

If iStepIncrease value is 0, the samples size does not increase. If iStepIncrease value is 1, each step is twice as big as its predecessor. The formula is:

  step = step + iStepIncrease * step

Setting the step value can be done with RED::IVolumeShape::SetRayMarchingStep.

Parameters:

iStepIncrease:	Increase rate of the sampling step.
iState:	The current transaction parameter.

Returns:

RED_OK if the operation has succeeded,
RED_FAIL otherwise.

public virtual RED_RC RED::IVolumeShape::SetLightRayMaxSamples	(	unsigned int	iSamples,
		const RED::State &	iState
	)	= 0

Sets the maximum number of samples used during ray marching to the lights.

Parameters:

iSamples:	Maximum number of samples.
iState:	The current transaction parameter.

Returns:

RED_OK if the operation has succeeded,
RED_FAIL otherwise.

public virtual RED_RC RED::IVolumeShape::SetRayCutoff	(	double	iRayCutoff,
		const RED::State &	iState
	)	= 0

Sets the ray cutoff under which ray marching is stopped during volume shading.

Parameters:

iRayCutoff:	Ray cutoff.
iState:	The current transaction parameter.

Returns:

RED_OK if the operation has succeeded,
RED_FAIL otherwise.

public virtual RED_RC RED::IVolumeShape::SetRayMarchingStep	(	double	iStep,
		const RED::State &	iState
	)	= 0

Sets the ray marching step size used during volume shading.

Parameters:

iStep:	Ray marching step size.
iState:	The current transaction parameter.

Returns:

RED_OK if the operation has succeeded,
RED_FAIL otherwise.

public virtual RED_RC RED::IVolumeShape::SetScatteringSamples	(	unsigned int	iSamples,
		const RED::State &	iState
	)	= 0

Sets the number of samples used for volume lighting in case of scattering events.

Parameters:

iSamples:	Scattering samples count.
iState:	The current transaction parameter.

Returns:

RED_OK if the operation has succeeded,
RED_FAIL otherwise.

public virtual RED_RC RED::IVolumeShape::SetVolumetricEffect	(	int	iNumber,
		const RED::VolumetricEffect *	iEffect,
		const RED::State &	iState
	)	= 0

Modifies a registered volumetric effect.

Parameters:

iNumber:	Number of the modified string.
iEffect:	The effect to setup.
iState:	The current transaction parameter.

Returns:

class RED::IVolumeShape

Public functions:

Public static functions:

Detailed description:

Functions documentation