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);
50 extern DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHook callback, void *userdata);
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 
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  */
66 extern DECLSPEC IDirect3DDevice9* SDLCALL SDL_RenderGetD3D9Device(SDL_Renderer * renderer);
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)
98 extern DECLSPEC void SDLCALL SDL_iPhoneSetEventPump(SDL_bool 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 30: Android 11
127  API level 29: Android 10
128  API level 28: Android 9
129  API level 27: Android 8.1
130  API level 26: Android 8.0
131  API level 25: Android 7.1
132  API level 24: Android 7.0
133  API level 23: Android 6.0
134  API level 22: Android 5.1
135  API level 21: Android 5.0
136  API level 20: Android 4.4W
137  API level 19: Android 4.4
138  API level 18: Android 4.3
139  API level 17: Android 4.2
140  API level 16: Android 4.1
141  API level 15: Android 4.0.3
142  API level 14: Android 4.0
143  API level 13: Android 3.2
144  API level 12: Android 3.1
145  API level 11: Android 3.0
146  API level 10: Android 2.3.3
147  */
148 extern DECLSPEC int SDLCALL SDL_GetAndroidSDKVersion(void);
149 
150 /**
151  \brief Return true if the application is running on Android TV
152  */
153 extern DECLSPEC SDL_bool SDLCALL SDL_IsAndroidTV(void);
154 
155 /**
156  \brief Return true if the application is running on a Chromebook
157  */
158 extern DECLSPEC SDL_bool SDLCALL SDL_IsChromebook(void);
159 
160 /**
161  \brief Return true is the application is running on a Samsung DeX docking station
162  */
163 extern DECLSPEC SDL_bool SDLCALL SDL_IsDeXMode(void);
164 
165 /**
166  \brief Trigger the Android system back button behavior.
167  */
168 extern DECLSPEC void SDLCALL SDL_AndroidBackButton(void);
169 
170 /**
171  See the official Android developer guide for more information:
172  http://developer.android.com/guide/topics/data/data-storage.html
173 */
174 #define SDL_ANDROID_EXTERNAL_STORAGE_READ 0x01
175 #define SDL_ANDROID_EXTERNAL_STORAGE_WRITE 0x02
176 
177 /**
178  \brief Get the path used for internal storage for this application.
179 
180  This path is unique to your application and cannot be written to
181  by other applications.
182  */
183 extern DECLSPEC const char * SDLCALL SDL_AndroidGetInternalStoragePath(void);
184 
185 /**
186  \brief Get the current state of external storage, a bitmask of these values:
187  SDL_ANDROID_EXTERNAL_STORAGE_READ
188  SDL_ANDROID_EXTERNAL_STORAGE_WRITE
189 
190  If external storage is currently unavailable, this will return 0.
191 */
192 extern DECLSPEC int SDLCALL SDL_AndroidGetExternalStorageState(void);
193 
194 /**
195  \brief Get the path used for external storage for this application.
196 
197  This path is unique to your application, but is public and can be
198  written to by other applications.
199  */
200 extern DECLSPEC const char * SDLCALL SDL_AndroidGetExternalStoragePath(void);
201 
202 /**
203  \brief Request permissions at runtime.
204 
205  This blocks the calling thread until the permission is granted or
206  denied. Returns SDL_TRUE if the permission was granted.
207  */
208 extern DECLSPEC SDL_bool SDLCALL SDL_AndroidRequestPermission(const char *permission);
209 
210 #endif /* __ANDROID__ */
211 
212 /* Platform specific functions for WinRT */
213 #ifdef __WINRT__
214 
215 /**
216  * \brief WinRT / Windows Phone path types
217  */
218 typedef enum
219 {
220  /** \brief The installed app's root directory.
221  Files here are likely to be read-only. */
222  SDL_WINRT_PATH_INSTALLED_LOCATION,
223 
224  /** \brief The app's local data store. Files may be written here */
225  SDL_WINRT_PATH_LOCAL_FOLDER,
226 
227  /** \brief The app's roaming data store. Unsupported on Windows Phone.
228  Files written here may be copied to other machines via a network
229  connection.
230  */
231  SDL_WINRT_PATH_ROAMING_FOLDER,
232 
233  /** \brief The app's temporary data store. Unsupported on Windows Phone.
234  Files written here may be deleted at any time. */
235  SDL_WINRT_PATH_TEMP_FOLDER
236 } SDL_WinRT_Path;
237 
238 
239 /**
240  * \brief WinRT Device Family
241  */
242 typedef enum
243 {
244  /** \brief Unknown family */
245  SDL_WINRT_DEVICEFAMILY_UNKNOWN,
246 
247  /** \brief Desktop family*/
248  SDL_WINRT_DEVICEFAMILY_DESKTOP,
249 
250  /** \brief Mobile family (for example smartphone) */
251  SDL_WINRT_DEVICEFAMILY_MOBILE,
252 
253  /** \brief XBox family */
254  SDL_WINRT_DEVICEFAMILY_XBOX,
255 } SDL_WinRT_DeviceFamily;
256 
257 
258 /**
259  * \brief Retrieves a WinRT defined path on the local file system
260  *
261  * \note Documentation on most app-specific path types on WinRT
262  * can be found on MSDN, at the URL:
263  * http://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx
264  *
265  * \param pathType The type of path to retrieve.
266  * \return A UCS-2 string (16-bit, wide-char) containing the path, or NULL
267  * if the path is not available for any reason. Not all paths are
268  * available on all versions of Windows. This is especially true on
269  * Windows Phone. Check the documentation for the given
270  * SDL_WinRT_Path for more information on which path types are
271  * supported where.
272  */
273 extern DECLSPEC const wchar_t * SDLCALL SDL_WinRTGetFSPathUNICODE(SDL_WinRT_Path pathType);
274 
275 /**
276  * \brief Retrieves a WinRT defined path on the local file system
277  *
278  * \note Documentation on most app-specific path types on WinRT
279  * can be found on MSDN, at the URL:
280  * http://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx
281  *
282  * \param pathType The type of path to retrieve.
283  * \return A UTF-8 string (8-bit, multi-byte) containing the path, or NULL
284  * if the path is not available for any reason. Not all paths are
285  * available on all versions of Windows. This is especially true on
286  * Windows Phone. Check the documentation for the given
287  * SDL_WinRT_Path for more information on which path types are
288  * supported where.
289  */
290 extern DECLSPEC const char * SDLCALL SDL_WinRTGetFSPathUTF8(SDL_WinRT_Path pathType);
291 
292 /**
293  * \brief Detects the device family of WinRT plattform on runtime
294  *
295  * \return Device family
296  */
297 extern DECLSPEC SDL_WinRT_DeviceFamily SDLCALL SDL_WinRTGetDeviceFamily();
298 
299 #endif /* __WINRT__ */
300 
301 /**
302  \brief Return true if the current device is a tablet.
303  */
304 extern DECLSPEC SDL_bool SDLCALL SDL_IsTablet(void);
305 
306 /* Functions used by iOS application delegates to notify SDL about state changes */
307 extern DECLSPEC void SDLCALL SDL_OnApplicationWillTerminate(void);
308 extern DECLSPEC void SDLCALL SDL_OnApplicationDidReceiveMemoryWarning(void);
309 extern DECLSPEC void SDLCALL SDL_OnApplicationWillResignActive(void);
310 extern DECLSPEC void SDLCALL SDL_OnApplicationDidEnterBackground(void);
311 extern DECLSPEC void SDLCALL SDL_OnApplicationWillEnterForeground(void);
312 extern DECLSPEC void SDLCALL SDL_OnApplicationDidBecomeActive(void);
313 #ifdef __IPHONEOS__
314 extern DECLSPEC void SDLCALL SDL_OnApplicationDidChangeStatusBarOrientation(void);
315 #endif
316 
317 /* Ends C function definitions when using C++ */
318 #ifdef __cplusplus
319 }
320 #endif
321 #include "close_code.h"
322 
323 #endif /* SDL_system_h_ */
324 
325 /* vi: set ts=4 sw=4 expandtab: */
void SDL_OnApplicationWillEnterForeground(void)
void SDL_OnApplicationWillResignActive(void)
SDL_bool SDL_DXGIGetOutputInfo(int displayIndex, int *adapterIndex, int *outputIndex)
Returns the DXGI Adapter and Output indices for the specified display index.
void SDL_OnApplicationWillTerminate(void)
SDL_bool
Definition: SDL_stdinc.h:167
void SDL_OnApplicationDidEnterBackground(void)
uint64_t Uint64
Definition: SDL_stdinc.h:222
int SDL_Direct3D9GetAdapterIndex(int displayIndex)
Returns the D3D9 adapter index that matches the specified display index.
struct SDL_Renderer SDL_Renderer
Definition: SDL_render.h:132
SDL_bool SDL_IsTablet(void)
Return true if the current device is a tablet.
void SDL_OnApplicationDidBecomeActive(void)
struct SDL_Window SDL_Window
The type used to identify a window.
Definition: SDL_video.h:90
void SDL_OnApplicationDidReceiveMemoryWarning(void)
int64_t Sint64
Definition: SDL_stdinc.h:216
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
void SDL_SetWindowsMessageHook(SDL_WindowsMessageHook callback, void *userdata)
void * userdata
Definition: SDL_surface.h:79
IDirect3DDevice9 * SDL_RenderGetD3D9Device(SDL_Renderer *renderer)
Returns the D3D device associated with a renderer, or NULL if it&#39;s not a D3D renderer.
struct IDirect3DDevice9 IDirect3DDevice9
Definition: SDL_system.h:60