Class Platform

Namespace

Sdl3Sharp.Utilities

Assembly

Sdl3Sharp.dll

Provides methods and properties to identify the current executing platform as well as to interact with it on a lower level in a more platform-specific way.

public static class Platform

Inheritance

object

Platform

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Most application can make do without using these methods, but they can be useful for integrating with other parts of a specific system, adding platform-specific polish to an applicaiton, or solving problems that only affect one target.

Properties

IsChromebook

Gets a value indicating whether the current platform is a Chromebook

public static bool IsChromebook { get; }

Property Value

bool

A value indicating whether the current platform is a Chromebook

Remarks

Note: This property is only available on Android and will throw a PlatformNotSupportedException on all other platforms!

Exceptions

PlatformNotSupportedException

The executing platform is not Android

IsDeX

Gets a value indicating whether the current platform is running Samsung's DeX mode

public static bool IsDeX { get; }

Property Value

bool

A value indicating whether the current platform is running Samsung's DeX mode

Remarks

Note: This property is only available on Android and will throw a PlatformNotSupportedException on all other platforms!

Exceptions

PlatformNotSupportedException

The executing platform is not Android

IsTV

Gets a value indicating whether the current platform is a (smart) TV

public static bool IsTV { get; }

Property Value

bool

A value indicating whether the current platform is a (smart) TV

Remarks

If SDL can't determine whether the current platform is a (smart) TV, the value of this property will be false.

IsTablet

Gets a value indicating whether the current platform is a tablet

public static bool IsTablet { get; }

Property Value

bool

A value indicating whether the current platform is a tablet

Remarks

If SDL can't determine whether the current platform is a tablet, the value of this property will be false.

Name

Gets the name of the platform

public static string Name { get; }

Property Value

string

The name of the platform, if it's available; otherwise a string beginning with "Unknown"

Remarks

If the platform is not available, the value of this property is a string beginning with "Unknown".

The following is an incomplete list of supported platform names:

• "Windows"
• "macOS"
• "Linux"
• "iOS"
• "Android"

Sandbox

Gets the Sandbox environment of the application

public static Sandbox Sandbox { get; }

Property Value

Sandbox

The Sandbox environment of the application, including None, if the application isn't execute in a Sandbox environment.

Methods

GetAndroidExternalStorageState()

Gets the current state of external storage for the Android application

public static AndroidExternalStorageState GetAndroidExternalStorageState()

Returns

AndroidExternalStorageState

The current state of external storage for the Android application, including Unavailable, if external storage is currently unavailable

Remarks

Note: This method is only available on Android and will throw a PlatformNotSupportedException on all other platforms!

Exceptions

PlatformNotSupportedException

The executing platform is not Android

GetAndroidSDKVersion()

Gets the Android API level of the current device

public static int GetAndroidSDKVersion()

Returns

int

The Android API level of the current device

Remarks

This method returns the Android API level of the current device, not the Android version. The following is an incomplete mapping from Android API levels to Android versions:

• API level 35Android 15 (VANILLA_ICE_CREAM)
• API level 34Android 14 (UPSIDE_DOWN_CAKE)
• API level 33Android 13 (TIRAMISU)
• API level 32Android 12L (S_V2)
• API level 31Android 12 (S)
• API level 30Android 11 (R)
• API level 29Android 10 (Q)
• API level 28Android 9 (P)
• API level 27Android 8.1 (O_MR1)
• API level 26Android 8.0 (O)
• API level 25Android 7.1 (N_MR1)
• API level 24Android 7.0 (N)
• API level 23Android 6.0 (M)
• API level 22Android 5.1 (LOLLIPOP_MR1)
• API level 21Android 5.0 (LOLLIPOP, L)
• API level 20Android 4.4W (KITKAT_WATCH)
• API level 19Android 4.4 (KITKAT)
• API level 18Android 4.3 (JELLY_BEAN_MR2)
• API level 17Android 4.2 (JELLY_BEAN_MR1)
• API level 16Android 4.1 (JELLY_BEAN)
• API level 15Android 4.0.3 (ICE_CREAM_SANDWICH_MR1)
• API level 14Android 4.0 (ICE_CREAM_SANDWICH)
• API level 13Android 3.2 (HONEYCOMB_MR2)
• API level 12Android 3.1 (HONEYCOMB_MR1)
• API level 11Android 3.0 (HONEYCOMB)
• API level 10Android 2.3.3 (GINGERBREAD_MR1)

