[SDL] Changes to SDL_PeepEvents() in 2.0.5

[Jeff Backus]

Hi List,

I manage a F/OSS project(1) that uses libSDL to manage joystick/gamepad
input. We experienced a breakage when upgrading to 2.0.5 due to a change
in the behavior of SDL_PeepEvents(). We use SDL_PumpEvents plus the
following call:
SDL_PeepEvents(NULL, 1, SDL_GETEVENT, SDL_FIRSTEVENT, SDL_LASTEVENT)
as a "SDL_PollEvent + Error Check", since SDL_PollEvent() only returns
whether an event is waiting. In 2.0.4 and earlier, the above call would
return -1, 0, or 1 depending on if there was an error, no events
waiting, or 1 or more events waiting, respectively. In 2.0.5, the above
call now returns -1, 0, or $numEvents. The documentation is a little
ambiguous as to what happens when the first argument is NULL, and the
summary for changeset 10060:739bc5c7d339 (which seems to be where the
change in behavior was introduced) implies that passing in NULL is an
undocumented / underdefined usecase.

So, my question is, is using SDL_PumpEvents() + SDL_PeepEvents(NULL,
...) a supported alternative to SDL_PollEvent()? If so, could we please
update the documentation to clarify how SDL_PeepEvents() should behave
when the first argument is NULL?

Thanks!
Jeff

1: https://github.com/AntiMicro/antimicro