- All Implemented Interfaces:
Styleable
,EventTarget
- Direct Known Subclasses:
AmbientLight
,DirectionalLight
,PointLight
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 sourcescope
- a list of nodes the light source affectsexlusionScope
- a list of nodes the light source does not affect
Light type | Rotation and Direction | Location and Attenuation |
---|---|---|
AmbientLight |
✗ | ✗ |
DirectionalLight |
✓ | ✗ |
PointLight |
✗ | ✓ |
SpotLight * |
✓ | ✓ |
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 inPhongMaterial
.
See also the implementation notes section.
Scopes
A light has ascope
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 thedirection
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 aShape3D
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:- A black colored light is ignored since its contribution is 0.
- The transparency (alpha) component of a light is ignored.
- Since:
- JavaFX 8.0
-
Property Summary
TypePropertyDescriptionfinal ObjectProperty<Color>
Specifies the color of light source.final BooleanProperty
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, focusVisible, focusWithin, 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
-
Method Summary
Modifier and TypeMethodDescriptionfinal ObjectProperty<Color>
Specifies the color of light source.final Color
getColor()
Gets the value of thecolor
property.Gets the list of nodes that specifies the hierarchical exclusion scope of this light.getScope()
Gets the list of nodes that specifies the hierarchical scope of this light.final boolean
Gets the value of thelightOn
property.final BooleanProperty
Defines the light on or off.final void
Sets the value of thecolor
property.final void
setLightOn
(boolean value) Sets the value of thelightOn
property.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, focusVisibleProperty, focusWithinProperty, 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, isFocusVisible, isFocusWithin, 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
Specifies the color of light source.- Default value:
- null
- See Also:
-
lightOn
Defines the light on or off.- Default value:
- true
- See Also:
-
-
Constructor Details
-
LightBase
protected LightBase()Creates a new instance ofLightBase
class with a default Color.WHITE light source. -
LightBase
Creates a new instance ofLightBase
class using the specified color.- Parameters:
color
- the color of the light source
-
-
Method Details
-
setColor
Sets the value of thecolor
property.- Property description:
- Specifies the color of light source.
- Default value:
- null
- Parameters:
value
- the value for thecolor
property- See Also:
-
getColor
Gets the value of thecolor
property.- Property description:
- Specifies the color of light source.
- Default value:
- null
- Returns:
- the value of the
color
property - See Also:
-
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 thelightOn
property.- Property description:
- Defines the light on or off.
- Default value:
- true
- Parameters:
value
- the value for thelightOn
property- See Also:
-
isLightOn
public final boolean isLightOn()Gets the value of thelightOn
property.- Property description:
- Defines the light on or off.
- Default value:
- true
- Returns:
- the value of the
lightOn
property - See Also:
-
lightOnProperty
Defines the light on or off.- Default value:
- true
- Returns:
- the
lightOn
property - See Also:
-
getScope
Gets the list of nodes that specifies the hierarchical scope of this light. AnyShape3D
s in this list or under aParent
in this list are affected by this light, unless a closer parent exists in theexclusionScope
list. If the list is empty, all nodes under the light's scene/subscene are affected by it (unless they are in theexclusionScope
).- Returns:
- the list of nodes that specifies the hierarchical scope of this light
- See Also:
-
getExclusionScope
Gets the list of nodes that specifies the hierarchical exclusion scope of this light. AnyShape3D
s in this list or under aParent
in this list are not affected by this light, unless a closer parent exists in thescope
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:
-