Class Sdl

Namespace: Sdl3Sharp

Assembly: Sdl3Sharp.dll

Represents the lifetime of SDL

public sealed class Sdl : IDisposable

Inheritance: object

Sdl

Implements: IDisposable

Inherited Members: object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

You must create an instance of Sdl in order to use most of the API. Creating an instance of Sdl initializes SDL (while disposing it shuts down SDL).

There can be only a single instance of Sdl at a time!

Constructors

Sdl(BuildAction?)

Creates a new Sdl instance and initializes SDL

public Sdl(Sdl.BuildAction? buildAction = null)

Parameters

buildAction Sdl.BuildAction: A Sdl.BuildAction that is performed right before initializing SDL. Use the provided Sdl.Builder argument to perfom some preliminaries before SDL gets initialized.

Remarks

Creating a Sdl instance initializes SDL (while disposing it quits SDL).

There can be only a single instance of Sdl at a time! Trying to create another one, while one already exist, results in an InvalidOperationException.

The file I/O (for example: FileStream) and threading (SDL_CreateThread) subsystems are initialized by default. Message boxes (TryShowSimple(MessageBoxFlags, string, string, Window?) and TryShow(out int)) also attempt to work without initializing the video sub system, in hopes of being useful in showing an error dialog even before SDL initializes correclty. Logging (such as Info(string)) works without initialization, too.

You must specifically initialize other subsystems (either by using InitializeSubSystems(SubSystems) or by using InitializeSubSystems(SubSystems)), if you use them in your application.

Consider reporting some basic metadata about your application inside the buildAction, by using one of the *SetMetadata methods.

In contrast to most of the remaining API which uses the Try-method pattern, this constructor intentionally fails by throwing an exception. If you want to handle failures wrap the call to this constructor in a try-block, and check TryGet(out string?) for more information when catching a SdlException.

Exceptions

InvalidOperationException: There already exists an instance of Sdl
SdlException: Couldn't initialize SDL (check TryGet(out string?) for more information)

Properties

EventFilter

Gets or sets the global event filter

public EventFilter? EventFilter { get; set; }

Property Value

EventFilter: The global event filter

Remarks

The global event filter is used for filtering all events before they get pushed onto SDL's event queue.

Returning false from the filter will prevent the event from being pushed onto the event queue.

The filter is called for every event that gets pushed onto the event queue using TryPushEvent(in Event), but events added to the queue using TryAddEvents(ReadOnlySpan<Event>, out int) bypass the filter.

Disabled events will never be passed to the filter nor will they be added to the event queue.

You can use this property to chain multiple filters together by getting the current filter as a delegate, and then setting a new filter delegate that calls the previous filter as part of its implementation.

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

GlobalProperties

Gets the global group of SDL properties

public static Properties? GlobalProperties { get; }

Property Value

Properties: The global group of SDL properties, if those could get successfully retrieved; otherwise, null (check TryGet(out string?) for more information)

ProcessEnvironment

Gets the set of environment variables for the current process

public Environment? ProcessEnvironment { get; }

Property Value

Environment: The set of environment variables for the current process, if those could get successfully retrieved; otherwise, null (check TryGet(out string?) for more information)

Remarks

This set of environment variables is initialized at application start and is not affected by external calls to modify process environments (e.g. setenv() or unsetenv()) after that point.

To modify this set of environment variables use TrySetVariable(string, string, bool) or TryUnsetVariable(string). Changes made in this way will not persist outside of SDL, and especially not after SDL is shut down.

If you want for changes to persist in the C runtime environment after SDL is shut down, use TrySetProcessVariableUnsafe(string, string, bool) or TryUnsetProcessVariableUnsafe(string).

Exceptions

InvalidOperationException: Could not register the Environment with the given sdl instance

Revision

Gets the revision string of the currently loaded native SDL library

public static string? Revision { get; }

Property Value

string: The revision string of the currently loaded native SDL library

Remarks

The revision is arbitrary string (a hash value) uniquely identifying the exact revision of the SDL library in use, and is only useful in comparing against other revisions. It is NOT an incrementing number.

If SDL wasn't built from a git repository with the appropriate tools, this will return an empty string.

You shouldn't use this value for anything but logging it for debugging purposes. The string is not intended to be reliable in any way.

Version

Gets the version of the currently loaded native SDL library

public static Version Version { get; }

Property Value

