SDL_SetEventFilter(3)

💖 SDL_SetEventFilter — the SDL3 FUNCTIONS era 💖

okay bestie, sit down, hydrate, because we're talking about the bouncer at the door of your event queue 👑 This is SDL_SetEventFilter(3) from the SDL3 FUNCTIONS collection and it is literally the vibe-check station for every event trying to get into your app.

---

✨ NAME ✨

SDL_SetEventFilter — set up a filter to process all events before they get added to the internal event queue. like, before. pre-queue. the velvet rope moment 🎀

---

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_events.h>

void SDL_SetEventFilter(SDL_EventFilter filter, void *userdata);

---

🦋 DESCRIPTION 🦋

okay so first thing, real talk: if you just want to peek at events without modifying them or stopping them from getting queued, you do NOT want this function, you want SDL_AddEventWatch() instead. different girl, different job. 💅

Now the actual tea. When your filter function gets called and it returns true, the event gets added to the internal queue. When it returns false, the event gets dropped from the queue — but bestie, listen, the internal state still gets updated. That's the whole point: it lets you do selective filtering of dynamically arriving events. you're curating. you're the editor. ✨

⚠️ WARNING, and I mean this with my whole chest: be VERY careful what you do inside the event filter function, because it may run on a different thread! 😭 The one exception is handling of SDL_EVENT_WINDOW_EXPOSED, which is guaranteed to be sent from the OS on the main thread, and you are expected to redraw your window in response to this event. that one's safe, bestie. the rest? watch yourself.

On platforms that support it, if the quit event is generated by an interrupt signal (like when someone hits Ctrl-C), it will be delivered to the application at the next event poll. not instantly. next poll. noted. 📝

🫶 Note: disabled events never make it to the event filter function — see SDL_SetEventEnabled().

🫶 Note: events pushed onto the queue with SDL_PushEvent() do get passed through the event filter, but events pushed onto the queue with SDL_PeepEvents() do not. yes this is a little unhinged. no I don't make the rules. 💀

---

🎀 FUNCTION PARAMETERS 🎀

• filter — a function to call when an event happens. your little event gremlin. 🧚
• userdata — a pointer that is passed to filter. it's the little bag of snacks you hand your gremlin so it knows what's up. 🍓

---

💜 THREAD SAFETY 💜

It is safe to call this function from any thread. slay. multitask. we love a function with no main-character-only energy. 👑

---

🌈 AVAILABILITY 🌈

This function is available since SDL 3.2.0. if you're on something older, no cap, you simply do not have her yet. 🙈

---

⭐ SEE ALSO ⭐

• SDL_AddEventWatch(3)
• SDL_SetEventEnabled(3)
• SDL_GetEventFilter(3)
• SDL_PeepEvents(3)
• SDL_PushEvent(3)

go read those too, iykyk 📚

---

and that's the page!! brought to you by Simple Directmedia Layer, running the SDL 3.4.18 release, and yeah the manpage itself carries the date SDL_SetEventFilter(3) in its footer so we're shouting her out here too 💖 mwah, go filter something, bestie 🫶✨