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