|
1
|
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 * Platform-specific SDL API functions. These are functions that deal with
|
|
|
26 * needs of specific operating systems, that didn't make sense to offer as
|
|
|
27 * platform-independent, generic APIs.
|
|
|
28 *
|
|
|
29 * Most apps can make do without these functions, but they can be useful for
|
|
|
30 * integrating with other parts of a specific system, adding platform-specific
|
|
|
31 * polish to an app, or solving problems that only affect one target.
|
|
|
32 */
|
|
|
33
|
|
|
34 #ifndef SDL_system_h_
|
|
|
35 #define SDL_system_h_
|
|
|
36
|
|
|
37 #include <SDL3/SDL_stdinc.h>
|
|
|
38 #include <SDL3/SDL_error.h>
|
|
|
39 #include <SDL3/SDL_keyboard.h>
|
|
|
40 #include <SDL3/SDL_video.h>
|
|
|
41
|
|
|
42 #include <SDL3/SDL_begin_code.h>
|
|
|
43 /* Set up for C function definitions, even when using C++ */
|
|
|
44 #ifdef __cplusplus
|
|
|
45 extern "C" {
|
|
|
46 #endif
|
|
|
47
|
|
|
48
|
|
|
49 /*
|
|
|
50 * Platform specific functions for Windows
|
|
|
51 */
|
|
|
52 #if defined(SDL_PLATFORM_WINDOWS)
|
|
|
53
|
|
|
54 typedef struct tagMSG MSG;
|
|
|
55
|
|
|
56 /**
|
|
|
57 * A callback to be used with SDL_SetWindowsMessageHook.
|
|
|
58 *
|
|
|
59 * This callback may modify the message, and should return true if the message
|
|
|
60 * should continue to be processed, or false to prevent further processing.
|
|
|
61 *
|
|
|
62 * As this is processing a message directly from the Windows event loop, this
|
|
|
63 * callback should do the minimum required work and return quickly.
|
|
|
64 *
|
|
|
65 * \param userdata the app-defined pointer provided to
|
|
|
66 * SDL_SetWindowsMessageHook.
|
|
|
67 * \param msg a pointer to a Win32 event structure to process.
|
|
|
68 * \returns true to let event continue on, false to drop it.
|
|
|
69 *
|
|
|
70 * \threadsafety This may only be called (by SDL) from the thread handling the
|
|
|
71 * Windows event loop.
|
|
|
72 *
|
|
|
73 * \since This datatype is available since SDL 3.2.0.
|
|
|
74 *
|
|
|
75 * \sa SDL_SetWindowsMessageHook
|
|
|
76 * \sa SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP
|
|
|
77 */
|
|
|
78 typedef bool (SDLCALL *SDL_WindowsMessageHook)(void *userdata, MSG *msg);
|
|
|
79
|
|
|
80 /**
|
|
|
81 * Set a callback for every Windows message, run before TranslateMessage().
|
|
|
82 *
|
|
|
83 * The callback may modify the message, and should return true if the message
|
|
|
84 * should continue to be processed, or false to prevent further processing.
|
|
|
85 *
|
|
|
86 * \param callback the SDL_WindowsMessageHook function to call.
|
|
|
87 * \param userdata a pointer to pass to every iteration of `callback`.
|
|
|
88 *
|
|
|
89 * \since This function is available since SDL 3.2.0.
|
|
|
90 *
|
|
|
91 * \sa SDL_WindowsMessageHook
|
|
|
92 * \sa SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP
|
|
|
93 */
|
|
|
94 extern SDL_DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHook callback, void *userdata);
|
|
|
95
|
|
|
96 #endif /* defined(SDL_PLATFORM_WINDOWS) */
|
|
|
97
|
|
|
98 #if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK)
|
|
|
99
|
|
|
100 /**
|
|
|
101 * Get the D3D9 adapter index that matches the specified display.
|
|
|
102 *
|
|
|
103 * The returned adapter index can be passed to `IDirect3D9::CreateDevice` and
|
|
|
104 * controls on which monitor a full screen application will appear.
|
|
|
105 *
|
|
|
106 * \param displayID the instance of the display to query.
|
|
|
107 * \returns the D3D9 adapter index on success or -1 on failure; call
|
|
|
108 * SDL_GetError() for more information.
|
|
|
109 *
|
|
|
110 * \since This function is available since SDL 3.2.0.
|
|
|
111 */
|
|
|
112 extern SDL_DECLSPEC int SDLCALL SDL_GetDirect3D9AdapterIndex(SDL_DisplayID displayID);
|
|
|
113
|
|
|
114 /**
|
|
|
115 * Get the DXGI Adapter and Output indices for the specified display.
|
|
|
116 *
|
|
|
117 * The DXGI Adapter and Output indices can be passed to `EnumAdapters` and
|
|
|
118 * `EnumOutputs` respectively to get the objects required to create a DX10 or
|
|
|
119 * DX11 device and swap chain.
|
|
|
120 *
|
|
|
121 * \param displayID the instance of the display to query.
|
|
|
122 * \param adapterIndex a pointer to be filled in with the adapter index.
|
|
|
123 * \param outputIndex a pointer to be filled in with the output index.
|
|
|
124 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
125 * information.
|
|
|
126 *
|
|
|
127 * \since This function is available since SDL 3.2.0.
|
|
|
128 */
|
|
|
129 extern SDL_DECLSPEC bool SDLCALL SDL_GetDXGIOutputInfo(SDL_DisplayID displayID, int *adapterIndex, int *outputIndex);
|
|
|
130
|
|
|
131 #endif /* defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK) */
|
|
|
132
|
|
|
133
|
|
|
134 /*
|
|
|
135 * Platform specific functions for UNIX
|
|
|
136 */
|
|
|
137
|
|
|
138 /* this is defined in Xlib's headers, just need a simple declaration here. */
|
|
|
139 typedef union _XEvent XEvent;
|
|
|
140
|
|
|
141 /**
|
|
|
142 * A callback to be used with SDL_SetX11EventHook.
|
|
|
143 *
|
|
|
144 * This callback may modify the event, and should return true if the event
|
|
|
145 * should continue to be processed, or false to prevent further processing.
|
|
|
146 *
|
|
|
147 * As this is processing an event directly from the X11 event loop, this
|
|
|
148 * callback should do the minimum required work and return quickly.
|
|
|
149 *
|
|
|
150 * \param userdata the app-defined pointer provided to SDL_SetX11EventHook.
|
|
|
151 * \param xevent a pointer to an Xlib XEvent union to process.
|
|
|
152 * \returns true to let event continue on, false to drop it.
|
|
|
153 *
|
|
|
154 * \threadsafety This may only be called (by SDL) from the thread handling the
|
|
|
155 * X11 event loop.
|
|
|
156 *
|
|
|
157 * \since This datatype is available since SDL 3.2.0.
|
|
|
158 *
|
|
|
159 * \sa SDL_SetX11EventHook
|
|
|
160 */
|
|
|
161 typedef bool (SDLCALL *SDL_X11EventHook)(void *userdata, XEvent *xevent);
|
|
|
162
|
|
|
163 /**
|
|
|
164 * Set a callback for every X11 event.
|
|
|
165 *
|
|
|
166 * The callback may modify the event, and should return true if the event
|
|
|
167 * should continue to be processed, or false to prevent further processing.
|
|
|
168 *
|
|
|
169 * \param callback the SDL_X11EventHook function to call.
|
|
|
170 * \param userdata a pointer to pass to every iteration of `callback`.
|
|
|
171 *
|
|
|
172 * \since This function is available since SDL 3.2.0.
|
|
|
173 */
|
|
|
174 extern SDL_DECLSPEC void SDLCALL SDL_SetX11EventHook(SDL_X11EventHook callback, void *userdata);
|
|
|
175
|
|
|
176 /* Platform specific functions for Linux*/
|
|
|
177 #ifdef SDL_PLATFORM_LINUX
|
|
|
178
|
|
|
179 /**
|
|
|
180 * Sets the UNIX nice value for a thread.
|
|
|
181 *
|
|
|
182 * This uses setpriority() if possible, and RealtimeKit if available.
|
|
|
183 *
|
|
|
184 * \param threadID the Unix thread ID to change priority of.
|
|
|
185 * \param priority the new, Unix-specific, priority value.
|
|
|
186 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
187 * information.
|
|
|
188 *
|
|
|
189 * \since This function is available since SDL 3.2.0.
|
|
|
190 */
|
|
|
191 extern SDL_DECLSPEC bool SDLCALL SDL_SetLinuxThreadPriority(Sint64 threadID, int priority);
|
|
|
192
|
|
|
193 /**
|
|
|
194 * Sets the priority (not nice level) and scheduling policy for a thread.
|
|
|
195 *
|
|
|
196 * This uses setpriority() if possible, and RealtimeKit if available.
|
|
|
197 *
|
|
|
198 * \param threadID the Unix thread ID to change priority of.
|
|
|
199 * \param sdlPriority the new SDL_ThreadPriority value.
|
|
|
200 * \param schedPolicy the new scheduling policy (SCHED_FIFO, SCHED_RR,
|
|
|
201 * SCHED_OTHER, etc...).
|
|
|
202 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
203 * information.
|
|
|
204 *
|
|
|
205 * \since This function is available since SDL 3.2.0.
|
|
|
206 */
|
|
|
207 extern SDL_DECLSPEC bool SDLCALL SDL_SetLinuxThreadPriorityAndPolicy(Sint64 threadID, int sdlPriority, int schedPolicy);
|
|
|
208
|
|
|
209 #endif /* SDL_PLATFORM_LINUX */
|
|
|
210
|
|
|
211 /*
|
|
|
212 * Platform specific functions for iOS
|
|
|
213 */
|
|
|
214 #ifdef SDL_PLATFORM_IOS
|
|
|
215
|
|
|
216 /**
|
|
|
217 * The prototype for an Apple iOS animation callback.
|
|
|
218 *
|
|
|
219 * This datatype is only useful on Apple iOS.
|
|
|
220 *
|
|
|
221 * After passing a function pointer of this type to
|
|
|
222 * SDL_SetiOSAnimationCallback, the system will call that function pointer at
|
|
|
223 * a regular interval.
|
|
|
224 *
|
|
|
225 * \param userdata what was passed as `callbackParam` to
|
|
|
226 * SDL_SetiOSAnimationCallback as `callbackParam`.
|
|
|
227 *
|
|
|
228 * \since This datatype is available since SDL 3.2.0.
|
|
|
229 *
|
|
|
230 * \sa SDL_SetiOSAnimationCallback
|
|
|
231 */
|
|
|
232 typedef void (SDLCALL *SDL_iOSAnimationCallback)(void *userdata);
|
|
|
233
|
|
|
234 /**
|
|
|
235 * Use this function to set the animation callback on Apple iOS.
|
|
|
236 *
|
|
|
237 * The function prototype for `callback` is:
|
|
|
238 *
|
|
|
239 * ```c
|
|
|
240 * void callback(void *callbackParam);
|
|
|
241 * ```
|
|
|
242 *
|
|
|
243 * Where its parameter, `callbackParam`, is what was passed as `callbackParam`
|
|
|
244 * to SDL_SetiOSAnimationCallback().
|
|
|
245 *
|
|
|
246 * This function is only available on Apple iOS.
|
|
|
247 *
|
|
|
248 * For more information see:
|
|
|
249 *
|
|
|
250 * https://wiki.libsdl.org/SDL3/README-ios
|
|
|
251 *
|
|
|
252 * Note that if you use the "main callbacks" instead of a standard C `main`
|
|
|
253 * function, you don't have to use this API, as SDL will manage this for you.
|
|
|
254 *
|
|
|
255 * Details on main callbacks are here:
|
|
|
256 *
|
|
|
257 * https://wiki.libsdl.org/SDL3/README-main-functions
|
|
|
258 *
|
|
|
259 * \param window the window for which the animation callback should be set.
|
|
|
260 * \param interval the number of frames after which **callback** will be
|
|
|
261 * called.
|
|
|
262 * \param callback the function to call for every frame.
|
|
|
263 * \param callbackParam a pointer that is passed to `callback`.
|
|
|
264 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
265 * information.
|
|
|
266 *
|
|
|
267 * \since This function is available since SDL 3.2.0.
|
|
|
268 *
|
|
|
269 * \sa SDL_SetiOSEventPump
|
|
|
270 */
|
|
|
271 extern SDL_DECLSPEC bool SDLCALL SDL_SetiOSAnimationCallback(SDL_Window *window, int interval, SDL_iOSAnimationCallback callback, void *callbackParam);
|
|
|
272
|
|
|
273 /**
|
|
|
274 * Use this function to enable or disable the SDL event pump on Apple iOS.
|
|
|
275 *
|
|
|
276 * This function is only available on Apple iOS.
|
|
|
277 *
|
|
|
278 * \param enabled true to enable the event pump, false to disable it.
|
|
|
279 *
|
|
|
280 * \since This function is available since SDL 3.2.0.
|
|
|
281 *
|
|
|
282 * \sa SDL_SetiOSAnimationCallback
|
|
|
283 */
|
|
|
284 extern SDL_DECLSPEC void SDLCALL SDL_SetiOSEventPump(bool enabled);
|
|
|
285
|
|
|
286 #endif /* SDL_PLATFORM_IOS */
|
|
|
287
|
|
|
288
|
|
|
289 /*
|
|
|
290 * Platform specific functions for Android
|
|
|
291 */
|
|
|
292 #ifdef SDL_PLATFORM_ANDROID
|
|
|
293
|
|
|
294 /**
|
|
|
295 * Get the Android Java Native Interface Environment of the current thread.
|
|
|
296 *
|
|
|
297 * This is the JNIEnv one needs to access the Java virtual machine from native
|
|
|
298 * code, and is needed for many Android APIs to be usable from C.
|
|
|
299 *
|
|
|
300 * The prototype of the function in SDL's code actually declare a void* return
|
|
|
301 * type, even if the implementation returns a pointer to a JNIEnv. The
|
|
|
302 * rationale being that the SDL headers can avoid including jni.h.
|
|
|
303 *
|
|
|
304 * \returns a pointer to Java native interface object (JNIEnv) to which the
|
|
|
305 * current thread is attached, or NULL on failure; call
|
|
|
306 * SDL_GetError() for more information.
|
|
|
307 *
|
|
|
308 * \threadsafety It is safe to call this function from any thread.
|
|
|
309 *
|
|
|
310 * \since This function is available since SDL 3.2.0.
|
|
|
311 *
|
|
|
312 * \sa SDL_GetAndroidActivity
|
|
|
313 */
|
|
|
314 extern SDL_DECLSPEC void * SDLCALL SDL_GetAndroidJNIEnv(void);
|
|
|
315
|
|
|
316 /**
|
|
|
317 * Retrieve the Java instance of the Android activity class.
|
|
|
318 *
|
|
|
319 * The prototype of the function in SDL's code actually declares a void*
|
|
|
320 * return type, even if the implementation returns a jobject. The rationale
|
|
|
321 * being that the SDL headers can avoid including jni.h.
|
|
|
322 *
|
|
|
323 * The jobject returned by the function is a local reference and must be
|
|
|
324 * released by the caller. See the PushLocalFrame() and PopLocalFrame() or
|
|
|
325 * DeleteLocalRef() functions of the Java native interface:
|
|
|
326 *
|
|
|
327 * https://docs.oracle.com/javase/1.5.0/docs/guide/jni/spec/functions.html
|
|
|
328 *
|
|
|
329 * \returns the jobject representing the instance of the Activity class of the
|
|
|
330 * Android application, or NULL on failure; call SDL_GetError() for
|
|
|
331 * more information.
|
|
|
332 *
|
|
|
333 * \threadsafety It is safe to call this function from any thread.
|
|
|
334 *
|
|
|
335 * \since This function is available since SDL 3.2.0.
|
|
|
336 *
|
|
|
337 * \sa SDL_GetAndroidJNIEnv
|
|
|
338 */
|
|
|
339 extern SDL_DECLSPEC void * SDLCALL SDL_GetAndroidActivity(void);
|
|
|
340
|
|
|
341 /**
|
|
|
342 * Query Android API level of the current device.
|
|
|
343 *
|
|
|
344 * - API level 35: Android 15 (VANILLA_ICE_CREAM)
|
|
|
345 * - API level 34: Android 14 (UPSIDE_DOWN_CAKE)
|
|
|
346 * - API level 33: Android 13 (TIRAMISU)
|
|
|
347 * - API level 32: Android 12L (S_V2)
|
|
|
348 * - API level 31: Android 12 (S)
|
|
|
349 * - API level 30: Android 11 (R)
|
|
|
350 * - API level 29: Android 10 (Q)
|
|
|
351 * - API level 28: Android 9 (P)
|
|
|
352 * - API level 27: Android 8.1 (O_MR1)
|
|
|
353 * - API level 26: Android 8.0 (O)
|
|
|
354 * - API level 25: Android 7.1 (N_MR1)
|
|
|
355 * - API level 24: Android 7.0 (N)
|
|
|
356 * - API level 23: Android 6.0 (M)
|
|
|
357 * - API level 22: Android 5.1 (LOLLIPOP_MR1)
|
|
|
358 * - API level 21: Android 5.0 (LOLLIPOP, L)
|
|
|
359 * - API level 20: Android 4.4W (KITKAT_WATCH)
|
|
|
360 * - API level 19: Android 4.4 (KITKAT)
|
|
|
361 * - API level 18: Android 4.3 (JELLY_BEAN_MR2)
|
|
|
362 * - API level 17: Android 4.2 (JELLY_BEAN_MR1)
|
|
|
363 * - API level 16: Android 4.1 (JELLY_BEAN)
|
|
|
364 * - API level 15: Android 4.0.3 (ICE_CREAM_SANDWICH_MR1)
|
|
|
365 * - API level 14: Android 4.0 (ICE_CREAM_SANDWICH)
|
|
|
366 * - API level 13: Android 3.2 (HONEYCOMB_MR2)
|
|
|
367 * - API level 12: Android 3.1 (HONEYCOMB_MR1)
|
|
|
368 * - API level 11: Android 3.0 (HONEYCOMB)
|
|
|
369 * - API level 10: Android 2.3.3 (GINGERBREAD_MR1)
|
|
|
370 *
|
|
|
371 * \returns the Android API level.
|
|
|
372 *
|
|
|
373 * \since This function is available since SDL 3.2.0.
|
|
|
374 */
|
|
|
375 extern SDL_DECLSPEC int SDLCALL SDL_GetAndroidSDKVersion(void);
|
|
|
376
|
|
|
377 /**
|
|
|
378 * Query if the application is running on a Chromebook.
|
|
|
379 *
|
|
|
380 * \returns true if this is a Chromebook, false otherwise.
|
|
|
381 *
|
|
|
382 * \since This function is available since SDL 3.2.0.
|
|
|
383 */
|
|
|
384 extern SDL_DECLSPEC bool SDLCALL SDL_IsChromebook(void);
|
|
|
385
|
|
|
386 /**
|
|
|
387 * Query if the application is running on a Samsung DeX docking station.
|
|
|
388 *
|
|
|
389 * \returns true if this is a DeX docking station, false otherwise.
|
|
|
390 *
|
|
|
391 * \since This function is available since SDL 3.2.0.
|
|
|
392 */
|
|
|
393 extern SDL_DECLSPEC bool SDLCALL SDL_IsDeXMode(void);
|
|
|
394
|
|
|
395 /**
|
|
|
396 * Trigger the Android system back button behavior.
|
|
|
397 *
|
|
|
398 * \threadsafety It is safe to call this function from any thread.
|
|
|
399 *
|
|
|
400 * \since This function is available since SDL 3.2.0.
|
|
|
401 */
|
|
|
402 extern SDL_DECLSPEC void SDLCALL SDL_SendAndroidBackButton(void);
|
|
|
403
|
|
|
404 /**
|
|
|
405 * See the official Android developer guide for more information:
|
|
|
406 * http://developer.android.com/guide/topics/data/data-storage.html
|
|
|
407 *
|
|
|
408 * \since This macro is available since SDL 3.2.0.
|
|
|
409 */
|
|
|
410 #define SDL_ANDROID_EXTERNAL_STORAGE_READ 0x01
|
|
|
411
|
|
|
412 /**
|
|
|
413 * See the official Android developer guide for more information:
|
|
|
414 * http://developer.android.com/guide/topics/data/data-storage.html
|
|
|
415 *
|
|
|
416 * \since This macro is available since SDL 3.2.0.
|
|
|
417 */
|
|
|
418 #define SDL_ANDROID_EXTERNAL_STORAGE_WRITE 0x02
|
|
|
419
|
|
|
420 /**
|
|
|
421 * Get the path used for internal storage for this Android application.
|
|
|
422 *
|
|
|
423 * This path is unique to your application and cannot be written to by other
|
|
|
424 * applications.
|
|
|
425 *
|
|
|
426 * Your internal storage path is typically:
|
|
|
427 * `/data/data/your.app.package/files`.
|
|
|
428 *
|
|
|
429 * This is a C wrapper over `android.content.Context.getFilesDir()`:
|
|
|
430 *
|
|
|
431 * https://developer.android.com/reference/android/content/Context#getFilesDir()
|
|
|
432 *
|
|
|
433 * \returns the path used for internal storage or NULL on failure; call
|
|
|
434 * SDL_GetError() for more information.
|
|
|
435 *
|
|
|
436 * \since This function is available since SDL 3.2.0.
|
|
|
437 *
|
|
|
438 * \sa SDL_GetAndroidExternalStoragePath
|
|
|
439 * \sa SDL_GetAndroidCachePath
|
|
|
440 */
|
|
|
441 extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidInternalStoragePath(void);
|
|
|
442
|
|
|
443 /**
|
|
|
444 * Get the current state of external storage for this Android application.
|
|
|
445 *
|
|
|
446 * The current state of external storage, a bitmask of these values:
|
|
|
447 * `SDL_ANDROID_EXTERNAL_STORAGE_READ`, `SDL_ANDROID_EXTERNAL_STORAGE_WRITE`.
|
|
|
448 *
|
|
|
449 * If external storage is currently unavailable, this will return 0.
|
|
|
450 *
|
|
|
451 * \returns the current state of external storage, or 0 if external storage is
|
|
|
452 * currently unavailable.
|
|
|
453 *
|
|
|
454 * \since This function is available since SDL 3.2.0.
|
|
|
455 *
|
|
|
456 * \sa SDL_GetAndroidExternalStoragePath
|
|
|
457 */
|
|
|
458 extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetAndroidExternalStorageState(void);
|
|
|
459
|
|
|
460 /**
|
|
|
461 * Get the path used for external storage for this Android application.
|
|
|
462 *
|
|
|
463 * This path is unique to your application, but is public and can be written
|
|
|
464 * to by other applications.
|
|
|
465 *
|
|
|
466 * Your external storage path is typically:
|
|
|
467 * `/storage/sdcard0/Android/data/your.app.package/files`.
|
|
|
468 *
|
|
|
469 * This is a C wrapper over `android.content.Context.getExternalFilesDir()`:
|
|
|
470 *
|
|
|
471 * https://developer.android.com/reference/android/content/Context#getExternalFilesDir()
|
|
|
472 *
|
|
|
473 * \returns the path used for external storage for this application on success
|
|
|
474 * or NULL on failure; call SDL_GetError() for more information.
|
|
|
475 *
|
|
|
476 * \since This function is available since SDL 3.2.0.
|
|
|
477 *
|
|
|
478 * \sa SDL_GetAndroidExternalStorageState
|
|
|
479 * \sa SDL_GetAndroidInternalStoragePath
|
|
|
480 * \sa SDL_GetAndroidCachePath
|
|
|
481 */
|
|
|
482 extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidExternalStoragePath(void);
|
|
|
483
|
|
|
484 /**
|
|
|
485 * Get the path used for caching data for this Android application.
|
|
|
486 *
|
|
|
487 * This path is unique to your application, but is public and can be written
|
|
|
488 * to by other applications.
|
|
|
489 *
|
|
|
490 * Your cache path is typically: `/data/data/your.app.package/cache/`.
|
|
|
491 *
|
|
|
492 * This is a C wrapper over `android.content.Context.getCacheDir()`:
|
|
|
493 *
|
|
|
494 * https://developer.android.com/reference/android/content/Context#getCacheDir()
|
|
|
495 *
|
|
|
496 * \returns the path used for caches for this application on success or NULL
|
|
|
497 * on failure; call SDL_GetError() for more information.
|
|
|
498 *
|
|
|
499 * \since This function is available since SDL 3.2.0.
|
|
|
500 *
|
|
|
501 * \sa SDL_GetAndroidInternalStoragePath
|
|
|
502 * \sa SDL_GetAndroidExternalStoragePath
|
|
|
503 */
|
|
|
504 extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidCachePath(void);
|
|
|
505
|
|
|
506 /**
|
|
|
507 * Callback that presents a response from a SDL_RequestAndroidPermission call.
|
|
|
508 *
|
|
|
509 * \param userdata an app-controlled pointer that is passed to the callback.
|
|
|
510 * \param permission the Android-specific permission name that was requested.
|
|
|
511 * \param granted true if permission is granted, false if denied.
|
|
|
512 *
|
|
|
513 * \since This datatype is available since SDL 3.2.0.
|
|
|
514 *
|
|
|
515 * \sa SDL_RequestAndroidPermission
|
|
|
516 */
|
|
|
517 typedef void (SDLCALL *SDL_RequestAndroidPermissionCallback)(void *userdata, const char *permission, bool granted);
|
|
|
518
|
|
|
519 /**
|
|
|
520 * Request permissions at runtime, asynchronously.
|
|
|
521 *
|
|
|
522 * You do not need to call this for built-in functionality of SDL; recording
|
|
|
523 * from a microphone or reading images from a camera, using standard SDL APIs,
|
|
|
524 * will manage permission requests for you.
|
|
|
525 *
|
|
|
526 * This function never blocks. Instead, the app-supplied callback will be
|
|
|
527 * called when a decision has been made. This callback may happen on a
|
|
|
528 * different thread, and possibly much later, as it might wait on a user to
|
|
|
529 * respond to a system dialog. If permission has already been granted for a
|
|
|
530 * specific entitlement, the callback will still fire, probably on the current
|
|
|
531 * thread and before this function returns.
|
|
|
532 *
|
|
|
533 * If the request submission fails, this function returns -1 and the callback
|
|
|
534 * will NOT be called, but this should only happen in catastrophic conditions,
|
|
|
535 * like memory running out. Normally there will be a yes or no to the request
|
|
|
536 * through the callback.
|
|
|
537 *
|
|
|
538 * For the `permission` parameter, choose a value from here:
|
|
|
539 *
|
|
|
540 * https://developer.android.com/reference/android/Manifest.permission
|
|
|
541 *
|
|
|
542 * \param permission the permission to request.
|
|
|
543 * \param cb the callback to trigger when the request has a response.
|
|
|
544 * \param userdata an app-controlled pointer that is passed to the callback.
|
|
|
545 * \returns true if the request was submitted, false if there was an error
|
|
|
546 * submitting. The result of the request is only ever reported
|
|
|
547 * through the callback, not this return value.
|
|
|
548 *
|
|
|
549 * \threadsafety It is safe to call this function from any thread.
|
|
|
550 *
|
|
|
551 * \since This function is available since SDL 3.2.0.
|
|
|
552 */
|
|
|
553 extern SDL_DECLSPEC bool SDLCALL SDL_RequestAndroidPermission(const char *permission, SDL_RequestAndroidPermissionCallback cb, void *userdata);
|
|
|
554
|
|
|
555 /**
|
|
|
556 * Shows an Android toast notification.
|
|
|
557 *
|
|
|
558 * Toasts are a sort of lightweight notification that are unique to Android.
|
|
|
559 *
|
|
|
560 * https://developer.android.com/guide/topics/ui/notifiers/toasts
|
|
|
561 *
|
|
|
562 * Shows toast in UI thread.
|
|
|
563 *
|
|
|
564 * For the `gravity` parameter, choose a value from here, or -1 if you don't
|
|
|
565 * have a preference:
|
|
|
566 *
|
|
|
567 * https://developer.android.com/reference/android/view/Gravity
|
|
|
568 *
|
|
|
569 * \param message text message to be shown.
|
|
|
570 * \param duration 0=short, 1=long.
|
|
|
571 * \param gravity where the notification should appear on the screen.
|
|
|
572 * \param xoffset set this parameter only when gravity >=0.
|
|
|
573 * \param yoffset set this parameter only when gravity >=0.
|
|
|
574 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
575 * information.
|
|
|
576 *
|
|
|
577 * \threadsafety It is safe to call this function from any thread.
|
|
|
578 *
|
|
|
579 * \since This function is available since SDL 3.2.0.
|
|
|
580 */
|
|
|
581 extern SDL_DECLSPEC bool SDLCALL SDL_ShowAndroidToast(const char *message, int duration, int gravity, int xoffset, int yoffset);
|
|
|
582
|
|
|
583 /**
|
|
|
584 * Send a user command to SDLActivity.
|
|
|
585 *
|
|
|
586 * Override "boolean onUnhandledMessage(Message msg)" to handle the message.
|
|
|
587 *
|
|
|
588 * \param command user command that must be greater or equal to 0x8000.
|
|
|
589 * \param param user parameter.
|
|
|
590 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
591 * information.
|
|
|
592 *
|
|
|
593 * \threadsafety It is safe to call this function from any thread.
|
|
|
594 *
|
|
|
595 * \since This function is available since SDL 3.2.0.
|
|
|
596 */
|
|
|
597 extern SDL_DECLSPEC bool SDLCALL SDL_SendAndroidMessage(Uint32 command, int param);
|
|
|
598
|
|
|
599 #endif /* SDL_PLATFORM_ANDROID */
|
|
|
600
|
|
|
601 /**
|
|
|
602 * Query if the current device is a tablet.
|
|
|
603 *
|
|
|
604 * If SDL can't determine this, it will return false.
|
|
|
605 *
|
|
|
606 * \returns true if the device is a tablet, false otherwise.
|
|
|
607 *
|
|
|
608 * \since This function is available since SDL 3.2.0.
|
|
|
609 */
|
|
|
610 extern SDL_DECLSPEC bool SDLCALL SDL_IsTablet(void);
|
|
|
611
|
|
|
612 /**
|
|
|
613 * Query if the current device is a TV.
|
|
|
614 *
|
|
|
615 * If SDL can't determine this, it will return false.
|
|
|
616 *
|
|
|
617 * \returns true if the device is a TV, false otherwise.
|
|
|
618 *
|
|
|
619 * \since This function is available since SDL 3.2.0.
|
|
|
620 */
|
|
|
621 extern SDL_DECLSPEC bool SDLCALL SDL_IsTV(void);
|
|
|
622
|
|
|
623 /**
|
|
|
624 * Application sandbox environment.
|
|
|
625 *
|
|
|
626 * \since This enum is available since SDL 3.2.0.
|
|
|
627 */
|
|
|
628 typedef enum SDL_Sandbox
|
|
|
629 {
|
|
|
630 SDL_SANDBOX_NONE = 0,
|
|
|
631 SDL_SANDBOX_UNKNOWN_CONTAINER,
|
|
|
632 SDL_SANDBOX_FLATPAK,
|
|
|
633 SDL_SANDBOX_SNAP,
|
|
|
634 SDL_SANDBOX_MACOS
|
|
|
635 } SDL_Sandbox;
|
|
|
636
|
|
|
637 /**
|
|
|
638 * Get the application sandbox environment, if any.
|
|
|
639 *
|
|
|
640 * \returns the application sandbox environment or SDL_SANDBOX_NONE if the
|
|
|
641 * application is not running in a sandbox environment.
|
|
|
642 *
|
|
|
643 * \since This function is available since SDL 3.2.0.
|
|
|
644 */
|
|
|
645 extern SDL_DECLSPEC SDL_Sandbox SDLCALL SDL_GetSandbox(void);
|
|
|
646
|
|
|
647
|
|
|
648 /* Functions used by iOS app delegates to notify SDL about state changes. */
|
|
|
649
|
|
|
650 /**
|
|
|
651 * Let iOS apps with external event handling report
|
|
|
652 * onApplicationWillTerminate.
|
|
|
653 *
|
|
|
654 * This functions allows iOS apps that have their own event handling to hook
|
|
|
655 * into SDL to generate SDL events. This maps directly to an iOS-specific
|
|
|
656 * event, but since it doesn't do anything iOS-specific internally, it is
|
|
|
657 * available on all platforms, in case it might be useful for some specific
|
|
|
658 * paradigm. Most apps do not need to use this directly; SDL's internal event
|
|
|
659 * code will handle all this for windows created by SDL_CreateWindow!
|
|
|
660 *
|
|
|
661 * \threadsafety It is safe to call this function from any thread.
|
|
|
662 *
|
|
|
663 * \since This function is available since SDL 3.2.0.
|
|
|
664 */
|
|
|
665 extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillTerminate(void);
|
|
|
666
|
|
|
667 /**
|
|
|
668 * Let iOS apps with external event handling report
|
|
|
669 * onApplicationDidReceiveMemoryWarning.
|
|
|
670 *
|
|
|
671 * This functions allows iOS apps that have their own event handling to hook
|
|
|
672 * into SDL to generate SDL events. This maps directly to an iOS-specific
|
|
|
673 * event, but since it doesn't do anything iOS-specific internally, it is
|
|
|
674 * available on all platforms, in case it might be useful for some specific
|
|
|
675 * paradigm. Most apps do not need to use this directly; SDL's internal event
|
|
|
676 * code will handle all this for windows created by SDL_CreateWindow!
|
|
|
677 *
|
|
|
678 * \threadsafety It is safe to call this function from any thread.
|
|
|
679 *
|
|
|
680 * \since This function is available since SDL 3.2.0.
|
|
|
681 */
|
|
|
682 extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidReceiveMemoryWarning(void);
|
|
|
683
|
|
|
684 /**
|
|
|
685 * Let iOS apps with external event handling report
|
|
|
686 * onApplicationWillResignActive.
|
|
|
687 *
|
|
|
688 * This functions allows iOS apps that have their own event handling to hook
|
|
|
689 * into SDL to generate SDL events. This maps directly to an iOS-specific
|
|
|
690 * event, but since it doesn't do anything iOS-specific internally, it is
|
|
|
691 * available on all platforms, in case it might be useful for some specific
|
|
|
692 * paradigm. Most apps do not need to use this directly; SDL's internal event
|
|
|
693 * code will handle all this for windows created by SDL_CreateWindow!
|
|
|
694 *
|
|
|
695 * \threadsafety It is safe to call this function from any thread.
|
|
|
696 *
|
|
|
697 * \since This function is available since SDL 3.2.0.
|
|
|
698 */
|
|
|
699 extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillEnterBackground(void);
|
|
|
700
|
|
|
701 /**
|
|
|
702 * Let iOS apps with external event handling report
|
|
|
703 * onApplicationDidEnterBackground.
|
|
|
704 *
|
|
|
705 * This functions allows iOS apps that have their own event handling to hook
|
|
|
706 * into SDL to generate SDL events. This maps directly to an iOS-specific
|
|
|
707 * event, but since it doesn't do anything iOS-specific internally, it is
|
|
|
708 * available on all platforms, in case it might be useful for some specific
|
|
|
709 * paradigm. Most apps do not need to use this directly; SDL's internal event
|
|
|
710 * code will handle all this for windows created by SDL_CreateWindow!
|
|
|
711 *
|
|
|
712 * \threadsafety It is safe to call this function from any thread.
|
|
|
713 *
|
|
|
714 * \since This function is available since SDL 3.2.0.
|
|
|
715 */
|
|
|
716 extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidEnterBackground(void);
|
|
|
717
|
|
|
718 /**
|
|
|
719 * Let iOS apps with external event handling report
|
|
|
720 * onApplicationWillEnterForeground.
|
|
|
721 *
|
|
|
722 * This functions allows iOS apps that have their own event handling to hook
|
|
|
723 * into SDL to generate SDL events. This maps directly to an iOS-specific
|
|
|
724 * event, but since it doesn't do anything iOS-specific internally, it is
|
|
|
725 * available on all platforms, in case it might be useful for some specific
|
|
|
726 * paradigm. Most apps do not need to use this directly; SDL's internal event
|
|
|
727 * code will handle all this for windows created by SDL_CreateWindow!
|
|
|
728 *
|
|
|
729 * \threadsafety It is safe to call this function from any thread.
|
|
|
730 *
|
|
|
731 * \since This function is available since SDL 3.2.0.
|
|
|
732 */
|
|
|
733 extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillEnterForeground(void);
|
|
|
734
|
|
|
735 /**
|
|
|
736 * Let iOS apps with external event handling report
|
|
|
737 * onApplicationDidBecomeActive.
|
|
|
738 *
|
|
|
739 * This functions allows iOS apps that have their own event handling to hook
|
|
|
740 * into SDL to generate SDL events. This maps directly to an iOS-specific
|
|
|
741 * event, but since it doesn't do anything iOS-specific internally, it is
|
|
|
742 * available on all platforms, in case it might be useful for some specific
|
|
|
743 * paradigm. Most apps do not need to use this directly; SDL's internal event
|
|
|
744 * code will handle all this for windows created by SDL_CreateWindow!
|
|
|
745 *
|
|
|
746 * \threadsafety It is safe to call this function from any thread.
|
|
|
747 *
|
|
|
748 * \since This function is available since SDL 3.2.0.
|
|
|
749 */
|
|
|
750 extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidEnterForeground(void);
|
|
|
751
|
|
|
752 #ifdef SDL_PLATFORM_IOS
|
|
|
753
|
|
|
754 /**
|
|
|
755 * Let iOS apps with external event handling report
|
|
|
756 * onApplicationDidChangeStatusBarOrientation.
|
|
|
757 *
|
|
|
758 * This functions allows iOS apps that have their own event handling to hook
|
|
|
759 * into SDL to generate SDL events. This maps directly to an iOS-specific
|
|
|
760 * event, but since it doesn't do anything iOS-specific internally, it is
|
|
|
761 * available on all platforms, in case it might be useful for some specific
|
|
|
762 * paradigm. Most apps do not need to use this directly; SDL's internal event
|
|
|
763 * code will handle all this for windows created by SDL_CreateWindow!
|
|
|
764 *
|
|
|
765 * \threadsafety It is safe to call this function from any thread.
|
|
|
766 *
|
|
|
767 * \since This function is available since SDL 3.2.0.
|
|
|
768 */
|
|
|
769 extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidChangeStatusBarOrientation(void);
|
|
|
770 #endif
|
|
|
771
|
|
|
772 /*
|
|
|
773 * Functions used only by GDK
|
|
|
774 */
|
|
|
775 #ifdef SDL_PLATFORM_GDK
|
|
|
776 typedef struct XTaskQueueObject *XTaskQueueHandle;
|
|
|
777 typedef struct XUser *XUserHandle;
|
|
|
778
|
|
|
779 /**
|
|
|
780 * Gets a reference to the global async task queue handle for GDK,
|
|
|
781 * initializing if needed.
|
|
|
782 *
|
|
|
783 * Once you are done with the task queue, you should call
|
|
|
784 * XTaskQueueCloseHandle to reduce the reference count to avoid a resource
|
|
|
785 * leak.
|
|
|
786 *
|
|
|
787 * \param outTaskQueue a pointer to be filled in with task queue handle.
|
|
|
788 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
789 * information.
|
|
|
790 *
|
|
|
791 * \since This function is available since SDL 3.2.0.
|
|
|
792 */
|
|
|
793 extern SDL_DECLSPEC bool SDLCALL SDL_GetGDKTaskQueue(XTaskQueueHandle *outTaskQueue);
|
|
|
794
|
|
|
795 /**
|
|
|
796 * Gets a reference to the default user handle for GDK.
|
|
|
797 *
|
|
|
798 * This is effectively a synchronous version of XUserAddAsync, which always
|
|
|
799 * prefers the default user and allows a sign-in UI.
|
|
|
800 *
|
|
|
801 * \param outUserHandle a pointer to be filled in with the default user
|
|
|
802 * handle.
|
|
|
803 * \returns true if success or false on failure; call SDL_GetError() for more
|
|
|
804 * information.
|
|
|
805 *
|
|
|
806 * \since This function is available since SDL 3.2.0.
|
|
|
807 */
|
|
|
808 extern SDL_DECLSPEC bool SDLCALL SDL_GetGDKDefaultUser(XUserHandle *outUserHandle);
|
|
|
809
|
|
|
810 #endif
|
|
|
811
|
|
|
812 /* Ends C function definitions when using C++ */
|
|
|
813 #ifdef __cplusplus
|
|
|
814 }
|
|
|
815 #endif
|
|
|
816 #include <SDL3/SDL_close_code.h>
|
|
|
817
|
|
|
818 #endif /* SDL_system_h_ */
|
