ISoftLight

Detailed Description

class ISoftLight : public RED::IREDObject

This interface gives access to soft light source properties.

@related The CPU Programming Pipeline, Writing a Custom Software Rendering Shader, task Iterating Over Lights in a Software Shader

When using the REDsdk soft tracer, the shaders receive the list of active lights as an array of objects that implement the RED::ISoftLight interface.

This interface gives read-only access to all the needed information about each light source.

Public Functions

SET_CID(CID_class_REDISoftLight)
virtual RED::Object *GetShape() const = 0

GetShape: Returns the light source shape address from which this soft light was created.

Returns:The light source shape address.
virtual bool IsSkyLight(bool *oHemispherical = NULL) const = 0

Returns true if the light is a skylight.

Parameters:oHemispherical – optional pointer set to true if the light is a hemispherical sky light, false otherwise.
Returns:true if the light is a skylight, false otherwise.
virtual void GetDiffuseIntensity(double oDiffuse[4]) const = 0

Gets the light diffuse intensity.

The diffuse intensity of the light is the color to be used while computing the diffuse part of the shading model (a specular intensity is available for for the specular part of the shading model).

Parameters:oDiffuse – the diffuse intensity of the light.
virtual void GetSpecularIntensity(double oSpecular[4]) const = 0

Gets the light specular intensity.

The specular intensity of the light is the intensity to be used while computing the specular part of the shading model (a diffuse color is available for for the diffuse part of the shading model).

Parameters:oSpecular – the specular intensity of the light.
virtual bool GetAttenuation(double oAttenuation[4], int iThreadID) const = 0

Gets the light attenuation at the given shading point.

The attenuation integrates spots & beams falloffs and global light backface culling vs. the current shading point & normal.

Parameters:
  • oAttenuation – Resulting attenuation.
  • iThreadID – ID of the calling thread.
Returns:

true if the light intensity is greater than 0, false otherwise.

virtual bool GetVolumeAttenuation(double oAttenuation[4], const double *iPoint) const = 0

Gets the light attenuation at a given point in a volume.

The attenuation integrates spots & beams falloffs and global light backface culling vs. the shaded ‘iPoint’ position in WCS (whitout any heading).

Parameters:
  • oAttenuation – Resulting attenuation.
  • iPoint – Lit point in world space.
Returns:

true if the light intensity is greater than 0, false otherwise.

virtual bool NeedSampling() const = 0

Returns true if the light needs sampling, false otherwise.

Note that sampling based light types are mapped onto centric lights types if the sampling is disabled for the rendering.

Returns:true if the light needs sampling, false otherwise.
virtual void GetWCSLightPos(double oLightPos[4]) const = 0

Gets the light position in world coordinates space.

Parameters:oLightPos – Light position in world coordinates space.
virtual void GetWCSLightDir(double oDirection[4]) const = 0

Gets the light direction in world coordinates space.

Parameters:oDirection – Light direction in world coordinates space.
virtual void GetWCSLightDir(double oDirection[4], const double *iPoint, const double *iSample) const = 0

Gets the direction to the light in world coordinate space from a given point.

Returns the direction from ‘iPoint’ to the light source. ‘iSample’ is only needed in the case of a varying sample position on an area light. ‘iPoint’ can be ignored for directional and beam lights and is otherwise required.

The returned direction is normalized.

Parameters:
  • oDirection – The returned direction to the light in WCS.
  • iPoint – Point from which we need the light direction (must be in WCS). This value must be set for all point lights area and skylights (double[4]).
  • iSample – Light source sample position for area lights or light source direction for skylights (double[4]).
virtual void GetWCSBoundingSphere(double oPosition[4], double &oRadius2) const = 0

Gets the light bounding sphere in world coordinates space.

The light must be a physical light to have a bounding sphere. For other light types, the function will return the light position and a radius of 0.

Parameters:
  • oPosition – Bounding sphere position in world coordinates space.
  • oRadius2 – Bounding sphere square radius.
virtual unsigned int GetSamplesCount() const = 0

Gets the number of samples set for the light.

Note that the sampling uses the GetNextWCSSample method. As a consequence of sampling adaptivity, the real number of samples used to evaluate a light’s contribution at a given shading point is not constant.

The number of samples for the light is ignored during sampling unless the RED::OPTIONS_RAY_LIGHTS_SAMPLING_RATE is set to 0.

Returns:the number of samples needed for the light.
virtual unsigned int GetSeed() const = 0
Returns:the seed of the light for random number generation.
virtual RED_RC GetNextWCSSample(bool &oCompleted, double oLightDirection[4], double oLightColor[4], double oShadowColor[4], const double iPosition[4], const double iNormal[4], const RED::ISoftRayContext &iRayContext, const RED::ISoftRenderingContext &iRenderingContext) const = 0

