class RED::ISkyLightShape
This interface gives access to the creation and edition of sky, sun and moon lights. More...
#include <REDISkyLightShape.h>Inherits: IREDObject.
Public functions:
| virtual RED_RC | AddClouds ( int & oLayerIndex, double iAltitude, double iDensity, double iIntensity, double iOpacity, RED::CLOUDS_TYPE iCloudsType, unsigned int iRandomSeed, const RED::State & iState ) = 0 |
| virtual RED_RC | ClearClouds ( const RED::State & iState ) = 0 |
| virtual RED_RC | ComputeMoonDirection ( RED::Vector3 & oMoonDir, const struct tm & iDate, double iLatitude, double iLongitude, double iHeight ) const = 0 |
| virtual RED_RC | ComputeSunDirection ( RED::Vector3 & oSunDir, const struct tm & iDate, double iLatitude, double iLongitude, double iHeight ) const = 0 |
| virtual RED_RC | CreatePhysicalSkyTexture ( RED::Object *& oTexture, bool iComposite, unsigned int iWidth, bool iHemispherical, bool iIncludeSun, bool iIncludeClouds, const RED::State & iState ) = 0 |
| virtual RED_RC | CreatePhysicalSkyTextureLegacy ( RED::Object *& oTexture, int iWidth, bool iHemispherical, const RED::Vector3 & iSunDir, bool iIncludeSun, unsigned int iTurbidity, float iAlbedo, float iScale, float iSaturation, const RED::State & iState ) = 0 |
| virtual RED_RC | GetBackgroundMatrixFromSky ( RED::Matrix & oBackgroundMatrix, const RED::Vector3 & iDir, const RED::Vector3 & iTop ) = 0 |
| virtual RED_RC | GetCustomModel ( RED::Vector3 & oSunDir, double & oSunRadiusScale, RED::Color & oSunIntensity, RED::Vector3 & oMoonDir, double & oMoonRadiusScale, RED::Color & oMoonIntensity, int iStateNumber = -1 ) = 0 |
| virtual RED_RC | GetPhysicalModel ( double & oSceneScale, double & oViewHeight, double & oSkyMult, unsigned int & oTurbidity, RED::Color & oAlbedo, double & oAerosolsAlbedo, double & oAsymmetryFactor, RED::Vector3 & oSunDir, double & oSunRadiusScale, double & oSunIntensityMultiplier, RED::Vector3 & oMoonDir, double & oMoonRadiusScale, double & oMoonIntensityMultiplier, double & oStarsIntensityMultiplier, double & oSaturation, int iStateNumber = -1 ) = 0 |
| virtual RED_RC | GetPortals ( RED::Vector< RED::Object * > & oPortals, int iStateNumber = -1 ) const = 0 |
| virtual RED_RC | GetSamplesCount ( unsigned int & oSamplesCount, int iStateNumber = -1 ) const = 0 |
| virtual RED_RC | GetSkyTexture ( RED::Object *& oTexture, int iStateNumber = -1 ) const = 0 |
| virtual RED_RC | IsCustomModel ( bool & oIsCustom, int iStateNumber = -1 ) const = 0 |
| virtual RED_RC | IsEmissiveSky ( bool & oEmissive, int iStateNumber = -1 ) const = 0 |
| virtual RED_RC | IsPhysicalModel ( bool & oIsPhysical, int iStateNumber = -1 ) const = 0 |
| virtual RED_RC | SetCustomModel ( const RED::Vector3 & iSunDir, double iSunRadiusScale, const RED::Color & iSunIntensity, const RED::Vector3 & iMoonDir, double iMoonRadiusScale, const RED::Color & iMoonIntensity, const RED::State & iState ) = 0 |
| virtual RED_RC | SetEmissiveSky ( bool iEmissive, const RED::State & iState ) = 0 |
| virtual RED_RC | SetMoonLight ( RED::Object *& oMoonLight, const RED::State & iState ) = 0 |
| virtual RED_RC | SetPhysicalModel ( double iSceneScale, double iViewHeight, double iSkyMult, unsigned int iTurbidity, const RED::Color & iAlbedo, double iAerosolsAlbedo, double iAsymmetryFactor, const RED::Vector3 & iSunDir, double iSunRadiusScale, double iSunIntensityMultiplier, const RED::Vector3 & iMoonDir, double iMoonRadiusScale, double iMoonIntensityMultiplier, double iStarsIntensityMultiplier, double iSaturation, const RED::State & iState ) = 0 |
| virtual RED_RC | SetPortals ( const RED::Vector< RED::Object * > & iPortals, const RED::State & iState ) = 0 |
| virtual RED_RC | SetSamplesCount ( unsigned int iSamplesCount, const RED::State & iState ) = 0 |
| virtual RED_RC | SetSkyTexture ( const RED::Object * iTexture, bool iHemispherical, const RED::Vector3 & iDir, const RED::Vector3 & iTop, const RED::State & iState ) = 0 |
| virtual RED_RC | SetSunLight ( RED::Object *& oSunLight, const RED::State & iState ) = 0 |
| virtual RED_RC | UpdateClouds ( int iLayerIndex, double iAltitude, double iIntensity, double iOpacity, const RED::State & iState ) = 0 |
Public static functions:
| static RED::CID | GetClassID ( ) |
Detailed description:
This interface gives access to the creation and edition of sky, sun and moon lights.
The RED::ISkyLightShape interface is exposed by the CID_REDLightShape instances.
The sky light relies on a model defined by the user. The model can be either a physical model (RED::ISkyLightShape::SetPhysicalModel) or a custom one (RED::ISkyLightShape::SetCustomModel).
Note:
Defining a model for the sky is the first step in building a sky light.
In a custom model, the user is responsible for providing the texture for the environment light as well as positions and intensities for optional sun and moon light.
In a physical model, the environment texture is computed directly from user-supplied physical sky data using RED::ISkyLightShape::CreatePhysicalSkyTexture. Sun and moon positions can be computed using the RED::ISkyLightShape::ComputeSunDirection and the RED::ISkyLightShape::ComputeMoonDirection methods.
A RED physical skylight simumlates light coming from the sun and scattered by the atmosphere. It is setup using a texture which can be provided by the user or be the result of a physically accurate sky simulation (physical sky).
For a complete physically accurate skylight simulation, you should create the sky texture using the RED::ISkyLightShape::CreatePhysicalSkyTexture.
This light only simulates sun and moon light which is scattered, not direct lighting. To add the direct sun and moon light contributions, you also need to setup a sun and a moon light by calling RED::ISkyLightShape::SetSunLight and RED::ISkyLightShape::SetMoonLight. See Outdoor lighting for further details.
For consistent results, physical sky should be used in conjunction with physical lights. This will ensure that correct physical units are preserved amongst various light sources.
Physical sky, as well as other physical lights in RED, can produce high intensity images outside the displayable range. Don't forget to turn on tone mapping through the RED::PostProcess instance in the RED::IViewpoint used to render the scene, to convert your output image to the visible range. You can also choose to scale the sky light intensity in RED::ISkyLightShape::CreatePhysicalSkyTexture.
This interface also provides portals which guide sky light sampling. Portals are useful for interior scenes for example, where sky light is entering by small openings which are difficult to sample efficiently. By marking explicitely the openings using portals, the engine can render difficult situations at a much higher quality in less time.
The skylight can be set as a 'GI emissive only' light source using RED::ISkyLightShape::SetEmissiveSky. This can be a useful method to speed-up all rendering calculations. If the sky is set emissive, then the direct sampling of the skylight is discarded, and the sky contribution is considered in the global illumination signal.
For an in-depth explanation of the sky models, please have a look at Sky model.
Task: Setup a physical sky light
You need to start with the creation of a light instance using the generic REDsdk shape creation mechanism (Creating and destroying shapes).
In RED, the sky light works with an input (hemi-)spherical texture which describes the radiance coming from any direction around the centre of the scene. This texture can be any user-defined texture. However, the user who wants to guarantee physically-correct results would prefer to use a texture created using RED::ISkyLightShape::CreatePhysicalSkyTexture (see Creating a physical sky texture).
// "sun" is a pointer to a previously created RED light instance.
RED::ISkyLightShape* isky = sky->As< RED::ISkyLightShape >();
// "sky_tex" is a pointer to the input sky texture.
// "sky_tex_is_hemi" is a boolean indicating if the input texture is hemispherical or spherical.
RED::Vector3 dir = RED::Vector3::XAXIS;
RED::Vector3 top = RED::Vector3::ZAXIS;
RC_TEST( isky->SetSkyTexture( sky_tex, sky_tex_is_hemi, dir, top, iresmgr->GetState() ) );
The two given vectors let you define a transformation basis for the sky texture. Here the texture horizon is mapped along the x-axis (i.e texture coordinate u = 0 along x) while the texture zenith is mapped along the z-axis.
The sky light basis.
As for any other sampled light in REDsdk, the user can control the rendering quality of the sky by setting the number of samples to used:
// 1024 samples are used to evaluate the contribution of the sky during rendering.
RC_TEST( isky->SetSamplesCount( 1024, iresmgr->GetState() ) );
The sky light is by far the biggest source of light in your scene and the number of samples used to render it must be set accordingly. Hence, it's not unusual to set the sky number of samples to something as big as 2048 or even more!
The effect of increasing the sky light samples count: 16 samples on the left, 256 on the right.
Functions documentation
| public static RED::CID RED::ISkyLightShape::GetClassID | ( | ) |
| public virtual RED_RC RED::ISkyLightShape::AddClouds | ( | int & | oLayerIndex, |
| double | iAltitude, | ||
| double | iDensity, | ||
| double | iIntensity, | ||
| double | iOpacity, | ||
| RED::CLOUDS_TYPE | iCloudsType, | ||
| unsigned int | iRandomSeed, | ||
| const RED::State & | iState | ||
| ) | = 0 |
Adds a cloud layer in the sky.
This function must be called after a sky model had been defined (by using RED::ISkyLightShape::SetPhysicalModel for example).
The added clouds are visible in the texture created by RED::ISkyLightShape::CreatePhysicalSkyTexture.
Multiple clouds layers can be added to the sky by calling this function multiple time.
The iRandomSeed parameter allows to initialize the random function used to generate the clouds shape.
Parameters:
| oLayerIndex: | returned layer index. |
| iAltitude: | clouds layer altitude. |
| iDensity: | overall clouds density. |
| iIntensity: | clouds intensity factor. |
| iOpacity: | opacity of the whole clouds layer. |
| iCloudsType: | clouds layer type. |
| iRandomSeed: | random seed initializer. |
| iState: | current transaction. |
Returns:
RED_BAD_PARAM if the method has received invalid parameters,
RED_FAIL otherwise.
| public virtual RED_RC RED::ISkyLightShape::ClearClouds | ( | const RED::State & | iState | ) = 0 |
| public virtual RED_RC RED::ISkyLightShape::ComputeMoonDirection | ( | RED::Vector3 & | oMoonDir, |
| const struct tm & | iDate, | ||
| double | iLatitude, | ||
| double | iLongitude, | ||
| double | iHeight | ||
| ) | const = 0 |
Computes the unit direction to the moon according to given date, time and location information.
Computes the exact direction towards the moon (unit vector from the earth) according to date, time and location on the earth surface, expressed in standard units.
Parameters:
| oMoonDir | returned unit direction to the moon. |
| iDate | date at which moon direction should be calculated (must be UTC/GMT time). |
| iLatitude | latitude of the position on earth's surface in degrees (in [0, 90]). |
| iLongitude | longitude of the position on earth's surface in degrees (in [-180, +180]). |
| iHeight | height of the observer in meters. |
Returns:
| public virtual RED_RC RED::ISkyLightShape::ComputeSunDirection | ( | RED::Vector3 & | oSunDir, |
| const struct tm & | iDate, | ||
| double | iLatitude, | ||
| double | iLongitude, | ||
| double | iHeight | ||
| ) | const = 0 |
Computes the unit direction to the sun according to given date, time and observer's location.
Computes the exact direction towards the sun (unit vector from the earth) according to date, time and location on the earth surface, expressed in standard units.
Parameters:
| oSunDir | returned unit direction to the sun. |
| iDate | date at which sun direction should be calculated (must be UTC/GMT time). |
| iLatitude | latitude of the observer on earth's surface in degrees (in [-90, +90]). |
| iLongitude | longitude of the observer on earth's surface in degrees (in [-180, +180]); West is considered positive. |
| iHeight | height of the observer in meters. |
Returns:
| public virtual RED_RC RED::ISkyLightShape::CreatePhysicalSkyTexture | ( | RED::Object *& | oTexture, |
| bool | iComposite, | ||
| unsigned int | iWidth, | ||
| bool | iHemispherical, | ||
| bool | iIncludeSun, | ||
| bool | iIncludeClouds, | ||
| const RED::State & | iState | ||
| ) | = 0 |
Creates a composite or a HDR texture of the sky model.
By providing a few physical sky parameters, one can create HDR or composite textures of the corresponding sky radiance using that method. Those textures can then be used as background texture (for VRLs), skylight texture (as source of illumination) or in your own software UI for feedback.
For explanations about the model used to simulate the sky, please read Sky model.
If the returned texture is intended to be used as a skylight texture, it is better to render it at a low resolution (about 512 in width). This will keep the sampling noise level as low as possible. The texture should be set as not composite (iComposite to false) and should not include the sun (iIncludeSun set to false) to avoid high frequency intensity spikes caused by the sun.
If the returned texture is intended to be used as a background texture, it is better to render it at a high resolution to avoid filtering artifacts with iComposite set to false (see RED::IViewpointRenderList::SetBackgroundImages to setup a background image). Even better is to use the composite mode (iComposite to true). In that case, the texture is rendered upon request during the rendering at the exact same resolution as the output image. As a consequence, the texture pixels are not available as the texture never exists in memory.
Note:
Composite sky textures are not supported by the GPU.
If iComposite is false, the height of the output texture is automatically determined from the user-defined width and the value of the iHemispherical flag:
if iHemispherical == true
height = width / 4
else
height = width / 2
In the case of a spherical texture, pixels below the horizon are clamped to the horizon pixels.
The method assumes that the up vector of the sky is aligned along the Z axis.
The returned texture becomes the property of the caller and should be deleted by it.
If iComposite is set to true, the ouput texture supports only software rendering and will be rendered as black if rendered using graphics hardware. This is because there is currently no support for the physical sky model on the GPU.
In order for clouds to appear in the texture, the RED::ISkyLightShape::AddClouds function must be called before this one and iIncludeClouds must be set to true.
Task: Creating a physical sky texture
Using REDsdk, you can create an instance of a physical sky:
RED::Object* sky = RED::Factory::CreateInstance( CID_REDLightShape );
RED::ISkyLightShape* isky = sky->As< RED::ISkyLightShape >();
and set up its model using:
RC_TEST( isky->SetPhysicalModel( 1.0, // scene scaling factor
1.0, // viewing height in meters,
1.0, // sky intensity multiplier
10, // turbidity
0.3, // ground albedo
0.8, // aerosols albedo
0.7, // aerosols asymmetry factor
RED::Vector3( 0.0, 0.0, 0.35 ), // direction to the sun
1.0, // sun scaling factor
1.0, // sun intensity multiplier
RED::Vector3( 0.0, 0.0, -0.35 ), // direction to the moon
1.0, // moon scaling factor
1.0, // moon intensity multiplier
1.0, // stars intensity multiplier
1.0, // sky color saturation factor
iresmgr->GetState() ) );
It's then easy to retrieve a spherical "picture" of that sky by calling:
RED::Object* sky_tex = NULL; // making this pointer NULL lets the method below to create the image instance for us.
RC_TEST( isky->CreatePhysicalSkyTexture( sky_tex, false, 512, false, false, true, iresmgr->GetState() ) );
Some physical sky textures at different times of the day.
Parameters:
| oTexture | pointer to the returned composite image (implements RED::IImage2D or RED::IImageComposite depending on the requested output format). If the pointer is NULL, a new image is created, otherwise a pointer to a valid image must be supplied. |
| iComposite | true to create a composite sky texture, false to create a 2D texture. |
| iWidth | width of the output texture (applies only if iComposite is false). |
| iHemispherical | true if the generated map should cover an hemisphere, false to cover the whole sphere (applies only if iComposite is false). |
| iIncludeSun | true to render the sun into the texture, false otherwise. |
| iIncludeClouds | true to render the clouds into the texture, false otherwise. |
| iState | current transaction. |
Returns:
RED_BAD_PARAM if the method has received invalid parameters,
RED_INIT_FAILED if we have no window created yet (a window must have been created before any texture operation can occur in the engine),
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
| public virtual RED_RC RED::ISkyLightShape::CreatePhysicalSkyTextureLegacy | ( | RED::Object *& | oTexture, |
| int | iWidth, | ||
| bool | iHemispherical, | ||
| const RED::Vector3 & | iSunDir, | ||
| bool | iIncludeSun, | ||
| unsigned int | iTurbidity, | ||
| float | iAlbedo, | ||
| float | iScale, | ||
| float | iSaturation, | ||
| const RED::State & | iState | ||
| ) | = 0 |
Legacy sky model texture creation method.
This method can be used to provide a legacy compatibility on the sky model for models that were created before REDsdk 4.2. This is the REDsdk 4.1 sky texture model construction method.
Parameters:
| oTexture: | pointer to the returned texture of the sky radiances as defined by the following physical parameters. If (*oTexture) is NULL, a new texture is created, otherwise the existing texture pixels are overwritten. |
| iWidth: | width of the output texture. |
| iHemispherical: | true if the generated map should cover an hemisphere, false to cover the whole sphere. |
| iSunDir: | sun direction, |
| iIncludeSun: | true to add the direct sun contribution to the texture, false otherwise (case of a very cloudy sky). |
| iTurbidity: | amount of molecules in the atmosphere (in [0, 100]). The higher, the more foggy. |
| iAlbedo: | amount of sun light reaching the ground which is reflected back to the sky (in [0, 1]). Default value of 0.1 is good. |
| iScale: | scale factor applied to each pixel in the texture. Set it to 1.0 to create a physically accurate texture of the sky. Lower values can be used to simulate the effect of clouds or environment on the sky intensity. |
| iSaturation: | saturation factor applied to each pixel in the texture. Set it to 1.0 to create a texture with vivid colors. Any other lower value will make the sky looking more gray and less colourful. The valid range of values is [0, 1]. be used to simulate the effect of clouds or environment on the sky intensity. |
| iState: | current transaction. |
Returns:
RED_BAD_PARAM if the method has received invalid parameters,
RED_INIT_FAILED if we have no window created yet (a window must have been created before any texture operation can occur in the engine),
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
| public virtual RED_RC RED::ISkyLightShape::GetBackgroundMatrixFromSky | ( | RED::Matrix & | oBackgroundMatrix, |
| const RED::Vector3 & | iDir, | ||
| const RED::Vector3 & | iTop | ||
| ) | = 0 |
Computes the matrix to apply to the cube background image in RED::IViewpointRenderList::SetBackgroundImages to match the sky texture setup.
Be sure to pass the same iDir and iTop vectors you passed to the RED::ISkyLightShape::SetSkyTexture method.
Parameters:
| oBackgroundMatrix | reference to the returned transformation matrix. |
| iDir: | First axis defining the orientation of the horizon. Sampling a direction parallel to iDir fall on the U = 0.0f edge of iTexture. |
| iTop: | Second axis defining the orientation of the skylight. indicates the direction of the zenith. Sampling a direction perpendicular to iTop fall on the V = 0.0f of iTexture. Sampling a direction parallel to iTop fall on the V = 1.0f of iTexture. |
Returns:
RED_BAD_PARAM if the method has received invalid parameters,
RED_FAIL otherwise.
| public virtual RED_RC RED::ISkyLightShape::GetCustomModel | ( | RED::Vector3 & | oSunDir, |
| double & | oSunRadiusScale, | ||
| RED::Color & | oSunIntensity, | ||
| RED::Vector3 & | oMoonDir, | ||
| double & | oMoonRadiusScale, | ||
| RED::Color & | oMoonIntensity, | ||
| int | iStateNumber = -1 | ||
| ) | = 0 |
Retrieves the custom sky model seetings.
Returns all the settings of a custom sky model. If no custom sky model has been set, this method returns RED_FAIL. You can check that a physical sky model has been set prior to calling that method with a call to RED::ISkyLightShape::IsCustomModel.
Parameters:
| oSunDir | unit direction towards the sun. |
| oSunRadiusScale | sun radius scaling. |
| oSunIntensity | RGB intensity of the sun. |
| oMoonDir | unit direction towards the moon. |
| oMoonRadiusScale | moon radius scaling. |
| oMoonIntensity | RGB intensity of the moon. |
| iStateNumber | queried state number. |
Returns:
RED_BAD_PARAM if the method has received invalid parameters,
RED_INIT_FAILED if we have no window created yet (a window must have been created before any texture operation can occur in the engine),
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
| public virtual RED_RC RED::ISkyLightShape::GetPhysicalModel | ( | double & | oSceneScale, |
| double & | oViewHeight, | ||
| double & | oSkyMult, | ||
| unsigned int & | oTurbidity, | ||
| RED::Color & | oAlbedo, | ||
| double & | oAerosolsAlbedo, | ||
| double & | oAsymmetryFactor, | ||
| RED::Vector3 & | oSunDir, | ||
| double & | oSunRadiusScale, | ||
| double & | oSunIntensityMultiplier, | ||
| RED::Vector3 & | oMoonDir, | ||
| double & | oMoonRadiusScale, | ||
| double & | oMoonIntensityMultiplier, | ||
| double & | oStarsIntensityMultiplier, | ||
| double & | oSaturation, | ||
| int | iStateNumber = -1 | ||
| ) | = 0 |
Retrieves the physical sky model settings.
Returns all the settings of a physical sky model. If no physical sky model has been set, this method returns RED_FAIL. You can check that a physical sky model has been set prior to calling that method with a call to RED::ISkyLightShape::IsPhysicalModel.
Parameters:
| oSceneScale | scaling factor to convert scene units to meters. |
| oViewHeight | height of the viewer in atmosphere in meters. |
| oSkyMult | sky multiplier applied to each pixel in the texture.. |
| oTurbidity | amount of molecules in the atmosphere. |
| oAlbedo | amount of light reflected by the ground to the sky. |
| oAerosolsAlbedo | amount of sun light reaching the aerosols which is reflected back to the sky. |
| oAsymmetryFactor | anisotropy of the light reflection due to aerosols. |
| oSunDir | unit direction towards the sun. |
| oSunRadiusScale | sun radius scaling. |
| oSunIntensityMultiplier | sun intensity multiplier. |
| oMoonDir | unit direction towards the moon. |
| oMoonRadiusScale | moon radius scaling. |
| oMoonIntensityMultiplier | moon intensity multiplier. |
| oStarsIntensityMultiplier | stars intensity multiplier. |
| oSaturation | sky saturation factor. |
| iStateNumber | queried state number. |
Returns:
| public virtual RED_RC RED::ISkyLightShape::GetPortals | ( | RED::Vector< RED::Object * > & | oPortals, |
| int | iStateNumber = -1 | ||
| ) | const = 0 |
Gets the list of portals defined for a skylight.
Parameters:
| oPortals | reference to the returned list of portals. |
| iStateNumber | Queried state number. |
Returns:
RED_BAD_PARAM if the method has received an invalid parameter,
RED_ALLOC_FAILURE if an internal allocation has failed.
| public virtual RED_RC RED::ISkyLightShape::GetSamplesCount | ( | unsigned int & | oSamplesCount, |
| int | iStateNumber = -1 | ||
| ) | const = 0 |
Gets the number of sky samples.
See SetSamplesCount for details.
Parameters:
| oSamplesCount | the maximum number of sky light samples. |
| iStateNumber | queried state number. |
Returns:
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.
| public virtual RED_RC RED::ISkyLightShape::GetSkyTexture | ( | RED::Object *& | oTexture, |
| int | iStateNumber = -1 | ||
| ) | const = 0 |
Gets the current sky texture.
See also Outdoor lighting.
Parameters:
| oTexture | the texture used by the sky to compute its color. |
| iStateNumber | queried state number. |
Returns:
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.
| public virtual RED_RC RED::ISkyLightShape::IsCustomModel | ( | bool & | oIsCustom, |
| int | iStateNumber = -1 | ||
| ) | const = 0 |
true if the current model is a custom one, false otherwise.
Requests the type of the sky model. If no model has been set, the method returns false.
Parameters:
| oIsCustom | true if a custom model has been set, false otherwise. |
| iStateNumber | queried state number. |
Returns:
| public virtual RED_RC RED::ISkyLightShape::IsEmissiveSky | ( | bool & | oEmissive, |
| int | iStateNumber = -1 | ||
| ) | const = 0 |
Is the sky emissive?
Parameters:
| oEmissive | Returned set to true if the sky is emissive, false otherwise. |
| iStateNumber | Queried state number. |
Returns:
RED_BAD_PARAM if the method has received an invalid parameter,
RED_ALLOC_FAILURE if an internal allocation has failed.
| public virtual RED_RC RED::ISkyLightShape::IsPhysicalModel | ( | bool & | oIsPhysical, |
| int | iStateNumber = -1 | ||
| ) | const = 0 |
true if the current model is a physical one, false otherwise.
Requests the type of the sky model. If no model has been set, the method returns false.
Parameters:
| oIsPhysical | true if a physical model has been set, false otherwise. |
| iStateNumber | queried state number. |
Returns:
| public virtual RED_RC RED::ISkyLightShape::SetCustomModel | ( | const RED::Vector3 & | iSunDir, |
| double | iSunRadiusScale, | ||
| const RED::Color & | iSunIntensity, | ||
| const RED::Vector3 & | iMoonDir, | ||
| double | iMoonRadiusScale, | ||
| const RED::Color & | iMoonIntensity, | ||
| const RED::State & | iState | ||
| ) | = 0 |
Sets up a custom sky model.
A custom sky model is made of two optional light sources (sun and moon) and a 2D texture. This call sets the sun and the moon while RED::ISkyLightShape::SetSkyTexture must be used for the environment texture.
A call to this method overwrites any previously set sky model.
Parameters:
| iSunDir | direction towards the sun (does not need to be a unit direction). |
| iSunRadiusScale | sun radius scaling (set it to 1.0 to get the real sun size). |
| iSunIntensity | RGB intensity of the sun. |
| iMoonDir | direction towards the moon (does not need to be a unit direction). |
| iMoonRadiusScale | moon radius scaling (set it to 1.0 to get the real moon size). |
| iMoonIntensity | RGB intensity of the moon. |
| iState | current transaction. |
Returns:
RED_BAD_PARAM if the method has received invalid parameters,
RED_INIT_FAILED if we have no window created yet (a window must have been created before any texture operation can occur in the engine),
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
| public virtual RED_RC RED::ISkyLightShape::SetEmissiveSky | ( | bool | iEmissive, |
| const RED::State & | iState | ||
| ) | = 0 |
Turns the sky emissive for the global illumination and disable the skylight direct lighting.
This method turns off the skylight direct sampling. Consequently, the skylight does not illuminate the scene anymore by means of direct lighting. The skylight is then considered as being emissive for all indirect lighting contributions generated during the GI phase.
Turning on the emissive sky is a useful speed-up optimization: the direct skylight sampling is replaced by the indirect GI contribution of the sky. Images created with emissive sky are incomplete (they lack the skylight direct contribution), but this is balanced by the extra emissive background contribution.
Parameters:
| iEmissive | Set to true to turn the sky emissive, false to disable the sky emission. |
| iState | Current transaction parameter. |
Returns:
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
| public virtual RED_RC RED::ISkyLightShape::SetMoonLight | ( | RED::Object *& | oMoonLight, |
| const RED::State & | iState | ||
| ) | = 0 |
Sets a moon light according to the current sky model.
If no sky model has been set, the method returns RED_FAIL.
If a valid pointer to a RED light is passed, the light is set up with the correct moon settings overwriting previous settings. Otherwise, a new light is created, set up and returned.
This method ensures that the moon light settings are synchronized with those of the sky light. Each time the sky light settings are changed, simply call this method again to get the moon light synchronized.
The returned light implements the RED::IMoonLightShape interface.
Parameters:
| oMoonLight | pointer to the returned light (if NULL, a light is created, otherwise a valid pointer to a RED light is assumed). |
| iState | current transaction. |
Returns:
| public virtual RED_RC RED::ISkyLightShape::SetPhysicalModel | ( | double | iSceneScale, |
| double | iViewHeight, | ||
| double | iSkyMult, | ||
| unsigned int | iTurbidity, | ||
| const RED::Color & | iAlbedo, | ||
| double | iAerosolsAlbedo, | ||
| double | iAsymmetryFactor, | ||
| const RED::Vector3 & | iSunDir, | ||
| double | iSunRadiusScale, | ||
| double | iSunIntensityMultiplier, | ||
| const RED::Vector3 & | iMoonDir, | ||
| double | iMoonRadiusScale, | ||
| double | iMoonIntensityMultiplier, | ||
| double | iStarsIntensityMultiplier, | ||
| double | iSaturation, | ||
| const RED::State & | iState | ||
| ) | = 0 |
Sets up a physical sky model.
For explanations about the model used to simulate the sky, please read Sky model.
A call to this method overwrites any previously set sky model.
Parameters:
| iSceneScale | scaling factor to convert scene units to meters. |
| iViewHeight | height of the viewer in atmosphere in meters (in [0, +inf[). |
| iSkyMult | sky multiplier applied to each pixel in the texture. Set it to 1.0 to create a physically accurate texture of the sky. Lower values can be used to simulate the effect of clouds or environment on the sky intensity. |
| iTurbidity | amount of molecules in the atmosphere (in [0, 100]). The higher, the more foggy. Default value of 20 is good for European countries. |
| iAlbedo | amount of sun light reaching the ground which is reflected back to the sky per RGB color component (in [0, 1]^3). A default value of 0.3 per component is good. |
| iAerosolsAlbedo | amount of sun light reaching the aerosols which is reflected back to the sky (in [0, 1]). The light which is not reflected is absorbed by aerosols. |
| iAsymmetryFactor | controls the anisotropy of the light reflection due to aerosols (in [-1, 1]). 0 is for fully isotropic aerosols, 1 is anisotropic (towards the viewer), -1 is anisotropic (towards the source). |
| iSunDir | direction towards the sun (does not need to be a unit direction). |
| iSunRadiusScale | sun radius scaling (set it to 1.0 to get the real sun size). |
| iSunIntensityMultiplier | sun intensity multiplier (set it to 1.0 to get the real sun intensity). |
| iMoonDir | direction towards the moon (does not need to be a unit direction) from the center of the earth. |
| iMoonRadiusScale | moon radius scaling (set it to 1.0 to get the real moon size). |
| iMoonIntensityMultiplier | moon intensity multiplier (set it to 1.0 to get the real moon intensity). |
| iStarsIntensityMultiplier | stars intensity multiplier (set it to 1.0 to get the real stars intensities). |
| iSaturation | saturation factor applied to the whole model. If saturation is set to 1.0, colors are returned as computed by the model. For other values, returned colors will look more greyish. The valid range of values is [0, 1]. |
| iState | current transaction. |
Returns:
RED_BAD_PARAM if the method has received invalid parameters,
RED_INIT_FAILED if we have no window created yet (a window must have been created before any texture operation can occur in the engine),
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
| public virtual RED_RC RED::ISkyLightShape::SetPortals | ( | const RED::Vector< RED::Object * > & | iPortals, |
| const RED::State & | iState | ||
| ) | = 0 |
Sets portal geometries to the skylight.
Setting portals to a skylight increases sampling quality for the same number of samples by giving insights about where the light actually comes from.
The number of samples used to render the skylight is not changed by using portals. Each portal is rendered with a number of samples depending on its area. For example, if two portals are set with areas A1 and A2 and n is the number of skylight samples:
portal1 samples count = n * A1 / ( A1 + A2 )
portal2 samples count = n * A2 / ( A1 + A2 )
letting the total number of samples unchanged.
Portal geometries must be real triangular meshes. It means that they should implement the RED::IMeshShape interface.
To remove portals, simply set an empty list of portals. The skylight will then be rendered as a classic one.
Please refer to Physical lights for details on portals, and to Using skylight portals for a practical example of portal setup.
Parameters:
| iPortals | list of portal geometries to be added. |
| iState | current transaction. |
Returns:
RED_BAD_PARAM if the method has received a shape in iPortals that is not a RED::IMeshShape,
RED_BAD_PARAM if the method has received twice the same portal in iPortals,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
| public virtual RED_RC RED::ISkyLightShape::SetSamplesCount | ( | unsigned int | iSamplesCount, |
| const RED::State & | iState | ||
| ) | = 0 |
Sets the number of samples to be taken during sky evaluation.
Lights are sampled during the rendering phase in each shaded point to estimate their contribution to the scene. The more the samples, the better the result and the longer the rendering times.
Lights can't have less than 1 sample. If 0 is supplied, 1 will be used instead.
A sky light may require a greate number of samples in difficult situations (like interior scenes without portals) to render with sufficient quality. A value of 1024 should be considered as common and is the default value when setuping a sky light.
See also Outdoor lighting.
Parameters:
| iSamplesCount | maximum number of samples to be taken while evaluating the sky light contribution. |
| iState | current transaction. |
Returns:
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.
| public virtual RED_RC RED::ISkyLightShape::SetSkyTexture | ( | const RED::Object * | iTexture, |
| bool | iHemispherical, | ||
| const RED::Vector3 & | iDir, | ||
| const RED::Vector3 & | iTop, | ||
| const RED::State & | iState | ||
| ) | = 0 |
Sets the texture of the sky.
Input values coherency is verified by this method. A skylight has no attenuation. Sample intensities are read from the provided environmental iTexture. The iDir and iTop are used to build an orthogonal basis needed to calculate spherical (u,v) values that are used to sample iTexture.
The texture must be a latitude/longitude map. It can be a hemispherical or a spherical sky map.
The skylight is always centered at the origin. The (u,v) = (0,0) point is heading toward the iDir axis. The (u,v) = (0,1) point is heading toward the iTop axis.
Best formats for that texture are floating point ones as they preserve the full range of intensities one can encounter in real sky colors.
Prefer low resolution maps (512x256 for a spherical map for example) as it will tend to reduce the noise due to sampling and will not be directly visible.
The sky light can't be visualized, it only produces light. To make it visible to the camera, you'll need to setup the same texture (but at a higher resolution this time) as the background texture of the viewpoint render list used to render the scene. If you use a cube texture as input, you can call RED::ISkyLightShape::GetBackgroundMatrixFromSky to retrieve the correct transformation matrix to apply to the cube you set in background.
The object does not become the owner of the texture. So be sure not to delete it while it's still in use by a sky light. If the texture content changes, don't forget to call SetSkyTexture again to reflect those changes.
The skylight has several additional specificities detailed below:
- A skylight is currently rendered as an ambient light on the GPU.
- A skylight is rendered as an ambient light on the CPU if the area sampling is disabled.
- A skylight only supports ray-traced shadows.
- The iTexture texture must be a RED::TGT_TEX_RECT image. We use this target to be able to consider HDR floating point sky images.
- A skylight disables the RED::RM_SHADOW_MAP render mode which is pointless to it as only ray-traced shadows are supported for a skylight.
This call resets the attenuation of the light to 1.0.
See also Outdoor lighting.
Parameters:
| iTexture: | This is the sky texture map. This texture must be a valid RED::TGT_TEX_RECT image to handle floating textures properly. |
| iHemispherical: | true if the skylight is hemispherical (iTexture is then a hemispherical map), false otherwise (the skylight is spherical). |
| iDir: | First axis defining the orientation of the horizon. Sampling a direction parallel to iDir fall on the U = 0.0f edge of iTexture. |
| iTop: | Second axis defining the orientation of the skylight. indicates the direction of the zenith. Sampling a direction perpendicular to iTop fall on the V = 0.0f of iTexture. Sampling a direction parallel to iTop fall on the V = 1.0f of iTexture. |
| iState: | current transaction. |
Returns:
RED_BAD_PARAM if the method has received an invalid parameter,
RED_BAD_PARAM if iTexture is not of the corresponding type or does not use a RED::TGT_TEX_RECT target,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
| public virtual RED_RC RED::ISkyLightShape::SetSunLight | ( | RED::Object *& | oSunLight, |
| const RED::State & | iState | ||
| ) | = 0 |
Sets a sun light according to the current sky model.
If no sky model has been set, the method returns RED_FAIL.
If a valid pointer to a RED light is passed, the light is set up with the correct sun settings overwriting previous settings. Otherwise, a new light is created, set up and returned.
This method ensures that the sun light settings are synchronized with those of the sky light. Each time the sky light settings are changed, simply call this method again to get the sun light synchronized.
The returned light implements the RED::ISunLightShape interface.
Parameters:
| oSunLight | pointer to the returned light (if NULL, a light is created, otherwise a valid pointer to a RED light is assumed). |
| iState | current transaction. |
Returns:
| public virtual RED_RC RED::ISkyLightShape::UpdateClouds | ( | int | iLayerIndex, |
| double | iAltitude, | ||
| double | iIntensity, | ||
| double | iOpacity, | ||
| const RED::State & | iState | ||
| ) | = 0 |
Updates a cloud layer in the sky.
This function can only be called after RED::ISkyLightShape::AddClouds.
This function updates the following clouds model parameters:
- clouds layer height;
- intensity;
- opacity;
- sun direction from sky model;
- view height from sky model.
Parameters:
| iLayerIndex: | layer index to update. |
| iAltitude: | clouds layer altitude. |
| iIntensity: | clouds intensity factor. |
| iOpacity: | opacity of the whole clouds layer. |
| iState | current transaction. |
Returns:
RED_BAD_PARAM if the method has received invalid parameters,
RED_WORKFLOW_ERROR if no clouds layer had been previously added,
RED_FAIL otherwise.
