Hey there.
While writing code to use SDL_WaitEventTimeout() from SDL 2, I was surprised to find that there is no separate return value for the timeout case. Instead, 0 means that either an error occurred, or the timeout was reached.
It is not clear to me how the caller is supposed to determine whether an error occurred or the timeout was reached when zero is returned, and I think the documentation for the function ought to be improved to provide some kind of guidance.
Maybe the intention is that the caller should clear errors bore calling SDL_WaitEventTimeout() and then use SDL_GetError() to check if an error occurred. That, however, seems to be an unsafe patterns, which is also discouraged in the documentation for SDL_GetError(), if I understand correctly.
For SDL 3, it seems to me that we have the opportunity to improve the function, such that it returns some value other than 0 and 1 to indicate the timeout case.
Looking at the implementation of SDL_WaitEventTimeout(), it seems to me that such a change is fairly trivial to implement. That is, we can return a different value here and in a couple of other places above.
Another option would be to add a timedOut boolean argument, which should then be checked by the caller upon return (on success). This is also safer in that it would trigger a compile-time error when upgrading an application from SDL 2 to SDL 3.
Do you agree that this kind of change is a good idea for SDL 3?