Class LightBase

java.lang.Object
javafx.scene.Node
javafx.scene.LightBase
All Implemented Interfaces:
Styleable, EventTarget
Direct Known Subclasses:
AmbientLight, DirectionalLight, PointLight
public abstract class LightBase extends Node
The LightBase class is the base class for all objects that represent a form of light source. All light types share the following common properties that are defined in this class:
  • color - the color of the light source
  • scope - a list of nodes the light source affects
  • exlusionScope - a list of nodes the light source does not affect
In addition to these, each light type supports a different set of properties, summarized in the following table:
Summary of Light types by attributes
Light type Rotation and Direction Location and Attenuation
AmbientLight ✗ ✗
DirectionalLight ✓ ✗
PointLight ✗ ✓
SpotLight* ✓ ✓
* Supports spotlight attenuation factors as described in its class docs.

An application cannot add its own light types. Extending LightBase directly may lead to an UnsupportedOperationException being thrown.

All light types are not affected by scaling and shearing transforms.

Color

A light source produces a light of a single color. The appearance of an object illuminated by the light is a result of the color of the light and the material the object is made of. For example, for a blue light, a white object will appear blue, a black object will appear black, and a (255, 0, 255)-colored object will appear blue, as the light "selects" only the blue component of the material color. The mathematical definition of the material-light interaction is available in PhongMaterial.

See also the implementation notes section.

Scopes

A light has a scope list and an exclusionScope list that define which nodes are illuminated by it and which aren't. A node can exist in only one of the lists: if it is added to one, it is silently removed from the other. If a node does not exist in any list, it inherits its affected state from its parent, recursively. An exception to this is that a light with an empty scope affects all nodes in its scene/subscene implicitly (except for those in its exlusionScope) as if the root of the scene is in the scope.

The exlusionScope is useful only for nodes that would otherwise be in scope of the light. Excluding a node is a convenient alternative to traversing the scenegraph hierarchy and adding all of the other nodes to the light's scope. Instead, the scope can remain wide, and specific nodes can be excluded with the exclusion scope.

Direction

The direction of the light is defined by the direction vector property of the light. The light's direction can be rotated by setting a rotation transform on the light. For example, if the direction vector is (1, 1, 1) and the light is not rotated, it will point in the (1, 1, 1) direction, and if the light is rotated 90 degrees on the y axis, it will point in the (1, 1, -1) direction.

Light types that do not have a direction are not affected by rotation transforms.

Distance Attenuation

Any pixel within the range of the light will be illuminated by it (unless it belongs to a Shape3D outside of its scope). The distance is measured from the light's position to the pixel's position, and is checked to be within the maximum range of the light, as defined by its maxRange property. The light's position can be changed by setting a translation transform on the light.

The light's intensity can be set to change over distance by attenuating it. The attenuation formula

attn = 1 / (ca + la * dist + qa * dist^2)

defines 3 coefficients: ca, la, and qa, which control the constant, linear, and quadratic behaviors of intensity falloff over distance, respectively. The effective color of the light at a given point in space is color * attn. It is possible, albeit unrealistic, to specify negative values to attenuation coefficients. This allows the resulting attenuation factor to be negative, which results in the light's color being subtracted from the material color instead of added to it, thus creating a "shadow caster".

For a realistic effect, maxRange should be set to a distance at which the attenuation is close to 0, as this will give a soft cutoff.

Light types that are not distance-attenuated are not affected by translation transforms. For these types, a decrease in intensity can be achieved by using a darker color.

Note: this is a conditional feature. See ConditionalFeature.SCENE3D for more information.

Implementation Note:
The following applies to the color property of the light:
  1. A black colored light is ignored since its contribution is 0.
  2. The transparency (alpha) component of a light is ignored.
These behaviors are not specified and could change in the future.
Since:
JavaFX 8.0

  • Property Details

  • Constructor Details

    • LightBase

      protected LightBase()
      Creates a new instance of LightBase class with a default Color.WHITE light source.

    • LightBase

      protected LightBase(Color color)
      Creates a new instance of LightBase class using the specified color.
      Parameters:
      color - the color of the light source

  • Method Details

    • setColor

      public final void setColor(Color value)
      Sets the value of the color property.
      Property description:
      Specifies the color of light source.
      Default value:
      null
      Parameters:
      value - the value for the color property
      See Also:

    • getColor

      public final Color getColor()
      Gets the value of the color property.
      Property description:
      Specifies the color of light source.
      Default value:
      null
      Returns:
      the value of the color property
      See Also:

    • colorProperty

      public final ObjectProperty<Color> colorProperty()
      Specifies the color of light source.
      Default value:
      null
      Returns:
      the color property
      See Also:

    • setLightOn

      public final void setLightOn(boolean value)
      Sets the value of the lightOn property.
      Property description:
      Defines the light on or off.
      Default value:
      true
      Parameters:
      value - the value for the lightOn property
      See Also:

    • isLightOn

      public final boolean isLightOn()
      Gets the value of the lightOn property.
      Property description:
      Defines the light on or off.
      Default value:
      true
      Returns:
      the value of the lightOn property
      See Also:

    • lightOnProperty

      public final BooleanProperty lightOnProperty()
      Defines the light on or off.
      Default value:
      true
      Returns:
      the lightOn property
      See Also:

    • getScope

      public ObservableList<Node> getScope()
      Gets the list of nodes that specifies the hierarchical scope of this light. Any Shape3Ds in this list or under a Parent in this list are affected by this light, unless a closer parent exists in the exclusionScope list. If the list is empty, all nodes under the light's scene/subscene are affected by it (unless they are in the exclusionScope).
      Returns:
      the list of nodes that specifies the hierarchical scope of this light
      See Also:

    • getExclusionScope

      public ObservableList<Node> getExclusionScope()
      Gets the list of nodes that specifies the hierarchical exclusion scope of this light. Any Shape3Ds in this list or under a Parent in this list are not affected by this light, unless a closer parent exists in the scope list.
      This is a convenience list for excluding nodes that would otherwise be in scope of the light.
      Returns:
      the list of nodes that specifies the hierarchical exclusion scope of this light
      Since:
      13
      See Also: