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