Pump the event loop, gathering events from the input devices.

This function updates the event queue and internal input device state.

pumpEvents gathers all the pending input information from devices and places it in the event queue. Without calls to pumpEvents no events would ever be placed on the queue. Often the need for calls to pumpEvents is hidden from the user since pollEvent and waitEvent implicitly call pumpEvents. However, if you are not polling or waiting for events (e.g. you are filtering them), then you must call pumpEvents to force an event queue update.

Thread safety

This function should only be called on the main thread.

See also

pollEvent, waitEvent

sdl3-bindgen-sys notes

Since: 3.2.0

Pump the event loop, gathering events from the input devices.

This function updates the event queue and internal input device state.

pumpEvents gathers all the pending input information from devices and places it in the event queue. Without calls to pumpEvents no events would ever be placed on the queue. Often the need for calls to pumpEvents is hidden from the user since pollEvent and waitEvent implicitly call pumpEvents. However, if you are not polling or waiting for events (e.g. you are filtering them), then you must call pumpEvents to force an event queue update.

Thread safety

This function should only be called on the main thread.

See also

pollEvent, waitEvent

sdl3-bindgen-sys notes

Since: 3.2.0

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 pumpEvents before calling this function. Otherwise, the events may not be ready to be filtered when you call peepEvents.

Returns

the number of events actually stored or -1 on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

pollEvent, pumpEvents, pushEvent

sdl3-bindgen-sys notes

Since: 3.2.0

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 pumpEvents before calling this function. Otherwise, the events may not be ready to be filtered when you call peepEvents.

Returns

the number of events actually stored or -1 on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

pollEvent, pumpEvents, pushEvent

sdl3-bindgen-sys notes

Since: 3.2.0

Check for the existence of a certain event type in the event queue.

If you need to check for a range of event types, use hasEvents instead.

Returns

true if events matching type are present, or false if events matching type are not present.

Thread safety

It is safe to call this function from any thread.

See also

hasEvents

sdl3-bindgen-sys notes

Since: 3.2.0

Check for the existence of a certain event type in the event queue.

If you need to check for a range of event types, use hasEvents instead.

Returns

true if events matching type are present, or false if events matching type are not present.

Thread safety

It is safe to call this function from any thread.

See also

hasEvents

sdl3-bindgen-sys notes

Since: 3.2.0

Check for the existence of certain event types in the event queue.

If you need to check for a single event type, use hasEvent instead.

Returns

true if events with type >= minType and <= maxType are present, or false if not.

Thread safety

It is safe to call this function from any thread.

See also

hasEvents

sdl3-bindgen-sys notes

Since: 3.2.0

Check for the existence of certain event types in the event queue.

If you need to check for a single event type, use hasEvent instead.

Returns

true if events with type >= minType and <= maxType are present, or false if not.

Thread safety

It is safe to call this function from any thread.

See also

hasEvents

sdl3-bindgen-sys notes

Since: 3.2.0

Clear events of a specific type from the event queue.

This will unconditionally remove any events from the queue that match type. If you need to remove a range of event types, use flushEvents instead.

It's also normal to just ignore events you don't care about in your event loop without calling this function.

This function only affects currently queued events. If you want to make sure that all pending OS events are flushed, you can call pumpEvents on the main thread immediately before the flush call.

If you have user events with custom data that needs to be freed, you should use peepEvents to remove and clean up those events before calling this function.

Thread safety

It is safe to call this function from any thread.

See also

flushEvents

sdl3-bindgen-sys notes

Since: 3.2.0

Clear events of a specific type from the event queue.

This will unconditionally remove any events from the queue that match type. If you need to remove a range of event types, use flushEvents instead.

It's also normal to just ignore events you don't care about in your event loop without calling this function.

This function only affects currently queued events. If you want to make sure that all pending OS events are flushed, you can call pumpEvents on the main thread immediately before the flush call.

If you have user events with custom data that needs to be freed, you should use peepEvents to remove and clean up those events before calling this function.

Thread safety

It is safe to call this function from any thread.

See also

flushEvents

sdl3-bindgen-sys notes

Since: 3.2.0

Clear events of a range of types from the event queue.

This will unconditionally remove any events from the queue that are in the range of minType to maxType, inclusive. If you need to remove a single event type, use flushEvent instead.

It's also normal to just ignore events you don't care about in your event loop without calling this function.

This function only affects currently queued events. If you want to make sure that all pending OS events are flushed, you can call pumpEvents on the main thread immediately before the flush call.

Thread safety

It is safe to call this function from any thread.

See also

flushEvent

sdl3-bindgen-sys notes

Since: 3.2.0

Clear events of a range of types from the event queue.

This will unconditionally remove any events from the queue that are in the range of minType to maxType, inclusive. If you need to remove a single event type, use flushEvent instead.

