IVolumeShape

Functions

SET_CID

RED_RC

AddVolumetricEffect

RED_RC

RemoveVolumetricEffect

RED_RC

ClearVolumetricEffects

RED_RC

GetVolumetricEffectsCount

RED_RC

GetVolumetricEffect

RED_RC

SetVolumetricEffect

RED_RC

SetRayMarchingStep

RED_RC

GetRayMarchingStep

RED_RC

SetRayCutoff

RED_RC

GetRayCutoff

RED_RC

SetScatteringSamples

RED_RC

GetScatteringSamples

RED_RC

SetLightRayMaxSamples

RED_RC

GetLightRayMaxSamples

RED_RC

SetLightRayMarchingStepIncrease

RED_RC

GetLightRayMarchingStepIncrease

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.