This page has been translated automatically.
Video Tutorials
Interface
Essentials
Advanced
How To
Professional (SIM)
UnigineEditor
Interface Overview
Assets Workflow
Version Control
Settings and Preferences
Working With Projects
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Lighting
Sandworm
Using Editor Tools for Specific Tasks
Extending Editor Functionality
Built-in Node Types
Nodes
Objects
Effects
Decals
Light Sources
Geodetics
World Nodes
Sound Objects
Pathfinding Objects
Players
Programming
Fundamentals
Setting Up Development Environment
Usage Examples
C++
C#
UnigineScript
UUSL (Unified UNIGINE Shader Language)
Plugins
File Formats
Materials and Shaders
Rebuilding the Engine Tools
GUI
Double Precision Coordinates
API
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Objects-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
IG Plugin
CIGIConnector Plugin
Rendering-Related Classes
Content Creation
Content Optimization
Materials
Material Nodes Library
Miscellaneous
Input
Math
Matrix
Textures
Art Samples
Tutorials
Warning! This version of documentation is OUTDATED, as it describes an older SDK version! Please switch to the documentation for the latest SDK version.
Warning! This version of documentation describes an old SDK version which is no longer supported! Please upgrade to the latest SDK version.

Unigine::Light Class

Header: #include <UnigineLights.h>
Inherits from: Node

This base class is used to create light sources and shadows from them. The lights can be rendered as a simplified deferred lighting.

Light Class

Enums

SHADOW_RESOLUTION#

NameDescription
SHADOW_RESOLUTION_MODE_DEFAULT = -1Default shadow map resolution (512×512).
SHADOW_RESOLUTION_MODE_64 = MODE_DEFAULT + 1Shadow map resolution equals 64×64.
SHADOW_RESOLUTION_MODE_128 = MODE_64 + 1Shadow map resolution equals 128×128.
SHADOW_RESOLUTION_MODE_256 = MODE_128 + 1Shadow map resolution equals 256×256.
SHADOW_RESOLUTION_MODE_512 = MODE_256 + 1Shadow map resolution equals 512×512.
SHADOW_RESOLUTION_MODE_1024 = MODE_512 + 1Shadow map resolution equals 1024×1024.
SHADOW_RESOLUTION_MODE_2048 = MODE_1024 + 1Shadow map resolution equals 2048×2048.
SHADOW_RESOLUTION_MODE_4096 = MODE_2048 + 1Shadow map resolution equals 4096×4096.
SHADOW_RESOLUTION_MODE_8192 = MODE_4096 + 1Shadow map resolution equals 8192×8192.
SHADOW_RESOLUTION_MODE_16384 = MODE_8192 + 1Shadow map resolution equals 16384×16384.

SHADOW_PENUMBRA#

NameDescription
SHADOW_PENUMBRA_GLOBAL = -1Quality mode of shadow penumbra that is set globally for all light sources is applied.
SHADOW_PENUMBRA_DISABLED = GLOBAL + 1Shadow penumbra is disabled.
SHADOW_PENUMBRA_LOW = DISABLED + 1Low quality of shadow penumbra.
SHADOW_PENUMBRA_MEDIUM = LOW + 1Medium quality of shadow penumbra.
SHADOW_PENUMBRA_HIGH = MEDIUM + 1High quality of shadow penumbra.
SHADOW_PENUMBRA_ULTRA = HIGH + 1Ultra quality of shadow penumbra.

SHADOW_FILTER#

NameDescription
SHADOW_FILTER_GLOBAL = -1Quality mode of shadow filtering that is set globally is applied.
SHADOW_FILTER_DISABLED = GLOBAL + 1Shadow filtering is disabled.
SHADOW_FILTER_LOW = DISABLED + 1Low quality of shadow filtering.
SHADOW_FILTER_MEDIUM = LOW + 1Medium quality of shadow filtering.
SHADOW_FILTER_HIGH = MEDIUM + 1High quality of shadow filtering.
SHADOW_FILTER_ULTRA = HIGH + 1Ultra quality of shadow filtering.

COLOR_MODE#

NameDescription
COLOR_MODE_CLASSIC = 0Classic color calculation mode, resulting color is defined by Color.
COLOR_MODE_TEMPERATURE = 1Physically based color calculation mode, resulting color is calculated as: ColorFilter * (color obtained using the ColorTemperature value).

SHADOW_MODE#

NameDescription
SHADOW_MODE_MIXED = 0Shadow mode for omni and projected light sources with the static light mode enabled to render both static and dynamic shadows.
SHADOW_MODE_STATIC = 1Static shadow mode for omni and projected light sources with the static light mode enabled.

SHADOW_COLOR_MODE#

NameDescription
SHADOW_COLOR_MODE_IES = 0Light distibution is defined by the IES profile.
SHADOW_COLOR_MODE_SIMPLE = 1An arbitrary 2D texture is projected onto the scene.

MODE#

NameDescription
MODE_DYNAMIC = 0Real-time light rendering mode. The light source with this mode enabled is turned off while light baking is being calculated. Objects lit by such light cast only dynamic shadows.
MODE_STATIC = 1Mixed light rendering mode. The light source with this light mode enabled contributes to light baking and remains enabled all the time providing direct realtime lighting. Objects lit by such light can cast static or dynamic shadows depending on the shadow mode set for the source and the object surface.

SHAPE#

