Removed raw mouse events

It's too close the 3.2.0 release for an API change like this.

If/when we re-add these, some things for consideration:
* What use cases does this enable that aren't currently possible?
* What cross-platform API guarantees do we make about the availability of these events? e.g. do we try to simulate them where raw input isn't actually available?
* How is this different from the existing relative mode, and how do we clearly explain when you want these events vs wanting relative mode?

Notes from @expikr:
First observation: the reason I originally passed denominators instead of multipliers was because some rational values cannot be exactly represented by floats (e.g 1/120) so instead let the end-developer decide how to do the dividing themselves. It was the reason why it was using split values with an integer numerator to begin with, instead of having both as floats or even just normalize it in advance.

On the other hand, passing them as multipliers might have hypothetical uses for dynamically passing end-user controlled scaling in a transparent manner without coupling? (Though in that case why not just do that as additional fields appended to `motion` structs in an API-compatible layout?)

So it’s somewhat of a philosophical judgement of what this API of optional availability do we intend for it to present itself as:
- should it be a bit-perfect escape hatch with the absolute minimally-denominal abstraction over platform details just enough to be able to serve the full information (á la HIDPIAPI),
- or a renewed ergonomic API for splitting relative motion from cursor motion (in light of The Great Warping Purge) so that it is unburdened by legacy RelativeMode state machines, in which case it would be more appropriate to just call it `RELATIVE` instead of `RAW` and should be added alongside another new event purely for cursor events?

This alternate API stream was conceived in the context of preserving compatibility of the existing RelativeMode state machine by adding an escape hatch. So given the same context, my taste leans towards the former designation.

However, as The Great Warping Purge has made it potentially viable to do so, if I were allowed to break ABI by nuking the RelativeMode state machine entirely, I would prefer the latter designation unified as one of three separate components split from the old state machine, each independently controlled by platform-dependent availability without any state switching of a leaky melting pot:
- cursor visibility controls (if platform has cursor)
- cursor motion events (if platform has cursor)
- relative motion events (if the platform reports hardware motion)
This commit is contained in:
Sam Lantinga 2024-12-21 04:58:54 -08:00
parent d07bb0e679
commit f37eef948c
17 changed files with 9 additions and 290 deletions

View file

@ -182,10 +182,6 @@ typedef enum SDL_EventType
SDL_EVENT_MOUSE_WHEEL, /**< Mouse wheel motion */
SDL_EVENT_MOUSE_ADDED, /**< A new mouse has been inserted into the system */
SDL_EVENT_MOUSE_REMOVED, /**< A mouse has been removed */
SDL_EVENT_RAW_MOUSE_MOTION, /**< Mouse moved (raw motion deltas) */
SDL_EVENT_RAW_MOUSE_BUTTON_DOWN, /**< Mouse button pressed (raw button press) */
SDL_EVENT_RAW_MOUSE_BUTTON_UP, /**< Mouse button released (raw button release) */
SDL_EVENT_RAW_MOUSE_WHEEL, /**< Mouse wheel motion (raw wheel deltas) */
/* Joystick events */
SDL_EVENT_JOYSTICK_AXIS_MOTION = 0x600, /**< Joystick axis motion */
@ -458,23 +454,6 @@ typedef struct SDL_MouseMotionEvent
float yrel; /**< The relative motion in the Y direction */
} SDL_MouseMotionEvent;
/**
* Raw mouse motion event structure (event.raw_motion.*)
*
* \since This struct is available since SDL 3.1.8.
*/
typedef struct SDL_RawMouseMotionEvent
{
SDL_EventType type; /**< SDL_EVENT_RAW_MOUSE_MOTION */
Uint32 reserved;
Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
SDL_MouseID which; /**< The mouse instance id */
Sint32 dx; /**< X axis delta */
Sint32 dy; /**< Y axis delta */
float scale_x; /**< X value scale to approximate desktop acceleration */
float scale_y; /**< Y value scale to approximate desktop acceleration */
} SDL_RawMouseMotionEvent;
/**
* Mouse button event structure (event.button.*)
*
@ -495,21 +474,6 @@ typedef struct SDL_MouseButtonEvent
float y; /**< Y coordinate, relative to window */
} SDL_MouseButtonEvent;
/**
* Raw mouse button event structure (event.raw_button.*)
*
* \since This struct is available since SDL 3.1.8.
*/
typedef struct SDL_RawMouseButtonEvent
{
SDL_EventType type; /**< SDL_EVENT_RAW_MOUSE_BUTTON_DOWN or SDL_EVENT_RAW_MOUSE_BUTTON_UP */
Uint32 reserved;
Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
SDL_MouseID which; /**< The mouse instance id */
Uint8 button; /**< The mouse button index */
bool down; /**< true if the button is pressed */
} SDL_RawMouseButtonEvent;
/**
* Mouse wheel event structure (event.wheel.*)
*
@ -529,23 +493,6 @@ typedef struct SDL_MouseWheelEvent
float mouse_y; /**< Y coordinate, relative to window */
} SDL_MouseWheelEvent;
/**
* Raw mouse wheel event structure (event.raw_wheel.*)
*
* \since This struct is available since SDL 3.1.3.
*/
typedef struct SDL_RawMouseWheelEvent
{
SDL_EventType type; /**< SDL_EVENT_RAW_MOUSE_WHEEL */
Uint32 reserved;
Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
SDL_MouseID which; /**< The mouse instance id */
Sint32 dx; /**< X axis delta, positive to the right and negative to the left */
Sint32 dy; /**< Y axis delta, positive away from the user and negative toward the user */
float scale_x; /**< X value scale to convert to logical scroll units */
float scale_y; /**< Y value scale to convert to logical scroll units */
} SDL_RawMouseWheelEvent;
/**
* Joystick axis motion event structure (event.jaxis.*)
*
@ -1048,11 +995,8 @@ typedef union SDL_Event
SDL_TextInputEvent text; /**< Text input event data */
SDL_MouseDeviceEvent mdevice; /**< Mouse device change event data */
SDL_MouseMotionEvent motion; /**< Mouse motion event data */
SDL_RawMouseMotionEvent raw_motion; /**< Raw mouse motion event data */
SDL_MouseButtonEvent button; /**< Mouse button event data */
SDL_RawMouseButtonEvent raw_button; /**< Raw mouse button event data */
SDL_MouseWheelEvent wheel; /**< Mouse wheel event data */
SDL_RawMouseWheelEvent raw_wheel; /**< Raw mouse wheel event data */
SDL_JoyDeviceEvent jdevice; /**< Joystick device change event data */
SDL_JoyAxisEvent jaxis; /**< Joystick axis event data */
SDL_JoyBallEvent jball; /**< Joystick ball event data */