Most visited

Recently visited

DirectionalLight

public class DirectionalLight
extends Light

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


DirectionalLight is a Light that illuminates all objects in the Scene from the same direction with constant intensity. Because the intensity is constant, there is no attenuation of a DirectionalLight and the position of the Node it is in has no impact.

DirectionalLight is meant to emulate powerful, far-away light sources like the sun.

DirectionalLight can cast shadows. These shadows are cast using an orthographic projection (e.g. the size of the shadows does not change as the shadow casters' distance from the light changes). This best simulates shadows cast from light sources like the sun.

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

Summary

Nested classes

class DirectionalLight.DirectionalLightBuilder<R extends Light, B extends LightBuilder<R, B>>

Builder for creating DirectionalLight.DirectionalLightBuilder objects. 

Public constructors

DirectionalLight()

Construct a new DirectionalLight with default values: white color, pointing in the negative Z direction, and normal intensity (1000).

DirectionalLight(long color, float intensity, Vector direction)

Construct a new DirectionalLight with the given color, intensity, and direction.

Public methods

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

Builder for building DirectionalLight.DirectionalLightBuilder objects.

boolean getCastsShadow()

Returns true if this DirectionalLight casts shadows.

Vector getDirection()

Get the direction of this DirectionalLight.

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.

Vector getShadowOrthographicPosition()

Return the center of the area to be shadowed by this light.

float getShadowOrthographicSize()

Return the size of the area to be shadowed by this light.

void setCastsShadow(boolean castsShadow)

Set to true to make this DirectionalLight cast shadows.

void setDirection(Vector direction)

Set the direction of the DirectionalLight.

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.

void setShadowOrthographicPosition(Vector position)

Set the center of the shadow map created by this directional light.

void setShadowOrthographicSize(float orthographicSize)

The orthographic size determines the width and height of the area, centered at shadowOrthographicPosition, for which shadows will be computed.

Public constructors

DirectionalLight

DirectionalLight ()

Construct a new DirectionalLight with default values: white color, pointing in the negative Z direction, and normal intensity (1000).

DirectionalLight

DirectionalLight (long color, 
                float intensity, 
                Vector direction)

Construct a new DirectionalLight with the given color, intensity, and direction.

Parameters
color long: The Color of the light.

intensity float: The intensity, where 1000 is normal intensity.

direction Vector: The direction of the light as a Vector.

Public methods

builder

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

Builder for building DirectionalLight.DirectionalLightBuilder objects.

Returns
DirectionalLightBuilder<? extends Light, ? extends LightBuilder>

getCastsShadow

boolean getCastsShadow ()

Returns true if this DirectionalLight casts shadows.

Returns
boolean True if this light casts shadows.

getDirection

Vector getDirection ()

Get the direction of this DirectionalLight.

Returns
Vector The direction 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.

getShadowOrthographicPosition

Vector getShadowOrthographicPosition ()

Return the center of the area to be shadowed by this light.

Returns
Vector The center of the shadow projection.

getShadowOrthographicSize

float getShadowOrthographicSize ()

Return the size of the area to be shadowed by this light.

Returns
float The shadow orthographic size.

setCastsShadow

void setCastsShadow (boolean castsShadow)

Set to true to make this DirectionalLight 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 DirectionalLight.

Parameters
direction Vector: The direction 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 shadowOrthographicPosition in the direction of the light.

The shadow bounds constructed from this property, shadowNearZ, and shadowOrthographicSize 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 shadowOrthographicPosition in the direction of the light.

The shadow bounds constructed from this property, shadowFarZ, and shadowOrthographicSize 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.

setShadowOrthographicPosition

void setShadowOrthographicPosition (Vector position)

Set the center of the shadow map created by this directional light. Although directional lights have no center, the shadow map must have a center.

Parameters
position Vector: The center of the shadow projection.

setShadowOrthographicSize

void setShadowOrthographicSize (float orthographicSize)

The orthographic size determines the width and height of the area, centered at shadowOrthographicPosition, for which shadows will be computed. More specifically, it determines the size of the area that is rendered to the shadow map.

A larger value means more of the scene will be shadowed, but at lower resolution.

The shadow bounds constructed from this property, shadowFarZ, and shadowOrthographicSize should be kept as tight as possible to maximize the resolution of shadows.

The default value is 20.

Parameters
orthographicSize float: The orthographic size for the shadow projection.

Hooray!