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