NameDescription
SHAPE_DEFAULT = -1A point light source (light is emitted by an infinitely small point) set by default.
SHAPE_POINT = DEFAULT + 1A point light source (light is emitted by an infinitely small point).
SHAPE_SPHERE = POINT + 1A sphere-shaped light source.
SHAPE_CAPSULE = SPHERE + 1A capsule-shaped light source.
SHAPE_RECTANGLE = CAPSULE + 1A rectangular light source. Such light source produces the light and the speck in a form of a rounded rectangle.

Members


void setMode ( Light::MODE mode ) #

Sets rendering mode for the light source. This option determines whether the light is to be rendered as a dynamic or static one.

Arguments

Light::MODE getMode ( ) const#

Returns the current rendering mode for the light source. This option determines whether the light is to be rendered as a dynamic or static one.

Return value

Light mode, one of the MODE_* variables.

void setAttenuationPower ( float power ) #

Updates the attenuation power of the light. This parameter determines how fast the intensity decreases up to the attenuation distance set for the light source. If the attenuation equals to zero or is close to it, the edge between illuminated and non-illuminated areas will be sharp.

Arguments

  • float power - Light attenuation power.

float getAttenuationPower ( ) const#

Returns the attenuation power of the light. This parameter determines how fast the intensity decreases up to the attenuation distance set for the light source. If the attenuation equals to zero or is close to it, the edge between illuminated and non-illuminated areas will be sharp. The default is 1.

Return value

Light attenuation power.

void setColor ( const Math::vec4 & color ) #

Updates the color of the light source. The method takes effect only when the Classic color mode is set.

Arguments

  • const Math::vec4 & color - New color in the RGBA format.

Math::vec4 getColor ( ) const#

Returns the color of the light source. The default is opaque white, (1, 1, 1, 1). The method takes effect only when the Classic color mode is set.

Return value

Color of the light source in the RGBA format.

Ptr<Texture> getShadowTexture ( ) const#

Returns the current depth texture (shadow map) of the light source.

Return value

Current depth texture (shadow map) of the light source.

Ptr<Texture> getShadowColorTexture ( ) const#

Returns the current shadow texture of the light source used to render translucent shadows: G-channel stores depth values, R-channel - transparency values.

Return value

Current shadow texture of the light source.

void setFadeDistance ( float distance ) #

Updates a distance, at which the light gradually disappears. This parameter enables to render the light with decreasing radiance after the Visible distance is past.

Arguments

  • float distance - Distance in units.

float getFadeDistance ( ) const#

Returns the current distance, at which the light source gradually disappears. This parameter enables to render the light with decreasing radiance after the Visible distance is past.

Return value

Distance in units.

void setIntensity ( float intensity ) #

Updates the multiplier for the light color used to control color intensity. The higher the value, the brighter the light is.
  • The minimum value of 1 corresponds to the least saturated light color.
  • The maximum value of 100 equals the most bright and intense color.

Arguments

  • float intensity - New color multiplier.

float getIntensity ( ) const#

Returns the multiplier of the light color used to control color intensity. The higher the value, the brighter the light is.

Return value

Light color multiplier.

void setShadowMask ( int mask ) #

Updates the light mask for the light source.

For the shadow from an object's surface to be rendered for the light source, this mask must match the following ones (one bit, at least):

Arguments

  • int mask - Integer, each bit of which is used to set a mask.

int getShadowMask ( ) const#

Returns the current light mask for the light source.

For the shadow from an object's surface to be rendered for the light source, this mask must match the following ones (one bit, at least):

Return value

Integer, each bit of which is used to set a mask.

void setRenderOnTransparent ( bool transparent ) #

Enables or disables rendering of the light from the source on transparent objects.

Arguments

  • bool transparent - true to render the light from the source on transparent objects, false not to render.

bool isRenderOnTransparent ( ) const#

Returns a value indicating if the light from the source is rendered on transparent objects.

Return value

true if the light from the source is rendered on transparent objects; otherwise, false.

void setRenderOnWater ( bool water ) #

Enables or disables rendering of the light from the source on water objects.

Arguments

  • bool water - true to render the light from the source on water objects, false not to render.

bool isRenderOnWater ( ) const#

Returns a value indicating if the light from the source is rendered on water objects.

Return value

true if the light from the source is rendered on water objects; otherwise, false.

void setShadow ( bool shadow ) #

Updates a value indicating if the light casts shadows from surfaces with the Cast Shadow material.

Arguments

  • bool shadow - true to cast shadows, false not to cast.

bool getShadow ( ) const#

Returns a value indicating if the light source casts shadows from surfaces with the Cast Shadow material.

Return value

true if the light source casts shadows; otherwise, false.

void setShadowBias ( float bias ) #

Updates the constant offset of depth values in a shadow map.
  • If the shadow acne appears, the bias value should be increased. This procedure eliminates the self-shadowing effect, as the points will appear closer to light source when compared to the map depth value.
  • If the bias value is set too high, the shadow will look detached from the object casting it (see the 3rd picture below).

Arguments

  • float bias - New constant depth offset. If a negative value is provided, 0 will be used instead.

float getShadowBias ( ) const#

Returns the constant offset of depth values in a shadow map.
  • If the shadow acne appears, the bias value should be increased. This procedure eliminates the self-shadowing effect, as the points will appear closer to light source when compared to the map depth value.
  • If the bias value is set too high, the shadow will look detached from the object casting it (see the 3rd picture below).

Return value

Constant depth offset.

void setShadowDistance ( float distance ) #

Updates a distance, at which shadow from the light source starts fading out to nonexistence.

Arguments

  • float distance - Distance in units.

float getShadowDistance ( ) const#

Returns the current distance, at which shadow from the light source starts fading out to nonexistence.

Return value

Distance in units.