Note: This method is only available on Android and will throw a PlatformNotSupportedException on all other platforms!

Exceptions

PlatformNotSupportedException

The executing platform is not Android

OnApplicationDidChangeStatusBarOrientation()

Report onApplicationDidChangeStatusBarOrientation on Apple iOS when using external event handling

public static void OnApplicationDidChangeStatusBarOrientation()

Remarks

This method allows apps that have their own event handling to hook into SDL to generate SDL events. It maps directly to the iOS-specific event onApplicationDidChangeStatusBarOrientation.

Most apps do not need to use this method directly; SDL's internal event code will handle all this for windows created by SDL_CreateWindow!

Exceptions

PlatformNotSupportedException

OnApplicationDidEnterBackground()

Report onApplicationDidEnterBackground on Apple iOS when using external event handling

public static void OnApplicationDidEnterBackground()

Remarks

This method allows apps that have their own event handling to hook into SDL to generate SDL events. It maps directly to the iOS-specific event onApplicationDidEnterBackground.

Since this method doesn't do anything iOS-specific internally, it is available on all platforms, in case it might be useful for some specific paradigm.

Most apps do not need to use this method directly; SDL's internal event code will handle all this for windows created by SDL_CreateWindow!

OnApplicationDidEnterForeground()

Report onApplicationDidBecomeActive on Apple iOS when using external event handling

public static void OnApplicationDidEnterForeground()

Remarks

This method allows apps that have their own event handling to hook into SDL to generate SDL events. It maps directly to the iOS-specific event onApplicationDidBecomeActive.

Since this method doesn't do anything iOS-specific internally, it is available on all platforms, in case it might be useful for some specific paradigm.

Most apps do not need to use this method directly; SDL's internal event code will handle all this for windows created by SDL_CreateWindow!

OnApplicationDidReceiveMemoryWarning()

Report onApplicationDidReceiveMemoryWarning on Apple iOS when using external event handling

public static void OnApplicationDidReceiveMemoryWarning()

Remarks

This method allows apps that have their own event handling to hook into SDL to generate SDL events. It maps directly to the iOS-specific event onApplicationDidReceiveMemoryWarning.

Since this method doesn't do anything iOS-specific internally, it is available on all platforms, in case it might be useful for some specific paradigm.

Most apps do not need to use this method directly; SDL's internal event code will handle all this for windows created by SDL_CreateWindow!

OnApplicationWillEnterBackground()

Report onApplicationWillResignActive on Apple iOS when using external event handling

public static void OnApplicationWillEnterBackground()

Remarks

This method allows apps that have their own event handling to hook into SDL to generate SDL events. It maps directly to the iOS-specific event onApplicationWillResignActive.

Since this method doesn't do anything iOS-specific internally, it is available on all platforms, in case it might be useful for some specific paradigm.

Most apps do not need to use this method directly; SDL's internal event code will handle all this for windows created by SDL_CreateWindow!

OnApplicationWillEnterForeground()

Report onApplicationWillEnterForeground on Apple iOS when using external event handling

public static void OnApplicationWillEnterForeground()

Remarks

This method allows apps that have their own event handling to hook into SDL to generate SDL events. It maps directly to the iOS-specific event onApplicationWillEnterForeground.

Since this method doesn't do anything iOS-specific internally, it is available on all platforms, in case it might be useful for some specific paradigm.

Most apps do not need to use this method directly; SDL's internal event code will handle all this for windows created by SDL_CreateWindow!

OnApplicationWillTerminate()

