ISkyLightShape

Functions

CID

GetClassID

RED_RC

SetPhysicalModel

RED_RC

IsPhysicalModel

RED_RC

GetPhysicalModel

RED_RC

SetCustomModel

RED_RC

IsCustomModel

RED_RC

GetCustomModel

RED_RC

AddClouds

RED_RC

UpdateClouds

RED_RC

ClearClouds

RED_RC

SetSkyTexture

RED_RC

GetSkyTexture

RED_RC

CreatePhysicalSkyTexture

RED_RC

CreatePhysicalSkyTextureLegacy

RED_RC

GetBackgroundMatrixFromSky

RED_RC

SetSunLight

RED_RC

ComputeSunDirection

RED_RC

SetMoonLight

RED_RC

ComputeMoonDirection

RED_RC

SetSamplesCount

RED_RC

GetSamplesCount

RED_RC

SetPortals

RED_RC

GetPortals

RED_RC

SetEmissiveSky

RED_RC

IsEmissiveSky

Detailed Description

class ISkyLightShape : public RED::IREDObject

This interface gives access to the creation and edition of sky, sun and moon lights.

@related Light Shapes, Outdoor Lighting, class RED::IShape

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).

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 \ref wf_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 \ref bk_sky_model.

\task tk_setup_a_physical_sky_light

Note

Defining a model for the sky is the first step in building a sky light.

Public Functions

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

Sets up a physical sky model.

For explanations about the model used to simulate the sky, please read \ref bk_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_OK if the operation has succeeded,

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.

virtual RED_RC 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

RED_BAD_PARAM on an invalid parameter,

RED_OK otherwise.

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

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

RED_FAIL if the current sky model is not a physical one (or no model hss been set),

RED_OK otherwise.

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

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_OK if the operation has succeeded,

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.

virtual RED_RC 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

RED_BAD_PARAM on an invalid parameter,

RED_OK otherwise.

virtual RED_RC 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_OK if the operation has succeeded,

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.

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

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_OK if the operation has succeeded,

RED_BAD_PARAM if the method has received invalid parameters,

RED_FAIL otherwise.

virtual RED_RC 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_OK if the operation has succeeded,

RED_BAD_PARAM if the method has received invalid parameters,

RED_WORKFLOW_ERROR if no clouds layer had been previously added,

RED_FAIL otherwise.

virtual RED_RC ClearClouds(const RED::State &iState) = 0

Deletes all the clouds layers from the sky.

Parameters

iState – current transaction.

Returns

RED_OK if the operation has succeeded,

RED_FAIL otherwise.

virtual RED_RC 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 \ref wf_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_OK if the operation has succeeded,

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.

virtual RED_RC GetSkyTexture(RED::Object *&oTexture, int iStateNumber = -1) const = 0

Gets the current sky texture.

See also \ref wf_outdoor_lighting.

Parameters
  • oTexture – the texture used by the sky to compute its color.

  • iStateNumber – queried state number.

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 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 \ref bk_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.

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 tk_creating_a_physical_sky_texture

Note

Composite sky textures are not supported by the GPU.

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_OK if the operation has succeeded,

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.

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

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_OK if the operation has succeeded,

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.

virtual RED_RC 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_OK if the operation has succeeded,

RED_BAD_PARAM if the method has received invalid parameters,

RED_FAIL otherwise.

virtual RED_RC 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

RED_BAD_PARAM on an invalid parameter

RED_OK on success.

virtual RED_RC 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

RED_BAD_PARAM on an invalid parameter,

RED_OK otherwise.

virtual RED_RC 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

RED_BAD_PARAM on an invalid parameter

RED_OK on success.

virtual RED_RC 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

RED_BAD_PARAM on an invalid parameter,

RED_OK otherwise.

virtual RED_RC 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 \ref wf_outdoor_lighting.

Parameters
  • iSamplesCount – maximum number of samples to be taken while evaluating the sky light contribution.

  • 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 sky samples.

See SetSamplesCount for details.

Parameters
  • oSamplesCount – the maximum number of sky light samples.

  • iStateNumber – queried state number.

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 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 \ref bk_sg_physical_lights for details on portals, and to \ref wf_using_skylight_portals for a practical example of portal setup.

Parameters
  • iPortals – list of portal geometries to be added.

  • iState – current transaction.

Returns

RED_OK if the operation has succeeded,

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.

virtual RED_RC 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_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.

virtual RED_RC 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_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 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_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.

Public Static Functions

static inline RED::CID GetClassID()