Most visited

Recently visited

Spotlight

public class Spotlight
extends Light

java.lang.Object
   ↳ com.viro.core.Light
     ↳ com.viro.core.Spotlight


Spotlight is a Light that illuminates objects within a cone-shaped area, in a given direction, with decreasing intensity over distance.

Spotlight can cast shadows. These shadows are cast using an perspective projection (e.g. the size of the shadows changes as the shadow casters' distance from the light changes).

For an extended discussion on Lights, refer to the Lighting and Materials Guide.

Summary

Nested classes

class Spotlight.SpotlightBuilder<R extends Light, B extends LightBuilder<R, B>>

Builder for creating Spotlight objects. 

Public constructors

Spotlight()

Construct a new Spotlight with default values: white color, normal intensity, pointing in the negative Z direction and positioned at the origin of its parent Node.

Public methods

static SpotlightBuilder<? extends Light, ? extends LightBuilder> builder()

Builder for building Spotlight objects.

float getAttenuationEndDistance()

Get the attenuation end distance, which is the distance from the light at which no illumination will be received.

float getAttenuationStartDistance()

Get the attenuation start distance, which determines when the light starts attenuating.

boolean getCastsShadow()

Returns true if this Spotlight casts shadows.

Vector getDirection()

Get the direction of this Spotlight.

float getInnerAngle()

Get the inner angle, which is the angle from edge to edge of the 'full strength' light cone.

float getOuterAngle()

Get the outer angle, which is the angle from edge to edge of the 'attenuated' light cone.

Vector getPosition()

Get the position of this Spotlight.

float getShadowBias()

Return the amount of bias that is applied to the Z coordinate when performing shadow depth comparisons.

float getShadowFarZ()

Get the far clipping plane used when rendering shadows.

int getShadowMapSize()

Return the size of the texture map to which the shadowed portion of the scene will be rendered when computing shadows.

float getShadowNearZ()

Get the near clipping plane used when rendering shadows.

float getShadowOpacity()

Return the opacity of shadows cast from this Light.

void setAttenuationEndDistance(float attenuationEndDistance)

Set the attenuation end distance, which determines when the light drops to zero illumination.

void setAttenuationStartDistance(float attenuationStartDistance)

Set the attenuation start distance, which determines when the light begins to attenuate.

void setCastsShadow(boolean castsShadow)

Set to true to make this Spotlight cast shadows.

void setDirection(Vector direction)

Set the direction of the Spotlight.

void setInnerAngle(float innerAngle)

Set the inner angle, which is the angle from edge to edge of the 'full strength' light cone.

void setOuterAngle(float outerAngle)

Set the outer angle, which is the angle from edge to edge of the 'attenuated' light cone.

void setPosition(Vector position)

Set the position of this Spotlight within the coordinate system of its parent Node.

void setShadowBias(float shadowBias)

Set the amount of bias to apply to the Z coordinate when performing the shadow depth comparison.

void setShadowFarZ(float shadowFarZ)

Set the far clipping plane to use when rendering shadows.

void setShadowMapSize(int shadowMapSize)

Set the size of the shadow map used to cast shadows for this light.

void setShadowNearZ(float shadowNearZ)

Set the near clipping plane to use when rendering shadows.

void setShadowOpacity(float opacity)

The opacity of the shadow.

Public constructors

Spotlight

Spotlight ()

Construct a new Spotlight with default values: white color, normal intensity, pointing in the negative Z direction and positioned at the origin of its parent Node.

Public methods

builder

SpotlightBuilder<? extends Light, ? extends LightBuilder> builder ()

Builder for building Spotlight objects.

Returns
SpotlightBuilder<? extends Light, ? extends LightBuilder>

getAttenuationEndDistance

float getAttenuationEndDistance ()

Get the attenuation end distance, which is the distance from the light at which no illumination will be received.

Returns
float The attenuation end distance.

getAttenuationStartDistance

float getAttenuationStartDistance ()

Get the attenuation start distance, which determines when the light starts attenuating.

Returns
float The attenuation start distance.

getCastsShadow

boolean getCastsShadow ()

Returns true if this Spotlight casts shadows.

Returns
boolean True if this light casts shadows.

getDirection

Vector getDirection ()

Get the direction of this Spotlight.

Returns
Vector The direction as a Vector.

getInnerAngle

float getInnerAngle ()

Get the inner angle, which is the angle from edge to edge of the 'full strength' light cone.

Returns
float The inner angle in radians.

getOuterAngle

float getOuterAngle ()

Get the outer angle, which is the angle from edge to edge of the 'attenuated' light cone.

Returns
float The outer angle in radians.

getPosition

Vector getPosition ()

Get the position of this Spotlight.

Returns
Vector The positio as a Vector.

getShadowBias

float getShadowBias ()

Return the amount of bias that is applied to the Z coordinate when performing shadow depth comparisons.

Returns
float The shadow bias value.

getShadowFarZ

float getShadowFarZ ()

Get the far clipping plane used when rendering shadows. See setShadowFarZ(float) for discussion.

Returns
float The shadow far clipping plane.

getShadowMapSize

int getShadowMapSize ()

Return the size of the texture map to which the shadowed portion of the scene will be rendered when computing shadows.

Returns
int The size of the shadow map.

getShadowNearZ

float getShadowNearZ ()

Get the near clipping plane used when rendering shadows. See setShadowNearZ(float) for discussion.

Returns
float The shadow near clipping plane.

getShadowOpacity

float getShadowOpacity ()

Return the opacity of shadows cast from this Light.

Returns
float The shadow opacity.

setAttenuationEndDistance

void setAttenuationEndDistance (float attenuationEndDistance)

Set the attenuation end distance, which determines when the light drops to zero illumination. Objects positioned at a distance greater than the attenuation end distance from the light's position will receive no illumination from this light.

The default value is Float.MAX_VALUE.

Parameters
attenuationEndDistance float: The distance from the light at which no illumination will be received.

setAttenuationStartDistance

void setAttenuationStartDistance (float attenuationStartDistance)

Set the attenuation start distance, which determines when the light begins to attenuate. Objects positioned closer to the light than the attenuation start distance will receive the light's full illumination.

Objects positioned between the start and end distance will receive a proportion of the lights illumination, transitioning from full illumination to no illumination the further out from the lights position the object is.

The default value is 2.

Parameters
attenuationStartDistance float: The distance from the light at which the light begins to attenuate.

setCastsShadow

void setCastsShadow (boolean castsShadow)

Set to true to make this Spotlight cast shadows. Shadow construction is performance intensive; it is recommended to cast shadows from as few lights as possible to preserve frame-rate.

Parameters
castsShadow boolean: True to cast shadows, false to not cast shadows from the light.

setDirection

void setDirection (Vector direction)

Set the direction of the Spotlight.

Parameters
direction Vector: The direction as a Vector.

setInnerAngle

void setInnerAngle (float innerAngle)

Set the inner angle, which is the angle from edge to edge of the 'full strength' light cone. The lighting is at maximum intensity within this cone, and begins to attenuate outside of it.

The default is set to 0, which means only objects hitting the center of the spotlight will receive the light's full illumination. The illumination declines from innerAngle until reaching outerAngle.

Parameters
innerAngle float: The inner angle in radians.

setOuterAngle

void setOuterAngle (float outerAngle)

Set the outer angle, which is the angle from edge to edge of the 'attenuated' light cone. The lighting declines in strength between the inner angle and outer angle. Outside of the outer angle the light attenuates to zero, resulting in no light.

The default is set to PI / 4 radians (45 degrees).

Parameters
outerAngle float: The outer angle in radians.

setPosition

void setPosition (Vector position)

Set the position of this Spotlight within the coordinate system of its parent Node.

Parameters
position Vector: The position of as a Vector.

setShadowBias

void setShadowBias (float shadowBias)

Set the amount of bias to apply to the Z coordinate when performing the shadow depth comparison. This reduces shadow acne, but large biases can cause "peter panning".

The default value is 0.005.

Parameters
shadowBias float: The shadow bias value.

setShadowFarZ

void setShadowFarZ (float shadowFarZ)

Set the far clipping plane to use when rendering shadows. Shadows are only cast by and on surfaces closer than this plane.

This value defines the units away the far clipping plane is from the light's position, in the direction of the light.

The shadow bounds constructed from this property, shadowNearZ, and the light's cone (innerAngle and outerAngle) should be kept as tight as possible to maximize the resolution of shadows.

The default value is 20.

setShadowMapSize

void setShadowMapSize (int shadowMapSize)

Set the size of the shadow map used to cast shadows for this light.

Shadows are created by rendering the silhouettes of scene geometry onto a 2D image from the point of view of the light, then projecting that image onto the final view.

Larger shadow maps result in higher resolution shadows, but can have a higher memory and performance cost. Smaller shadow maps are faster but result in pixelated edges.

The default value is 1024.

Parameters
shadowMapSize int: The size of the shadow map.

setShadowNearZ

void setShadowNearZ (float shadowNearZ)

Set the near clipping plane to use when rendering shadows. Shadows are only cast by and on surfaces further away than this plane.

This value defines the units away the near clipping plane is from the light's position, in the direction of the light.

The shadow bounds constructed from this property, shadowNearZ, and the light's cone (innerAngle and outerAngle) should be kept as tight as possible to maximize the resolution of shadows.

The default value is 0.1.

setShadowOpacity

void setShadowOpacity (float opacity)

The opacity of the shadow. 1.0 creates a pitch black shadow. Lower opacities (approaching 0.0), make the shadow fainter and fainter.

Parameters
opacity float: The shadow opacity.

Hooray!