proposal/question: better document SDL_PeepEvents, and/or provide SDL_CountEvents

[rohlem]

Originally I was looking around event code to implement one of these things, but my use case didn't end up needing any of them. I thought I might start up discussion anyway, so if there's a clear decision someone can go ahead and implement it.

For context, SDL_PeepEvents has had a "hidden usage mode" present since SDL 2.0.0 that was never documented, but always used to implement SDL_HasEvent (and -s). Basically, if you pass events=NULL as first argument (in which case third argument action MUST NOT BE SDL_ADDEVENT), then the function can be used to check for the presence of events without retrieving them, meaning you don't need to allocate buffer to store them in.

Up until SDL 2.0.4 inclusively, this looked for a single event to return 1 or 0, but starting with SDL 2.0.5 it instead always counts all events (ignoring the numevents argument). The (probably very minor) issue with just documenting the behaviour is that the earlier versions used to just return 0 or 1.

Depending on whether this interface is considered internal-only or not, it might make sense to document this option. Alternatively, to expose this in a more user-friendly way, we could add functions SDL_CountEvent/SDL_CountEvents, which would return not just a boolean but an integer giving the amount.

Another unintended side-effect of the change in 2.0.5 is that SDL_HasEvent(s) now doesn't stop at the first event, but instead always searches the entire queue - probably not a huge performance hazard, but seems like unnecessary work nonetheless. So that's another change I propose, to re-enable some way to stop counting after a given number of events (maybe don't ignore numevents when > 0).