Report onApplicationWillTerminate on Apple iOS when using external event handling

public static void OnApplicationWillTerminate()

Remarks

This method allows apps that have their own event handling to hook into SDL to generate SDL events. It maps directly to the iOS-specific event onApplicationWillTerminate.

Since this method doesn't do anything iOS-specific internally, it is available on all platforms, in case it might be useful for some specific paradigm.

Most apps do not need to use this method directly; SDL's internal event code will handle all this for windows created by SDL_CreateWindow!

SendAndroidBackButton()

Triggers the Android system back button behavior

public static void SendAndroidBackButton()

Remarks

Note: This method is only available on Android and will throw a PlatformNotSupportedException on all other platforms!

Exceptions

PlatformNotSupportedException

The executing platform is not Android

SetIOSEventPump(bool)

Enables or disables the SDL event pump on Apple iOS

public static void SetIOSEventPump(bool enabled)

Parameters

enabled bool

true to enable the SDL event pump; otherwise, false to disable it

Remarks

Note: This method is only available on Apple iOS and will throw a PlatformNotSupportedException on all other platforms!

Exceptions

PlatformNotSupportedException

The executing platform is not Apple iOS

SetWindowsMessageHook(WindowsMessageHook)

Sets a callback for every Windows message

public static void SetWindowsMessageHook(WindowsMessageHook callback)

Parameters

callback WindowsMessageHook

The WindowsMessageHook to invoke for every Windows message

Remarks

The callback may modify the message, and should return true if the message should continue to be processed, or false to prevent further processing.

The callback is invoked before TranslateMessage.

Note: This method is only available on Windows and will throw a PlatformNotSupportedException on all other platforms!

Exceptions

PlatformNotSupportedException

The executing platform is not Windows

ArgumentNullException

callback is null

SetX11EventHook(X11EventHook)

Sets a callback for every X11 event

public static void SetX11EventHook(X11EventHook callback)

Parameters

callback X11EventHook

The X11EventHook to invoke for every X11 event

Remarks

The callback may modify the event, and should return true if the event should continue to be processed, or false to prevent further processing.

Exceptions

ArgumentNullException

callback is null

TryGetAndroidActivity(out nint)

Tries to retrieve the Java instance of the Android activity class

public static bool TryGetAndroidActivity(out nint activity)

Parameters

activity nint

The jobject representing the instance of the Activity class of the Android application, when this method returns true; otherwise, default(nint)

Returns

bool

true if the Java instance of the Android activity class could be succesfully retrieved; otherwise, false (check TryGet(out string?) for more information)

Remarks

The activity parameter is declared as nint here, but it's actually of type jobject (a pointer type) defined like in jni.h.

The resulting jobject activity is a local reference and must be released by the caller. See the PushLocalFrame and PopLocalFrame or DeleteLocalRef functions of the Java native interface: https://docs.oracle.com/javase/1.5.0/docs/guide/jni/spec/functions.html.

Note: This method is only available on Android and will throw a PlatformNotSupportedException on all other platforms!

Exceptions

PlatformNotSupportedException

The executing platform is not Android

TryGetAndroidCachePath(out string?)

Tries to get the path used for caching data for the Android application

public static bool TryGetAndroidCachePath(out string? cachePath)

Parameters

cachePath string

The path used for caches for the Android application, when this method returns true; otherwise, null

Returns

bool

true if the path used for caching data for the Android application could be succesfully retrieved; otherwise, false (check TryGet(out string?) for more information)

Remarks

The resulting path is unique to your application, but is public and can be written to by other applications. Its typically "/data/data/your.app.package/cache/".

This effectively wraps android.content.Context.getCacheDir.

Note: This method is only available on Android and will throw a PlatformNotSupportedException on all other platforms!

Exceptions

PlatformNotSupportedException

The executing platform is not Android

TryGetAndroidExternalStoragePath(out string?)

Tries to get the path used for external storage for the Android application

public static bool TryGetAndroidExternalStoragePath(out string? externalStoragePath)