void setShadowNormalBias ( float bias ) #

Updates the shadow bias that is achieved by shifting the surface on which the shadow falls. The surface is shifted along normals stored in the normal map. Depending on the normal map of the surface, the shadow may differ for the same values of the normal bias.

Arguments

  • float bias - New normal bias. If a negative value is provided, 0 will be used instead.

float getShadowNormalBias ( ) const#

Returns the shadow bias that is achieved by shifting the surface on which the shadow falls. The surface is shifted along normals stored in the normal map. Depending on the normal map of the surface, the shadow may differ for the same values of the normal bias.

Return value

The normal bias.

void setShadowResolution ( Light::SHADOW_RESOLUTION resolution ) #

Updates the size of the shadow map created for the light source.
  • The higher the resolution, the smoother and true to life the result is.
  • The lower the resolution, the more blocky and jagged the shadows outline appears.

Arguments

Light::SHADOW_RESOLUTION getShadowResolution ( ) const#

Returns the size of the shadow map created for the light source.

Return value

Shadow map size, one of the SHADOW_RESOLUTION_VALUE_ variables

void setShadowScreenSpace ( bool space ) #

Enables or disables screen-space shadows for the light source. When this option is enabled, penumbras from the light source are calculated using the ray tracing algorithm.

Arguments

  • bool space - true to enable screen-space shadows for the light source, false to disable. The default value is false.

bool isShadowScreenSpace ( ) const#

Returns a value indicating if screen-space shadows for the light source are enabled. When this option is enabled, penumbras from the light source are calculated using the ray tracing algorithm.

Return value

true if screen-space shadows for the light source are enabled; otherwise, false.

void setShadowScreenSpaceNoiseRay ( float ray ) #

Sets the intensity of the ray noise used to calculate screen-space shadows for the light source. This parameter is used to reduce the banding effect.

Arguments

  • float ray - Ray noise intensity. The default value is 0.5. The higher is the value, the less pronounced is the banding effect. However, this option significantly affects performance.
    Notice
    Screen-space shadows must be enabled, see the setShadowScreenSpace() method.

float getShadowScreenSpaceNoiseRay ( ) const#

Returns the current intensity of the ray noise used to calculate screen-space shadows for the light source.

Return value

Ray noise intensity.

void setShadowScreenSpaceNoiseStep ( float step ) #

Sets the intensity of the step noise used to calculate screen-space shadows for the light source. This parameter is used to reduce the banding effect.

Arguments

  • float step - Step noise intensity. The default value is 0.5. The higher is the value, the less pronounced is the banding effect. However, this option significantly affects performance.
    Notice
    Screen-space shadows must be enabled, see the setShadowScreenSpace() method.

float getShadowScreenSpaceNoiseStep ( ) const#

Returns the current intensity of the step noise used to calculate screen-space shadows for the light source.

Return value

Step noise intensity.

void setShadowScreenSpaceNumRays ( int rays ) #

Sets the number of rays used to calculate screen-space shadows for the light source.

Arguments

  • int rays - Number of rays. The default value is 8. The higher is the value, the better is the quality of shadows. However, this option significantly affects performance.
    Notice
    Screen-space shadows must be enabled, see the setShadowScreenSpace() method.

int getShadowScreenSpaceNumRays ( ) const#

Returns the current number of rays used to calculate screen-space shadows for the light source.

Return value

Number of rays.

void setShadowScreenSpaceNumSteps ( int steps ) #

Sets the number of steps used to calculate screen-space shadows for the light source.

Arguments

  • int steps - Number of steps. The default value is 8. The higher is the value, the better is the quality of shadows. However, this option significantly affects performance.
    Notice
    Screen-space shadows must be enabled, see the setShadowScreenSpace() method.

int getShadowScreenSpaceNumSteps ( ) const#

Returns the current number of steps used to calculate screen-space shadows for the light source.

Return value

Number of steps.

void setShadowScreenSpaceSoftness ( float softness ) #

Returns the softness value of the screen-space shadows for the light source.

Arguments

  • float softness - Screen-space shadows softness. The default value is 0.4. The higher is the value, the softer are the shadows.
    Notice
    Screen-space shadows must be enabled, see the setShadowScreenSpace() method.

float getShadowScreenSpaceSoftness ( ) const#

Returns the current softness value of the screen-space shadows for the light source.

Return value

Screen-space shadows softness.

void setShadowScreenSpaceStepSizeNear ( float val ) #

Sets the size of the step used to calculate screen-space shadows for the light source (close distance range). This parameter can be used to adjust calculation of shadows for specific sizes of objects. You can set different Step Size and Threshold values for objects located near the camera and far away from it. Thus, full-scale shadows will be rendered for large objects located far away, while within the close distance range only shadows cast by small objects will be rendered. This feature is especially useful for locations where details are required for both short and long-distance ranges.

Arguments

float getShadowScreenSpaceStepSizeNear ( ) const#

Returns the current size of the step used to calculate screen-space shadows for the light source (close distance range). This parameter can be used to adjust calculation of shadows for specific sizes of objects. You can set different Step Size and Threshold values for objects located near the camera and far away from it. Thus, full-scale shadows will be rendered for large objects located far away, while within the close distance range only shadows cast by small objects will be rendered. This feature is especially useful for locations where details are required for both short and long-distance ranges.

Return value

Screen-space step size for close distance range. The default value is 0.5.
Notice
Screen-space shadows must be enabled, see the setShadowScreenSpace() method.

void setShadowScreenSpaceStepSizeFar ( float val ) #

