Module javafx.graphics
Package javafx.scene

# 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 Summary

  Properties
  Type
  Property
  Description
  `final ObjectProperty<Color>`
  `color`
  Specifies the color of light source.
  `final BooleanProperty`
  `lightOn`
  Defines the light on or off.

  ### Properties declared in class javafx.scene.Node

  `accessibleHelp, accessibleRoleDescription, accessibleRole, accessibleText, blendMode, boundsInLocal, boundsInParent, cacheHint, cache, clip, cursor, depthTest, disabled, disable, effectiveNodeOrientation, effect, eventDispatcher, focused, focusTraversable, hover, id, inputMethodRequests, layoutBounds, layoutX, layoutY, localToParentTransform, localToSceneTransform, managed, mouseTransparent, nodeOrientation, onContextMenuRequested, onDragDetected, onDragDone, onDragDropped, onDragEntered, onDragExited, onDragOver, onInputMethodTextChanged, onKeyPressed, onKeyReleased, onKeyTyped, onMouseClicked, onMouseDragEntered, onMouseDragExited, onMouseDragged, onMouseDragOver, onMouseDragReleased, onMouseEntered, onMouseExited, onMouseMoved, onMousePressed, onMouseReleased, onRotate, onRotationFinished, onRotationStarted, onScrollFinished, onScroll, onScrollStarted, onSwipeDown, onSwipeLeft, onSwipeRight, onSwipeUp, onTouchMoved, onTouchPressed, onTouchReleased, onTouchStationary, onZoomFinished, onZoom, onZoomStarted, opacity, parent, pickOnBounds, pressed, rotate, rotationAxis, scaleX, scaleY, scaleZ, scene, style, translateX, translateY, translateZ, viewOrder, visible`

