SDL_PollEvent() vs SDL_WaitEvent()

What's the difference between SDL_PollEvent() and 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.

// Typical game loop structure
SDL_Event e;
bool quit = false;
while (!quit) {
  // Handle events currently in the queue
  while (SDL_PollEvent(&e)) { // Returns 0 immediately if queue empty
    if (e.type == SDL_QUIT) {
      quit = true;
    }
    // Handle other events like mouse motion, clicks, keys...
    HandleEvent(e);
  }

  // Update game state (runs every frame)
  UpdateGame();

  // Render the scene (runs every frame)
  RenderGame();
}

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.
// Typical event-driven (non-game loop) structure
SDL_Event e;
bool quit = false;
while (!quit) {
  // Waits here until an event happens
  if (SDL_WaitEvent(&e)) { // Blocks if queue is empty
    if (e.type == SDL_QUIT) {
      quit = true;
    }
    // Handle other events
    HandleEventAndUpdateUIIfNeeded(e);
  } else {
    // SDL_WaitEvent returning 0 usually indicates an error
    std::cerr << "Error waiting for event: "
      << SDL_GetError() << '\n';
    quit = true; // Exit on error
  }
}

Summary

FeatureSDL_PollEvent()SDL_WaitEvent()
Queue EmptyReturns 0 immediatelyBlocks (waits) until an event arrives
Return Value1 (event), 0 (no event/error)1 (event), 0 (error)
CPU UsageHigher (loop runs continuously)Lower (sleeps when idle)
Primary UseGame loops, real-time applicationsGUI applications, low-resource tools

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.

Mouse Input Basics

Discover how to process mouse input, including position tracking and button presses

Questions & Answers

Answers are generated by AI models and may not have been reviewed. Be mindful when running any code on your device.

SDL Coordinate System: Why Y-Down?
Why does SDL use a y-down coordinate system instead of y-up?
SDL: Get Mouse Screen Coordinates
Can I get mouse coordinates relative to the screen instead of the window?
SDL Event Timestamp Field
What does the timestamp field in the event structures mean?
SDL Event which Field
What does the which field in the event structures refer to (e.g., multiple mice)?
SDL: Custom Mouse Cursor Appearance
Can I change the mouse cursor's appearance (e.g., to a crosshair)?
SDL Double Click Timing Customization
How does SDL determine the time window for registering a double click? Can I customize this timing?
Retrieve Mouse Position
How do I retrieve the current position of the mouse cursor in SDL?
SDL Mouse Motion Events
What is the difference between SDL_MOUSEMOTION and SDL_MouseMotionEvent?
Detect Double Clicks in SDL
How can I detect double clicks using SDL?
SDL_MouseButtonEvent Structure
What is the SDL_MouseButtonEvent structure used for?
Calculate Mouse Position
How can I calculate the distance of the mouse cursor from the edges of the window?
Or Ask your Own Question
Get an immediate answer to your specific question using our AI assistant