Sets the current size of the step used to calculate screen-space shadows for the light source (long distance range). This parameter can be used to adjust calculation of shadows for specific sizes of objects. You can set different Step Size and Threshold values for objects located near the camera and far away from it. Thus, full-scale shadows will be rendered for large objects located far away, while within the close distance range only shadows cast by small objects will be rendered. This feature is especially useful for locations where details are required for both short and long-distance ranges.

Arguments

float getShadowScreenSpaceStepSizeFar ( ) const#

Returns the current size of the step used to calculate screen-space shadows for the light source (long distance range). This parameter can be used to adjust calculation of shadows for specific sizes of objects. You can set different Step Size and Threshold values for objects located near the camera and far away from it. Thus, full-scale shadows will be rendered for large objects located far away, while within the close distance range only shadows cast by small objects will be rendered. This feature is especially useful for locations where details are required for both short and long-distance ranges.

Return value

Screen-space step size for long distance range. The default value is 0.5.
Notice
Screen-space shadows must be enabled, see the setShadowScreenSpace() method.

void setShadowScreenSpaceThresholdNear ( float val ) #

Sets the threshold value used to calculate screen-space shadows for the light source (close distance range). This parameter is used to adjust the look of screen-space shadows. You can set different Step Size and Threshold values for objects located near the camera and far away from it. Thus, full-scale shadows will be rendered for large objects located far away, while within the close distance range only shadows cast by small objects will be rendered. This feature is especially useful for locations where details are required for both short and long-distance ranges.

Arguments

float getShadowScreenSpaceThresholdNear ( ) const#

Returns the current threshold value used to calculate screen-space shadows for the light source (close distance range). You can set different Step Size and Threshold values for objects located near the camera and far away from it. Thus, full-scale shadows will be rendered for large objects located far away, while within the close distance range only shadows cast by small objects will be rendered. This feature is especially useful for locations where details are required for both short and long-distance ranges.

Return value

Screen-space shadows threshold for close distance range.

void setShadowScreenSpaceThresholdFar ( float val ) #

Sets the threshold value used to calculate screen-space shadows for the light source (long distance range). This parameter is used to adjust the look of screen-space shadows.You can set different Step Size and Threshold values for objects located near the camera and far away from it. Thus, full-scale shadows will be rendered for large objects located far away, while within the close distance range only shadows cast by small objects will be rendered. This feature is especially useful for locations where details are required for both short and long-distance ranges.

Arguments

float getShadowScreenSpaceThresholdFar ( ) const#

Returns the current threshold value used to calculate screen-space shadows for the light source (long distance range). You can set different Step Size and Threshold values for objects located near the camera and far away from it. Thus, full-scale shadows will be rendered for large objects located far away, while within the close distance range only shadows cast by small objects will be rendered. This feature is especially useful for locations where details are required for both short and long-distance ranges.

Return value

Screen-space shadows threshold for long distance range.

void setViewportMask ( int mask ) #

Updates a bit mask for rendering into the viewport. The light is rendered, if its mask matches the player's one.

Arguments

  • int mask - Integer, each bit of which is used to set a mask.

int getViewportMask ( ) const#

Returns the current bit mask for rendering into the viewport. The light is rendered, if its mask matches the player's one.

Return value

Integer, each bit of which is used to set a mask.

void setVisibleDistance ( float distance ) #

Updates a distance, at which the light source starts fading. If the distance is set to infinity, the source is always rendered.

Arguments

  • float distance - Distance in units.

float getVisibleDistance ( ) const#

Returns the current distance, at which the light source starts fading. If the distance is set to infinity, the source is always rendered.

Return value

Distance in units.

void setLensFlaresEnabled ( bool enabled ) #

Enables or disables the per-light lens flare effect for the light source.
Notice

Arguments

  • bool enabled - 1 to enable the per-light lens flare effect for the light source, 0 to disable. The default value is 0.

bool isLensFlaresEnabled ( ) const#

Returns a value indicating if the per-light lens flare effect is enabled for the light source.
Notice
This feature is available only for: Omni Lights, Projected Lights and World Lights.

Return value

1 if the per-light lens flare effect for the light source is enabled; otherwise, 0.

void allocateLensFlares ( int num ) #

Allocate a buffer for a given number of lens flares to be created. With this function, memory can be allocated once rather than in chunks, making the creation faster.
Notice
The lens flare effect must be enabled for the light source. This feature is available only for: Omni Lights, Projected Lights and World Lights.

Arguments

  • int num - Number of lens flares to be created in the allocated buffer.

void addLensFlare ( ) #

Add a new lens flare for the per-light lens flare effect.
Notice
The lens flare effect must be enabled for the light source. This feature is available only for: Omni Lights, Projected Lights and World Lights.

Ptr<LightLensFlare> getLensFlare ( int num ) #

Returns the given lens flare from the list of the ones used for the per-light lens flare effect.
Notice
The lens flare effect must be enabled for the light source. This feature is available only for: Omni Lights, Projected Lights and World Lights.

Arguments

  • int num - Lens flare number.

Return value

Light lens flare smart pointer.

void cloneLensFlare ( int num ) #

Creates a clone of the lens flare with a given number in the list of lens flares used for the per-light lens flare effect.
Notice
The lens flare effect must be enabled for the light source. This feature is available only for: Omni Lights, Projected Lights and World Lights.

Arguments

  • int num - Number of lens flare to be cloned.

void removeLensFlare ( int num ) #

Removes the lens flare with a given number from the list of lens flares used for the per-light lens flare effect.
Notice
The lens flare effect must be enabled for the light source. This feature is available only for: Omni Lights, Projected Lights and World Lights.