Parameters

externalStoragePath string

The path used for external storage for the Android application, when this method returns true; otherwise, null

Returns

bool

true if the path used for external storage for the Android application could be succesfully retrieved; otherwise, false (check TryGet(out string?) for more information)

Remarks

The resulting path is unique to your application, but is public and can be written to by other applications. It's typically "/storage/sdcard0/Android/data/your.app.package/files".

This effectively wraps android.content.Context.getExternalFilesDir.

Note: This method is only available on Android and will throw a PlatformNotSupportedException on all other platforms!

Exceptions

PlatformNotSupportedException

The executing platform is not Android

TryGetAndroidInternalStoragePath(out string?)

Tries to get the path used for internal storage for the Android application

public static bool TryGetAndroidInternalStoragePath(out string? internalStoragePath)

Parameters

internalStoragePath string

The path used for internal storage for the Android application, when this method returns true; otherwise, null

Returns

bool

true if the path used for internal storage for the Android application could be succesfully retrieved; otherwise, false (check TryGet(out string?) for more information)

Remarks

The resulting path is unique to your application, but is public and cannot be written to by other applications. It's typically "/data/data/your.app.package/files".

This effectively wraps android.content.Context.getFilesDir.

Note: This method is only available on Android and will throw a PlatformNotSupportedException on all other platforms!

Exceptions

PlatformNotSupportedException

The executing platform is not Android

TryGetAndroidJniEnv(out nint)

Tries to get the Android Java Native Interface Environment of the current thread

public static bool TryGetAndroidJniEnv(out nint jniEnv)

Parameters

jniEnv nint

The Java native interface object (JNIEnv) to which the current thread is attached, when this method returns true; otherwise, default(nint)

Returns

bool

true if the Android Java Native Interface Environment could be succesfully retrieved; otherwise, false (check TryGet(out string?) for more information)

Remarks

The jniEnv parameter is declared as nint here, but it's actually of type JNIEnv (a pointer type) defined like in jni.h.

The resulting JNIEnv jniEnv is needed to access the Java virtual machine and many Android APIs from native code.

Note: This method is only available on Android and will throw a PlatformNotSupportedException on all other platforms!

Exceptions

PlatformNotSupportedException

The executing platform is not Android

TryGetDXGIOutputInfo(uint, out int, out int)

Tries to get the DXGI adapter index and output index for a specified display

public static bool TryGetDXGIOutputInfo(uint displayId, out int adapterIndex, out int outputIndex)

Parameters

displayId uint

The display id of the display that the resulting DXGI adapter index and output index should match

adapterIndex int

The DXGI adapter index that matches the given displayId when this method returns true; otherwise, unspecified

outputIndex int

The DXGI output index that matches the given displayId when this method returns true; otherwise, unspecified

Returns

bool

true if the DXGI apapter index and output index matching the given displayId could be succesfully retrieved; otherwise, false (check TryGet(out string?) for more information)

Remarks

The resulting DXGI adapter index (adapterIndex) and output index (outputIndex) can be passed to IDXGIFactory::EnumAdapters and IDXGIAdapter::EnumOutputs respectively to get the objects required to create a DX10 or DX11 device and swap chain.

Note: This method is only available on Windows and will throw a PlatformNotSupportedException on all other platforms!

Exceptions

PlatformNotSupportedException

The executing platform is not Windows

TryGetDirect3D9AdapterIndex(uint, out int)

Tries to get the D3D9 adapter index that matches a specified display

public static bool TryGetDirect3D9AdapterIndex(uint displayId, out int adapterIndex)

Parameters

displayId uint

The display id of the display that the resulting D3D9 adapter index should match

adapterIndex int

The D3D9 adapter index that matches the given displayId when this method returns true; otherwise, -1

Returns

bool

true if the D3D9 apapter index matching the given displayId could be succesfully retrieved; otherwise, false (check TryGet(out string?) for more information)

Remarks

