SDL 3.0
SDL_system.h
Go to the documentation of this file.
1/*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
4
5 This software is provided 'as-is', without any express or implied
6 warranty. In no event will the authors be held liable for any damages
7 arising from the use of this software.
8
9 Permission is granted to anyone to use this software for any purpose,
10 including commercial applications, and to alter it and redistribute it
11 freely, subject to the following restrictions:
12
13 1. The origin of this software must not be misrepresented; you must not
14 claim that you wrote the original software. If you use this software
15 in a product, an acknowledgment in the product documentation would be
16 appreciated but is not required.
17 2. Altered source versions must be plainly marked as such, and must not be
18 misrepresented as being the original software.
19 3. This notice may not be removed or altered from any source distribution.
20*/
21
22/**
23 * # CategorySystem
24 *
25 * Platform-specific SDL API functions.
26 */
27
28#ifndef SDL_system_h_
29#define SDL_system_h_
30
31#include <SDL3/SDL_stdinc.h>
32#include <SDL3/SDL_error.h>
33#include <SDL3/SDL_keyboard.h>
34#include <SDL3/SDL_render.h>
35#include <SDL3/SDL_video.h>
36
37#include <SDL3/SDL_begin_code.h>
38/* Set up for C function definitions, even when using C++ */
39#ifdef __cplusplus
40extern "C" {
41#endif
42
43
44/*
45 * Platform specific functions for Windows
46 */
47#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK)
48
49typedef struct tagMSG MSG;
50
51/**
52 * A callback to be used with SDL_SetWindowsMessageHook.
53 *
54 * This callback may modify the message, and should return SDL_TRUE if the
55 * message should continue to be processed, or SDL_FALSE to prevent further
56 * processing.
57 *
58 * As this is processing a message directly from the Windows event loop, this
59 * callback should do the minimum required work and return quickly.
60 *
61 * \param userdata the app-defined pointer provided to
62 * SDL_SetWindowsMessageHook.
63 * \param msg a pointer to a Win32 event structure to process.
64 * \returns SDL_TRUE to let event continue on, SDL_FALSE to drop it.
65 *
66 * \threadsafety This may only be called (by SDL) from the thread handling the
67 * Windows event loop.
68 *
69 * \since This datatype is available since SDL 3.0.0.
70 *
71 * \sa SDL_SetWindowsMessageHook
72 * \sa SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP
73 */
74typedef SDL_bool (SDLCALL *SDL_WindowsMessageHook)(void *userdata, MSG *msg);
75
76/**
77 * Set a callback for every Windows message, run before TranslateMessage().
78 *
79 * The callback may modify the message, and should return SDL_TRUE if the
80 * message should continue to be processed, or SDL_FALSE to prevent further
81 * processing.
82 *
83 * \param callback the SDL_WindowsMessageHook function to call.
84 * \param userdata a pointer to pass to every iteration of `callback`.
85 *
86 * \since This function is available since SDL 3.0.0.
87 *
88 * \sa SDL_WindowsMessageHook
89 * \sa SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP
90 */
91extern SDL_DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHook callback, void *userdata);
92
93#endif /* defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) */
94
95#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK)
96
97/**
98 * Get the D3D9 adapter index that matches the specified display.
99 *
100 * The returned adapter index can be passed to `IDirect3D9::CreateDevice` and
101 * controls on which monitor a full screen application will appear.
102 *
103 * \param displayID the instance of the display to query.
104 * \returns the D3D9 adapter index on success or a negative error code on
105 * failure; call SDL_GetError() for more information.
106 *
107 * \since This function is available since SDL 3.0.0.
108 */
109extern SDL_DECLSPEC int SDLCALL SDL_GetDirect3D9AdapterIndex(SDL_DisplayID displayID);
110
111#endif /* defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK) */
112
113#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK)
114
115/**
116 * Get the DXGI Adapter and Output indices for the specified display.
117 *
118 * The DXGI Adapter and Output indices can be passed to `EnumAdapters` and
119 * `EnumOutputs` respectively to get the objects required to create a DX10 or
120 * DX11 device and swap chain.
121 *
122 * \param displayID the instance of the display to query.
123 * \param adapterIndex a pointer to be filled in with the adapter index.
124 * \param outputIndex a pointer to be filled in with the output index.
125 * \returns 0 on success or a negative error code on failure; call
126 * SDL_GetError() for more information.
127 *
128 * \since This function is available since SDL 3.0.0.
129 */
130extern SDL_DECLSPEC int SDLCALL SDL_GetDXGIOutputInfo(SDL_DisplayID displayID, int *adapterIndex, int *outputIndex);
131
132#endif /* defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK) */
133
134/*
135 * Platform specific functions for UNIX
136 */
137
138typedef union _XEvent XEvent;
139typedef SDL_bool (SDLCALL *SDL_X11EventHook)(void *userdata, XEvent *xevent);
140
141/**
142 * Set a callback for every X11 event.
143 *
144 * The callback may modify the event, and should return SDL_TRUE if the event
145 * should continue to be processed, or SDL_FALSE to prevent further
146 * processing.
147 *
148 * \param callback the SDL_X11EventHook function to call.
149 * \param userdata a pointer to pass to every iteration of `callback`.
150 *
151 * \since This function is available since SDL 3.0.0.
152 */
153extern SDL_DECLSPEC void SDLCALL SDL_SetX11EventHook(SDL_X11EventHook callback, void *userdata);
154
155/* Platform specific functions for Linux*/
156#ifdef SDL_PLATFORM_LINUX
157
158/**
159 * Sets the UNIX nice value for a thread.
160 *
161 * This uses setpriority() if possible, and RealtimeKit if available.
162 *
163 * \param threadID the Unix thread ID to change priority of.
164 * \param priority the new, Unix-specific, priority value.
165 * \returns 0 on success or a negative error code on failure; call
166 * SDL_GetError() for more information.
167 *
168 * \since This function is available since SDL 3.0.0.
169 */
170extern SDL_DECLSPEC int SDLCALL SDL_SetLinuxThreadPriority(Sint64 threadID, int priority);
171
172/**
173 * Sets the priority (not nice level) and scheduling policy for a thread.
174 *
175 * This uses setpriority() if possible, and RealtimeKit if available.
176 *
177 * \param threadID the Unix thread ID to change priority of.
178 * \param sdlPriority the new SDL_ThreadPriority value.
179 * \param schedPolicy the new scheduling policy (SCHED_FIFO, SCHED_RR,
180 * SCHED_OTHER, etc...).
181 * \returns 0 on success or a negative error code on failure; call
182 * SDL_GetError() for more information.
183 *
184 * \since This function is available since SDL 3.0.0.
185 */
186extern SDL_DECLSPEC int SDLCALL SDL_SetLinuxThreadPriorityAndPolicy(Sint64 threadID, int sdlPriority, int schedPolicy);
187
188#endif /* SDL_PLATFORM_LINUX */
189
190/*
191 * Platform specific functions for iOS
192 */
193#ifdef SDL_PLATFORM_IOS
194
195/**
196 * The prototype for an Apple iOS animation callback.
197 *
198 * This datatype is only useful on Apple iOS.
199 *
200 * After passing a function pointer of this type to
201 * SDL_SetiOSAnimationCallback, the system will call that function pointer at
202 * a regular interval.
203 *
204 * \param userdata what was passed as `callbackParam` to
205 * SDL_SetiOSAnimationCallback as `callbackParam`.
206 *
207 * \since This datatype is available since SDL 3.0.0.
208 *
209 * \sa SDL_SetiOSAnimationCallback
210 */
211typedef void (SDLCALL *SDL_iOSAnimationCallback)(void *userdata);
212
213/**
214 * Use this function to set the animation callback on Apple iOS.
215 *
216 * The function prototype for `callback` is:
217 *
218 * ```c
219 * void callback(void *callbackParam);
220 * ```
221 *
222 * Where its parameter, `callbackParam`, is what was passed as `callbackParam`
223 * to SDL_SetiOSAnimationCallback().
224 *
225 * This function is only available on Apple iOS.
226 *
227 * For more information see:
228 *
229 * https://wiki.libsdl.org/SDL3/README/ios
230 *
231 * Note that if you use the "main callbacks" instead of a standard C `main`
232 * function, you don't have to use this API, as SDL will manage this for you.
233 *
234 * Details on main callbacks are here:
235 *
236 * https://wiki.libsdl.org/SDL3/README/main-functions
237 *
238 * \param window the window for which the animation callback should be set.
239 * \param interval the number of frames after which **callback** will be
240 * called.
241 * \param callback the function to call for every frame.
242 * \param callbackParam a pointer that is passed to `callback`.
243 * \returns 0 on success or a negative error code on failure; call
244 * SDL_GetError() for more information.
245 *
246 * \since This function is available since SDL 3.0.0.
247 *
248 * \sa SDL_SetiOSEventPump
249 */
250extern SDL_DECLSPEC int SDLCALL SDL_SetiOSAnimationCallback(SDL_Window *window, int interval, SDL_iOSAnimationCallback callback, void *callbackParam);
251
252/**
253 * Use this function to enable or disable the SDL event pump on Apple iOS.
254 *
255 * This function is only available on Apple iOS.
256 *
257 * \param enabled SDL_TRUE to enable the event pump, SDL_FALSE to disable it.
258 *
259 * \since This function is available since SDL 3.0.0.
260 *
261 * \sa SDL_SetiOSAnimationCallback
262 */
263extern SDL_DECLSPEC void SDLCALL SDL_SetiOSEventPump(SDL_bool enabled);
264
265#endif /* SDL_PLATFORM_IOS */
266
267
268/*
269 * Platform specific functions for Android
270 */
271#ifdef SDL_PLATFORM_ANDROID
272
273/**
274 * Get the Android Java Native Interface Environment of the current thread.
275 *
276 * This is the JNIEnv one needs to access the Java virtual machine from native
277 * code, and is needed for many Android APIs to be usable from C.
278 *
279 * The prototype of the function in SDL's code actually declare a void* return
280 * type, even if the implementation returns a pointer to a JNIEnv. The
281 * rationale being that the SDL headers can avoid including jni.h.
282 *
283 * \returns a pointer to Java native interface object (JNIEnv) to which the
284 * current thread is attached, or NULL on failure; call
285 * SDL_GetError() for more information.
286 *
287 * \threadsafety It is safe to call this function from any thread.
288 *
289 * \since This function is available since SDL 3.0.0.
290 *
291 * \sa SDL_GetAndroidActivity
292 */
293extern SDL_DECLSPEC void * SDLCALL SDL_GetAndroidJNIEnv(void);
294
295/**
296 * Retrieve the Java instance of the Android activity class.
297 *
298 * The prototype of the function in SDL's code actually declares a void*
299 * return type, even if the implementation returns a jobject. The rationale
300 * being that the SDL headers can avoid including jni.h.
301 *
302 * The jobject returned by the function is a local reference and must be
303 * released by the caller. See the PushLocalFrame() and PopLocalFrame() or
304 * DeleteLocalRef() functions of the Java native interface:
305 *
306 * https://docs.oracle.com/javase/1.5.0/docs/guide/jni/spec/functions.html
307 *
308 * \returns the jobject representing the instance of the Activity class of the
309 * Android application, or NULL on failure; call SDL_GetError() for
310 * more information.
311 *
312 * \threadsafety It is safe to call this function from any thread.
313 *
314 * \since This function is available since SDL 3.0.0.
315 *
316 * \sa SDL_GetAndroidJNIEnv
317 */
318extern SDL_DECLSPEC void * SDLCALL SDL_GetAndroidActivity(void);
319
320/**
321 * Query Android API level of the current device.
322 *
323 * - API level 35: Android 15 (VANILLA_ICE_CREAM)
324 * - API level 34: Android 14 (UPSIDE_DOWN_CAKE)
325 * - API level 33: Android 13 (TIRAMISU)
326 * - API level 32: Android 12L (S_V2)
327 * - API level 31: Android 12 (S)
328 * - API level 30: Android 11 (R)
329 * - API level 29: Android 10 (Q)
330 * - API level 28: Android 9 (P)
331 * - API level 27: Android 8.1 (O_MR1)
332 * - API level 26: Android 8.0 (O)
333 * - API level 25: Android 7.1 (N_MR1)
334 * - API level 24: Android 7.0 (N)
335 * - API level 23: Android 6.0 (M)
336 * - API level 22: Android 5.1 (LOLLIPOP_MR1)
337 * - API level 21: Android 5.0 (LOLLIPOP, L)
338 * - API level 20: Android 4.4W (KITKAT_WATCH)
339 * - API level 19: Android 4.4 (KITKAT)
340 * - API level 18: Android 4.3 (JELLY_BEAN_MR2)
341 * - API level 17: Android 4.2 (JELLY_BEAN_MR1)
342 * - API level 16: Android 4.1 (JELLY_BEAN)
343 * - API level 15: Android 4.0.3 (ICE_CREAM_SANDWICH_MR1)
344 * - API level 14: Android 4.0 (ICE_CREAM_SANDWICH)
345 * - API level 13: Android 3.2 (HONEYCOMB_MR2)
346 * - API level 12: Android 3.1 (HONEYCOMB_MR1)
347 * - API level 11: Android 3.0 (HONEYCOMB)
348 * - API level 10: Android 2.3.3 (GINGERBREAD_MR1)
349 *
350 * \returns the Android API level.
351 *
352 * \since This function is available since SDL 3.0.0.
353 */
354extern SDL_DECLSPEC int SDLCALL SDL_GetAndroidSDKVersion(void);
355
356/**
357 * Query if the application is running on Android TV.
358 *
359 * \returns SDL_TRUE if this is Android TV, SDL_FALSE otherwise.
360 *
361 * \since This function is available since SDL 3.0.0.
362 */
363extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsAndroidTV(void);
364
365/**
366 * Query if the application is running on a Chromebook.
367 *
368 * \returns SDL_TRUE if this is a Chromebook, SDL_FALSE otherwise.
369 *
370 * \since This function is available since SDL 3.0.0.
371 */
372extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsChromebook(void);
373
374/**
375 * Query if the application is running on a Samsung DeX docking station.
376 *
377 * \returns SDL_TRUE if this is a DeX docking station, SDL_FALSE otherwise.
378 *
379 * \since This function is available since SDL 3.0.0.
380 */
381extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsDeXMode(void);
382
383/**
384 * Trigger the Android system back button behavior.
385 *
386 * \threadsafety It is safe to call this function from any thread.
387 *
388 * \since This function is available since SDL 3.0.0.
389 */
390extern SDL_DECLSPEC void SDLCALL SDL_SendAndroidBackButton(void);
391
392/**
393 * See the official Android developer guide for more information:
394 * http://developer.android.com/guide/topics/data/data-storage.html
395 *
396 * \since This macro is available since SDL 3.0.0.
397 */
398#define SDL_ANDROID_EXTERNAL_STORAGE_READ 0x01
399#define SDL_ANDROID_EXTERNAL_STORAGE_WRITE 0x02
400
401/**
402 * Get the path used for internal storage for this Android application.
403 *
404 * This path is unique to your application and cannot be written to by other
405 * applications.
406 *
407 * Your internal storage path is typically:
408 * `/data/data/your.app.package/files`.
409 *
410 * This is a C wrapper over `android.content.Context.getFilesDir()`:
411 *
412 * https://developer.android.com/reference/android/content/Context#getFilesDir()
413 *
414 * \returns the path used for internal storage or NULL on failure; call
415 * SDL_GetError() for more information.
416 *
417 * \since This function is available since SDL 3.0.0.
418 *
419 * \sa SDL_GetAndroidExternalStorageState
420 */
421extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidInternalStoragePath(void);
422
423/**
424 * Get the current state of external storage for this Android application.
425 *
426 * The current state of external storage, a bitmask of these values:
427 * `SDL_ANDROID_EXTERNAL_STORAGE_READ`, `SDL_ANDROID_EXTERNAL_STORAGE_WRITE`.
428 *
429 * If external storage is currently unavailable, this will return 0.
430 *
431 * \returns the current state of external storage, or 0 if external storage is
432 * currently unavailable.
433 *
434 * \since This function is available since SDL 3.0.0.
435 *
436 * \sa SDL_GetAndroidExternalStoragePath
437 */
438extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetAndroidExternalStorageState(void);
439
440/**
441 * Get the path used for external storage for this Android application.
442 *
443 * This path is unique to your application, but is public and can be written
444 * to by other applications.
445 *
446 * Your external storage path is typically:
447 * `/storage/sdcard0/Android/data/your.app.package/files`.
448 *
449 * This is a C wrapper over `android.content.Context.getExternalFilesDir()`:
450 *
451 * https://developer.android.com/reference/android/content/Context#getExternalFilesDir()
452 *
453 * \returns the path used for external storage for this application on success
454 * or NULL on failure; call SDL_GetError() for more information.
455 *
456 * \since This function is available since SDL 3.0.0.
457 *
458 * \sa SDL_GetAndroidExternalStorageState
459 */
460extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidExternalStoragePath(void);
461
462/**
463 * Get the path used for caching data for this Android application.
464 *
465 * This path is unique to your application, but is public and can be written
466 * to by other applications.
467 *
468 * Your cache path is typically: `/data/data/your.app.package/cache/`.
469 *
470 * This is a C wrapper over `android.content.Context.getCacheDir()`:
471 *
472 * https://developer.android.com/reference/android/content/Context#getCacheDir()
473 *
474 * \returns the path used for caches for this application on success or NULL
475 * on failure; call SDL_GetError() for more information.
476 *
477 * \since This function is available since SDL 3.0.0.
478 */
479extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidCachePath(void);
480
481
482typedef void (SDLCALL *SDL_RequestAndroidPermissionCallback)(void *userdata, const char *permission, SDL_bool granted);
483
484/**
485 * Request permissions at runtime, asynchronously.
486 *
487 * You do not need to call this for built-in functionality of SDL; recording
488 * from a microphone or reading images from a camera, using standard SDL APIs,
489 * will manage permission requests for you.
490 *
491 * This function never blocks. Instead, the app-supplied callback will be
492 * called when a decision has been made. This callback may happen on a
493 * different thread, and possibly much later, as it might wait on a user to
494 * respond to a system dialog. If permission has already been granted for a
495 * specific entitlement, the callback will still fire, probably on the current
496 * thread and before this function returns.
497 *
498 * If the request submission fails, this function returns -1 and the callback
499 * will NOT be called, but this should only happen in catastrophic conditions,
500 * like memory running out. Normally there will be a yes or no to the request
501 * through the callback.
502 *
503 * \param permission the permission to request.
504 * \param cb the callback to trigger when the request has a response.
505 * \param userdata an app-controlled pointer that is passed to the callback.
506 * \returns zero if the request was submitted, -1 if there was an error
507 * submitting. The result of the request is only ever reported
508 * through the callback, not this return value.
509 *
510 * \threadsafety It is safe to call this function from any thread.
511 *
512 * \since This function is available since SDL 3.0.0.
513 */
514extern SDL_DECLSPEC int SDLCALL SDL_RequestAndroidPermission(const char *permission, SDL_RequestAndroidPermissionCallback cb, void *userdata);
515
516/**
517 * Shows an Android toast notification.
518 *
519 * Toasts are a sort of lightweight notification that are unique to Android.
520 *
521 * https://developer.android.com/guide/topics/ui/notifiers/toasts
522 *
523 * Shows toast in UI thread.
524 *
525 * For the `gravity` parameter, choose a value from here, or -1 if you don't
526 * have a preference:
527 *
528 * https://developer.android.com/reference/android/view/Gravity
529 *
530 * \param message text message to be shown.
531 * \param duration 0=short, 1=long.
532 * \param gravity where the notification should appear on the screen.
533 * \param xoffset set this parameter only when gravity >=0.
534 * \param yoffset set this parameter only when gravity >=0.
535 * \returns 0 on success or a negative error code on failure; call
536 * SDL_GetError() for more information.
537 *
538 * \threadsafety It is safe to call this function from any thread.
539 *
540 * \since This function is available since SDL 3.0.0.
541 */
542extern SDL_DECLSPEC int SDLCALL SDL_ShowAndroidToast(const char *message, int duration, int gravity, int xoffset, int yoffset);
543
544/**
545 * Send a user command to SDLActivity.
546 *
547 * Override "boolean onUnhandledMessage(Message msg)" to handle the message.
548 *
549 * \param command user command that must be greater or equal to 0x8000.
550 * \param param user parameter.
551 * \returns 0 on success or a negative error code on failure; call
552 * SDL_GetError() for more information.
553 *
554 * \threadsafety It is safe to call this function from any thread.
555 *
556 * \since This function is available since SDL 3.0.0.
557 */
558extern SDL_DECLSPEC int SDLCALL SDL_SendAndroidMessage(Uint32 command, int param);
559
560#endif /* SDL_PLATFORM_ANDROID */
561
562/*
563 * Platform specific functions for WinRT
564 */
565#ifdef SDL_PLATFORM_WINRT
566
567/**
568 * WinRT / Windows Phone path types
569 *
570 * \since This enum is available since SDL 3.0.0.
571 */
572typedef enum SDL_WinRT_Path
573{
574 /** The installed app's root directory.
575 Files here are likely to be read-only. */
576 SDL_WINRT_PATH_INSTALLED_LOCATION,
577
578 /** The app's local data store. Files may be written here */
579 SDL_WINRT_PATH_LOCAL_FOLDER,
580
581 /** The app's roaming data store. Unsupported on Windows Phone.
582 Files written here may be copied to other machines via a network
583 connection.
584 */
585 SDL_WINRT_PATH_ROAMING_FOLDER,
586
587 /** The app's temporary data store. Unsupported on Windows Phone.
588 Files written here may be deleted at any time. */
589 SDL_WINRT_PATH_TEMP_FOLDER
590} SDL_WinRT_Path;
591
592
593/**
594 * WinRT Device Family
595 *
596 * \since This enum is available since SDL 3.0.0.
597 */
598typedef enum SDL_WinRT_DeviceFamily
599{
600 /** Unknown family */
601 SDL_WINRT_DEVICEFAMILY_UNKNOWN,
602
603 /** Desktop family*/
604 SDL_WINRT_DEVICEFAMILY_DESKTOP,
605
606 /** Mobile family (for example smartphone) */
607 SDL_WINRT_DEVICEFAMILY_MOBILE,
608
609 /** XBox family */
610 SDL_WINRT_DEVICEFAMILY_XBOX,
611} SDL_WinRT_DeviceFamily;
612
613
614/**
615 * Retrieve a WinRT defined path on the local file system.
616 *
617 * Not all paths are available on all versions of Windows. This is especially
618 * true on Windows Phone. Check the documentation for the given SDL_WinRT_Path
619 * for more information on which path types are supported where.
620 *
621 * Documentation on most app-specific path types on WinRT can be found on
622 * MSDN, at the URL:
623 *
624 * https://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx
625 *
626 * \param pathType the type of path to retrieve, one of SDL_WinRT_Path.
627 * \returns a UTF-8 string (8-bit, multi-byte) containing the path, or NULL if
628 * the path is not available for any reason; call SDL_GetError() for
629 * more information.
630 *
631 * \since This function is available since SDL 3.0.0.
632 */
633extern SDL_DECLSPEC const char * SDLCALL SDL_GetWinRTFSPath(SDL_WinRT_Path pathType);
634
635/**
636 * Detects the device family of WinRT platform at runtime.
637 *
638 * \returns a value from the SDL_WinRT_DeviceFamily enum.
639 *
640 * \since This function is available since SDL 3.0.0.
641 */
642extern SDL_DECLSPEC SDL_WinRT_DeviceFamily SDLCALL SDL_GetWinRTDeviceFamily();
643
644#endif /* SDL_PLATFORM_WINRT */
645
646/**
647 * Query if the current device is a tablet.
648 *
649 * If SDL can't determine this, it will return SDL_FALSE.
650 *
651 * \returns SDL_TRUE if the device is a tablet, SDL_FALSE otherwise.
652 *
653 * \since This function is available since SDL 3.0.0.
654 */
655extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsTablet(void);
656
657/* Functions used by iOS app delegates to notify SDL about state changes. */
658
659/**
660 * Let iOS apps with external event handling report
661 * onApplicationWillTerminate.
662 *
663 * This functions allows iOS apps that have their own event handling to hook
664 * into SDL to generate SDL events. This maps directly to an iOS-specific
665 * event, but since it doesn't do anything iOS-specific internally, it is
666 * available on all platforms, in case it might be useful for some specific
667 * paradigm. Most apps do not need to use this directly; SDL's internal event
668 * code will handle all this for windows created by SDL_CreateWindow!
669 *
670 * \threadsafety It is safe to call this function from any thread.
671 *
672 * \since This function is available since SDL 3.0.0.
673 */
674extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillTerminate(void);
675
676/**
677 * Let iOS apps with external event handling report
678 * onApplicationDidReceiveMemoryWarning.
679 *
680 * This functions allows iOS apps that have their own event handling to hook
681 * into SDL to generate SDL events. This maps directly to an iOS-specific
682 * event, but since it doesn't do anything iOS-specific internally, it is
683 * available on all platforms, in case it might be useful for some specific
684 * paradigm. Most apps do not need to use this directly; SDL's internal event
685 * code will handle all this for windows created by SDL_CreateWindow!
686 *
687 * \threadsafety It is safe to call this function from any thread.
688 *
689 * \since This function is available since SDL 3.0.0.
690 */
691extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidReceiveMemoryWarning(void);
692
693/**
694 * Let iOS apps with external event handling report
695 * onApplicationWillResignActive.
696 *
697 * This functions allows iOS apps that have their own event handling to hook
698 * into SDL to generate SDL events. This maps directly to an iOS-specific
699 * event, but since it doesn't do anything iOS-specific internally, it is
700 * available on all platforms, in case it might be useful for some specific
701 * paradigm. Most apps do not need to use this directly; SDL's internal event
702 * code will handle all this for windows created by SDL_CreateWindow!
703 *
704 * \threadsafety It is safe to call this function from any thread.
705 *
706 * \since This function is available since SDL 3.0.0.
707 */
708extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillEnterBackground(void);
709
710/**
711 * Let iOS apps with external event handling report
712 * onApplicationDidEnterBackground.
713 *
714 * This functions allows iOS apps that have their own event handling to hook
715 * into SDL to generate SDL events. This maps directly to an iOS-specific
716 * event, but since it doesn't do anything iOS-specific internally, it is
717 * available on all platforms, in case it might be useful for some specific
718 * paradigm. Most apps do not need to use this directly; SDL's internal event
719 * code will handle all this for windows created by SDL_CreateWindow!
720 *
721 * \threadsafety It is safe to call this function from any thread.
722 *
723 * \since This function is available since SDL 3.0.0.
724 */
725extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidEnterBackground(void);
726
727/**
728 * Let iOS apps with external event handling report
729 * onApplicationWillEnterForeground.
730 *
731 * This functions allows iOS apps that have their own event handling to hook
732 * into SDL to generate SDL events. This maps directly to an iOS-specific
733 * event, but since it doesn't do anything iOS-specific internally, it is
734 * available on all platforms, in case it might be useful for some specific
735 * paradigm. Most apps do not need to use this directly; SDL's internal event
736 * code will handle all this for windows created by SDL_CreateWindow!
737 *
738 * \threadsafety It is safe to call this function from any thread.
739 *
740 * \since This function is available since SDL 3.0.0.
741 */
742extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillEnterForeground(void);
743
744/**
745 * Let iOS apps with external event handling report
746 * onApplicationDidBecomeActive.
747 *
748 * This functions allows iOS apps that have their own event handling to hook
749 * into SDL to generate SDL events. This maps directly to an iOS-specific
750 * event, but since it doesn't do anything iOS-specific internally, it is
751 * available on all platforms, in case it might be useful for some specific
752 * paradigm. Most apps do not need to use this directly; SDL's internal event
753 * code will handle all this for windows created by SDL_CreateWindow!
754 *
755 * \threadsafety It is safe to call this function from any thread.
756 *
757 * \since This function is available since SDL 3.0.0.
758 */
759extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidEnterForeground(void);
760
761#ifdef SDL_PLATFORM_IOS
762
763/**
764 * Let iOS apps with external event handling report
765 * onApplicationDidChangeStatusBarOrientation.
766 *
767 * This functions allows iOS apps that have their own event handling to hook
768 * into SDL to generate SDL events. This maps directly to an iOS-specific
769 * event, but since it doesn't do anything iOS-specific internally, it is
770 * available on all platforms, in case it might be useful for some specific
771 * paradigm. Most apps do not need to use this directly; SDL's internal event
772 * code will handle all this for windows created by SDL_CreateWindow!
773 *
774 * \threadsafety It is safe to call this function from any thread.
775 *
776 * \since This function is available since SDL 3.0.0.
777 */
778extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidChangeStatusBarOrientation(void);
779#endif
780
781/*
782 * Functions used only by GDK
783 */
784#ifdef SDL_PLATFORM_GDK
785typedef struct XTaskQueueObject *XTaskQueueHandle;
786typedef struct XUser *XUserHandle;
787
788/**
789 * Gets a reference to the global async task queue handle for GDK,
790 * initializing if needed.
791 *
792 * Once you are done with the task queue, you should call
793 * XTaskQueueCloseHandle to reduce the reference count to avoid a resource
794 * leak.
795 *
796 * \param outTaskQueue a pointer to be filled in with task queue handle.
797 * \returns 0 on success or a negative error code on failure; call
798 * SDL_GetError() for more information.
799 *
800 * \since This function is available since SDL 3.0.0.
801 */
802extern SDL_DECLSPEC int SDLCALL SDL_GetGDKTaskQueue(XTaskQueueHandle *outTaskQueue);
803
804/**
805 * Gets a reference to the default user handle for GDK.
806 *
807 * This is effectively a synchronous version of XUserAddAsync, which always
808 * prefers the default user and allows a sign-in UI.
809 *
810 * \param outUserHandle a pointer to be filled in with the default user
811 * handle.
812 * \returns 0 if success or a negative error code on failure; call
813 * SDL_GetError() for more information.
814 *
815 * \since This function is available since SDL 3.0.0.
816 */
817extern SDL_DECLSPEC int SDLCALL SDL_GetGDKDefaultUser(XUserHandle *outUserHandle);
818
819#endif
820
821/* Ends C function definitions when using C++ */
822#ifdef __cplusplus
823}
824#endif
825#include <SDL3/SDL_close_code.h>
826
827#endif /* SDL_system_h_ */
int64_t Sint64
Definition SDL_stdinc.h:276
int SDL_bool
Definition SDL_stdinc.h:213
uint32_t Uint32
Definition SDL_stdinc.h:265
union _XEvent XEvent
Definition SDL_system.h:138
SDL_bool(* SDL_X11EventHook)(void *userdata, XEvent *xevent)
Definition SDL_system.h:139
SDL_bool SDL_IsTablet(void)
void SDL_OnApplicationWillEnterForeground(void)
void SDL_OnApplicationDidEnterForeground(void)
void SDL_OnApplicationDidEnterBackground(void)
void SDL_SetX11EventHook(SDL_X11EventHook callback, void *userdata)
void SDL_OnApplicationDidReceiveMemoryWarning(void)
void SDL_OnApplicationWillEnterBackground(void)
void SDL_OnApplicationWillTerminate(void)
Uint32 SDL_DisplayID
Definition SDL_video.h:45
struct SDL_Window SDL_Window
Definition SDL_video.h:127