Arguments

  • int num - Number of lens flare to be removed.

int getNumLensFlares ( ) const#

Returns the total number of lens flares used for the per-light lens flare effect.
Notice
The lens flare effect must be enabled for the light source. This feature is available only for: Omni Lights, Projected Lights and World Lights.

Return value

Number of lens flares used for the per-light lens flare effect.

void clearLensFlares ( ) #

Clears the list of lens flares used for the per-light lens flare effect.
Notice
The lens flare effect must be enabled for the light source. This feature is available only for: Omni Lights, Projected Lights and World Lights.

void setLensFlaresIntensity ( float intensity ) #

Sets the intensity of per-light lens flares.
Notice
The lens flare effect must be enabled for the light source. This feature is available only for: Omni Lights, Projected Lights and World Lights.

Arguments

  • float intensity - Intensity of per-light lens flares.Higher values make the effect more pronounced.

float getLensFlaresIntensity ( ) const#

Returns the current intensity of per-light lens flares.
Notice
The lens flare effect must be enabled for the light source. This feature is available only for: Omni Lights, Projected Lights and World Lights.

Return value

Intensity of per-light lens flares.Higher values make the effect more pronounced.

void setLensFlaresUseLightColor ( bool color ) #

Enables or disables light color modulation for per-light lens flares. When enabled, the lens flares will have the same color as the light source.
Notice
The lens flare effect must be enabled for the light source. This feature is available only for: Omni Lights, Projected Lights and World Lights.

Arguments

  • bool color - 1 to enable light color modulation for the per-light lens flare effect, 0 to disable. The default value is 0.

bool isLensFlaresUseLightColor ( ) const#

Returns a value indicating if light color modulation is enabled for per-light lens flares. When enabled, the lens flares will have the same color as the light source.
Notice
The lens flare effect must be enabled for the light source. This feature is available only for: Omni Lights, Projected Lights and World Lights.

Return value

1 if light color modulation for per-light lens flares is enabled; otherwise, 0.

void setLensFlaresOcclusionFade ( float fade ) #

Sets the lens flare occlusion fade value for the cases when the light source becomes occluded by an object.
Notice
The lens flare effect must be enabled for the light source. This feature is available only for: Omni Lights, Projected Lights and World Lights.

Arguments

  • float fade - Lens flare occlusion fade value in the range [0.0f; 1.0f]. By the value of 0.0f, lens flares disappear abruptly, as the light source becomes occluded by an object. If 1.0f is set, lens flares will fade out gradually.

float getLensFlaresOcclusionFade ( ) const#

Returns the current lens flare occlusion fade value for the cases when the light source becomes occluded by an object.
Notice
The lens flare effect must be enabled for the light source. This feature is available only for: Omni Lights, Projected Lights and World Lights.

Return value

Current lens flare occlusion fade value in the range [0.0f; 1.0f]. By the value of 0.0f, lens flares disappear abruptly, as the light source becomes occluded by an object. If 1.0f is set, lens flares will fade out gradually.

void setLensFlaresOcclusionFadeBorder ( float border ) #

Sets the lens flare occlusion fade value for the cases when the light source becomes occluded by the edges of the screen.
Notice
The lens flare effect must be enabled for the light source. This feature is available only for: Omni Lights, Projected Lights and World Lights.

Arguments

  • float border - Lens flare occlusion fade value in the range [0.0f; 1.0f]. By the value of 0.0f, lens flares disappear abruptly, as the light source becomes occluded by an object. If 1.0f is set, lens flares will fade out gradually.

float getLensFlaresOcclusionFadeBorder ( ) const#

Returns the current lens flare occlusion fade value for the cases when the light source becomes occluded by the edges of the screen.
Notice
The lens flare effect must be enabled for the light source. This feature is available only for: Omni Lights, Projected Lights and World Lights.

Return value

Current lens flare occlusion fade value in the range [0.0f; 1.0f]. By the value of 0.0f, lens flares disappear abruptly, as the light source becomes occluded by the edges of the screen. If 1.0f is set, lens flares will fade out gradually.

void setLensFlaresWorldPositionOffset ( const Math::vec3 & offset ) #

Sets the offset from the world position of the light source for the per-light lens flares. Offset is not available for World Lights.
Notice
The lens flare effect must be enabled for the light source. This feature is available only for: Omni Lights, Projected Lights and World Lights.

Arguments

  • const Math::vec3 & offset - Vector representing the offset of lens flares from the light source world position.

Math::vec3 getLensFlaresWorldPositionOffset ( ) const#

Returns the current offset from the world position of the light source for the per-light lens flares. Offset is not available for World Lights.
Notice
The lens flare effect must be enabled for the light source. This feature is available only for: Omni Lights, Projected Lights and World Lights.

Return value

Vector representing the current offset of lens flares from the light source world position.

void setLensFlaresTextureName ( const char * name ) #

Sets the name of the texture to be used for the per-light lens flare effect. This texture stores images for all lens flares used to render lens flares.
Notice
The lens flare effect must be enabled for the light source. This feature is available only for: Omni Lights, Projected Lights and World Lights.

Arguments

  • const char * name - Texture name.

const char * getLensFlaresTextureName ( ) const#

Returns the name of the texture currently used for the per-light lens flare effect. This texture stores images for all lens flares used to render lens flares.
Notice
The lens flare effect must be enabled for the light source. This feature is available only for: Omni Lights, Projected Lights and World Lights.

Return value

Texture name.

void setLux ( float lux ) #