It's also normal to just ignore events you don't care about in your event loop without calling this function.

This function only affects currently queued events. If you want to make sure that all pending OS events are flushed, you can call pumpEvents on the main thread immediately before the flush call.

Thread safety

It is safe to call this function from any thread.

See also

flushEvent

sdl3-bindgen-sys notes

Since: 3.2.0

Poll for currently pending events.

If event is not NULL, the next event is removed from the queue and stored in the SDL_Event structure pointed to by event.

If event is NULL, it simply returns true if there is an event in the queue, but will not remove it from the queue.

As this function may implicitly call pumpEvents, you can only call this function in the thread that initialized the video subsystem.

pollEvent is the favored way of receiving system events since it can be done from the main loop and does not suspend the main loop while waiting on an event to be posted.

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

    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
    }
    

Note that Windows (and possibly other platforms) has a quirk about how it handles events while dragging/resizing a window, which can cause this function to block for significant amounts of time. Technical explanations and solutions are discussed on the wiki:

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

Returns

true if this got an event or false if there are none available.

Thread safety

This function should only be called on the main thread.

See also

pushEvent, waitEvent, waitEventTimeout

sdl3-bindgen-sys notes

Since: 3.2.0

Poll for currently pending events.

If event is not NULL, the next event is removed from the queue and stored in the SDL_Event structure pointed to by event.

If event is NULL, it simply returns true if there is an event in the queue, but will not remove it from the queue.

As this function may implicitly call pumpEvents, you can only call this function in the thread that initialized the video subsystem.

pollEvent is the favored way of receiving system events since it can be done from the main loop and does not suspend the main loop while waiting on an event to be posted.

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

    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
    }
    

Note that Windows (and possibly other platforms) has a quirk about how it handles events while dragging/resizing a window, which can cause this function to block for significant amounts of time. Technical explanations and solutions are discussed on the wiki:

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

Returns

true if this got an event or false if there are none available.

Thread safety

This function should only be called on the main thread.

See also

pushEvent, waitEvent, waitEventTimeout

sdl3-bindgen-sys notes

Since: 3.2.0

Wait indefinitely for the next available event.

If event is not NULL, the next event is removed from the queue and stored in the SDL_Event structure pointed to by event.

As this function may implicitly call pumpEvents, you can only call this function in the thread that initialized the video subsystem.

Returns

true on success or false if there was an error while waiting for events; call getError for more information.

Thread safety

This function should only be called on the main thread.

See also

pollEvent, pushEvent, waitEventTimeout

sdl3-bindgen-sys notes

Since: 3.2.0

Wait indefinitely for the next available event.

If event is not NULL, the next event is removed from the queue and stored in the SDL_Event structure pointed to by event.

As this function may implicitly call pumpEvents, you can only call this function in the thread that initialized the video subsystem.

Returns

true on success or false if there was an error while waiting for events; call getError for more information.

Thread safety

This function should only be called on the main thread.

See also

pollEvent, pushEvent, waitEventTimeout

sdl3-bindgen-sys notes

Since: 3.2.0

Wait until the specified timeout (in milliseconds) for the next available event.

If event is not NULL, the next event is removed from the queue and stored in the SDL_Event structure pointed to by event.

As this function may implicitly call pumpEvents, you can only call this function in the thread that initialized the video subsystem.

The timeout is not guaranteed, the actual wait time could be longer due to system scheduling.

Returns

true if this got an event or false if the timeout elapsed without any events available.

Thread safety

This function should only be called on the main thread.

See also

pollEvent, pushEvent, waitEvent

sdl3-bindgen-sys notes

Since: 3.2.0

Wait until the specified timeout (in milliseconds) for the next available event.

If event is not NULL, the next event is removed from the queue and stored in the SDL_Event structure pointed to by event.

As this function may implicitly call pumpEvents, you can only call this function in the thread that initialized the video subsystem.

The timeout is not guaranteed, the actual wait time could be longer due to system scheduling.

Returns

true if this got an event or false if the timeout elapsed without any events available.

Thread safety

This function should only be called on the main thread.

See also

pollEvent, pushEvent, waitEvent

sdl3-bindgen-sys notes

Since: 3.2.0

Add an event to the event queue.

The event queue can actually be used as a two way communication channel. Not only can events be read from the queue, but the user can also push their own events onto it. event is a pointer to the event structure you wish to push onto the queue. The event is copied into the queue, and the caller may dispose of the memory pointed to after pushEvent returns.

Note: Pushing device input events onto the queue doesn't modify the state of the device within SDL.

Note: Events pushed onto the queue with pushEvent get passed through the event filter but events added with peepEvents do not.

For pushing application-specific events, please use registerEvents to get an event type that does not conflict with other code that also wants its own custom event types.

