NULL-Events in SDL_PollEvent?

SDL Development
1

In the SDL2 wiki, it says:

If event is NULL, it simply returns 1 if there is an event in the queue, but will not remove it from the queue.

It keeps talking about NULL, but in no example ever did I find anyone checking for NULL or handling it.

The way this is worded, it sounds like an event pileup will happen if you keep getting events that are NULL. Why is a NULL event kept instead of automatically discarded?

Help me understand how this works and what I should do

2

That doesn’t mean it isn’t useful.

Some time ago, when I was programming events handling in my engine, I used it to check how many events were in the queue (without pulling anything from it). If the queue was empty, I didn’t do anything else. However, if there were any events, I triggered the initialization of the engine subsystems, then processed the events, and finally finalized the update of the subsystems. This initialization and finalization only had to be performed if the event queue contained something in a given game frame.

Something like this pseudocode:

if SDL_PollEvent(nil) > 0 then
begin
  SubsystemsUpdateBegin();

  while SDL_PollEvent(@Event) = 1 do
    SubsystemsUpdate(Event);

  SubsystemsUpdateEnd();
end;

Currently, I don’t use it — I have event handling implemented differently and I no longer need to check the number of events. This still does not change the fact that this option may be useful.

3

The wiki talks about you, the caller, intentionally passing NULL as argument like this: SDL_PollEvent(NULL). This can be used to check if there are any events left to handle without removing any events from the queue.

4

You can also check this with the SDL_PeepEvents function, using the SDL_PEEKEVENT flag. It will also check whether something is in the queue, without extracting events from it.

The problem is that in order to process the events, you need to call the SDL_PumpEvents function in a given game frame. This can be done explicitly, but if you use the SDL_PollEvent function, it internally calls SDL_PumpEvents for you (if needed).

If the event processing code is written in such a way that it may not call SDL_PollEvent in a given frame, it should either be called manually by specifying null in the parameter (checking if the queue is or is not empty), or SDL_PumpEvents should be called initially, before touching the queue.