Sets an intensity of a light color (as perceived by the human eye) in lux. In UNIGINE, all light sources have the intensity of 1 by default, which is equal to 100000 lux.

Arguments

  • float lux - Light color intensity, lux.

float getLux ( ) const#

Returns the intensity of the light color (as perceived by the human eye) in lux. In UNIGINE, all light sources have the intensity of 1 by default, which is equal to 100000 lux.

Return value

Light color intensity, lux.

void setColorTemperature ( float temperature ) #

Sets a light source temperature used for light color calculation.

Arguments

  • float temperature - Light source temperature in range [0;40000].

float getColorTemperature ( ) const#

Returns the light source temperature used for light color calculation.

Return value

Light source temperature [0;40000].

void setColorFilter ( const Math::vec4 & filter ) #

Sets a color multiplier for the light source color (calculated using the color temperature value). This can be used to imitate colored glass. The method takes effect only when the Temperature color mode is set.

Arguments

  • const Math::vec4 & filter - Color.

Math::vec4 getColorFilter ( ) const#

Returns the color multiplier for the light source color (calculated using the color temperature value). This is used to imitate colored glass. The method takes effect only when the Temperature color mode is set.

Return value

Color.

void setColorMode ( Light::COLOR_MODE mode ) #

Sets color calculation mode for the light source. Light source color can be defined by the color value (classic mode) or by the color temperature and color filter values (physically based mode).

Arguments

Light::COLOR_MODE getColorMode ( ) const#

Returns the current color calculation mode of the light source. Light source color can be defined by the color value (classic mode) or by the color temperature and color filter values (physically based mode).

Return value

Current color calculation mode, one of the following values:

Math::vec4 calculateFinalColor ( ) const#

Calculates the final color of the light source depending on the calculation mode used.

Return value

Resulting color of the light source.

bool saveStateLight ( const Ptr<Stream> & stream ) const#

Saves the state of the light source to the specified stream.

Example using SaveStateLight() and restoreStateLight() methods:

Source code (C++)
// set the light state
light->setColorTemperature(15000.0f);

// save state
BlobPtr blob_state = Blob::create();
light->saveStateLight(blob_state);

// change state
light>setColorTemperature(27000.0f);

// restore state
blob_state->seekSet(0);				// returning the carriage to the start of the blob
light->restoreStateLight(blob_state);

Arguments

  • const Ptr<Stream> & stream - Stream smart pointer.

Return value

true if the state of the light source is saved successfully; otherwise, false.

bool restoreStateLight ( const Ptr<Stream> & stream ) #

Restores the state of the light source from the specified stream.

Example using saveStateLight() and restoreStateLight() methods:

Source code (C++)
// set the light state
light->setColorTemperature(15000.0f);

// save state
BlobPtr blob_state = Blob::create();
light->saveStateLight(blob_state);

// change state
light->setColorTemperature(27000.0f);

// restore state
blob_state->seekSet(0);				// returning the carriage to the start of the blob
light->restoreStateLight(blob_state);

Arguments

  • const Ptr<Stream> & stream - Stream smart pointer.

Return value

true if the state of the light source is restored successfully; otherwise, false.

bool saveStateLensFlares ( const Ptr<Stream> & stream ) const#

Saves the state of the per-light lens flare effect to the specified stream.

Example using saveStateLensFlares() and restoreStateLensFlares() methods:

Source code (C++)
// set the lens flare state
lens_flare->setLensFlaresIntensity(0.75f);

// save state
BlobPtr blob_state = Blob::create();
lens_flare->saveStateLensFlares(blob_state);

// change state
lens_flare->setLensFlaresIntensity(0.25f);

// restore state
blob_state->seekSet(0);				// returning the carriage to the start of the blob
lens_flare->restoreStateLensFlares(blob_state);

Arguments

  • const Ptr<Stream> & stream - Stream smart pointer.

Return value

true if the state of the per-light lens flare effect is saved successfully; otherwise, false.

bool restoreStateLensFlares ( const Ptr<Stream> & stream ) #

Restores the state of the per-light lens flare effect from the specified stream.

Example using saveStateLensFlares() and restoreStateLensFlares() methods:

Source code (C++)
// set the lens flare state
lens_flare->setLensFlaresIntensity(0.75f);

// save state
BlobPtr blob_state = Blob::create();
lens_flare->saveStateLensFlares(blob_state);

// change state
lens_flare->setLensFlaresIntensity(0.25f);

// restore state
blob_state->seekSet(0);				// returning the carriage to the start of the blob
lens_flare->restoreStateLensFlares(blob_state);

Arguments

  • const Ptr<Stream> & stream - Stream smart pointer.

Return value

true if the state of the per-light lens flare effect is restored successfully; otherwise, false.

void setBakedDepthTexturePath ( const char * path ) #

Sets a path to a baked depth texture, which stores a shadow map generated for the light source, when its mode is set to MODE_STATIC. EnvironmentProbes use this texture for cutting out reflections for occluded areas, where they should not be visible.

Arguments

  • const char * path - Path to a baked depth texture to be used.

const char * getBakedDepthTexturePath ( ) const#

Returns a path to a baked depth texture, which is used for storing the shadow map created from the light source set to the static light mode. This texture is baked automatically via the Editor or using bake() or bakeAll() methods.

Return value

Path to a baked depth texture to be used.

void setShadowMode ( Light::SHADOW_MODE mode ) #

Sets shadow mode for the light source in static mode. This shadow mode should be aligned with the shadow mode of the object surface in order to make this surface cast a shadow from the light source.

Arguments

Light::SHADOW_MODE getShadowMode ( ) const#