- ## Field Summary

  ### Fields declared in class javafx.scene.Node

  `BASELINE_OFFSET_SAME_AS_HEIGHT`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `LightBase()`
  Creates a new instance of `LightBase` class with a default Color.WHITE light source.
  `protected`
  `LightBase(Color color)`
  Creates a new instance of `LightBase` class using the specified color.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final ObjectProperty<Color>`
  `colorProperty()`
  Specifies the color of light source.
  `final Color`
  `getColor()`
  Gets the value of the property color.
  `ObservableList<Node>`
  `getExclusionScope()`
  Gets the list of nodes that specifies the hierarchical exclusion scope of this light.
  `ObservableList<Node>`
  `getScope()`
  Gets the list of nodes that specifies the hierarchical scope of this light.
  `final boolean`
  `isLightOn()`
  Gets the value of the property lightOn.
  `final BooleanProperty`
  `lightOnProperty()`
  Defines the light on or off.
  `final void`
  `setColor(Color value)`
  Sets the value of the property color.
  `final void`
  `setLightOn(boolean value)`
  Sets the value of the property lightOn.

  ### Methods declared in class javafx.scene.Node

  `accessibleHelpProperty, accessibleRoleDescriptionProperty, accessibleRoleProperty, accessibleTextProperty, addEventFilter, addEventHandler, applyCss, autosize, blendModeProperty, boundsInLocalProperty, boundsInParentProperty, buildEventDispatchChain, cacheHintProperty, cacheProperty, clipProperty, computeAreaInScreen, contains, contains, cursorProperty, depthTestProperty, disabledProperty, disableProperty, effectiveNodeOrientationProperty, effectProperty, eventDispatcherProperty, executeAccessibleAction, fireEvent, focusedProperty, focusTraversableProperty, getAccessibleHelp, getAccessibleRole, getAccessibleRoleDescription, getAccessibleText, getBaselineOffset, getBlendMode, getBoundsInLocal, getBoundsInParent, getCacheHint, getClassCssMetaData, getClip, getContentBias, getCssMetaData, getCursor, getDepthTest, getEffect, getEffectiveNodeOrientation, getEventDispatcher, getId, getInitialCursor, getInitialFocusTraversable, getInputMethodRequests, getLayoutBounds, getLayoutX, getLayoutY, getLocalToParentTransform, getLocalToSceneTransform, getNodeOrientation, getOnContextMenuRequested, getOnDragDetected, getOnDragDone, getOnDragDropped, getOnDragEntered, getOnDragExited, getOnDragOver, getOnInputMethodTextChanged, getOnKeyPressed, getOnKeyReleased, getOnKeyTyped, getOnMouseClicked, getOnMouseDragEntered, getOnMouseDragExited, getOnMouseDragged, getOnMouseDragOver, getOnMouseDragReleased, getOnMouseEntered, getOnMouseExited, getOnMouseMoved, getOnMousePressed, getOnMouseReleased, getOnRotate, getOnRotationFinished, getOnRotationStarted, getOnScroll, getOnScrollFinished, getOnScrollStarted, getOnSwipeDown, getOnSwipeLeft, getOnSwipeRight, getOnSwipeUp, getOnTouchMoved, getOnTouchPressed, getOnTouchReleased, getOnTouchStationary, getOnZoom, getOnZoomFinished, getOnZoomStarted, getOpacity, getParent, getProperties, getPseudoClassStates, getRotate, getRotationAxis, getScaleX, getScaleY, getScaleZ, getScene, getStyle, getStyleableParent, getStyleClass, getTransforms, getTranslateX, getTranslateY, getTranslateZ, getTypeSelector, getUserData, getViewOrder, hasProperties, hoverProperty, idProperty, inputMethodRequestsProperty, intersects, intersects, isCache, isDisable, isDisabled, isFocused, isFocusTraversable, isHover, isManaged, isMouseTransparent, isPickOnBounds, isPressed, isResizable, isVisible, layoutBoundsProperty, layoutXProperty, layoutYProperty, localToParent, localToParent, localToParent, localToParent, localToParent, localToParentTransformProperty, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToSceneTransformProperty, localToScreen, localToScreen, localToScreen, localToScreen, localToScreen, lookup, lookupAll, managedProperty, maxHeight, maxWidth, minHeight, minWidth, mouseTransparentProperty, nodeOrientationProperty, notifyAccessibleAttributeChanged, onContextMenuRequestedProperty, onDragDetectedProperty, onDragDoneProperty, onDragDroppedProperty, onDragEnteredProperty, onDragExitedProperty, onDragOverProperty, onInputMethodTextChangedProperty, onKeyPressedProperty, onKeyReleasedProperty, onKeyTypedProperty, onMouseClickedProperty, onMouseDragEnteredProperty, onMouseDragExitedProperty, onMouseDraggedProperty, onMouseDragOverProperty, onMouseDragReleasedProperty, onMouseEnteredProperty, onMouseExitedProperty, onMouseMovedProperty, onMousePressedProperty, onMouseReleasedProperty, onRotateProperty, onRotationFinishedProperty, onRotationStartedProperty, onScrollFinishedProperty, onScrollProperty, onScrollStartedProperty, onSwipeDownProperty, onSwipeLeftProperty, onSwipeRightProperty, onSwipeUpProperty, onTouchMovedProperty, onTouchPressedProperty, onTouchReleasedProperty, onTouchStationaryProperty, onZoomFinishedProperty, onZoomProperty, onZoomStartedProperty, opacityProperty, parentProperty, parentToLocal, parentToLocal, parentToLocal, parentToLocal, parentToLocal, pickOnBoundsProperty, prefHeight, prefWidth, pressedProperty, pseudoClassStateChanged, queryAccessibleAttribute, relocate, removeEventFilter, removeEventHandler, requestFocus, resize, resizeRelocate, rotateProperty, rotationAxisProperty, scaleXProperty, scaleYProperty, scaleZProperty, sceneProperty, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, screenToLocal, screenToLocal, screenToLocal, setAccessibleHelp, setAccessibleRole, setAccessibleRoleDescription, setAccessibleText, setBlendMode, setCache, setCacheHint, setClip, setCursor, setDepthTest, setDisable, setDisabled, setEffect, setEventDispatcher, setEventHandler, setFocused, setFocusTraversable, setHover, setId, setInputMethodRequests, setLayoutX, setLayoutY, setManaged, setMouseTransparent, setNodeOrientation, setOnContextMenuRequested, setOnDragDetected, setOnDragDone, setOnDragDropped, setOnDragEntered, setOnDragExited, setOnDragOver, setOnInputMethodTextChanged, setOnKeyPressed, setOnKeyReleased, setOnKeyTyped, setOnMouseClicked, setOnMouseDragEntered, setOnMouseDragExited, setOnMouseDragged, setOnMouseDragOver, setOnMouseDragReleased, setOnMouseEntered, setOnMouseExited, setOnMouseMoved, setOnMousePressed, setOnMouseReleased, setOnRotate, setOnRotationFinished, setOnRotationStarted, setOnScroll, setOnScrollFinished, setOnScrollStarted, setOnSwipeDown, setOnSwipeLeft, setOnSwipeRight, setOnSwipeUp, setOnTouchMoved, setOnTouchPressed, setOnTouchReleased, setOnTouchStationary, setOnZoom, setOnZoomFinished, setOnZoomStarted, setOpacity, setPickOnBounds, setPressed, setRotate, setRotationAxis, setScaleX, setScaleY, setScaleZ, setStyle, setTranslateX, setTranslateY, setTranslateZ, setUserData, setViewOrder, setVisible, snapshot, snapshot, startDragAndDrop, startFullDrag, styleProperty, toBack, toFront, toString, translateXProperty, translateYProperty, translateZProperty, usesMirroring, viewOrderProperty, visibleProperty`

  ### Methods declared in class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

  ### Methods declared in interface javafx.css.Styleable

  `getStyleableNode`

- ## Property Details

  - ### color

    public final ObjectProperty<Color> colorProperty
    Specifies the color of light source.
    Default value:
      null
    See Also:
      - `getColor()`
      - `setColor(Color)`

  - ### lightOn

    public final BooleanProperty lightOnProperty
    Defines the light on or off.
    Default value:
      true
    See Also:
      - `isLightOn()`
      - `setLightOn(boolean)`

- ## 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 property color.
    Property description:
      Specifies the color of light source.
    Default value:
      null

  - ### getColor

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

  - ### colorProperty

    public final ObjectProperty<Color> colorProperty()
    Specifies the color of light source.
    Default value:
      null
    See Also:
      - `getColor()`
      - `setColor(Color)`

  - ### setLightOn

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

  - ### isLightOn

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

  - ### lightOnProperty

    public final BooleanProperty lightOnProperty()
    Defines the light on or off.
    Default value:
      true
    See Also:
      - `isLightOn()`
      - `setLightOn(boolean)`

  - ### getScope

    public ObservableList<Node> getScope()
    Gets the list of nodes that specifies the hierarchical scope of this light. Any `Shape3D`s 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()`

  - ### getExclusionScope

    public ObservableList<Node> getExclusionScope()
    Gets the list of nodes that specifies the hierarchical exclusion scope of this light. Any `Shape3D`s 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:
      - `getScope()`