[API Review] RT-28129: event coordinates with perspective camera

[Pavel Safrata]

Hello,
this is related to the 3D support planned for FX8, yet it is a bugfix of 
an existing issue.

With perspective camera, events delivered to any node that's not lying 
flat on the XY plane contain wrong local coordinates - they ignore the 
projection transformations. It's enough to rotate a rectangle along X 
axis and the coordinates become useless.

http://javafx-jira.kenai.com/browse/RT-28129

Solution to this problem requires API changes, because we need to 
compute in 3D to get proper numbers. So I propose to add a "double 
getZ()" method to all picking-based events, with the following 
semantics: the event's getSceneX(), getSceneY() values still represent 
the 2D coordinates of the mouse in the window content pixels (screen 
coordinates minus window position and decorations); the getX(), getY(), 
getZ() represent the hit point in the local 3D space (which may now be 
different even for scene because of the perspective transform). If no 
node is picked, the hit point with the scene will be found on the 
projection plane. Note that nothing changes for the 2D case, for the 3D 
case we now have correct 3D coordinates instead of a complete nonsense.

There is one more issue - how to pass the correct coordinates to the 
event constructors. Instead of creating more construrctors with the 
three additional coordinates, I propose to use a concept called 
PickResult which was briefly discussed earlier and will soon be part of 
a 3D API review. In short, it is an object that contains information 
about the pick for the event - the picked node, local coordinates of the 
hit and some 3D-specific stuff. For proper 3D support, it will anyway be 
necessary to pass the PickResult to the events and allow access to it; 
once this is done, the event can compute the coordinates from it. So I 
propose adding PickResult to the event constructors. Note that they've 
not been released yet, so we can modify them instead of adding new ones. 
Also note that for convenience of 2D use-cases, the constructors will 
accept a null PickResult and in this case compute PickResult values 
based on the passed event target and scene coordinates (which is 
sufficient for 2D case).

Side note for those who remember the previous 3D API discussion: the 
PickResult is no longer restricted to 3d shapes, it is present always, 
with the 3D-specific fields having null values where not applicable.


Summary of this proposal:
Affected classes: MouseEvent, MouseDragEvent, DragEvent, GestureEvent, 
ContextMenuEvent and TouchPoint
new methods: getZ(), getPickResult() (and extended semantics of event 
local coordinates for 3D case)
modified methods: added PickResult to all constructors

Concrete description of the PickResult and the proposed picking API can 
be found here:
https://wikis.oracle.com/display/OpenJDK/Picking3dAPI

Thanks,
Pavel