Returns shadow mode for the light source in static mode. This shadow mode should be aligned with the shadow mode of the object surface in order to make this surface cast a shadow from the light source.

Return value

Shadow mode of the light source in static mode, one of the SHADOW_MODE_* variables.

void setShadowColorTextureMode ( Light::SHADOW_COLOR_MODE mode ) #

Sets the type of texture used to define light distribution.
Notice
This feature is available only for Omni Lights and Projected Lights. See description of the modes in the corresponding articles forOmni Lights and Projected Lights.

Arguments

Light::SHADOW_COLOR_MODE getShadowColorTextureMode ( ) const#

Returns the current type of texture used to define light distribution.
Notice
This feature is available only for Omni Lights and Projected Lights. See description of the modes in the corresponding articles forOmni Lights and Projected Lights.

Return value

Current mode.

void setDynamicDepthTexture ( const Ptr<Texture> & texture ) #

Sets the dynamic depth texture for the light source. This texture is available for the following types of light sources:

Arguments

  • const Ptr<Texture> & texture - Depth texture to be used for the light source.

Ptr<Texture> getDynamicDepthTexture ( ) const#

Returns the current dynamic depth texture for the light source. This texture is available for the following types of light sources:

Return value

Current dynamic depth texture of the light source.

Ptr<Texture> getBakedDepthTexture ( ) const#

Returns the depth texture baked for the light source. This texture is available for Static light sources only.
Notice
Static lights with mixed shadow mode enabled use a mixture of dynamic and baked depth textures.

Return value

Baked depth texture for the light source.

void setShadowFilterMode ( Light::SHADOW_FILTER mode ) #

Sets the filtering mode to be used to reduce the stair-step effect for soft shadows making the edges smoother.

Arguments

Light::SHADOW_FILTER getShadowFilterMode ( ) const#

Returns the current filtering mode used to reduce the stair-step effect for soft shadows making the edges smoother.

Return value

Current filtering mode used, one of SHADOW_FILTER_* values.

void setShadowFilter ( float filter ) #

Sets filtering intensity for the selected mode.
Notice
This value is ignored when filtering mode is set to disabled.

Arguments

  • float filter - Filtering intensity for the selected mode. The higher the value the less noticeable the stair-step effect at the edges of shadows will be. The default value is 1.0f.

float getShadowFilter ( ) const#

Returns the current filtering intensity for the selected mode.

Return value

Filtering intensity for the selected mode. The higher the value the less noticeable the stair-step effect at the edges of shadows will be. The default value is 1.0f.

void setShadowPenumbraMode ( Light::SHADOW_PENUMBRA mode ) #

Sets the global quality mode to be used for rendering penumbra from the light source. This mode enables simulation of real-world shadows by keeping sharp contact shadows closer to the base and softening the farther the shadow stretches away. Higher values produce softer shadows. The default value is SHADOW_PENUMBRA_GLOBAL.

Arguments

Light::SHADOW_PENUMBRA getShadowPenumbraMode ( ) const#

Returns the current global quality mode used for rendering penumbra from the light source. This mode enables simulation of real-world shadows by keeping sharp contact shadows closer to the base and softening the farther the shadow stretches away. Higher values produce softer shadows. The default value is SHADOW_PENUMBRA_GLOBAL.

Return value

Current quality mode used for penumbra rendering, one of the SHADOW_PENUMBRA_* variables.

void setShadowPenumbra ( float penumbra ) #

Sets intensity of penumbra for the selected mode.
Notice
This value is ignored when penumbra rendering mode is set to disabled.

Arguments

  • float penumbra - Intensity of penumbra for the selected mode:
    • Low values correspond to sharper shadow edges.
    • Higher values increase penumbra size.
    The default value is 0.0f.

float getShadowPenumbra ( ) const#

Returns the current intensity of penumbra for the selected mode.

Return value

Current intensity of penumbra for the selected mode:
  • Low values correspond to sharper shadow edges.
  • Higher values increase penumbra size.
The default value is 0.0f.

void setShadowScreenSpaceStepSizeFarDistance ( float distance ) #

Sets the distance from the camera after which the Far Step Size shall be used for screen-space shadows calculation. You can set different Step Size and Threshold values for objects located near the camera and far away from it. Thus, full-scale shadows will be rendered for large objects located far away, while within the close distance range only shadows cast by small objects will be rendered. This feature is especially useful for locations where details are required for both short and long-distance ranges.

Arguments

float getShadowScreenSpaceStepSizeFarDistance ( ) const#

Returns the current distance from the camera after which the Far Step Size is used for screen-space shadows calculation. You can set different Step Size and Threshold values for objects located near the camera and far away from it. Thus, full-scale shadows will be rendered for large objects located far away, while within the close distance range only shadows cast by small objects will be rendered. This feature is especially useful for locations where details are required for both short and long-distance ranges.

Return value

Distance from the camera (in units) after which the Far Step Size shall be used for screen-space shadows calculation. For the space between Near Step Size Distance and Far Step Size Distance, the step size value is interpolated from Near Step Size to Far Step Size.

void setShadowScreenSpaceStepSizeNearDistance ( float distance ) #

Sets the distance from the camera up to which the Near Step Size shall be used for screen-space shadows calculation. You can set different Step Size and Threshold values for objects located near the camera and far away from it. Thus, full-scale shadows will be rendered for large objects located far away, while within the close distance range only shadows cast by small objects will be rendered. This feature is especially useful for locations where details are required for both short and long-distance ranges.

Arguments

  • float distance - Distance from the camera (in units) up to which the Near Step Size shall be used for screen-space shadows calculation.

