Updated return values for SDL event functions

SDL_PollEvent(), SDL_WaitEvent(), and SDL_WaitEventTimeout() all return SDL_bool.
SDL_AddEventWatch() returns an int result code.

Also improved timeout accuracy in SDL_WaitEventTimeout()
main
Sam Lantinga 2023-11-03 22:31:42 -07:00
parent e0379c3b37
commit f439ccfc1a
4 changed files with 96 additions and 93 deletions

View File

@ -731,9 +731,7 @@ typedef enum
* \sa SDL_PumpEvents
* \sa SDL_PushEvent
*/
extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents,
SDL_eventaction action,
Uint32 minType, Uint32 maxType);
extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event *events, int numevents, SDL_eventaction action, Uint32 minType, Uint32 maxType);
/* @} */
/**
@ -852,7 +850,7 @@ extern DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType);
*
* \param event the SDL_Event structure to be filled with the next event from
* the queue, or NULL
* \returns 1 if there is a pending event or 0 if there are none available.
* \returns SDL_TRUE if this got an event or SDL_FALSE if there are none available.
*
* \since This function is available since SDL 3.0.0.
*
@ -863,7 +861,7 @@ extern DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType);
* \sa SDL_WaitEvent
* \sa SDL_WaitEventTimeout
*/
extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
extern DECLSPEC SDL_bool SDLCALL SDL_PollEvent(SDL_Event *event);
/**
* Wait indefinitely for the next available event.
@ -876,7 +874,7 @@ extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
*
* \param event the SDL_Event structure to be filled in with the next event
* from the queue, or NULL
* \returns 1 on success or 0 if there was an error while waiting for events;
* \returns SDL_TRUE on success or SDL_FALSE if there was an error while waiting for events;
* call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -885,7 +883,7 @@ extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
* \sa SDL_PumpEvents
* \sa SDL_WaitEventTimeout
*/
extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event *event);
extern DECLSPEC SDL_bool SDLCALL SDL_WaitEvent(SDL_Event *event);
/**
* Wait until the specified timeout (in milliseconds) for the next available
@ -904,9 +902,7 @@ extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event *event);
* from the queue, or NULL
* \param timeoutMS the maximum number of milliseconds to wait for the next
* available event
* \returns 1 on success or 0 if there was an error while waiting for events;
* call SDL_GetError() for more information. This also returns 0 if
* the timeout elapsed without an event arriving.
* \returns SDL_TRUE if this got an event or SDL_FALSE if the timeout elapsed without any events available.
*
* \since This function is available since SDL 3.0.0.
*
@ -914,7 +910,7 @@ extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event *event);
* \sa SDL_PumpEvents
* \sa SDL_WaitEvent
*/
extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint32 timeoutMS);
extern DECLSPEC SDL_bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint32 timeoutMS);
/**
* Add an event to the event queue.
@ -948,7 +944,7 @@ extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint32 timeou
* \sa SDL_PollEvent
* \sa SDL_RegisterEvents
*/
extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event);
extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event *event);
/**
* A function pointer used for callbacks that watch the event queue.
@ -962,7 +958,7 @@ extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event);
* \sa SDL_SetEventFilter
* \sa SDL_AddEventWatch
*/
typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
typedef int (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event);
/**
* Set up a filter to process all events before they change internal state and
@ -1006,8 +1002,7 @@ typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
* \sa SDL_PeepEvents
* \sa SDL_PushEvent
*/
extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter,
void *userdata);
extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter, void *userdata);
/**
* Query the current event filter.
@ -1024,8 +1019,7 @@ extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter,
*
* \sa SDL_SetEventFilter
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter,
void **userdata);
extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter *filter, void **userdata);
/**
* Add a callback to be triggered when an event is added to the event queue.
@ -1047,14 +1041,14 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter,
*
* \param filter an SDL_EventFilter function to call when an event happens.
* \param userdata a pointer that is passed to `filter`
* \returns 0 on success, or a negative error code on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_DelEventWatch
* \sa SDL_SetEventFilter
*/
extern DECLSPEC void SDLCALL SDL_AddEventWatch(SDL_EventFilter filter,
void *userdata);
extern DECLSPEC int SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, void *userdata);
/**
* Remove an event watch callback added with SDL_AddEventWatch().
@ -1069,8 +1063,7 @@ extern DECLSPEC void SDLCALL SDL_AddEventWatch(SDL_EventFilter filter,
*
* \sa SDL_AddEventWatch
*/
extern DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter,
void *userdata);
extern DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter, void *userdata);
/**
* Run a specific filter function on the current event queue, removing any
@ -1088,8 +1081,7 @@ extern DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter,
* \sa SDL_GetEventFilter
* \sa SDL_SetEventFilter
*/
extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter,
void *userdata);
extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter, void *userdata);
/**
* Set the state of processing events by type.

View File

@ -200,7 +200,7 @@ extern "C" {
extern DECLSPEC Uint32 SDLCALL SDL_GetNextObjectID(void);
extern DECLSPEC int SDLCALL SDL_WaitSemaphoreTimeoutNS(SDL_Semaphore *sem, Sint64 timeoutNS);
extern DECLSPEC int SDLCALL SDL_WaitConditionTimeoutNS(SDL_Condition *cond, SDL_Mutex *mutex, Sint64 timeoutNS);
extern DECLSPEC int SDLCALL SDL_WaitEventTimeoutNS(SDL_Event *event, Sint64 timeoutNS);
extern DECLSPEC SDL_bool SDLCALL SDL_WaitEventTimeoutNS(SDL_Event *event, Sint64 timeoutNS);
/* Ends C function definitions when using C++ */
#ifdef __cplusplus

