macOS: Add a hint for smooth momentum values in SDL_EVENT_MOUSE_WHEEL events

[jansedivy]

This PR adds a new hint for smooth momentum values in SDL_EVENT_MOUSE_WHEEL events on MacOS.

Description

When scrolling on a touchpad on MacOS the scroll values usually contain momentum inside all native applications. But inside SDL the scroll values were without momentum. This PR adds a simple hint to control "AppleMomentumScrollSupported" MacOS API for requesting the native momentum.

Please let me know if there is a better name for the hint or if you have better wording for the documentation part.

Demo

Here is a simple "browser" test application with scrolling to see the difference.

Momentum	Video
OFF	Kapture.2024-09-07.at.11.25.43.mp4
ON	Kapture.2024-09-07.at.11.26.18.mp4

Existing Issue(s)

fixes #2176 which mentions adding a hint for this in SDL 3.0.

[jansedivy]

I was looking at the macOS documentation and Apple recommends using scrollingDeltaX/scrollingDeltaY over deltaX/deltaY properties when reading scroll events. This does provide smoother values that more closely match native applications.

https://developer.apple.com/documentation/appkit/nsevent/1524505-scrollingdeltax?language=objc

SDL/src/video/cocoa/SDL_cocoamouse.m

Lines 528 to 529 in 1d59be6

	x = -[event deltaX];
	y = [event deltaY];

Maybe we could switch to that property as well. From my testing, it behaves more closely to what I would expect on MacOS.

Looks like Chromium is using scrollDelta{X,Y} when hasPreciseScrollingDeltas is true and delta{X,Y} when not. But the issue with this is scrollDelta and delta have different sensitivity so we would need to scale it to not break existing SDL applications, or this could all be new behavior behind the hint flag.

https://source.chromium.org/chromium/chromium/src/+/main:ui/events/cocoa/events_mac.mm;l=144-164;drc=ae99ae281ffc2fe19024f86c5c64939efc1b2e87

[slouken]

What does this mean in terms of SDL application life cycle? We should answer that for the SDL_HINT_MAC_BACKGROUND_APP hint as well. :)

[slouken]

@jansedivy, can you update the documentation here?

[jansedivy]

@slouken I did some digging to figure out when the hints are used.

There are two flows within the macOS cocoa code to call registerUserDefaults where the momentum is set.

1. macOS applicationDidFinishLaunching event that's called sometime after SDL_Init/SDL_CreateWindow.

   SDL/src/video/cocoa/SDL_cocoaevents.m

   Line 333 in 345d9bf

   [SDL3Application registerUserDefaults];

2. Manual registerUserDefaults under some condition which I am not fully sure about. This is called within SDL_Init.

   SDL/src/video/cocoa/SDL_cocoaevents.m

   Lines 526 to 531 in 345d9bf

   	if ([NSApp delegate]) {
   	/* The SDL app delegate calls this in didFinishLaunching if it's
   	* attached to the NSApp, otherwise we need to call it manually.
   	*/
   	[SDL3Application registerUserDefaults];
   	}

This means if we want to guarantee the hint will be read in both cases it needs to be set before SDL_Init(). I have updated both documentation comments to reflect that. SDL_HINT_MAC_BACKGROUND_APP has the same code flow.

But it's still possible to set the hint after SDL_Init/SDL_CreateWindow and have applicationDidFinishLaunching event callback pick it up. Do we want to put some guard code to prevent that or are we good with just having the documentation say to set it before SDL_Init?

[slouken]

Merged, thanks!