devela::_dep::sdl3::sys::events

Function SDL_PeepEvents

pub unsafe extern "C" fn SDL_PeepEvents(
    events: *mut SDL_Event,
    numevents: i32,
    action: SDL_EventAction,
    minType: u32,
    maxType: u32,
) -> i32
Available on crate feature dep_sdl3 only.
Expand description

Check the event queue for messages and optionally return them.

action may be any of the following:

  • SDL_ADDEVENT: up to numevents events will be added to the back of the event queue.
  • 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. If you pass NULL for events, then numevents is ignored and the total number of matching events will be returned.
  • 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.

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().

§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.
  • 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.
  • action: action to take; see [[#action|Remarks]] for details.
  • minType: minimum value of the event type to be considered; SDL_EVENT_FIRST is a safe choice.
  • maxType: maximum value of the event type to be considered; SDL_EVENT_LAST is a safe choice.

§Return value

Returns the number of events actually stored or -1 on failure; call SDL_GetError() for more information.

§Thread safety

It is safe to call this function from any thread.

§Availability

This function is available since SDL 3.2.0.

§See also