I manage a F/OSS project (https://github.com/AntiMicro/antimicro) that uses SDL 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_PeepEvents() + SDL_PumpEvents() as a “SDL_PollEvent() + Error Check”. In 2.0.4 and earlier, the following call:
SDL_PeepEvents(NULL, 1, SDL_GETEVENT, SDL_FIRSTEVENT, SDL_LASTEVENT)
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 the number of events waiting. The documentation is 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?