Getting Started with JavaFX 3D Graphics


Beta Draft: 2013-09-17

7 Picking

This chapter describes the PickResult API that is included with the JavaFX 3D Graphics feature.

The PickResult API was already available for 2D primitives with the Perspective Camera. However, there were existing limitations when it was used with depth buffer so the PickResult class has been added to the javafx.scene.input package. It is a container object that contains the result of a pick event.

The PickResult argument has been added to all the constructors of the MouseEvent, MouseDragEvent, DragEvent, GestureEvent, ContextMenuEvent and TouchPoint classes so that information about the user's pick is returned. The newly added getPickResult() method in these classes returns a new PickResult object that contains information about the pick. Another method added is getZ() which returns the depth position of the event relative to the origin of the MouseEvent's source.

Creating a PickResult Object

The JavaFX API provides three constructors for creating a new instance of a PickResult object in your application, as shown in Example 7-1.

Example 7-1 PickResult Constructors

// Creates a pick result for a 2D case where no additional information
// is needed. Converts the given scene coordinates to the target's local
// coordinate space andstores the value as the intersected point. Sets 
// intersected node to the giventarget, distance to 1.0, face to 
// FACE_UNDEFINED and texCoord to null
PickResult(EventTarget target, double sceneX, double sceneY)

// Creates a new instance of PickResult for a non-3d-shape target. Sets face
// to FACE_UNDEFINED and texCoord to null.
PickResult(Node node, Point3D point, double distance)

// Creates a new instance of PickResult
PickResult(Node node, Point3D point, double distance, int face, 
           Point2D texCoord)

Methods for the PickResult Object

Once you have created a PickResult object in your code, you can use the following methods to work with the information passed from the classes that handle the events.

Example 7-2 PickResult Methods

// Returns the intersected node. Returns null if there was no intersection
// with any node and the scene was picked.
public final Node getIntersectedNode()

// Returns the intersected point in local coordinate of the picked Node. If
// no node was picked, it returns the intersected point with the projection 
// plane.
public final Point3D getIntersectedPoint()

// Returns the intersected distance between camera position and the 
// intersected point
public final double getIntersectedDistance()

// Returns the intersected face of the picked Node, FACE_UNDEFINED if the
//  node doesn't have user-specified faces or was picked on bounds.
public final int getIntersectedFace()
// Return the intersected texture coordinates of the picked 3d shape. If the
// picked target is not Shape3D or has pickOnBounds==true, it returns null. 
// Returns new Point2D presenting the intersected TexCoord
public final Point2D getIntersectedTexCoord()