The resulting adapter index (adapterIndex) can be passed to IDirect3D9::CreateDevice and controls on which monitor a full screen application will appear.

Note: This method is only available on Windows and will throw a PlatformNotSupportedException on all other platforms!

Exceptions

PlatformNotSupportedException

The executing platform is not Windows

TryGetGDKDefaultUser(out nint)

Tries to get a handle to the default user for GDK

public static bool TryGetGDKDefaultUser(out nint userHandle)

Parameters

userHandle nint

The default user handle for GDK when this method returns true; otherwise, unspecified

Returns

bool

true if the handle to the default user for GDK could be succesfully retrieved; otherwise, false (check TryGet(out string?) for more information)

Remarks

The userHandle parameter is declared as nint here, but it's actually of type XUserHandle (a handle type).

This is effectively a synchronous version of XUserAddAsync, which always prefers the default user and allows a sign-in UI.

Note: This method is only available on platforms using Microsoft's Game Development Kit (GDK)! Since there's currently no way to use GDK and Sdl3Sharp together, this method will always throw a PlatformNotSupportedException!

Exceptions

PlatformNotSupportedException

The executing platform is not using Microsoft's Game Development Kit (GDK)

TryGetGDKTaskQueue(out nint)

Tries to get a handle to the global async task queue handle for GDK, initializing it if needed

public static bool TryGetGDKTaskQueue(out nint taskQueueHandle)

Parameters

taskQueueHandle nint

The global async task queue handle for GDK when this method returns true; otherwise, unspecified

Returns

bool

true if the handle to the global async task queue for GDK could be succesfully retrieved; otherwise, false (check TryGet(out string?) for more information)

Remarks

The taskQueueHandle parameter is declared as nint here, but it's actually of type XTaskQueueHandle (a handle type).

Once you are done with the task queue, you should call XTaskQueueCloseHandle to reduce the reference count to avoid a resource leak.

Note: This method is only available on platforms using Microsoft's Game Development Kit (GDK)! Since there's currently no way to use GDK and Sdl3Sharp together, this method will always throw a PlatformNotSupportedException!

Exceptions

PlatformNotSupportedException

The executing platform is not using Microsoft's Game Development Kit (GDK)

TryRequestAndroidPermission(string, AndroidRequestPermissionCallback)

Tries to request an Android permission at runtime, asynchronously

public static bool TryRequestAndroidPermission(string permission, AndroidRequestPermissionCallback callback)

Parameters

permission string

The permission to request. Should be one of those values: https://developer.android.com/reference/android/Manifest.permission.

callback AndroidRequestPermissionCallback

A AndroidRequestPermissionCallback that will be invoked when the request has a response

Returns

bool

true if the request was succesfully submitted; otherwise, false (check TryGet(out string?) for more information)

Remarks

Note: The returned value of a call to this method just indicates if the request was succesfully submitted, not if the permission was granted. Only the given callback will receive a response the request.

You do not need to call this for built-in functionality of SDL. When using standard SDL APIs (e.g. recording from a microphone or reading images from a camera), SDL will manage permission requests for you.

This method never blocks. Instead, the given callback will be invoked when a decision has been made. That callback may get invoked on a different thread, and possibly much later, as it might wait on a user to respond to a system dialog. If permission has already been granted for a specific entitlement, the callback will still be invoked, probably on the current thread and before this method returns.

Note: This method is only available on Android and will throw a PlatformNotSupportedException on all other platforms!

Exceptions

PlatformNotSupportedException

The executing platform is not Android

ArgumentNullException

callback is null

TrySendAndroidMessage(uint, int)

Tries to send a user command to the Android SDLActivity

public static bool TrySendAndroidMessage(uint command, int parameter)

Parameters

command uint

The user command. Must be greater or equal to 0x8000.

parameter int

The user parameter

Returns

bool

true if the user command was succesfully sent; otherwise, false (check TryGet(out string?) for more information)

Remarks

You would override boolean onUnhandledMessage(Message msg) on the Android side to handle such a message.

