SDL  2.0
SDL_system.h
Go to the documentation of this file.
1 /*
2  Simple DirectMedia Layer
3  Copyright (C) 1997-2021 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  * \file SDL_system.h
24  *
25  * Include file for platform specific SDL API functions
26  */
27 
28 #ifndef SDL_system_h_
29 #define SDL_system_h_
30 
31 #include "SDL_stdinc.h"
32 #include "SDL_keyboard.h"
33 #include "SDL_render.h"
34 #include "SDL_video.h"
35 
36 #include "begin_code.h"
37 /* Set up for C function definitions, even when using C++ */
38 #ifdef __cplusplus
39 extern "C" {
40 #endif
41 
42 
43 /* Platform specific functions for Windows */
44 #ifdef __WIN32__
45 
46 typedef void (SDLCALL * SDL_WindowsMessageHook)(void *userdata, void *hWnd, unsigned int message, Uint64 wParam, Sint64 lParam);
47 
48 /**
49  * Set a callback for every Windows message, run before TranslateMessage().
50  *
51  * \param callback The SDL_WindowsMessageHook function to call.
52  * \param userdata a pointer to pass to every iteration of `callback`
53  *
54  * \since This function is available since SDL 2.0.4.
55  */
56 extern DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHook callback, void *userdata);
57 
58 /**
59  * Get the D3D9 adapter index that matches the specified display index.
60  *
61  * The returned adapter index can be passed to `IDirect3D9::CreateDevice` and
62  * controls on which monitor a full screen application will appear.
63  *
64  * \param displayIndex the display index for which to get the D3D9 adapter
65  * index
66  * \returns the D3D9 adapter index on success or a negative error code on
67  * failure; call SDL_GetError() for more information.
68  *
69  * \since This function is available since SDL 2.0.1.
70  */
71 extern DECLSPEC int SDLCALL SDL_Direct3D9GetAdapterIndex( int displayIndex );
72 
73 typedef struct IDirect3DDevice9 IDirect3DDevice9;
74 
75 /**
76  * Get the D3D9 device associated with a renderer.
77  *
78  * Once you are done using the device, you should release it to avoid a
79  * resource leak.
80  *
81  * \param renderer the renderer from which to get the associated D3D device
82  * \returns the D3D9 device associated with given renderer or NULL if it is
83  * not a D3D9 renderer; call SDL_GetError() for more information.
84  *
85  * \since This function is available since SDL 2.0.1.
86  */
87 extern DECLSPEC IDirect3DDevice9* SDLCALL SDL_RenderGetD3D9Device(SDL_Renderer * renderer);
88 
89 typedef struct ID3D11Device ID3D11Device;
90 
91 /**
92  * Get the D3D11 device associated with a renderer.
93  *
94  * Once you are done using the device, you should release it to avoid a
95  * resource leak.
96  *
97  * \param renderer the renderer from which to get the associated D3D11 device
98  * \returns the D3D11 device associated with given renderer or NULL if it is
99  * not a D3D11 renderer; call SDL_GetError() for more information.
100  *
101  * \since This function is available since SDL 2.0.16.
102  */
103 extern DECLSPEC ID3D11Device* SDLCALL SDL_RenderGetD3D11Device(SDL_Renderer * renderer);
104 
105 /**
106  * Get the DXGI Adapter and Output indices for the specified display index.
107  *
108  * The DXGI Adapter and Output indices can be passed to `EnumAdapters` and
109  * `EnumOutputs` respectively to get the objects required to create a DX10 or
110  * DX11 device and swap chain.
111  *
112  * Before SDL 2.0.4 this function did not return a value. Since SDL 2.0.4 it
113  * returns an SDL_bool.
114  *
115  * \param displayIndex the display index for which to get both indices
116  * \param adapterIndex a pointer to be filled in with the adapter index
117  * \param outputIndex a pointer to be filled in with the output index
118  * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
119  * for more information.
120  *
121  * \since This function is available since SDL 2.0.2.
122  */
123 extern DECLSPEC SDL_bool SDLCALL SDL_DXGIGetOutputInfo( int displayIndex, int *adapterIndex, int *outputIndex );
124 
125 #endif /* __WIN32__ */
126 
127 
128 /* Platform specific functions for Linux */
129 #ifdef __LINUX__
130 
131 /**
132  * Sets the UNIX nice value for a thread.
133  *
134  * This uses setpriority() if possible, and RealtimeKit if available.
135  *
136  * \param threadID the Unix thread ID to change priority of.
137  * \param priority The new, Unix-specific, priority value.
138  * \returns 0 on success, or -1 on error.
139  *
140  * \since This function is available since SDL 2.0.9.
141  */
142 extern DECLSPEC int SDLCALL SDL_LinuxSetThreadPriority(Sint64 threadID, int priority);
143 
144 /**
145  * Sets the priority (not nice level) and scheduling policy for a thread.
146  *
147  * This uses setpriority() if possible, and RealtimeKit if available.
148  *
149  * \param threadID The Unix thread ID to change priority of.
150  * \param sdlPriority The new SDL_ThreadPriority value.
151  * \param schedPolicy The new scheduling policy (SCHED_FIFO, SCHED_RR,
152  * SCHED_OTHER, etc...)
153  * \returns 0 on success, or -1 on error.
154  *
155  * \since This function is available since SDL 2.0.18.
156  */
157 extern DECLSPEC int SDLCALL SDL_LinuxSetThreadPriorityAndPolicy(Sint64 threadID, int sdlPriority, int schedPolicy);
158 
159 #endif /* __LINUX__ */
160 
161 /* Platform specific functions for iOS */
162 #ifdef __IPHONEOS__
163 
164 #define SDL_iOSSetAnimationCallback(window, interval, callback, callbackParam) SDL_iPhoneSetAnimationCallback(window, interval, callback, callbackParam)
165 
166 /**
167  * Use this function to set the animation callback on Apple iOS.
168  *
169  * The function prototype for `callback` is:
170  *
171  * ```c
172  * void callback(void* callbackParam);
173  * ```
174  *
175  * Where its parameter, `callbackParam`, is what was passed as `callbackParam`
176  * to SDL_iPhoneSetAnimationCallback().
177  *
178  * This function is only available on Apple iOS.
179  *
180  * For more information see:
181  * [README-ios.md](https://hg.libsdl.org/SDL/file/default/docs/README-ios.md)
182  *
183  * This functions is also accessible using the macro
184  * SDL_iOSSetAnimationCallback() since SDL 2.0.4.
185  *
186  * \param window the window for which the animation callback should be set
187  * \param interval the number of frames after which **callback** will be
188  * called
189  * \param callback the function to call for every frame.
190  * \param callbackParam a pointer that is passed to `callback`.
191  * \returns 0 on success or a negative error code on failure; call
192  * SDL_GetError() for more information.
193  *
194  * \since This function is available since SDL 2.0.0.
195  *
196  * \sa SDL_iPhoneSetEventPump
197  */
198 extern DECLSPEC int SDLCALL SDL_iPhoneSetAnimationCallback(SDL_Window * window, int interval, void (*callback)(void*), void *callbackParam);
199 
200 #define SDL_iOSSetEventPump(enabled) SDL_iPhoneSetEventPump(enabled)
201 
202 /**
203  * Use this function to enable or disable the SDL event pump on Apple iOS.
204  *
205  * This function is only available on Apple iOS.
206  *
207  * This functions is also accessible using the macro SDL_iOSSetEventPump()
208  * since SDL 2.0.4.
209  *
210  * \param enabled SDL_TRUE to enable the event pump, SDL_FALSE to disable it
211  *
212  * \since This function is available since SDL 2.0.0.
213  *
214  * \sa SDL_iPhoneSetAnimationCallback
215  */
216 extern DECLSPEC void SDLCALL SDL_iPhoneSetEventPump(SDL_bool enabled);
217 
218 #endif /* __IPHONEOS__ */
219 
220 
221 /* Platform specific functions for Android */
222 #ifdef __ANDROID__
223 
224 /**
225  * Get the Android Java Native Interface Environment of the current thread.
226  *
227  * This is the JNIEnv one needs to access the Java virtual machine from native
228  * code, and is needed for many Android APIs to be usable from C.
229  *
230  * The prototype of the function in SDL's code actually declare a void* return
231  * type, even if the implementation returns a pointer to a JNIEnv. The
232  * rationale being that the SDL headers can avoid including jni.h.
233  *
234  * \returns a pointer to Java native interface object (JNIEnv) to which the
235  * current thread is attached, or 0 on error.
236  *
237  * \since This function is available since SDL 2.0.0.
238  *
239  * \sa SDL_AndroidGetActivity
240  */
241 extern DECLSPEC void * SDLCALL SDL_AndroidGetJNIEnv(void);
242 
243 /**
244  * Retrieve the Java instance of the Android activity class.
245  *
246  * The prototype of the function in SDL's code actually declares a void*
247  * return type, even if the implementation returns a jobject. The rationale
248  * being that the SDL headers can avoid including jni.h.
249  *
250  * The jobject returned by the function is a local reference and must be
251  * released by the caller. See the PushLocalFrame() and PopLocalFrame() or
252  * DeleteLocalRef() functions of the Java native interface:
253  *
254  * https://docs.oracle.com/javase/1.5.0/docs/guide/jni/spec/functions.html
255  *
256  * \returns the jobject representing the instance of the Activity class of the
257  * Android application, or NULL on error.
258  *
259  * \since This function is available since SDL 2.0.0.
260  *
261  * \sa SDL_AndroidGetJNIEnv
262  */
263 extern DECLSPEC void * SDLCALL SDL_AndroidGetActivity(void);
264 
265 /**
266  * Query Android API level of the current device.
267  *
268  * - API level 31: Android 12
269  * - API level 30: Android 11
270  * - API level 29: Android 10
271  * - API level 28: Android 9
272  * - API level 27: Android 8.1
273  * - API level 26: Android 8.0
274  * - API level 25: Android 7.1
275  * - API level 24: Android 7.0
276  * - API level 23: Android 6.0
277  * - API level 22: Android 5.1
278  * - API level 21: Android 5.0
279  * - API level 20: Android 4.4W
280  * - API level 19: Android 4.4
281  * - API level 18: Android 4.3
282  * - API level 17: Android 4.2
283  * - API level 16: Android 4.1
284  * - API level 15: Android 4.0.3
285  * - API level 14: Android 4.0
286  * - API level 13: Android 3.2
287  * - API level 12: Android 3.1
288  * - API level 11: Android 3.0
289  * - API level 10: Android 2.3.3
290  *
291  * \returns the Android API level.
292  *
293  * \since This function is available since SDL 2.0.12.
294  */
295 extern DECLSPEC int SDLCALL SDL_GetAndroidSDKVersion(void);
296 
297 /**
298  * Query if the application is running on Android TV.
299  *
300  * \returns SDL_TRUE if this is Android TV, SDL_FALSE otherwise.
301  *
302  * \since This function is available since SDL 2.0.8.
303  */
304 extern DECLSPEC SDL_bool SDLCALL SDL_IsAndroidTV(void);
305 
306 /**
307  * Query if the application is running on a Chromebook.
308  *
309  * \returns SDL_TRUE if this is a Chromebook, SDL_FALSE otherwise.
310  *
311  * \since This function is available since SDL 2.0.9.
312  */
313 extern DECLSPEC SDL_bool SDLCALL SDL_IsChromebook(void);
314 
315 /**
316  * Query if the application is running on a Samsung DeX docking station.
317  *
318  * \returns SDL_TRUE if this is a DeX docking station, SDL_FALSE otherwise.
319  *
320  * \since This function is available since SDL 2.0.9.
321  */
322 extern DECLSPEC SDL_bool SDLCALL SDL_IsDeXMode(void);
323 
324 /**
325  * Trigger the Android system back button behavior.
326  *
327  * \since This function is available since SDL 2.0.9.
328  */
329 extern DECLSPEC void SDLCALL SDL_AndroidBackButton(void);
330 
331 /**
332  See the official Android developer guide for more information:
333  http://developer.android.com/guide/topics/data/data-storage.html
334 */
335 #define SDL_ANDROID_EXTERNAL_STORAGE_READ 0x01
336 #define SDL_ANDROID_EXTERNAL_STORAGE_WRITE 0x02
337 
338 /**
339  * Get the path used for internal storage for this application.
340  *
341  * This path is unique to your application and cannot be written to by other
342  * applications.
343  *
344  * Your internal storage path is typically:
345  * `/data/data/your.app.package/files`.
346  *
347  * \returns the path used for internal storage or NULL on failure; call
348  * SDL_GetError() for more information.
349  *
350  * \since This function is available since SDL 2.0.0.
351  *
352  * \sa SDL_AndroidGetExternalStorageState
353  */
354 extern DECLSPEC const char * SDLCALL SDL_AndroidGetInternalStoragePath(void);
355 
356 /**
357  * Get the current state of external storage.
358  *
359  * The current state of external storage, a bitmask of these values:
360  * `SDL_ANDROID_EXTERNAL_STORAGE_READ`, `SDL_ANDROID_EXTERNAL_STORAGE_WRITE`.
361  *
362  * If external storage is currently unavailable, this will return 0.
363  *
364  * \returns the current state of external storage on success or 0 on failure;
365  * call SDL_GetError() for more information.
366  *
367  * \since This function is available since SDL 2.0.0.
368  *
369  * \sa SDL_AndroidGetExternalStoragePath
370  */
371 extern DECLSPEC int SDLCALL SDL_AndroidGetExternalStorageState(void);
372 
373 /**
374  * Get the path used for external storage for this application.
375  *
376  * This path is unique to your application, but is public and can be written
377  * to by other applications.
378  *
379  * Your external storage path is typically:
380  * `/storage/sdcard0/Android/data/your.app.package/files`.
381  *
382  * \returns the path used for external storage for this application on success
383  * or NULL on failure; call SDL_GetError() for more information.
384  *
385  * \since This function is available since SDL 2.0.0.
386  *
387  * \sa SDL_AndroidGetExternalStorageState
388  */
389 extern DECLSPEC const char * SDLCALL SDL_AndroidGetExternalStoragePath(void);
390 
391 /**
392  * Request permissions at runtime.
393  *
394  * This blocks the calling thread until the permission is granted or denied.
395  *
396  * \param permission The permission to request.
397  * \returns SDL_TRUE if the permission was granted, SDL_FALSE otherwise.
398  *
399  * \since This function is available since SDL 2.0.14.
400  */
401 extern DECLSPEC SDL_bool SDLCALL SDL_AndroidRequestPermission(const char *permission);
402 
403 /**
404  * Shows an Android toast notification.
405  *
406  * Toasts are a sort of lightweight notification that are unique to Android.
407  *
408  * https://developer.android.com/guide/topics/ui/notifiers/toasts
409  *
410  * Shows toast in UI thread.
411  *
412  * For the `gravity` parameter, choose a value from here, or -1 if you don't
413  * have a preference:
414  *
415  * https://developer.android.com/reference/android/view/Gravity
416  *
417  * \param message text message to be shown
418  * \param duration 0=short, 1=long
419  * \param gravity where the notification should appear on the screen.
420  * \param xoffset set this parameter only when gravity >=0
421  * \param yoffset set this parameter only when gravity >=0
422  * \returns 0 if success, -1 if any error occurs.
423  *
424  * \since This function is available since SDL 2.0.16.
425  */
426 extern DECLSPEC int SDLCALL SDL_AndroidShowToast(const char* message, int duration, int gravity, int xoffset, int yoffset);
427 
428 #endif /* __ANDROID__ */
429 
430 /* Platform specific functions for WinRT */
431 #ifdef __WINRT__
432 
433 /**
434  * \brief WinRT / Windows Phone path types
435  */
436 typedef enum
437 {
438  /** \brief The installed app's root directory.
439  Files here are likely to be read-only. */
440  SDL_WINRT_PATH_INSTALLED_LOCATION,
441 
442  /** \brief The app's local data store. Files may be written here */
443  SDL_WINRT_PATH_LOCAL_FOLDER,
444 
445  /** \brief The app's roaming data store. Unsupported on Windows Phone.
446  Files written here may be copied to other machines via a network
447  connection.
448  */
449  SDL_WINRT_PATH_ROAMING_FOLDER,
450 
451  /** \brief The app's temporary data store. Unsupported on Windows Phone.
452  Files written here may be deleted at any time. */
453  SDL_WINRT_PATH_TEMP_FOLDER
454 } SDL_WinRT_Path;
455 
456 
457 /**
458  * \brief WinRT Device Family
459  */
460 typedef enum
461 {
462  /** \brief Unknown family */
463  SDL_WINRT_DEVICEFAMILY_UNKNOWN,
464 
465  /** \brief Desktop family*/
466  SDL_WINRT_DEVICEFAMILY_DESKTOP,
467 
468  /** \brief Mobile family (for example smartphone) */
469  SDL_WINRT_DEVICEFAMILY_MOBILE,
470 
471  /** \brief XBox family */
472  SDL_WINRT_DEVICEFAMILY_XBOX,
473 } SDL_WinRT_DeviceFamily;
474 
475 
476 /**
477  * Retrieve a WinRT defined path on the local file system.
478  *
479  * Not all paths are available on all versions of Windows. This is especially
480  * true on Windows Phone. Check the documentation for the given SDL_WinRT_Path
481  * for more information on which path types are supported where.
482  *
483  * Documentation on most app-specific path types on WinRT can be found on
484  * MSDN, at the URL:
485  *
486  * https://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx
487  *
488  * \param pathType the type of path to retrieve, one of SDL_WinRT_Path
489  * \returns a UCS-2 string (16-bit, wide-char) containing the path, or NULL if
490  * the path is not available for any reason; call SDL_GetError() for
491  * more information.
492  *
493  * \since This function is available since SDL 2.0.3.
494  *
495  * \sa SDL_WinRTGetFSPathUTF8
496  */
497 extern DECLSPEC const wchar_t * SDLCALL SDL_WinRTGetFSPathUNICODE(SDL_WinRT_Path pathType);
498 
499 /**
500  * Retrieve a WinRT defined path on the local file system.
501  *
502  * Not all paths are available on all versions of Windows. This is especially
503  * true on Windows Phone. Check the documentation for the given SDL_WinRT_Path
504  * for more information on which path types are supported where.
505  *
506  * Documentation on most app-specific path types on WinRT can be found on
507  * MSDN, at the URL:
508  *
509  * https://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx
510  *
511  * \param pathType the type of path to retrieve, one of SDL_WinRT_Path
512  * \returns a UTF-8 string (8-bit, multi-byte) containing the path, or NULL if
513  * the path is not available for any reason; call SDL_GetError() for
514  * more information.
515  *
516  * \since This function is available since SDL 2.0.3.
517  *
518  * \sa SDL_WinRTGetFSPathUNICODE
519  */
520 extern DECLSPEC const char * SDLCALL SDL_WinRTGetFSPathUTF8(SDL_WinRT_Path pathType);
521 
522 /**
523  * Detects the device family of WinRT plattform at runtime.
524  *
525  * \returns a value from the SDL_WinRT_DeviceFamily enum.
526  *
527  * \since This function is available since SDL 2.0.8.
528  */
529 extern DECLSPEC SDL_WinRT_DeviceFamily SDLCALL SDL_WinRTGetDeviceFamily();
530 
531 #endif /* __WINRT__ */
532 
533 /**
534  * Query if the current device is a tablet.
535  *
536  * If SDL can't determine this, it will return SDL_FALSE.
537  *
538  * \returns SDL_TRUE if the device is a tablet, SDL_FALSE otherwise.
539  *
540  * \since This function is available since SDL 2.0.9.
541  */
542 extern DECLSPEC SDL_bool SDLCALL SDL_IsTablet(void);
543 
544 /* Functions used by iOS application delegates to notify SDL about state changes */
545 extern DECLSPEC void SDLCALL SDL_OnApplicationWillTerminate(void);
546 extern DECLSPEC void SDLCALL SDL_OnApplicationDidReceiveMemoryWarning(void);
547 extern DECLSPEC void SDLCALL SDL_OnApplicationWillResignActive(void);
548 extern DECLSPEC void SDLCALL SDL_OnApplicationDidEnterBackground(void);
549 extern DECLSPEC void SDLCALL SDL_OnApplicationWillEnterForeground(void);
550 extern DECLSPEC void SDLCALL SDL_OnApplicationDidBecomeActive(void);
551 #ifdef __IPHONEOS__
552 extern DECLSPEC void SDLCALL SDL_OnApplicationDidChangeStatusBarOrientation(void);
553 #endif
554 
555 /* Ends C function definitions when using C++ */
556 #ifdef __cplusplus
557 }
558 #endif
559 #include "close_code.h"
560 
561 #endif /* SDL_system_h_ */
562 
563 /* vi: set ts=4 sw=4 expandtab: */
struct SDL_Renderer SDL_Renderer
Definition: SDL_render.h:142
int64_t Sint64
Definition: SDL_stdinc.h:227
SDL_bool
Definition: SDL_stdinc.h:179
uint64_t Uint64
Definition: SDL_stdinc.h:233
SDL_bool SDL_IsTablet(void)
void SDL_OnApplicationWillEnterForeground(void)
int SDL_Direct3D9GetAdapterIndex(int displayIndex)
SDL_bool SDL_DXGIGetOutputInfo(int displayIndex, int *adapterIndex, int *outputIndex)
void(* SDL_WindowsMessageHook)(void *userdata, void *hWnd, unsigned int message, Uint64 wParam, Sint64 lParam)
Definition: SDL_system.h:46
void SDL_OnApplicationDidBecomeActive(void)
struct IDirect3DDevice9 IDirect3DDevice9
Definition: SDL_system.h:73
struct ID3D11Device ID3D11Device
Definition: SDL_system.h:89
void SDL_OnApplicationDidEnterBackground(void)
IDirect3DDevice9 * SDL_RenderGetD3D9Device(SDL_Renderer *renderer)
void SDL_SetWindowsMessageHook(SDL_WindowsMessageHook callback, void *userdata)
ID3D11Device * SDL_RenderGetD3D11Device(SDL_Renderer *renderer)
void SDL_OnApplicationDidReceiveMemoryWarning(void)
void SDL_OnApplicationWillResignActive(void)
void SDL_OnApplicationWillTerminate(void)
struct SDL_Window SDL_Window
The type used to identify a window.
Definition: SDL_video.h:95