SDL_PollEvent(3)

✨ SDL_PollEvent ✨

ok bestie, welcome to SDL_PollEvent, one of the SDL3 FUNCTIONS 🎀 this one's literally the main character of your game loop, no cap.

---

🌸 NAME 🌸

SDL_PollEvent — poll for currently pending events. that's it, that's the vibe. 💅

---

🦋 SYNOPSIS 🦋

#include <SDL3/SDL_events.h>

bool SDL_PollEvent(SDL_Event *event);

---

✨ DESCRIPTION ✨

okay so. if event is not NULL, the next event gets removed from the queue and stored in the SDL_Event structure that event points to. gone. popped. slayed. 💅

if event is NULL, it just returns true if there's an event chillin' in the queue, but it will not remove it. like, it'll peek but it won't touch. respectful king 🫶

⚠️ important caveat bestie: since this function may implicitly call SDL_PumpEvents(), you can only call this function in the thread that initialized the video subsystem. do not try it anywhere else, it's giving chaos 😭

SDL_PollEvent() is the favored way of receiving system events, because you can do it right from your main loop and it does not suspend the main loop while waiting on an event to be posted. no blocking, no waiting around, we move. 🔥

the common practice is to fully process the event queue once every frame, usually as a first step before updating the game's state. iconic behavior, truly:

while (game_is_still_running) {
    SDL_Event event;
    while (SDL_PollEvent(&event)) {  // poll until all events are handled!
        // decide what to do with this event.
    }

    // update game state, draw the current frame
}

ngl there's a little quirk you should know about 👀 Windows (and possibly other platforms) handles events weird while you're dragging/resizing a window, which can cause this function to block for significant amounts of time. not the vibe. the technical explanations and solutions are discussed on the wiki:

https://wiki.libsdl.org/SDL3/AppFreezeDuringDrag

go read it, it's worth it fr fr 📖

---

🎀 FUNCTION PARAMETERS 🎀

• event — the SDL_Event structure to be filled with the next event from the queue, or NULL.

---

💖 RETURN VALUE 💖

returns true if this got an event, or false if there are none available. simple as that, bestie ✨

---

🧚 THREAD SAFETY 🧚

this function should only be called on the main thread. main character energy only, we don't do side threads here 👑

---

⭐ AVAILABILITY ⭐

this function is available since SDL 3.2.0. so if you're on something older... bestie. upgrade. 🙈

---

🌈 SEE ALSO 🌈

• SDL_PushEvent(3)
• SDL_WaitEvent(3)
• SDL_WaitEventTimeout(3)

---

and that's the whole page!! 💜 this was brought to you by Simple Directmedia Layer, version SDL 3.4.18 🎀 go poll some events, bestie, you got this 🫶✨🌸