Version: The version of the currently loaded native SDL library

Methods

Dispose()

Disposes the Sdl instance and quits SDL

public void Dispose()

Exceptions

InvalidOperationException: The Sdl instance is currently running. You cannot dispose an running Sdl.
AggregateException: One or more registered Sdl.IDisposeReceiver threw an exception during the call to their DisposeFromSdl(Sdl)

FilterEvents(EventFilter)

Filters events on the current event queue using the specified filter

public void FilterEvents(EventFilter filter)

Parameters

filter EventFilter: The event filter to apply

Remarks

Unlike the EventFilter property, this method only applies the filter to events that are already in the event queue once and potentially removes some of them. It doesn't apply permanently.

Exceptions

ArgumentNullException: filter is null

~Sdl()

protected ~Sdl()

Exceptions

AggregateException: One or more registered Sdl.IDisposeReceiver threw an exception during the call to their DisposeFromSdl(Sdl)

FlushEvents()

Clears all events from the current event queue

public void FlushEvents()

Remarks

This will unconditionally remove any events from the event queue. If you need to remove specific events, use FlushEvents(EventType) or FlushEvents(EventType, EventType) instead.

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

This method 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 calling this method.

If you have user defined events with custom data that needs to be handled (e.g. disposed or freed), you should use TryGetEvents(Span<Event>, EventType, EventType, out int) or TryPeekEvents(Span<Event>, EventType, EventType, out int) to retrieve and handle those events before flushing.

FlushEvents(EventType)

Clears events of the specified type from the current event queue

public void FlushEvents(EventType type)

Parameters

type EventType: The type of events to clear

Remarks

This will unconditionally remove any events from the event queue that match the specified type. If you need to remove a specific range of event types, use FlushEvents(EventType, EventType) instead.

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

This method 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 calling this method.

FlushEvents(EventType, EventType)

Clears events in the specified type range from the current event queue

public void FlushEvents(EventType minType, EventType maxType)

Parameters

minType EventType: The inclusive lower bound of the event type range to be cleared
maxType EventType: The inclusive upper bound of the event type range to be cleared

Remarks

This will unconditionally remove any events from the event queue in the range between minType and maxType, inclusive. If you need to remove a specific single event type only, use FlushEvents(EventType) instead.

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

This method 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 calling this method.

GetInitializedSubSystems()

Gets the currently initialized SubSystems

public SubSystems GetInitializedSubSystems()

Returns

SubSystems: A SubSystems representing all of the currently initialized SubSystems

Remarks

If you just want to check the initialization state SubSystems, you can use the get_IsInitialized(SubSystems) extension property.

GetInitializedSubSystems(SubSystems)

Gets a mask of currently initialized SubSystems

public SubSystems GetInitializedSubSystems(SubSystems subSystems)

Parameters

subSystems SubSystems: The SubSystems to check for

Returns

SubSystems: A SubSystems representing all of the currently initialized SubSystems, if subSystems is None; otherwise, a SubSystems representing the currently initialized SubSystems from the ones specified in the given subSystems

Remarks

If you just want to check the initialization state SubSystems, you can use the get_IsInitialized(SubSystems) extension property.

GetMetadata(string)

Get metadata about your app

public string? GetMetadata(string name)

Parameters

name string: The name of the metadata

Returns

string: The current value of the metadata, if it's set; otherwise, the default value for the metadata, or null, if it has no default value

Remarks

This returns metadata previously set using one of the *SetMetadata methods on the Sdl.Builder that was used to create the current Sdl instance.

See Sdl.Metadata for a overview over the available metadata properties and their meanings.

HasEvents()

Determines whether there are any events in the current event queue

public bool HasEvents()

Returns

bool: true, if there are events in the queue; otherwise, false

Remarks

If you need to check for specific event types, use HasEvents(EventType) or HasEvents(EventType, EventType) instead.

HasEvents(EventType)

Determines whether there are any events of the specified type in the current event queue

public bool HasEvents(EventType type)

Parameters

type EventType: The type of the event to check for

Returns

bool: true, if there are events of the specified type in the queue; otherwise, false

Remarks

If you need to check for a specific range of event types, use HasEvents(EventType, EventType) instead.

HasEvents(EventType, EventType)

Determines whether there are any events in the specified type range in the current event queue

public bool HasEvents(EventType minType, EventType maxType)

Parameters

