SubScene (JavaFX 17)

Module javafx.graphics
Package javafx.scene

## Class SubScene

- java.lang.Object
- - javafx.scene.Node
  - - javafx.scene.SubScene

- All Implemented Interfaces:
    `Styleable`, `EventTarget`

      public class SubScene
      extends Node

  The `SubScene` class is the container for content in a scene graph. `SubScene` provides separation of different parts of a scene, each of which can be rendered with a different camera, depth buffer, or scene anti-aliasing. A `SubScene` is embedded into the main scene or another sub-scene.

  An application may request depth buffer support or scene anti-aliasing support at the creation of a `SubScene`. A sub-scene with only 2D shapes and without any 3D transforms does not need a depth buffer nor scene anti-aliasing support. A sub-scene containing 3D shapes or 2D shapes with 3D transforms may use depth buffer support for proper depth sorted rendering; to avoid depth fighting (also known as Z fighting), disable depth testing on 2D shapes that have no 3D transforms. See `depthTest` for more information. A sub-scene with 3D shapes may enable scene anti-aliasing to improve its rendering quality.

  The depthBuffer and antiAliasing flags are conditional features. With the respective default values of: false and `SceneAntialiasing.DISABLED`. See `ConditionalFeature.SCENE3D` for more information.

  Possible use cases are:

  - Mixing 2D and 3D content
  - Overlay for UI controls
  - Underlay for background
  - Heads-up display

  A default headlight will be added to a `SubScene` that contains one or more `Shape3D` nodes, but no light nodes. This light source is a `Color.WHITE` `PointLight` placed at the camera position.

  Since:
    JavaFX 8.0

- - ### Property Summary

    Properties
    Type | Property | Description
    --- | --- | ---
    `ObjectProperty<Camera>` | `camera` | Specifies the type of camera use for rendering this `SubScene`.
    `ObjectProperty<Paint>` | `fill` | Defines the background fill of this `SubScene`.
    `DoubleProperty` | `height` | Defines the height of this `SubScene`
    `ObjectProperty<Parent>` | `root` | Defines the root `Node` of the `SubScene` scene graph.
    `ObjectProperty<String>` | `userAgentStylesheet` |
    `DoubleProperty` | `width` | Defines the width of this `SubScene`

    - ### 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
    Constructor | Description
    --- | ---
    `SubScene​(Parent root, double width, double height)` | Creates a `SubScene` for a specific root Node with a specific size.
    `SubScene​(Parent root, double width, double height, boolean depthBuffer, SceneAntialiasing antiAliasing)` | Constructs a `SubScene` consisting of a root, with a dimension of width and height, specifies whether a depth buffer is created for this scene and specifies whether scene anti-aliasing is requested.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `ObjectProperty<Camera>` | `cameraProperty()` | Specifies the type of camera use for rendering this `SubScene`.
    `ObjectProperty<Paint>` | `fillProperty()` | Defines the background fill of this `SubScene`.
    `SceneAntialiasing` | `getAntiAliasing()` | Return the defined `SceneAntialiasing` for this `SubScene`.
    `Camera` | `getCamera()` | Gets the value of the property camera.
    `Paint` | `getFill()` | Gets the value of the property fill.
    `double` | `getHeight()` | Gets the value of the property height.
    `Parent` | `getRoot()` | Gets the value of the property root.
    `String` | `getUserAgentStylesheet()` | Get the URL of the user-agent stylesheet that will be used by this SubScene.
    `double` | `getWidth()` | Gets the value of the property width.
    `DoubleProperty` | `heightProperty()` | Defines the height of this `SubScene`
    `boolean` | `isDepthBuffer()` | Retrieves the depth buffer attribute for this `SubScene`.
    `ObjectProperty<Parent>` | `rootProperty()` | Defines the root `Node` of the `SubScene` scene graph.
    `void` | `setCamera​(Camera value)` | Sets the value of the property camera.
    `void` | `setFill​(Paint value)` | Sets the value of the property fill.
    `void` | `setHeight​(double value)` | Sets the value of the property height.
    `void` | `setRoot​(Parent value)` | Sets the value of the property root.
    `void` | `setUserAgentStylesheet​(String url)` | Set the URL of the user-agent stylesheet that will be used by this SubScene in place of the the platform-default user-agent stylesheet.
    `void` | `setWidth​(double value)` | Sets the value of the property width.
    `ObjectProperty<String>` | `userAgentStylesheetProperty()` |
    `DoubleProperty` | `widthProperty()` | Defines the width of this `SubScene`

    - ### 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, 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, getStyleClass`

