Does SDL_PollEvent() Permanently Remove Events from the Queue in SDL2?

Yes, when SDL_PollEvent() successfully retrieves an event from SDL's internal event queue, that specific event instance is permanently removed from the queue.

Understanding Queues and Popping

Think of SDL's event queue like a line of people waiting for service.

• New events arriving from the operating system (via SDL_PumpEvents() or the internal pumping within SDL_PollEvent()) are added to the back of the line (queue).
• SDL_PollEvent() looks at the person at the front of the line.
• If someone is there (SDL_PollEvent() returns true), it "serves" that person (copies the event data into the SDL_Event variable you provided) and that person leaves the line (the event is removed from the queue).
• If the line is empty (SDL_PollEvent() returns false), nothing happens to the queue.

Event Data vs. Queue Instance

It's helpful to distinguish between the data representing the event and the event's place in the queue.

When SDL_PollEvent(&myEvent) returns true:

1. SDL identifies the event structure at the front of its internal queue.
2. SDL copies the data from that internal event structure into your myEvent variable.
3. SDL then removes the internal event structure from the front of its queue.

Your myEvent variable now holds a copy of the information about the event that was at the front of the queue. The original instance in the queue itself is gone.

1SDL_Event currentEvent;
2bool shouldContinue{true};
3
4while (shouldContinue) {
5  // Check the front of the queue
6  while (SDL_PollEvent(&currentEvent)) {
7    // If an event was found (SDL_PollEvent returned true):
8    // 1. currentEvent is now filled with data from that event.
9    // 2. That specific event is REMOVED from SDL's queue.
10
11    if (currentEvent.type == SDL_QUIT) {
12      // We process the data we received
13      shouldContinue = false;
14      // The original SDL_QUIT event instance is gone from the queue.
15    } else if (currentEvent.type == SDL_KEYDOWN) {
16      // Process key press based on data in currentEvent
17      // The original SDL_KEYDOWN event instance is gone.
18    }
19    // If we don't handle an event type here, its data in
20    // currentEvent is overwritten on the next loop iteration
21    // (if another event exists), and the original event instance
22    // is still gone from the queue.
23  }
24  // ... Update ...
25  // ... Render ...
26}

Because SDL_PollEvent() removes the event, it's crucial that your event-handling logic (the code inside the while(SDL_PollEvent(...)) loop) fully processes or makes a decision about each event as it receives it.

If you ignore an event after polling it, you won't get a second chance to retrieve that specific event instance from the queue later - it's gone.