Note: This method is only available on Android and will throw a PlatformNotSupportedException on all other platforms!

Exceptions

PlatformNotSupportedException

The executing platform is not Android

TrySetIOSAnimationCallback(Window, int, IOSAnimationCallback)

Tries to set the animation callback on Apple iOS

public static bool TrySetIOSAnimationCallback(Window window, int interval, IOSAnimationCallback callback)

Parameters

window Window

The Window for which the animation callback should be set

interval int

The number of frames after which callback will be invoked

callback IOSAnimationCallback

The IOSAnimationCallback to invoke for every frame

Returns

bool

true if animation callback was succesfully set; otherwise, false (check TryGet(out string?) for more information)

Remarks

Note: if you use AppBase, especially OnIterate(Sdl), you don't have to use this API, as SDL will manage this for you.

Note: This method is only available on Apple iOS and will throw a PlatformNotSupportedException on all other platforms!

Exceptions

PlatformNotSupportedException

The executing platform is not Apple iOS

ArgumentNullException

callback is null

TrySetLinuxThreadPriority(long, ThreadPriority, int)

Tries to set the priority and scheduling policy for a thread

public static bool TrySetLinuxThreadPriority(long threadId, ThreadPriority priority, int schedulingPolicy)

Parameters

threadId long

The UNIX thread id of the thread to change it's priority and scheduling policy of

priority ThreadPriority

The new priority (not a UNIX nice value!) to change the thread priority to

schedulingPolicy int

The new scheduling policy to change the thread's scheduling policy to (SCHED_FIFO, SCHED_RR, SCHED_OTHER, etc...)

Returns

bool

true if the priority and scheduling policy of the thread with id threadId was succesfully changed to priority and schedulingPolicy respectively; otherwise, false (check TryGet(out string?) for more information)

Remarks

This uses setpriority() if possible, and RealtimeKit if available.

Note: This method is only available on Linux and will throw a PlatformNotSupportedException on all other platforms!

Exceptions

PlatformNotSupportedException

The executing platform is not Linux

TrySetLinuxThreadPriority(long, int)

Tires to set the UNIX nice value for a thread

public static bool TrySetLinuxThreadPriority(long threadId, int niceValue)

Parameters

threadId long

The UNIX thread id of the thread to change it's priority of

niceValue int

The new UNIX nice value to change the thread priority to

Returns

bool

true if the priority of the thread with id threadId was succesfully changed to niceValue; otherwise, false (check TryGet(out string?) for more information)

Remarks

This uses setpriority() if possible, and RealtimeKit if available.

Note: This method is only available on Linux and will throw a PlatformNotSupportedException on all other platforms!

Exceptions

PlatformNotSupportedException

The executing platform is not Linux

TryShowAndroidToast(string, int, int, int, int)

Shows an Android toast notification

public static bool TryShowAndroidToast(string message, int duration = 0, int gravity = -1, int xOffset = 0, int yOffset = 0)

Parameters

message string

The text message to be shown

duration int

The duration for which the toast notification shall appear on screen. Set this to 0 for a short duration, or to 1 for a long duration.

gravity int

The positioning for where the toast notification shall appear on screen. Should be one of those values: https://developer.android.com/reference/android/view/Gravity. You can also set this to -1 if you don't have a preference.

xOffset int

The horizontal offset in relation to the choosen gravity. Must be only set if gravity is ≥ 0!

yOffset int

The vertical offset in relation to the choosen gravity. Must be only set if gravity is ≥ 0!

Returns

bool

true if the Android toast notification was succesfully shown; otherwise, false (check TryGet(out string?) for more information)

Remarks

Toasts are a sort of lightweight notification that are unique to Android. For more information see: https://developer.android.com/guide/topics/ui/notifiers/toasts.

Android toast notifications are shown in the UI thread.

Note: This method is only available on Android and will throw a PlatformNotSupportedException on all other platforms!

Exceptions

PlatformNotSupportedException

The executing platform is not Android