Returns light information computed for the next sample of an unknown length sampling sequence.

A sampling sequence must have been previously started using RED::ISoftRayContext::PrepareLights.

This method takes into consideration the light source visibility and attenuation due to decay or falloff (returned in ‘oLightColor’) and calculates shadows (returned in ‘oShadowColor’).

\task tk_iterating_over_lights_software_shader

Parameters:
  • oCompleted – true if the sampling process must be ended, false otherwise.
  • oLightDirection – return the unit-length light direction to the sample from the shaded surface.
  • oLightColor – return the color of the light reaching the given position. In order to get the full color of the light reaching the point, you still have to multiply ‘oLightColor’ value by the light diffuse (or specular) intensity and the value of ‘oShadowColor’.
  • oShadowColor – return the color of the shadow at the shading point.
  • iPosition – position of the point being shaded.
  • iNormal – normal vector at ‘iPosition’.
  • iRayContext – the current ray context.
  • iRenderingContext – the current rendering context.
Returns:

RED_OK on success,

RED_BAD_PARAM on an invalid parameter,

RED_ALLOC_FAILURE on a memory allocation error,

RED_FAIL otherwise.
virtual RED_RC GetWCSSample(double oLightDirection[4], double oLightColor[4], double oShadowColor[4], double &oPDF, const double iPosition[4], const double iNormal[4], double iSample[2], const RED::ISoftRayContext &iRayContext, const RED::ISoftRenderingContext &iRenderingContext) const = 0

Gets a light sample for direct lighting integration.

Users should prefer the use of the classical light sampling sequence described in:

\task tk_iterating_over_lights_software_shader

This method is for experienced users only who wrote their own light sampling function.

Parameters:
  • oLightDirection – return the unit-length light direction to the sample from the shaded surface.
  • oLightColor – return the color of the light reaching the given position. In order to get the full color of the light reaching the point, you still have to multiply oLightColor value by the light diffuse (or specular) intensity and the value of oShadowColor.
  • oShadowColor – return the color of the shadow at the shading point.
  • oPDF – the pdf of the sample.
  • iPosition – position of the point being shaded.
  • iNormal – normal vector at iPosition.
  • iSample – Input randomized sampling coordinates.
  • iRayContext – the current ray context.
  • iRenderingContext – the current rendering context.
Returns:

RED_OK on success, RED_BAD_PARAM on an invalid parameter, RED_ALLOC_FAILURE on a memory allocation error, RED_FAIL otherwise.

virtual int GetRenderMode(RENDER_MODE iMode) const = 0

Gets the requested render mode value.

Parameters:iMode – the render mode to retrieve.
Returns:the requested render mode value.
virtual const Color &GetShadowColor() const = 0

Returns the color of shadows for this light.

Returns:A reference to the shadow color to use.
virtual double GetShadowBias() const = 0

Returns the shadow bias for this light.

Returns:The shadow bias value for the light.
virtual const RED::LayerSet &GetLayerSetLit() const = 0

Returns the lighting layerset.

An object whose layerset intersects the lit layerset of the light source receives lighting from that light source.

Returns:The lighting layerset for this light source.
virtual const RED::LayerSet &GetLayerSetShadowCaster() const = 0

Returns the light shadow casting layerset.

An object whose layerset intersects the shadow casting layerset of the light source will cast shadows onto other objects.

Returns:The shadow casting layerset for this light source.
virtual const RED::LayerSet &GetLayerSetShadowReceiver() const = 0

Returns the light shadow receiver layerset.

An object whose layerset intersects the shadow receiver layerset of the light source will receive shadows from other objects.

Returns:The shadow receiver layerset for this light source.
virtual RED::LIGHT_TYPE GetLightType() const = 0

Returns the light type.

Returns:The light type.
virtual double GetSpotAngle() const = 0

Returns the spot angle if the light is a spot.

Returns:The spot angle.
virtual double GetSpotFallOff() const = 0

Returns the spot falloff if the light is a spot.

Returns:The spot falloff.
virtual double GetEffectDistance() const = 0

Returns the effect distance of the light.

The effect distance of a light is based on its attenuation equation, and represents the sphere of influence of the light. A light source that has no attenuation emits lights up to RED_INVTOL2 units.

Returns:The value of this effect area in [0.0f,RED_INVTOL2[.
virtual double GetBeamInnerRadius() const = 0

Returns the beam inner radius if the light is a beam.

Returns:The beam inner radius.
virtual double GetBeamOuterRadius() const = 0

Returns the beam outer radius if the light is a beam.

Returns:The beam outer radius.