Add more information for pinch gestures on mobile

[brentfpage]

Description

• the SDL_PinchFingerEvent struct defined in include/SDL3/SDL_events.h has been expanded to include the midpoint of the finger positions comprising the pinch gesture (focus) as well as the x and y displacements between the finger positions (span). Including this information allows a programmer to implement a zoom in response to the gesture that a.) keeps focus centered on the screen and that b.) zooms the y axis more rapidly if the user's fingers are more vertically aligned.
• the updated declaration and definition of SDL_SendPinch in src/events/(SDL_touch_c.h and SDL_touch.c) accommodate this new focus and span information
• Capturing the additional pinch info in Java/Android
  • when a pinch event is detected in android-project/app/src/main/java/org/libsdl/app/SDLSurface.java , now the focus and span info is forwarded on to downstream functions in addition to scale, while previously only scale was forwarded. This forwarding function is specifically onNativePinchUpdate
  • the Java Native interface in android-project/app/src/main/java/org/libsdl/app/SDLActivity.java and src/core/android/SDL_android.c that connects onNativePinchUpdate to SDL_SendPinch has been expanded to include focus and span
• Calls to SDL_SendPinch in non-Android user interface frameworks
  • src/video/cocoa/SDL_cocoawindow.m
  • src/video/uikit/SDL_uikitview.m
  • src/video/wayland/SDL_waylandevents.c
  • src/video/x11/SDL_x11xinput2.c
    have been adjusted so that event.pinch.focus_x, event.pinch.focus_y, event.pinch.span_x, and event.pinch.span_y are set to zero by SDL_SendPinch. Existing uses of pinch events will only involve event.pinch.scale, so these changes are non-breaking. On the other hand, it may be surprising to a programmer that focus and span are zero considering that they exist. I am unfamiliar with these UI frameworks, so won't attempt to add focus and span info to their SDL_SendPinch calls, but some glances at these frameworks' APIs suggests this would be possible to some extent.

Coordinate system transformations:

In SDLSurface.java, the Android gesture detector returns span and focus info in screen pixel coordinates. For consistency with what is done in that same file for simple touch events, I convert span and focus to normalized screen coordinates before passing them on to SDL_SendPinch/onNativePinchUpdate. But, I convert them back to pixel screen coordinates in SDL_SendPinch, again to be consistent with what is done for touch events (in SDL_SendTouch)

To be precise, the pinch info transformations are very nearly inverses of one another, but for reasons I'm unfamiliar with, the original conversion to normalized screen coordinates divides by (pixel_count - 1) instead of (pixel_count), while the subsequent conversion back to screen pixel coordinates multiplies by pixel_count. The final change in coordinates by a multiplicative factor pixel_count/(pixel_count - 1) is minuscule for all devices.

[maia-s]

This breaks binary compatibility, because the windowID field of SDL_PinchFingerEvent changes offset. An app compiled against an older SDL would get a garbage window id if dynamically linked to an SDL library with this patch.

[brentfpage]

Does the newest commit fix the issue?