ILightShape
Functions
Detailed Description
-
class ILightShape : public RED::IREDObject
This interface gives access to light source properties.
@related Light Shapes, class RED::IShape, Light
The CID_REDLightShape exposes the RED::ILightShape interface.
The bounding sphere of a light source is defined based on its attenuation distance, when this is applicable:
Directional lights, skylights and ambient lights have no bounding sphere.
All other lights may have a bounding sphere.
The bounding sphere is set to enclose the effect area of the light in an optimized way, so there may be no relationship between the light position and the center of its bounding sphere (case of a beam light for instance).
The light source bounding sphere behaves differently, depending on the type of the light source:
For all centric lights, the light’s power is representative of the energy that is emitted from the light, no matter the position and transform applied to the light: so practically, the bounding sphere of a centric light is not scaled with the inheritance transform of the DAG it comes from.
For area lights, the light’s power is representative of the emitted energy by the light, but the amount of energy that is received by a point in space depends on the visible light source surface from that point. Therefore, the bounding sphere of the light source has to be scaled by the DAG transform it comes from.
Similarly, the radial effect of a beam and the spot angles of a point or area light don’t scale with the transformation that are applied to them.
The light source shape enforces all othe DAG inheritance rules, with the exception of the material rule has no effect on it.
Ambient lights should be unique in a DAG. However, as they can be used like any other shape, an ambient light that is child of a node that has a bounding sphere may be culled out of the scene if its parent node gets culled too. This is a side effect of the DAG. The most common way to deal with an ambient light is to link it to the root node of the scene with no bounding sphere.
Area lights are rendered using an approximated shading equation on the GPU and are rendered by Quasi Monte Carlo sampling methods on the CPU, using a number of samples during the definition of the light (see RED::ILightShape::SetRectangularAreaLight). An area light can only use a RED::ATN_QUADRATIC decay equation. Area lights are fast to render on the GPU and provide a very good approximation of a rectangular physical light in realtime.
All centric lights are using a single intensity sample centered at the light source position.
The ambient light does not use any sample at all.
The skylight is a very specific light. It has several special behaviors:
A skylight is rendered using a specific shading model on the GPU that approximates the illumination coming from the spherical or hemispherical dome of the sky.
A skylight ignores it’s specular intensities. The light intensity of a skylight comes from it’s texture map (usually a HDR map).
A skylight is rendered as an ambient light on the CPU or on the GPU if area sampling is disabled and if the engine is in hybrid mode or in software mode.
A skylight only supports ray-traced shadows.
The skylight has a specific RED::ISkyLightShape interface.
The default axis system of a light is:
sight = RED::Vector3::XAXIS.
top = RED::Vector3::YAXIS.
right = RED::Vector3::ZAXIS.
Please refer to \ref bk_sg_the_axis_system_of_a_light for details on the setup of the axis system of a light.
Shadow mapping is a common shadow method used for light sources. Shadow maps in REDsdk can use a feature called the “auto range” (enabled by default). If enabled, the “auto range” system calculates the optimal near / far values to use for the effect range of a shadow map. This can affect the shadowing performances in a significant manner. Note that this feature only works if the scene has bounding spheres set on its objects and if the rendering is perfored in hardware. In software, a lower quality auto range calculation is performed. See RED::ILightShape::SetShadowMapAutoRange. Please read this page: \ref bk_re_shadow_mapping_detailed if you need any further details on shadow mapping.
Public Functions
-
virtual RED_RC SetPointLight(ATTENUATION iAtt, float iAttValue[7], const RED::Vector3 &iPos, const RED::Color &iDiffuse, const RED::Color &iSpecular, const RED::State &iState) = 0
Sets the parameters for a point light.
Sets the base parameters needed for the rendering of a point light. Input values coherency is verified by this method. Note that the light will loose its spot attribute after this call unless a call to RED::ILightShape::SetSpotLight is made again.
See also \ref wf_hello_world.
- Parameters
iAtt – Attenuation of the light source.
iAttValue – Attenuation parameters.
iPos – Light source position.
iDiffuse – Light source diffuse intensity.
iSpecular – Light source specular intensity.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC SetRectangularAreaLight(float iIntensity, const RED::Vector3 &iPos, const RED::Vector3 &iLightDir, const RED::Vector3 &iTopDir, const RED::Color &iDiffuse, const RED::Color &iSpecular, int iSamplesCount, float iWidth, float iHeight, const RED::State &iState) = 0
Defines a rectangular area light.
Sets parameters for the rendering of a rectangular area light. Input values coherency is verified by this method. Note that the light will loose its spot attribute after this call unless a call to RED::ILightShape::SetSpotLight is made again.
The light is defined as a rectangular area light of size iWidth along the light’s right axis, ranging [ -iWidth / 2.0, +iWidth / 2.0 ] and of size iHeight along the light’s top axis, ranging [ -iHeight / 2.0, iHeight / 2.0 ].
The light’s right axis is defined by the cross product of ( iLightDir, iTopDir ).
A rectangular area light is rendered using shading and shadowing approximations on the GPU and is rendered using quasi Monte-Carlo sampling on the CPU.
The number of samples that can be rolled by the software ray-tracer to estimate the lighting produced by the light is defined by iSamplesCount.
The area light is an approximation of rectangular physical lights, mainly aimed for realtime. It can be rendered seamlessly on the CPU or on the GPU. The shading of the rectangular area light is identical to the shading of a rectangular physical light if the shaded point “sees” the entire light. Otherwise, if the light is partly below the horizon of the shaded point, the produced shading is not physically correct and tends to be darker than the correct shading.
The image below summarizes the differences in shading between the area light and the physical lights:
Practically, the use of area lights tends to create very slightly darker images on regions that are not well illuminated. As far as we have experienced, most of the times, this effect can be neglected.
The area light’s intensity is not identical to a rectangular physical light intensity of the same dimensions and the formula below can be used to exactly convert the physical light intensity into an area light intensity and vice-versa:
// Access physical light parameters: RED::IPhysicalLightShape* iphy = ... RC_TEST( iphy->GetColor( physical_color ) ); RC_TEST( iphy->GetEfficacy( efficacy ) ); RC_TEST( iphy->GetEmitter( mesh, scale, area ) ); RC_TEST( iphy->GetLuminousFlux( intensity ) ); RC_TEST( iphy->IsDoubleSided( is_double_sided ) ); // Assuming that width and height are the physical rectangular light dimensions, // Calculate the new intensity for the area light: // intensity *= 1.0 / area light surface in square meters. // *= 1.0 / light efficacy. // *= 1.0 / spherical diffuse integral normalization factor. intensity = 2.0f * intensity / ( (float)width * scale * (float)height * scale * efficacy * RED_PI ); if( is_double_sided == true ) intensity *= 0.5f; // Setup the area light equivalent parameters: RED::ILightShape* ilight = ... RC_TEST( ilight->SetDiffuseIntensity( physical_color ) ); RC_TEST( ilight->SetSpecularIntensity( RED::Color::BLACK ) ); float att_values[ RED_LIGHT_ATT_NB_VALUES ]; for( i = RED_LIGHT_ATT_NB_VALUES - 1; i >= 0; i-- ) att_values[i] = 0.0f; att_values[0] = intensity; RC_TEST( ilight->SetAttenuation( RED::ATN_QUADRATIC, att_values ) );
See also \ref tk_setup_a_rectangular_area_light.
- Parameters
iIntensity – intensity of the light source. Is the first attenuation parameter value.
iPos – Light source position.
iLightDir – Area source light’s axis.
iTopDir – Top axis used to define the area light orientation.
iDiffuse – Light source diffuse intensity.
iSpecular – Light source specular intensity.
iSamplesCount – Number of samples to populate the light surface. Must be greater than 0.
iWidth – Width of the rectangle, along the light’s right axis.
iHeight – Height of the rectangle, along the light’s top axis.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC SetDirectionalLight(float iIntensity, const RED::Vector3 &iPos, const RED::Vector3 &iLightDir, const RED::Vector3 &iTopDir, const RED::Color &iDiffuse, const RED::Color &iSpecular, const RED::State &iState) = 0
Sets the parameters for a directional light.
Sets the base parameters needed for the rendering of a directional light. Input values coherency is verified by this method.
A directional light emits light rays along iLightDir, and is considered to be of infinite extension in the plane perpendicular to iLightDir. iTopDir complete the definition of the directional light’s basis (the third direction being the cross product of the two others), that is centered at iPos.
All vectors are unitized by the function.
Directional lights can’t cast shadow maps. Beam lights are also directional lights but that are able to use shadow mapping.
See also \ref tk_setup_a_directional_light.
- Parameters
iIntensity – Intensity of the directional light. We do not support any falloff for a directional light, but we have a constant intensity for it that we may configure. This intensity is stored in the first attenuation value.
iPos – Light source position.
iLightDir – Directional source light’s axis.
iTopDir – Lighting window definition axis.
iDiffuse – Light source diffuse intensity.
iSpecular – Light source specular intensity.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC SetBeamLight(ATTENUATION iAtt, float iAttValues[7], const RED::Vector3 &iPos, const RED::Vector3 &iLightDir, const RED::Vector3 &iTopDir, const RED::Color &iDiffuse, const RED::Color &iSpecular, float iInnerRadius, float iOuterRadius, const RED::State &iState) = 0
Sets the parameters for a beam light.
Sets the base parameters needed for the rendering of a beam light. Input values coherency is verified by this method.
A beam light emits light rays along iLightDir and has a finite radial extension defined by iInnerRadius and iOuterRadius. Between the two radii values, the light intensity smoothly decreases.
iTopDir defines the second axis of the light’s system which is completed internally and centered at iPos.
All vectors are unitized by the call.
See also \ref tk_setup_a_beam_light.
- Parameters
iAtt – Attenuation of the light source.
iAttValues – Attenuation parameters.
iPos – Light source position.
iLightDir – Directional source light’s axis.
iTopDir – Lighting window definition axis.
iDiffuse – Light source diffuse intensity.
iSpecular – Light source specular intensity.
iInnerRadius – Full intensity radius of the light.
iOuterRadius – Zero intensity radius of the light.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC SetSpotLight(const RED::Vector3 &iSpotOrigin, const RED::Vector3 &iSpotDir, const RED::Vector3 &iSpotTop, float iSpotAngle, float iSpotFalloff, float iSpotDropoff, const RED::State &iState) = 0
Turns a point light or an area light into a spot.
This method sets the parameters needed to render the provided light source data as a spot. Two spots definition axis must be provided:
iSpotOrigin: origin of the spot (should be the same origin point as for a point light).
iSpotDir: direction of the spot center.
iSpotTop: perpendicular to the spot direction, used for the spot rotation, if its display is not circular.
In addition to that, we need:
iSpotAngle: the spot half-angle. In the cone whose apex is at the light’s source position, headed at iSpotDir, of iSpotAngle angle, the light radial intensity is pow(cos(angle(L,S)),iSpotDropoff).
iSpotFalloff: beyond the iSpotAngle cone, the radial intensity smoothly drops to 0.0f at the iSpotAngle + iSpotFalloff limit angle.
iSpotDropoff: intensity decay within the main cone area.
All vectors are unitized by the function. Note that the sum of both angles can’t be greater than Pi / 2 (as the whole spot angle will be twice that sum).
See also \ref wf_hello_world.
- Parameters
iSpotOrigin – Origin of the spot.
iSpotDir – Spot center direction.
iSpotTop – Perpendicular to iSpotDir defines the spot orientation.
iSpotAngle – Spot half-angle.
iSpotFalloff – Additional angle for the spot penumbra dropoff.
iSpotDropoff – Exponent of the intensity variation in the main spot cone.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC SetAmbientLight(const RED::Color &iDiffuse, const RED::State &iState) = 0
Sets the light data to be an ambient light.
Sets the parameters of the light to be those of an ambient light emitting the [iR,iG,iB] color.
See also \ref tk_setup_an_ambient_light.
- Parameters
iDiffuse – Light’s color.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if invalid parameters were provided to the routine.
-
virtual RED_RC IsPointLight(bool &oPoint, int iStateNumber = -1) const = 0
Is the light a point light?
See also \ref wf_deferred_shading.
- Parameters
oPoint – Returns true if the light is a point light. Note that this is not related to whether the light is a spot or not.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
-
virtual RED_RC IsAreaLight(bool &oArea, int iStateNumber = -1) const = 0
Is the light an area light?
- Parameters
oArea – Returns true if the light is an area light. Note that this is not related to whether the light is a spot or not.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
-
virtual RED_RC IsSpotLight(bool &oSpot, int iStateNumber = -1) const = 0
Is the light a spot light?
See also \ref wf_deferred_shading.
- Parameters
oSpot – Returns true if the light is a spot light. Point lights and area lights may be spotlights.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
-
virtual RED_RC IsDirectionalLight(bool &oDir, int iStateNumber = -1) const = 0
Is the light a directional light?
- Parameters
oDir – Returns true if the light is a directional light.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
-
virtual RED_RC IsBeamLight(bool &oBeam, int iStateNumber = -1) const = 0
Is the light a beam light?
- Parameters
oBeam – Returns true if the light is a beam light.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
-
virtual RED_RC IsAmbientLight(bool &oAmbient, int iStateNumber = -1) const = 0
Is the light an ambient light?
See also \ref wf_deferred_shading.
- Parameters
oAmbient – Returns true if the light is an ambient light.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
-
virtual RED_RC IsSkyLight(bool &oSky, bool &oHemispherical, int iStateNumber = -1) const = 0
Is the light a skylight?
- Parameters
oSky – Returns true if the light is a skylight.
oHemispherical – Returns true if the skylight is hemispherical.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
-
virtual RED_RC IsSunLight(bool &oSun, int iStateNumber = -1) const = 0
Is the light a sunlight?
- Parameters
oSun – Returns true if the light is a sunlight.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
-
virtual RED_RC IsMoonLight(bool &oMoon, int iStateNumber = -1) const = 0
Is the light a moonlight?
- Parameters
oMoon – Returns true if the light is a moonlight.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
-
virtual RED_RC IsPhysicalLight(bool &oPhysical, int iStateNumber = -1) const = 0
Is the light a physical one?
- Parameters
oPhysical – Returns true if the light is a physical light.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
-
virtual RED_RC SetLayerSetLit(const RED::LayerSet &iLitLayerSet, const RED::State &iState) = 0
Defines the layer set identifying the light receivers.
All objects in the light’s area are lit by default. If a layerset is specified with this method, only shapes that have a layer set that intersects iLitLayerSet will be lit.
Please refer to \ref bk_sg_layersets and \ref bk_sg_light_layersets for details on RED::LayerSet setup for a light source.
- Parameters
iLitLayerSet – The lighting layer set for that light.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC GetLayerSetLit(RED::LayerSet &oLayerSet, int iStateNumber = -1) const = 0
Returns the layer set identifying light receivers.
Please refer to \ref bk_sg_layersets and \ref bk_sg_light_layersets for details on RED::LayerSet setup for a light source.
- Parameters
oLayerSet – The layerset that must be intersected by a shape to be lit.
iStateNumber – Queried state number.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters.
-
virtual RED_RC SetLayerSetShadowCaster(const RED::LayerSet &iShadowCasterLayerSet, const RED::State &iState) = 0
Defines the layer set identifying shadow casters.
All objects in the light’s area are shadow casters for that light by default. If a layerset is specified with this method, only shapes that have a layer set that intersects iShadowCasterLayerSet will be set as shadow casters.
Please refer to \ref bk_sg_layersets and \ref bk_sg_light_layersets for details on RED::LayerSet setup for a light source.
- Parameters
iShadowCasterLayerSet – The shadow casting layer set for that light.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC GetLayerSetShadowCaster(RED::LayerSet &oLayerSet, int iStateNumber = -1) const = 0
Returns the layerset identifying shadow casters.
Please refer to \ref bk_sg_layersets and \ref bk_sg_light_layersets for details on RED::LayerSet setup for a light source.
- Parameters
oLayerSet – The layerset that must be intersected by a shape to be considered as a shadow emitter.
iStateNumber – Queried state number.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters.
-
virtual RED_RC SetLayerSetShadowReceiver(const RED::LayerSet &iShadowReceiverLayerSet, const RED::State &iState) = 0
Defines the layer set identifying shadow receivers.
All objects in the light’s area are shadow receivers for that light by default. If a layerset is specified with this method, only shapes that have a layer set that intersects iLitLayerSet will be set as shadow receivers.
Please refer to \ref bk_sg_layersets and \ref bk_sg_light_layersets for details on RED::LayerSet setup for a light source.
- Parameters
iShadowReceiverLayerSet – The shadow receivers layer set for that light.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC GetLayerSetShadowReceiver(RED::LayerSet &oLayerSet, int iStateNumber = -1) const = 0
Returns the layerset identifying shadow receivers.
Please refer to \ref bk_sg_layersets and \ref bk_sg_light_layersets for details on RED::LayerSet setup for a light source.
- Parameters
oLayerSet – The layerset that must be intersected by a shape to be considered as a shadow receiver.
iStateNumber – Queried state number.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters.
-
virtual RED_RC GetAttenuation(RED::ATTENUATION &oAttenuation, int iStateNumber = -1) const = 0
Gets the attenuation mode.
See the section \ref bk_sg_decay_equations to learn about the various attenuation modes and settings.
See also \ref wf_custom_software_shader.
- Parameters
oAttenuation – The attenuation mode.
iStateNumber – Queried state number.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters.
-
virtual RED_RC GetAttenuationParameters(const float *&oParameters, int iStateNumber = -1) const = 0
Gets the attenuation parameters.
See the section \ref bk_sg_decay_equations to learn about the various attenuation modes and settings.
- Parameters
oParameters – A pointer to the attenuation user parameters.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC SetAttenuation(ATTENUATION iAtt, float iAttValue[7], const RED::State &iState) = 0
Sets the light source attenuation.
See the section \ref bk_sg_decay_equations to learn about the various attenuation modes and settings.
For sun and sky lights, please go through the respective creation methods to modify their attenuation. This will ensure that the physically-sased sky model keeps correct.
- Parameters
iAtt – Attenuation of the light source.
iAttValue – Attenuation parameters.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC GetRenderMode(int &oValue, RENDER_MODE iMode, int iStateNumber = -1) const = 0
Returns the value of the given render mode.
- Parameters
iMode – Render mode of interest.
oValue – Value of the given render mode.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC SetRenderMode(RENDER_MODE iMode, int iValue, const RED::State &iState) = 0
Sets the value of the given render mode.
- Parameters
iMode – Render mode to modify.
iState – Current transaction.
iValue – Value to set.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC GetPos(RED::Vector3 &oPos, int iStateNumber = -1) const = 0
Returns the position of the light.
See also \ref wf_deferred_shading.
- Parameters
oPos – The position of the light.
iStateNumber – Queried state number.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters.
-
virtual RED_RC SetPos(const RED::Vector3 &iLightPos, const RED::State &iState) = 0
Sets the position of the light.
See also \ref wf_hello_world.
- Parameters
iLightPos – The new light position.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC GetSight(RED::Vector3 &oSight, int iStateNumber = -1) const = 0
Returns the sight vector of the light.
See also \ref wf_hello_world.
- Parameters
oSight – The sight vector of the light.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC SetSight(const RED::Vector3 &iSight, const RED::State &iState) = 0
Sets the sight vector of the light.
See also \ref wf_hello_world.
- Parameters
iSight – The new light sight vector.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC GetTop(RED::Vector3 &oTop, int iStateNumber = -1) const = 0
Returns the top vector of the light.
See also \ref wf_hello_world.
- Parameters
oTop – The top vector of the light.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC SetTop(const RED::Vector3 &iTop, const RED::State &iState) = 0
Sets the top vector of the light.
See also \ref wf_hello_world.
- Parameters
iTop – New top vector of the light.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC GetRight(RED::Vector3 &oRight, int iStateNumber = -1) const = 0
Returns the right vector of the light.
See also \ref wf_hello_world.
- Parameters
oRight – The right vector of the light.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC SetRight(const RED::Vector3 &iRight, const RED::State &iState) = 0
Sets the right vector of the light.
See also \ref wf_hello_world.
- Parameters
iRight – The new right vector of the light.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC GetSpotAngle(float &oAngle, int iStateNumber = -1) const = 0
Returns the angle of a spot light.
For a lit point P, light source center position L, the angle between LP and the light source sight vector defines the area in which P receives the full intensity from the light source.
See \ref tk_setup_a_spot_light for details on spot light setup.
See also \ref wf_deferred_shading.
- Parameters
oAngle – The angle of a spot light.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC SetSpotAngle(float iAngle, const RED::State &iState) = 0
Defines the angle of a spot light.
For a lit point P, light source center position L, the angle between LP and the light source sight vector defines the area in which P receives the full intensity from the light source.
See \ref tk_setup_a_spot_light for details on spot light setup.
- Parameters
iAngle – The new spot angle.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC GetSpotFallOff(float &oFallOff, int iStateNumber = -1) const = 0
Returns the fall off angle of a spot light.
For a lit point P, light source center position L, the falloff angle is the extra angle beyond the spot angle in which the light source intensity is linearly interpolated between the full light’s intensity and zero.
See \ref tk_setup_a_spot_light for details on spot light setup.
See also \ref wf_deferred_shading.
- Parameters
oFallOff – The fall off angle of a spot light.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC SetSpotFallOff(float iFallOff, const RED::State &iState) = 0
Defines the new fall of a spot.
For a lit point P, light source center position L, the falloff angle is the extra angle beyond the spot angle in which the light source intensity is linearly interpolated between the full light’s intensity and zero.
See \ref tk_setup_a_spot_light for details on spot light setup.
- Parameters
iFallOff – The new falloff angle for the spot.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC GetSpotDropOff(float &oDropOff, int iStateNumber = -1) const = 0
Returns the drop off value of a spot light.
The dropoff value defines the intensity rule inside the light’s full intensity area (for lighting angles below the spot’s lighting angle). The intensity is pow(cos(angle),dropoff), where angle is the angle between LP (P lit point, L light source position) and the light source sight vector.
See \ref tk_setup_a_spot_light for details on spot light setup.
- Parameters
oDropOff – The drop off value of a spot light.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC SetSpotDropOff(float iDropOff, const RED::State &iState) = 0
Defines the new dropoff value of a spot.
The dropoff value defines the intensity rule inside the light’s full intensity area (for lighting angles below the spot’s lighting angle). The intensity is pow(cos(angle),dropoff), where angle is the angle between LP (P lit point, L light source position) and the light source sight vector.
See \ref tk_setup_a_spot_light for details on spot light setup.
- Parameters
iDropOff – The dropoff value of a spot.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC GetBeamInnerRadius(float &oInnerRadius, int iStateNumber = -1) const = 0
Returns the inner radius of a beam light.
The beam inner radius defines the circular distance from the light’s source sight vector axis below which a lit point receives the full intensity of the light.
Please see the \ref tk_setup_a_beam_light for details on how to setup a beam light.
- Parameters
oInnerRadius – The inner radius of a beam light.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC SetBeamInnerRadius(float iBeamInRad, const RED::State &iState) = 0
Modifies the inner radius of a beam light.
The beam inner radius defines the circular distance from the light’s source sight vector axis below which a lit point receives the full intensity of the light.
Please see the \ref tk_setup_a_beam_light for details on how to setup a beam light.
- Parameters
iBeamInRad – The new inner radius value for the beam.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC GetBeamOuterRadius(float &oOuterRadius, int iStateNumber = -1) const = 0
Returns the outer radius of a beam light.
The beam inner radius defines the circular distance from the light’s source sight vector axis above which a lit point receives no lighting intensity from the light. Between the inner and outer radius, the light’s emitted intensity is linearly interpolated.
Please see the \ref tk_setup_a_beam_light for details on how to setup a beam light.
- Parameters
oOuterRadius – The outer radius of a beam light.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC SetBeamOuterRadius(float iBeamOutRad, const RED::State &iState) = 0
Modifies the outer radius of a beam light.
The beam inner radius defines the circular distance from the light’s source sight vector axis above which a lit point receives no lighting intensity from the light. Between the inner and outer radius, the light’s emitted intensity is linearly interpolated.
Please see the \ref tk_setup_a_beam_light for details on how to setup a beam light.
- Parameters
iBeamOutRad – The new outer radius value for the beam.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC GetDiffuseIntensity(RED::Color &oDiffuse, int iStateNumber = -1) const = 0
Returns the diffuse intensity of the light.
See also \ref wf_deferred_shading.
- Parameters
oDiffuse – The diffuse intensity of the light.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC SetDiffuseIntensity(const RED::Color &iDiffuse, const RED::State &iState) = 0
Defines the new light’s diffuse intensity.
See also \ref wf_deferred_shading.
- Parameters
iDiffuse – The new diffuse intensity value.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC GetSpecularIntensity(RED::Color &oSpecular, int iStateNumber = -1) const = 0
Returns the specular intensity of the light.
See also \ref wf_cartoon_shading.
- Parameters
oSpecular – The specular intensity of the light.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC SetSpecularIntensity(const RED::Color &iSpecular, const RED::State &iState) = 0
Defines the new light’s specular intensity.
- Parameters
iSpecular – The new specular intensity value.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC GetSamplesCount(unsigned int &oSamplesCount, int iStateNumber = -1) const = 0
Gets the number of samples in a rectangular area light.
Defines the number of samples used to render a rectangular area light. This number only affects the CPU rendering of the light.
See \ref tk_setup_a_rectangular_area_light for details on the setup of a rectangular area light.
- Parameters
oSamplesCount – The number of samples in the light.
iStateNumber – Queried state number.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters.
-
virtual RED_RC SetSamplesCount(unsigned int iSamplesCount, const RED::State &iState) = 0
Changes the number of samples used to render a rectangular area light.
Changes the number of samples in a rectangular area light.
- Parameters
iSamplesCount – The new number of samples. Must be greater than zero.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC GetRectangularAreaLightShape(float oDimensions[2], int iStateNumber = -1) const = 0
Gets the shape of a rectangular area light.
The dimensions of the light are returned in oDimensions with: oDimensions[0] = width and oDimensions[1] = height.
See \ref tk_setup_a_rectangular_area_light for details on the setup of a rectangular area light.
- Parameters
oDimensions – 2 floats to store the dimensions of the rectangular area light.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
-
virtual RED_RC SetRectangularAreaLightShape(const float iDimensions[2], const RED::State &iState) = 0
Sets the shape of a rectangular area light.
The width of the light must be in oDimensions[0] and the height in oDimensions[1]. Refer to RED::ILightShape::SetRectangularAreaLight for all details on a rectangular area light geometry.
See \ref tk_setup_a_rectangular_area_light for details on the setup of a rectangular area light.
- Parameters
iDimensions – 2 floats which define the dimensions of the rectangular area light.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC GetEffectDistance(float &oEffectDistance, int iStateNumber = -1) const = 0
Calculates the effect distance of a light source.
Most lights have an infinite effect distance. However, for performance reasons, we consider that a light becomes ineffective when its intensity is below a given threshold defined by the value of RED::OPTIONS_LIGHT_CUTOFF. The oEffectDistance of the light is the distance at which the light’s intensity has dropped below the threshold.
See \ref bk_sg_decay_equations for details on light attenuation and effect distances.
See also \ref wf_deferred_shading.
- Parameters
oEffectDistance – The effect distance of the light.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC GetBeamProjectorMatrix(RED::Matrix &oMatrix, int iStateNumber = -1) const = 0
Gets to the UV projector matrix of a beam light.
The matrix is updated each time it’s accessed. This matrix can be used to compute the UV coordinates of a point into the beam shadow map by multiplying the returned homogeneous matrix by the point’s coordinates. Resulting UVs can be used to query the shadow map.
- Parameters
oMatrix – The projector matrix of the beam.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC SetShadowMapping(bool iOnOff, const RED::State &iState) = 0
Enables or disables shadow mapping for this light.
When shadow mapping is enabled, this method also turns on shadow casting for the light. However, when shadow mapping is disabled, shadow casting is not disarmed.
Use the RED::ILightShape::SetRenderMode method to control the shadow casting properties of the light.
See also \ref wf_hello_world.
- Parameters
iOnOff – Enable / Disable.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC GetShadowMapping(bool &oShadowMap, int iStateNumber = -1) const = 0
Gets the shadow mapping status for this light.
- Parameters
oShadowMap – Returned to true if shadow maps are used for this light.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC SetShadowMapResolution(int iShadowMapRes, const RED::State &iState) = 0
Defines the resolution of the shadow map for that light.
This resolution will be used per face for a point light using shadow maps.
See also \ref wf_hello_world.
- Parameters
iShadowMapRes – Pixel resolution of the shadow map.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC GetShadowMapResolution(int &oShadowMapRes, int iStateNumber = -1) const = 0
Returns the resolution used for shadow maps.
The default shadow map resolution is 512 x 512 pixels per map.
- Parameters
oShadowMapRes – Pixel resolution of the shadow map.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC SetShadowMapPolygonOffset(float iPolygonOffsetFactor, float iPolygonOffsetUnits, const RED::State &iState) = 0
Bias the shadow map to avoid shadowing artifacts.
Shadow maps are generated using a depth offset to avoid the detection of false self shadows. Default factor is 2.0f. Default units are 1.0f.
See also \ref bk_improving_cad_graphics.
- Parameters
iPolygonOffsetFactor – Factor for the polygon offset equation.
iPolygonOffsetUnits – Units for the polygon offset equation.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC GetShadowMapPolygonOffset(float &oPolygonOffsetFactor, float &oPolygonOffsetUnits, int iStateNumber = -1) const = 0
Gets the biasing parameters for the light.
See also \ref bk_improving_cad_graphics.
- Parameters
oPolygonOffsetFactor – Factor for the polygon offset equation.
oPolygonOffsetUnits – Units for the polygon offset equation.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC SetShadowMapSides(bool iSingleMap, int iFaceMaps, const RED::State &iState) = 0
Defines the maps to use for a light.
Specify whether we are going to use one shadow map for the shadow casting of a spot or the 6 faces of a cube instead. This has an impact on the accuracy of the result. Default is to use one single map if we are a spot. If we are a point light, we use the 6 faces of a cube all the times.
This can be used to reduce the burden of the rendering for directions that are worthless for shadow emission. Default is to enable all sides if we don’t use a single map.
- Parameters
iSingleMap – true to use one single shadow map for the spot shadows.
iFaceMaps – A bitwise combination of the faces to use: +X = 1, -X = 2, +Y = 4, -Y = 8, +Z = 16, -Z = 32.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC GetShadowMapSides(bool &oSingleMap, int &oFaceMaps, int iStateNumber = -1) const = 0
Gets the shadow maps in use for a light.
- Parameters
oSingleMap – Returned true if we use one single shadow map for spot shadows.
oFaceMaps – A bitwise combination of the faces in use: +X = 1, -X = 2, +Y = 4, -Y = 8, +Z = 16, -Z = 32.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC SetShadowMapBlur(int iBlurSize, const RED::State &iState) = 0
Sets a built-in gaussian blur filter on shadow maps.
This method setup a blur effect that can be added during the generation of a shadow map based image. The blur reduces the ‘stair steps’ artifacts that are usually produced by shadow mapping techniques.
The shadow mapping blur is supported by both the GPU and CPU rendering models of REDsdk.
The specified value is the size of the “blurring kernel” used for the production of the blur effect. The diameter of the blur effect is then the size of the kernel minus one.
The default blur size is one, indicating no blur, but a bilinear filtering of the shadow map. Several graphic cards do not support blur values above a certain diameter. If iBlurSize is above the maximal hardware capabilities, then it’s silently clamped to an acceptable range.
Maximal hardware blur values (inclusive) per chipset category:
ATI R300
1
ATI R400
3
ATI R500
5
ATI R600
14
Any NVIDIA
20
Software
no limit
- Parameters
iBlurSize – Define the size of the gaussian blur kernel. iBlurSize must be greater than or equal to 0.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC GetShadowMapBlur(int &oBlurSize, int iStateNumber = -1) const = 0
Gets the current blur filter for shadow maps.
- Parameters
oBlurSize – Current value of the gaussian blur kernel.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC SetShadowMapFiltering(bool iOnOff, const RED::State &iState) = 0
Enables/disables bilinear texture filtering for the shadow map.
Default setting is to enable bilinear texture filtering while sampling a shadow map. This method enables or disables bilinear texture filtering for the shadow map. Effects of the shadow map filtering vary with the underlying GPU:
NVIDIA GPUs: Disabling bilinear filtering cause ‘stair steps’ artifacts to be visible on the shadow map, and this is visible for any shadow map blur kernel size.
ATI GPUs: Disabling bilinear filtering is only effective for blur size 0 or 1. Shadow map filtering is only an approximated bilinear filter on R300, R400 and R500 chipsets. Shadow map filtering is ignored on these chipsets for a gaussian blur kernel size above 1.
- Parameters
iOnOff – Enable or disable bilinear shadow map filtering.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC IsShadowMapFiltering(bool &oOnOff, int iStateNumber = -1) const = 0
Queries the shadow map texture filtering mode.
See RED::ILightShape::SetShadowMapFiltering for all details on the effect of the filtering on the shadow map.
- Parameters
oOnOff – Returns true if the shadow map bilinear filtering is enabled, false otherwise.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC SetShadowMapCustomRange(float iDNear, float iDFar, const RED::State &iState) = 0
Defines the near and far effect distances of the shadow map.
The engine automatically sets the near / far distances to use for a shadow map. However, this may not be optimal for some scenes for which an applicative knowledge may easily lead to the best values.
This method can be used to force these near / far shadow casting distances to the specified values, given in model units.
See also \ref bk_improving_cad_graphics.
- Parameters
iDNear – Near distance to use.
iDFar – Far distance to use.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC SetShadowMapAutoRange(bool iOnOff, const RED::State &iState) = 0
Lets the engine automatically compute shadow map near / far.
This is the engine default setting: it automatically calculates the near / far effect range of the shadow maps used for the light. Please note that the shadow map auto-range calculation method only works if the scene has bounding spheres in it.
Note that due to the limited accuracy of shadow maps, there may be no solution to properly see shadows on all the parts of a given model. In this case, setting up custom shadow map near / far values may be an alternative to auto range shadow mapping, or using another more robust shadowing technique may be considered.
See RED::ILightShape::SetShadowMapCustomRange for details.
See \ref bk_re_shadow_mapping_detailed for details on the shadow mapping process.
- Parameters
iOnOff – Enable or disable auto near / far calculation.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC GetShadowMapCustomRange(float &oDNear, float &oDFar, int iStateNumber = -1) const = 0
Retrieves near/far custom shadow map range values.
If the shadow map is in automatic mode, these return values are undefined unless they have been defined before.
See \ref bk_re_shadow_mapping_detailed for details on the shadow mapping process.
- Parameters
oDNear – Near shadow map effect distance.
oDFar – Far shadow map effect distance.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_FAIL otherwise.
-
virtual RED_RC IsShadowMapAutoRange(bool &oAuto, int iStateNumber = -1) const = 0
Gets the shadow map near / far calculation mode.
See \ref bk_re_shadow_mapping_detailed for details on the shadow mapping process.
- Parameters
oAuto – true if the shadow map near / far are automatically computed, false otherwise.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_FAIL otherwise.
-
virtual RED_RC SetShadowMapSpotAngle(float iAngle, const RED::State &iState) = 0
Defines the shadow map area in a spot.
It may we wishful to concentrate the effect of a shadow map in a reduced area of a spotlight. Setting up a shadow map spot angle will cause the shadow map effect area to be reduced to a cone defined using this angle.
This helps improving performances while locally increasing the shadow map resolution. By default the shadow map spot angle is set to the light source spot angle.
See \ref bk_re_shadow_mapping_detailed for details on the shadow mapping process.
- Parameters
iAngle – New shadow map spot angle (radians). If the provided value is above the light’s spot angle, then the shadow map will use the spot angle as effect area limit. The supplied angle must be greater than 0.0f and lower than RED_PI.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC GetShadowMapSpotAngle(float &oAngle, int iStateNumber = -1) const = 0
Gets the shadow map effect cone in a spot.
The call returns the current angle used to calculate the shadow map in a spot.
See \ref bk_re_shadow_mapping_detailed for details on the shadow mapping process.
- Parameters
oAngle – Current angular value in radians. Is returned to the spot angle if no value has been specified.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_FAIL otherwise.
-
virtual RED_RC SetShadowMapBeamRadius(float iRadius, const RED::State &iState) = 0
Defines the shadow map area in a beam.
It may we wishful to concentrate the effect of a shadow map in a reduced area of a beamlight. Setting up a shadow map radius will cause the shadow map effect area to be reduced to a cylinder defined using this radius.
This helps improving performances while locally increasing the shadow map resolution. By default the shadow map beam radius is set to the light source beam outer radius.
See \ref bk_re_shadow_mapping_detailed for details on the shadow mapping process.
- Parameters
iRadius – New shadow map beam radius. If the provided value is above the light’s beam outer radius, then the shadow map will use the beam outer radius as effect area limit.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received invalid parameters,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC GetShadowMapBeamRadius(float &oRadius, int iStateNumber = -1) const = 0
Gets the shadow map effect radius in a beam.
The call returns the current radius used to calculate the shadow map in a beam.
See \ref bk_re_shadow_mapping_detailed for details on the shadow mapping process.
- Parameters
oRadius – Current shadow map effect radius. Is returned to the beam radius if no value has been specified.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_FAIL otherwise.
-
virtual RED_RC SetShadowMapDirectAccess(bool iOnOff, const RED::State &iState) = 0
Enables or disables the direct shadow map access.
The default engine rendering workflow let a shader access to the RED::RenderShaderParameter::REF_SHADOW_MAP_TEX reference image that contains the per-pixel shadowing information to use for the image. It may be needed
mainly for performance reasons - to get a direct access to the shadow map.
The shadow map is a floating value texture, set for projective texturing on NVIDIA GPUs, not set for projective texturing on ATI or INTEL GPUs. It contains the depth of the closest occluding fragment visible from the light’s frustum.
Enabling the direct shadow map access invalidates any access to the REF_SHADOW_IMAGE_TEX reference, which is not calculated anymore. Any shader still using this reference will render incorrectly. The RED::RenderShaderParameter::REF_SHADOW_MAP_TEX and the RED::RenderShaderParameter::REF_SHADOW_MAP_FRUSTUM_MATX references can be used to directly do the shadow mapping operation in a custom shader.
Usage of this method is only valid for beam and spot lights. By default the shadow map direct access is disabled.
See \ref bk_re_shadow_mapping_detailed for details on the shadow mapping process.
- Parameters
iOnOff – Enable or disable direct shadow map access.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred or if the light is not of the appropriate kind,
RED_FAIL otherwise.
-
virtual RED_RC IsShadowMapDirectAccess(bool &oOnOff, int iStateNumber = -1) const = 0
Queries the shadow map access mode.
See \ref bk_re_shadow_mapping_detailed for details on the shadow mapping process.
- Parameters
oOnOff – Returns true if the shadow map direct access mode is authorized for this light source.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_FAIL otherwise.
-
virtual RED_RC GetShadowColor(RED::Color &oColor, int iStateNumber = -1) const = 0
Gets the current shadow color of the light source.
Return the current shadow color of the light source. The default shadow color is BLACK.
- Parameters
oColor – The shadow color.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_BAD_PARAM if iStateNumber is invalid,
RED_FAIL otherwise.
-
virtual RED_RC SetShadowColor(const RED::Color &iColor, const RED::State &iState) = 0
Sets the shadow color of the light source.
The shadow color is used for both shadow mapping and ray-traced shadows. This color replaces the black default shadow color used otherwise.
- Parameters
iColor – The new shadow color.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC GetShadowBias(double &oBias, int iStateNumber = -1) const = 0
Returns the shadow bias value for the light source.
The shadow bias is an offset value expressed in model units that helps filtering incorrect self shadowing artifacts that may arise when the source of the shadow is too close to the shaded surface. The shadow bias is applied to the point hit by a ray to move it away from the surface that has been hit:
The shadow bias is applied only to ray-traced shadows. Biasing with shadow maps can be queried through RED::ILightShape::GetShadowMapPolygonOffset.
- Parameters
oBias – The actual shadow bias for the light.
iStateNumber – Queried state number.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if iStateNumber is invalid,
RED_FAIL otherwise.
-
virtual RED_RC SetShadowBias(double iBias, const RED::State &iState) = 0
Sets the shadow bias for the light source.
The shadow bias is an offset value expressed in model units that helps filtering incorrect self shadowing artifacts that may arise when the source of the shadow is too close to the shaded surface. The shadow bias is applied to the point hit by a ray to move it away from the surface that has been hit.
The shadow bias is applied only to ray-traced shadows. Biasing with shadow maps can be performed through RED::ILightShape::SetShadowMapPolygonOffset.
- Parameters
iBias – The shadow bias to set for the light source. This value can’t be negative.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
-
virtual RED_RC CopyFrom(const RED::Object &iLight, const RED::State &iState, int iSrcStateNumber = -1) = 0
Copies the content of a RED::ILightShape instance to the current object.
This method will work for only two instances of the same concrete class.
- Parameters
iLight – Reference to the object to copy from.
iState – Current transaction.
iSrcStateNumber – State from which the source light must be copied.
- Returns
RED_OK on success,
RED_BAD_PARAM if iLight and ‘this’ are from different classes, or if iSrcStateNumber is invalid,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL for any other error.