View File

@ -103,7 +103,7 @@ SDL_DYNAPI_PROC(SDL_bool,SDL_IsAndroidTV,(void),(),return)
SDL_DYNAPI_PROC(SDL_bool,SDL_IsChromebook,(void),(),return)
SDL_DYNAPI_PROC(SDL_bool,SDL_IsDeXMode,(void),(),return)
SDL_DYNAPI_PROC(void,SDL_AddEventWatch,(SDL_EventFilter a, void *b),(a,b),)
SDL_DYNAPI_PROC(int,SDL_AddEventWatch,(SDL_EventFilter a, void *b),(a,b),)
SDL_DYNAPI_PROC(int,SDL_AddGamepadMapping,(const char *a),(a),return)
SDL_DYNAPI_PROC(int,SDL_AddGamepadMappingsFromRW,(SDL_RWops *a, SDL_bool b),(a,b),return)
SDL_DYNAPI_PROC(int,SDL_AddHintCallback,(const char *a, SDL_HintCallback b, void *c),(a,b,c),return)
@ -554,7 +554,7 @@ SDL_DYNAPI_PROC(SDL_Joystick*,SDL_OpenJoystick,(SDL_JoystickID a),(a),return)
SDL_DYNAPI_PROC(SDL_Sensor*,SDL_OpenSensor,(SDL_SensorID a),(a),return)
SDL_DYNAPI_PROC(int,SDL_OpenURL,(const char *a),(a),return)
SDL_DYNAPI_PROC(int,SDL_PeepEvents,(SDL_Event *a, int b, SDL_eventaction c, Uint32 d, Uint32 e),(a,b,c,d,e),return)
SDL_DYNAPI_PROC(int,SDL_PollEvent,(SDL_Event *a),(a),return)
SDL_DYNAPI_PROC(SDL_bool,SDL_PollEvent,(SDL_Event *a),(a),return)
SDL_DYNAPI_PROC(int,SDL_PostSemaphore,(SDL_Semaphore *a),(a),return)
SDL_DYNAPI_PROC(int,SDL_PremultiplyAlpha,(int a, int b, Uint32 c, const void *d, int e, Uint32 f, void *g, int h),(a,b,c,d,e,f,g,h),return)
SDL_DYNAPI_PROC(void,SDL_PumpEvents,(void),(),)
@ -725,8 +725,8 @@ SDL_DYNAPI_PROC(int,SDL_Vulkan_LoadLibrary,(const char *a),(a),return)
SDL_DYNAPI_PROC(void,SDL_Vulkan_UnloadLibrary,(void),(),)
SDL_DYNAPI_PROC(int,SDL_WaitCondition,(SDL_Condition *a, SDL_Mutex *b),(a,b),return)
SDL_DYNAPI_PROC(int,SDL_WaitConditionTimeout,(SDL_Condition *a, SDL_Mutex *b, Sint32 c),(a,b,c),return)
SDL_DYNAPI_PROC(int,SDL_WaitEvent,(SDL_Event *a),(a),return)
SDL_DYNAPI_PROC(int,SDL_WaitEventTimeout,(SDL_Event *a, Sint32 b),(a,b),return)
SDL_DYNAPI_PROC(SDL_bool,SDL_WaitEvent,(SDL_Event *a),(a),return)
SDL_DYNAPI_PROC(SDL_bool,SDL_WaitEventTimeout,(SDL_Event *a, Sint32 b),(a,b),return)
SDL_DYNAPI_PROC(int,SDL_WaitSemaphore,(SDL_Semaphore *a),(a),return)
SDL_DYNAPI_PROC(int,SDL_WaitSemaphoreTimeout,(SDL_Semaphore *a, Sint32 b),(a,b),return)
SDL_DYNAPI_PROC(void,SDL_WaitThread,(SDL_Thread *a, int *b),(a,b),)

