IVolumeShape
Functions
Detailed Description
-
class IVolumeShape : public RED::IREDObject
Main interface of the volume shape, that display volumic shapes in a scene.
@related Volumetric Shapes, Volumetric Effects, Rendering Volumetric Effects , class RED::IShape, class RED::VolumetricEffect
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.
Public Functions
-
SET_CID(CID_class_REDIVolumeShape)
-
virtual RED_RC 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.
-
virtual RED_RC 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
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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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
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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
SET_CID(CID_class_REDIVolumeShape)