SDL  2.0
SDL_system.h
Go to the documentation of this file.
1 /*
2  Simple DirectMedia Layer
3  Copyright (C) 1997-2020 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 /**
47  \brief Set a function that is called for every windows message, before TranslateMessage()
48 */
49 typedef void (SDLCALL * SDL_WindowsMessageHook)(void *userdata, void *hWnd, unsigned int message, Uint64 wParam, Sint64 lParam);
51 
52 /**
53  \brief Returns the D3D9 adapter index that matches the specified display index.
54 
55  This adapter index can be passed to IDirect3D9::CreateDevice and controls
56  on which monitor a full screen application will appear.
57 */
58 extern DECLSPEC int SDLCALL SDL_Direct3D9GetAdapterIndex( int displayIndex );
59 
60 typedef struct IDirect3DDevice9 IDirect3DDevice9;
61 /**
62  \brief Returns the D3D device associated with a renderer, or NULL if it's not a D3D renderer.
63 
64  Once you are done using the device, you should release it to avoid a resource leak.
65  */
67 
68 /**
69  \brief Returns the DXGI Adapter and Output indices for the specified display index.
70 
71  These can be passed to EnumAdapters and EnumOutputs respectively to get the objects
72  required to create a DX10 or DX11 device and swap chain.
73  */
74 extern DECLSPEC SDL_bool SDLCALL SDL_DXGIGetOutputInfo( int displayIndex, int *adapterIndex, int *outputIndex );
75 
76 #endif /* __WIN32__ */
77 
78 
79 /* Platform specific functions for Linux */
80 #ifdef __LINUX__
81 
82 /**
83  \brief Sets the UNIX nice value for a thread, using setpriority() if possible, and RealtimeKit if available.
84 
85  \return 0 on success, or -1 on error.
86  */
87 extern DECLSPEC int SDLCALL SDL_LinuxSetThreadPriority(Sint64 threadID, int priority);
88 
89 #endif /* __LINUX__ */
90 
91 /* Platform specific functions for iOS */
92 #ifdef __IPHONEOS__
93 
94 #define SDL_iOSSetAnimationCallback(window, interval, callback, callbackParam) SDL_iPhoneSetAnimationCallback(window, interval, callback, callbackParam)
95 extern DECLSPEC int SDLCALL SDL_iPhoneSetAnimationCallback(SDL_Window * window, int interval, void (*callback)(void*), void *callbackParam);
96 
97 #define SDL_iOSSetEventPump(enabled) SDL_iPhoneSetEventPump(enabled)
99 
100 #endif /* __IPHONEOS__ */
101 
102 
103 /* Platform specific functions for Android */
104 #ifdef __ANDROID__
105 
106 /**
107  \brief Get the JNI environment for the current thread
108 
109  This returns JNIEnv*, but the prototype is void* so we don't need jni.h
110  */
111 extern DECLSPEC void * SDLCALL SDL_AndroidGetJNIEnv(void);
112 
113 /**
114  \brief Get the SDL Activity object for the application
115 
116  This returns jobject, but the prototype is void* so we don't need jni.h
117  The jobject returned by SDL_AndroidGetActivity is a local reference.
118  It is the caller's responsibility to properly release it
119  (using env->Push/PopLocalFrame or manually with env->DeleteLocalRef)
120  */
121 extern DECLSPEC void * SDLCALL SDL_AndroidGetActivity(void);
122 
123 /**
124  \brief Return API level of the current device
125 
126  API level 29: Android 10
127  API level 28: Android 9
128  API level 27: Android 8.1
129  API level 26: Android 8.0
130  API level 25: Android 7.1
131  API level 24: Android 7.0
132  API level 23: Android 6.0
133  API level 22: Android 5.1
134  API level 21: Android 5.0
135  API level 20: Android 4.4W
136  API level 19: Android 4.4
137  API level 18: Android 4.3
138  API level 17: Android 4.2
139  API level 16: Android 4.1
140  API level 15: Android 4.0.3
141  API level 14: Android 4.0
142  API level 13: Android 3.2
143  API level 12: Android 3.1
144  API level 11: Android 3.0
145  API level 10: Android 2.3.3
146  */
147 extern DECLSPEC int SDLCALL SDL_GetAndroidSDKVersion(void);
148 
149 /**
150  \brief Return true if the application is running on Android TV
151  */
153 
154 /**
155  \brief Return true if the application is running on a Chromebook
156  */
158 
159 /**
160  \brief Return true is the application is running on a Samsung DeX docking station
161  */
163 
164 /**
165  \brief Trigger the Android system back button behavior.
166  */
167 extern DECLSPEC void SDLCALL SDL_AndroidBackButton(void);
168 
169 /**
170  See the official Android developer guide for more information:
171  http://developer.android.com/guide/topics/data/data-storage.html
172 */
173 #define SDL_ANDROID_EXTERNAL_STORAGE_READ 0x01
174 #define SDL_ANDROID_EXTERNAL_STORAGE_WRITE 0x02
175 
176 /**
177  \brief Get the path used for internal storage for this application.
178 
179  This path is unique to your application and cannot be written to
180  by other applications.
181  */
182 extern DECLSPEC const char * SDLCALL SDL_AndroidGetInternalStoragePath(void);
183 
184 /**
185  \brief Get the current state of external storage, a bitmask of these values:
186  SDL_ANDROID_EXTERNAL_STORAGE_READ
187  SDL_ANDROID_EXTERNAL_STORAGE_WRITE
188 
189  If external storage is currently unavailable, this will return 0.
190 */
192 
193 /**
194  \brief Get the path used for external storage for this application.
195 
196  This path is unique to your application, but is public and can be
197  written to by other applications.
198  */
199 extern DECLSPEC const char * SDLCALL SDL_AndroidGetExternalStoragePath(void);
200 
201 #endif /* __ANDROID__ */
202 
203 /* Platform specific functions for WinRT */
204 #ifdef __WINRT__
205 
206 /**
207  * \brief WinRT / Windows Phone path types
208  */
209 typedef enum
210 {
211  /** \brief The installed app's root directory.
212  Files here are likely to be read-only. */
213  SDL_WINRT_PATH_INSTALLED_LOCATION,
214 
215  /** \brief The app's local data store. Files may be written here */
216  SDL_WINRT_PATH_LOCAL_FOLDER,
217 
218  /** \brief The app's roaming data store. Unsupported on Windows Phone.
219  Files written here may be copied to other machines via a network
220  connection.
221  */
222  SDL_WINRT_PATH_ROAMING_FOLDER,
223 
224  /** \brief The app's temporary data store. Unsupported on Windows Phone.
225  Files written here may be deleted at any time. */
226  SDL_WINRT_PATH_TEMP_FOLDER
227 } SDL_WinRT_Path;
228 
229 
230 /**
231  * \brief WinRT Device Family
232  */
233 typedef enum
234 {
235  /** \brief Unknown family */
236  SDL_WINRT_DEVICEFAMILY_UNKNOWN,
237 
238  /** \brief Desktop family*/
239  SDL_WINRT_DEVICEFAMILY_DESKTOP,
240 
241  /** \brief Mobile family (for example smartphone) */
242  SDL_WINRT_DEVICEFAMILY_MOBILE,
243 
244  /** \brief XBox family */
245  SDL_WINRT_DEVICEFAMILY_XBOX,
246 } SDL_WinRT_DeviceFamily;
247 
248 
249 /**
250  * \brief Retrieves a WinRT defined path on the local file system
251  *
252  * \note Documentation on most app-specific path types on WinRT
253  * can be found on MSDN, at the URL:
254  * http://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx
255  *
256  * \param pathType The type of path to retrieve.
257  * \return A UCS-2 string (16-bit, wide-char) containing the path, or NULL
258  * if the path is not available for any reason. Not all paths are
259  * available on all versions of Windows. This is especially true on
260  * Windows Phone. Check the documentation for the given
261  * SDL_WinRT_Path for more information on which path types are
262  * supported where.
263  */
264 extern DECLSPEC const wchar_t * SDLCALL SDL_WinRTGetFSPathUNICODE(SDL_WinRT_Path pathType);
265 
266 /**
267  * \brief Retrieves a WinRT defined path on the local file system
268  *
269  * \note Documentation on most app-specific path types on WinRT
270  * can be found on MSDN, at the URL:
271  * http://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx
272  *
273  * \param pathType The type of path to retrieve.
274  * \return A UTF-8 string (8-bit, multi-byte) containing the path, or NULL
275  * if the path is not available for any reason. Not all paths are
276  * available on all versions of Windows. This is especially true on
277  * Windows Phone. Check the documentation for the given
278  * SDL_WinRT_Path for more information on which path types are
279  * supported where.
280  */
281 extern DECLSPEC const char * SDLCALL SDL_WinRTGetFSPathUTF8(SDL_WinRT_Path pathType);
282 
283 /**
284  * \brief Detects the device family of WinRT plattform on runtime
285  *
286  * \return Device family
287  */
288 extern DECLSPEC SDL_WinRT_DeviceFamily SDLCALL SDL_WinRTGetDeviceFamily();
289 
290 #endif /* __WINRT__ */
291 
292 /**
293  \brief Return true if the current device is a tablet.
294  */
296 
297 /* Functions used by iOS application delegates to notify SDL about state changes */
304 #ifdef __IPHONEOS__
306 #endif
307 
308 /* Ends C function definitions when using C++ */
309 #ifdef __cplusplus
310 }
311 #endif
312 #include "close_code.h"
313 
314 #endif /* SDL_system_h_ */
315 
316 /* vi: set ts=4 sw=4 expandtab: */
DECLSPEC
#define DECLSPEC
Definition: SDL_internal.h:48
SDL_OnApplicationDidReceiveMemoryWarning
void SDL_OnApplicationDidReceiveMemoryWarning(void)
Definition: SDL_dynapi_procs.h:799
Sint64
int64_t Sint64
Definition: SDL_stdinc.h:210
SDL_DXGIGetOutputInfo
SDL_bool SDL_DXGIGetOutputInfo(int displayIndex, int *adapterIndex, int *outputIndex)
Returns the DXGI Adapter and Output indices for the specified display index.
SDL_render.h
SDL_AndroidBackButton
#define SDL_AndroidBackButton
Definition: SDL_dynapi_overrides.h:677
SDL_OnApplicationDidEnterBackground
void SDL_OnApplicationDidEnterBackground(void)
Definition: SDL_dynapi_procs.h:801
message
GLuint GLsizei const GLchar * message
Definition: SDL_opengl_glext.h:2486
SDL_WindowsMessageHook
void(* SDL_WindowsMessageHook)(void *userdata, void *hWnd, unsigned int message, Uint64 wParam, Sint64 lParam)
Set a function that is called for every windows message, before TranslateMessage()
Definition: SDL_system.h:49
SDL_OnApplicationWillEnterForeground
void SDL_OnApplicationWillEnterForeground(void)
Definition: SDL_video.c:4087
SDLCALL
#define SDLCALL
Definition: SDL_internal.h:49
SDL_keyboard.h
SDL_AndroidGetExternalStoragePath
#define SDL_AndroidGetExternalStoragePath
Definition: SDL_dynapi_overrides.h:53
callback
static Uint32 callback(Uint32 interval, void *param)
Definition: testtimer.c:34
IDirect3DDevice9
struct IDirect3DDevice9 IDirect3DDevice9
Definition: SDL_system.h:60
close_code.h
SDL_Window
The type used to identify a window.
Definition: SDL_sysvideo.h:75
begin_code.h
SDL_LinuxSetThreadPriority
#define SDL_LinuxSetThreadPriority
Definition: SDL_dynapi_overrides.h:673
SDL_Renderer
Definition: SDL_sysrender.h:110
window
EGLSurface EGLNativeWindowType * window
Definition: eglext.h:1025
SDL_IsAndroidTV
SDL_bool SDL_IsAndroidTV(void)
SDL_WinRTGetDeviceFamily
SDL_WinRT_DeviceFamily SDL_WinRTGetDeviceFamily()
Definition: SDL_winrtapp_common.cpp:47
SDL_IsChromebook
SDL_bool SDL_IsChromebook(void)
SDL_Direct3D9GetAdapterIndex
int SDL_Direct3D9GetAdapterIndex(int displayIndex)
Returns the D3D9 adapter index that matches the specified display index.
SDL_Surface::userdata
void * userdata
Definition: SDL_surface.h:79
SDL_GetAndroidSDKVersion
int SDL_GetAndroidSDKVersion(void)
SDL_OnApplicationWillTerminate
void SDL_OnApplicationWillTerminate(void)
Definition: SDL_video.c:4060
SDL_AndroidGetActivity
#define SDL_AndroidGetActivity
Definition: SDL_dynapi_overrides.h:50
SDL_OnApplicationWillResignActive
void SDL_OnApplicationWillResignActive(void)
Definition: SDL_video.c:4070
SDL_IsDeXMode
SDL_bool SDL_IsDeXMode(void)
renderer
static SDL_Renderer * renderer
Definition: testaudiocapture.c:21
Uint64
uint64_t Uint64
Definition: SDL_stdinc.h:216
SDL_SetWindowsMessageHook
void SDL_SetWindowsMessageHook(SDL_WindowsMessageHook callback, void *userdata)
SDL_stdinc.h
SDL_RenderGetD3D9Device
IDirect3DDevice9 * SDL_RenderGetD3D9Device(SDL_Renderer *renderer)
Returns the D3D device associated with a renderer, or NULL if it's not a D3D renderer.
SDL_AndroidGetJNIEnv
#define SDL_AndroidGetJNIEnv
Definition: SDL_dynapi_overrides.h:49
enabled
GLenum GLenum GLsizei const GLuint GLboolean enabled
Definition: SDL_opengl_glext.h:2482
SDL_bool
SDL_bool
Definition: SDL_stdinc.h:162
SDL_WinRTGetFSPathUTF8
#define SDL_WinRTGetFSPathUTF8
Definition: SDL_dynapi_overrides.h:579
SDL_OnApplicationDidChangeStatusBarOrientation
#define SDL_OnApplicationDidChangeStatusBarOrientation
Definition: SDL_dynapi_overrides.h:748
SDL_video.h
SDL_AndroidGetExternalStorageState
#define SDL_AndroidGetExternalStorageState
Definition: SDL_dynapi_overrides.h:52
SDL_iPhoneSetEventPump
#define SDL_iPhoneSetEventPump
Definition: SDL_dynapi_overrides.h:48
SDL_OnApplicationDidBecomeActive
void SDL_OnApplicationDidBecomeActive(void)
Definition: SDL_dynapi_procs.h:803
void
SDL_PRINTF_FORMAT_STRING const char int SDL_PRINTF_FORMAT_STRING const char int SDL_PRINTF_FORMAT_STRING const char int SDL_PRINTF_FORMAT_STRING const char const char SDL_SCANF_FORMAT_STRING const char return SDL_ThreadFunction const char void return Uint32 return Uint32 void
Definition: SDL_dynapi_procs.h:89
SDL_iPhoneSetAnimationCallback
#define SDL_iPhoneSetAnimationCallback
Definition: SDL_dynapi_overrides.h:47
SDL_WinRTGetFSPathUNICODE
#define SDL_WinRTGetFSPathUNICODE
Definition: SDL_dynapi_overrides.h:578
SDL_AndroidGetInternalStoragePath
#define SDL_AndroidGetInternalStoragePath
Definition: SDL_dynapi_overrides.h:51
SDL_IsTablet
SDL_bool SDL_IsTablet(void)
Return true if the current device is a tablet.
Definition: SDL.c:519