minType EventType: The inclusive lower bound of the event type range to check
maxType EventType: The inclusive upper bound of the event type range to check

Returns

bool: true, if there are events in the specified type range; otherwise, false

Remarks

If you need to check for a specific single event type only, use HasEvents(EventType) instead.

InitializeSubSystems(SubSystems)

Initializes certain sub systems

public SubSystemInit InitializeSubSystems(SubSystems subSystems)

Parameters

subSystems SubSystems: Sub systems to initialize

Returns

SubSystemInit: A SubSystemInit that handles the lifetime of the sub systems

Remarks

SubSystems are reference counted through SubSystemInits. This method increases the reference count for the subSystems.

SubSystems can get shut down through Dispose() or Dispose().

In contrast to most of the remaining API which uses the Try-method pattern, this method intentionally fails by throwing an exception. If you want to handle failures wrap the call to this method in a try-block, and check TryGet(out string?) for more information when catching a SdlException.

Exceptions

SdlException: Couldn't initialize the specified sub systems (check TryGet(out string?) for more information)
InvalidOperationException: Could not register the SubSystemInit with the Sdl instance

PumpEvents()

Pumps the event loop, gathering events from the input devices

public void PumpEvents()

Remarks

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

This method 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 methods like TryPollEvent() and TryWaitForEvent(out Event) 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.