- - ### Property Detail

    - #### root

          public final ObjectProperty<Parent> rootProperty

      Defines the root `Node` of the `SubScene` scene graph. If a `Group` is used as the root, the contents of the scene graph will be clipped by the `SubScene`'s width and height. `SubScene` doesn't accept null root.
      See Also:
        `getRoot()`, `setRoot(Parent)`

    - #### camera

          public final ObjectProperty<Camera> cameraProperty

      Specifies the type of camera use for rendering this `SubScene`. If `camera` is null, a parallel camera is used for rendering. It is illegal to set a camera that belongs to other `Scene` or `SubScene`.

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

      Default value:
        null
      See Also:
        `getCamera()`, `setCamera(Camera)`

    - #### width

          public final DoubleProperty widthProperty

      Defines the width of this `SubScene`
      Default value:
        0.0
      See Also:
        `getWidth()`, `setWidth(double)`

    - #### height

          public final DoubleProperty heightProperty

      Defines the height of this `SubScene`
      Default value:
        0.0
      See Also:
        `getHeight()`, `setHeight(double)`

    - #### fill

          public final ObjectProperty<Paint> fillProperty

      Defines the background fill of this `SubScene`. Both a `null` value meaning paint no background and a `Paint` with transparency are supported. The default value is null.
      Default value:
        null
      See Also:
        `getFill()`, `setFill(Paint)`

    - #### userAgentStylesheet

          public final ObjectProperty<String> userAgentStylesheetProperty

      Since:
        JavaFX 8u20
      See Also:
        `getUserAgentStylesheet()`, `setUserAgentStylesheet(String)`

  - ### Constructor Detail

    - #### SubScene

          public SubScene​(Parent root,
                          double width,
                          double height)

      Creates a `SubScene` for a specific root Node with a specific size.
      Parameters:
        `root` - The root node of the scene graph
        `width` - The width of the sub-scene
        `height` - The height of the sub-scene
      Throws:
        `NullPointerException` - if root is null

    - #### SubScene

          public SubScene​(Parent root,
                          double width,
                          double height,
                          boolean depthBuffer,
                          SceneAntialiasing antiAliasing)

      Constructs a `SubScene` consisting of a root, with a dimension of width and height, specifies whether a depth buffer is created for this scene and specifies whether scene anti-aliasing is requested.

      A sub-scene with only 2D shapes and without any 3D transforms does not need a depth buffer nor scene anti-aliasing support. A sub-scene containing 3D shapes or 2D shapes with 3D transforms may use depth buffer support for proper depth sorted rendering; to avoid depth fighting (also known as Z fighting), disable depth testing on 2D shapes that have no 3D transforms. See `depthTest` for more information. A sub-scene with 3D shapes may enable scene anti-aliasing to improve its rendering quality.

      Parameters:
        `root` - The root node of the scene graph
        `width` - The width of the sub-scene
        `height` - The height of the sub-scene
        `depthBuffer` - The depth buffer flag
        `antiAliasing` - The sub-scene anti-aliasing attribute. A value of `null` is treated as DISABLED.

        The depthBuffer and antiAliasing flags are conditional features. With the respective default values of: false and `SceneAntialiasing.DISABLED`. See `ConditionalFeature.SCENE3D` for more information.

      Throws:
        `NullPointerException` - if root is null
      See Also:
        `Node.setDepthTest(DepthTest)`

  - ### Method Detail

    - #### getAntiAliasing

          public final SceneAntialiasing getAntiAliasing()

      Return the defined `SceneAntialiasing` for this `SubScene`.

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

      Returns:
        the SceneAntialiasing for this sub-scene
      Since:
        JavaFX 8.0

    - #### isDepthBuffer

          public final boolean isDepthBuffer()

      Retrieves the depth buffer attribute for this `SubScene`.
      Returns:
        the depth buffer attribute.

    - #### setRoot

          public final void setRoot​(Parent value)

      Sets the value of the property root.
      Property description:
        Defines the root `Node` of the `SubScene` scene graph. If a `Group` is used as the root, the contents of the scene graph will be clipped by the `SubScene`'s width and height. `SubScene` doesn't accept null root.

    - #### getRoot

          public final Parent getRoot()

      Gets the value of the property root.
      Property description:
        Defines the root `Node` of the `SubScene` scene graph. If a `Group` is used as the root, the contents of the scene graph will be clipped by the `SubScene`'s width and height. `SubScene` doesn't accept null root.

    - #### rootProperty

          public final ObjectProperty<Parent> rootProperty()

      Defines the root `Node` of the `SubScene` scene graph. If a `Group` is used as the root, the contents of the scene graph will be clipped by the `SubScene`'s width and height. `SubScene` doesn't accept null root.
      See Also:
        `getRoot()`, `setRoot(Parent)`

    - #### setCamera

          public final void setCamera​(Camera value)

      Sets the value of the property camera.
      Property description:
        Specifies the type of camera use for rendering this `SubScene`. If `camera` is null, a parallel camera is used for rendering. It is illegal to set a camera that belongs to other `Scene` or `SubScene`.

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

      Default value:
        null

    - #### getCamera

          public final Camera getCamera()

      Gets the value of the property camera.
      Property description:
        Specifies the type of camera use for rendering this `SubScene`. If `camera` is null, a parallel camera is used for rendering. It is illegal to set a camera that belongs to other `Scene` or `SubScene`.

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

      Default value:
        null

    - #### cameraProperty

          public final ObjectProperty<Camera> cameraProperty()

      Specifies the type of camera use for rendering this `SubScene`. If `camera` is null, a parallel camera is used for rendering. It is illegal to set a camera that belongs to other `Scene` or `SubScene`.

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

      Default value:
        null
      See Also:
        `getCamera()`, `setCamera(Camera)`

    - #### setWidth

          public final void setWidth​(double value)

      Sets the value of the property width.
      Property description:
        Defines the width of this `SubScene`
      Default value:
        0.0

    - #### getWidth

          public final double getWidth()

      Gets the value of the property width.
      Property description:
        Defines the width of this `SubScene`
      Default value:
        0.0

    - #### widthProperty

          public final DoubleProperty widthProperty()

      Defines the width of this `SubScene`
      Default value:
        0.0
      See Also:
        `getWidth()`, `setWidth(double)`

    - #### setHeight

          public final void setHeight​(double value)

      Sets the value of the property height.
      Property description:
        Defines the height of this `SubScene`
      Default value:
        0.0

    - #### getHeight

          public final double getHeight()

      Gets the value of the property height.
      Property description:
        Defines the height of this `SubScene`
      Default value:
        0.0

    - #### heightProperty

          public final DoubleProperty heightProperty()

      Defines the height of this `SubScene`
      Default value:
        0.0
      See Also:
        `getHeight()`, `setHeight(double)`

    - #### setFill

          public final void setFill​(Paint value)

      Sets the value of the property fill.
      Property description:
        Defines the background fill of this `SubScene`. Both a `null` value meaning paint no background and a `Paint` with transparency are supported. The default value is null.
      Default value:
        null

    - #### getFill

          public final Paint getFill()

      Gets the value of the property fill.
      Property description:
        Defines the background fill of this `SubScene`. Both a `null` value meaning paint no background and a `Paint` with transparency are supported. The default value is null.
      Default value:
        null

    - #### fillProperty

          public final ObjectProperty<Paint> fillProperty()

      Defines the background fill of this `SubScene`. Both a `null` value meaning paint no background and a `Paint` with transparency are supported. The default value is null.
      Default value:
        null
      See Also:
        `getFill()`, `setFill(Paint)`

    - #### userAgentStylesheetProperty

          public final ObjectProperty<String> userAgentStylesheetProperty()

      Since:
        JavaFX 8u20
      See Also:
        `getUserAgentStylesheet()`, `setUserAgentStylesheet(String)`

    - #### getUserAgentStylesheet

          public final String getUserAgentStylesheet()

      Get the URL of the user-agent stylesheet that will be used by this SubScene. If the URL has not been set, the platform-default user-agent stylesheet will be used.

      For additional information about using CSS with the scene graph, see the CSS Reference Guide.

      Returns:
        The URL of the user-agent stylesheet that will be used by this SubScene, or null if has not been set.
      Since:
        JavaFX 8u20

    - #### setUserAgentStylesheet

          public final void setUserAgentStylesheet​(String url)

      Set the URL of the user-agent stylesheet that will be used by this SubScene in place of the the platform-default user-agent stylesheet. If the URL does not resolve to a valid location, the platform-default user-agent stylesheet will be used.

      The URL is a hierarchical URI of the form [scheme:][//authority][path]. If the URL does not have a [scheme:] component, the URL is considered to be the [path] component only. Any leading '/' character of the [path] is ignored and the [path] is treated as a path relative to the root of the application's classpath.

      The RFC 2397 "data" scheme for URLs is supported in addition to the protocol handlers that are registered for the application. If a URL uses the "data" scheme and the MIME type is either empty, "text/plain", or "text/css", the payload will be interpreted as a CSS file. If the MIME type is "application/octet-stream", the payload will be interpreted as a binary CSS file (see `Stylesheet.convertToBinary(File, File)`).

      For additional information about using CSS with the scene graph, see the CSS Reference Guide.

      Parameters:
        `url` - the URL of the user-agent stylesheet
      Since:
        JavaFX 8u20