SDL_PeepEvents(3)

📦
version 3.4.18 · 10 versions
, in fedora 43, fedora 44

✨ SDL_PeepEvents ✨

ok so bestie, we're in the SDL3 FUNCTIONS section of the SDL_PeepEvents(3) manual and this one is genuinely such a vibe — it's the peeky-looky function for your event queue 💅

🎀 NAME 🎀

SDL_PeepEvents — check the event queue for messages and optionally return them.

like, it goes in, it looks around, and it maybe brings stuff back. iconic behavior tbh.

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_events.h>

int SDL_PeepEvents(SDL_Event *events, int numevents, SDL_EventAction action, Uint32 minType, Uint32 maxType);

🦋 DESCRIPTION 🦋

action can be literally any of these three, and ngl they each have a whole different personality:

  • SDL_ADDEVENT — up to numevents events will be added to the back of the event queue. yes, back. the end. the tail. the line-ends-here spot 🫶
  • SDL_PEEKEVENT — numevents events at the front of the event queue, within the specified minimum and maximum type, will be returned to the caller and will _not_ be removed from the queue. look-but-don't-touch energy fr fr. 👀 and listen — if you pass NULL for events, then numevents is ignored and the total number of matching events will be returned. free little count for you, no notes.
  • SDL_GETEVENT — up to numevents events at the front of the event queue, within the specified minimum and maximum type, will be returned to the caller and will be removed from the queue. okay so this one actually takes them. gone. bye. snatched. 💀
heads up bestie!! you may have to call SDL_PumpEvents() before calling this function. otherwise, the events may not be ready to be filtered when you call SDL_PeepEvents(). don't skip the pump, that's the whole ritual ✨

💖 FUNCTION PARAMETERS 💖

  • events — destination buffer for the retrieved events, may be NULL to leave the events in the queue and return the number of events that would have been stored. lowkey a "just tell me how many" mode and honestly? we love a buffer-less option.
  • numevents — if action is SDL_ADDEVENT, the number of events to add back to the event queue; if action is SDL_PEEKEVENT or SDL_GETEVENT, the maximum number of events to retrieve. same name, different job, main character duality tbh 👑
  • action — action to take; see [Remarks](#remarks) for details.
  • minType — minimum value of the event type to be considered; SDL_EVENT_FIRST is a safe choice. the safe choice!! the little safety blanket 🧚
  • maxType — maximum value of the event type to be considered; SDL_EVENT_LAST is a safe choice. matching safety blanket, we love a symmetrical queen 🌈

⭐ RETURN VALUE ⭐

Returns the number of events actually stored, or -1 on failure; call SDL_GetError() for more information. so if you see that -1... go ask SDL_GetError() what happened, she always knows 😭

🔥 THREAD SAFETY 🔥

It is safe to call this function from any thread. no cap. every thread. go off 🫶

💜 AVAILABILITY 💜

This function is available since SDL 3.2.0.

🍓 SEE ALSO 🍓

and that's the whole page bestie!! brought to you by Simple Directmedia Layer, running SDL 3.4.18 — mwah, go peek some events, ily 💖✨🎀

📦 where this page comes from