|
SDL3pp
A slim C++ wrapper for SDL3
|
Platform-specific SDL API functions. More...
Typedefs | |
| using | SDL::WindowsMessageHook = SDL_WindowsMessageHook |
| A callback to be used with SetWindowsMessageHook. | |
| using | SDL::WindowsMessageHookCB = std::function< bool(MSG *)> |
| A callback to be used with SetWindowsMessageHook. | |
| using | SDL::X11EventHook = SDL_X11EventHook |
| A callback to be used with SetX11EventHook. | |
| using | SDL::X11EventHookCB = std::function< bool(XEvent *)> |
| A callback to be used with SetX11EventHook. | |
| using | SDL::iOSAnimationCallback = SDL_iOSAnimationCallback |
| The prototype for an Apple iOS animation callback. | |
| using | SDL::iOSAnimationCB = std::function< void()> |
| The prototype for an Apple iOS animation callback. | |
| using | SDL::RequestAndroidPermissionCallback = SDL_RequestAndroidPermissionCallback |
| Callback that presents a response from a RequestAndroidPermission call. | |
| using | SDL::RequestAndroidPermissionCB = std::function< void(const char *, bool)> |
| Callback that presents a response from a RequestAndroidPermission call. | |
| using | SDL::Sandbox = SDL_Sandbox |
| Application sandbox environment. | |
Functions | |
| void | SDL::SetWindowsMessageHook (WindowsMessageHook callback, void *userdata) |
| Set a callback for every Windows message, run before TranslateMessage(). | |
| void | SDL::SetWindowsMessageHook (WindowsMessageHookCB callback) |
| Set a callback for every Windows message, run before TranslateMessage(). | |
| int | SDL::GetDirect3D9AdapterIndex (Display displayID) |
| Get the D3D9 adapter index that matches the specified display. | |
| void | SDL::GetDXGIOutputInfo (Display displayID, int *adapterIndex, int *outputIndex) |
| Get the DXGI Adapter and Output indices for the specified display. | |
| void | SDL::SetX11EventHook (X11EventHook callback, void *userdata) |
| Set a callback for every X11 event. | |
| void | SDL::SetX11EventHook (X11EventHookCB callback) |
| Set a callback for every X11 event. | |
| void | SDL::SetLinuxThreadPriority (Sint64 threadID, int priority) |
| Sets the UNIX nice value for a thread. | |
| void | SDL::SetLinuxThreadPriorityAndPolicy (Sint64 threadID, int sdlPriority, int schedPolicy) |
| Sets the priority (not nice level) and scheduling policy for a thread. | |
| void | SDL::SetiOSAnimationCallback (WindowBase &window, int interval, iOSAnimationCallback callback, void *callbackParam) |
| Use this function to set the animation callback on Apple iOS. | |
| void | SDL::SetiOSAnimationCallback (WindowBase &window, int interval, iOSAnimationCB callback) |
| Use this function to set the animation callback on Apple iOS. | |
| void | SDL::SetiOSEventPump (bool enabled) |
| Use this function to enable or disable the SDL event pump on Apple iOS. | |
| void * | SDL::GetAndroidJNIEnv () |
| Get the Android Java Native Interface Environment of the current thread. | |
| void * | SDL::GetAndroidActivity () |
| Retrieve the Java instance of the Android activity class. | |
| int | SDL::GetAndroidSDKVersion () |
| Query Android API level of the current device. | |
| bool | SDL::IsChromebook () |
| Query if the application is running on a Chromebook. | |
| bool | SDL::IsDeXMode () |
| Query if the application is running on a Samsung DeX docking station. | |
| void | SDL::SendAndroidBackButton () |
| Trigger the Android system back button behavior. | |
| const char * | SDL::GetAndroidInternalStoragePath () |
| Get the path used for internal storage for this Android application. | |
| Uint32 | SDL::GetAndroidExternalStorageState () |
| Get the current state of external storage for this Android application. | |
| const char * | SDL::GetAndroidExternalStoragePath () |
| Get the path used for external storage for this Android application. | |
| const char * | SDL::GetAndroidCachePath () |
| Get the path used for caching data for this Android application. | |
| bool | SDL::RequestAndroidPermission (StringParam permission, RequestAndroidPermissionCallback cb, void *userdata) |
| Request permissions at runtime, asynchronously. | |
| bool | SDL::RequestAndroidPermission (StringParam permission, RequestAndroidPermissionCB cb) |
| Request permissions at runtime, asynchronously. | |
| void | SDL::ShowAndroidToast (StringParam message, int duration, int gravity, int xoffset, int yoffset) |
| Shows an Android toast notification. | |
| void | SDL::SendAndroidMessage (Uint32 command, int param) |
| Send a user command to SDLActivity. | |
| bool | SDL::IsTablet () |
| Query if the current device is a tablet. | |
| bool | SDL::IsTV () |
| Query if the current device is a TV. | |
| Sandbox | SDL::GetSandbox () |
| Get the application sandbox environment, if any. | |
| void | SDL::OnApplicationWillTerminate () |
| Let iOS apps with external event handling report onApplicationWillTerminate. | |
| void | SDL::OnApplicationDidReceiveMemoryWarning () |
| Let iOS apps with external event handling report onApplicationDidReceiveMemoryWarning. | |
| void | SDL::OnApplicationWillEnterBackground () |
| Let iOS apps with external event handling report onApplicationWillResignActive. | |
| void | SDL::OnApplicationDidEnterBackground () |
| Let iOS apps with external event handling report onApplicationDidEnterBackground. | |
| void | SDL::OnApplicationWillEnterForeground () |
| Let iOS apps with external event handling report onApplicationWillEnterForeground. | |
| void | SDL::OnApplicationDidEnterForeground () |
| Let iOS apps with external event handling report onApplicationDidBecomeActive. | |
| void | SDL::OnApplicationDidChangeStatusBarOrientation () |
| Let iOS apps with external event handling report onApplicationDidChangeStatusBarOrientation. | |
| void | SDL::GetGDKTaskQueue (XTaskQueueHandle *outTaskQueue) |
| Gets a reference to the global async task queue handle for GDK, initializing if needed. | |
| bool | SDL::GetGDKDefaultUser (XUserHandle *outUserHandle) |
| Gets a reference to the default user handle for GDK. | |
Variables | |
| constexpr Uint32 | SDL::ANDROID_EXTERNAL_STORAGE_READ |
| See the official Android developer guide for more information: http://developer.android.com/guide/topics/data/data-storage.html. | |
| constexpr Uint32 | SDL::ANDROID_EXTERNAL_STORAGE_WRITE |
| See the official Android developer guide for more information: http://developer.android.com/guide/topics/data/data-storage.html. | |
| constexpr Sandbox | SDL::SANDBOX_NONE = SDL_SANDBOX_NONE |
| NONE. | |
| constexpr Sandbox | SDL::SANDBOX_UNKNOWN_CONTAINER |
| UNKNOWN_CONTAINER. | |
| constexpr Sandbox | SDL::SANDBOX_FLATPAK = SDL_SANDBOX_FLATPAK |
| FLATPAK. | |
| constexpr Sandbox | SDL::SANDBOX_SNAP = SDL_SANDBOX_SNAP |
| SNAP. | |
| constexpr Sandbox | SDL::SANDBOX_MACOS = SDL_SANDBOX_MACOS |
| MACOS. | |
These are functions that deal with needs of specific operating systems, that didn't make sense to offer as platform-independent, generic APIs.
Most apps can make do without these functions, but they can be useful for integrating with other parts of a specific system, adding platform-specific polish to an app, or solving problems that only affect one target.
| using SDL::iOSAnimationCallback = typedef SDL_iOSAnimationCallback |
This datatype is only useful on Apple iOS.
After passing a function pointer of this type to SetiOSAnimationCallback, the system will call that function pointer at a regular interval.
| userdata | what was passed as callbackParam to SetiOSAnimationCallback as callbackParam. |
| using SDL::iOSAnimationCB = typedef std::function<void ()> |
This datatype is only useful on Apple iOS.
After passing a function pointer of this type to SetiOSAnimationCallback, the system will call that function pointer at a regular interval.
| userdata | what was passed as callbackParam to SetiOSAnimationCallback as callbackParam. |
| using SDL::RequestAndroidPermissionCallback = typedef SDL_RequestAndroidPermissionCallback |
| userdata | an app-controlled pointer that is passed to the callback. |
| permission | the Android-specific permission name that was requested. |
| granted | true if permission is granted, false if denied. |
| using SDL::RequestAndroidPermissionCB = typedef std::function<void (const char *, bool)> |
| userdata | an app-controlled pointer that is passed to the callback. |
| permission | the Android-specific permission name that was requested. |
| granted | true if permission is granted, false if denied. |
| using SDL::Sandbox = typedef SDL_Sandbox |
| using SDL::WindowsMessageHook = typedef SDL_WindowsMessageHook |
This callback may modify the message, and should return true if the message should continue to be processed, or false to prevent further processing.
As this is processing a message directly from the Windows event loop, this callback should do the minimum required work and return quickly.
| userdata | the app-defined pointer provided to SetWindowsMessageHook. |
| msg | a pointer to a Win32 event structure to process. |
| using SDL::WindowsMessageHookCB = typedef std::function<bool (MSG *)> |
This callback may modify the message, and should return true if the message should continue to be processed, or false to prevent further processing.
As this is processing a message directly from the Windows event loop, this callback should do the minimum required work and return quickly.
| userdata | the app-defined pointer provided to SetWindowsMessageHook. |
| msg | a pointer to a Win32 event structure to process. |
| using SDL::X11EventHook = typedef SDL_X11EventHook |
This callback may modify the event, and should return true if the event should continue to be processed, or false to prevent further processing.
As this is processing an event directly from the X11 event loop, this callback should do the minimum required work and return quickly.
| userdata | the app-defined pointer provided to SetX11EventHook. |
| xevent | a pointer to an Xlib XEvent union to process. |
| using SDL::X11EventHookCB = typedef std::function<bool(XEvent*)> |
This callback may modify the event, and should return true if the event should continue to be processed, or false to prevent further processing.
As this is processing an event directly from the X11 event loop, this callback should do the minimum required work and return quickly.
| userdata | the app-defined pointer provided to SetX11EventHook. |
| xevent | a pointer to an Xlib XEvent union to process. |
|
inline |
The prototype of the function in SDL's code actually declares a void* return type, even if the implementation returns a jobject. The rationale being that the SDL headers can avoid including jni.h.
The jobject returned by the function 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
|
inline |
This path is unique to your application, but is public and can be written to by other applications.
Your cache path is typically: /data/data/your.app.package/cache/.
This is a C wrapper over android.content.Context.getCacheDir():
https://developer.android.com/reference/android/content/Context#getCacheDir()
| Error | on failure. |
|
inline |
This path is unique to your application, but is public and can be written to by other applications.
Your external storage path is typically: /storage/sdcard0/Android/data/your.app.package/files.
This is a C wrapper over android.content.Context.getExternalFilesDir():
https://developer.android.com/reference/android/content/Context#getExternalFilesDir()
| Error | on failure. |
|
inline |
The current state of external storage, a bitmask of these values: ANDROID_EXTERNAL_STORAGE_READ, ANDROID_EXTERNAL_STORAGE_WRITE.
If external storage is currently unavailable, this will return 0.
|
inline |
This path is unique to your application and cannot be written to by other applications.
Your internal storage path is typically: /data/data/your.app.package/files.
This is a C wrapper over android.content.Context.getFilesDir():
https://developer.android.com/reference/android/content/Context#getFilesDir()
|
inline |
This is the JNIEnv one needs to access the Java virtual machine from native code, and is needed for many Android APIs to be usable from C.
The prototype of the function in SDL's code actually declare a void* return type, even if the implementation returns a pointer to a JNIEnv. The rationale being that the SDL headers can avoid including jni.h.
|
inline |
|
inline |
The returned adapter index can be passed to IDirect3D9::CreateDevice and controls on which monitor a full screen application will appear.
| displayID | the instance of the display to query. |
| Error | on failure. |
|
inline |
The DXGI Adapter and Output indices can be passed to EnumAdapters and EnumOutputs respectively to get the objects required to create a DX10 or DX11 device and swap chain.
| displayID | the instance of the display to query. |
| adapterIndex | a pointer to be filled in with the adapter index. |
| outputIndex | a pointer to be filled in with the output index. |
| Error | on failure. |
|
inline |
This is effectively a synchronous version of XUserAddAsync, which always prefers the default user and allows a sign-in UI.
| outUserHandle | a pointer to be filled in with the default user handle. |
|
inline |
|
inline |
|
inline |
|
inline |
|
inline |
|
inline |
|
inline |
This functions allows iOS apps that have their own event handling to hook into SDL to generate SDL events. This maps directly to an iOS-specific event, but since it 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 directly; SDL's internal event code will handle all this for windows created by WindowBase.WindowBase!
|
inline |
This functions allows iOS apps that have their own event handling to hook into SDL to generate SDL events. This maps directly to an iOS-specific event, but since it 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 directly; SDL's internal event code will handle all this for windows created by WindowBase.WindowBase!
|
inline |
This functions allows iOS apps that have their own event handling to hook into SDL to generate SDL events. This maps directly to an iOS-specific event, but since it 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 directly; SDL's internal event code will handle all this for windows created by WindowBase.WindowBase!
|
inline |
This functions allows iOS apps that have their own event handling to hook into SDL to generate SDL events. This maps directly to an iOS-specific event, but since it 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 directly; SDL's internal event code will handle all this for windows created by WindowBase.WindowBase!
|
inline |
This functions allows iOS apps that have their own event handling to hook into SDL to generate SDL events. This maps directly to an iOS-specific event, but since it 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 directly; SDL's internal event code will handle all this for windows created by WindowBase.WindowBase!
|
inline |
This functions allows iOS apps that have their own event handling to hook into SDL to generate SDL events. This maps directly to an iOS-specific event, but since it 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 directly; SDL's internal event code will handle all this for windows created by WindowBase.WindowBase!
|
inline |
This functions allows iOS apps that have their own event handling to hook into SDL to generate SDL events. This maps directly to an iOS-specific event, but since it 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 directly; SDL's internal event code will handle all this for windows created by WindowBase.WindowBase!
|
inline |
You do not need to call this for built-in functionality of SDL; recording from a microphone or reading images from a camera, using standard SDL APIs, will manage permission requests for you.
This function never blocks. Instead, the app-supplied callback will be called when a decision has been made. This callback may happen 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 fire, probably on the current thread and before this function returns.
If the request submission fails, this function returns -1 and the callback will NOT be called, but this should only happen in catastrophic conditions, like memory running out. Normally there will be a yes or no to the request through the callback.
For the permission parameter, choose a value from here:
https://developer.android.com/reference/android/Manifest.permission
| permission | the permission to request. |
| cb | the callback to trigger when the request has a response. |
| userdata | an app-controlled pointer that is passed to the callback. |
|
inline |
You do not need to call this for built-in functionality of SDL; recording from a microphone or reading images from a camera, using standard SDL APIs, will manage permission requests for you.
This function never blocks. Instead, the app-supplied callback will be called when a decision has been made. This callback may happen 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 fire, probably on the current thread and before this function returns.
If the request submission fails, this function returns -1 and the callback will NOT be called, but this should only happen in catastrophic conditions, like memory running out. Normally there will be a yes or no to the request through the callback.
For the permission parameter, choose a value from here:
https://developer.android.com/reference/android/Manifest.permission
| permission | the permission to request. |
| cb | the callback to trigger when the request has a response. |
|
inline |
|
inline |
Override "boolean onUnhandledMessage(Message msg)" to handle the message.
| command | user command that must be greater or equal to 0x8000. |
| param | user parameter. |
| Error | on failure. |
|
inline |
The function prototype for callback is:
Where its parameter, callbackParam, is what was passed as callbackParam to SetiOSAnimationCallback().
This function is only available on Apple iOS.
For more information see:
https://wiki.libsdl.org/SDL3/README/ios
Note that if you use the "main callbacks" instead of a standard C main function, you don't have to use this API, as SDL will manage this for you.
Details on main callbacks are here:
https://wiki.libsdl.org/SDL3/README/main-functions
| window | the window for which the animation callback should be set. |
| interval | the number of frames after which callback will be called. |
| callback | the function to call for every frame. |
| callbackParam | a pointer that is passed to callback. |
| Error | on failure. |
|
inline |
The function prototype for callback is:
Where its parameter, callbackParam, is what was passed as callbackParam to SetiOSAnimationCallback().
This function is only available on Apple iOS.
For more information see:
https://wiki.libsdl.org/SDL3/README/ios
Note that if you use the "main callbacks" instead of a standard C main function, you don't have to use this API, as SDL will manage this for you.
Details on main callbacks are here:
https://wiki.libsdl.org/SDL3/README/main-functions
| window | the window for which the animation callback should be set. |
| interval | the number of frames after which callback will be called. |
| callback | the function to call for every frame. |
| Error | on failure. |
|
inline |
This function is only available on Apple iOS.
| enabled | true to enable the event pump, false to disable it. |
|
inline |
|
inline |
This uses setpriority() if possible, and RealtimeKit if available.
| threadID | the Unix thread ID to change priority of. |
| sdlPriority | the new ThreadPriority value. |
| schedPolicy | the new scheduling policy (SCHED_FIFO, SCHED_RR, SCHED_OTHER, etc...). |
| Error | on failure. |
|
inline |
The callback may modify the message, and should return true if the message should continue to be processed, or false to prevent further processing.
| callback | the WindowsMessageHook function to call. |
| userdata | a pointer to pass to every iteration of callback. |
|
inline |
The callback may modify the message, and should return true if the message should continue to be processed, or false to prevent further processing.
| callback | the WindowsMessageHook function to call. |
|
inline |
The callback may modify the event, and should return true if the event should continue to be processed, or false to prevent further processing.
| callback | the X11EventHook function to call. |
| userdata | a pointer to pass to every iteration of callback. |
|
inline |
The callback may modify the event, and should return true if the event should continue to be processed, or false to prevent further processing.
| callback | the X11EventHook function to call. |
|
inline |
Toasts are a sort of lightweight notification that are unique to Android.
https://developer.android.com/guide/topics/ui/notifiers/toasts
Shows toast in UI thread.
For the gravity parameter, choose a value from here, or -1 if you don't have a preference:
https://developer.android.com/reference/android/view/Gravity
| message | text message to be shown. |
| duration | 0=short, 1=long. |
| gravity | where the notification should appear on the screen. |
| xoffset | set this parameter only when gravity >=0. |
| yoffset | set this parameter only when gravity >=0. |
| Error | on failure. |
|
constexpr |
|
constexpr |
|
constexpr |
1.9.8