float getShadowScreenSpaceStepSizeNearDistance ( ) const#

Returns the current distance from the camera up to which the Near Step Size is used for screen-space shadows calculation. You can set different Step Size and Threshold values for objects located near the camera and far away from it. Thus, full-scale shadows will be rendered for large objects located far away, while within the close distance range only shadows cast by small objects will be rendered. This feature is especially useful for locations where details are required for both short and long-distance ranges.

Return value

Distance from the camera (in units) up to which the Near Step Size is used for screen-space shadows calculation.

void setShadowScreenSpaceThresholdNearDistance ( float distance ) #

Sets the current distance from the camera up to which the Near Threshold shall be used for screen-space shadows calculation. You can set different Step Size and Threshold values for objects located near the camera and far away from it. Thus, full-scale shadows will be rendered for large objects located far away, while within the close distance range only shadows cast by small objects will be rendered. This feature is especially useful for locations where details are required for both short and long-distance ranges.

Arguments

  • float distance - Distance from the camera (in units) up to which the Near Threshold shall be used for screen-space shadows calculation.

float getShadowScreenSpaceThresholdNearDistance ( ) const#

Returns the current distance from the camera up to which the Near Threshold is used for screen-space shadows calculation. You can set different Step Size and Threshold values for objects located near the camera and far away from it. Thus, full-scale shadows will be rendered for large objects located far away, while within the close distance range only shadows cast by small objects will be rendered. This feature is especially useful for locations where details are required for both short and long-distance ranges.

Return value

Distance from the camera (in units) up to which the Near Threshold is used for screen-space shadows calculation.

void setShadowScreenSpaceThresholdFarDistance ( float distance ) #

Sets the distance from the camera after which the Far Threshold shall be used for screen-space shadows calculation. You can set different Step Size and Threshold values for objects located near the camera and far away from it. Thus, full-scale shadows will be rendered for large objects located far away, while within the close distance range only shadows cast by small objects will be rendered. This feature is especially useful for locations where details are required for both short and long-distance ranges.

Arguments

float getShadowScreenSpaceThresholdFarDistance ( ) const#

Sets the distance from the camera after which the Far Threshold is used for screen-space shadows calculation. You can set different Step Size and Threshold values for objects located near the camera and far away from it. Thus, full-scale shadows will be rendered for large objects located far away, while within the close distance range only shadows cast by small objects will be rendered. This feature is especially useful for locations where details are required for both short and long-distance ranges.

Return value

Distance from the camera (in units) after which the Far Threshold is used for screen-space shadows calculation. For the space between Near Threshold Distance and Far Threshold Distance, the threshold value is interpolated from Near Threshold to Far Threshold.

void setShadowScreenSpaceTranslucentDepth ( float depth ) #

Sets the Translucent Depth value for Screen-Space Shadows indicating how much the light passes through screen-space shadows on translucent materials (with Translucence option enabled).

Arguments

  • float depth - New Translucent Depth value to be set for Screen-Space Shadows:
    The higher the value the deeper the light penetrates translucent objects shifting the shadow.

float getShadowScreenSpaceTranslucentDepth ( ) const#

Returns the current Translucent Depth value for Screen-Space Shadows indicating how much the light passes through screen-space shadows on translucent materials (with Translucence option enabled).

Return value

Current Translucent Depth value set for Screen-Space Shadows:
The higher the value the deeper the light penetrates translucent objects shifting the shadow.

void setShadowScreenSpaceTranslucentDepthPerspectiveCompensation ( float compensation ) #

Sets a new Perspective Compensation value for Screen-Space Shadows, that defines whether the Translucent Depth parameter depends on the distance from the camera to the surface or not. This effect is used to make tree crowns located far from the camera more translucent than the grass nearby.

Arguments

  • float compensation - New Perspective Compensation value to be set for the Translucent Depth parameter of Screen-Space Shadows:
    • 0 - the Translucent Depth value does not depend on the distance from the camera to the surface.
    • 1 - the Translucent Depth value linearly depends on the distance from the camera to the surface.

float getShadowScreenSpaceTranslucentDepthPerspectiveCompensation ( ) const#

Returns the current Perspective Compensation value for Screen-Space Shadows, that defines whether the Translucent Depth parameter depends on the distance from the camera to the surface or not. This effect is used to make tree crowns located far from the camera more translucent than the grass nearby.

Return value

Current Perspective Compensation value set for the Translucent Depth parameter of Screen-Space Shadows:
  • 0 - the Translucent Depth value does not depend on the distance from the camera to the surface.
  • 1 - the Translucent Depth value linearly depends on the distance from the camera to the surface.

void setShadowScreenSpaceTranslucentViewBias ( float bias ) #

Sets a new View Bias value for Screen-Space Shadows, that controls an effect of fuzziness for vegetation (e.g. simulating leaves of saintpaulia or providing a sponge-like look for tree crowns).

Arguments

  • float bias - New View Bias value to be set for Screen-Space Shadows:
    • By the value of 0 the effect is disabled
    • the value of 1 corresponds to the maximum effect.

float getShadowScreenSpaceTranslucentViewBias ( ) const#

Returns the current Translucent View Bias value for Screen-Space Shadows, that controls an effect of fuzziness for vegetation (e.g. simulating leaves of saintpaulia or providing a sponge-like look for tree crowns).

Return value

Current Translucent View Bias value for Screen-Space Shadows:
  • By the value of 0 the effect is disabled
  • the value of 1 corresponds to the maximum effect.
Last update: 2023-06-23
Build: ()