Unigine.Light Class
| 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#
SHADOW_PENUMBRA#
| Name | Description |
|---|---|
| GLOBAL = -1 | Quality mode of shadow penumbra that is set globally for all light sources is applied. |
| DISABLED = GLOBAL + 1 | Shadow penumbra is disabled. |
| LOW = DISABLED + 1 | Low quality of shadow penumbra. |
| MEDIUM = LOW + 1 | Medium quality of shadow penumbra. |
| HIGH = MEDIUM + 1 | High quality of shadow penumbra. |
| ULTRA = HIGH + 1 | Ultra quality of shadow penumbra. |
SHADOW_FILTER#
| Name | Description |
|---|---|
| GLOBAL = -1 | Quality mode of shadow filtering that is set globally is applied. |
| DISABLED = GLOBAL + 1 | Shadow filtering is disabled. |
| LOW = DISABLED + 1 | Low quality of shadow filtering. |
| MEDIUM = LOW + 1 | Medium quality of shadow filtering. |
| HIGH = MEDIUM + 1 | High quality of shadow filtering. |
| ULTRA = HIGH + 1 | Ultra quality of shadow filtering. |
COLOR_MODE#
| Name | Description |
|---|---|
| CLASSIC = 0 | Classic color calculation mode, resulting color is defined by Color. |
| TEMPERATURE = 1 | Physically based color calculation mode, resulting color is calculated as: ColorFilter * (color obtained using the ColorTemperature value). |
SHADOW_MODE#
SHADOW_COLOR_MODE#
| Name | Description |
|---|---|
| IES = 0 | Light distibution is defined by the IES profile. |
| SIMPLE = 1 | An arbitrary 2D texture is projected onto the scene. |
MODE#
SHAPE#
Properties
float ShadowScreenSpaceSoftness#
The softness value of the screen-space shadows for the light source. Higher values provide softer shadows.
Notice
Screen-space shadows must be enabled, see the setShadowScreenSpace() method.
float ShadowScreenSpaceThresholdNear#
The 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.
Notice
Screen-space shadows must be enabled, see the setShadowScreenSpace() method.
float ShadowScreenSpaceStepSizeNear#
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.
Notice
Screen-space shadows must be enabled, see the setShadowScreenSpace() method.
float ShadowScreenSpaceNoiseStep#
The intensity of the step noise used to calculate screen-space shadows for the light source. Higher values reduce the banding effect more. However, this option significantly affects performance.
Notice
Screen-space shadows must be enabled, see the setShadowScreenSpace() method.
float ShadowScreenSpaceNoiseRay#
The intensity of the ray noise used to calculate screen-space shadows for the light source. Higher values reduce the banding effect more. However, this option significantly affects performance.
Notice
Screen-space shadows must be enabled, see the setShadowScreenSpace() method.
int ShadowScreenSpaceNumSteps#
The number of steps used to calculate screen-space shadows for the light source. Higher values, improve the quality of shadows more. However, this option significantly affects performance.
Notice
Screen-space shadows must be enabled, see the setShadowScreenSpace() method.
int ShadowScreenSpaceNumRays#
The number of rays used to calculate screen-space shadows for the light source. Higher values, improve the quality of shadows more. However, this option significantly affects performance.
Notice
Screen-space shadows must be enabled, see the setShadowScreenSpace() method.
bool ShadowScreenSpace#
The value indicating if screen-space shadows for the light source are enabled. With this option enabled, penumbras from the light source are calculated using the ray tracing algorithm.
Texture ShadowTexture#
The depth texture (shadow map) of the light source.
Texture DynamicShadowColorTexture#
The shadow texture of the light source used to render translucent shadows: G-channel stores depth values, R-channel - transparency values.
Texture BakedDepthTexture#
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.
string BakedDepthTextureFilePath#
The path to a baked depth texture file, 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. This texture is baked automatically via the Editor or using bake() or bakeAll() methods.
Texture DynamicDepthTexture#
The dynamic depth texture for the light source. This texture is available for the following types of light sources:
- Dynamic lights.
- Static lights with mixed shadow mode enabled, that use a mixture of dynamic and baked depth textures.
float ShadowPenumbra#
The intensity of penumbra for the selected mode.
Notice
This value is ignored when penumbra rendering mode is set to disabled.
Light.SHADOW_PENUMBRA ShadowPenumbraMode#
The 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.
float ShadowFilter#
The filtering intensity for the selected mode.
Notice
This value is ignored when filtering mode is set to disabled.
Light.SHADOW_FILTER ShadowFilterMode#
The filtering mode used to reduce the stair-step effect for soft shadows making the edges smoother.
Light.SHADOW_MODE ShadowMode#
The 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.
Light.MODE Mode#
The rendering mode for the light source. This option determines whether the light is to be rendered as a dynamic or static one.
float ShadowNormalBias#
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.
float ShadowBias#
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.
Light.SHADOW_RESOLUTION ShadowResolution#
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.
bool Shadow#
The value indicating if the light source casts shadows from surfaces with the Cast Shadow material.
float AttenuationPower#
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 is sharp.
vec4 ColorFilter#
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 color mode is set to Temperature.
float ColorTemperature#
The light source temperature used for light color calculation.
float Lux#
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.
float Intensity#
The multiplier of 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.
vec4 Color#
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.
Light.COLOR_MODE ColorMode#
The 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).
int ViewportMask#
The bit mask for rendering into the viewport. The light is rendered, if its mask matches the player's one.
int ShadowMask#
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):
- Shadow mask of the surface of the object
- Shadow mask of the material assigned to this surface
bool RenderOnTransparent#
The value indicating if the light from the source is rendered on transparent objects.
bool RenderOnWater#
The value indicating if the light from the source is rendered on water objects.
float FadeDistance#
The distance, at which the light source gradually disappears. This parameter enables to render the light with decreasing radiance after the Visible distance is past.
float ShadowDistance#
The distance, at which shadow from the light source starts fading out to nonexistence.
float VisibleDistance#
The distance, at which the light source starts fading. If the distance is set to infinity, the source is always rendered.
int NumLensFlares#
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.
bool LensFlaresUseLightColor#
The 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.
vec3 LensFlaresWorldPositionOffset#
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.
float LensFlaresOcclusionFadeBorder#
The lens flare occlusion fade border 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.
float LensFlaresOcclusionFade#
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.
float LensFlaresIntensity#
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.
string LensFlaresTextureName#
The name of the texture 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.
bool LensFlaresEnabled#
The 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.
- The maximum number of per-light lens flares that can be rendered is 32.
float ShadowScreenSpaceThresholdFar#
The 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.
float ShadowScreenSpaceThresholdFarDistance#
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.
float ShadowScreenSpaceThresholdNearDistance#
The 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.
float ShadowScreenSpaceStepSizeFar#
The 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.
float ShadowScreenSpaceStepSizeNearDistance#
The 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.
float ShadowScreenSpaceStepSizeFarDistance#
The 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.
Light.SHADOW_COLOR_MODE ShadowColorTextureMode#
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.
float ShadowScreenSpaceTranslucentViewBias#
The 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).
float ShadowScreenSpaceTranslucentDepthPerspectiveCompensation#
The 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.
float ShadowScreenSpaceTranslucentDepth#
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).
float ShadowFadeDistance#
The distance from the camera after which the shadows gradually disappear.
Members
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.
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 instance.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.
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.
vec4 CalculateFinalColor ( ) #
Calculates the final color of the light source depending on the calculation mode used.Return value
Resulting color of the light source.bool SaveStateLight ( Stream stream ) #
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.ColorTemperature = 15000.0f;
// save state
Blob blob_state = new Blob();
light.SaveStateLight(blob_state);
// change the node state
light.ColorTemperature = 27000.0f;
// restore state
blob_state.SeekSet(0); // returning the carriage to the start of the blob
light.RestoreStateLight(blob_state);Arguments
- Stream stream - Stream instance.
Return value
true if the state of the light source is saved successfully; otherwise, false.bool RestoreStateLight ( 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.ColorTemperature = 15000.0f;
// save state
Blob blob_state = new Blob();
light.SaveStateLight(blob_state);
// change the node state
light.ColorTemperature = 27000.0f;
// restore state
blob_state.SeekSet(0); // returning the carriage to the start of the blob
light.RestoreStateLight(blob_state);Arguments
- Stream stream - Stream instance.
Return value
true if the state of the light source is restored successfully; otherwise, false.bool SaveStateLensFlares ( Stream stream ) #
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.LensFlaresIntensity = 0.75f;
// save state
Blob blob_state = new Blob();
lens_flare.SaveStateLensFlares(blob_state);
// change the node state
lens_flare.LensFlaresIntensity = 0.25f;
// restore state
blob_state.SeekSet(0); // returning the carriage to the start of the blob
lens_flare.RestoreStateLensFlares(blob_state);Arguments
- Stream stream - Stream instance.
Return value
true if the state of the per-light lens flare effect is saved successfully; otherwise, false.bool RestoreStateLensFlares ( 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.LensFlaresIntensity = 0.75f;
// save state
Blob blob_state = new Blob();
lens_flare.SaveStateLensFlares(blob_state);
// change the node state
lens_flare.LensFlaresIntensity = 0.25f;
// restore state
blob_state.SeekSet(0); // returning the carriage to the start of the blob
lens_flare.RestoreStateLensFlares(blob_state);Arguments
- Stream stream - Stream instance.
Return value
true if the state of the per-light lens flare effect is restored successfully; otherwise, false.Last update:
2024-12-13
Help improve this article
Was this article helpful?
(or select a word/phrase and press Ctrl+Enter)