SDL_PollEvent() vs SDL_WaitEvent()

SDL_PollEvent() and SDL_WaitEvent() are two distinct functions for retrieving events from SDL's event queue, differing primarily in their behavior when no events are pending.

SDL_PollEvent()

Behavior: Checks the event queue for pending events.

• If an event exists, it fills the provided SDL_Event structure with the event data and returns 1 (true).
• If the queue is empty, it returns 0 (false) immediately without waiting.

Use Case: This is the standard choice for game loops and real-time applications. Because it doesn't wait, the rest of your game loop (updating game logic, rendering) can execute even if the user isn't providing any input. This prevents the application from freezing.

1// Typical game loop structure
2SDL_Event e;
3bool quit = false;
4while (!quit) {
5  // Handle events currently in the queue
6  while (SDL_PollEvent(&e)) { // Returns 0 immediately if queue empty
7    if (e.type == SDL_QUIT) {
8      quit = true;
9    }
10    // Handle other events like mouse motion, clicks, keys...
11    HandleEvent(e);
12  }
13
14  // Update game state (runs every frame)
15  UpdateGame();
16
17  // Render the scene (runs every frame)
18  RenderGame();
19}

SDL_WaitEvent()

Behavior: Checks the event queue for pending events.

• If an event exists, it fills the provided SDL_Event structure and returns 1 (true).
• If the queue is empty, it waits (blocks execution) until an event occurs, then fills the structure and returns 1. It can optionally time out if SDL_WaitEventTimeout() is used.

Use Case: This is more suitable for applications that don't need to constantly update or render unless there's user input, such as:

• GUI applications (like text editors or dialog boxes) where the display only needs to change in response to user actions.
• Simple tools or utilities.
• Situations where minimizing CPU usage when idle is a high priority. Using SDL_WaitEvent() allows the application's thread to sleep, consuming fewer resources.

1// Typical event-driven (non-game loop) structure
2SDL_Event e;
3bool quit = false;
4while (!quit) {
5  // Waits here until an event happens
6  if (SDL_WaitEvent(&e)) { // Blocks if queue is empty
7    if (e.type == SDL_QUIT) {
8      quit = true;
9    }
10    // Handle other events
11    HandleEventAndUpdateUIIfNeeded(e);
12  } else {
13    // SDL_WaitEvent returning 0 usually indicates an error
14    std::cerr << "Error waiting for event: "
15      << SDL_GetError() << '\n';
16    quit = true; // Exit on error
17  }
18}

Summary

Choose SDL_PollEvent() for applications that need continuous processing and rendering, and SDL_WaitEvent() for applications that only need to act when the user does something.