Returns

true on success, false if the event was filtered or on failure; call getError for more information. A common reason for error is the event queue being full.

Thread safety

It is safe to call this function from any thread.

See also

peepEvents, pollEvent, registerEvents

sdl3-bindgen-sys notes

Since: 3.2.0

Add an event to the event queue.

The event queue can actually be used as a two way communication channel. Not only can events be read from the queue, but the user can also push their own events onto it. event is a pointer to the event structure you wish to push onto the queue. The event is copied into the queue, and the caller may dispose of the memory pointed to after pushEvent returns.

Note: Pushing device input events onto the queue doesn't modify the state of the device within SDL.

Note: Events pushed onto the queue with pushEvent get passed through the event filter but events added with peepEvents do not.

For pushing application-specific events, please use registerEvents to get an event type that does not conflict with other code that also wants its own custom event types.

Returns

true on success, false if the event was filtered or on failure; call getError for more information. A common reason for error is the event queue being full.

Thread safety

It is safe to call this function from any thread.

See also

peepEvents, pollEvent, registerEvents

sdl3-bindgen-sys notes

Since: 3.2.0

Set up a filter to process all events before they are added to the internal event queue.

If you just want to see events without modifying them or preventing them from being queued, you should use addEventWatch instead.

If the filter function returns true when called, then the event will be added to the internal queue. If it returns false, then the event will be dropped from the queue, but the internal state will still be updated. This allows selective filtering of dynamically arriving events.

WARNING: Be very careful of what you do in the event filter function, as it may run in a different thread! The 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.

On platforms that support it, if the quit event is generated by an interrupt signal (e.g. pressing Ctrl-C), it will be delivered to the application at the next event poll.

Note: Disabled events never make it to the event filter function; see setEventEnabled.

Note: Events pushed onto the queue with pushEvent get passed through the event filter, but events pushed onto the queue with peepEvents do not.

Thread safety

It is safe to call this function from any thread.

See also

addEventWatch, setEventEnabled, getEventFilter, peepEvents, pushEvent

sdl3-bindgen-sys notes

Since: 3.2.0

Set up a filter to process all events before they are added to the internal event queue.

If you just want to see events without modifying them or preventing them from being queued, you should use addEventWatch instead.

If the filter function returns true when called, then the event will be added to the internal queue. If it returns false, then the event will be dropped from the queue, but the internal state will still be updated. This allows selective filtering of dynamically arriving events.

WARNING: Be very careful of what you do in the event filter function, as it may run in a different thread! The 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.

On platforms that support it, if the quit event is generated by an interrupt signal (e.g. pressing Ctrl-C), it will be delivered to the application at the next event poll.

Note: Disabled events never make it to the event filter function; see setEventEnabled.

Note: Events pushed onto the queue with pushEvent get passed through the event filter, but events pushed onto the queue with peepEvents do not.

Thread safety

It is safe to call this function from any thread.

See also

addEventWatch, setEventEnabled, getEventFilter, peepEvents, pushEvent

sdl3-bindgen-sys notes

Since: 3.2.0

Query the current event filter.

This function can be used to "chain" filters, by saving the existing filter before replacing it with a function that will call that saved filter.

Returns

true on success or false if there is no event filter set.

Thread safety

It is safe to call this function from any thread.

See also

setEventFilter

sdl3-bindgen-sys notes

Since: 3.2.0

Query the current event filter.

This function can be used to "chain" filters, by saving the existing filter before replacing it with a function that will call that saved filter.

Returns

true on success or false if there is no event filter set.

Thread safety

It is safe to call this function from any thread.

See also

setEventFilter

sdl3-bindgen-sys notes

Since: 3.2.0

Add a callback to be triggered when an event is added to the event queue.

filter will be called when an event happens, and its return value is ignored.

WARNING: Be very careful of what you do in the event filter function, as it may run in a different thread!

If the quit event is generated by a signal (e.g. SIGINT), it will bypass the internal queue and be delivered to the watch callback immediately, and arrive at the next event poll.

Note: the callback is called for events posted by the user through pushEvent, but not for disabled events, nor for events by a filter callback set with setEventFilter, nor for events posted by the user through peepEvents.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

removeEventWatch, setEventFilter

sdl3-bindgen-sys notes

Since: 3.2.0

Add a callback to be triggered when an event is added to the event queue.

filter will be called when an event happens, and its return value is ignored.

WARNING: Be very careful of what you do in the event filter function, as it may run in a different thread!

If the quit event is generated by a signal (e.g. SIGINT), it will bypass the internal queue and be delivered to the watch callback immediately, and arrive at the next event poll.

Note: the callback is called for events posted by the user through pushEvent, but not for disabled events, nor for events by a filter callback set with setEventFilter, nor for events posted by the user through peepEvents.