View File

@ -903,7 +903,7 @@ void SDL_PumpEvents(void)
/* Public functions */
int SDL_PollEvent(SDL_Event *event)
SDL_bool SDL_PollEvent(SDL_Event *event)
{
return SDL_WaitEventTimeoutNS(event, 0);
}
@ -1014,14 +1014,14 @@ static SDL_Window *SDL_find_active_window(SDL_VideoDevice *_this)
return NULL;
}
int SDL_WaitEvent(SDL_Event *event)
SDL_bool SDL_WaitEvent(SDL_Event *event)
{
return SDL_WaitEventTimeoutNS(event, -1);
}
int SDL_WaitEventTimeout(SDL_Event *event, Sint32 timeoutMS)
SDL_bool SDL_WaitEventTimeout(SDL_Event *event, Sint32 timeoutMS)
{
Uint64 timeoutNS;
Sint64 timeoutNS;
if (timeoutMS > 0) {
timeoutNS = SDL_MS_TO_NS(timeoutMS);
@ -1031,7 +1031,7 @@ int SDL_WaitEventTimeout(SDL_Event *event, Sint32 timeoutMS)
return SDL_WaitEventTimeoutNS(event, timeoutNS);
}
int SDL_WaitEventTimeoutNS(SDL_Event *event, Sint64 timeoutNS)
SDL_bool SDL_WaitEventTimeoutNS(SDL_Event *event, Sint64 timeoutNS)
{
SDL_VideoDevice *_this = SDL_GetVideoDevice();
SDL_Window *wakeup_window;
@ -1039,46 +1039,6 @@ int SDL_WaitEventTimeoutNS(SDL_Event *event, Sint64 timeoutNS)
SDL_bool include_sentinel = (timeoutNS == 0);
int result;
/* If there isn't a poll sentinel event pending, pump events and add one */
if (SDL_AtomicGet(&SDL_sentinel_pending) == 0) {
SDL_PumpEventsInternal(SDL_TRUE);
}
/* First check for existing events */
result = SDL_PeepEventsInternal(event, 1, SDL_GETEVENT, SDL_EVENT_FIRST, SDL_EVENT_LAST, include_sentinel);
if (result < 0) {
return 0;
}
if (include_sentinel) {
if (event) {
if (event->type == SDL_EVENT_POLL_SENTINEL) {
/* Reached the end of a poll cycle, and not willing to wait */
return 0;
}
} else {
/* Need to peek the next event to check for sentinel */
SDL_Event dummy;
if (SDL_PeepEventsInternal(&dummy, 1, SDL_PEEKEVENT, SDL_EVENT_FIRST, SDL_EVENT_LAST, SDL_TRUE) &&
dummy.type == SDL_EVENT_POLL_SENTINEL) {
SDL_PeepEventsInternal(&dummy, 1, SDL_GETEVENT, SDL_EVENT_POLL_SENTINEL, SDL_EVENT_POLL_SENTINEL, SDL_TRUE);
/* Reached the end of a poll cycle, and not willing to wait */
return 0;
}
}
}
if (result == 0) {
if (timeoutNS == 0) {
/* No events available, and not willing to wait */
return 0;
}
} else {
/* Has existing events */
return 1;
}
/* We should have completely handled timeoutNS == 0 above */
SDL_assert(timeoutNS != 0);
if (timeoutNS > 0) {
start = SDL_GetTicksNS();
expiration = start + timeoutNS;
@ -1087,36 +1047,80 @@ int SDL_WaitEventTimeoutNS(SDL_Event *event, Sint64 timeoutNS)
expiration = 0;
}
/* If there isn't a poll sentinel event pending, pump events and add one */
if (SDL_AtomicGet(&SDL_sentinel_pending) == 0) {
SDL_PumpEventsInternal(SDL_TRUE);
}
/* First check for existing events */
result = SDL_PeepEventsInternal(event, 1, SDL_GETEVENT, SDL_EVENT_FIRST, SDL_EVENT_LAST, include_sentinel);
if (result < 0) {
return SDL_FALSE;
}
if (include_sentinel) {
if (event) {
if (event->type == SDL_EVENT_POLL_SENTINEL) {
/* Reached the end of a poll cycle, and not willing to wait */
return SDL_FALSE;
}
} else {
/* Need to peek the next event to check for sentinel */
SDL_Event dummy;
if (SDL_PeepEventsInternal(&dummy, 1, SDL_PEEKEVENT, SDL_EVENT_FIRST, SDL_EVENT_LAST, SDL_TRUE) &&
dummy.type == SDL_EVENT_POLL_SENTINEL) {
SDL_PeepEventsInternal(&dummy, 1, SDL_GETEVENT, SDL_EVENT_POLL_SENTINEL, SDL_EVENT_POLL_SENTINEL, SDL_TRUE);
/* Reached the end of a poll cycle, and not willing to wait */
return SDL_FALSE;
}
}
}
if (result == 0) {
if (timeoutNS == 0) {
/* No events available, and not willing to wait */
return SDL_FALSE;
}
} else {
/* Has existing events */
return SDL_TRUE;
}
/* We should have completely handled timeoutNS == 0 above */
SDL_assert(timeoutNS != 0);
if (_this && _this->WaitEventTimeout && _this->SendWakeupEvent && !SDL_events_need_polling()) {
/* Look if a shown window is available to send the wakeup event. */
wakeup_window = SDL_find_active_window(_this);
if (wakeup_window) {
int status = SDL_WaitEventTimeout_Device(_this, wakeup_window, event, start, timeoutNS);
/* There may be implementation-defined conditions where the backend cannot
reliably wait for the next event. If that happens, fall back to polling. */
if (status >= 0) {
return status;
result = SDL_WaitEventTimeout_Device(_this, wakeup_window, event, start, timeoutNS);
if (result > 0) {
return SDL_TRUE;
} else if (result == 0) {
return SDL_FALSE;
} else {
/* There may be implementation-defined conditions where the backend cannot
* reliably wait for the next event. If that happens, fall back to polling.
*/
}
}
}
for (;;) {
SDL_PumpEventsInternal(SDL_TRUE);
switch (SDL_PeepEvents(event, 1, SDL_GETEVENT, SDL_EVENT_FIRST, SDL_EVENT_LAST)) {
case -1:
return 0;
case 0:
if (timeoutNS > 0 && SDL_GetTicksNS() >= expiration) {
/* Timeout expired and no events */
return 0;
}
SDL_Delay(1);
break;
default:
/* Has events */
return 1;
if (SDL_PeepEvents(event, 1, SDL_GETEVENT, SDL_EVENT_FIRST, SDL_EVENT_LAST) > 0) {
return SDL_TRUE;
}
Uint64 delay = SDL_MS_TO_NS(1);
if (timeoutNS > 0) {
Uint64 now = SDL_GetTicksNS();
if (now >= expiration) {
/* Timeout expired and no events */
return SDL_FALSE;
}
delay = SDL_min((expiration - now), delay);
}
SDL_DelayNS(delay);
}
}
@ -1200,8 +1204,10 @@ SDL_bool SDL_GetEventFilter(SDL_EventFilter *filter, void **userdata)
return event_ok.callback ? SDL_TRUE : SDL_FALSE;
}
void SDL_AddEventWatch(SDL_EventFilter filter, void *userdata)
int SDL_AddEventWatch(SDL_EventFilter filter, void *userdata)
{
int result = 0;
SDL_LockMutex(SDL_event_watchers_lock);
{
SDL_EventWatcher *event_watchers;
@ -1216,9 +1222,14 @@ void SDL_AddEventWatch(SDL_EventFilter filter, void *userdata)
watcher->userdata = userdata;
watcher->removed = SDL_FALSE;
++SDL_event_watchers_count;
} else {
SDL_OutOfMemory();
result = -1;
}
}
SDL_UnlockMutex(SDL_event_watchers_lock);
return result;
}
void SDL_DelEventWatch(SDL_EventFilter filter, void *userdata)