1 | /* |
2 | Simple DirectMedia Layer |
3 | Copyright (C) 1997-2024 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_hints.h |
24 | * |
25 | * Official documentation for SDL configuration variables |
26 | * |
27 | * This file contains functions to set and get configuration hints, |
28 | * as well as listing each of them alphabetically. |
29 | * |
30 | * The convention for naming hints is SDL_HINT_X, where "SDL_X" is |
31 | * the environment variable that can be used to override the default. |
32 | * |
33 | * In general these hints are just that - they may or may not be |
34 | * supported or applicable on any given platform, but they provide |
35 | * a way for an application or user to give the library a hint as |
36 | * to how they would like the library to work. |
37 | */ |
38 | |
39 | #ifndef SDL_hints_h_ |
40 | #define SDL_hints_h_ |
41 | |
42 | #include "SDL_stdinc.h" |
43 | |
44 | #include "begin_code.h" |
45 | /* Set up for C function definitions, even when using C++ */ |
46 | #ifdef __cplusplus |
47 | extern "C" { |
48 | #endif |
49 | |
50 | /** |
51 | * \brief A variable controlling whether the Android / iOS built-in |
52 | * accelerometer should be listed as a joystick device. |
53 | * |
54 | * This variable can be set to the following values: |
55 | * "0" - The accelerometer is not listed as a joystick |
56 | * "1" - The accelerometer is available as a 3 axis joystick (the default). |
57 | */ |
58 | #define SDL_HINT_ACCELEROMETER_AS_JOYSTICK "SDL_ACCELEROMETER_AS_JOYSTICK" |
59 | |
60 | /** |
61 | * \brief Specify the behavior of Alt+Tab while the keyboard is grabbed. |
62 | * |
63 | * By default, SDL emulates Alt+Tab functionality while the keyboard is grabbed |
64 | * and your window is full-screen. This prevents the user from getting stuck in |
65 | * your application if you've enabled keyboard grab. |
66 | * |
67 | * The variable can be set to the following values: |
68 | * "0" - SDL will not handle Alt+Tab. Your application is responsible |
69 | for handling Alt+Tab while the keyboard is grabbed. |
70 | * "1" - SDL will minimize your window when Alt+Tab is pressed (default) |
71 | */ |
72 | #define SDL_HINT_ALLOW_ALT_TAB_WHILE_GRABBED "SDL_ALLOW_ALT_TAB_WHILE_GRABBED" |
73 | |
74 | /** |
75 | * \brief If set to "0" then never set the top most bit on a SDL Window, even if the video mode expects it. |
76 | * This is a debugging aid for developers and not expected to be used by end users. The default is "1" |
77 | * |
78 | * This variable can be set to the following values: |
79 | * "0" - don't allow topmost |
80 | * "1" - allow topmost |
81 | */ |
82 | #define SDL_HINT_ALLOW_TOPMOST "SDL_ALLOW_TOPMOST" |
83 | |
84 | /** |
85 | * \brief Android APK expansion main file version. Should be a string number like "1", "2" etc. |
86 | * |
87 | * Must be set together with SDL_HINT_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION. |
88 | * |
89 | * If both hints were set then SDL_RWFromFile() will look into expansion files |
90 | * after a given relative path was not found in the internal storage and assets. |
91 | * |
92 | * By default this hint is not set and the APK expansion files are not searched. |
93 | */ |
94 | #define SDL_HINT_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION "SDL_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION" |
95 | |
96 | /** |
97 | * \brief Android APK expansion patch file version. Should be a string number like "1", "2" etc. |
98 | * |
99 | * Must be set together with SDL_HINT_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION. |
100 | * |
101 | * If both hints were set then SDL_RWFromFile() will look into expansion files |
102 | * after a given relative path was not found in the internal storage and assets. |
103 | * |
104 | * By default this hint is not set and the APK expansion files are not searched. |
105 | */ |
106 | #define SDL_HINT_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION "SDL_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION" |
107 | |
108 | /** |
109 | * \brief A variable to control whether the event loop will block itself when the app is paused. |
110 | * |
111 | * The variable can be set to the following values: |
112 | * "0" - Non blocking. |
113 | * "1" - Blocking. (default) |
114 | * |
115 | * The value should be set before SDL is initialized. |
116 | */ |
117 | #define SDL_HINT_ANDROID_BLOCK_ON_PAUSE "SDL_ANDROID_BLOCK_ON_PAUSE" |
118 | |
119 | /** |
120 | * \brief A variable to control whether SDL will pause audio in background |
121 | * (Requires SDL_ANDROID_BLOCK_ON_PAUSE as "Non blocking") |
122 | * |
123 | * The variable can be set to the following values: |
124 | * "0" - Non paused. |
125 | * "1" - Paused. (default) |
126 | * |
127 | * The value should be set before SDL is initialized. |
128 | */ |
129 | #define SDL_HINT_ANDROID_BLOCK_ON_PAUSE_PAUSEAUDIO "SDL_ANDROID_BLOCK_ON_PAUSE_PAUSEAUDIO" |
130 | |
131 | /** |
132 | * \brief A variable to control whether we trap the Android back button to handle it manually. |
133 | * This is necessary for the right mouse button to work on some Android devices, or |
134 | * to be able to trap the back button for use in your code reliably. If set to true, |
135 | * the back button will show up as an SDL_KEYDOWN / SDL_KEYUP pair with a keycode of |
136 | * SDL_SCANCODE_AC_BACK. |
137 | * |
138 | * The variable can be set to the following values: |
139 | * "0" - Back button will be handled as usual for system. (default) |
140 | * "1" - Back button will be trapped, allowing you to handle the key press |
141 | * manually. (This will also let right mouse click work on systems |
142 | * where the right mouse button functions as back.) |
143 | * |
144 | * The value of this hint is used at runtime, so it can be changed at any time. |
145 | */ |
146 | #define SDL_HINT_ANDROID_TRAP_BACK_BUTTON "SDL_ANDROID_TRAP_BACK_BUTTON" |
147 | |
148 | /** |
149 | * \brief Specify an application name. |
150 | * |
151 | * This hint lets you specify the application name sent to the OS when |
152 | * required. For example, this will often appear in volume control applets for |
153 | * audio streams, and in lists of applications which are inhibiting the |
154 | * screensaver. You should use a string that describes your program ("My Game |
155 | * 2: The Revenge") |
156 | * |
157 | * Setting this to "" or leaving it unset will have SDL use a reasonable |
158 | * default: probably the application's name or "SDL Application" if SDL |
159 | * doesn't have any better information. |
160 | * |
161 | * Note that, for audio streams, this can be overridden with |
162 | * SDL_HINT_AUDIO_DEVICE_APP_NAME. |
163 | * |
164 | * On targets where this is not supported, this hint does nothing. |
165 | */ |
166 | #define SDL_HINT_APP_NAME "SDL_APP_NAME" |
167 | |
168 | /** |
169 | * \brief A variable controlling whether controllers used with the Apple TV |
170 | * generate UI events. |
171 | * |
172 | * When UI events are generated by controller input, the app will be |
173 | * backgrounded when the Apple TV remote's menu button is pressed, and when the |
174 | * pause or B buttons on gamepads are pressed. |
175 | * |
176 | * More information about properly making use of controllers for the Apple TV |
177 | * can be found here: |
178 | * https://developer.apple.com/tvos/human-interface-guidelines/remote-and-controllers/ |
179 | * |
180 | * This variable can be set to the following values: |
181 | * "0" - Controller input does not generate UI events (the default). |
182 | * "1" - Controller input generates UI events. |
183 | */ |
184 | #define SDL_HINT_APPLE_TV_CONTROLLER_UI_EVENTS "SDL_APPLE_TV_CONTROLLER_UI_EVENTS" |
185 | |
186 | /** |
187 | * \brief A variable controlling whether the Apple TV remote's joystick axes |
188 | * will automatically match the rotation of the remote. |
189 | * |
190 | * This variable can be set to the following values: |
191 | * "0" - Remote orientation does not affect joystick axes (the default). |
192 | * "1" - Joystick axes are based on the orientation of the remote. |
193 | */ |
194 | #define SDL_HINT_APPLE_TV_REMOTE_ALLOW_ROTATION "SDL_APPLE_TV_REMOTE_ALLOW_ROTATION" |
195 | |
196 | /** |
197 | * \brief A variable controlling the audio category on iOS and Mac OS X |
198 | * |
199 | * This variable can be set to the following values: |
200 | * |
201 | * "ambient" - Use the AVAudioSessionCategoryAmbient audio category, will be muted by the phone mute switch (default) |
202 | * "playback" - Use the AVAudioSessionCategoryPlayback category |
203 | * |
204 | * For more information, see Apple's documentation: |
205 | * https://developer.apple.com/library/content/documentation/Audio/Conceptual/AudioSessionProgrammingGuide/AudioSessionCategoriesandModes/AudioSessionCategoriesandModes.html |
206 | */ |
207 | #define SDL_HINT_AUDIO_CATEGORY "SDL_AUDIO_CATEGORY" |
208 | |
209 | /** |
210 | * \brief Specify an application name for an audio device. |
211 | * |
212 | * Some audio backends (such as PulseAudio) allow you to describe your audio |
213 | * stream. Among other things, this description might show up in a system |
214 | * control panel that lets the user adjust the volume on specific audio |
215 | * streams instead of using one giant master volume slider. |
216 | * |
217 | * This hints lets you transmit that information to the OS. The contents of |
218 | * this hint are used while opening an audio device. You should use a string |
219 | * that describes your program ("My Game 2: The Revenge") |
220 | * |
221 | * Setting this to "" or leaving it unset will have SDL use a reasonable |
222 | * default: this will be the name set with SDL_HINT_APP_NAME, if that hint is |
223 | * set. Otherwise, it'll probably the application's name or "SDL Application" |
224 | * if SDL doesn't have any better information. |
225 | * |
226 | * On targets where this is not supported, this hint does nothing. |
227 | */ |
228 | #define SDL_HINT_AUDIO_DEVICE_APP_NAME "SDL_AUDIO_DEVICE_APP_NAME" |
229 | |
230 | /** |
231 | * \brief Specify an application name for an audio device. |
232 | * |
233 | * Some audio backends (such as PulseAudio) allow you to describe your audio |
234 | * stream. Among other things, this description might show up in a system |
235 | * control panel that lets the user adjust the volume on specific audio |
236 | * streams instead of using one giant master volume slider. |
237 | * |
238 | * This hints lets you transmit that information to the OS. The contents of |
239 | * this hint are used while opening an audio device. You should use a string |
240 | * that describes your what your program is playing ("audio stream" is |
241 | * probably sufficient in many cases, but this could be useful for something |
242 | * like "team chat" if you have a headset playing VoIP audio separately). |
243 | * |
244 | * Setting this to "" or leaving it unset will have SDL use a reasonable |
245 | * default: "audio stream" or something similar. |
246 | * |
247 | * On targets where this is not supported, this hint does nothing. |
248 | */ |
249 | #define SDL_HINT_AUDIO_DEVICE_STREAM_NAME "SDL_AUDIO_DEVICE_STREAM_NAME" |
250 | |
251 | /** |
252 | * \brief Specify an application role for an audio device. |
253 | * |
254 | * Some audio backends (such as Pipewire) allow you to describe the role of |
255 | * your audio stream. Among other things, this description might show up in |
256 | * a system control panel or software for displaying and manipulating media |
257 | * playback/capture graphs. |
258 | * |
259 | * This hints lets you transmit that information to the OS. The contents of |
260 | * this hint are used while opening an audio device. You should use a string |
261 | * that describes your what your program is playing (Game, Music, Movie, |
262 | * etc...). |
263 | * |
264 | * Setting this to "" or leaving it unset will have SDL use a reasonable |
265 | * default: "Game" or something similar. |
266 | * |
267 | * On targets where this is not supported, this hint does nothing. |
268 | */ |
269 | #define SDL_HINT_AUDIO_DEVICE_STREAM_ROLE "SDL_AUDIO_DEVICE_STREAM_ROLE" |
270 | |
271 | /** |
272 | * \brief A variable controlling speed/quality tradeoff of audio resampling. |
273 | * |
274 | * If available, SDL can use libsamplerate ( http://www.mega-nerd.com/SRC/ ) |
275 | * to handle audio resampling. There are different resampling modes available |
276 | * that produce different levels of quality, using more CPU. |
277 | * |
278 | * If this hint isn't specified to a valid setting, or libsamplerate isn't |
279 | * available, SDL will use the default, internal resampling algorithm. |
280 | * |
281 | * As of SDL 2.26, SDL_ConvertAudio() respects this hint when libsamplerate is available. |
282 | * |
283 | * This hint is currently only checked at audio subsystem initialization. |
284 | * |
285 | * This variable can be set to the following values: |
286 | * |
287 | * "0" or "default" - Use SDL's internal resampling (Default when not set - low quality, fast) |
288 | * "1" or "fast" - Use fast, slightly higher quality resampling, if available |
289 | * "2" or "medium" - Use medium quality resampling, if available |
290 | * "3" or "best" - Use high quality resampling, if available |
291 | */ |
292 | #define SDL_HINT_AUDIO_RESAMPLING_MODE "SDL_AUDIO_RESAMPLING_MODE" |
293 | |
294 | /** |
295 | * \brief A variable controlling whether SDL updates joystick state when getting input events |
296 | * |
297 | * This variable can be set to the following values: |
298 | * |
299 | * "0" - You'll call SDL_JoystickUpdate() manually |
300 | * "1" - SDL will automatically call SDL_JoystickUpdate() (default) |
301 | * |
302 | * This hint can be toggled on and off at runtime. |
303 | */ |
304 | #define SDL_HINT_AUTO_UPDATE_JOYSTICKS "SDL_AUTO_UPDATE_JOYSTICKS" |
305 | |
306 | /** |
307 | * \brief A variable controlling whether SDL updates sensor state when getting input events |
308 | * |
309 | * This variable can be set to the following values: |
310 | * |
311 | * "0" - You'll call SDL_SensorUpdate() manually |
312 | * "1" - SDL will automatically call SDL_SensorUpdate() (default) |
313 | * |
314 | * This hint can be toggled on and off at runtime. |
315 | */ |
316 | #define SDL_HINT_AUTO_UPDATE_SENSORS "SDL_AUTO_UPDATE_SENSORS" |
317 | |
318 | /** |
319 | * \brief Prevent SDL from using version 4 of the bitmap header when saving BMPs. |
320 | * |
321 | * The bitmap header version 4 is required for proper alpha channel support and |
322 | * SDL will use it when required. Should this not be desired, this hint can |
323 | * force the use of the 40 byte header version which is supported everywhere. |
324 | * |
325 | * The variable can be set to the following values: |
326 | * "0" - Surfaces with a colorkey or an alpha channel are saved to a |
327 | * 32-bit BMP file with an alpha mask. SDL will use the bitmap |
328 | * header version 4 and set the alpha mask accordingly. |
329 | * "1" - Surfaces with a colorkey or an alpha channel are saved to a |
330 | * 32-bit BMP file without an alpha mask. The alpha channel data |
331 | * will be in the file, but applications are going to ignore it. |
332 | * |
333 | * The default value is "0". |
334 | */ |
335 | #define SDL_HINT_BMP_SAVE_LEGACY_FORMAT "SDL_BMP_SAVE_LEGACY_FORMAT" |
336 | |
337 | /** |
338 | * \brief Override for SDL_GetDisplayUsableBounds() |
339 | * |
340 | * If set, this hint will override the expected results for |
341 | * SDL_GetDisplayUsableBounds() for display index 0. Generally you don't want |
342 | * to do this, but this allows an embedded system to request that some of the |
343 | * screen be reserved for other uses when paired with a well-behaved |
344 | * application. |
345 | * |
346 | * The contents of this hint must be 4 comma-separated integers, the first |
347 | * is the bounds x, then y, width and height, in that order. |
348 | */ |
349 | #define SDL_HINT_DISPLAY_USABLE_BOUNDS "SDL_DISPLAY_USABLE_BOUNDS" |
350 | |
351 | /** |
352 | * \brief Disable giving back control to the browser automatically |
353 | * when running with asyncify |
354 | * |
355 | * With -s ASYNCIFY, SDL2 calls emscripten_sleep during operations |
356 | * such as refreshing the screen or polling events. |
357 | * |
358 | * This hint only applies to the emscripten platform |
359 | * |
360 | * The variable can be set to the following values: |
361 | * "0" - Disable emscripten_sleep calls (if you give back browser control manually or use asyncify for other purposes) |
362 | * "1" - Enable emscripten_sleep calls (the default) |
363 | */ |
364 | #define SDL_HINT_EMSCRIPTEN_ASYNCIFY "SDL_EMSCRIPTEN_ASYNCIFY" |
365 | |
366 | /** |
367 | * \brief override the binding element for keyboard inputs for Emscripten builds |
368 | * |
369 | * This hint only applies to the emscripten platform |
370 | * |
371 | * The variable can be one of |
372 | * "#window" - The javascript window object (this is the default) |
373 | * "#document" - The javascript document object |
374 | * "#screen" - the javascript window.screen object |
375 | * "#canvas" - the WebGL canvas element |
376 | * any other string without a leading # sign applies to the element on the page with that ID. |
377 | */ |
378 | #define SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT "SDL_EMSCRIPTEN_KEYBOARD_ELEMENT" |
379 | |
380 | /** |
381 | * \brief A variable that controls whether the on-screen keyboard should be shown when text input is active |
382 | * |
383 | * The variable can be set to the following values: |
384 | * "0" - Do not show the on-screen keyboard |
385 | * "1" - Show the on-screen keyboard |
386 | * |
387 | * The default value is "1". This hint must be set before text input is activated. |
388 | */ |
389 | #define SDL_HINT_ENABLE_SCREEN_KEYBOARD "SDL_ENABLE_SCREEN_KEYBOARD" |
390 | |
391 | /** |
392 | * \brief A variable that controls whether Steam Controllers should be exposed using the SDL joystick and game controller APIs |
393 | * |
394 | * The variable can be set to the following values: |
395 | * "0" - Do not scan for Steam Controllers |
396 | * "1" - Scan for Steam Controllers (the default) |
397 | * |
398 | * The default value is "1". This hint must be set before initializing the joystick subsystem. |
399 | */ |
400 | #define SDL_HINT_ENABLE_STEAM_CONTROLLERS "SDL_ENABLE_STEAM_CONTROLLERS" |
401 | |
402 | /** |
403 | * \brief A variable controlling verbosity of the logging of SDL events pushed onto the internal queue. |
404 | * |
405 | * This variable can be set to the following values, from least to most verbose: |
406 | * |
407 | * "0" - Don't log any events (default) |
408 | * "1" - Log most events (other than the really spammy ones). |
409 | * "2" - Include mouse and finger motion events. |
410 | * "3" - Include SDL_SysWMEvent events. |
411 | * |
412 | * This is generally meant to be used to debug SDL itself, but can be useful |
413 | * for application developers that need better visibility into what is going |
414 | * on in the event queue. Logged events are sent through SDL_Log(), which |
415 | * means by default they appear on stdout on most platforms or maybe |
416 | * OutputDebugString() on Windows, and can be funneled by the app with |
417 | * SDL_LogSetOutputFunction(), etc. |
418 | * |
419 | * This hint can be toggled on and off at runtime, if you only need to log |
420 | * events for a small subset of program execution. |
421 | */ |
422 | #define SDL_HINT_EVENT_LOGGING "SDL_EVENT_LOGGING" |
423 | |
424 | /** |
425 | * \brief A variable controlling whether raising the window should be done more forcefully |
426 | * |
427 | * This variable can be set to the following values: |
428 | * "0" - No forcing (the default) |
429 | * "1" - Extra level of forcing |
430 | * |
431 | * At present, this is only an issue under MS Windows, which makes it nearly impossible to |
432 | * programmatically move a window to the foreground, for "security" reasons. See |
433 | * http://stackoverflow.com/a/34414846 for a discussion. |
434 | */ |
435 | #define SDL_HINT_FORCE_RAISEWINDOW "SDL_HINT_FORCE_RAISEWINDOW" |
436 | |
437 | /** |
438 | * \brief A variable controlling how 3D acceleration is used to accelerate the SDL screen surface. |
439 | * |
440 | * SDL can try to accelerate the SDL screen surface by using streaming |
441 | * textures with a 3D rendering engine. This variable controls whether and |
442 | * how this is done. |
443 | * |
444 | * This variable can be set to the following values: |
445 | * "0" - Disable 3D acceleration |
446 | * "1" - Enable 3D acceleration, using the default renderer. |
447 | * "X" - Enable 3D acceleration, using X where X is one of the valid rendering drivers. (e.g. "direct3d", "opengl", etc.) |
448 | * |
449 | * By default SDL tries to make a best guess for each platform whether |
450 | * to use acceleration or not. |
451 | */ |
452 | #define SDL_HINT_FRAMEBUFFER_ACCELERATION "SDL_FRAMEBUFFER_ACCELERATION" |
453 | |
454 | /** |
455 | * \brief A variable that lets you manually hint extra gamecontroller db entries. |
456 | * |
457 | * The variable should be newline delimited rows of gamecontroller config data, see SDL_gamecontroller.h |
458 | * |
459 | * This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER) |
460 | * You can update mappings after the system is initialized with SDL_GameControllerMappingForGUID() and SDL_GameControllerAddMapping() |
461 | */ |
462 | #define SDL_HINT_GAMECONTROLLERCONFIG "SDL_GAMECONTROLLERCONFIG" |
463 | |
464 | /** |
465 | * \brief A variable that lets you provide a file with extra gamecontroller db entries. |
466 | * |
467 | * The file should contain lines of gamecontroller config data, see SDL_gamecontroller.h |
468 | * |
469 | * This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER) |
470 | * You can update mappings after the system is initialized with SDL_GameControllerMappingForGUID() and SDL_GameControllerAddMapping() |
471 | */ |
472 | #define SDL_HINT_GAMECONTROLLERCONFIG_FILE "SDL_GAMECONTROLLERCONFIG_FILE" |
473 | |
474 | /** |
475 | * \brief A variable that overrides the automatic controller type detection |
476 | * |
477 | * The variable should be comma separated entries, in the form: VID/PID=type |
478 | * |
479 | * The VID and PID should be hexadecimal with exactly 4 digits, e.g. 0x00fd |
480 | * |
481 | * The type should be one of: |
482 | * Xbox360 |
483 | * XboxOne |
484 | * PS3 |
485 | * PS4 |
486 | * PS5 |
487 | * SwitchPro |
488 | * |
489 | * This hint affects what driver is used, and must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER) |
490 | */ |
491 | #define SDL_HINT_GAMECONTROLLERTYPE "SDL_GAMECONTROLLERTYPE" |
492 | |
493 | /** |
494 | * \brief A variable containing a list of devices to skip when scanning for game controllers. |
495 | * |
496 | * The format of the string is a comma separated list of USB VID/PID pairs |
497 | * in hexadecimal form, e.g. |
498 | * |
499 | * 0xAAAA/0xBBBB,0xCCCC/0xDDDD |
500 | * |
501 | * The variable can also take the form of @file, in which case the named |
502 | * file will be loaded and interpreted as the value of the variable. |
503 | */ |
504 | #define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES "SDL_GAMECONTROLLER_IGNORE_DEVICES" |
505 | |
506 | /** |
507 | * \brief If set, all devices will be skipped when scanning for game controllers except for the ones listed in this variable. |
508 | * |
509 | * The format of the string is a comma separated list of USB VID/PID pairs |
510 | * in hexadecimal form, e.g. |
511 | * |
512 | * 0xAAAA/0xBBBB,0xCCCC/0xDDDD |
513 | * |
514 | * The variable can also take the form of @file, in which case the named |
515 | * file will be loaded and interpreted as the value of the variable. |
516 | */ |
517 | #define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT "SDL_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT" |
518 | |
519 | /** |
520 | * \brief If set, game controller face buttons report their values according to their labels instead of their positional layout. |
521 | * |
522 | * For example, on Nintendo Switch controllers, normally you'd get: |
523 | * |
524 | * (Y) |
525 | * (X) (B) |
526 | * (A) |
527 | * |
528 | * but if this hint is set, you'll get: |
529 | * |
530 | * (X) |
531 | * (Y) (A) |
532 | * (B) |
533 | * |
534 | * The variable can be set to the following values: |
535 | * "0" - Report the face buttons by position, as though they were on an Xbox controller. |
536 | * "1" - Report the face buttons by label instead of position |
537 | * |
538 | * The default value is "1". This hint may be set at any time. |
539 | */ |
540 | #define SDL_HINT_GAMECONTROLLER_USE_BUTTON_LABELS "SDL_GAMECONTROLLER_USE_BUTTON_LABELS" |
541 | |
542 | /** |
543 | * \brief A variable controlling whether grabbing input grabs the keyboard |
544 | * |
545 | * This variable can be set to the following values: |
546 | * "0" - Grab will affect only the mouse |
547 | * "1" - Grab will affect mouse and keyboard |
548 | * |
549 | * By default SDL will not grab the keyboard so system shortcuts still work. |
550 | */ |
551 | #define SDL_HINT_GRAB_KEYBOARD "SDL_GRAB_KEYBOARD" |
552 | |
553 | /** |
554 | * \brief A variable containing a list of devices to ignore in SDL_hid_enumerate() |
555 | * |
556 | * For example, to ignore the Shanwan DS3 controller and any Valve controller, you might |
557 | * have the string "0x2563/0x0523,0x28de/0x0000" |
558 | */ |
559 | #define SDL_HINT_HIDAPI_IGNORE_DEVICES "SDL_HIDAPI_IGNORE_DEVICES" |
560 | |
561 | /** |
562 | * \brief A variable controlling whether the idle timer is disabled on iOS. |
563 | * |
564 | * When an iOS app does not receive touches for some time, the screen is |
565 | * dimmed automatically. For games where the accelerometer is the only input |
566 | * this is problematic. This functionality can be disabled by setting this |
567 | * hint. |
568 | * |
569 | * As of SDL 2.0.4, SDL_EnableScreenSaver() and SDL_DisableScreenSaver() |
570 | * accomplish the same thing on iOS. They should be preferred over this hint. |
571 | * |
572 | * This variable can be set to the following values: |
573 | * "0" - Enable idle timer |
574 | * "1" - Disable idle timer |
575 | */ |
576 | #define SDL_HINT_IDLE_TIMER_DISABLED "SDL_IOS_IDLE_TIMER_DISABLED" |
577 | |
578 | /** |
579 | * \brief A variable to control whether certain IMEs should handle text editing internally instead of sending SDL_TEXTEDITING events. |
580 | * |
581 | * The variable can be set to the following values: |
582 | * "0" - SDL_TEXTEDITING events are sent, and it is the application's |
583 | * responsibility to render the text from these events and |
584 | * differentiate it somehow from committed text. (default) |
585 | * "1" - If supported by the IME then SDL_TEXTEDITING events are not sent, |
586 | * and text that is being composed will be rendered in its own UI. |
587 | */ |
588 | #define SDL_HINT_IME_INTERNAL_EDITING "SDL_IME_INTERNAL_EDITING" |
589 | |
590 | /** |
591 | * \brief A variable to control whether certain IMEs should show native UI components (such as the Candidate List) instead of suppressing them. |
592 | * |
593 | * The variable can be set to the following values: |
594 | * "0" - Native UI components are not display. (default) |
595 | * "1" - Native UI components are displayed. |
596 | */ |
597 | #define SDL_HINT_IME_SHOW_UI "SDL_IME_SHOW_UI" |
598 | |
599 | /** |
600 | * \brief A variable to control if extended IME text support is enabled. |
601 | * If enabled then SDL_TextEditingExtEvent will be issued if the text would be truncated otherwise. |
602 | * Additionally SDL_TextInputEvent will be dispatched multiple times so that it is not truncated. |
603 | * |
604 | * The variable can be set to the following values: |
605 | * "0" - Legacy behavior. Text can be truncated, no heap allocations. (default) |
606 | * "1" - Modern behavior. |
607 | */ |
608 | #define SDL_HINT_IME_SUPPORT_EXTENDED_TEXT "SDL_IME_SUPPORT_EXTENDED_TEXT" |
609 | |
610 | /** |
611 | * \brief A variable controlling whether the home indicator bar on iPhone X |
612 | * should be hidden. |
613 | * |
614 | * This variable can be set to the following values: |
615 | * "0" - The indicator bar is not hidden (default for windowed applications) |
616 | * "1" - The indicator bar is hidden and is shown when the screen is touched (useful for movie playback applications) |
617 | * "2" - The indicator bar is dim and the first swipe makes it visible and the second swipe performs the "home" action (default for fullscreen applications) |
618 | */ |
619 | #define SDL_HINT_IOS_HIDE_HOME_INDICATOR "SDL_IOS_HIDE_HOME_INDICATOR" |
620 | |
621 | /** |
622 | * \brief A variable that lets you enable joystick (and gamecontroller) events even when your app is in the background. |
623 | * |
624 | * The variable can be set to the following values: |
625 | * "0" - Disable joystick & gamecontroller input events when the |
626 | * application is in the background. |
627 | * "1" - Enable joystick & gamecontroller input events when the |
628 | * application is in the background. |
629 | * |
630 | * The default value is "0". This hint may be set at any time. |
631 | */ |
632 | #define SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS "SDL_JOYSTICK_ALLOW_BACKGROUND_EVENTS" |
633 | |
634 | /** |
635 | * A variable containing a list of arcade stick style controllers. |
636 | * |
637 | * The format of the string is a comma separated list of USB VID/PID pairs |
638 | * in hexadecimal form, e.g. |
639 | * |
640 | * 0xAAAA/0xBBBB,0xCCCC/0xDDDD |
641 | * |
642 | * The variable can also take the form of @file, in which case the named |
643 | * file will be loaded and interpreted as the value of the variable. |
644 | */ |
645 | #define SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES "SDL_JOYSTICK_ARCADESTICK_DEVICES" |
646 | |
647 | /** |
648 | * A variable containing a list of devices that are not arcade stick style controllers. This will override SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES and the built in device list. |
649 | * |
650 | * The format of the string is a comma separated list of USB VID/PID pairs |
651 | * in hexadecimal form, e.g. |
652 | * |
653 | * 0xAAAA/0xBBBB,0xCCCC/0xDDDD |
654 | * |
655 | * The variable can also take the form of @file, in which case the named |
656 | * file will be loaded and interpreted as the value of the variable. |
657 | */ |
658 | #define SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED "SDL_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED" |
659 | |
660 | /** |
661 | * A variable containing a list of devices that should not be considerd joysticks. |
662 | * |
663 | * The format of the string is a comma separated list of USB VID/PID pairs |
664 | * in hexadecimal form, e.g. |
665 | * |
666 | * 0xAAAA/0xBBBB,0xCCCC/0xDDDD |
667 | * |
668 | * The variable can also take the form of @file, in which case the named |
669 | * file will be loaded and interpreted as the value of the variable. |
670 | */ |
671 | #define SDL_HINT_JOYSTICK_BLACKLIST_DEVICES "SDL_JOYSTICK_BLACKLIST_DEVICES" |
672 | |
673 | /** |
674 | * A variable containing a list of devices that should be considered joysticks. This will override SDL_HINT_JOYSTICK_BLACKLIST_DEVICES and the built in device list. |
675 | * |
676 | * The format of the string is a comma separated list of USB VID/PID pairs |
677 | * in hexadecimal form, e.g. |
678 | * |
679 | * 0xAAAA/0xBBBB,0xCCCC/0xDDDD |
680 | * |
681 | * The variable can also take the form of @file, in which case the named |
682 | * file will be loaded and interpreted as the value of the variable. |
683 | */ |
684 | #define SDL_HINT_JOYSTICK_BLACKLIST_DEVICES_EXCLUDED "SDL_JOYSTICK_BLACKLIST_DEVICES_EXCLUDED" |
685 | |
686 | /** |
687 | * A variable containing a list of flightstick style controllers. |
688 | * |
689 | * The format of the string is a comma separated list of USB VID/PID pairs |
690 | * in hexadecimal form, e.g. |
691 | * |
692 | * 0xAAAA/0xBBBB,0xCCCC/0xDDDD |
693 | * |
694 | * The variable can also take the form of @file, in which case the named |
695 | * file will be loaded and interpreted as the value of the variable. |
696 | */ |
697 | #define SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES "SDL_JOYSTICK_FLIGHTSTICK_DEVICES" |
698 | |
699 | /** |
700 | * A variable containing a list of devices that are not flightstick style controllers. This will override SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES and the built in device list. |
701 | * |
702 | * The format of the string is a comma separated list of USB VID/PID pairs |
703 | * in hexadecimal form, e.g. |
704 | * |
705 | * 0xAAAA/0xBBBB,0xCCCC/0xDDDD |
706 | * |
707 | * The variable can also take the form of @file, in which case the named |
708 | * file will be loaded and interpreted as the value of the variable. |
709 | */ |
710 | #define SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED "SDL_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED" |
711 | |
712 | /** |
713 | * A variable containing a list of devices known to have a GameCube form factor. |
714 | * |
715 | * The format of the string is a comma separated list of USB VID/PID pairs |
716 | * in hexadecimal form, e.g. |
717 | * |
718 | * 0xAAAA/0xBBBB,0xCCCC/0xDDDD |
719 | * |
720 | * The variable can also take the form of @file, in which case the named |
721 | * file will be loaded and interpreted as the value of the variable. |
722 | */ |
723 | #define SDL_HINT_JOYSTICK_GAMECUBE_DEVICES "SDL_JOYSTICK_GAMECUBE_DEVICES" |
724 | |
725 | /** |
726 | * A variable containing a list of devices known not to have a GameCube form factor. This will override SDL_HINT_JOYSTICK_GAMECUBE_DEVICES and the built in device list. |
727 | * |
728 | * The format of the string is a comma separated list of USB VID/PID pairs |
729 | * in hexadecimal form, e.g. |
730 | * |
731 | * 0xAAAA/0xBBBB,0xCCCC/0xDDDD |
732 | * |
733 | * The variable can also take the form of @file, in which case the named |
734 | * file will be loaded and interpreted as the value of the variable. |
735 | */ |
736 | #define SDL_HINT_JOYSTICK_GAMECUBE_DEVICES_EXCLUDED "SDL_JOYSTICK_GAMECUBE_DEVICES_EXCLUDED" |
737 | |
738 | /** |
739 | * \brief A variable controlling whether the HIDAPI joystick drivers should be used. |
740 | * |
741 | * This variable can be set to the following values: |
742 | * "0" - HIDAPI drivers are not used |
743 | * "1" - HIDAPI drivers are used (the default) |
744 | * |
745 | * This variable is the default for all drivers, but can be overridden by the hints for specific drivers below. |
746 | */ |
747 | #define SDL_HINT_JOYSTICK_HIDAPI "SDL_JOYSTICK_HIDAPI" |
748 | |
749 | /** |
750 | * \brief A variable controlling whether the HIDAPI driver for Nintendo GameCube controllers should be used. |
751 | * |
752 | * This variable can be set to the following values: |
753 | * "0" - HIDAPI driver is not used |
754 | * "1" - HIDAPI driver is used |
755 | * |
756 | * The default is the value of SDL_HINT_JOYSTICK_HIDAPI |
757 | */ |
758 | #define SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE "SDL_JOYSTICK_HIDAPI_GAMECUBE" |
759 | |
760 | /** |
761 | * \brief A variable controlling whether "low_frequency_rumble" and "high_frequency_rumble" is used to implement |
762 | * the GameCube controller's 3 rumble modes, Stop(0), Rumble(1), and StopHard(2) |
763 | * this is useful for applications that need full compatibility for things like ADSR envelopes. |
764 | * Stop is implemented by setting "low_frequency_rumble" to "0" and "high_frequency_rumble" ">0" |
765 | * Rumble is both at any arbitrary value, |
766 | * StopHard is implemented by setting both "low_frequency_rumble" and "high_frequency_rumble" to "0" |
767 | * |
768 | * This variable can be set to the following values: |
769 | * "0" - Normal rumble behavior is behavior is used (default) |
770 | * "1" - Proper GameCube controller rumble behavior is used |
771 | * |
772 | */ |
773 | #define SDL_HINT_JOYSTICK_GAMECUBE_RUMBLE_BRAKE "SDL_JOYSTICK_GAMECUBE_RUMBLE_BRAKE" |
774 | |
775 | /** |
776 | * \brief A variable controlling whether the HIDAPI driver for Nintendo Switch Joy-Cons should be used. |
777 | * |
778 | * This variable can be set to the following values: |
779 | * "0" - HIDAPI driver is not used |
780 | * "1" - HIDAPI driver is used |
781 | * |
782 | * The default is the value of SDL_HINT_JOYSTICK_HIDAPI |
783 | */ |
784 | #define SDL_HINT_JOYSTICK_HIDAPI_JOY_CONS "SDL_JOYSTICK_HIDAPI_JOY_CONS" |
785 | |
786 | /** |
787 | * \brief A variable controlling whether Nintendo Switch Joy-Con controllers will be combined into a single Pro-like controller when using the HIDAPI driver |
788 | * |
789 | * This variable can be set to the following values: |
790 | * "0" - Left and right Joy-Con controllers will not be combined and each will be a mini-gamepad |
791 | * "1" - Left and right Joy-Con controllers will be combined into a single controller (the default) |
792 | */ |
793 | #define SDL_HINT_JOYSTICK_HIDAPI_COMBINE_JOY_CONS "SDL_JOYSTICK_HIDAPI_COMBINE_JOY_CONS" |
794 | |
795 | /** |
796 | * \brief A variable controlling whether Nintendo Switch Joy-Con controllers will be in vertical mode when using the HIDAPI driver |
797 | * |
798 | * This variable can be set to the following values: |
799 | * "0" - Left and right Joy-Con controllers will not be in vertical mode (the default) |
800 | * "1" - Left and right Joy-Con controllers will be in vertical mode |
801 | * |
802 | * This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER) |
803 | */ |
804 | #define SDL_HINT_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS "SDL_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS" |
805 | |
806 | /** |
807 | * \brief A variable controlling whether the HIDAPI driver for Amazon Luna controllers connected via Bluetooth should be used. |
808 | * |
809 | * This variable can be set to the following values: |
810 | * "0" - HIDAPI driver is not used |
811 | * "1" - HIDAPI driver is used |
812 | * |
813 | * The default is the value of SDL_HINT_JOYSTICK_HIDAPI |
814 | */ |
815 | #define SDL_HINT_JOYSTICK_HIDAPI_LUNA "SDL_JOYSTICK_HIDAPI_LUNA" |
816 | |
817 | /** |
818 | * \brief A variable controlling whether the HIDAPI driver for Nintendo Online classic controllers should be used. |
819 | * |
820 | * This variable can be set to the following values: |
821 | * "0" - HIDAPI driver is not used |
822 | * "1" - HIDAPI driver is used |
823 | * |
824 | * The default is the value of SDL_HINT_JOYSTICK_HIDAPI |
825 | */ |
826 | #define SDL_HINT_JOYSTICK_HIDAPI_NINTENDO_CLASSIC "SDL_JOYSTICK_HIDAPI_NINTENDO_CLASSIC" |
827 | |
828 | /** |
829 | * \brief A variable controlling whether the HIDAPI driver for NVIDIA SHIELD controllers should be used. |
830 | * |
831 | * This variable can be set to the following values: |
832 | * "0" - HIDAPI driver is not used |
833 | * "1" - HIDAPI driver is used |
834 | * |
835 | * The default is the value of SDL_HINT_JOYSTICK_HIDAPI |
836 | */ |
837 | #define SDL_HINT_JOYSTICK_HIDAPI_SHIELD "SDL_JOYSTICK_HIDAPI_SHIELD" |
838 | |
839 | /** |
840 | * \brief A variable controlling whether the HIDAPI driver for PS3 controllers should be used. |
841 | * |
842 | * This variable can be set to the following values: |
843 | * "0" - HIDAPI driver is not used |
844 | * "1" - HIDAPI driver is used |
845 | * |
846 | * The default is the value of SDL_HINT_JOYSTICK_HIDAPI on macOS, and "0" on other platforms. |
847 | * |
848 | * It is not possible to use this driver on Windows, due to limitations in the default drivers |
849 | * installed. See https://github.com/ViGEm/DsHidMini for an alternative driver on Windows. |
850 | */ |
851 | #define SDL_HINT_JOYSTICK_HIDAPI_PS3 "SDL_JOYSTICK_HIDAPI_PS3" |
852 | |
853 | /** |
854 | * \brief A variable controlling whether the HIDAPI driver for PS4 controllers should be used. |
855 | * |
856 | * This variable can be set to the following values: |
857 | * "0" - HIDAPI driver is not used |
858 | * "1" - HIDAPI driver is used |
859 | * |
860 | * The default is the value of SDL_HINT_JOYSTICK_HIDAPI |
861 | */ |
862 | #define SDL_HINT_JOYSTICK_HIDAPI_PS4 "SDL_JOYSTICK_HIDAPI_PS4" |
863 | |
864 | /** |
865 | * \brief A variable controlling whether extended input reports should be used for PS4 controllers when using the HIDAPI driver. |
866 | * |
867 | * This variable can be set to the following values: |
868 | * "0" - extended reports are not enabled (the default) |
869 | * "1" - extended reports |
870 | * |
871 | * Extended input reports allow rumble on Bluetooth PS4 controllers, but |
872 | * break DirectInput handling for applications that don't use SDL. |
873 | * |
874 | * Once extended reports are enabled, they can not be disabled without |
875 | * power cycling the controller. |
876 | * |
877 | * For compatibility with applications written for versions of SDL prior |
878 | * to the introduction of PS5 controller support, this value will also |
879 | * control the state of extended reports on PS5 controllers when the |
880 | * SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE hint is not explicitly set. |
881 | */ |
882 | #define SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE "SDL_JOYSTICK_HIDAPI_PS4_RUMBLE" |
883 | |
884 | /** |
885 | * \brief A variable controlling whether the HIDAPI driver for PS5 controllers should be used. |
886 | * |
887 | * This variable can be set to the following values: |
888 | * "0" - HIDAPI driver is not used |
889 | * "1" - HIDAPI driver is used |
890 | * |
891 | * The default is the value of SDL_HINT_JOYSTICK_HIDAPI |
892 | */ |
893 | #define SDL_HINT_JOYSTICK_HIDAPI_PS5 "SDL_JOYSTICK_HIDAPI_PS5" |
894 | |
895 | /** |
896 | * \brief A variable controlling whether the player LEDs should be lit to indicate which player is associated with a PS5 controller. |
897 | * |
898 | * This variable can be set to the following values: |
899 | * "0" - player LEDs are not enabled |
900 | * "1" - player LEDs are enabled (the default) |
901 | */ |
902 | #define SDL_HINT_JOYSTICK_HIDAPI_PS5_PLAYER_LED "SDL_JOYSTICK_HIDAPI_PS5_PLAYER_LED" |
903 | |
904 | /** |
905 | * \brief A variable controlling whether extended input reports should be used for PS5 controllers when using the HIDAPI driver. |
906 | * |
907 | * This variable can be set to the following values: |
908 | * "0" - extended reports are not enabled (the default) |
909 | * "1" - extended reports |
910 | * |
911 | * Extended input reports allow rumble on Bluetooth PS5 controllers, but |
912 | * break DirectInput handling for applications that don't use SDL. |
913 | * |
914 | * Once extended reports are enabled, they can not be disabled without |
915 | * power cycling the controller. |
916 | * |
917 | * For compatibility with applications written for versions of SDL prior |
918 | * to the introduction of PS5 controller support, this value defaults to |
919 | * the value of SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE. |
920 | */ |
921 | #define SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE "SDL_JOYSTICK_HIDAPI_PS5_RUMBLE" |
922 | |
923 | /** |
924 | * \brief A variable controlling whether the HIDAPI driver for Google Stadia controllers should be used. |
925 | * |
926 | * This variable can be set to the following values: |
927 | * "0" - HIDAPI driver is not used |
928 | * "1" - HIDAPI driver is used |
929 | * |
930 | * The default is the value of SDL_HINT_JOYSTICK_HIDAPI |
931 | */ |
932 | #define SDL_HINT_JOYSTICK_HIDAPI_STADIA "SDL_JOYSTICK_HIDAPI_STADIA" |
933 | |
934 | /** |
935 | * \brief A variable controlling whether the HIDAPI driver for Bluetooth Steam Controllers should be used. |
936 | * |
937 | * This variable can be set to the following values: |
938 | * "0" - HIDAPI driver is not used |
939 | * "1" - HIDAPI driver is used for Steam Controllers, which requires Bluetooth access |
940 | * and may prompt the user for permission on iOS and Android. |
941 | * |
942 | * The default is "0" |
943 | */ |
944 | #define SDL_HINT_JOYSTICK_HIDAPI_STEAM "SDL_JOYSTICK_HIDAPI_STEAM" |
945 | |
946 | /** |
947 | * \brief A variable controlling whether the HIDAPI driver for the Steam Deck builtin controller should be used. |
948 | * |
949 | * This variable can be set to the following values: |
950 | * "0" - HIDAPI driver is not used |
951 | * "1" - HIDAPI driver is used |
952 | * |
953 | * The default is the value of SDL_HINT_JOYSTICK_HIDAPI |
954 | */ |
955 | #define SDL_HINT_JOYSTICK_HIDAPI_STEAMDECK "SDL_JOYSTICK_HIDAPI_STEAMDECK" |
956 | |
957 | /** |
958 | * \brief A variable controlling whether the HIDAPI driver for Nintendo Switch controllers should be used. |
959 | * |
960 | * This variable can be set to the following values: |
961 | * "0" - HIDAPI driver is not used |
962 | * "1" - HIDAPI driver is used |
963 | * |
964 | * The default is the value of SDL_HINT_JOYSTICK_HIDAPI |
965 | */ |
966 | #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH "SDL_JOYSTICK_HIDAPI_SWITCH" |
967 | |
968 | /** |
969 | * \brief A variable controlling whether the Home button LED should be turned on when a Nintendo Switch Pro controller is opened |
970 | * |
971 | * This variable can be set to the following values: |
972 | * "0" - home button LED is turned off |
973 | * "1" - home button LED is turned on |
974 | * |
975 | * By default the Home button LED state is not changed. This hint can also be set to a floating point value between 0.0 and 1.0 which controls the brightness of the Home button LED. |
976 | */ |
977 | #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH_HOME_LED "SDL_JOYSTICK_HIDAPI_SWITCH_HOME_LED" |
978 | |
979 | /** |
980 | * \brief A variable controlling whether the Home button LED should be turned on when a Nintendo Switch Joy-Con controller is opened |
981 | * |
982 | * This variable can be set to the following values: |
983 | * "0" - home button LED is turned off |
984 | * "1" - home button LED is turned on |
985 | * |
986 | * By default the Home button LED state is not changed. This hint can also be set to a floating point value between 0.0 and 1.0 which controls the brightness of the Home button LED. |
987 | */ |
988 | #define SDL_HINT_JOYSTICK_HIDAPI_JOYCON_HOME_LED "SDL_JOYSTICK_HIDAPI_JOYCON_HOME_LED" |
989 | |
990 | /** |
991 | * \brief A variable controlling whether the player LEDs should be lit to indicate which player is associated with a Nintendo Switch controller. |
992 | * |
993 | * This variable can be set to the following values: |
994 | * "0" - player LEDs are not enabled |
995 | * "1" - player LEDs are enabled (the default) |
996 | */ |
997 | #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED "SDL_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED" |
998 | |
999 | /** |
1000 | * \brief A variable controlling whether the HIDAPI driver for Nintendo Wii and Wii U controllers should be used. |
1001 | * |
1002 | * This variable can be set to the following values: |
1003 | * "0" - HIDAPI driver is not used |
1004 | * "1" - HIDAPI driver is used |
1005 | * |
1006 | * This driver doesn't work with the dolphinbar, so the default is SDL_FALSE for now. |
1007 | */ |
1008 | #define SDL_HINT_JOYSTICK_HIDAPI_WII "SDL_JOYSTICK_HIDAPI_WII" |
1009 | |
1010 | /** |
1011 | * \brief A variable controlling whether the player LEDs should be lit to indicate which player is associated with a Wii controller. |
1012 | * |
1013 | * This variable can be set to the following values: |
1014 | * "0" - player LEDs are not enabled |
1015 | * "1" - player LEDs are enabled (the default) |
1016 | */ |
1017 | #define SDL_HINT_JOYSTICK_HIDAPI_WII_PLAYER_LED "SDL_JOYSTICK_HIDAPI_WII_PLAYER_LED" |
1018 | |
1019 | /** |
1020 | * \brief A variable controlling whether the HIDAPI driver for XBox controllers should be used. |
1021 | * |
1022 | * This variable can be set to the following values: |
1023 | * "0" - HIDAPI driver is not used |
1024 | * "1" - HIDAPI driver is used |
1025 | * |
1026 | * The default is "0" on Windows, otherwise the value of SDL_HINT_JOYSTICK_HIDAPI |
1027 | */ |
1028 | #define SDL_HINT_JOYSTICK_HIDAPI_XBOX "SDL_JOYSTICK_HIDAPI_XBOX" |
1029 | |
1030 | /** |
1031 | * \brief A variable controlling whether the HIDAPI driver for XBox 360 controllers should be used. |
1032 | * |
1033 | * This variable can be set to the following values: |
1034 | * "0" - HIDAPI driver is not used |
1035 | * "1" - HIDAPI driver is used |
1036 | * |
1037 | * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX |
1038 | */ |
1039 | #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 "SDL_JOYSTICK_HIDAPI_XBOX_360" |
1040 | |
1041 | /** |
1042 | * \brief A variable controlling whether the player LEDs should be lit to indicate which player is associated with an Xbox 360 controller. |
1043 | * |
1044 | * This variable can be set to the following values: |
1045 | * "0" - player LEDs are not enabled |
1046 | * "1" - player LEDs are enabled (the default) |
1047 | */ |
1048 | #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED "SDL_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED" |
1049 | |
1050 | /** |
1051 | * \brief A variable controlling whether the HIDAPI driver for XBox 360 wireless controllers should be used. |
1052 | * |
1053 | * This variable can be set to the following values: |
1054 | * "0" - HIDAPI driver is not used |
1055 | * "1" - HIDAPI driver is used |
1056 | * |
1057 | * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 |
1058 | */ |
1059 | #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_WIRELESS "SDL_JOYSTICK_HIDAPI_XBOX_360_WIRELESS" |
1060 | |
1061 | /** |
1062 | * \brief A variable controlling whether the HIDAPI driver for XBox One controllers should be used. |
1063 | * |
1064 | * This variable can be set to the following values: |
1065 | * "0" - HIDAPI driver is not used |
1066 | * "1" - HIDAPI driver is used |
1067 | * |
1068 | * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX |
1069 | */ |
1070 | #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE "SDL_JOYSTICK_HIDAPI_XBOX_ONE" |
1071 | |
1072 | /** |
1073 | * \brief A variable controlling whether the Home button LED should be turned on when an Xbox One controller is opened |
1074 | * |
1075 | * This variable can be set to the following values: |
1076 | * "0" - home button LED is turned off |
1077 | * "1" - home button LED is turned on |
1078 | * |
1079 | * By default the Home button LED state is not changed. This hint can also be set to a floating point value between 0.0 and 1.0 which controls the brightness of the Home button LED. The default brightness is 0.4. |
1080 | */ |
1081 | #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED "SDL_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED" |
1082 | |
1083 | /** |
1084 | * A variable controlling whether IOKit should be used for controller handling. |
1085 | * |
1086 | * This variable can be set to the following values: |
1087 | * "0" - IOKit is not used |
1088 | * "1" - IOKit is used (the default) |
1089 | */ |
1090 | #define SDL_HINT_JOYSTICK_IOKIT "SDL_JOYSTICK_IOKIT" |
1091 | |
1092 | /** |
1093 | * A variable controlling whether GCController should be used for controller handling. |
1094 | * |
1095 | * This variable can be set to the following values: |
1096 | * "0" - GCController is not used |
1097 | * "1" - GCController is used (the default) |
1098 | */ |
1099 | #define SDL_HINT_JOYSTICK_MFI "SDL_JOYSTICK_MFI" |
1100 | |
1101 | /** |
1102 | * \brief A variable controlling whether the RAWINPUT joystick drivers should be used for better handling XInput-capable devices. |
1103 | * |
1104 | * This variable can be set to the following values: |
1105 | * "0" - RAWINPUT drivers are not used |
1106 | * "1" - RAWINPUT drivers are used (the default) |
1107 | */ |
1108 | #define SDL_HINT_JOYSTICK_RAWINPUT "SDL_JOYSTICK_RAWINPUT" |
1109 | |
1110 | /** |
1111 | * \brief A variable controlling whether the RAWINPUT driver should pull correlated data from XInput. |
1112 | * |
1113 | * This variable can be set to the following values: |
1114 | * "0" - RAWINPUT driver will only use data from raw input APIs |
1115 | * "1" - RAWINPUT driver will also pull data from XInput, providing |
1116 | * better trigger axes, guide button presses, and rumble support |
1117 | * for Xbox controllers |
1118 | * |
1119 | * The default is "1". This hint applies to any joysticks opened after setting the hint. |
1120 | */ |
1121 | #define SDL_HINT_JOYSTICK_RAWINPUT_CORRELATE_XINPUT "SDL_JOYSTICK_RAWINPUT_CORRELATE_XINPUT" |
1122 | |
1123 | /** |
1124 | * \brief A variable controlling whether the ROG Chakram mice should show up as joysticks |
1125 | * |
1126 | * This variable can be set to the following values: |
1127 | * "0" - ROG Chakram mice do not show up as joysticks (the default) |
1128 | * "1" - ROG Chakram mice show up as joysticks |
1129 | */ |
1130 | #define SDL_HINT_JOYSTICK_ROG_CHAKRAM "SDL_JOYSTICK_ROG_CHAKRAM" |
1131 | |
1132 | /** |
1133 | * \brief A variable controlling whether a separate thread should be used |
1134 | * for handling joystick detection and raw input messages on Windows |
1135 | * |
1136 | * This variable can be set to the following values: |
1137 | * "0" - A separate thread is not used (the default) |
1138 | * "1" - A separate thread is used for handling raw input messages |
1139 | * |
1140 | */ |
1141 | #define SDL_HINT_JOYSTICK_THREAD "SDL_JOYSTICK_THREAD" |
1142 | |
1143 | /** |
1144 | * A variable containing a list of throttle style controllers. |
1145 | * |
1146 | * The format of the string is a comma separated list of USB VID/PID pairs |
1147 | * in hexadecimal form, e.g. |
1148 | * |
1149 | * 0xAAAA/0xBBBB,0xCCCC/0xDDDD |
1150 | * |
1151 | * The variable can also take the form of @file, in which case the named |
1152 | * file will be loaded and interpreted as the value of the variable. |
1153 | */ |
1154 | #define SDL_HINT_JOYSTICK_THROTTLE_DEVICES "SDL_JOYSTICK_THROTTLE_DEVICES" |
1155 | |
1156 | /** |
1157 | * A variable containing a list of devices that are not throttle style controllers. This will override SDL_HINT_JOYSTICK_THROTTLE_DEVICES and the built in device list. |
1158 | * |
1159 | * The format of the string is a comma separated list of USB VID/PID pairs |
1160 | * in hexadecimal form, e.g. |
1161 | * |
1162 | * 0xAAAA/0xBBBB,0xCCCC/0xDDDD |
1163 | * |
1164 | * The variable can also take the form of @file, in which case the named |
1165 | * file will be loaded and interpreted as the value of the variable. |
1166 | */ |
1167 | #define SDL_HINT_JOYSTICK_THROTTLE_DEVICES_EXCLUDED "SDL_JOYSTICK_THROTTLE_DEVICES_EXCLUDED" |
1168 | |
1169 | /** |
1170 | * \brief A variable controlling whether Windows.Gaming.Input should be used for controller handling. |
1171 | * |
1172 | * This variable can be set to the following values: |
1173 | * "0" - WGI is not used |
1174 | * "1" - WGI is used (the default) |
1175 | */ |
1176 | #define SDL_HINT_JOYSTICK_WGI "SDL_JOYSTICK_WGI" |
1177 | |
1178 | /** |
1179 | * A variable containing a list of wheel style controllers. |
1180 | * |
1181 | * The format of the string is a comma separated list of USB VID/PID pairs |
1182 | * in hexadecimal form, e.g. |
1183 | * |
1184 | * 0xAAAA/0xBBBB,0xCCCC/0xDDDD |
1185 | * |
1186 | * The variable can also take the form of @file, in which case the named |
1187 | * file will be loaded and interpreted as the value of the variable. |
1188 | */ |
1189 | #define SDL_HINT_JOYSTICK_WHEEL_DEVICES "SDL_JOYSTICK_WHEEL_DEVICES" |
1190 | |
1191 | /** |
1192 | * A variable containing a list of devices that are not wheel style controllers. This will override SDL_HINT_JOYSTICK_WHEEL_DEVICES and the built in device list. |
1193 | * |
1194 | * The format of the string is a comma separated list of USB VID/PID pairs |
1195 | * in hexadecimal form, e.g. |
1196 | * |
1197 | * 0xAAAA/0xBBBB,0xCCCC/0xDDDD |
1198 | * |
1199 | * The variable can also take the form of @file, in which case the named |
1200 | * file will be loaded and interpreted as the value of the variable. |
1201 | */ |
1202 | #define SDL_HINT_JOYSTICK_WHEEL_DEVICES_EXCLUDED "SDL_JOYSTICK_WHEEL_DEVICES_EXCLUDED" |
1203 | |
1204 | /** |
1205 | * A variable containing a list of devices known to have all axes centered at zero. |
1206 | * |
1207 | * The format of the string is a comma separated list of USB VID/PID pairs |
1208 | * in hexadecimal form, e.g. |
1209 | * |
1210 | * 0xAAAA/0xBBBB,0xCCCC/0xDDDD |
1211 | * |
1212 | * The variable can also take the form of @file, in which case the named |
1213 | * file will be loaded and interpreted as the value of the variable. |
1214 | */ |
1215 | #define SDL_HINT_JOYSTICK_ZERO_CENTERED_DEVICES "SDL_JOYSTICK_ZERO_CENTERED_DEVICES" |
1216 | |
1217 | /** |
1218 | * \brief Determines whether SDL enforces that DRM master is required in order |
1219 | * to initialize the KMSDRM video backend. |
1220 | * |
1221 | * The DRM subsystem has a concept of a "DRM master" which is a DRM client that |
1222 | * has the ability to set planes, set cursor, etc. When SDL is DRM master, it |
1223 | * can draw to the screen using the SDL rendering APIs. Without DRM master, SDL |
1224 | * is still able to process input and query attributes of attached displays, |
1225 | * but it cannot change display state or draw to the screen directly. |
1226 | * |
1227 | * In some cases, it can be useful to have the KMSDRM backend even if it cannot |
1228 | * be used for rendering. An app may want to use SDL for input processing while |
1229 | * using another rendering API (such as an MMAL overlay on Raspberry Pi) or |
1230 | * using its own code to render to DRM overlays that SDL doesn't support. |
1231 | * |
1232 | * This hint must be set before initializing the video subsystem. |
1233 | * |
1234 | * This variable can be set to the following values: |
1235 | * "0" - SDL will allow usage of the KMSDRM backend without DRM master |
1236 | * "1" - SDL Will require DRM master to use the KMSDRM backend (default) |
1237 | */ |
1238 | #define SDL_HINT_KMSDRM_REQUIRE_DRM_MASTER "SDL_KMSDRM_REQUIRE_DRM_MASTER" |
1239 | |
1240 | /** |
1241 | * \brief A comma separated list of devices to open as joysticks |
1242 | * |
1243 | * This variable is currently only used by the Linux joystick driver. |
1244 | */ |
1245 | #define SDL_HINT_JOYSTICK_DEVICE "SDL_JOYSTICK_DEVICE" |
1246 | |
1247 | /** |
1248 | * \brief A variable controlling whether joysticks on Linux will always treat 'hat' axis inputs (ABS_HAT0X - ABS_HAT3Y) as 8-way digital hats without checking whether they may be analog. |
1249 | * |
1250 | * This variable can be set to the following values: |
1251 | * "0" - Only map hat axis inputs to digital hat outputs if the input axes appear to actually be digital (the default) |
1252 | * "1" - Always handle the input axes numbered ABS_HAT0X to ABS_HAT3Y as digital hats |
1253 | */ |
1254 | #define SDL_HINT_LINUX_DIGITAL_HATS "SDL_LINUX_DIGITAL_HATS" |
1255 | |
1256 | /** |
1257 | * \brief A variable controlling whether digital hats on Linux will apply deadzones to their underlying input axes or use unfiltered values. |
1258 | * |
1259 | * This variable can be set to the following values: |
1260 | * "0" - Return digital hat values based on unfiltered input axis values |
1261 | * "1" - Return digital hat values with deadzones on the input axes taken into account (the default) |
1262 | */ |
1263 | #define SDL_HINT_LINUX_HAT_DEADZONES "SDL_LINUX_HAT_DEADZONES" |
1264 | |
1265 | /** |
1266 | * \brief A variable controlling whether to use the classic /dev/input/js* joystick interface or the newer /dev/input/event* joystick interface on Linux |
1267 | * |
1268 | * This variable can be set to the following values: |
1269 | * "0" - Use /dev/input/event* |
1270 | * "1" - Use /dev/input/js* |
1271 | * |
1272 | * By default the /dev/input/event* interfaces are used |
1273 | */ |
1274 | #define SDL_HINT_LINUX_JOYSTICK_CLASSIC "SDL_LINUX_JOYSTICK_CLASSIC" |
1275 | |
1276 | /** |
1277 | * \brief A variable controlling whether joysticks on Linux adhere to their HID-defined deadzones or return unfiltered values. |
1278 | * |
1279 | * This variable can be set to the following values: |
1280 | * "0" - Return unfiltered joystick axis values (the default) |
1281 | * "1" - Return axis values with deadzones taken into account |
1282 | */ |
1283 | #define SDL_HINT_LINUX_JOYSTICK_DEADZONES "SDL_LINUX_JOYSTICK_DEADZONES" |
1284 | |
1285 | /** |
1286 | * \brief A variable controlling the default SDL log levels. |
1287 | * |
1288 | * This variable is a comma separated set of category=level tokens that define the default logging levels for SDL applications. |
1289 | * |
1290 | * The category can be a numeric category, one of "app", "error", "assert", "system", "audio", "video", "render", "input", "test", or `*` for any unspecified category. |
1291 | * |
1292 | * The level can be a numeric level, one of "verbose", "debug", "info", "warn", "error", "critical", or "quiet" to disable that category. |
1293 | * |
1294 | * You can omit the category if you want to set the logging level for all categories. |
1295 | * |
1296 | * If this hint isn't set, the default log levels are equivalent to: |
1297 | * "app=info,assert=warn,test=verbose,*=error" |
1298 | */ |
1299 | #define SDL_HINT_LOGGING "SDL_LOGGING" |
1300 | |
1301 | /** |
1302 | * \brief When set don't force the SDL app to become a foreground process |
1303 | * |
1304 | * This hint only applies to Mac OS X. |
1305 | * |
1306 | */ |
1307 | #define SDL_HINT_MAC_BACKGROUND_APP "SDL_MAC_BACKGROUND_APP" |
1308 | |
1309 | /** |
1310 | * \brief A variable that determines whether ctrl+click should generate a right-click event on Mac |
1311 | * |
1312 | * If present, holding ctrl while left clicking will generate a right click |
1313 | * event when on Mac. |
1314 | */ |
1315 | #define SDL_HINT_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK "SDL_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK" |
1316 | |
1317 | /** |
1318 | * \brief A variable controlling whether dispatching OpenGL context updates should block the dispatching thread until the main thread finishes processing |
1319 | * |
1320 | * This variable can be set to the following values: |
1321 | * "0" - Dispatching OpenGL context updates will block the dispatching thread until the main thread finishes processing (default). |
1322 | * "1" - Dispatching OpenGL context updates will allow the dispatching thread to continue execution. |
1323 | * |
1324 | * Generally you want the default, but if you have OpenGL code in a background thread on a Mac, and the main thread |
1325 | * hangs because it's waiting for that background thread, but that background thread is also hanging because it's |
1326 | * waiting for the main thread to do an update, this might fix your issue. |
1327 | * |
1328 | * This hint only applies to macOS. |
1329 | * |
1330 | * This hint is available since SDL 2.24.0. |
1331 | * |
1332 | */ |
1333 | #define SDL_HINT_MAC_OPENGL_ASYNC_DISPATCH "SDL_MAC_OPENGL_ASYNC_DISPATCH" |
1334 | |
1335 | /** |
1336 | * \brief A variable setting the double click radius, in pixels. |
1337 | */ |
1338 | #define SDL_HINT_MOUSE_DOUBLE_CLICK_RADIUS "SDL_MOUSE_DOUBLE_CLICK_RADIUS" |
1339 | |
1340 | /** |
1341 | * \brief A variable setting the double click time, in milliseconds. |
1342 | */ |
1343 | #define SDL_HINT_MOUSE_DOUBLE_CLICK_TIME "SDL_MOUSE_DOUBLE_CLICK_TIME" |
1344 | |
1345 | /** |
1346 | * \brief Allow mouse click events when clicking to focus an SDL window |
1347 | * |
1348 | * This variable can be set to the following values: |
1349 | * "0" - Ignore mouse clicks that activate a window |
1350 | * "1" - Generate events for mouse clicks that activate a window |
1351 | * |
1352 | * By default SDL will ignore mouse clicks that activate a window |
1353 | */ |
1354 | #define SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH "SDL_MOUSE_FOCUS_CLICKTHROUGH" |
1355 | |
1356 | /** |
1357 | * \brief A variable setting the speed scale for mouse motion, in floating point, when the mouse is not in relative mode |
1358 | */ |
1359 | #define SDL_HINT_MOUSE_NORMAL_SPEED_SCALE "SDL_MOUSE_NORMAL_SPEED_SCALE" |
1360 | |
1361 | /** |
1362 | * \brief A variable controlling whether relative mouse mode constrains the mouse to the center of the window |
1363 | * |
1364 | * This variable can be set to the following values: |
1365 | * "0" - Relative mouse mode constrains the mouse to the window |
1366 | * "1" - Relative mouse mode constrains the mouse to the center of the window |
1367 | * |
1368 | * Constraining to the center of the window works better for FPS games and when the |
1369 | * application is running over RDP. Constraining to the whole window works better |
1370 | * for 2D games and increases the chance that the mouse will be in the correct |
1371 | * position when using high DPI mice. |
1372 | * |
1373 | * By default SDL will constrain the mouse to the center of the window |
1374 | */ |
1375 | #define SDL_HINT_MOUSE_RELATIVE_MODE_CENTER "SDL_MOUSE_RELATIVE_MODE_CENTER" |
1376 | |
1377 | /** |
1378 | * \brief A variable controlling whether relative mouse mode is implemented using mouse warping |
1379 | * |
1380 | * This variable can be set to the following values: |
1381 | * "0" - Relative mouse mode uses raw input |
1382 | * "1" - Relative mouse mode uses mouse warping |
1383 | * |
1384 | * By default SDL will use raw input for relative mouse mode |
1385 | */ |
1386 | #define SDL_HINT_MOUSE_RELATIVE_MODE_WARP "SDL_MOUSE_RELATIVE_MODE_WARP" |
1387 | |
1388 | /** |
1389 | * \brief A variable controlling whether relative mouse motion is affected by renderer scaling |
1390 | * |
1391 | * This variable can be set to the following values: |
1392 | * "0" - Relative motion is unaffected by DPI or renderer's logical size |
1393 | * "1" - Relative motion is scaled according to DPI scaling and logical size |
1394 | * |
1395 | * By default relative mouse deltas are affected by DPI and renderer scaling |
1396 | */ |
1397 | #define SDL_HINT_MOUSE_RELATIVE_SCALING "SDL_MOUSE_RELATIVE_SCALING" |
1398 | |
1399 | /** |
1400 | * \brief A variable setting the scale for mouse motion, in floating point, when the mouse is in relative mode |
1401 | */ |
1402 | #define SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE "SDL_MOUSE_RELATIVE_SPEED_SCALE" |
1403 | |
1404 | /** |
1405 | * \brief A variable controlling whether the system mouse acceleration curve is used for relative mouse motion. |
1406 | * |
1407 | * This variable can be set to the following values: |
1408 | * "0" - Relative mouse motion will be unscaled (the default) |
1409 | * "1" - Relative mouse motion will be scaled using the system mouse acceleration curve. |
1410 | * |
1411 | * If SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE is set, that will override the system speed scale. |
1412 | */ |
1413 | #define SDL_HINT_MOUSE_RELATIVE_SYSTEM_SCALE "SDL_MOUSE_RELATIVE_SYSTEM_SCALE" |
1414 | |
1415 | /** |
1416 | * \brief A variable controlling whether a motion event should be generated for mouse warping in relative mode. |
1417 | * |
1418 | * This variable can be set to the following values: |
1419 | * "0" - Warping the mouse will not generate a motion event in relative mode |
1420 | * "1" - Warping the mouse will generate a motion event in relative mode |
1421 | * |
1422 | * By default warping the mouse will not generate motion events in relative mode. This avoids the application having to filter out large relative motion due to warping. |
1423 | */ |
1424 | #define SDL_HINT_MOUSE_RELATIVE_WARP_MOTION "SDL_MOUSE_RELATIVE_WARP_MOTION" |
1425 | |
1426 | /** |
1427 | * \brief A variable controlling whether mouse events should generate synthetic touch events |
1428 | * |
1429 | * This variable can be set to the following values: |
1430 | * "0" - Mouse events will not generate touch events (default for desktop platforms) |
1431 | * "1" - Mouse events will generate touch events (default for mobile platforms, such as Android and iOS) |
1432 | */ |
1433 | #define SDL_HINT_MOUSE_TOUCH_EVENTS "SDL_MOUSE_TOUCH_EVENTS" |
1434 | |
1435 | /** |
1436 | * \brief A variable controlling whether the mouse is captured while mouse buttons are pressed |
1437 | * |
1438 | * This variable can be set to the following values: |
1439 | * "0" - The mouse is not captured while mouse buttons are pressed |
1440 | * "1" - The mouse is captured while mouse buttons are pressed |
1441 | * |
1442 | * By default the mouse is captured while mouse buttons are pressed so if the mouse is dragged |
1443 | * outside the window, the application continues to receive mouse events until the button is |
1444 | * released. |
1445 | */ |
1446 | #define SDL_HINT_MOUSE_AUTO_CAPTURE "SDL_MOUSE_AUTO_CAPTURE" |
1447 | |
1448 | /** |
1449 | * \brief Tell SDL not to catch the SIGINT or SIGTERM signals. |
1450 | * |
1451 | * This hint only applies to Unix-like platforms, and should set before |
1452 | * any calls to SDL_Init() |
1453 | * |
1454 | * The variable can be set to the following values: |
1455 | * "0" - SDL will install a SIGINT and SIGTERM handler, and when it |
1456 | * catches a signal, convert it into an SDL_QUIT event. |
1457 | * "1" - SDL will not install a signal handler at all. |
1458 | */ |
1459 | #define SDL_HINT_NO_SIGNAL_HANDLERS "SDL_NO_SIGNAL_HANDLERS" |
1460 | |
1461 | /** |
1462 | * \brief A variable controlling what driver to use for OpenGL ES contexts. |
1463 | * |
1464 | * On some platforms, currently Windows and X11, OpenGL drivers may support |
1465 | * creating contexts with an OpenGL ES profile. By default SDL uses these |
1466 | * profiles, when available, otherwise it attempts to load an OpenGL ES |
1467 | * library, e.g. that provided by the ANGLE project. This variable controls |
1468 | * whether SDL follows this default behaviour or will always load an |
1469 | * OpenGL ES library. |
1470 | * |
1471 | * Circumstances where this is useful include |
1472 | * - Testing an app with a particular OpenGL ES implementation, e.g ANGLE, |
1473 | * or emulator, e.g. those from ARM, Imagination or Qualcomm. |
1474 | * - Resolving OpenGL ES function addresses at link time by linking with |
1475 | * the OpenGL ES library instead of querying them at run time with |
1476 | * SDL_GL_GetProcAddress(). |
1477 | * |
1478 | * Caution: for an application to work with the default behaviour across |
1479 | * different OpenGL drivers it must query the OpenGL ES function |
1480 | * addresses at run time using SDL_GL_GetProcAddress(). |
1481 | * |
1482 | * This variable is ignored on most platforms because OpenGL ES is native |
1483 | * or not supported. |
1484 | * |
1485 | * This variable can be set to the following values: |
1486 | * "0" - Use ES profile of OpenGL, if available. (Default when not set.) |
1487 | * "1" - Load OpenGL ES library using the default library names. |
1488 | * |
1489 | */ |
1490 | #define SDL_HINT_OPENGL_ES_DRIVER "SDL_OPENGL_ES_DRIVER" |
1491 | |
1492 | /** |
1493 | * \brief A variable controlling which orientations are allowed on iOS/Android. |
1494 | * |
1495 | * In some circumstances it is necessary to be able to explicitly control |
1496 | * which UI orientations are allowed. |
1497 | * |
1498 | * This variable is a space delimited list of the following values: |
1499 | * "LandscapeLeft", "LandscapeRight", "Portrait" "PortraitUpsideDown" |
1500 | */ |
1501 | #define SDL_HINT_ORIENTATIONS "SDL_IOS_ORIENTATIONS" |
1502 | |
1503 | /** |
1504 | * \brief A variable controlling the use of a sentinel event when polling the event queue |
1505 | * |
1506 | * This variable can be set to the following values: |
1507 | * "0" - Disable poll sentinels |
1508 | * "1" - Enable poll sentinels |
1509 | * |
1510 | * When polling for events, SDL_PumpEvents is used to gather new events from devices. |
1511 | * If a device keeps producing new events between calls to SDL_PumpEvents, a poll loop will |
1512 | * become stuck until the new events stop. |
1513 | * This is most noticeable when moving a high frequency mouse. |
1514 | * |
1515 | * By default, poll sentinels are enabled. |
1516 | */ |
1517 | #define SDL_HINT_POLL_SENTINEL "SDL_POLL_SENTINEL" |
1518 | |
1519 | /** |
1520 | * \brief Override for SDL_GetPreferredLocales() |
1521 | * |
1522 | * If set, this will be favored over anything the OS might report for the |
1523 | * user's preferred locales. Changing this hint at runtime will not generate |
1524 | * a SDL_LOCALECHANGED event (but if you can change the hint, you can push |
1525 | * your own event, if you want). |
1526 | * |
1527 | * The format of this hint is a comma-separated list of language and locale, |
1528 | * combined with an underscore, as is a common format: "en_GB". Locale is |
1529 | * optional: "en". So you might have a list like this: "en_GB,jp,es_PT" |
1530 | */ |
1531 | #define SDL_HINT_PREFERRED_LOCALES "SDL_PREFERRED_LOCALES" |
1532 | |
1533 | /** |
1534 | * \brief A variable describing the content orientation on QtWayland-based platforms. |
1535 | * |
1536 | * On QtWayland platforms, windows are rotated client-side to allow for custom |
1537 | * transitions. In order to correctly position overlays (e.g. volume bar) and |
1538 | * gestures (e.g. events view, close/minimize gestures), the system needs to |
1539 | * know in which orientation the application is currently drawing its contents. |
1540 | * |
1541 | * This does not cause the window to be rotated or resized, the application |
1542 | * needs to take care of drawing the content in the right orientation (the |
1543 | * framebuffer is always in portrait mode). |
1544 | * |
1545 | * This variable can be one of the following values: |
1546 | * "primary" (default), "portrait", "landscape", "inverted-portrait", "inverted-landscape" |
1547 | * |
1548 | * Since SDL 2.0.22 this variable accepts a comma-separated list of values above. |
1549 | */ |
1550 | #define SDL_HINT_QTWAYLAND_CONTENT_ORIENTATION "SDL_QTWAYLAND_CONTENT_ORIENTATION" |
1551 | |
1552 | /** |
1553 | * \brief Flags to set on QtWayland windows to integrate with the native window manager. |
1554 | * |
1555 | * On QtWayland platforms, this hint controls the flags to set on the windows. |
1556 | * For example, on Sailfish OS "OverridesSystemGestures" disables swipe gestures. |
1557 | * |
1558 | * This variable is a space-separated list of the following values (empty = no flags): |
1559 | * "OverridesSystemGestures", "StaysOnTop", "BypassWindowManager" |
1560 | */ |
1561 | #define SDL_HINT_QTWAYLAND_WINDOW_FLAGS "SDL_QTWAYLAND_WINDOW_FLAGS" |
1562 | |
1563 | /** |
1564 | * \brief A variable controlling whether the 2D render API is compatible or efficient. |
1565 | * |
1566 | * This variable can be set to the following values: |
1567 | * |
1568 | * "0" - Don't use batching to make rendering more efficient. |
1569 | * "1" - Use batching, but might cause problems if app makes its own direct OpenGL calls. |
1570 | * |
1571 | * Up to SDL 2.0.9, the render API would draw immediately when requested. Now |
1572 | * it batches up draw requests and sends them all to the GPU only when forced |
1573 | * to (during SDL_RenderPresent, when changing render targets, by updating a |
1574 | * texture that the batch needs, etc). This is significantly more efficient, |
1575 | * but it can cause problems for apps that expect to render on top of the |
1576 | * render API's output. As such, SDL will disable batching if a specific |
1577 | * render backend is requested (since this might indicate that the app is |
1578 | * planning to use the underlying graphics API directly). This hint can |
1579 | * be used to explicitly request batching in this instance. It is a contract |
1580 | * that you will either never use the underlying graphics API directly, or |
1581 | * if you do, you will call SDL_RenderFlush() before you do so any current |
1582 | * batch goes to the GPU before your work begins. Not following this contract |
1583 | * will result in undefined behavior. |
1584 | */ |
1585 | #define SDL_HINT_RENDER_BATCHING "SDL_RENDER_BATCHING" |
1586 | |
1587 | /** |
1588 | * \brief A variable controlling how the 2D render API renders lines |
1589 | * |
1590 | * This variable can be set to the following values: |
1591 | * "0" - Use the default line drawing method (Bresenham's line algorithm as of SDL 2.0.20) |
1592 | * "1" - Use the driver point API using Bresenham's line algorithm (correct, draws many points) |
1593 | * "2" - Use the driver line API (occasionally misses line endpoints based on hardware driver quirks, was the default before 2.0.20) |
1594 | * "3" - Use the driver geometry API (correct, draws thicker diagonal lines) |
1595 | * |
1596 | * This variable should be set when the renderer is created. |
1597 | */ |
1598 | #define SDL_HINT_RENDER_LINE_METHOD "SDL_RENDER_LINE_METHOD" |
1599 | |
1600 | /** |
1601 | * \brief A variable controlling whether to enable Direct3D 11+'s Debug Layer. |
1602 | * |
1603 | * This variable does not have any effect on the Direct3D 9 based renderer. |
1604 | * |
1605 | * This variable can be set to the following values: |
1606 | * "0" - Disable Debug Layer use |
1607 | * "1" - Enable Debug Layer use |
1608 | * |
1609 | * By default, SDL does not use Direct3D Debug Layer. |
1610 | */ |
1611 | #define SDL_HINT_RENDER_DIRECT3D11_DEBUG "SDL_RENDER_DIRECT3D11_DEBUG" |
1612 | |
1613 | /** |
1614 | * \brief A variable controlling whether the Direct3D device is initialized for thread-safe operations. |
1615 | * |
1616 | * This variable can be set to the following values: |
1617 | * "0" - Thread-safety is not enabled (faster) |
1618 | * "1" - Thread-safety is enabled |
1619 | * |
1620 | * By default the Direct3D device is created with thread-safety disabled. |
1621 | */ |
1622 | #define SDL_HINT_RENDER_DIRECT3D_THREADSAFE "SDL_RENDER_DIRECT3D_THREADSAFE" |
1623 | |
1624 | /** |
1625 | * \brief A variable specifying which render driver to use. |
1626 | * |
1627 | * If the application doesn't pick a specific renderer to use, this variable |
1628 | * specifies the name of the preferred renderer. If the preferred renderer |
1629 | * can't be initialized, the normal default renderer is used. |
1630 | * |
1631 | * This variable is case insensitive and can be set to the following values: |
1632 | * "direct3d" |
1633 | * "direct3d11" |
1634 | * "direct3d12" |
1635 | * "opengl" |
1636 | * "opengles2" |
1637 | * "opengles" |
1638 | * "metal" |
1639 | * "software" |
1640 | * |
1641 | * The default varies by platform, but it's the first one in the list that |
1642 | * is available on the current platform. |
1643 | */ |
1644 | #define SDL_HINT_RENDER_DRIVER "SDL_RENDER_DRIVER" |
1645 | |
1646 | /** |
1647 | * \brief A variable controlling the scaling policy for SDL_RenderSetLogicalSize. |
1648 | * |
1649 | * This variable can be set to the following values: |
1650 | * "0" or "letterbox" - Uses letterbox/sidebars to fit the entire rendering on screen |
1651 | * "1" or "overscan" - Will zoom the rendering so it fills the entire screen, allowing edges to be drawn offscreen |
1652 | * |
1653 | * By default letterbox is used |
1654 | */ |
1655 | #define SDL_HINT_RENDER_LOGICAL_SIZE_MODE "SDL_RENDER_LOGICAL_SIZE_MODE" |
1656 | |
1657 | /** |
1658 | * \brief A variable controlling whether the OpenGL render driver uses shaders if they are available. |
1659 | * |
1660 | * This variable can be set to the following values: |
1661 | * "0" - Disable shaders |
1662 | * "1" - Enable shaders |
1663 | * |
1664 | * By default shaders are used if OpenGL supports them. |
1665 | */ |
1666 | #define SDL_HINT_RENDER_OPENGL_SHADERS "SDL_RENDER_OPENGL_SHADERS" |
1667 | |
1668 | /** |
1669 | * \brief A variable controlling the scaling quality |
1670 | * |
1671 | * This variable can be set to the following values: |
1672 | * "0" or "nearest" - Nearest pixel sampling |
1673 | * "1" or "linear" - Linear filtering (supported by OpenGL and Direct3D) |
1674 | * "2" or "best" - Currently this is the same as "linear" |
1675 | * |
1676 | * By default nearest pixel sampling is used |
1677 | */ |
1678 | #define SDL_HINT_RENDER_SCALE_QUALITY "SDL_RENDER_SCALE_QUALITY" |
1679 | |
1680 | /** |
1681 | * \brief A variable controlling whether updates to the SDL screen surface should be synchronized with the vertical refresh, to avoid tearing. |
1682 | * |
1683 | * This variable can be set to the following values: |
1684 | * "0" - Disable vsync |
1685 | * "1" - Enable vsync |
1686 | * |
1687 | * By default SDL does not sync screen surface updates with vertical refresh. |
1688 | */ |
1689 | #define SDL_HINT_RENDER_VSYNC "SDL_RENDER_VSYNC" |
1690 | |
1691 | /** |
1692 | * \brief A variable controlling whether the Metal render driver select low power device over default one |
1693 | * |
1694 | * This variable can be set to the following values: |
1695 | * "0" - Use the prefered OS device |
1696 | * "1" - Select a low power one |
1697 | * |
1698 | * By default the prefered OS device is used. |
1699 | */ |
1700 | #define SDL_HINT_RENDER_METAL_PREFER_LOW_POWER_DEVICE "SDL_RENDER_METAL_PREFER_LOW_POWER_DEVICE" |
1701 | |
1702 | /** |
1703 | * A variable containing a list of ROG gamepad capable mice. |
1704 | * |
1705 | * The format of the string is a comma separated list of USB VID/PID pairs |
1706 | * in hexadecimal form, e.g. |
1707 | * |
1708 | * 0xAAAA/0xBBBB,0xCCCC/0xDDDD |
1709 | * |
1710 | * The variable can also take the form of @file, in which case the named |
1711 | * file will be loaded and interpreted as the value of the variable. |
1712 | */ |
1713 | #define SDL_HINT_ROG_GAMEPAD_MICE "SDL_ROG_GAMEPAD_MICE" |
1714 | |
1715 | /** |
1716 | * A variable containing a list of devices that are not ROG gamepad capable mice. This will override SDL_HINT_ROG_GAMEPAD_MICE and the built in device list. |
1717 | * |
1718 | * The format of the string is a comma separated list of USB VID/PID pairs |
1719 | * in hexadecimal form, e.g. |
1720 | * |
1721 | * 0xAAAA/0xBBBB,0xCCCC/0xDDDD |
1722 | * |
1723 | * The variable can also take the form of @file, in which case the named |
1724 | * file will be loaded and interpreted as the value of the variable. |
1725 | */ |
1726 | #define SDL_HINT_ROG_GAMEPAD_MICE_EXCLUDED "SDL_ROG_GAMEPAD_MICE_EXCLUDED" |
1727 | |
1728 | /** |
1729 | * \brief A variable controlling if VSYNC is automatically disable if doesn't reach the enough FPS |
1730 | * |
1731 | * This variable can be set to the following values: |
1732 | * "0" - It will be using VSYNC as defined in the main flag. Default |
1733 | * "1" - If VSYNC was previously enabled, then it will disable VSYNC if doesn't reach enough speed |
1734 | * |
1735 | * By default SDL does not enable the automatic VSYNC |
1736 | */ |
1737 | #define SDL_HINT_PS2_DYNAMIC_VSYNC "SDL_PS2_DYNAMIC_VSYNC" |
1738 | |
1739 | /** |
1740 | * \brief A variable to control whether the return key on the soft keyboard |
1741 | * should hide the soft keyboard on Android and iOS. |
1742 | * |
1743 | * The variable can be set to the following values: |
1744 | * "0" - The return key will be handled as a key event. This is the behaviour of SDL <= 2.0.3. (default) |
1745 | * "1" - The return key will hide the keyboard. |
1746 | * |
1747 | * The value of this hint is used at runtime, so it can be changed at any time. |
1748 | */ |
1749 | #define SDL_HINT_RETURN_KEY_HIDES_IME "SDL_RETURN_KEY_HIDES_IME" |
1750 | |
1751 | /** |
1752 | * \brief Tell SDL which Dispmanx layer to use on a Raspberry PI |
1753 | * |
1754 | * Also known as Z-order. The variable can take a negative or positive value. |
1755 | * The default is 10000. |
1756 | */ |
1757 | #define SDL_HINT_RPI_VIDEO_LAYER "SDL_RPI_VIDEO_LAYER" |
1758 | |
1759 | /** |
1760 | * \brief Specify an "activity name" for screensaver inhibition. |
1761 | * |
1762 | * Some platforms, notably Linux desktops, list the applications which are |
1763 | * inhibiting the screensaver or other power-saving features. |
1764 | * |
1765 | * This hint lets you specify the "activity name" sent to the OS when |
1766 | * SDL_DisableScreenSaver() is used (or the screensaver is automatically |
1767 | * disabled). The contents of this hint are used when the screensaver is |
1768 | * disabled. You should use a string that describes what your program is doing |
1769 | * (and, therefore, why the screensaver is disabled). For example, "Playing a |
1770 | * game" or "Watching a video". |
1771 | * |
1772 | * Setting this to "" or leaving it unset will have SDL use a reasonable |
1773 | * default: "Playing a game" or something similar. |
1774 | * |
1775 | * On targets where this is not supported, this hint does nothing. |
1776 | */ |
1777 | #define SDL_HINT_SCREENSAVER_INHIBIT_ACTIVITY_NAME "SDL_SCREENSAVER_INHIBIT_ACTIVITY_NAME" |
1778 | |
1779 | /** |
1780 | * \brief Specifies whether SDL_THREAD_PRIORITY_TIME_CRITICAL should be treated as realtime. |
1781 | * |
1782 | * On some platforms, like Linux, a realtime priority thread may be subject to restrictions |
1783 | * that require special handling by the application. This hint exists to let SDL know that |
1784 | * the app is prepared to handle said restrictions. |
1785 | * |
1786 | * On Linux, SDL will apply the following configuration to any thread that becomes realtime: |
1787 | * * The SCHED_RESET_ON_FORK bit will be set on the scheduling policy, |
1788 | * * An RLIMIT_RTTIME budget will be configured to the rtkit specified limit. |
1789 | * * Exceeding this limit will result in the kernel sending SIGKILL to the app, |
1790 | * * Refer to the man pages for more information. |
1791 | * |
1792 | * This variable can be set to the following values: |
1793 | * "0" - default platform specific behaviour |
1794 | * "1" - Force SDL_THREAD_PRIORITY_TIME_CRITICAL to a realtime scheduling policy |
1795 | */ |
1796 | #define SDL_HINT_THREAD_FORCE_REALTIME_TIME_CRITICAL "SDL_THREAD_FORCE_REALTIME_TIME_CRITICAL" |
1797 | |
1798 | /** |
1799 | * \brief A string specifying additional information to use with SDL_SetThreadPriority. |
1800 | * |
1801 | * By default SDL_SetThreadPriority will make appropriate system changes in order to |
1802 | * apply a thread priority. For example on systems using pthreads the scheduler policy |
1803 | * is changed automatically to a policy that works well with a given priority. |
1804 | * Code which has specific requirements can override SDL's default behavior with this hint. |
1805 | * |
1806 | * pthread hint values are "current", "other", "fifo" and "rr". |
1807 | * Currently no other platform hint values are defined but may be in the future. |
1808 | * |
1809 | * \note On Linux, the kernel may send SIGKILL to realtime tasks which exceed the distro |
1810 | * configured execution budget for rtkit. This budget can be queried through RLIMIT_RTTIME |
1811 | * after calling SDL_SetThreadPriority(). |
1812 | */ |
1813 | #define SDL_HINT_THREAD_PRIORITY_POLICY "SDL_THREAD_PRIORITY_POLICY" |
1814 | |
1815 | /** |
1816 | * \brief A string specifying SDL's threads stack size in bytes or "0" for the backend's default size |
1817 | * |
1818 | * Use this hint in case you need to set SDL's threads stack size to other than the default. |
1819 | * This is specially useful if you build SDL against a non glibc libc library (such as musl) which |
1820 | * provides a relatively small default thread stack size (a few kilobytes versus the default 8MB glibc uses). |
1821 | * Support for this hint is currently available only in the pthread, Windows, and PSP backend. |
1822 | * |
1823 | * Instead of this hint, in 2.0.9 and later, you can use |
1824 | * SDL_CreateThreadWithStackSize(). This hint only works with the classic |
1825 | * SDL_CreateThread(). |
1826 | */ |
1827 | #define SDL_HINT_THREAD_STACK_SIZE "SDL_THREAD_STACK_SIZE" |
1828 | |
1829 | /** |
1830 | * \brief A variable that controls the timer resolution, in milliseconds. |
1831 | * |
1832 | * The higher resolution the timer, the more frequently the CPU services |
1833 | * timer interrupts, and the more precise delays are, but this takes up |
1834 | * power and CPU time. This hint is only used on Windows. |
1835 | * |
1836 | * See this blog post for more information: |
1837 | * http://randomascii.wordpress.com/2013/07/08/windows-timer-resolution-megawatts-wasted/ |
1838 | * |
1839 | * If this variable is set to "0", the system timer resolution is not set. |
1840 | * |
1841 | * The default value is "1". This hint may be set at any time. |
1842 | */ |
1843 | #define SDL_HINT_TIMER_RESOLUTION "SDL_TIMER_RESOLUTION" |
1844 | |
1845 | /** |
1846 | * \brief A variable controlling whether touch events should generate synthetic mouse events |
1847 | * |
1848 | * This variable can be set to the following values: |
1849 | * "0" - Touch events will not generate mouse events |
1850 | * "1" - Touch events will generate mouse events |
1851 | * |
1852 | * By default SDL will generate mouse events for touch events |
1853 | */ |
1854 | #define SDL_HINT_TOUCH_MOUSE_EVENTS "SDL_TOUCH_MOUSE_EVENTS" |
1855 | |
1856 | /** |
1857 | * \brief A variable controlling which touchpad should generate synthetic mouse events |
1858 | * |
1859 | * This variable can be set to the following values: |
1860 | * "0" - Only front touchpad should generate mouse events. Default |
1861 | * "1" - Only back touchpad should generate mouse events. |
1862 | * "2" - Both touchpads should generate mouse events. |
1863 | * |
1864 | * By default SDL will generate mouse events for all touch devices |
1865 | */ |
1866 | #define SDL_HINT_VITA_TOUCH_MOUSE_DEVICE "SDL_HINT_VITA_TOUCH_MOUSE_DEVICE" |
1867 | |
1868 | /** |
1869 | * \brief A variable controlling whether the Android / tvOS remotes |
1870 | * should be listed as joystick devices, instead of sending keyboard events. |
1871 | * |
1872 | * This variable can be set to the following values: |
1873 | * "0" - Remotes send enter/escape/arrow key events |
1874 | * "1" - Remotes are available as 2 axis, 2 button joysticks (the default). |
1875 | */ |
1876 | #define SDL_HINT_TV_REMOTE_AS_JOYSTICK "SDL_TV_REMOTE_AS_JOYSTICK" |
1877 | |
1878 | /** |
1879 | * \brief A variable controlling whether the screensaver is enabled. |
1880 | * |
1881 | * This variable can be set to the following values: |
1882 | * "0" - Disable screensaver |
1883 | * "1" - Enable screensaver |
1884 | * |
1885 | * By default SDL will disable the screensaver. |
1886 | */ |
1887 | #define SDL_HINT_VIDEO_ALLOW_SCREENSAVER "SDL_VIDEO_ALLOW_SCREENSAVER" |
1888 | |
1889 | /** |
1890 | * \brief Tell the video driver that we only want a double buffer. |
1891 | * |
1892 | * By default, most lowlevel 2D APIs will use a triple buffer scheme that |
1893 | * wastes no CPU time on waiting for vsync after issuing a flip, but |
1894 | * introduces a frame of latency. On the other hand, using a double buffer |
1895 | * scheme instead is recommended for cases where low latency is an important |
1896 | * factor because we save a whole frame of latency. |
1897 | * We do so by waiting for vsync immediately after issuing a flip, usually just |
1898 | * after eglSwapBuffers call in the backend's *_SwapWindow function. |
1899 | * |
1900 | * Since it's driver-specific, it's only supported where possible and |
1901 | * implemented. Currently supported the following drivers: |
1902 | * |
1903 | * - KMSDRM (kmsdrm) |
1904 | * - Raspberry Pi (raspberrypi) |
1905 | */ |
1906 | #define SDL_HINT_VIDEO_DOUBLE_BUFFER "SDL_VIDEO_DOUBLE_BUFFER" |
1907 | |
1908 | /** |
1909 | * \brief A variable controlling whether the EGL window is allowed to be |
1910 | * composited as transparent, rather than opaque. |
1911 | * |
1912 | * Most window systems will always render windows opaque, even if the surface |
1913 | * format has an alpha channel. This is not always true, however, so by default |
1914 | * SDL will try to enforce opaque composition. To override this behavior, you |
1915 | * can set this hint to "1". |
1916 | */ |
1917 | #define SDL_HINT_VIDEO_EGL_ALLOW_TRANSPARENCY "SDL_VIDEO_EGL_ALLOW_TRANSPARENCY" |
1918 | |
1919 | /** |
1920 | * \brief A variable controlling whether the graphics context is externally managed. |
1921 | * |
1922 | * This variable can be set to the following values: |
1923 | * "0" - SDL will manage graphics contexts that are attached to windows. |
1924 | * "1" - Disable graphics context management on windows. |
1925 | * |
1926 | * By default SDL will manage OpenGL contexts in certain situations. For example, on Android the |
1927 | * context will be automatically saved and restored when pausing the application. Additionally, some |
1928 | * platforms will assume usage of OpenGL if Vulkan isn't used. Setting this to "1" will prevent this |
1929 | * behavior, which is desireable when the application manages the graphics context, such as |
1930 | * an externally managed OpenGL context or attaching a Vulkan surface to the window. |
1931 | */ |
1932 | #define SDL_HINT_VIDEO_EXTERNAL_CONTEXT "SDL_VIDEO_EXTERNAL_CONTEXT" |
1933 | |
1934 | /** |
1935 | * \brief If set to 1, then do not allow high-DPI windows. ("Retina" on Mac and iOS) |
1936 | */ |
1937 | #define SDL_HINT_VIDEO_HIGHDPI_DISABLED "SDL_VIDEO_HIGHDPI_DISABLED" |
1938 | |
1939 | /** |
1940 | * \brief A variable that dictates policy for fullscreen Spaces on Mac OS X. |
1941 | * |
1942 | * This hint only applies to Mac OS X. |
1943 | * |
1944 | * The variable can be set to the following values: |
1945 | * "0" - Disable Spaces support (FULLSCREEN_DESKTOP won't use them and |
1946 | * SDL_WINDOW_RESIZABLE windows won't offer the "fullscreen" |
1947 | * button on their titlebars). |
1948 | * "1" - Enable Spaces support (FULLSCREEN_DESKTOP will use them and |
1949 | * SDL_WINDOW_RESIZABLE windows will offer the "fullscreen" |
1950 | * button on their titlebars). |
1951 | * |
1952 | * The default value is "1". This hint must be set before any windows are created. |
1953 | */ |
1954 | #define SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES "SDL_VIDEO_MAC_FULLSCREEN_SPACES" |
1955 | |
1956 | /** |
1957 | * \brief Minimize your SDL_Window if it loses key focus when in fullscreen mode. Defaults to false. |
1958 | * \warning Before SDL 2.0.14, this defaulted to true! In 2.0.14, we're |
1959 | * seeing if "true" causes more problems than it solves in modern times. |
1960 | * |
1961 | */ |
1962 | #define SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS "SDL_VIDEO_MINIMIZE_ON_FOCUS_LOSS" |
1963 | |
1964 | /** |
1965 | * \brief A variable controlling whether the libdecor Wayland backend is allowed to be used. |
1966 | * |
1967 | * This variable can be set to the following values: |
1968 | * "0" - libdecor use is disabled. |
1969 | * "1" - libdecor use is enabled (default). |
1970 | * |
1971 | * libdecor is used over xdg-shell when xdg-decoration protocol is unavailable. |
1972 | */ |
1973 | #define SDL_HINT_VIDEO_WAYLAND_ALLOW_LIBDECOR "SDL_VIDEO_WAYLAND_ALLOW_LIBDECOR" |
1974 | |
1975 | /** |
1976 | * \brief A variable controlling whether the libdecor Wayland backend is preferred over native decrations. |
1977 | * |
1978 | * When this hint is set, libdecor will be used to provide window decorations, even if xdg-decoration is |
1979 | * available. (Note that, by default, libdecor will use xdg-decoration itself if available). |
1980 | * |
1981 | * This variable can be set to the following values: |
1982 | * "0" - libdecor is enabled only if server-side decorations are unavailable. |
1983 | * "1" - libdecor is always enabled if available. |
1984 | * |
1985 | * libdecor is used over xdg-shell when xdg-decoration protocol is unavailable. |
1986 | */ |
1987 | #define SDL_HINT_VIDEO_WAYLAND_PREFER_LIBDECOR "SDL_VIDEO_WAYLAND_PREFER_LIBDECOR" |
1988 | |
1989 | /** |
1990 | * \brief A variable controlling whether video mode emulation is enabled under Wayland. |
1991 | * |
1992 | * When this hint is set, a standard set of emulated CVT video modes will be exposed for use by the application. |
1993 | * If it is disabled, the only modes exposed will be the logical desktop size and, in the case of a scaled |
1994 | * desktop, the native display resolution. |
1995 | * |
1996 | * This variable can be set to the following values: |
1997 | * "0" - Video mode emulation is disabled. |
1998 | * "1" - Video mode emulation is enabled. |
1999 | * |
2000 | * By default video mode emulation is enabled. |
2001 | */ |
2002 | #define SDL_HINT_VIDEO_WAYLAND_MODE_EMULATION "SDL_VIDEO_WAYLAND_MODE_EMULATION" |
2003 | |
2004 | /** |
2005 | * \brief Enable or disable mouse pointer warp emulation, needed by some older games. |
2006 | * |
2007 | * When this hint is set, any SDL will emulate mouse warps using relative mouse mode. |
2008 | * This is required for some older games (such as Source engine games), which warp the |
2009 | * mouse to the centre of the screen rather than using relative mouse motion. Note that |
2010 | * relative mouse mode may have different mouse acceleration behaviour than pointer warps. |
2011 | * |
2012 | * This variable can be set to the following values: |
2013 | * "0" - All mouse warps fail, as mouse warping is not available under wayland. |
2014 | * "1" - Some mouse warps will be emulated by forcing relative mouse mode. |
2015 | * |
2016 | * If not set, this is automatically enabled unless an application uses relative mouse |
2017 | * mode directly. |
2018 | */ |
2019 | #define SDL_HINT_VIDEO_WAYLAND_EMULATE_MOUSE_WARP "SDL_VIDEO_WAYLAND_EMULATE_MOUSE_WARP" |
2020 | |
2021 | /** |
2022 | * \brief A variable that is the address of another SDL_Window* (as a hex string formatted with "%p"). |
2023 | * |
2024 | * If this hint is set before SDL_CreateWindowFrom() and the SDL_Window* it is set to has |
2025 | * SDL_WINDOW_OPENGL set (and running on WGL only, currently), then two things will occur on the newly |
2026 | * created SDL_Window: |
2027 | * |
2028 | * 1. Its pixel format will be set to the same pixel format as this SDL_Window. This is |
2029 | * needed for example when sharing an OpenGL context across multiple windows. |
2030 | * |
2031 | * 2. The flag SDL_WINDOW_OPENGL will be set on the new window so it can be used for |
2032 | * OpenGL rendering. |
2033 | * |
2034 | * This variable can be set to the following values: |
2035 | * The address (as a string "%p") of the SDL_Window* that new windows created with SDL_CreateWindowFrom() should |
2036 | * share a pixel format with. |
2037 | */ |
2038 | #define SDL_HINT_VIDEO_WINDOW_SHARE_PIXEL_FORMAT "SDL_VIDEO_WINDOW_SHARE_PIXEL_FORMAT" |
2039 | |
2040 | /** |
2041 | * \brief When calling SDL_CreateWindowFrom(), make the window compatible with OpenGL. |
2042 | * |
2043 | * This variable can be set to the following values: |
2044 | * "0" - Don't add any graphics flags to the SDL_WindowFlags |
2045 | * "1" - Add SDL_WINDOW_OPENGL to the SDL_WindowFlags |
2046 | * |
2047 | * By default SDL will not make the foreign window compatible with OpenGL. |
2048 | */ |
2049 | #define SDL_HINT_VIDEO_FOREIGN_WINDOW_OPENGL "SDL_VIDEO_FOREIGN_WINDOW_OPENGL" |
2050 | |
2051 | /** |
2052 | * \brief When calling SDL_CreateWindowFrom(), make the window compatible with Vulkan. |
2053 | * |
2054 | * This variable can be set to the following values: |
2055 | * "0" - Don't add any graphics flags to the SDL_WindowFlags |
2056 | * "1" - Add SDL_WINDOW_VULKAN to the SDL_WindowFlags |
2057 | * |
2058 | * By default SDL will not make the foreign window compatible with Vulkan. |
2059 | */ |
2060 | #define SDL_HINT_VIDEO_FOREIGN_WINDOW_VULKAN "SDL_VIDEO_FOREIGN_WINDOW_VULKAN" |
2061 | |
2062 | /** |
2063 | * \brief A variable specifying which shader compiler to preload when using the Chrome ANGLE binaries |
2064 | * |
2065 | * SDL has EGL and OpenGL ES2 support on Windows via the ANGLE project. It |
2066 | * can use two different sets of binaries, those compiled by the user from source |
2067 | * or those provided by the Chrome browser. In the later case, these binaries require |
2068 | * that SDL loads a DLL providing the shader compiler. |
2069 | * |
2070 | * This variable can be set to the following values: |
2071 | * "d3dcompiler_46.dll" - default, best for Vista or later. |
2072 | * "d3dcompiler_43.dll" - for XP support. |
2073 | * "none" - do not load any library, useful if you compiled ANGLE from source and included the compiler in your binaries. |
2074 | * |
2075 | */ |
2076 | #define SDL_HINT_VIDEO_WIN_D3DCOMPILER "SDL_VIDEO_WIN_D3DCOMPILER" |
2077 | |
2078 | /** |
2079 | * \brief A variable controlling whether X11 should use GLX or EGL by default |
2080 | * |
2081 | * This variable can be set to the following values: |
2082 | * "0" - Use GLX |
2083 | * "1" - Use EGL |
2084 | * |
2085 | * By default SDL will use GLX when both are present. |
2086 | */ |
2087 | #define SDL_HINT_VIDEO_X11_FORCE_EGL "SDL_VIDEO_X11_FORCE_EGL" |
2088 | |
2089 | /** |
2090 | * \brief A variable controlling whether the X11 _NET_WM_BYPASS_COMPOSITOR hint should be used. |
2091 | * |
2092 | * This variable can be set to the following values: |
2093 | * "0" - Disable _NET_WM_BYPASS_COMPOSITOR |
2094 | * "1" - Enable _NET_WM_BYPASS_COMPOSITOR |
2095 | * |
2096 | * By default SDL will use _NET_WM_BYPASS_COMPOSITOR |
2097 | * |
2098 | */ |
2099 | #define SDL_HINT_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR "SDL_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR" |
2100 | |
2101 | /** |
2102 | * \brief A variable controlling whether the X11 _NET_WM_PING protocol should be supported. |
2103 | * |
2104 | * This variable can be set to the following values: |
2105 | * "0" - Disable _NET_WM_PING |
2106 | * "1" - Enable _NET_WM_PING |
2107 | * |
2108 | * By default SDL will use _NET_WM_PING, but for applications that know they |
2109 | * will not always be able to respond to ping requests in a timely manner they can |
2110 | * turn it off to avoid the window manager thinking the app is hung. |
2111 | * The hint is checked in CreateWindow. |
2112 | */ |
2113 | #define SDL_HINT_VIDEO_X11_NET_WM_PING "SDL_VIDEO_X11_NET_WM_PING" |
2114 | |
2115 | /** |
2116 | * \brief A variable forcing the visual ID chosen for new X11 windows |
2117 | * |
2118 | */ |
2119 | #define SDL_HINT_VIDEO_X11_WINDOW_VISUALID "SDL_VIDEO_X11_WINDOW_VISUALID" |
2120 | |
2121 | /** |
2122 | * \brief A no-longer-used variable controlling whether the X11 Xinerama extension should be used. |
2123 | * |
2124 | * Before SDL 2.0.24, this would let apps and users disable Xinerama support on X11. |
2125 | * Now SDL never uses Xinerama, and does not check for this hint at all. |
2126 | * The preprocessor define is left here for source compatibility. |
2127 | */ |
2128 | #define SDL_HINT_VIDEO_X11_XINERAMA "SDL_VIDEO_X11_XINERAMA" |
2129 | |
2130 | /** |
2131 | * \brief A variable controlling whether the X11 XRandR extension should be used. |
2132 | * |
2133 | * This variable can be set to the following values: |
2134 | * "0" - Disable XRandR |
2135 | * "1" - Enable XRandR |
2136 | * |
2137 | * By default SDL will use XRandR. |
2138 | */ |
2139 | #define SDL_HINT_VIDEO_X11_XRANDR "SDL_VIDEO_X11_XRANDR" |
2140 | |
2141 | /** |
2142 | * \brief A no-longer-used variable controlling whether the X11 VidMode extension should be used. |
2143 | * |
2144 | * Before SDL 2.0.24, this would let apps and users disable XVidMode support on X11. |
2145 | * Now SDL never uses XVidMode, and does not check for this hint at all. |
2146 | * The preprocessor define is left here for source compatibility. |
2147 | */ |
2148 | #define SDL_HINT_VIDEO_X11_XVIDMODE "SDL_VIDEO_X11_XVIDMODE" |
2149 | |
2150 | /** |
2151 | * \brief Controls how the fact chunk affects the loading of a WAVE file. |
2152 | * |
2153 | * The fact chunk stores information about the number of samples of a WAVE |
2154 | * file. The Standards Update from Microsoft notes that this value can be used |
2155 | * to 'determine the length of the data in seconds'. This is especially useful |
2156 | * for compressed formats (for which this is a mandatory chunk) if they produce |
2157 | * multiple sample frames per block and truncating the block is not allowed. |
2158 | * The fact chunk can exactly specify how many sample frames there should be |
2159 | * in this case. |
2160 | * |
2161 | * Unfortunately, most application seem to ignore the fact chunk and so SDL |
2162 | * ignores it by default as well. |
2163 | * |
2164 | * This variable can be set to the following values: |
2165 | * |
2166 | * "truncate" - Use the number of samples to truncate the wave data if |
2167 | * the fact chunk is present and valid |
2168 | * "strict" - Like "truncate", but raise an error if the fact chunk |
2169 | * is invalid, not present for non-PCM formats, or if the |
2170 | * data chunk doesn't have that many samples |
2171 | * "ignorezero" - Like "truncate", but ignore fact chunk if the number of |
2172 | * samples is zero |
2173 | * "ignore" - Ignore fact chunk entirely (default) |
2174 | */ |
2175 | #define SDL_HINT_WAVE_FACT_CHUNK "SDL_WAVE_FACT_CHUNK" |
2176 | |
2177 | /** |
2178 | * \brief Controls how the size of the RIFF chunk affects the loading of a WAVE file. |
2179 | * |
2180 | * The size of the RIFF chunk (which includes all the sub-chunks of the WAVE |
2181 | * file) is not always reliable. In case the size is wrong, it's possible to |
2182 | * just ignore it and step through the chunks until a fixed limit is reached. |
2183 | * |
2184 | * Note that files that have trailing data unrelated to the WAVE file or |
2185 | * corrupt files may slow down the loading process without a reliable boundary. |
2186 | * By default, SDL stops after 10000 chunks to prevent wasting time. Use the |
2187 | * environment variable SDL_WAVE_CHUNK_LIMIT to adjust this value. |
2188 | * |
2189 | * This variable can be set to the following values: |
2190 | * |
2191 | * "force" - Always use the RIFF chunk size as a boundary for the chunk search |
2192 | * "ignorezero" - Like "force", but a zero size searches up to 4 GiB (default) |
2193 | * "ignore" - Ignore the RIFF chunk size and always search up to 4 GiB |
2194 | * "maximum" - Search for chunks until the end of file (not recommended) |
2195 | */ |
2196 | #define SDL_HINT_WAVE_RIFF_CHUNK_SIZE "SDL_WAVE_RIFF_CHUNK_SIZE" |
2197 | |
2198 | /** |
2199 | * \brief Controls how a truncated WAVE file is handled. |
2200 | * |
2201 | * A WAVE file is considered truncated if any of the chunks are incomplete or |
2202 | * the data chunk size is not a multiple of the block size. By default, SDL |
2203 | * decodes until the first incomplete block, as most applications seem to do. |
2204 | * |
2205 | * This variable can be set to the following values: |
2206 | * |
2207 | * "verystrict" - Raise an error if the file is truncated |
2208 | * "strict" - Like "verystrict", but the size of the RIFF chunk is ignored |
2209 | * "dropframe" - Decode until the first incomplete sample frame |
2210 | * "dropblock" - Decode until the first incomplete block (default) |
2211 | */ |
2212 | #define SDL_HINT_WAVE_TRUNCATION "SDL_WAVE_TRUNCATION" |
2213 | |
2214 | /** |
2215 | * \brief Tell SDL not to name threads on Windows with the 0x406D1388 Exception. |
2216 | * The 0x406D1388 Exception is a trick used to inform Visual Studio of a |
2217 | * thread's name, but it tends to cause problems with other debuggers, |
2218 | * and the .NET runtime. Note that SDL 2.0.6 and later will still use |
2219 | * the (safer) SetThreadDescription API, introduced in the Windows 10 |
2220 | * Creators Update, if available. |
2221 | * |
2222 | * The variable can be set to the following values: |
2223 | * "0" - SDL will raise the 0x406D1388 Exception to name threads. |
2224 | * This is the default behavior of SDL <= 2.0.4. |
2225 | * "1" - SDL will not raise this exception, and threads will be unnamed. (default) |
2226 | * This is necessary with .NET languages or debuggers that aren't Visual Studio. |
2227 | */ |
2228 | #define SDL_HINT_WINDOWS_DISABLE_THREAD_NAMING "SDL_WINDOWS_DISABLE_THREAD_NAMING" |
2229 | |
2230 | /** |
2231 | * \brief Controls whether menus can be opened with their keyboard shortcut (Alt+mnemonic). |
2232 | * |
2233 | * If the mnemonics are enabled, then menus can be opened by pressing the Alt |
2234 | * key and the corresponding mnemonic (for example, Alt+F opens the File menu). |
2235 | * However, in case an invalid mnemonic is pressed, Windows makes an audible |
2236 | * beep to convey that nothing happened. This is true even if the window has |
2237 | * no menu at all! |
2238 | * |
2239 | * Because most SDL applications don't have menus, and some want to use the Alt |
2240 | * key for other purposes, SDL disables mnemonics (and the beeping) by default. |
2241 | * |
2242 | * Note: This also affects keyboard events: with mnemonics enabled, when a |
2243 | * menu is opened from the keyboard, you will not receive a KEYUP event for |
2244 | * the mnemonic key, and *might* not receive one for Alt. |
2245 | * |
2246 | * This variable can be set to the following values: |
2247 | * "0" - Alt+mnemonic does nothing, no beeping. (default) |
2248 | * "1" - Alt+mnemonic opens menus, invalid mnemonics produce a beep. |
2249 | */ |
2250 | #define "SDL_WINDOWS_ENABLE_MENU_MNEMONICS" |
2251 | |
2252 | /** |
2253 | * \brief A variable controlling whether the windows message loop is processed by SDL |
2254 | * |
2255 | * This variable can be set to the following values: |
2256 | * "0" - The window message loop is not run |
2257 | * "1" - The window message loop is processed in SDL_PumpEvents() |
2258 | * |
2259 | * By default SDL will process the windows message loop |
2260 | */ |
2261 | #define SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP "SDL_WINDOWS_ENABLE_MESSAGELOOP" |
2262 | |
2263 | /** |
2264 | * \brief Force SDL to use Critical Sections for mutexes on Windows. |
2265 | * On Windows 7 and newer, Slim Reader/Writer Locks are available. |
2266 | * They offer better performance, allocate no kernel ressources and |
2267 | * use less memory. SDL will fall back to Critical Sections on older |
2268 | * OS versions or if forced to by this hint. |
2269 | * |
2270 | * This variable can be set to the following values: |
2271 | * "0" - Use SRW Locks when available. If not, fall back to Critical Sections. (default) |
2272 | * "1" - Force the use of Critical Sections in all cases. |
2273 | * |
2274 | */ |
2275 | #define SDL_HINT_WINDOWS_FORCE_MUTEX_CRITICAL_SECTIONS "SDL_WINDOWS_FORCE_MUTEX_CRITICAL_SECTIONS" |
2276 | |
2277 | /** |
2278 | * \brief Force SDL to use Kernel Semaphores on Windows. |
2279 | * Kernel Semaphores are inter-process and require a context |
2280 | * switch on every interaction. On Windows 8 and newer, the |
2281 | * WaitOnAddress API is available. Using that and atomics to |
2282 | * implement semaphores increases performance. |
2283 | * SDL will fall back to Kernel Objects on older OS versions |
2284 | * or if forced to by this hint. |
2285 | * |
2286 | * This variable can be set to the following values: |
2287 | * "0" - Use Atomics and WaitOnAddress API when available. If not, fall back to Kernel Objects. (default) |
2288 | * "1" - Force the use of Kernel Objects in all cases. |
2289 | * |
2290 | */ |
2291 | #define SDL_HINT_WINDOWS_FORCE_SEMAPHORE_KERNEL "SDL_WINDOWS_FORCE_SEMAPHORE_KERNEL" |
2292 | |
2293 | /** |
2294 | * \brief A variable to specify custom icon resource id from RC file on Windows platform |
2295 | */ |
2296 | #define SDL_HINT_WINDOWS_INTRESOURCE_ICON "SDL_WINDOWS_INTRESOURCE_ICON" |
2297 | #define SDL_HINT_WINDOWS_INTRESOURCE_ICON_SMALL "SDL_WINDOWS_INTRESOURCE_ICON_SMALL" |
2298 | |
2299 | /** |
2300 | * \brief Tell SDL not to generate window-close events for Alt+F4 on Windows. |
2301 | * |
2302 | * The variable can be set to the following values: |
2303 | * "0" - SDL will generate a window-close event when it sees Alt+F4. |
2304 | * "1" - SDL will only do normal key handling for Alt+F4. |
2305 | */ |
2306 | #define SDL_HINT_WINDOWS_NO_CLOSE_ON_ALT_F4 "SDL_WINDOWS_NO_CLOSE_ON_ALT_F4" |
2307 | |
2308 | /** |
2309 | * \brief Use the D3D9Ex API introduced in Windows Vista, instead of normal D3D9. |
2310 | * Direct3D 9Ex contains changes to state management that can eliminate device |
2311 | * loss errors during scenarios like Alt+Tab or UAC prompts. D3D9Ex may require |
2312 | * some changes to your application to cope with the new behavior, so this |
2313 | * is disabled by default. |
2314 | * |
2315 | * This hint must be set before initializing the video subsystem. |
2316 | * |
2317 | * For more information on Direct3D 9Ex, see: |
2318 | * - https://docs.microsoft.com/en-us/windows/win32/direct3darticles/graphics-apis-in-windows-vista#direct3d-9ex |
2319 | * - https://docs.microsoft.com/en-us/windows/win32/direct3darticles/direct3d-9ex-improvements |
2320 | * |
2321 | * This variable can be set to the following values: |
2322 | * "0" - Use the original Direct3D 9 API (default) |
2323 | * "1" - Use the Direct3D 9Ex API on Vista and later (and fall back if D3D9Ex is unavailable) |
2324 | * |
2325 | */ |
2326 | #define SDL_HINT_WINDOWS_USE_D3D9EX "SDL_WINDOWS_USE_D3D9EX" |
2327 | |
2328 | /** |
2329 | * \brief Controls whether SDL will declare the process to be DPI aware. |
2330 | * |
2331 | * This hint must be set before initializing the video subsystem. |
2332 | * |
2333 | * The main purpose of declaring DPI awareness is to disable OS bitmap scaling of SDL windows on monitors with |
2334 | * a DPI scale factor. |
2335 | * |
2336 | * This hint is equivalent to requesting DPI awareness via external means (e.g. calling SetProcessDpiAwarenessContext) |
2337 | * and does not cause SDL to use a virtualized coordinate system, so it will generally give you 1 SDL coordinate = 1 pixel |
2338 | * even on high-DPI displays. |
2339 | * |
2340 | * For more information, see: |
2341 | * https://docs.microsoft.com/en-us/windows/win32/hidpi/high-dpi-desktop-application-development-on-windows |
2342 | * |
2343 | * This variable can be set to the following values: |
2344 | * "" - Do not change the DPI awareness (default). |
2345 | * "unaware" - Declare the process as DPI unaware. (Windows 8.1 and later). |
2346 | * "system" - Request system DPI awareness. (Vista and later). |
2347 | * "permonitor" - Request per-monitor DPI awareness. (Windows 8.1 and later). |
2348 | * "permonitorv2" - Request per-monitor V2 DPI awareness. (Windows 10, version 1607 and later). |
2349 | * The most visible difference from "permonitor" is that window title bar will be scaled |
2350 | * to the visually correct size when dragging between monitors with different scale factors. |
2351 | * This is the preferred DPI awareness level. |
2352 | * |
2353 | * If the requested DPI awareness is not available on the currently running OS, SDL will try to request the best |
2354 | * available match. |
2355 | */ |
2356 | #define SDL_HINT_WINDOWS_DPI_AWARENESS "SDL_WINDOWS_DPI_AWARENESS" |
2357 | |
2358 | /** |
2359 | * \brief Uses DPI-scaled points as the SDL coordinate system on Windows. |
2360 | * |
2361 | * This changes the SDL coordinate system units to be DPI-scaled points, rather than pixels everywhere. |
2362 | * This means windows will be appropriately sized, even when created on high-DPI displays with scaling. |
2363 | * |
2364 | * e.g. requesting a 640x480 window from SDL, on a display with 125% scaling in Windows display settings, |
2365 | * will create a window with an 800x600 client area (in pixels). |
2366 | * |
2367 | * Setting this to "1" implicitly requests process DPI awareness (setting SDL_WINDOWS_DPI_AWARENESS is unnecessary), |
2368 | * and forces SDL_WINDOW_ALLOW_HIGHDPI on all windows. |
2369 | * |
2370 | * This variable can be set to the following values: |
2371 | * "0" - SDL coordinates equal Windows coordinates. No automatic window resizing when dragging |
2372 | * between monitors with different scale factors (unless this is performed by |
2373 | * Windows itself, which is the case when the process is DPI unaware). |
2374 | * "1" - SDL coordinates are in DPI-scaled points. Automatically resize windows as needed on |
2375 | * displays with non-100% scale factors. |
2376 | */ |
2377 | #define SDL_HINT_WINDOWS_DPI_SCALING "SDL_WINDOWS_DPI_SCALING" |
2378 | |
2379 | /** |
2380 | * \brief A variable controlling whether the window frame and title bar are interactive when the cursor is hidden |
2381 | * |
2382 | * This variable can be set to the following values: |
2383 | * "0" - The window frame is not interactive when the cursor is hidden (no move, resize, etc) |
2384 | * "1" - The window frame is interactive when the cursor is hidden |
2385 | * |
2386 | * By default SDL will allow interaction with the window frame when the cursor is hidden |
2387 | */ |
2388 | #define SDL_HINT_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN "SDL_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN" |
2389 | |
2390 | /** |
2391 | * \brief A variable controlling whether the window is activated when the SDL_ShowWindow function is called |
2392 | * |
2393 | * This variable can be set to the following values: |
2394 | * "0" - The window is activated when the SDL_ShowWindow function is called |
2395 | * "1" - The window is not activated when the SDL_ShowWindow function is called |
2396 | * |
2397 | * By default SDL will activate the window when the SDL_ShowWindow function is called |
2398 | */ |
2399 | #define SDL_HINT_WINDOW_NO_ACTIVATION_WHEN_SHOWN "SDL_WINDOW_NO_ACTIVATION_WHEN_SHOWN" |
2400 | |
2401 | /** \brief Allows back-button-press events on Windows Phone to be marked as handled |
2402 | * |
2403 | * Windows Phone devices typically feature a Back button. When pressed, |
2404 | * the OS will emit back-button-press events, which apps are expected to |
2405 | * handle in an appropriate manner. If apps do not explicitly mark these |
2406 | * events as 'Handled', then the OS will invoke its default behavior for |
2407 | * unhandled back-button-press events, which on Windows Phone 8 and 8.1 is to |
2408 | * terminate the app (and attempt to switch to the previous app, or to the |
2409 | * device's home screen). |
2410 | * |
2411 | * Setting the SDL_HINT_WINRT_HANDLE_BACK_BUTTON hint to "1" will cause SDL |
2412 | * to mark back-button-press events as Handled, if and when one is sent to |
2413 | * the app. |
2414 | * |
2415 | * Internally, Windows Phone sends back button events as parameters to |
2416 | * special back-button-press callback functions. Apps that need to respond |
2417 | * to back-button-press events are expected to register one or more |
2418 | * callback functions for such, shortly after being launched (during the |
2419 | * app's initialization phase). After the back button is pressed, the OS |
2420 | * will invoke these callbacks. If the app's callback(s) do not explicitly |
2421 | * mark the event as handled by the time they return, or if the app never |
2422 | * registers one of these callback, the OS will consider the event |
2423 | * un-handled, and it will apply its default back button behavior (terminate |
2424 | * the app). |
2425 | * |
2426 | * SDL registers its own back-button-press callback with the Windows Phone |
2427 | * OS. This callback will emit a pair of SDL key-press events (SDL_KEYDOWN |
2428 | * and SDL_KEYUP), each with a scancode of SDL_SCANCODE_AC_BACK, after which |
2429 | * it will check the contents of the hint, SDL_HINT_WINRT_HANDLE_BACK_BUTTON. |
2430 | * If the hint's value is set to "1", the back button event's Handled |
2431 | * property will get set to 'true'. If the hint's value is set to something |
2432 | * else, or if it is unset, SDL will leave the event's Handled property |
2433 | * alone. (By default, the OS sets this property to 'false', to note.) |
2434 | * |
2435 | * SDL apps can either set SDL_HINT_WINRT_HANDLE_BACK_BUTTON well before a |
2436 | * back button is pressed, or can set it in direct-response to a back button |
2437 | * being pressed. |
2438 | * |
2439 | * In order to get notified when a back button is pressed, SDL apps should |
2440 | * register a callback function with SDL_AddEventWatch(), and have it listen |
2441 | * for SDL_KEYDOWN events that have a scancode of SDL_SCANCODE_AC_BACK. |
2442 | * (Alternatively, SDL_KEYUP events can be listened-for. Listening for |
2443 | * either event type is suitable.) Any value of SDL_HINT_WINRT_HANDLE_BACK_BUTTON |
2444 | * set by such a callback, will be applied to the OS' current |
2445 | * back-button-press event. |
2446 | * |
2447 | * More details on back button behavior in Windows Phone apps can be found |
2448 | * at the following page, on Microsoft's developer site: |
2449 | * http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj247550(v=vs.105).aspx |
2450 | */ |
2451 | #define SDL_HINT_WINRT_HANDLE_BACK_BUTTON "SDL_WINRT_HANDLE_BACK_BUTTON" |
2452 | |
2453 | /** \brief Label text for a WinRT app's privacy policy link |
2454 | * |
2455 | * Network-enabled WinRT apps must include a privacy policy. On Windows 8, 8.1, and RT, |
2456 | * Microsoft mandates that this policy be available via the Windows Settings charm. |
2457 | * SDL provides code to add a link there, with its label text being set via the |
2458 | * optional hint, SDL_HINT_WINRT_PRIVACY_POLICY_LABEL. |
2459 | * |
2460 | * Please note that a privacy policy's contents are not set via this hint. A separate |
2461 | * hint, SDL_HINT_WINRT_PRIVACY_POLICY_URL, is used to link to the actual text of the |
2462 | * policy. |
2463 | * |
2464 | * The contents of this hint should be encoded as a UTF8 string. |
2465 | * |
2466 | * The default value is "Privacy Policy". This hint should only be set during app |
2467 | * initialization, preferably before any calls to SDL_Init(). |
2468 | * |
2469 | * For additional information on linking to a privacy policy, see the documentation for |
2470 | * SDL_HINT_WINRT_PRIVACY_POLICY_URL. |
2471 | */ |
2472 | #define SDL_HINT_WINRT_PRIVACY_POLICY_LABEL "SDL_WINRT_PRIVACY_POLICY_LABEL" |
2473 | |
2474 | /** |
2475 | * \brief A URL to a WinRT app's privacy policy |
2476 | * |
2477 | * All network-enabled WinRT apps must make a privacy policy available to its |
2478 | * users. On Windows 8, 8.1, and RT, Microsoft mandates that this policy be |
2479 | * be available in the Windows Settings charm, as accessed from within the app. |
2480 | * SDL provides code to add a URL-based link there, which can point to the app's |
2481 | * privacy policy. |
2482 | * |
2483 | * To setup a URL to an app's privacy policy, set SDL_HINT_WINRT_PRIVACY_POLICY_URL |
2484 | * before calling any SDL_Init() functions. The contents of the hint should |
2485 | * be a valid URL. For example, "http://www.example.com". |
2486 | * |
2487 | * The default value is "", which will prevent SDL from adding a privacy policy |
2488 | * link to the Settings charm. This hint should only be set during app init. |
2489 | * |
2490 | * The label text of an app's "Privacy Policy" link may be customized via another |
2491 | * hint, SDL_HINT_WINRT_PRIVACY_POLICY_LABEL. |
2492 | * |
2493 | * Please note that on Windows Phone, Microsoft does not provide standard UI |
2494 | * for displaying a privacy policy link, and as such, SDL_HINT_WINRT_PRIVACY_POLICY_URL |
2495 | * will not get used on that platform. Network-enabled phone apps should display |
2496 | * their privacy policy through some other, in-app means. |
2497 | */ |
2498 | #define SDL_HINT_WINRT_PRIVACY_POLICY_URL "SDL_WINRT_PRIVACY_POLICY_URL" |
2499 | |
2500 | /** |
2501 | * \brief Mark X11 windows as override-redirect. |
2502 | * |
2503 | * If set, this _might_ increase framerate at the expense of the desktop |
2504 | * not working as expected. Override-redirect windows aren't noticed by the |
2505 | * window manager at all. |
2506 | * |
2507 | * You should probably only use this for fullscreen windows, and you probably |
2508 | * shouldn't even use it for that. But it's here if you want to try! |
2509 | */ |
2510 | #define SDL_HINT_X11_FORCE_OVERRIDE_REDIRECT "SDL_X11_FORCE_OVERRIDE_REDIRECT" |
2511 | |
2512 | /** |
2513 | * \brief A variable that lets you disable the detection and use of Xinput gamepad devices |
2514 | * |
2515 | * The variable can be set to the following values: |
2516 | * "0" - Disable XInput detection (only uses direct input) |
2517 | * "1" - Enable XInput detection (the default) |
2518 | */ |
2519 | #define SDL_HINT_XINPUT_ENABLED "SDL_XINPUT_ENABLED" |
2520 | |
2521 | /** |
2522 | * \brief A variable that lets you disable the detection and use of DirectInput gamepad devices |
2523 | * |
2524 | * The variable can be set to the following values: |
2525 | * "0" - Disable DirectInput detection (only uses XInput) |
2526 | * "1" - Enable DirectInput detection (the default) |
2527 | */ |
2528 | #define SDL_HINT_DIRECTINPUT_ENABLED "SDL_DIRECTINPUT_ENABLED" |
2529 | |
2530 | /** |
2531 | * \brief A variable that causes SDL to use the old axis and button mapping for XInput devices. |
2532 | * |
2533 | * This hint is for backwards compatibility only and will be removed in SDL 2.1 |
2534 | * |
2535 | * The default value is "0". This hint must be set before SDL_Init() |
2536 | */ |
2537 | #define SDL_HINT_XINPUT_USE_OLD_JOYSTICK_MAPPING "SDL_XINPUT_USE_OLD_JOYSTICK_MAPPING" |
2538 | |
2539 | /** |
2540 | * \brief A variable that causes SDL to not ignore audio "monitors" |
2541 | * |
2542 | * This is currently only used for PulseAudio and ignored elsewhere. |
2543 | * |
2544 | * By default, SDL ignores audio devices that aren't associated with physical |
2545 | * hardware. Changing this hint to "1" will expose anything SDL sees that |
2546 | * appears to be an audio source or sink. This will add "devices" to the list |
2547 | * that the user probably doesn't want or need, but it can be useful in |
2548 | * scenarios where you want to hook up SDL to some sort of virtual device, |
2549 | * etc. |
2550 | * |
2551 | * The default value is "0". This hint must be set before SDL_Init(). |
2552 | * |
2553 | * This hint is available since SDL 2.0.16. Before then, virtual devices are |
2554 | * always ignored. |
2555 | */ |
2556 | #define SDL_HINT_AUDIO_INCLUDE_MONITORS "SDL_AUDIO_INCLUDE_MONITORS" |
2557 | |
2558 | /** |
2559 | * \brief A variable that forces X11 windows to create as a custom type. |
2560 | * |
2561 | * This is currently only used for X11 and ignored elsewhere. |
2562 | * |
2563 | * During SDL_CreateWindow, SDL uses the _NET_WM_WINDOW_TYPE X11 property |
2564 | * to report to the window manager the type of window it wants to create. |
2565 | * This might be set to various things if SDL_WINDOW_TOOLTIP or |
2566 | * SDL_WINDOW_POPUP_MENU, etc, were specified. For "normal" windows that |
2567 | * haven't set a specific type, this hint can be used to specify a custom |
2568 | * type. For example, a dock window might set this to |
2569 | * "_NET_WM_WINDOW_TYPE_DOCK". |
2570 | * |
2571 | * If not set or set to "", this hint is ignored. This hint must be set |
2572 | * before the SDL_CreateWindow() call that it is intended to affect. |
2573 | * |
2574 | * This hint is available since SDL 2.0.22. |
2575 | */ |
2576 | #define SDL_HINT_X11_WINDOW_TYPE "SDL_X11_WINDOW_TYPE" |
2577 | |
2578 | /** |
2579 | * \brief A variable that decides whether to send SDL_QUIT when closing the final window. |
2580 | * |
2581 | * By default, SDL sends an SDL_QUIT event when there is only one window |
2582 | * and it receives an SDL_WINDOWEVENT_CLOSE event, under the assumption most |
2583 | * apps would also take the loss of this window as a signal to terminate the |
2584 | * program. |
2585 | * |
2586 | * However, it's not unreasonable in some cases to have the program continue |
2587 | * to live on, perhaps to create new windows later. |
2588 | * |
2589 | * Changing this hint to "0" will cause SDL to not send an SDL_QUIT event |
2590 | * when the final window is requesting to close. Note that in this case, |
2591 | * there are still other legitimate reasons one might get an SDL_QUIT |
2592 | * event: choosing "Quit" from the macOS menu bar, sending a SIGINT (ctrl-c) |
2593 | * on Unix, etc. |
2594 | * |
2595 | * The default value is "1". This hint can be changed at any time. |
2596 | * |
2597 | * This hint is available since SDL 2.0.22. Before then, you always get |
2598 | * an SDL_QUIT event when closing the final window. |
2599 | */ |
2600 | #define SDL_HINT_QUIT_ON_LAST_WINDOW_CLOSE "SDL_QUIT_ON_LAST_WINDOW_CLOSE" |
2601 | |
2602 | |
2603 | /** |
2604 | * \brief A variable that decides what video backend to use. |
2605 | * |
2606 | * By default, SDL will try all available video backends in a reasonable |
2607 | * order until it finds one that can work, but this hint allows the app |
2608 | * or user to force a specific target, such as "x11" if, say, you are |
2609 | * on Wayland but want to try talking to the X server instead. |
2610 | * |
2611 | * This functionality has existed since SDL 2.0.0 (indeed, before that) |
2612 | * but before 2.0.22 this was an environment variable only. In 2.0.22, |
2613 | * it was upgraded to a full SDL hint, so you can set the environment |
2614 | * variable as usual or programatically set the hint with SDL_SetHint, |
2615 | * which won't propagate to child processes. |
2616 | * |
2617 | * The default value is unset, in which case SDL will try to figure out |
2618 | * the best video backend on your behalf. This hint needs to be set |
2619 | * before SDL_Init() is called to be useful. |
2620 | * |
2621 | * This hint is available since SDL 2.0.22. Before then, you could set |
2622 | * the environment variable to get the same effect. |
2623 | */ |
2624 | #define SDL_HINT_VIDEODRIVER "SDL_VIDEODRIVER" |
2625 | |
2626 | /** |
2627 | * \brief A variable that decides what audio backend to use. |
2628 | * |
2629 | * By default, SDL will try all available audio backends in a reasonable |
2630 | * order until it finds one that can work, but this hint allows the app |
2631 | * or user to force a specific target, such as "alsa" if, say, you are |
2632 | * on PulseAudio but want to try talking to the lower level instead. |
2633 | * |
2634 | * This functionality has existed since SDL 2.0.0 (indeed, before that) |
2635 | * but before 2.0.22 this was an environment variable only. In 2.0.22, |
2636 | * it was upgraded to a full SDL hint, so you can set the environment |
2637 | * variable as usual or programatically set the hint with SDL_SetHint, |
2638 | * which won't propagate to child processes. |
2639 | * |
2640 | * The default value is unset, in which case SDL will try to figure out |
2641 | * the best audio backend on your behalf. This hint needs to be set |
2642 | * before SDL_Init() is called to be useful. |
2643 | * |
2644 | * This hint is available since SDL 2.0.22. Before then, you could set |
2645 | * the environment variable to get the same effect. |
2646 | */ |
2647 | #define SDL_HINT_AUDIODRIVER "SDL_AUDIODRIVER" |
2648 | |
2649 | /** |
2650 | * \brief A variable that decides what KMSDRM device to use. |
2651 | * |
2652 | * Internally, SDL might open something like "/dev/dri/cardNN" to |
2653 | * access KMSDRM functionality, where "NN" is a device index number. |
2654 | * |
2655 | * SDL makes a guess at the best index to use (usually zero), but the |
2656 | * app or user can set this hint to a number between 0 and 99 to |
2657 | * force selection. |
2658 | * |
2659 | * This hint is available since SDL 2.24.0. |
2660 | */ |
2661 | #define SDL_HINT_KMSDRM_DEVICE_INDEX "SDL_KMSDRM_DEVICE_INDEX" |
2662 | |
2663 | |
2664 | /** |
2665 | * \brief A variable that treats trackpads as touch devices. |
2666 | * |
2667 | * On macOS (and possibly other platforms in the future), SDL will report |
2668 | * touches on a trackpad as mouse input, which is generally what users |
2669 | * expect from this device; however, these are often actually full |
2670 | * multitouch-capable touch devices, so it might be preferable to some apps |
2671 | * to treat them as such. |
2672 | * |
2673 | * Setting this hint to true will make the trackpad input report as a |
2674 | * multitouch device instead of a mouse. The default is false. |
2675 | * |
2676 | * Note that most platforms don't support this hint. As of 2.24.0, it |
2677 | * only supports MacBooks' trackpads on macOS. Others may follow later. |
2678 | * |
2679 | * This hint is checked during SDL_Init and can not be changed after. |
2680 | * |
2681 | * This hint is available since SDL 2.24.0. |
2682 | */ |
2683 | #define SDL_HINT_TRACKPAD_IS_TOUCH_ONLY "SDL_TRACKPAD_IS_TOUCH_ONLY" |
2684 | |
2685 | /** |
2686 | * Cause SDL to call dbus_shutdown() on quit. |
2687 | * |
2688 | * This is useful as a debug tool to validate memory leaks, but shouldn't ever |
2689 | * be set in production applications, as other libraries used by the application |
2690 | * might use dbus under the hood and this cause cause crashes if they continue |
2691 | * after SDL_Quit(). |
2692 | * |
2693 | * This variable can be set to the following values: |
2694 | * "0" - SDL will not call dbus_shutdown() on quit (default) |
2695 | * "1" - SDL will call dbus_shutdown() on quit |
2696 | * |
2697 | * This hint is available since SDL 2.30.0. |
2698 | */ |
2699 | #define SDL_HINT_SHUTDOWN_DBUS_ON_QUIT "SDL_SHUTDOWN_DBUS_ON_QUIT" |
2700 | |
2701 | |
2702 | /** |
2703 | * \brief An enumeration of hint priorities |
2704 | */ |
2705 | typedef enum |
2706 | { |
2707 | SDL_HINT_DEFAULT, |
2708 | SDL_HINT_NORMAL, |
2709 | SDL_HINT_OVERRIDE |
2710 | } SDL_HintPriority; |
2711 | |
2712 | |
2713 | /** |
2714 | * Set a hint with a specific priority. |
2715 | * |
2716 | * The priority controls the behavior when setting a hint that already has a |
2717 | * value. Hints will replace existing hints of their priority and lower. |
2718 | * Environment variables are considered to have override priority. |
2719 | * |
2720 | * \param name the hint to set |
2721 | * \param value the value of the hint variable |
2722 | * \param priority the SDL_HintPriority level for the hint |
2723 | * \returns SDL_TRUE if the hint was set, SDL_FALSE otherwise. |
2724 | * |
2725 | * \since This function is available since SDL 2.0.0. |
2726 | * |
2727 | * \sa SDL_GetHint |
2728 | * \sa SDL_SetHint |
2729 | */ |
2730 | extern DECLSPEC SDL_bool SDLCALL SDL_SetHintWithPriority(const char *name, |
2731 | const char *value, |
2732 | SDL_HintPriority priority); |
2733 | |
2734 | /** |
2735 | * Set a hint with normal priority. |
2736 | * |
2737 | * Hints will not be set if there is an existing override hint or environment |
2738 | * variable that takes precedence. You can use SDL_SetHintWithPriority() to |
2739 | * set the hint with override priority instead. |
2740 | * |
2741 | * \param name the hint to set |
2742 | * \param value the value of the hint variable |
2743 | * \returns SDL_TRUE if the hint was set, SDL_FALSE otherwise. |
2744 | * |
2745 | * \since This function is available since SDL 2.0.0. |
2746 | * |
2747 | * \sa SDL_GetHint |
2748 | * \sa SDL_SetHintWithPriority |
2749 | */ |
2750 | extern DECLSPEC SDL_bool SDLCALL SDL_SetHint(const char *name, |
2751 | const char *value); |
2752 | |
2753 | /** |
2754 | * Reset a hint to the default value. |
2755 | * |
2756 | * This will reset a hint to the value of the environment variable, or NULL if |
2757 | * the environment isn't set. Callbacks will be called normally with this |
2758 | * change. |
2759 | * |
2760 | * \param name the hint to set |
2761 | * \returns SDL_TRUE if the hint was set, SDL_FALSE otherwise. |
2762 | * |
2763 | * \since This function is available since SDL 2.24.0. |
2764 | * |
2765 | * \sa SDL_GetHint |
2766 | * \sa SDL_SetHint |
2767 | */ |
2768 | extern DECLSPEC SDL_bool SDLCALL SDL_ResetHint(const char *name); |
2769 | |
2770 | /** |
2771 | * Reset all hints to the default values. |
2772 | * |
2773 | * This will reset all hints to the value of the associated environment |
2774 | * variable, or NULL if the environment isn't set. Callbacks will be called |
2775 | * normally with this change. |
2776 | * |
2777 | * \since This function is available since SDL 2.26.0. |
2778 | * |
2779 | * \sa SDL_GetHint |
2780 | * \sa SDL_SetHint |
2781 | * \sa SDL_ResetHint |
2782 | */ |
2783 | extern DECLSPEC void SDLCALL SDL_ResetHints(void); |
2784 | |
2785 | /** |
2786 | * Get the value of a hint. |
2787 | * |
2788 | * \param name the hint to query |
2789 | * \returns the string value of a hint or NULL if the hint isn't set. |
2790 | * |
2791 | * \since This function is available since SDL 2.0.0. |
2792 | * |
2793 | * \sa SDL_SetHint |
2794 | * \sa SDL_SetHintWithPriority |
2795 | */ |
2796 | extern DECLSPEC const char * SDLCALL SDL_GetHint(const char *name); |
2797 | |
2798 | /** |
2799 | * Get the boolean value of a hint variable. |
2800 | * |
2801 | * \param name the name of the hint to get the boolean value from |
2802 | * \param default_value the value to return if the hint does not exist |
2803 | * \returns the boolean value of a hint or the provided default value if the |
2804 | * hint does not exist. |
2805 | * |
2806 | * \since This function is available since SDL 2.0.5. |
2807 | * |
2808 | * \sa SDL_GetHint |
2809 | * \sa SDL_SetHint |
2810 | */ |
2811 | extern DECLSPEC SDL_bool SDLCALL SDL_GetHintBoolean(const char *name, SDL_bool default_value); |
2812 | |
2813 | /** |
2814 | * Type definition of the hint callback function. |
2815 | * |
2816 | * \param userdata what was passed as `userdata` to SDL_AddHintCallback() |
2817 | * \param name what was passed as `name` to SDL_AddHintCallback() |
2818 | * \param oldValue the previous hint value |
2819 | * \param newValue the new value hint is to be set to |
2820 | */ |
2821 | typedef void (SDLCALL *SDL_HintCallback)(void *userdata, const char *name, const char *oldValue, const char *newValue); |
2822 | |
2823 | /** |
2824 | * Add a function to watch a particular hint. |
2825 | * |
2826 | * \param name the hint to watch |
2827 | * \param callback An SDL_HintCallback function that will be called when the |
2828 | * hint value changes |
2829 | * \param userdata a pointer to pass to the callback function |
2830 | * |
2831 | * \since This function is available since SDL 2.0.0. |
2832 | * |
2833 | * \sa SDL_DelHintCallback |
2834 | */ |
2835 | extern DECLSPEC void SDLCALL SDL_AddHintCallback(const char *name, |
2836 | SDL_HintCallback callback, |
2837 | void *userdata); |
2838 | |
2839 | /** |
2840 | * Remove a function watching a particular hint. |
2841 | * |
2842 | * \param name the hint being watched |
2843 | * \param callback An SDL_HintCallback function that will be called when the |
2844 | * hint value changes |
2845 | * \param userdata a pointer being passed to the callback function |
2846 | * |
2847 | * \since This function is available since SDL 2.0.0. |
2848 | * |
2849 | * \sa SDL_AddHintCallback |
2850 | */ |
2851 | extern DECLSPEC void SDLCALL SDL_DelHintCallback(const char *name, |
2852 | SDL_HintCallback callback, |
2853 | void *userdata); |
2854 | |
2855 | /** |
2856 | * Clear all hints. |
2857 | * |
2858 | * This function is automatically called during SDL_Quit(), and deletes all |
2859 | * callbacks without calling them and frees all memory associated with hints. |
2860 | * If you're calling this from application code you probably want to call |
2861 | * SDL_ResetHints() instead. |
2862 | * |
2863 | * This function will be removed from the API the next time we rev the ABI. |
2864 | * |
2865 | * \since This function is available since SDL 2.0.0. |
2866 | * |
2867 | * \sa SDL_ResetHints |
2868 | */ |
2869 | extern DECLSPEC void SDLCALL SDL_ClearHints(void); |
2870 | |
2871 | |
2872 | /* Ends C function definitions when using C++ */ |
2873 | #ifdef __cplusplus |
2874 | } |
2875 | #endif |
2876 | #include "close_code.h" |
2877 | |
2878 | #endif /* SDL_hints_h_ */ |
2879 | |
2880 | /* vi: set ts=4 sw=4 expandtab: */ |
2881 | |