Returns

true on success or false on failure; call getError for more information.

Thread safety

It is safe to call this function from any thread.

See also

removeEventWatch, setEventFilter

sdl3-bindgen-sys notes

Since: 3.2.0

Remove an event watch callback added with addEventWatch.

This function takes the same input as addEventWatch to identify and delete the corresponding callback.

Thread safety

It is safe to call this function from any thread.

See also

addEventWatch

sdl3-bindgen-sys notes

Since: 3.2.0

Remove an event watch callback added with addEventWatch.

This function takes the same input as addEventWatch to identify and delete the corresponding callback.

Thread safety

It is safe to call this function from any thread.

See also

addEventWatch

sdl3-bindgen-sys notes

Since: 3.2.0

Run a specific filter function on the current event queue, removing any events for which the filter returns false.

See setEventFilter for more information. Unlike setEventFilter, this function does not change the filter permanently, it only uses the supplied filter until this function returns.

Thread safety

It is safe to call this function from any thread.

See also

getEventFilter, setEventFilter

sdl3-bindgen-sys notes

Since: 3.2.0

Set the state of processing events by type.

Thread safety

It is safe to call this function from any thread.

See also

eventEnabled

sdl3-bindgen-sys notes

Since: 3.2.0

Set the state of processing events by type.

Thread safety

It is safe to call this function from any thread.

See also

eventEnabled

sdl3-bindgen-sys notes

Since: 3.2.0

Query the state of processing events by type.

Returns

true if the event is being processed, false otherwise.

Thread safety

It is safe to call this function from any thread.

See also

setEventEnabled

sdl3-bindgen-sys notes

Since: 3.2.0

Query the state of processing events by type.

Returns

true if the event is being processed, false otherwise.

Thread safety

It is safe to call this function from any thread.

See also

setEventEnabled

sdl3-bindgen-sys notes

Since: 3.2.0

Allocate a set of user-defined events, and return the beginning event number for that set of events.

Returns

the beginning event number, or 0 if numevents is invalid or if there are not enough user-defined events left.

Thread safety

It is safe to call this function from any thread.

See also

pushEvent

sdl3-bindgen-sys notes

Since: 3.2.0

Allocate a set of user-defined events, and return the beginning event number for that set of events.

Returns

the beginning event number, or 0 if numevents is invalid or if there are not enough user-defined events left.

Thread safety

It is safe to call this function from any thread.

See also

pushEvent

sdl3-bindgen-sys notes

Since: 3.2.0

Get window associated with an event.

Returns

the associated window on success or NULL if there is none.

Thread safety

It is safe to call this function from any thread.

See also

pollEvent, waitEvent, waitEventTimeout

sdl3-bindgen-sys notes

Since: 3.2.0

Get window associated with an event.

Returns

the associated window on success or NULL if there is none.

Thread safety

It is safe to call this function from any thread.

See also

pollEvent, waitEvent, waitEventTimeout

sdl3-bindgen-sys notes

Since: 3.2.0

Generate an English description of an event.

This will fill buf with a null-terminated string that might look something like this:

    SDL_EVENT_MOUSE_MOTION (timestamp=1140256324 windowid=2 which=0 state=0 x=492.99 y=139.09 xrel=52 yrel=6)
    

The exact format of the string is not guaranteed; it is intended for logging purposes, to be read by a human, and not parsed by a computer.

The returned value follows the same rules as SDL_snprintf(): buf will always be NULL-terminated (unless buflen is zero), and will be truncated if buflen is too small. The return code is the number of bytes needed for the complete string, not counting the NULL-terminator, whether the string was truncated or not. Unlike SDL_snprintf(), though, this function never returns -1.

Returns

number of bytes needed for the full string, not counting the null-terminator byte.

Thread safety

It is safe to call this function from any thread.

sdl3-bindgen-sys notes

Since: 3.4.0

Generate an English description of an event.

This will fill buf with a null-terminated string that might look something like this:

    SDL_EVENT_MOUSE_MOTION (timestamp=1140256324 windowid=2 which=0 state=0 x=492.99 y=139.09 xrel=52 yrel=6)
    

The exact format of the string is not guaranteed; it is intended for logging purposes, to be read by a human, and not parsed by a computer.

The returned value follows the same rules as SDL_snprintf(): buf will always be NULL-terminated (unless buflen is zero), and will be truncated if buflen is too small. The return code is the number of bytes needed for the complete string, not counting the NULL-terminator, whether the string was truncated or not. Unlike SDL_snprintf(), though, this function never returns -1.

Returns

number of bytes needed for the full string, not counting the null-terminator byte.

Thread safety

It is safe to call this function from any thread.

sdl3-bindgen-sys notes

Since: 3.4.0