Unigine::Light Class

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

Members

---

Ptr<Light> cast(const Ptr<Node> & node)

Casts a Light out of the Node instance.

Arguments

• const Ptr<Node> & node - Pointer to Node.

Return value

Pointer to Light.

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

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.

Arguments

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

Math::vec4 getColor()

Returns the color of the light source. The default is opaque white, (1, 1, 1, 1).

Return value

Color of the light source in the RGBA format.

void setDepthTexture(const Ptr<Texture> & texture)

Sets the depth texture (shadow map) for the light source.

Arguments

• const Ptr<Texture> & texture - Depth texture smart pointer.

Ptr<Texture> getDepthTexture()

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

Return value

Depth texture smart pointer.

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

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

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.

Ptr<Light> getLight()

Returns a light pointer.

Return value

The light pointer.

void setLightMask(int mask)

Updates a light mask for the surface. For the surface to be illuminated by the light source, its light mask must match the mask of the light source.

Arguments

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

int getLightMask()

Returns a light mask of the surface. For the surface to be illuminated by the light source, its light mask must match the mask of the light source.

Return value

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

void setRenderTransparent(int transparent)

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

Arguments

• int transparent - 1 to render the light from the source on transparent objects, 0 not to render.

int getRenderTransparent()

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

Return value

1 if the light from the source is rendered on transparent objects; otherwise, 0.

void setRenderWater(int water)

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

Arguments

• int water - 1 to render the light from the source on water objects, 0 not to render.

int getRenderWater()

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

Return value

1 if the light from the source is rendered on water objects; otherwise, 0.

void setShadow(int shadow)

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

Arguments

• int shadow - 1 to cast shadows, 0 not to cast.

int getShadow()

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

Return value

1 if the light source casts shadows; otherwise, 0.

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

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

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

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(int 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

• int resolution - New shadow map size:
  • -1  — default (512×512)
  • 0  — 64×64
  • 1  — 128×128
  • 2  — 256×256
  • 3  — 512×512
  • 4  — 1024×1024
  • 5  — 2048×2048
  • 6  — 4096×4096

int getShadowResolution()

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

Return value

Shadow map size:

• -1  — default (512×512)
• 0  — 64×64
• 1  — 128×128
• 2  — 256×256
• 3  — 512×512
• 4  — 1024×1024
• 5  — 2048×2048
• 6  — 4096×4096

void setShadowSoftness(float softness)

Updates the size of the blur applied to the shadow edge.

• Low softness values corresponds to the crisp and sharp shadow edges.
• Higher softness values serve to accentuate the effect of soft indirect lighting.

Arguments

• float softness - New softness of shadows.

float getShadowSoftness()

Returns the size of the blur applied to the shadow edge.

• Low softness values corresponds to the crisp and sharp shadow edges.
• Higher softness values serve to accentuate the effect of soft indirect lighting.

Return value

Softness of shadows.

void setShadowScreenSpace(int 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

• int space - 1 to enable screen-space shadows for the light source, 0 to disable. The default value is 0.

int getShadowScreenSpace()

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

1 if screen-space shadows for the light source are enabled; otherwise, 0.

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

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

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

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

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

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

Return value

Screen-space shadows softness.

void setShadowScreenSpaceStepSize(float size)

Sets the size of the step used to calculate screen-space shadows for the light source. This parameter can be used to adjust calculation of shadows for specific sizes of objects.

Arguments

• float size - Step size. The default value is 0.5.
  Notice

  Screen-space shadows must be enabled, see the setShadowScreenSpace() method.

float getShadowScreenSpaceStepSize()

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

Return value

Step size.

void setShadowScreenSpaceThreshold(float threshold)

Sets the threshold value used to calculate screen-space shadows for the light source. This parameter is used to adjust the look of screen-space shadows.

Arguments

• float threshold - Screen-space shadows threshold. The default value is 1.0.
  Notice

  Screen-space shadows must be enabled, see the setShadowScreenSpace() method.

float getShadowScreenSpaceThreshold()

Returns the current threshold value used to calculate screen-space shadows for the light source.

Return value

Screen-space shadows threshold.

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

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

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 setFlareEnabled(int enabled)

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

Arguments

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

int isFlareEnabled()

Returns a value indicating if the per-light lens flare effect is enabled for the light source.

Return value

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

void allocateFlareBillboards(int num)

Allocate a buffer for a given number of flare billboards to be created. With this function, memory can be allocated once rather than in chunks, making the creation faster.

Arguments

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

void addFlareBillboard()

Add a new billboard for the per-light lens flare effect.

Ptr<LightFlareBillboard> getFlareBillboard(int num)

Returns the given billboard from the list of the ones used for the per-light lens flare effect.

Arguments

• int num - Billboard number.

Return value

Light flare billboard smart pointer.

void cloneFlareBillboard(int num)

Creates a clone of the billboard with a given number in the list of billboard used for the per-light lens flare effect.

Arguments

• int num - Number of billboard to be cloned.

void removeFlareBillboard(int num)

Removes the billboard with a given number from the list of billboard used for the per-light lens flare effect.

Arguments

• int num - Number of billboard to be removed.

int getNumFlareBillboards()

Returns the total number of billboards used for the per-light lens flare effect.

Return value

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

void clearFlareBillboards()

Clears the list of billboards used for the per-light lens flare effect.

void setFlareUseLightColor(int enabled)

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.

Arguments

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

int isFlareUseLightColor()

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.

Return value

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

void setFlareOcclusionFade(float fade)

Sets the lens flare occlusion fade value for the cases when the light source becomes occluded by an object.

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 getFlareOcclusionFade()

Returns the current lens flare occlusion fade value for the cases when the light source becomes occluded by an object.

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 setFlareOcclusionFadeBorder(float fade)

Sets the lens flare occlusion fade value for the cases when the light source becomes occluded by the edges of the screen.

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 getFlareOcclusionFadeBorder()

Returns the current lens flare occlusion fade value for the cases when the light source becomes occluded by the edges of the screen.

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 setFlareWorldPositionOffset(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.

Arguments

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

Math::vec3 getFlareWorldPositionOffset()

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.

Return value

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

void setFlareTextureName(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 billboards used to render lens flares.

Arguments

• const char * name - Texture name.

const char * getFlareTextureName()

Returns the name of the texture currently used for the per-light lens flare effect. This texture stores images for all billboards used to render lens flares.

Return value

Texture name.

---

int SHAPE_CAPSULE

Description

A capsule-shaped light source.

int SHAPE_POINT

Description

A point light source (light is emitted by an infinitely small point).

int SHAPE_RECTANGLE

Description

A rectangular light source. Such light source produces the light and the speck in a form of a rounded rectangle.

int SHAPE_SPHERE

Description

A sphere-shaped light source.

int MODE_BAKED

Description

Baked light rendering mode: the light is rendered as a static one, only GI from it is baked. Such lights are more performance-friendly, but moving them will not affect lighting at all. This mode is recommended for light sources, which always remain at their initial position at run time.

int MODE_MIXED

Description

Mixed light rendering mode: the light is rendered dynamically and GI from it is baked to a probe.

int MODE_REALTIME

Description

Real-time light rendering mode: the light is rendered as a fully dynamic one without baking GI from it. Such lights are more realistic but have greater impact on performance. This mode is recommended for light sources, which are going to be moved at run time.