You can only call this method in the thread that set the video mode (most probably that's the main thread).

Run(AppBase, ReadOnlySpan<string>)

Executes the provided app and deinitializes the current instance afterwards

public int Run(AppBase app, ReadOnlySpan<string> args)

Parameters

app AppBase: The AppBase to execute
args ReadOnlySpan<string>: A collection of arguments to pass to OnInitialize(Sdl, string[])

Returns

int: A standard Unix main return value (a non-zero value, if there was a failure; otherwise, 0)

Remarks

It's important to notice, that this method will always dispose the current Sdl instance after it finishes executing the app! This is unavoidable!

You might be able to reuse the provided app after this method returns, but you can't reuse this instance of Sdl (as SDL will be shut down). If you want to use SDL after a call to this method, you must create a new Sdl instance and use that one instead.

Exceptions

ArgumentNullException: app is null
InvalidOperationException: The current Sdl instance is currently already executing an AppBase. You can only execute a single AppBase at a time.
ObjectDisposedException: The current Sdl instance is already disposed

Run<TArguments>(AppBase, in TArguments?)

Executes the provided app and deinitializes the current instance afterwards

public int Run<TArguments>(AppBase app, in TArguments? args) where TArguments : IReadOnlyCollection<string>, allows ref struct

Parameters

app AppBase: The AppBase to execute
args TArguments: A collection of arguments to pass to OnInitialize(Sdl, string[])

Returns

int: A standard Unix main return value (a non-zero value, if there was a failure; otherwise, 0)

Type Parameters

TArguments: The source type of collection of arguments to pass to OnInitialize(Sdl, string[])

Remarks

It's important to notice, that this method will always dispose the current Sdl instance after it finishes executing the app! This is unavoidable!

Exceptions

ArgumentNullException: app is null
InvalidOperationException: The current Sdl instance is currently already executing an AppBase. You can only execute a single AppBase at a time.
ObjectDisposedException: The current Sdl instance is already disposed

TryAddEvents(ReadOnlySpan<Event>, out int)

Tries to add new events to the current event queue

public bool TryAddEvents(ReadOnlySpan<Event> events, out int added)

Parameters

events ReadOnlySpan<Event>: The events to be added
added int: The number of events that were added to the event queue

Returns

bool: true, if the operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

Calling this method is effectively calling TryPeepEvents(events, EventAction.Add, out added).

TryCountEvents(EventType, EventType, out int)

Tries to count events in the specified type range in the current event queue

public bool TryCountEvents(EventType minType, EventType maxType, out int counted)

Parameters

minType EventType: The inclusive lower bound of the event type range to count
maxType EventType: The inclusive upper bound of the event type range to count
counted int: The number of events that match the specified minType and maxType range in the current event queue

Returns

bool: true, if the operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

Calling this method is effectively calling TryPeepEvents(int.MaxValue, EventAction.Peek, minType, maxType, out counted).

TryCountEvents(EventType, out int)

Tries to count events in the specified type range in the current event queue

public bool TryCountEvents(EventType type, out int counted)

Parameters

type EventType: The type of the event to count
counted int: The number of events that match the specified type in the current event queue

Returns

bool: true, if the operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

Calling this method is effectively calling TryPeepEvents(int.MaxValue, EventAction.Peek, type, out counted).

TryCountEvents(out int)

Tries to count any events in the current event queue

public bool TryCountEvents(out int counted)

Parameters

counted int: The number of events in the current event queue

Returns

bool: true, if the operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

Calling this method is effectively calling TryPeepEvents(int.MaxValue, EventAction.Peek, out counted).

TryDeregisterDisposable(IDisposeReceiver)

Tries to deregister a formerly registered Sdl.IDisposeReceiver from the Sdl instance, so that it won't longer receive a call to DisposeFromSdl(Sdl) from that Sdl instance

public bool TryDeregisterDisposable(Sdl.IDisposeReceiver disposeReceiver)

Parameters

disposeReceiver Sdl.IDisposeReceiver: The receiver to be deregistered

Returns

bool: true, if disposeReceiver was successfully deregistered from the Sdl instance; otherwise, false

TryGetEvents(Span<Event>, EventType, EventType, out int)

Tries to retrieve events in the specified type range from the current event queue and removes them

public bool TryGetEvents(Span<Event> events, EventType minType, EventType maxType, out int stored)

Parameters

events Span<Event>: The destination span to store the retrieved events
minType EventType: The inclusive lower bound of the event type range to retrieve
maxType EventType: The inclusive upper bound of the event type range to retrieve
stored int: The number of events that were retrieved and removed from the current event queue

Returns

bool: true, if the operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

Calling this method is effectively calling TryPeepEvents(events, EventAction.Get, minType, maxType, out stored).

TryGetEvents(Span<Event>, EventType, out int)

Tries to retrieve events of a specified type from the current event queue and removes them

public bool TryGetEvents(Span<Event> events, EventType type, out int stored)

Parameters

events Span<Event>: The destination span to store the retrieved events
type EventType: The type of events to retrieve
stored int: The number of events that were retrieved and removed from the current event queue

Returns

bool: true, if the operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

Calling this method is effectively calling TryPeepEvents(events, EventAction.Get, type, out stored).

TryGetEvents(Span<Event>, out int)

Tries to retrieve any events from the current event queue and removes them

public bool TryGetEvents(Span<Event> events, out int stored)

Parameters

events Span<Event>: The destination span to store the retrieved events
stored int: The number of events that were retrieved and removed from the current event queue

Returns

bool: true, if the operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

Calling this method is effectively calling TryPeepEvents(events, EventAction.Get, out stored).

TryPeekEvents(Span<Event>, EventType, EventType, out int)

Tries to retrieve events in the specified type range from the current event queue without removing them

public bool TryPeekEvents(Span<Event> events, EventType minType, EventType maxType, out int stored)

Parameters

events Span<Event>: The destination span to store the retrieved events
minType EventType: The inclusive lower bound of the event type range to retrieve
maxType EventType: The inclusive upper bound of the event type range to retrieve
stored int: The number of events that were retrieved from the current event queue

Returns

bool: true, if the operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

Calling this method is effectively calling TryPeepEvents(events, EventAction.Peek, minType, maxType, out stored).

TryPeekEvents(Span<Event>, EventType, out int)

Tries to retrieve events of a specified type from the current event queue without removing them

public bool TryPeekEvents(Span<Event> events, EventType type, out int stored)

Parameters

events Span<Event>: The destination span to store the retrieved events
type EventType: The event type to retrieve
stored int: The number of events that were retrieved from the current event queue

Returns

bool: true, if the operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

Calling this method is effectively calling TryPeepEvents(events, EventAction.Peek, type, out stored).

TryPeekEvents(Span<Event>, out int)

Tries to retrieve any events from the current event queue without removing them

public bool TryPeekEvents(Span<Event> events, out int stored)

Parameters

events Span<Event>: The destination span to store the retrieved events
stored int: The number of events that were retrieved from the current event queue

Returns

bool: true, if the operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

Calling this method is effectively calling TryPeepEvents(events, EventAction.Peek, out stored).

TryPeepEvents(int, EventAction, EventType, EventType, out int)

Tries to check the current event queue for events in specified type range and optionally removes them

public bool TryPeepEvents(int count, EventAction action, EventType minType, EventType maxType, out int counted)

Parameters

count int: The maximum number of events affected
action EventAction: The action to perform on the events
minType EventType: The inclusive lower bound of the event type range to check
maxType EventType: The inclusive upper bound of the event type range to check
counted int: The number of events that were affected

Returns

bool: true, if the operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

AddDoes nothing and will result in a failure (this method will return false)
Peek Up to count events from the front of the event queue that match the specified minType and maxType range are counted without removing them from the queue. The counted output parameter contains the number of events that were counted.
Get Up to count events from the front of the event queue that match the specified minType and maxType range are counted and removed from the queue. The counted output parameter contains the number of events that were counted and removed from the current event queue.

You may have to call PumpEvents() before calling this method. Otherwise, events may not be ready to be filtered when you call this method.

TryPeepEvents(int, EventAction, EventType, out int)

Tries to check the current event queue for events of a specified type and optionally removes them

public bool TryPeepEvents(int count, EventAction action, EventType type, out int counted)

Parameters

count int: The maximum number of events affected
action EventAction: The action to perform on the events
type EventType: The type of the event to check for
counted int: The number of events that were affected

Returns

bool: true, if the operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

AddDoes nothing and will result in a failure (this method will return false)
Peek Up to count events from the front of the event queue that match the specified type are counted without removing them from the queue. The counted output parameter contains the number of events that were counted.
Get Up to count events from the front of the event queue that match the specified type are counted and removed from the queue. The counted output parameter contains the number of events that were counted and removed from the current event queue.

You may have to call PumpEvents() before calling this method. Otherwise, events may not be ready to be filtered when you call this method.

TryPeepEvents(int, EventAction, out int)

Tries to check the current event queue for any events and optionally removes them

public bool TryPeepEvents(int count, EventAction action, out int counted)

Parameters

count int: The maximum number of events affected
action EventAction: The action to perform on the events
counted int: The number of events that were affected

Returns

bool: true, if the operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

AddDoes nothing and will result in a failure (this method will return false)
Peek Up to count events from the front of the event queue are counted without removing them from the queue. The counted output parameter contains the number of events that were counted.
Get Up to count events from the front of the event queue are counted and removed from the queue. The counted output parameter contains the number of events that were counted and removed from the current event queue.

You may have to call PumpEvents() before calling this method. Otherwise, events may not be ready to be filtered when you call this method.

TryPeepEvents(Span<Event>, EventAction, EventType, EventType, out int)

Tries to check the current event queue for events in specified type range and retrieves them, or tries to add new events to the the current event queue

public bool TryPeepEvents(Span<Event> events, EventAction action, EventType minType, EventType maxType, out int stored)

Parameters

events Span<Event>: A destination span to store the retrieved events or a source span of new events to add
action EventAction: The action to perform on the events
minType EventType: The inclusive lower bound of the event type range to check
maxType EventType: The inclusive upper bound of the event type range to check
stored int: The number of events stored in the destination span or the number of events added to the queue

Returns

bool: true, if the operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method tries to perform different actions on the event queue depending on the specified action:

Add All events from the source events span are added to the event queue. The minType and maxType parameters are ignored in this case. The stored output parameter contains the number of events that were added to the queue.
Peek Up to events.Length events from the front of the event queue that match the specified minType and maxType range are copied into the span without removing them from the queue. The stored output parameter contains the number of events that were copied into the span.
Get Up to events.Length events from the front of the event queue that match the specified minType and maxType range are copied into the span and removed from the queue. The stored output parameter contains the number of events that were copied into the span and removed from the current event queue.

You may have to call PumpEvents() before calling this method. Otherwise, events may not be ready to be filtered when you call this method.

TryPeepEvents(Span<Event>, EventAction, EventType, out int)

Tries to check the current event queue for events of a specified type and retrieves them, or tries to add new events to the the current event queue

public bool TryPeepEvents(Span<Event> events, EventAction action, EventType type, out int stored)

Parameters

events Span<Event>: A destination span to store the retrieved events or a source span of new events to add
action EventAction: The action to perform on the events
type EventType: The type of the event to check for
stored int: The number of events stored in the destination span or the number of events added to the queue

Returns

bool: true, if the operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method tries to perform different actions on the event queue depending on the specified action:

Add All events from the source events span are added to the event queue. The type parameter is ignored in this case. The stored output parameter contains the number of events that were added to the queue.
Peek Up to events.Length events from the front of the event queue that match the specified type are copied into the span without removing them from the queue. The stored output parameter contains the number of events that were copied into the span.
Get Up to events.Length events from the front of the event queue that match the specified type are copied into the span and removed from the queue. The stored output parameter contains the number of events that were copied into the span and removed from the current event queue.

You may have to call PumpEvents() before calling this method. Otherwise, events may not be ready to be filtered when you call this method.

TryPeepEvents(Span<Event>, EventAction, out int)

Tries to check the current event queue for any events and retrieves them, or tries to add new events to the the current event queue

public bool TryPeepEvents(Span<Event> events, EventAction action, out int stored)

Parameters

events Span<Event>: A destination span to store the retrieved events or a source span of new events to add
action EventAction: The action to perform on the events
stored int: The number of events stored in the destination span or the number of events added to the queue

Returns

bool: true, if the operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method tries to perform different actions on the event queue depending on the specified action:

Add All events from the source events span are added to the event queue. The stored output parameter contains the number of events that were added to the queue.
Peek Up to events.Length events from the front of the event queue are copied into the span without removing them from the queue. The stored output parameter contains the number of events that were copied into the span.
Get Up to events.Length events from the front of the event queue are copied into the span and removed from the queue. The stored output parameter contains the number of events that were copied into the span and removed from the current event queue.

You may have to call PumpEvents() before calling this method. Otherwise, events may not be ready to be filtered when you call this method.

TryPollEvent()

Tries to poll for pending events from the current event queue

public bool TryPollEvent()

Returns

bool: true, if there is a pending event in the event queue; otherwise, false

Remarks

If there is a pending event in the current event queue, it will not be removed from the event queue, and this method will simply return true. In the case this method returned false, there was no pending event in the current event queue. The event queue remains unchanged in any case. Therefore you can use this method to check if there are pending events in the current event queue.

As this method may implicitly call PumpEvents(), you can only call this method in the thread that set the video mode.

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.

TryPollEvent(out Event)

Tries to poll for pending events from the current event queue

public bool TryPollEvent(out Event @event)

Parameters

event Event: The next pending event from the event queue, if this method returns true

Returns

bool: true, if there was a pending event in the event queue and it was copied into event; otherwise, false

Remarks

If there is a pending event in the current event queue, it will be copied into the event argument and removed from the event queue, and then this method will return true. In the case this method returned false, there was no pending event in the current event queue and the event queue remained unchanged.

As this method may implicitly call PumpEvents(), you can only call this method in the thread that set the video mode.

TryPollEvent(out Event) 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 current event queue once every frame, usually as a first step before updating the game's state.

TryPushEvent(in Event)

Tries to add a new event to the current event queue

public bool TryPushEvent(in Event @event)

Parameters

event Event: The event to add to the queue

Returns

bool: true, if the event was successfully added to the queue; otherwise, false (check TryGet(out string?) for more information)

Remarks

Events that are supposed to be added via this method are passed to the EventFilter and are susceptible to being disabled. If the event is filtered out, this method will return false (use TryGet(out string?) to check if the event was filtered out or if there was another kind of failure). If you want to bypass the filter you can use TryAddEvents(ReadOnlySpan<Event>, out int) instead.

Another common reason for this method failing is the event queue being full.

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. The event will be copied into the queue, and afterwards user can forget about it until it's (polled) by themselves or somewhere else.

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

For pushing user defined custom events, please use TryRegister(out EventType) or TryRegister(Span<EventType>) to get event types that does not conflict with other code that also wants its own custom event types.

TryRegisterDisposable(IDisposeReceiver)

Tries to register an Sdl.IDisposeReceiver with the Sdl instance, so it will receive a call to DisposeFromSdl(Sdl) when that Sdl instance gets disposed

public bool TryRegisterDisposable(Sdl.IDisposeReceiver disposeReceiver)

Parameters

disposeReceiver Sdl.IDisposeReceiver: The receiver to be registered

Returns

bool: true, if disposeReceiver was successfully registered with the Sdl instance; otherwise, false

Remarks

This method also returns true, if the disposeReceiver was already registered with the Sdl instance before

TryRemoveEvents(int, EventType, EventType, out int)

Tries to remove events in the specified type range from the current event queue

public bool TryRemoveEvents(int count, EventType minType, EventType maxType, out int removed)

Parameters

count int: The maximum number of events to remove
minType EventType: The inclusive lower bound of the event type range to remove
maxType EventType: The inclusive upper bound of the event type range to remove
removed int: The number of events that were removed from the current event queue

Returns

bool: true, if the operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

Calling this method is effectively calling TryPeepEvents(count, EventAction.Get, minType, maxType, out removed).

TryRemoveEvents(int, EventType, out int)

Tries to remove events of a specified type from the current event queue

public bool TryRemoveEvents(int count, EventType type, out int removed)

Parameters

count int: The maximum number of events to remove
type EventType: The type of events to remove
removed int: The number of events that were removed from the current event queue

Returns

bool: true, if the operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

Calling this method is effectively calling TryPeepEvents(count, EventAction.Get, type, out removed).

TryRemoveEvents(int, out int)

Tries to remove any events from the current event queue

public bool TryRemoveEvents(int count, out int removed)

Parameters

count int: The maximum number of events to remove
removed int: The number of events that were removed from the current event queue

Returns

bool: true, if the operation was successful; otherwise, false (check TryGet(out string?) for more information)

Remarks

Calling this method is effectively calling TryPeepEvents(count, EventAction.Get, out removed).

TryWaitForEvent()

Tries to wait for pending events from the current event queue indefinitely

public bool TryWaitForEvent()

Returns

bool: true, if there was a pending event received in the event queue; otherwise, false (check TryGet(out string?) for more information)

Remarks

If there is a pending event recieved in the current event queue, it will not be removed from the event queue, and this method will simply return true. In the case this method returned false, there was an error while waiting and you should check TryGet(out string?) for more information. The event queue remains unchanged in any case. Therefore you can use this method to block and wait until there are pending events recieved in the current event queue.

As this method may implicitly call PumpEvents(), you can only call this method in the thread that set the video mode.

TryWaitForEvent(out Event)

Tries to wait for pending events from the current event queue indefinitely

public bool TryWaitForEvent(out Event @event)

Parameters

event Event: The next pending event from the event queue

Returns

bool: true, if there was a pending event received in the event queue and it was copied into event; otherwise, false (check TryGet(out string?) for more information)

Remarks

If there is a pending event recieved in the current event queue, it will be copied into the event argument and removed from the event queue, and then this method will return true. In the case this method returned false, there was an error while waiting and you should check TryGet(out string?) for more information.

As this method may implicitly call PumpEvents(), you can only call this method in the thread that set the video mode.

TryWaitForEvent(out Event, int)

Tries to wait until a specified timeout for pending events from the current event queue

public bool TryWaitForEvent(out Event @event, int timeoutMs)

Parameters

event Event: The next pending event from the event queue, if this method returns true
timeoutMs int: The timeout in milliseconds

Returns

bool: true, if there was a pending event recieved in the event queue before the timeout and it was copied into event; otherwise, false

Remarks

If there is a pending event recieved in the current event queue before the timeout, it will be copied into the event argument and removed from the event queue, and then this method will return true. In the case this method returned false, there was no pending event recieved in the current event queue until the specified timeout.

As this method may implicitly call PumpEvents(), you can only call this method in the thread that set the video mode.

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

TryWaitForEvent(out Event, TimeSpan)

Tries to wait until a specified timeout for pending events from the current event queue

public bool TryWaitForEvent(out Event @event, TimeSpan timeout)

Parameters

event Event: The next pending event from the event queue, if this method returns true
timeout TimeSpan: The timeout

Returns

bool: true, if there was a pending event recieved in the event queue before the timeout and it was copied into event; otherwise, false

Remarks

As this method may implicitly call PumpEvents(), you can only call this method in the thread that set the video mode.

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

TryWaitForEvent(int)

Tries to wait until a specified timeout for pending events from the current event queue

public bool TryWaitForEvent(int timeoutMs)

Parameters

timeoutMs int: The timeout in milliseconds

Returns

bool: true, if there was a pending event recieved in the event queue before the timeout; otherwise, false

Remarks

If there is a pending event recieved in the current event queue before the timeout, it will not be removed from the event queue, and this method will simply return true. In the case this method returned false, there was no pending event recieved in the current event queue until the specified timeout. The event queue remains unchanged in any case. Therefore you can use this method to block and wait until there are pending events recieved in the current event queue.

As this method may implicitly call PumpEvents(), you can only call this method in the thread that set the video mode.

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

TryWaitForEvent(TimeSpan)

Tries to wait until a specified timeout for pending events from the current event queue

public bool TryWaitForEvent(TimeSpan timeout)

Parameters

timeout TimeSpan: The timeout

Returns

bool: true, if there was a pending event recieved in the event queue before the timeout; otherwise, false

Remarks

As this method may implicitly call PumpEvents(), you can only call this method in the thread that set the video mode.

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

Events

DidEnterBackground

Occurs when the application has entered the background

public event EventHandler<Sdl, Event>? DidEnterBackground

Event Type

EventHandler<Sdl, Event>

Remarks

The application may not get any CPU for some time.

Raised on iOS in applicationDidEnterBackground(). Raised on Android in onPause().

DidEnterForeground

Occurs when the application has entered the foreground

public event EventHandler<Sdl, Event>? DidEnterForeground

Event Type

EventHandler<Sdl, Event>

Remarks

The application is now interactive.

Raised on iOS in applicationDidBecomeActive(). Raised on Android in onResume().

EventWatch

Occurs when an event is pushed onto the event queue

public event EventWatch? EventWatch

Event Type

EventWatch

Remarks

The event handler to this event is called for every event that gets pushed onto SDL's event queue using TryPushEvent(in Event), but not for disabled events, nor for events that were filtered out by the EventFilter, nor for events added to the queue using TryAddEvents(ReadOnlySpan<Event>, out int).

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

LocaleChanged

Occurs when the user's locale preferences have changed

public event EventHandler<Sdl, Event>? LocaleChanged

Event Type

EventHandler<Sdl, Event>

LowMemory

Occurs when the application is running low on memory

public event EventHandler<Sdl, Event>? LowMemory

Event Type

EventHandler<Sdl, Event>

Remarks

Free some memory if possible.

Raised on iOS in applicationDidReceiveMemoryWarning(). Raised on Android in onTrimMemory().

Quit

Occurs when the application "requests" to quit

public event EventHandler<Sdl, QuitEvent>? Quit

Event Type

EventHandler<Sdl, QuitEvent>

SystemThemeChanged

Occurs when the system theme has changed

public event EventHandler<Sdl, Event>? SystemThemeChanged

Event Type

EventHandler<Sdl, Event>

Terminating

Occurs when the application is being terminated by the OS

public event EventHandler<Sdl, Event>? Terminating

Event Type

EventHandler<Sdl, Event>

Remarks

Raised on iOS in applicationWillTerminate(). Raised on Android in onDestroy().

WillEnterBackground

Occurs when the application is about to enter the background

public event EventHandler<Sdl, Event>? WillEnterBackground

Event Type

EventHandler<Sdl, Event>

Remarks

Raised on iOS in applicationWillResignActive(). Raised on Android in onPause().

WillEnterForeground

Occurs when the application is about to enter the foreground

public event EventHandler<Sdl, Event>? WillEnterForeground

Event Type

EventHandler<Sdl, Event>

Remarks

Raised on iOS in applicationWillEnterForeground(). Raised on Android in onResume().

Table of Contents

Class Sdl

Remarks

Constructors

Sdl(BuildAction?)

Parameters

Remarks

Exceptions

Properties

EventFilter

Property Value

Remarks

GlobalProperties

Property Value

ProcessEnvironment

Property Value

Remarks

Exceptions

Revision

Property Value

Remarks

Version

Property Value

Methods

Dispose()

Exceptions

FilterEvents(EventFilter)

Parameters

Remarks

Exceptions

~Sdl()

Exceptions

FlushEvents()

Remarks

FlushEvents(EventType)

Parameters

Remarks

FlushEvents(EventType, EventType)

Parameters

Remarks

GetInitializedSubSystems()

Returns

Remarks

GetInitializedSubSystems(SubSystems)

Parameters

Returns

Remarks

GetMetadata(string)

Parameters

Returns

Remarks

HasEvents()

Returns

Remarks

HasEvents(EventType)

Parameters

Returns

Remarks

HasEvents(EventType, EventType)

Parameters

Returns

Remarks

InitializeSubSystems(SubSystems)

Parameters

Returns

Remarks

Exceptions

PumpEvents()

Remarks

Run(AppBase, ReadOnlySpan<string>)

Parameters

Returns

Remarks

Exceptions

Run<TArguments>(AppBase, in TArguments?)

Parameters

Returns

Type Parameters

Remarks

Exceptions