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

[Chien Yang]

Looks good to me. This proposed change will also provide a consistent 
picking framework for 2D and 3D primitives.

Thanks,
- Chien

On 2/1/2013 8:51 AM, Pavel Safrata wrote:
> 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
>