1 | /* |
2 | Simple DirectMedia Layer |
3 | Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org> |
4 | |
5 | This software is provided 'as-is', without any express or implied |
6 | warranty. In no event will the authors be held liable for any damages |
7 | arising from the use of this software. |
8 | |
9 | Permission is granted to anyone to use this software for any purpose, |
10 | including commercial applications, and to alter it and redistribute it |
11 | freely, subject to the following restrictions: |
12 | |
13 | 1. The origin of this software must not be misrepresented; you must not |
14 | claim that you wrote the original software. If you use this software |
15 | in a product, an acknowledgment in the product documentation would be |
16 | appreciated but is not required. |
17 | 2. Altered source versions must be plainly marked as such, and must not be |
18 | misrepresented as being the original software. |
19 | 3. This notice may not be removed or altered from any source distribution. |
20 | */ |
21 | |
22 | /** |
23 | * # CategoryHints |
24 | * |
25 | * This file contains functions to set and get configuration hints, as well as |
26 | * listing each of them alphabetically. |
27 | * |
28 | * The convention for naming hints is SDL_HINT_X, where "SDL_X" is the |
29 | * environment variable that can be used to override the default. |
30 | * |
31 | * In general these hints are just that - they may or may not be supported or |
32 | * applicable on any given platform, but they provide a way for an application |
33 | * or user to give the library a hint as to how they would like the library to |
34 | * work. |
35 | */ |
36 | |
37 | #ifndef SDL_hints_h_ |
38 | #define SDL_hints_h_ |
39 | |
40 | #include <SDL3/SDL_error.h> |
41 | #include <SDL3/SDL_stdinc.h> |
42 | |
43 | #include <SDL3/SDL_begin_code.h> |
44 | /* Set up for C function definitions, even when using C++ */ |
45 | #ifdef __cplusplus |
46 | extern "C" { |
47 | #endif |
48 | |
49 | /** |
50 | * Specify the behavior of Alt+Tab while the keyboard is grabbed. |
51 | * |
52 | * By default, SDL emulates Alt+Tab functionality while the keyboard is |
53 | * grabbed and your window is full-screen. This prevents the user from getting |
54 | * stuck in your application if you've enabled keyboard grab. |
55 | * |
56 | * The variable can be set to the following values: |
57 | * |
58 | * - "0": SDL will not handle Alt+Tab. Your application is responsible for |
59 | * handling Alt+Tab while the keyboard is grabbed. |
60 | * - "1": SDL will minimize your window when Alt+Tab is pressed (default) |
61 | * |
62 | * This hint can be set anytime. |
63 | * |
64 | * \since This hint is available since SDL 3.2.0. |
65 | */ |
66 | #define SDL_HINT_ALLOW_ALT_TAB_WHILE_GRABBED "SDL_ALLOW_ALT_TAB_WHILE_GRABBED" |
67 | |
68 | /** |
69 | * A variable to control whether the SDL activity is allowed to be re-created. |
70 | * |
71 | * If this hint is true, the activity can be recreated on demand by the OS, |
72 | * and Java static data and C++ static data remain with their current values. |
73 | * If this hint is false, then SDL will call exit() when you return from your |
74 | * main function and the application will be terminated and then started fresh |
75 | * each time. |
76 | * |
77 | * The variable can be set to the following values: |
78 | * |
79 | * - "0": The application starts fresh at each launch. (default) |
80 | * - "1": The application activity can be recreated by the OS. |
81 | * |
82 | * This hint can be set anytime. |
83 | * |
84 | * \since This hint is available since SDL 3.2.0. |
85 | */ |
86 | #define SDL_HINT_ANDROID_ALLOW_RECREATE_ACTIVITY "SDL_ANDROID_ALLOW_RECREATE_ACTIVITY" |
87 | |
88 | /** |
89 | * A variable to control whether the event loop will block itself when the app |
90 | * is paused. |
91 | * |
92 | * The variable can be set to the following values: |
93 | * |
94 | * - "0": Non blocking. |
95 | * - "1": Blocking. (default) |
96 | * |
97 | * This hint should be set before SDL is initialized. |
98 | * |
99 | * \since This hint is available since SDL 3.2.0. |
100 | */ |
101 | #define SDL_HINT_ANDROID_BLOCK_ON_PAUSE "SDL_ANDROID_BLOCK_ON_PAUSE" |
102 | |
103 | /** |
104 | * A variable to control whether low latency audio should be enabled. |
105 | * |
106 | * Some devices have poor quality output when this is enabled, but this is |
107 | * usually an improvement in audio latency. |
108 | * |
109 | * The variable can be set to the following values: |
110 | * |
111 | * - "0": Low latency audio is not enabled. |
112 | * - "1": Low latency audio is enabled. (default) |
113 | * |
114 | * This hint should be set before SDL audio is initialized. |
115 | * |
116 | * \since This hint is available since SDL 3.2.0. |
117 | */ |
118 | #define SDL_HINT_ANDROID_LOW_LATENCY_AUDIO "SDL_ANDROID_LOW_LATENCY_AUDIO" |
119 | |
120 | /** |
121 | * A variable to control whether we trap the Android back button to handle it |
122 | * manually. |
123 | * |
124 | * This is necessary for the right mouse button to work on some Android |
125 | * devices, or to be able to trap the back button for use in your code |
126 | * reliably. If this hint is true, the back button will show up as an |
127 | * SDL_EVENT_KEY_DOWN / SDL_EVENT_KEY_UP pair with a keycode of |
128 | * SDL_SCANCODE_AC_BACK. |
129 | * |
130 | * The variable can be set to the following values: |
131 | * |
132 | * - "0": Back button will be handled as usual for system. (default) |
133 | * - "1": Back button will be trapped, allowing you to handle the key press |
134 | * manually. (This will also let right mouse click work on systems where the |
135 | * right mouse button functions as back.) |
136 | * |
137 | * This hint can be set anytime. |
138 | * |
139 | * \since This hint is available since SDL 3.2.0. |
140 | */ |
141 | #define SDL_HINT_ANDROID_TRAP_BACK_BUTTON "SDL_ANDROID_TRAP_BACK_BUTTON" |
142 | |
143 | /** |
144 | * A variable setting the app ID string. |
145 | * |
146 | * This string is used by desktop compositors to identify and group windows |
147 | * together, as well as match applications with associated desktop settings |
148 | * and icons. |
149 | * |
150 | * This will override SDL_PROP_APP_METADATA_IDENTIFIER_STRING, if set by the |
151 | * application. |
152 | * |
153 | * This hint should be set before SDL is initialized. |
154 | * |
155 | * \since This hint is available since SDL 3.2.0. |
156 | */ |
157 | #define SDL_HINT_APP_ID "SDL_APP_ID" |
158 | |
159 | /** |
160 | * A variable setting the application name. |
161 | * |
162 | * This hint lets you specify the application name sent to the OS when |
163 | * required. For example, this will often appear in volume control applets for |
164 | * audio streams, and in lists of applications which are inhibiting the |
165 | * screensaver. You should use a string that describes your program ("My Game |
166 | * 2: The Revenge") |
167 | * |
168 | * This will override SDL_PROP_APP_METADATA_NAME_STRING, if set by the |
169 | * application. |
170 | * |
171 | * This hint should be set before SDL is initialized. |
172 | * |
173 | * \since This hint is available since SDL 3.2.0. |
174 | */ |
175 | #define SDL_HINT_APP_NAME "SDL_APP_NAME" |
176 | |
177 | /** |
178 | * A variable controlling whether controllers used with the Apple TV generate |
179 | * UI events. |
180 | * |
181 | * When UI events are generated by controller input, the app will be |
182 | * backgrounded when the Apple TV remote's menu button is pressed, and when |
183 | * the pause or B buttons on gamepads are pressed. |
184 | * |
185 | * More information about properly making use of controllers for the Apple TV |
186 | * can be found here: |
187 | * https://developer.apple.com/tvos/human-interface-guidelines/remote-and-controllers/ |
188 | * |
189 | * The variable can be set to the following values: |
190 | * |
191 | * - "0": Controller input does not generate UI events. (default) |
192 | * - "1": Controller input generates UI events. |
193 | * |
194 | * This hint can be set anytime. |
195 | * |
196 | * \since This hint is available since SDL 3.2.0. |
197 | */ |
198 | #define SDL_HINT_APPLE_TV_CONTROLLER_UI_EVENTS "SDL_APPLE_TV_CONTROLLER_UI_EVENTS" |
199 | |
200 | /** |
201 | * A variable controlling whether the Apple TV remote's joystick axes will |
202 | * automatically match the rotation of the remote. |
203 | * |
204 | * The variable can be set to the following values: |
205 | * |
206 | * - "0": Remote orientation does not affect joystick axes. (default) |
207 | * - "1": Joystick axes are based on the orientation of the remote. |
208 | * |
209 | * This hint can be set anytime. |
210 | * |
211 | * \since This hint is available since SDL 3.2.0. |
212 | */ |
213 | #define SDL_HINT_APPLE_TV_REMOTE_ALLOW_ROTATION "SDL_APPLE_TV_REMOTE_ALLOW_ROTATION" |
214 | |
215 | /** |
216 | * Specify the default ALSA audio device name. |
217 | * |
218 | * This variable is a specific audio device to open when the "default" audio |
219 | * device is used. |
220 | * |
221 | * This hint will be ignored when opening the default playback device if |
222 | * SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE is set, or when opening the |
223 | * default recording device if SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE is |
224 | * set. |
225 | * |
226 | * This hint should be set before an audio device is opened. |
227 | * |
228 | * \since This hint is available since SDL 3.2.0. |
229 | * |
230 | * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE |
231 | * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE |
232 | */ |
233 | #define SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE "SDL_AUDIO_ALSA_DEFAULT_DEVICE" |
234 | |
235 | /** |
236 | * Specify the default ALSA audio playback device name. |
237 | * |
238 | * This variable is a specific audio device to open for playback, when the |
239 | * "default" audio device is used. |
240 | * |
241 | * If this hint isn't set, SDL will check SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE |
242 | * before choosing a reasonable default. |
243 | * |
244 | * This hint should be set before an audio device is opened. |
245 | * |
246 | * \since This hint is available since SDL 3.2.0. |
247 | * |
248 | * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE |
249 | * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE |
250 | */ |
251 | #define SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE "SDL_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE" |
252 | |
253 | /** |
254 | * Specify the default ALSA audio recording device name. |
255 | * |
256 | * This variable is a specific audio device to open for recording, when the |
257 | * "default" audio device is used. |
258 | * |
259 | * If this hint isn't set, SDL will check SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE |
260 | * before choosing a reasonable default. |
261 | * |
262 | * This hint should be set before an audio device is opened. |
263 | * |
264 | * \since This hint is available since SDL 3.2.0. |
265 | * |
266 | * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE |
267 | * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE |
268 | */ |
269 | #define SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE "SDL_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE" |
270 | |
271 | /** |
272 | * A variable controlling the audio category on iOS and macOS. |
273 | * |
274 | * The variable can be set to the following values: |
275 | * |
276 | * - "ambient": Use the AVAudioSessionCategoryAmbient audio category, will be |
277 | * muted by the phone mute switch (default) |
278 | * - "playback": Use the AVAudioSessionCategoryPlayback category. |
279 | * |
280 | * For more information, see Apple's documentation: |
281 | * https://developer.apple.com/library/content/documentation/Audio/Conceptual/AudioSessionProgrammingGuide/AudioSessionCategoriesandModes/AudioSessionCategoriesandModes.html |
282 | * |
283 | * This hint should be set before an audio device is opened. |
284 | * |
285 | * \since This hint is available since SDL 3.2.0. |
286 | */ |
287 | #define SDL_HINT_AUDIO_CATEGORY "SDL_AUDIO_CATEGORY" |
288 | |
289 | /** |
290 | * A variable controlling the default audio channel count. |
291 | * |
292 | * If the application doesn't specify the audio channel count when opening the |
293 | * device, this hint can be used to specify a default channel count that will |
294 | * be used. This defaults to "1" for recording and "2" for playback devices. |
295 | * |
296 | * This hint should be set before an audio device is opened. |
297 | * |
298 | * \since This hint is available since SDL 3.2.0. |
299 | */ |
300 | #define SDL_HINT_AUDIO_CHANNELS "SDL_AUDIO_CHANNELS" |
301 | |
302 | /** |
303 | * Specify an application icon name for an audio device. |
304 | * |
305 | * Some audio backends (such as Pulseaudio and Pipewire) allow you to set an |
306 | * XDG icon name for your application. Among other things, this icon might |
307 | * show up in a system control panel that lets the user adjust the volume on |
308 | * specific audio streams instead of using one giant master volume slider. |
309 | * Note that this is unrelated to the icon used by the windowing system, which |
310 | * may be set with SDL_SetWindowIcon (or via desktop file on Wayland). |
311 | * |
312 | * Setting this to "" or leaving it unset will have SDL use a reasonable |
313 | * default, "applications-games", which is likely to be installed. See |
314 | * https://specifications.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html |
315 | * and |
316 | * https://specifications.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html |
317 | * for the relevant XDG icon specs. |
318 | * |
319 | * This hint should be set before an audio device is opened. |
320 | * |
321 | * \since This hint is available since SDL 3.2.0. |
322 | */ |
323 | #define SDL_HINT_AUDIO_DEVICE_APP_ICON_NAME "SDL_AUDIO_DEVICE_APP_ICON_NAME" |
324 | |
325 | /** |
326 | * A variable controlling device buffer size. |
327 | * |
328 | * This hint is an integer > 0, that represents the size of the device's |
329 | * buffer in sample frames (stereo audio data in 16-bit format is 4 bytes per |
330 | * sample frame, for example). |
331 | * |
332 | * SDL3 generally decides this value on behalf of the app, but if for some |
333 | * reason the app needs to dictate this (because they want either lower |
334 | * latency or higher throughput AND ARE WILLING TO DEAL WITH what that might |
335 | * require of the app), they can specify it. |
336 | * |
337 | * SDL will try to accommodate this value, but there is no promise you'll get |
338 | * the buffer size requested. Many platforms won't honor this request at all, |
339 | * or might adjust it. |
340 | * |
341 | * This hint should be set before an audio device is opened. |
342 | * |
343 | * \since This hint is available since SDL 3.2.0. |
344 | */ |
345 | #define SDL_HINT_AUDIO_DEVICE_SAMPLE_FRAMES "SDL_AUDIO_DEVICE_SAMPLE_FRAMES" |
346 | |
347 | /** |
348 | * Specify an audio stream name for an audio device. |
349 | * |
350 | * Some audio backends (such as PulseAudio) allow you to describe your audio |
351 | * stream. Among other things, this description might show up in a system |
352 | * control panel that lets the user adjust the volume on specific audio |
353 | * streams instead of using one giant master volume slider. |
354 | * |
355 | * This hints lets you transmit that information to the OS. The contents of |
356 | * this hint are used while opening an audio device. You should use a string |
357 | * that describes your what your program is playing ("audio stream" is |
358 | * probably sufficient in many cases, but this could be useful for something |
359 | * like "team chat" if you have a headset playing VoIP audio separately). |
360 | * |
361 | * Setting this to "" or leaving it unset will have SDL use a reasonable |
362 | * default: "audio stream" or something similar. |
363 | * |
364 | * Note that while this talks about audio streams, this is an OS-level |
365 | * concept, so it applies to a physical audio device in this case, and not an |
366 | * SDL_AudioStream, nor an SDL logical audio device. |
367 | * |
368 | * This hint should be set before an audio device is opened. |
369 | * |
370 | * \since This hint is available since SDL 3.2.0. |
371 | */ |
372 | #define SDL_HINT_AUDIO_DEVICE_STREAM_NAME "SDL_AUDIO_DEVICE_STREAM_NAME" |
373 | |
374 | /** |
375 | * Specify an application role for an audio device. |
376 | * |
377 | * Some audio backends (such as Pipewire) allow you to describe the role of |
378 | * your audio stream. Among other things, this description might show up in a |
379 | * system control panel or software for displaying and manipulating media |
380 | * playback/recording graphs. |
381 | * |
382 | * This hints lets you transmit that information to the OS. The contents of |
383 | * this hint are used while opening an audio device. You should use a string |
384 | * that describes your what your program is playing (Game, Music, Movie, |
385 | * etc...). |
386 | * |
387 | * Setting this to "" or leaving it unset will have SDL use a reasonable |
388 | * default: "Game" or something similar. |
389 | * |
390 | * Note that while this talks about audio streams, this is an OS-level |
391 | * concept, so it applies to a physical audio device in this case, and not an |
392 | * SDL_AudioStream, nor an SDL logical audio device. |
393 | * |
394 | * This hint should be set before an audio device is opened. |
395 | * |
396 | * \since This hint is available since SDL 3.2.0. |
397 | */ |
398 | #define SDL_HINT_AUDIO_DEVICE_STREAM_ROLE "SDL_AUDIO_DEVICE_STREAM_ROLE" |
399 | |
400 | /** |
401 | * Specify the input file when recording audio using the disk audio driver. |
402 | * |
403 | * This defaults to "sdlaudio-in.raw" |
404 | * |
405 | * This hint should be set before an audio device is opened. |
406 | * |
407 | * \since This hint is available since SDL 3.2.0. |
408 | */ |
409 | #define SDL_HINT_AUDIO_DISK_INPUT_FILE "SDL_AUDIO_DISK_INPUT_FILE" |
410 | |
411 | /** |
412 | * Specify the output file when playing audio using the disk audio driver. |
413 | * |
414 | * This defaults to "sdlaudio.raw" |
415 | * |
416 | * This hint should be set before an audio device is opened. |
417 | * |
418 | * \since This hint is available since SDL 3.2.0. |
419 | */ |
420 | #define SDL_HINT_AUDIO_DISK_OUTPUT_FILE "SDL_AUDIO_DISK_OUTPUT_FILE" |
421 | |
422 | /** |
423 | * A variable controlling the audio rate when using the disk audio driver. |
424 | * |
425 | * The disk audio driver normally simulates real-time for the audio rate that |
426 | * was specified, but you can use this variable to adjust this rate higher or |
427 | * lower down to 0. The default value is "1.0". |
428 | * |
429 | * This hint should be set before an audio device is opened. |
430 | * |
431 | * \since This hint is available since SDL 3.2.0. |
432 | */ |
433 | #define SDL_HINT_AUDIO_DISK_TIMESCALE "SDL_AUDIO_DISK_TIMESCALE" |
434 | |
435 | /** |
436 | * A variable that specifies an audio backend to use. |
437 | * |
438 | * By default, SDL will try all available audio backends in a reasonable order |
439 | * until it finds one that can work, but this hint allows the app or user to |
440 | * force a specific driver, such as "pipewire" if, say, you are on PulseAudio |
441 | * but want to try talking to the lower level instead. |
442 | * |
443 | * This hint should be set before SDL is initialized. |
444 | * |
445 | * \since This hint is available since SDL 3.2.0. |
446 | */ |
447 | #define SDL_HINT_AUDIO_DRIVER "SDL_AUDIO_DRIVER" |
448 | |
449 | /** |
450 | * A variable controlling the audio rate when using the dummy audio driver. |
451 | * |
452 | * The dummy audio driver normally simulates real-time for the audio rate that |
453 | * was specified, but you can use this variable to adjust this rate higher or |
454 | * lower down to 0. The default value is "1.0". |
455 | * |
456 | * This hint should be set before an audio device is opened. |
457 | * |
458 | * \since This hint is available since SDL 3.2.0. |
459 | */ |
460 | #define SDL_HINT_AUDIO_DUMMY_TIMESCALE "SDL_AUDIO_DUMMY_TIMESCALE" |
461 | |
462 | /** |
463 | * A variable controlling the default audio format. |
464 | * |
465 | * If the application doesn't specify the audio format when opening the |
466 | * device, this hint can be used to specify a default format that will be |
467 | * used. |
468 | * |
469 | * The variable can be set to the following values: |
470 | * |
471 | * - "U8": Unsigned 8-bit audio |
472 | * - "S8": Signed 8-bit audio |
473 | * - "S16LE": Signed 16-bit little-endian audio |
474 | * - "S16BE": Signed 16-bit big-endian audio |
475 | * - "S16": Signed 16-bit native-endian audio (default) |
476 | * - "S32LE": Signed 32-bit little-endian audio |
477 | * - "S32BE": Signed 32-bit big-endian audio |
478 | * - "S32": Signed 32-bit native-endian audio |
479 | * - "F32LE": Floating point little-endian audio |
480 | * - "F32BE": Floating point big-endian audio |
481 | * - "F32": Floating point native-endian audio |
482 | * |
483 | * This hint should be set before an audio device is opened. |
484 | * |
485 | * \since This hint is available since SDL 3.2.0. |
486 | */ |
487 | #define SDL_HINT_AUDIO_FORMAT "SDL_AUDIO_FORMAT" |
488 | |
489 | /** |
490 | * A variable controlling the default audio frequency. |
491 | * |
492 | * If the application doesn't specify the audio frequency when opening the |
493 | * device, this hint can be used to specify a default frequency that will be |
494 | * used. This defaults to "44100". |
495 | * |
496 | * This hint should be set before an audio device is opened. |
497 | * |
498 | * \since This hint is available since SDL 3.2.0. |
499 | */ |
500 | #define SDL_HINT_AUDIO_FREQUENCY "SDL_AUDIO_FREQUENCY" |
501 | |
502 | /** |
503 | * A variable that causes SDL to not ignore audio "monitors". |
504 | * |
505 | * This is currently only used by the PulseAudio driver. |
506 | * |
507 | * By default, SDL ignores audio devices that aren't associated with physical |
508 | * hardware. Changing this hint to "1" will expose anything SDL sees that |
509 | * appears to be an audio source or sink. This will add "devices" to the list |
510 | * that the user probably doesn't want or need, but it can be useful in |
511 | * scenarios where you want to hook up SDL to some sort of virtual device, |
512 | * etc. |
513 | * |
514 | * The variable can be set to the following values: |
515 | * |
516 | * - "0": Audio monitor devices will be ignored. (default) |
517 | * - "1": Audio monitor devices will show up in the device list. |
518 | * |
519 | * This hint should be set before SDL is initialized. |
520 | * |
521 | * \since This hint is available since SDL 3.2.0. |
522 | */ |
523 | #define SDL_HINT_AUDIO_INCLUDE_MONITORS "SDL_AUDIO_INCLUDE_MONITORS" |
524 | |
525 | /** |
526 | * A variable controlling whether SDL updates joystick state when getting |
527 | * input events. |
528 | * |
529 | * The variable can be set to the following values: |
530 | * |
531 | * - "0": You'll call SDL_UpdateJoysticks() manually. |
532 | * - "1": SDL will automatically call SDL_UpdateJoysticks(). (default) |
533 | * |
534 | * This hint can be set anytime. |
535 | * |
536 | * \since This hint is available since SDL 3.2.0. |
537 | */ |
538 | #define SDL_HINT_AUTO_UPDATE_JOYSTICKS "SDL_AUTO_UPDATE_JOYSTICKS" |
539 | |
540 | /** |
541 | * A variable controlling whether SDL updates sensor state when getting input |
542 | * events. |
543 | * |
544 | * The variable can be set to the following values: |
545 | * |
546 | * - "0": You'll call SDL_UpdateSensors() manually. |
547 | * - "1": SDL will automatically call SDL_UpdateSensors(). (default) |
548 | * |
549 | * This hint can be set anytime. |
550 | * |
551 | * \since This hint is available since SDL 3.2.0. |
552 | */ |
553 | #define SDL_HINT_AUTO_UPDATE_SENSORS "SDL_AUTO_UPDATE_SENSORS" |
554 | |
555 | /** |
556 | * Prevent SDL from using version 4 of the bitmap header when saving BMPs. |
557 | * |
558 | * The bitmap header version 4 is required for proper alpha channel support |
559 | * and SDL will use it when required. Should this not be desired, this hint |
560 | * can force the use of the 40 byte header version which is supported |
561 | * everywhere. |
562 | * |
563 | * The variable can be set to the following values: |
564 | * |
565 | * - "0": Surfaces with a colorkey or an alpha channel are saved to a 32-bit |
566 | * BMP file with an alpha mask. SDL will use the bitmap header version 4 and |
567 | * set the alpha mask accordingly. (default) |
568 | * - "1": Surfaces with a colorkey or an alpha channel are saved to a 32-bit |
569 | * BMP file without an alpha mask. The alpha channel data will be in the |
570 | * file, but applications are going to ignore it. |
571 | * |
572 | * This hint can be set anytime. |
573 | * |
574 | * \since This hint is available since SDL 3.2.0. |
575 | */ |
576 | #define SDL_HINT_BMP_SAVE_LEGACY_FORMAT "SDL_BMP_SAVE_LEGACY_FORMAT" |
577 | |
578 | /** |
579 | * A variable that decides what camera backend to use. |
580 | * |
581 | * By default, SDL will try all available camera backends in a reasonable |
582 | * order until it finds one that can work, but this hint allows the app or |
583 | * user to force a specific target, such as "directshow" if, say, you are on |
584 | * Windows Media Foundations but want to try DirectShow instead. |
585 | * |
586 | * The default value is unset, in which case SDL will try to figure out the |
587 | * best camera backend on your behalf. This hint needs to be set before |
588 | * SDL_Init() is called to be useful. |
589 | * |
590 | * \since This hint is available since SDL 3.2.0. |
591 | */ |
592 | #define SDL_HINT_CAMERA_DRIVER "SDL_CAMERA_DRIVER" |
593 | |
594 | /** |
595 | * A variable that limits what CPU features are available. |
596 | * |
597 | * By default, SDL marks all features the current CPU supports as available. |
598 | * This hint allows to limit these to a subset. |
599 | * |
600 | * When the hint is unset, or empty, SDL will enable all detected CPU |
601 | * features. |
602 | * |
603 | * The variable can be set to a comma separated list containing the following |
604 | * items: |
605 | * |
606 | * - "all" |
607 | * - "altivec" |
608 | * - "sse" |
609 | * - "sse2" |
610 | * - "sse3" |
611 | * - "sse41" |
612 | * - "sse42" |
613 | * - "avx" |
614 | * - "avx2" |
615 | * - "avx512f" |
616 | * - "arm-simd" |
617 | * - "neon" |
618 | * - "lsx" |
619 | * - "lasx" |
620 | * |
621 | * The items can be prefixed by '+'/'-' to add/remove features. |
622 | * |
623 | * \since This hint is available since SDL 3.2.0. |
624 | */ |
625 | #define SDL_HINT_CPU_FEATURE_MASK "SDL_CPU_FEATURE_MASK" |
626 | |
627 | /** |
628 | * A variable controlling whether DirectInput should be used for controllers. |
629 | * |
630 | * The variable can be set to the following values: |
631 | * |
632 | * - "0": Disable DirectInput detection. |
633 | * - "1": Enable DirectInput detection. (default) |
634 | * |
635 | * This hint should be set before SDL is initialized. |
636 | * |
637 | * \since This hint is available since SDL 3.2.0. |
638 | */ |
639 | #define SDL_HINT_JOYSTICK_DIRECTINPUT "SDL_JOYSTICK_DIRECTINPUT" |
640 | |
641 | /** |
642 | * A variable that specifies a dialog backend to use. |
643 | * |
644 | * By default, SDL will try all available dialog backends in a reasonable |
645 | * order until it finds one that can work, but this hint allows the app or |
646 | * user to force a specific target. |
647 | * |
648 | * If the specified target does not exist or is not available, the |
649 | * dialog-related function calls will fail. |
650 | * |
651 | * This hint currently only applies to platforms using the generic "Unix" |
652 | * dialog implementation, but may be extended to more platforms in the future. |
653 | * Note that some Unix and Unix-like platforms have their own implementation, |
654 | * such as macOS and Haiku. |
655 | * |
656 | * The variable can be set to the following values: |
657 | * |
658 | * - NULL: Select automatically (default, all platforms) |
659 | * - "portal": Use XDG Portals through DBus (Unix only) |
660 | * - "zenity": Use the Zenity program (Unix only) |
661 | * |
662 | * More options may be added in the future. |
663 | * |
664 | * This hint can be set anytime. |
665 | * |
666 | * \since This hint is available since SDL 3.2.0. |
667 | */ |
668 | #define SDL_HINT_FILE_DIALOG_DRIVER "SDL_FILE_DIALOG_DRIVER" |
669 | |
670 | /** |
671 | * Override for SDL_GetDisplayUsableBounds(). |
672 | * |
673 | * If set, this hint will override the expected results for |
674 | * SDL_GetDisplayUsableBounds() for display index 0. Generally you don't want |
675 | * to do this, but this allows an embedded system to request that some of the |
676 | * screen be reserved for other uses when paired with a well-behaved |
677 | * application. |
678 | * |
679 | * The contents of this hint must be 4 comma-separated integers, the first is |
680 | * the bounds x, then y, width and height, in that order. |
681 | * |
682 | * This hint can be set anytime. |
683 | * |
684 | * \since This hint is available since SDL 3.2.0. |
685 | */ |
686 | #define SDL_HINT_DISPLAY_USABLE_BOUNDS "SDL_DISPLAY_USABLE_BOUNDS" |
687 | |
688 | /** |
689 | * Disable giving back control to the browser automatically when running with |
690 | * asyncify. |
691 | * |
692 | * With -s ASYNCIFY, SDL calls emscripten_sleep during operations such as |
693 | * refreshing the screen or polling events. |
694 | * |
695 | * This hint only applies to the emscripten platform. |
696 | * |
697 | * The variable can be set to the following values: |
698 | * |
699 | * - "0": Disable emscripten_sleep calls (if you give back browser control |
700 | * manually or use asyncify for other purposes). |
701 | * - "1": Enable emscripten_sleep calls. (default) |
702 | * |
703 | * This hint can be set anytime. |
704 | * |
705 | * \since This hint is available since SDL 3.2.0. |
706 | */ |
707 | #define SDL_HINT_EMSCRIPTEN_ASYNCIFY "SDL_EMSCRIPTEN_ASYNCIFY" |
708 | |
709 | /** |
710 | * Specify the CSS selector used for the "default" window/canvas. |
711 | * |
712 | * This hint only applies to the emscripten platform. |
713 | * |
714 | * This hint should be set before creating a window. |
715 | * |
716 | * \since This hint is available since SDL 3.2.0. |
717 | */ |
718 | #define SDL_HINT_EMSCRIPTEN_CANVAS_SELECTOR "SDL_EMSCRIPTEN_CANVAS_SELECTOR" |
719 | |
720 | /** |
721 | * Override the binding element for keyboard inputs for Emscripten builds. |
722 | * |
723 | * This hint only applies to the emscripten platform. |
724 | * |
725 | * The variable can be one of: |
726 | * |
727 | * - "#window": the javascript window object |
728 | * - "#document": the javascript document object |
729 | * - "#screen": the javascript window.screen object |
730 | * - "#canvas": the WebGL canvas element |
731 | * - "#none": Don't bind anything at all |
732 | * - any other string without a leading # sign applies to the element on the |
733 | * page with that ID. |
734 | * |
735 | * This hint should be set before creating a window. |
736 | * |
737 | * \since This hint is available since SDL 3.2.0. |
738 | */ |
739 | #define SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT "SDL_EMSCRIPTEN_KEYBOARD_ELEMENT" |
740 | |
741 | /** |
742 | * A variable that controls whether the on-screen keyboard should be shown |
743 | * when text input is active. |
744 | * |
745 | * The variable can be set to the following values: |
746 | * |
747 | * - "auto": The on-screen keyboard will be shown if there is no physical |
748 | * keyboard attached. (default) |
749 | * - "0": Do not show the on-screen keyboard. |
750 | * - "1": Show the on-screen keyboard, if available. |
751 | * |
752 | * This hint must be set before SDL_StartTextInput() is called |
753 | * |
754 | * \since This hint is available since SDL 3.2.0. |
755 | */ |
756 | #define SDL_HINT_ENABLE_SCREEN_KEYBOARD "SDL_ENABLE_SCREEN_KEYBOARD" |
757 | |
758 | /** |
759 | * A variable containing a list of evdev devices to use if udev is not |
760 | * available. |
761 | * |
762 | * The list of devices is in the form: |
763 | * |
764 | * deviceclass:path[,deviceclass:path[,...]] |
765 | * |
766 | * where device class is an integer representing the SDL_UDEV_deviceclass and |
767 | * path is the full path to the event device. |
768 | * |
769 | * This hint should be set before SDL is initialized. |
770 | * |
771 | * \since This hint is available since SDL 3.2.0. |
772 | */ |
773 | #define SDL_HINT_EVDEV_DEVICES "SDL_EVDEV_DEVICES" |
774 | |
775 | /** |
776 | * A variable controlling verbosity of the logging of SDL events pushed onto |
777 | * the internal queue. |
778 | * |
779 | * The variable can be set to the following values, from least to most |
780 | * verbose: |
781 | * |
782 | * - "0": Don't log any events. (default) |
783 | * - "1": Log most events (other than the really spammy ones). |
784 | * - "2": Include mouse and finger motion events. |
785 | * |
786 | * This is generally meant to be used to debug SDL itself, but can be useful |
787 | * for application developers that need better visibility into what is going |
788 | * on in the event queue. Logged events are sent through SDL_Log(), which |
789 | * means by default they appear on stdout on most platforms or maybe |
790 | * OutputDebugString() on Windows, and can be funneled by the app with |
791 | * SDL_SetLogOutputFunction(), etc. |
792 | * |
793 | * This hint can be set anytime. |
794 | * |
795 | * \since This hint is available since SDL 3.2.0. |
796 | */ |
797 | #define SDL_HINT_EVENT_LOGGING "SDL_EVENT_LOGGING" |
798 | |
799 | /** |
800 | * A variable controlling whether raising the window should be done more |
801 | * forcefully. |
802 | * |
803 | * The variable can be set to the following values: |
804 | * |
805 | * - "0": Honor the OS policy for raising windows. (default) |
806 | * - "1": Force the window to be raised, overriding any OS policy. |
807 | * |
808 | * At present, this is only an issue under MS Windows, which makes it nearly |
809 | * impossible to programmatically move a window to the foreground, for |
810 | * "security" reasons. See http://stackoverflow.com/a/34414846 for a |
811 | * discussion. |
812 | * |
813 | * This hint can be set anytime. |
814 | * |
815 | * \since This hint is available since SDL 3.2.0. |
816 | */ |
817 | #define SDL_HINT_FORCE_RAISEWINDOW "SDL_FORCE_RAISEWINDOW" |
818 | |
819 | /** |
820 | * A variable controlling how 3D acceleration is used to accelerate the SDL |
821 | * screen surface. |
822 | * |
823 | * SDL can try to accelerate the SDL screen surface by using streaming |
824 | * textures with a 3D rendering engine. This variable controls whether and how |
825 | * this is done. |
826 | * |
827 | * The variable can be set to the following values: |
828 | * |
829 | * - "0": Disable 3D acceleration |
830 | * - "1": Enable 3D acceleration, using the default renderer. (default) |
831 | * - "X": Enable 3D acceleration, using X where X is one of the valid |
832 | * rendering drivers. (e.g. "direct3d", "opengl", etc.) |
833 | * |
834 | * This hint should be set before calling SDL_GetWindowSurface() |
835 | * |
836 | * \since This hint is available since SDL 3.2.0. |
837 | */ |
838 | #define SDL_HINT_FRAMEBUFFER_ACCELERATION "SDL_FRAMEBUFFER_ACCELERATION" |
839 | |
840 | /** |
841 | * A variable that lets you manually hint extra gamecontroller db entries. |
842 | * |
843 | * The variable should be newline delimited rows of gamecontroller config |
844 | * data, see SDL_gamepad.h |
845 | * |
846 | * You can update mappings after SDL is initialized with |
847 | * SDL_GetGamepadMappingForGUID() and SDL_AddGamepadMapping() |
848 | * |
849 | * This hint should be set before SDL is initialized. |
850 | * |
851 | * \since This hint is available since SDL 3.2.0. |
852 | */ |
853 | #define SDL_HINT_GAMECONTROLLERCONFIG "SDL_GAMECONTROLLERCONFIG" |
854 | |
855 | /** |
856 | * A variable that lets you provide a file with extra gamecontroller db |
857 | * entries. |
858 | * |
859 | * The file should contain lines of gamecontroller config data, see |
860 | * SDL_gamepad.h |
861 | * |
862 | * You can update mappings after SDL is initialized with |
863 | * SDL_GetGamepadMappingForGUID() and SDL_AddGamepadMapping() |
864 | * |
865 | * This hint should be set before SDL is initialized. |
866 | * |
867 | * \since This hint is available since SDL 3.2.0. |
868 | */ |
869 | #define SDL_HINT_GAMECONTROLLERCONFIG_FILE "SDL_GAMECONTROLLERCONFIG_FILE" |
870 | |
871 | /** |
872 | * A variable that overrides the automatic controller type detection. |
873 | * |
874 | * The variable should be comma separated entries, in the form: VID/PID=type |
875 | * |
876 | * The VID and PID should be hexadecimal with exactly 4 digits, e.g. 0x00fd |
877 | * |
878 | * This hint affects what low level protocol is used with the HIDAPI driver. |
879 | * |
880 | * The variable can be set to the following values: |
881 | * |
882 | * - "Xbox360" |
883 | * - "XboxOne" |
884 | * - "PS3" |
885 | * - "PS4" |
886 | * - "PS5" |
887 | * - "SwitchPro" |
888 | * |
889 | * This hint should be set before SDL is initialized. |
890 | * |
891 | * \since This hint is available since SDL 3.2.0. |
892 | */ |
893 | #define SDL_HINT_GAMECONTROLLERTYPE "SDL_GAMECONTROLLERTYPE" |
894 | |
895 | /** |
896 | * A variable containing a list of devices to skip when scanning for game |
897 | * controllers. |
898 | * |
899 | * The format of the string is a comma separated list of USB VID/PID pairs in |
900 | * hexadecimal form, e.g. |
901 | * |
902 | * 0xAAAA/0xBBBB,0xCCCC/0xDDDD |
903 | * |
904 | * The variable can also take the form of "@file", in which case the named |
905 | * file will be loaded and interpreted as the value of the variable. |
906 | * |
907 | * This hint can be set anytime. |
908 | * |
909 | * \since This hint is available since SDL 3.2.0. |
910 | */ |
911 | #define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES "SDL_GAMECONTROLLER_IGNORE_DEVICES" |
912 | |
913 | /** |
914 | * If set, all devices will be skipped when scanning for game controllers |
915 | * except for the ones listed in this variable. |
916 | * |
917 | * The format of the string is a comma separated list of USB VID/PID pairs in |
918 | * hexadecimal form, e.g. |
919 | * |
920 | * 0xAAAA/0xBBBB,0xCCCC/0xDDDD |
921 | * |
922 | * The variable can also take the form of "@file", in which case the named |
923 | * file will be loaded and interpreted as the value of the variable. |
924 | * |
925 | * This hint can be set anytime. |
926 | * |
927 | * \since This hint is available since SDL 3.2.0. |
928 | */ |
929 | #define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT "SDL_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT" |
930 | |
931 | /** |
932 | * A variable that controls whether the device's built-in accelerometer and |
933 | * gyro should be used as sensors for gamepads. |
934 | * |
935 | * The variable can be set to the following values: |
936 | * |
937 | * - "0": Sensor fusion is disabled |
938 | * - "1": Sensor fusion is enabled for all controllers that lack sensors |
939 | * |
940 | * Or the variable can be a comma separated list of USB VID/PID pairs in |
941 | * hexadecimal form, e.g. |
942 | * |
943 | * 0xAAAA/0xBBBB,0xCCCC/0xDDDD |
944 | * |
945 | * The variable can also take the form of "@file", in which case the named |
946 | * file will be loaded and interpreted as the value of the variable. |
947 | * |
948 | * This hint should be set before a gamepad is opened. |
949 | * |
950 | * \since This hint is available since SDL 3.2.0. |
951 | */ |
952 | #define SDL_HINT_GAMECONTROLLER_SENSOR_FUSION "SDL_GAMECONTROLLER_SENSOR_FUSION" |
953 | |
954 | /** |
955 | * This variable sets the default text of the TextInput window on GDK |
956 | * platforms. |
957 | * |
958 | * This hint is available only if SDL_GDK_TEXTINPUT defined. |
959 | * |
960 | * This hint should be set before calling SDL_StartTextInput() |
961 | * |
962 | * \since This hint is available since SDL 3.2.0. |
963 | */ |
964 | #define SDL_HINT_GDK_TEXTINPUT_DEFAULT_TEXT "SDL_GDK_TEXTINPUT_DEFAULT_TEXT" |
965 | |
966 | /** |
967 | * This variable sets the description of the TextInput window on GDK |
968 | * platforms. |
969 | * |
970 | * This hint is available only if SDL_GDK_TEXTINPUT defined. |
971 | * |
972 | * This hint should be set before calling SDL_StartTextInput() |
973 | * |
974 | * \since This hint is available since SDL 3.2.0. |
975 | */ |
976 | #define SDL_HINT_GDK_TEXTINPUT_DESCRIPTION "SDL_GDK_TEXTINPUT_DESCRIPTION" |
977 | |
978 | /** |
979 | * This variable sets the maximum input length of the TextInput window on GDK |
980 | * platforms. |
981 | * |
982 | * The value must be a stringified integer, for example "10" to allow for up |
983 | * to 10 characters of text input. |
984 | * |
985 | * This hint is available only if SDL_GDK_TEXTINPUT defined. |
986 | * |
987 | * This hint should be set before calling SDL_StartTextInput() |
988 | * |
989 | * \since This hint is available since SDL 3.2.0. |
990 | */ |
991 | #define SDL_HINT_GDK_TEXTINPUT_MAX_LENGTH "SDL_GDK_TEXTINPUT_MAX_LENGTH" |
992 | |
993 | /** |
994 | * This variable sets the input scope of the TextInput window on GDK |
995 | * platforms. |
996 | * |
997 | * Set this hint to change the XGameUiTextEntryInputScope value that will be |
998 | * passed to the window creation function. The value must be a stringified |
999 | * integer, for example "0" for XGameUiTextEntryInputScope::Default. |
1000 | * |
1001 | * This hint is available only if SDL_GDK_TEXTINPUT defined. |
1002 | * |
1003 | * This hint should be set before calling SDL_StartTextInput() |
1004 | * |
1005 | * \since This hint is available since SDL 3.2.0. |
1006 | */ |
1007 | #define SDL_HINT_GDK_TEXTINPUT_SCOPE "SDL_GDK_TEXTINPUT_SCOPE" |
1008 | |
1009 | /** |
1010 | * This variable sets the title of the TextInput window on GDK platforms. |
1011 | * |
1012 | * This hint is available only if SDL_GDK_TEXTINPUT defined. |
1013 | * |
1014 | * This hint should be set before calling SDL_StartTextInput() |
1015 | * |
1016 | * \since This hint is available since SDL 3.2.0. |
1017 | */ |
1018 | #define SDL_HINT_GDK_TEXTINPUT_TITLE "SDL_GDK_TEXTINPUT_TITLE" |
1019 | |
1020 | /** |
1021 | * A variable to control whether HIDAPI uses libusb for device access. |
1022 | * |
1023 | * By default libusb will only be used for a few devices that require direct |
1024 | * USB access, and this can be controlled with |
1025 | * SDL_HINT_HIDAPI_LIBUSB_WHITELIST. |
1026 | * |
1027 | * The variable can be set to the following values: |
1028 | * |
1029 | * - "0": HIDAPI will not use libusb for device access. |
1030 | * - "1": HIDAPI will use libusb for device access if available. (default) |
1031 | * |
1032 | * This hint should be set before SDL is initialized. |
1033 | * |
1034 | * \since This hint is available since SDL 3.2.0. |
1035 | */ |
1036 | #define SDL_HINT_HIDAPI_LIBUSB "SDL_HIDAPI_LIBUSB" |
1037 | |
1038 | /** |
1039 | * A variable to control whether HIDAPI uses libusb only for whitelisted |
1040 | * devices. |
1041 | * |
1042 | * By default libusb will only be used for a few devices that require direct |
1043 | * USB access. |
1044 | * |
1045 | * The variable can be set to the following values: |
1046 | * |
1047 | * - "0": HIDAPI will use libusb for all device access. |
1048 | * - "1": HIDAPI will use libusb only for whitelisted devices. (default) |
1049 | * |
1050 | * This hint should be set before SDL is initialized. |
1051 | * |
1052 | * \since This hint is available since SDL 3.2.0. |
1053 | */ |
1054 | #define SDL_HINT_HIDAPI_LIBUSB_WHITELIST "SDL_HIDAPI_LIBUSB_WHITELIST" |
1055 | |
1056 | /** |
1057 | * A variable to control whether HIDAPI uses udev for device detection. |
1058 | * |
1059 | * The variable can be set to the following values: |
1060 | * |
1061 | * - "0": HIDAPI will poll for device changes. |
1062 | * - "1": HIDAPI will use udev for device detection. (default) |
1063 | * |
1064 | * This hint should be set before SDL is initialized. |
1065 | * |
1066 | * \since This hint is available since SDL 3.2.0. |
1067 | */ |
1068 | #define SDL_HINT_HIDAPI_UDEV "SDL_HIDAPI_UDEV" |
1069 | |
1070 | /** |
1071 | * A variable that specifies a GPU backend to use. |
1072 | * |
1073 | * By default, SDL will try all available GPU backends in a reasonable order |
1074 | * until it finds one that can work, but this hint allows the app or user to |
1075 | * force a specific target, such as "direct3d11" if, say, your hardware |
1076 | * supports D3D12 but want to try using D3D11 instead. |
1077 | * |
1078 | * This hint should be set before any GPU functions are called. |
1079 | * |
1080 | * \since This hint is available since SDL 3.2.0. |
1081 | */ |
1082 | #define SDL_HINT_GPU_DRIVER "SDL_GPU_DRIVER" |
1083 | |
1084 | /** |
1085 | * A variable to control whether SDL_hid_enumerate() enumerates all HID |
1086 | * devices or only controllers. |
1087 | * |
1088 | * The variable can be set to the following values: |
1089 | * |
1090 | * - "0": SDL_hid_enumerate() will enumerate all HID devices. |
1091 | * - "1": SDL_hid_enumerate() will only enumerate controllers. (default) |
1092 | * |
1093 | * By default SDL will only enumerate controllers, to reduce risk of hanging |
1094 | * or crashing on devices with bad drivers and avoiding macOS keyboard capture |
1095 | * permission prompts. |
1096 | * |
1097 | * This hint can be set anytime. |
1098 | * |
1099 | * \since This hint is available since SDL 3.2.0. |
1100 | */ |
1101 | #define SDL_HINT_HIDAPI_ENUMERATE_ONLY_CONTROLLERS "SDL_HIDAPI_ENUMERATE_ONLY_CONTROLLERS" |
1102 | |
1103 | /** |
1104 | * A variable containing a list of devices to ignore in SDL_hid_enumerate(). |
1105 | * |
1106 | * The format of the string is a comma separated list of USB VID/PID pairs in |
1107 | * hexadecimal form, e.g. |
1108 | * |
1109 | * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` |
1110 | * |
1111 | * For example, to ignore the Shanwan DS3 controller and any Valve controller, |
1112 | * you might use the string "0x2563/0x0523,0x28de/0x0000" |
1113 | * |
1114 | * This hint can be set anytime. |
1115 | * |
1116 | * \since This hint is available since SDL 3.2.0. |
1117 | */ |
1118 | #define SDL_HINT_HIDAPI_IGNORE_DEVICES "SDL_HIDAPI_IGNORE_DEVICES" |
1119 | |
1120 | /** |
1121 | * A variable describing what IME UI elements the application can display. |
1122 | * |
1123 | * By default IME UI is handled using native components by the OS where |
1124 | * possible, however this can interfere with or not be visible when exclusive |
1125 | * fullscreen mode is used. |
1126 | * |
1127 | * The variable can be set to a comma separated list containing the following |
1128 | * items: |
1129 | * |
1130 | * - "none" or "0": The application can't render any IME elements, and native |
1131 | * UI should be used. (default) |
1132 | * - "composition": The application handles SDL_EVENT_TEXT_EDITING events and |
1133 | * can render the composition text. |
1134 | * - "candidates": The application handles SDL_EVENT_TEXT_EDITING_CANDIDATES |
1135 | * and can render the candidate list. |
1136 | * |
1137 | * This hint should be set before SDL is initialized. |
1138 | * |
1139 | * \since This hint is available since SDL 3.2.0. |
1140 | */ |
1141 | #define SDL_HINT_IME_IMPLEMENTED_UI "SDL_IME_IMPLEMENTED_UI" |
1142 | |
1143 | /** |
1144 | * A variable controlling whether the home indicator bar on iPhone X should be |
1145 | * hidden. |
1146 | * |
1147 | * The variable can be set to the following values: |
1148 | * |
1149 | * - "0": The indicator bar is not hidden. (default for windowed applications) |
1150 | * - "1": The indicator bar is hidden and is shown when the screen is touched |
1151 | * (useful for movie playback applications). |
1152 | * - "2": The indicator bar is dim and the first swipe makes it visible and |
1153 | * the second swipe performs the "home" action. (default for fullscreen |
1154 | * applications) |
1155 | * |
1156 | * This hint can be set anytime. |
1157 | * |
1158 | * \since This hint is available since SDL 3.2.0. |
1159 | */ |
1160 | #define SDL_HINT_IOS_HIDE_HOME_INDICATOR "SDL_IOS_HIDE_HOME_INDICATOR" |
1161 | |
1162 | /** |
1163 | * A variable that lets you enable joystick (and gamecontroller) events even |
1164 | * when your app is in the background. |
1165 | * |
1166 | * The variable can be set to the following values: |
1167 | * |
1168 | * - "0": Disable joystick & gamecontroller input events when the application |
1169 | * is in the background. (default) |
1170 | * - "1": Enable joystick & gamecontroller input events when the application |
1171 | * is in the background. |
1172 | * |
1173 | * This hint can be set anytime. |
1174 | * |
1175 | * \since This hint is available since SDL 3.2.0. |
1176 | */ |
1177 | #define SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS "SDL_JOYSTICK_ALLOW_BACKGROUND_EVENTS" |
1178 | |
1179 | /** |
1180 | * A variable containing a list of arcade stick style controllers. |
1181 | * |
1182 | * The format of the string is a comma separated list of USB VID/PID pairs in |
1183 | * hexadecimal form, e.g. |
1184 | * |
1185 | * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` |
1186 | * |
1187 | * The variable can also take the form of "@file", in which case the named |
1188 | * file will be loaded and interpreted as the value of the variable. |
1189 | * |
1190 | * This hint can be set anytime. |
1191 | * |
1192 | * \since This hint is available since SDL 3.2.0. |
1193 | */ |
1194 | #define SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES "SDL_JOYSTICK_ARCADESTICK_DEVICES" |
1195 | |
1196 | /** |
1197 | * A variable containing a list of devices that are not arcade stick style |
1198 | * controllers. |
1199 | * |
1200 | * This will override SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES and the built in |
1201 | * device list. |
1202 | * |
1203 | * The format of the string is a comma separated list of USB VID/PID pairs in |
1204 | * hexadecimal form, e.g. |
1205 | * |
1206 | * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` |
1207 | * |
1208 | * The variable can also take the form of "@file", in which case the named |
1209 | * file will be loaded and interpreted as the value of the variable. |
1210 | * |
1211 | * This hint can be set anytime. |
1212 | * |
1213 | * \since This hint is available since SDL 3.2.0. |
1214 | */ |
1215 | #define SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED "SDL_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED" |
1216 | |
1217 | /** |
1218 | * A variable containing a list of devices that should not be considered |
1219 | * joysticks. |
1220 | * |
1221 | * The format of the string is a comma separated list of USB VID/PID pairs in |
1222 | * hexadecimal form, e.g. |
1223 | * |
1224 | * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` |
1225 | * |
1226 | * The variable can also take the form of "@file", in which case the named |
1227 | * file will be loaded and interpreted as the value of the variable. |
1228 | * |
1229 | * This hint can be set anytime. |
1230 | * |
1231 | * \since This hint is available since SDL 3.2.0. |
1232 | */ |
1233 | #define SDL_HINT_JOYSTICK_BLACKLIST_DEVICES "SDL_JOYSTICK_BLACKLIST_DEVICES" |
1234 | |
1235 | /** |
1236 | * A variable containing a list of devices that should be considered |
1237 | * joysticks. |
1238 | * |
1239 | * This will override SDL_HINT_JOYSTICK_BLACKLIST_DEVICES and the built in |
1240 | * device list. |
1241 | * |
1242 | * The format of the string is a comma separated list of USB VID/PID pairs in |
1243 | * hexadecimal form, e.g. |
1244 | * |
1245 | * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` |
1246 | * |
1247 | * The variable can also take the form of "@file", in which case the named |
1248 | * file will be loaded and interpreted as the value of the variable. |
1249 | * |
1250 | * This hint can be set anytime. |
1251 | * |
1252 | * \since This hint is available since SDL 3.2.0. |
1253 | */ |
1254 | #define SDL_HINT_JOYSTICK_BLACKLIST_DEVICES_EXCLUDED "SDL_JOYSTICK_BLACKLIST_DEVICES_EXCLUDED" |
1255 | |
1256 | /** |
1257 | * A variable containing a comma separated list of devices to open as |
1258 | * joysticks. |
1259 | * |
1260 | * This variable is currently only used by the Linux joystick driver. |
1261 | * |
1262 | * \since This hint is available since SDL 3.2.0. |
1263 | */ |
1264 | #define SDL_HINT_JOYSTICK_DEVICE "SDL_JOYSTICK_DEVICE" |
1265 | |
1266 | /** |
1267 | * A variable controlling whether enhanced reports should be used for |
1268 | * controllers when using the HIDAPI driver. |
1269 | * |
1270 | * Enhanced reports allow rumble and effects on Bluetooth PlayStation |
1271 | * controllers and gyro on Nintendo Switch controllers, but break Windows |
1272 | * DirectInput for other applications that don't use SDL. |
1273 | * |
1274 | * Once enhanced reports are enabled, they can't be disabled on PlayStation |
1275 | * controllers without power cycling the controller. |
1276 | * |
1277 | * The variable can be set to the following values: |
1278 | * |
1279 | * - "0": enhanced reports are not enabled. |
1280 | * - "1": enhanced reports are enabled. (default) |
1281 | * - "auto": enhanced features are advertised to the application, but SDL |
1282 | * doesn't change the controller report mode unless the application uses |
1283 | * them. |
1284 | * |
1285 | * This hint can be enabled anytime. |
1286 | * |
1287 | * \since This hint is available since SDL 3.2.0. |
1288 | */ |
1289 | #define SDL_HINT_JOYSTICK_ENHANCED_REPORTS "SDL_JOYSTICK_ENHANCED_REPORTS" |
1290 | |
1291 | /** |
1292 | * A variable containing a list of flightstick style controllers. |
1293 | * |
1294 | * The format of the string is a comma separated list of USB VID/PID pairs in |
1295 | * hexadecimal form, e.g. |
1296 | * |
1297 | * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` |
1298 | * |
1299 | * The variable can also take the form of @file, in which case the named file |
1300 | * will be loaded and interpreted as the value of the variable. |
1301 | * |
1302 | * This hint can be set anytime. |
1303 | * |
1304 | * \since This hint is available since SDL 3.2.0. |
1305 | */ |
1306 | #define SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES "SDL_JOYSTICK_FLIGHTSTICK_DEVICES" |
1307 | |
1308 | /** |
1309 | * A variable containing a list of devices that are not flightstick style |
1310 | * controllers. |
1311 | * |
1312 | * This will override SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES and the built in |
1313 | * device list. |
1314 | * |
1315 | * The format of the string is a comma separated list of USB VID/PID pairs in |
1316 | * hexadecimal form, e.g. |
1317 | * |
1318 | * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` |
1319 | * |
1320 | * The variable can also take the form of "@file", in which case the named |
1321 | * file will be loaded and interpreted as the value of the variable. |
1322 | * |
1323 | * This hint can be set anytime. |
1324 | * |
1325 | * \since This hint is available since SDL 3.2.0. |
1326 | */ |
1327 | #define SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED "SDL_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED" |
1328 | |
1329 | /** |
1330 | * A variable controlling whether GameInput should be used for controller |
1331 | * handling on Windows. |
1332 | * |
1333 | * The variable can be set to the following values: |
1334 | * |
1335 | * - "0": GameInput is not used. |
1336 | * - "1": GameInput is used. |
1337 | * |
1338 | * The default is "1" on GDK platforms, and "0" otherwise. |
1339 | * |
1340 | * This hint should be set before SDL is initialized. |
1341 | * |
1342 | * \since This hint is available since SDL 3.2.0. |
1343 | */ |
1344 | #define SDL_HINT_JOYSTICK_GAMEINPUT "SDL_JOYSTICK_GAMEINPUT" |
1345 | |
1346 | /** |
1347 | * A variable containing a list of devices known to have a GameCube form |
1348 | * factor. |
1349 | * |
1350 | * The format of the string is a comma separated list of USB VID/PID pairs in |
1351 | * hexadecimal form, e.g. |
1352 | * |
1353 | * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` |
1354 | * |
1355 | * The variable can also take the form of "@file", in which case the named |
1356 | * file will be loaded and interpreted as the value of the variable. |
1357 | * |
1358 | * This hint can be set anytime. |
1359 | * |
1360 | * \since This hint is available since SDL 3.2.0. |
1361 | */ |
1362 | #define SDL_HINT_JOYSTICK_GAMECUBE_DEVICES "SDL_JOYSTICK_GAMECUBE_DEVICES" |
1363 | |
1364 | /** |
1365 | * A variable containing a list of devices known not to have a GameCube form |
1366 | * factor. |
1367 | * |
1368 | * This will override SDL_HINT_JOYSTICK_GAMECUBE_DEVICES and the built in |
1369 | * device list. |
1370 | * |
1371 | * The format of the string is a comma separated list of USB VID/PID pairs in |
1372 | * hexadecimal form, e.g. |
1373 | * |
1374 | * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` |
1375 | * |
1376 | * The variable can also take the form of "@file", in which case the named |
1377 | * file will be loaded and interpreted as the value of the variable. |
1378 | * |
1379 | * This hint can be set anytime. |
1380 | * |
1381 | * \since This hint is available since SDL 3.2.0. |
1382 | */ |
1383 | #define SDL_HINT_JOYSTICK_GAMECUBE_DEVICES_EXCLUDED "SDL_JOYSTICK_GAMECUBE_DEVICES_EXCLUDED" |
1384 | |
1385 | /** |
1386 | * A variable controlling whether the HIDAPI joystick drivers should be used. |
1387 | * |
1388 | * The variable can be set to the following values: |
1389 | * |
1390 | * - "0": HIDAPI drivers are not used. |
1391 | * - "1": HIDAPI drivers are used. (default) |
1392 | * |
1393 | * This variable is the default for all drivers, but can be overridden by the |
1394 | * hints for specific drivers below. |
1395 | * |
1396 | * This hint should be set before initializing joysticks and gamepads. |
1397 | * |
1398 | * \since This hint is available since SDL 3.2.0. |
1399 | */ |
1400 | #define SDL_HINT_JOYSTICK_HIDAPI "SDL_JOYSTICK_HIDAPI" |
1401 | |
1402 | /** |
1403 | * A variable controlling whether Nintendo Switch Joy-Con controllers will be |
1404 | * combined into a single Pro-like controller when using the HIDAPI driver. |
1405 | * |
1406 | * The variable can be set to the following values: |
1407 | * |
1408 | * - "0": Left and right Joy-Con controllers will not be combined and each |
1409 | * will be a mini-gamepad. |
1410 | * - "1": Left and right Joy-Con controllers will be combined into a single |
1411 | * controller. (default) |
1412 | * |
1413 | * This hint should be set before initializing joysticks and gamepads. |
1414 | * |
1415 | * \since This hint is available since SDL 3.2.0. |
1416 | */ |
1417 | #define SDL_HINT_JOYSTICK_HIDAPI_COMBINE_JOY_CONS "SDL_JOYSTICK_HIDAPI_COMBINE_JOY_CONS" |
1418 | |
1419 | /** |
1420 | * A variable controlling whether the HIDAPI driver for Nintendo GameCube |
1421 | * controllers should be used. |
1422 | * |
1423 | * The variable can be set to the following values: |
1424 | * |
1425 | * - "0": HIDAPI driver is not used. |
1426 | * - "1": HIDAPI driver is used. |
1427 | * |
1428 | * The default is the value of SDL_HINT_JOYSTICK_HIDAPI |
1429 | * |
1430 | * This hint should be set before initializing joysticks and gamepads. |
1431 | * |
1432 | * \since This hint is available since SDL 3.2.0. |
1433 | */ |
1434 | #define SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE "SDL_JOYSTICK_HIDAPI_GAMECUBE" |
1435 | |
1436 | /** |
1437 | * A variable controlling whether rumble is used to implement the GameCube |
1438 | * controller's 3 rumble modes, Stop(0), Rumble(1), and StopHard(2). |
1439 | * |
1440 | * This is useful for applications that need full compatibility for things |
1441 | * like ADSR envelopes. - Stop is implemented by setting low_frequency_rumble |
1442 | * to 0 and high_frequency_rumble >0 - Rumble is both at any arbitrary value - |
1443 | * StopHard is implemented by setting both low_frequency_rumble and |
1444 | * high_frequency_rumble to 0 |
1445 | * |
1446 | * The variable can be set to the following values: |
1447 | * |
1448 | * - "0": Normal rumble behavior is behavior is used. (default) |
1449 | * - "1": Proper GameCube controller rumble behavior is used. |
1450 | * |
1451 | * This hint can be set anytime. |
1452 | * |
1453 | * \since This hint is available since SDL 3.2.0. |
1454 | */ |
1455 | #define SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE "SDL_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE" |
1456 | |
1457 | /** |
1458 | * A variable controlling whether the HIDAPI driver for Nintendo Switch |
1459 | * Joy-Cons should be used. |
1460 | * |
1461 | * The variable can be set to the following values: |
1462 | * |
1463 | * - "0": HIDAPI driver is not used. |
1464 | * - "1": HIDAPI driver is used. |
1465 | * |
1466 | * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. |
1467 | * |
1468 | * This hint should be set before initializing joysticks and gamepads. |
1469 | * |
1470 | * \since This hint is available since SDL 3.2.0. |
1471 | */ |
1472 | #define SDL_HINT_JOYSTICK_HIDAPI_JOY_CONS "SDL_JOYSTICK_HIDAPI_JOY_CONS" |
1473 | |
1474 | /** |
1475 | * A variable controlling whether the Home button LED should be turned on when |
1476 | * a Nintendo Switch Joy-Con controller is opened. |
1477 | * |
1478 | * The variable can be set to the following values: |
1479 | * |
1480 | * - "0": home button LED is turned off |
1481 | * - "1": home button LED is turned on |
1482 | * |
1483 | * By default the Home button LED state is not changed. This hint can also be |
1484 | * set to a floating point value between 0.0 and 1.0 which controls the |
1485 | * brightness of the Home button LED. |
1486 | * |
1487 | * This hint can be set anytime. |
1488 | * |
1489 | * \since This hint is available since SDL 3.2.0. |
1490 | */ |
1491 | #define SDL_HINT_JOYSTICK_HIDAPI_JOYCON_HOME_LED "SDL_JOYSTICK_HIDAPI_JOYCON_HOME_LED" |
1492 | |
1493 | /** |
1494 | * A variable controlling whether the HIDAPI driver for Amazon Luna |
1495 | * controllers connected via Bluetooth should be used. |
1496 | * |
1497 | * The variable can be set to the following values: |
1498 | * |
1499 | * - "0": HIDAPI driver is not used. |
1500 | * - "1": HIDAPI driver is used. |
1501 | * |
1502 | * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. |
1503 | * |
1504 | * This hint should be set before initializing joysticks and gamepads. |
1505 | * |
1506 | * \since This hint is available since SDL 3.2.0. |
1507 | */ |
1508 | #define SDL_HINT_JOYSTICK_HIDAPI_LUNA "SDL_JOYSTICK_HIDAPI_LUNA" |
1509 | |
1510 | /** |
1511 | * A variable controlling whether the HIDAPI driver for Nintendo Online |
1512 | * classic controllers should be used. |
1513 | * |
1514 | * The variable can be set to the following values: |
1515 | * |
1516 | * - "0": HIDAPI driver is not used. |
1517 | * - "1": HIDAPI driver is used. |
1518 | * |
1519 | * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. |
1520 | * |
1521 | * This hint should be set before initializing joysticks and gamepads. |
1522 | * |
1523 | * \since This hint is available since SDL 3.2.0. |
1524 | */ |
1525 | #define SDL_HINT_JOYSTICK_HIDAPI_NINTENDO_CLASSIC "SDL_JOYSTICK_HIDAPI_NINTENDO_CLASSIC" |
1526 | |
1527 | /** |
1528 | * A variable controlling whether the HIDAPI driver for PS3 controllers should |
1529 | * be used. |
1530 | * |
1531 | * The variable can be set to the following values: |
1532 | * |
1533 | * - "0": HIDAPI driver is not used. |
1534 | * - "1": HIDAPI driver is used. |
1535 | * |
1536 | * The default is the value of SDL_HINT_JOYSTICK_HIDAPI on macOS, and "0" on |
1537 | * other platforms. |
1538 | * |
1539 | * For official Sony driver (sixaxis.sys) use |
1540 | * SDL_HINT_JOYSTICK_HIDAPI_PS3_SIXAXIS_DRIVER. See |
1541 | * https://github.com/ViGEm/DsHidMini for an alternative driver on Windows. |
1542 | * |
1543 | * This hint should be set before initializing joysticks and gamepads. |
1544 | * |
1545 | * \since This hint is available since SDL 3.2.0. |
1546 | */ |
1547 | #define SDL_HINT_JOYSTICK_HIDAPI_PS3 "SDL_JOYSTICK_HIDAPI_PS3" |
1548 | |
1549 | /** |
1550 | * A variable controlling whether the Sony driver (sixaxis.sys) for PS3 |
1551 | * controllers (Sixaxis/DualShock 3) should be used. |
1552 | * |
1553 | * The variable can be set to the following values: |
1554 | * |
1555 | * - "0": Sony driver (sixaxis.sys) is not used. |
1556 | * - "1": Sony driver (sixaxis.sys) is used. |
1557 | * |
1558 | * The default value is 0. |
1559 | * |
1560 | * This hint should be set before initializing joysticks and gamepads. |
1561 | * |
1562 | * \since This hint is available since SDL 3.2.0. |
1563 | */ |
1564 | #define SDL_HINT_JOYSTICK_HIDAPI_PS3_SIXAXIS_DRIVER "SDL_JOYSTICK_HIDAPI_PS3_SIXAXIS_DRIVER" |
1565 | |
1566 | /** |
1567 | * A variable controlling whether the HIDAPI driver for PS4 controllers should |
1568 | * be used. |
1569 | * |
1570 | * The variable can be set to the following values: |
1571 | * |
1572 | * - "0": HIDAPI driver is not used. |
1573 | * - "1": HIDAPI driver is used. |
1574 | * |
1575 | * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. |
1576 | * |
1577 | * This hint should be set before initializing joysticks and gamepads. |
1578 | * |
1579 | * \since This hint is available since SDL 3.2.0. |
1580 | */ |
1581 | #define SDL_HINT_JOYSTICK_HIDAPI_PS4 "SDL_JOYSTICK_HIDAPI_PS4" |
1582 | |
1583 | /** |
1584 | * A variable controlling the update rate of the PS4 controller over Bluetooth |
1585 | * when using the HIDAPI driver. |
1586 | * |
1587 | * This defaults to 4 ms, to match the behavior over USB, and to be more |
1588 | * friendly to other Bluetooth devices and older Bluetooth hardware on the |
1589 | * computer. It can be set to "1" (1000Hz), "2" (500Hz) and "4" (250Hz) |
1590 | * |
1591 | * This hint can be set anytime, but only takes effect when extended input |
1592 | * reports are enabled. |
1593 | * |
1594 | * \since This hint is available since SDL 3.2.0. |
1595 | */ |
1596 | #define SDL_HINT_JOYSTICK_HIDAPI_PS4_REPORT_INTERVAL "SDL_JOYSTICK_HIDAPI_PS4_REPORT_INTERVAL" |
1597 | |
1598 | /** |
1599 | * A variable controlling whether the HIDAPI driver for PS5 controllers should |
1600 | * be used. |
1601 | * |
1602 | * The variable can be set to the following values: |
1603 | * |
1604 | * - "0": HIDAPI driver is not used. |
1605 | * - "1": HIDAPI driver is used. |
1606 | * |
1607 | * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. |
1608 | * |
1609 | * This hint should be set before initializing joysticks and gamepads. |
1610 | * |
1611 | * \since This hint is available since SDL 3.2.0. |
1612 | */ |
1613 | #define SDL_HINT_JOYSTICK_HIDAPI_PS5 "SDL_JOYSTICK_HIDAPI_PS5" |
1614 | |
1615 | /** |
1616 | * A variable controlling whether the player LEDs should be lit to indicate |
1617 | * which player is associated with a PS5 controller. |
1618 | * |
1619 | * The variable can be set to the following values: |
1620 | * |
1621 | * - "0": player LEDs are not enabled. |
1622 | * - "1": player LEDs are enabled. (default) |
1623 | * |
1624 | * \since This hint is available since SDL 3.2.0. |
1625 | */ |
1626 | #define SDL_HINT_JOYSTICK_HIDAPI_PS5_PLAYER_LED "SDL_JOYSTICK_HIDAPI_PS5_PLAYER_LED" |
1627 | |
1628 | /** |
1629 | * A variable controlling whether the HIDAPI driver for NVIDIA SHIELD |
1630 | * controllers should be used. |
1631 | * |
1632 | * The variable can be set to the following values: |
1633 | * |
1634 | * - "0": HIDAPI driver is not used. |
1635 | * - "1": HIDAPI driver is used. |
1636 | * |
1637 | * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. |
1638 | * |
1639 | * This hint should be set before initializing joysticks and gamepads. |
1640 | * |
1641 | * \since This hint is available since SDL 3.2.0. |
1642 | */ |
1643 | #define SDL_HINT_JOYSTICK_HIDAPI_SHIELD "SDL_JOYSTICK_HIDAPI_SHIELD" |
1644 | |
1645 | /** |
1646 | * A variable controlling whether the HIDAPI driver for Google Stadia |
1647 | * controllers should be used. |
1648 | * |
1649 | * The variable can be set to the following values: |
1650 | * |
1651 | * - "0": HIDAPI driver is not used. |
1652 | * - "1": HIDAPI driver is used. |
1653 | * |
1654 | * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. |
1655 | * |
1656 | * \since This hint is available since SDL 3.2.0. |
1657 | */ |
1658 | #define SDL_HINT_JOYSTICK_HIDAPI_STADIA "SDL_JOYSTICK_HIDAPI_STADIA" |
1659 | |
1660 | /** |
1661 | * A variable controlling whether the HIDAPI driver for Bluetooth Steam |
1662 | * Controllers should be used. |
1663 | * |
1664 | * The variable can be set to the following values: |
1665 | * |
1666 | * - "0": HIDAPI driver is not used. (default) |
1667 | * - "1": HIDAPI driver is used for Steam Controllers, which requires |
1668 | * Bluetooth access and may prompt the user for permission on iOS and |
1669 | * Android. |
1670 | * |
1671 | * This hint should be set before initializing joysticks and gamepads. |
1672 | * |
1673 | * \since This hint is available since SDL 3.2.0. |
1674 | */ |
1675 | #define SDL_HINT_JOYSTICK_HIDAPI_STEAM "SDL_JOYSTICK_HIDAPI_STEAM" |
1676 | |
1677 | /** |
1678 | * A variable controlling whether the Steam button LED should be turned on |
1679 | * when a Steam controller is opened. |
1680 | * |
1681 | * The variable can be set to the following values: |
1682 | * |
1683 | * - "0": Steam button LED is turned off. |
1684 | * - "1": Steam button LED is turned on. |
1685 | * |
1686 | * By default the Steam button LED state is not changed. This hint can also be |
1687 | * set to a floating point value between 0.0 and 1.0 which controls the |
1688 | * brightness of the Steam button LED. |
1689 | * |
1690 | * This hint can be set anytime. |
1691 | * |
1692 | * \since This hint is available since SDL 3.2.0. |
1693 | */ |
1694 | #define SDL_HINT_JOYSTICK_HIDAPI_STEAM_HOME_LED "SDL_JOYSTICK_HIDAPI_STEAM_HOME_LED" |
1695 | |
1696 | /** |
1697 | * A variable controlling whether the HIDAPI driver for the Steam Deck builtin |
1698 | * controller should be used. |
1699 | * |
1700 | * The variable can be set to the following values: |
1701 | * |
1702 | * - "0": HIDAPI driver is not used. |
1703 | * - "1": HIDAPI driver is used. |
1704 | * |
1705 | * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. |
1706 | * |
1707 | * This hint should be set before initializing joysticks and gamepads. |
1708 | * |
1709 | * \since This hint is available since SDL 3.2.0. |
1710 | */ |
1711 | #define SDL_HINT_JOYSTICK_HIDAPI_STEAMDECK "SDL_JOYSTICK_HIDAPI_STEAMDECK" |
1712 | |
1713 | /** |
1714 | * A variable controlling whether the HIDAPI driver for HORI licensed Steam |
1715 | * controllers should be used. |
1716 | * |
1717 | * This variable can be set to the following values: "0" - HIDAPI driver is |
1718 | * not used "1" - HIDAPI driver is used |
1719 | * |
1720 | * The default is the value of SDL_HINT_JOYSTICK_HIDAPI |
1721 | */ |
1722 | #define SDL_HINT_JOYSTICK_HIDAPI_STEAM_HORI "SDL_JOYSTICK_HIDAPI_STEAM_HORI" |
1723 | |
1724 | /** |
1725 | * A variable controlling whether the HIDAPI driver for some Logitech wheels |
1726 | * should be used. |
1727 | * |
1728 | * This variable can be set to the following values: |
1729 | * |
1730 | * - "0": HIDAPI driver is not used |
1731 | * - "1": HIDAPI driver is used |
1732 | * |
1733 | * The default is the value of SDL_HINT_JOYSTICK_HIDAPI |
1734 | */ |
1735 | #define SDL_HINT_JOYSTICK_HIDAPI_LG4FF "SDL_JOYSTICK_HIDAPI_LG4FF" |
1736 | |
1737 | /** |
1738 | * A variable controlling whether the HIDAPI driver for Nintendo Switch |
1739 | * controllers should be used. |
1740 | * |
1741 | * The variable can be set to the following values: |
1742 | * |
1743 | * - "0": HIDAPI driver is not used. |
1744 | * - "1": HIDAPI driver is used. |
1745 | * |
1746 | * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. |
1747 | * |
1748 | * This hint should be set before initializing joysticks and gamepads. |
1749 | * |
1750 | * \since This hint is available since SDL 3.2.0. |
1751 | */ |
1752 | #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH "SDL_JOYSTICK_HIDAPI_SWITCH" |
1753 | |
1754 | /** |
1755 | * A variable controlling whether the Home button LED should be turned on when |
1756 | * a Nintendo Switch Pro controller is opened. |
1757 | * |
1758 | * The variable can be set to the following values: |
1759 | * |
1760 | * - "0": Home button LED is turned off. |
1761 | * - "1": Home button LED is turned on. |
1762 | * |
1763 | * By default the Home button LED state is not changed. This hint can also be |
1764 | * set to a floating point value between 0.0 and 1.0 which controls the |
1765 | * brightness of the Home button LED. |
1766 | * |
1767 | * This hint can be set anytime. |
1768 | * |
1769 | * \since This hint is available since SDL 3.2.0. |
1770 | */ |
1771 | #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH_HOME_LED "SDL_JOYSTICK_HIDAPI_SWITCH_HOME_LED" |
1772 | |
1773 | /** |
1774 | * A variable controlling whether the player LEDs should be lit to indicate |
1775 | * which player is associated with a Nintendo Switch controller. |
1776 | * |
1777 | * The variable can be set to the following values: |
1778 | * |
1779 | * - "0": Player LEDs are not enabled. |
1780 | * - "1": Player LEDs are enabled. (default) |
1781 | * |
1782 | * This hint can be set anytime. |
1783 | * |
1784 | * \since This hint is available since SDL 3.2.0. |
1785 | */ |
1786 | #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED "SDL_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED" |
1787 | |
1788 | /** |
1789 | * A variable controlling whether Nintendo Switch Joy-Con controllers will be |
1790 | * in vertical mode when using the HIDAPI driver. |
1791 | * |
1792 | * The variable can be set to the following values: |
1793 | * |
1794 | * - "0": Left and right Joy-Con controllers will not be in vertical mode. |
1795 | * (default) |
1796 | * - "1": Left and right Joy-Con controllers will be in vertical mode. |
1797 | * |
1798 | * This hint should be set before opening a Joy-Con controller. |
1799 | * |
1800 | * \since This hint is available since SDL 3.2.0. |
1801 | */ |
1802 | #define SDL_HINT_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS "SDL_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS" |
1803 | |
1804 | /** |
1805 | * A variable controlling whether the HIDAPI driver for Nintendo Wii and Wii U |
1806 | * controllers should be used. |
1807 | * |
1808 | * The variable can be set to the following values: |
1809 | * |
1810 | * - "0": HIDAPI driver is not used. |
1811 | * - "1": HIDAPI driver is used. |
1812 | * |
1813 | * This driver doesn't work with the dolphinbar, so the default is false for |
1814 | * now. |
1815 | * |
1816 | * This hint should be set before initializing joysticks and gamepads. |
1817 | * |
1818 | * \since This hint is available since SDL 3.2.0. |
1819 | */ |
1820 | #define SDL_HINT_JOYSTICK_HIDAPI_WII "SDL_JOYSTICK_HIDAPI_WII" |
1821 | |
1822 | /** |
1823 | * A variable controlling whether the player LEDs should be lit to indicate |
1824 | * which player is associated with a Wii controller. |
1825 | * |
1826 | * The variable can be set to the following values: |
1827 | * |
1828 | * - "0": Player LEDs are not enabled. |
1829 | * - "1": Player LEDs are enabled. (default) |
1830 | * |
1831 | * This hint can be set anytime. |
1832 | * |
1833 | * \since This hint is available since SDL 3.2.0. |
1834 | */ |
1835 | #define SDL_HINT_JOYSTICK_HIDAPI_WII_PLAYER_LED "SDL_JOYSTICK_HIDAPI_WII_PLAYER_LED" |
1836 | |
1837 | /** |
1838 | * A variable controlling whether the HIDAPI driver for XBox controllers |
1839 | * should be used. |
1840 | * |
1841 | * The variable can be set to the following values: |
1842 | * |
1843 | * - "0": HIDAPI driver is not used. |
1844 | * - "1": HIDAPI driver is used. |
1845 | * |
1846 | * The default is "0" on Windows, otherwise the value of |
1847 | * SDL_HINT_JOYSTICK_HIDAPI |
1848 | * |
1849 | * This hint should be set before initializing joysticks and gamepads. |
1850 | * |
1851 | * \since This hint is available since SDL 3.2.0. |
1852 | */ |
1853 | #define SDL_HINT_JOYSTICK_HIDAPI_XBOX "SDL_JOYSTICK_HIDAPI_XBOX" |
1854 | |
1855 | /** |
1856 | * A variable controlling whether the HIDAPI driver for XBox 360 controllers |
1857 | * should be used. |
1858 | * |
1859 | * The variable can be set to the following values: |
1860 | * |
1861 | * - "0": HIDAPI driver is not used. |
1862 | * - "1": HIDAPI driver is used. |
1863 | * |
1864 | * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX |
1865 | * |
1866 | * This hint should be set before initializing joysticks and gamepads. |
1867 | * |
1868 | * \since This hint is available since SDL 3.2.0. |
1869 | */ |
1870 | #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 "SDL_JOYSTICK_HIDAPI_XBOX_360" |
1871 | |
1872 | /** |
1873 | * A variable controlling whether the player LEDs should be lit to indicate |
1874 | * which player is associated with an Xbox 360 controller. |
1875 | * |
1876 | * The variable can be set to the following values: |
1877 | * |
1878 | * - "0": Player LEDs are not enabled. |
1879 | * - "1": Player LEDs are enabled. (default) |
1880 | * |
1881 | * This hint can be set anytime. |
1882 | * |
1883 | * \since This hint is available since SDL 3.2.0. |
1884 | */ |
1885 | #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED "SDL_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED" |
1886 | |
1887 | /** |
1888 | * A variable controlling whether the HIDAPI driver for XBox 360 wireless |
1889 | * controllers should be used. |
1890 | * |
1891 | * The variable can be set to the following values: |
1892 | * |
1893 | * - "0": HIDAPI driver is not used. |
1894 | * - "1": HIDAPI driver is used. |
1895 | * |
1896 | * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 |
1897 | * |
1898 | * This hint should be set before initializing joysticks and gamepads. |
1899 | * |
1900 | * \since This hint is available since SDL 3.2.0. |
1901 | */ |
1902 | #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_WIRELESS "SDL_JOYSTICK_HIDAPI_XBOX_360_WIRELESS" |
1903 | |
1904 | /** |
1905 | * A variable controlling whether the HIDAPI driver for XBox One controllers |
1906 | * should be used. |
1907 | * |
1908 | * The variable can be set to the following values: |
1909 | * |
1910 | * - "0": HIDAPI driver is not used. |
1911 | * - "1": HIDAPI driver is used. |
1912 | * |
1913 | * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX. |
1914 | * |
1915 | * This hint should be set before initializing joysticks and gamepads. |
1916 | * |
1917 | * \since This hint is available since SDL 3.2.0. |
1918 | */ |
1919 | #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE "SDL_JOYSTICK_HIDAPI_XBOX_ONE" |
1920 | |
1921 | /** |
1922 | * A variable controlling whether the Home button LED should be turned on when |
1923 | * an Xbox One controller is opened. |
1924 | * |
1925 | * The variable can be set to the following values: |
1926 | * |
1927 | * - "0": Home button LED is turned off. |
1928 | * - "1": Home button LED is turned on. |
1929 | * |
1930 | * By default the Home button LED state is not changed. This hint can also be |
1931 | * set to a floating point value between 0.0 and 1.0 which controls the |
1932 | * brightness of the Home button LED. The default brightness is 0.4. |
1933 | * |
1934 | * This hint can be set anytime. |
1935 | * |
1936 | * \since This hint is available since SDL 3.2.0. |
1937 | */ |
1938 | #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED "SDL_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED" |
1939 | |
1940 | /** |
1941 | * A variable controlling whether IOKit should be used for controller |
1942 | * handling. |
1943 | * |
1944 | * The variable can be set to the following values: |
1945 | * |
1946 | * - "0": IOKit is not used. |
1947 | * - "1": IOKit is used. (default) |
1948 | * |
1949 | * This hint should be set before SDL is initialized. |
1950 | * |
1951 | * \since This hint is available since SDL 3.2.0. |
1952 | */ |
1953 | #define SDL_HINT_JOYSTICK_IOKIT "SDL_JOYSTICK_IOKIT" |
1954 | |
1955 | /** |
1956 | * A variable controlling whether to use the classic /dev/input/js* joystick |
1957 | * interface or the newer /dev/input/event* joystick interface on Linux. |
1958 | * |
1959 | * The variable can be set to the following values: |
1960 | * |
1961 | * - "0": Use /dev/input/event* (default) |
1962 | * - "1": Use /dev/input/js* |
1963 | * |
1964 | * This hint should be set before SDL is initialized. |
1965 | * |
1966 | * \since This hint is available since SDL 3.2.0. |
1967 | */ |
1968 | #define SDL_HINT_JOYSTICK_LINUX_CLASSIC "SDL_JOYSTICK_LINUX_CLASSIC" |
1969 | |
1970 | /** |
1971 | * A variable controlling whether joysticks on Linux adhere to their |
1972 | * HID-defined deadzones or return unfiltered values. |
1973 | * |
1974 | * The variable can be set to the following values: |
1975 | * |
1976 | * - "0": Return unfiltered joystick axis values. (default) |
1977 | * - "1": Return axis values with deadzones taken into account. |
1978 | * |
1979 | * This hint should be set before a controller is opened. |
1980 | * |
1981 | * \since This hint is available since SDL 3.2.0. |
1982 | */ |
1983 | #define SDL_HINT_JOYSTICK_LINUX_DEADZONES "SDL_JOYSTICK_LINUX_DEADZONES" |
1984 | |
1985 | /** |
1986 | * A variable controlling whether joysticks on Linux will always treat 'hat' |
1987 | * axis inputs (ABS_HAT0X - ABS_HAT3Y) as 8-way digital hats without checking |
1988 | * whether they may be analog. |
1989 | * |
1990 | * The variable can be set to the following values: |
1991 | * |
1992 | * - "0": Only map hat axis inputs to digital hat outputs if the input axes |
1993 | * appear to actually be digital. (default) |
1994 | * - "1": Always handle the input axes numbered ABS_HAT0X to ABS_HAT3Y as |
1995 | * digital hats. |
1996 | * |
1997 | * This hint should be set before a controller is opened. |
1998 | * |
1999 | * \since This hint is available since SDL 3.2.0. |
2000 | */ |
2001 | #define SDL_HINT_JOYSTICK_LINUX_DIGITAL_HATS "SDL_JOYSTICK_LINUX_DIGITAL_HATS" |
2002 | |
2003 | /** |
2004 | * A variable controlling whether digital hats on Linux will apply deadzones |
2005 | * to their underlying input axes or use unfiltered values. |
2006 | * |
2007 | * The variable can be set to the following values: |
2008 | * |
2009 | * - "0": Return digital hat values based on unfiltered input axis values. |
2010 | * - "1": Return digital hat values with deadzones on the input axes taken |
2011 | * into account. (default) |
2012 | * |
2013 | * This hint should be set before a controller is opened. |
2014 | * |
2015 | * \since This hint is available since SDL 3.2.0. |
2016 | */ |
2017 | #define SDL_HINT_JOYSTICK_LINUX_HAT_DEADZONES "SDL_JOYSTICK_LINUX_HAT_DEADZONES" |
2018 | |
2019 | /** |
2020 | * A variable controlling whether GCController should be used for controller |
2021 | * handling. |
2022 | * |
2023 | * The variable can be set to the following values: |
2024 | * |
2025 | * - "0": GCController is not used. |
2026 | * - "1": GCController is used. (default) |
2027 | * |
2028 | * This hint should be set before SDL is initialized. |
2029 | * |
2030 | * \since This hint is available since SDL 3.2.0. |
2031 | */ |
2032 | #define SDL_HINT_JOYSTICK_MFI "SDL_JOYSTICK_MFI" |
2033 | |
2034 | /** |
2035 | * A variable controlling whether the RAWINPUT joystick drivers should be used |
2036 | * for better handling XInput-capable devices. |
2037 | * |
2038 | * The variable can be set to the following values: |
2039 | * |
2040 | * - "0": RAWINPUT drivers are not used. |
2041 | * - "1": RAWINPUT drivers are used. (default) |
2042 | * |
2043 | * This hint should be set before SDL is initialized. |
2044 | * |
2045 | * \since This hint is available since SDL 3.2.0. |
2046 | */ |
2047 | #define SDL_HINT_JOYSTICK_RAWINPUT "SDL_JOYSTICK_RAWINPUT" |
2048 | |
2049 | /** |
2050 | * A variable controlling whether the RAWINPUT driver should pull correlated |
2051 | * data from XInput. |
2052 | * |
2053 | * The variable can be set to the following values: |
2054 | * |
2055 | * - "0": RAWINPUT driver will only use data from raw input APIs. |
2056 | * - "1": RAWINPUT driver will also pull data from XInput and |
2057 | * Windows.Gaming.Input, providing better trigger axes, guide button |
2058 | * presses, and rumble support for Xbox controllers. (default) |
2059 | * |
2060 | * This hint should be set before a gamepad is opened. |
2061 | * |
2062 | * \since This hint is available since SDL 3.2.0. |
2063 | */ |
2064 | #define SDL_HINT_JOYSTICK_RAWINPUT_CORRELATE_XINPUT "SDL_JOYSTICK_RAWINPUT_CORRELATE_XINPUT" |
2065 | |
2066 | /** |
2067 | * A variable controlling whether the ROG Chakram mice should show up as |
2068 | * joysticks. |
2069 | * |
2070 | * The variable can be set to the following values: |
2071 | * |
2072 | * - "0": ROG Chakram mice do not show up as joysticks. (default) |
2073 | * - "1": ROG Chakram mice show up as joysticks. |
2074 | * |
2075 | * This hint should be set before SDL is initialized. |
2076 | * |
2077 | * \since This hint is available since SDL 3.2.0. |
2078 | */ |
2079 | #define SDL_HINT_JOYSTICK_ROG_CHAKRAM "SDL_JOYSTICK_ROG_CHAKRAM" |
2080 | |
2081 | /** |
2082 | * A variable controlling whether a separate thread should be used for |
2083 | * handling joystick detection and raw input messages on Windows. |
2084 | * |
2085 | * The variable can be set to the following values: |
2086 | * |
2087 | * - "0": A separate thread is not used. |
2088 | * - "1": A separate thread is used for handling raw input messages. (default) |
2089 | * |
2090 | * This hint should be set before SDL is initialized. |
2091 | * |
2092 | * \since This hint is available since SDL 3.2.0. |
2093 | */ |
2094 | #define SDL_HINT_JOYSTICK_THREAD "SDL_JOYSTICK_THREAD" |
2095 | |
2096 | /** |
2097 | * A variable containing a list of throttle style controllers. |
2098 | * |
2099 | * The format of the string is a comma separated list of USB VID/PID pairs in |
2100 | * hexadecimal form, e.g. |
2101 | * |
2102 | * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` |
2103 | * |
2104 | * The variable can also take the form of "@file", in which case the named |
2105 | * file will be loaded and interpreted as the value of the variable. |
2106 | * |
2107 | * This hint can be set anytime. |
2108 | * |
2109 | * \since This hint is available since SDL 3.2.0. |
2110 | */ |
2111 | #define SDL_HINT_JOYSTICK_THROTTLE_DEVICES "SDL_JOYSTICK_THROTTLE_DEVICES" |
2112 | |
2113 | /** |
2114 | * A variable containing a list of devices that are not throttle style |
2115 | * controllers. |
2116 | * |
2117 | * This will override SDL_HINT_JOYSTICK_THROTTLE_DEVICES and the built in |
2118 | * device list. |
2119 | * |
2120 | * The format of the string is a comma separated list of USB VID/PID pairs in |
2121 | * hexadecimal form, e.g. |
2122 | * |
2123 | * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` |
2124 | * |
2125 | * The variable can also take the form of "@file", in which case the named |
2126 | * file will be loaded and interpreted as the value of the variable. |
2127 | * |
2128 | * This hint can be set anytime. |
2129 | * |
2130 | * \since This hint is available since SDL 3.2.0. |
2131 | */ |
2132 | #define SDL_HINT_JOYSTICK_THROTTLE_DEVICES_EXCLUDED "SDL_JOYSTICK_THROTTLE_DEVICES_EXCLUDED" |
2133 | |
2134 | /** |
2135 | * A variable controlling whether Windows.Gaming.Input should be used for |
2136 | * controller handling. |
2137 | * |
2138 | * The variable can be set to the following values: |
2139 | * |
2140 | * - "0": WGI is not used. |
2141 | * - "1": WGI is used. (default) |
2142 | * |
2143 | * This hint should be set before SDL is initialized. |
2144 | * |
2145 | * \since This hint is available since SDL 3.2.0. |
2146 | */ |
2147 | #define SDL_HINT_JOYSTICK_WGI "SDL_JOYSTICK_WGI" |
2148 | |
2149 | /** |
2150 | * A variable containing a list of wheel style controllers. |
2151 | * |
2152 | * The format of the string is a comma separated list of USB VID/PID pairs in |
2153 | * hexadecimal form, e.g. |
2154 | * |
2155 | * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` |
2156 | * |
2157 | * The variable can also take the form of "@file", in which case the named |
2158 | * file will be loaded and interpreted as the value of the variable. |
2159 | * |
2160 | * This hint can be set anytime. |
2161 | * |
2162 | * \since This hint is available since SDL 3.2.0. |
2163 | */ |
2164 | #define SDL_HINT_JOYSTICK_WHEEL_DEVICES "SDL_JOYSTICK_WHEEL_DEVICES" |
2165 | |
2166 | /** |
2167 | * A variable containing a list of devices that are not wheel style |
2168 | * controllers. |
2169 | * |
2170 | * This will override SDL_HINT_JOYSTICK_WHEEL_DEVICES and the built in device |
2171 | * list. |
2172 | * |
2173 | * The format of the string is a comma separated list of USB VID/PID pairs in |
2174 | * hexadecimal form, e.g. |
2175 | * |
2176 | * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` |
2177 | * |
2178 | * The variable can also take the form of "@file", in which case the named |
2179 | * file will be loaded and interpreted as the value of the variable. |
2180 | * |
2181 | * This hint can be set anytime. |
2182 | * |
2183 | * \since This hint is available since SDL 3.2.0. |
2184 | */ |
2185 | #define SDL_HINT_JOYSTICK_WHEEL_DEVICES_EXCLUDED "SDL_JOYSTICK_WHEEL_DEVICES_EXCLUDED" |
2186 | |
2187 | /** |
2188 | * A variable containing a list of devices known to have all axes centered at |
2189 | * zero. |
2190 | * |
2191 | * The format of the string is a comma separated list of USB VID/PID pairs in |
2192 | * hexadecimal form, e.g. |
2193 | * |
2194 | * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` |
2195 | * |
2196 | * The variable can also take the form of "@file", in which case the named |
2197 | * file will be loaded and interpreted as the value of the variable. |
2198 | * |
2199 | * This hint should be set before a controller is opened. |
2200 | * |
2201 | * \since This hint is available since SDL 3.2.0. |
2202 | */ |
2203 | #define SDL_HINT_JOYSTICK_ZERO_CENTERED_DEVICES "SDL_JOYSTICK_ZERO_CENTERED_DEVICES" |
2204 | |
2205 | /** |
2206 | * A variable containing a list of devices and their desired number of haptic |
2207 | * (force feedback) enabled axis. |
2208 | * |
2209 | * The format of the string is a comma separated list of USB VID/PID pairs in |
2210 | * hexadecimal form plus the number of desired axes, e.g. |
2211 | * |
2212 | * `0xAAAA/0xBBBB/1,0xCCCC/0xDDDD/3` |
2213 | * |
2214 | * This hint supports a "wildcard" device that will set the number of haptic |
2215 | * axes on all initialized haptic devices which were not defined explicitly in |
2216 | * this hint. |
2217 | * |
2218 | * `0xFFFF/0xFFFF/1` |
2219 | * |
2220 | * This hint should be set before a controller is opened. The number of haptic |
2221 | * axes won't exceed the number of real axes found on the device. |
2222 | * |
2223 | * \since This hint is available since SDL 3.2.5. |
2224 | */ |
2225 | #define SDL_HINT_JOYSTICK_HAPTIC_AXES "SDL_JOYSTICK_HAPTIC_AXES" |
2226 | |
2227 | /** |
2228 | * A variable that controls keycode representation in keyboard events. |
2229 | * |
2230 | * This variable is a comma separated set of options for translating keycodes |
2231 | * in events: |
2232 | * |
2233 | * - "none": Keycode options are cleared, this overrides other options. |
2234 | * - "hide_numpad": The numpad keysyms will be translated into their |
2235 | * non-numpad versions based on the current NumLock state. For example, |
2236 | * SDLK_KP_4 would become SDLK_4 if SDL_KMOD_NUM is set in the event |
2237 | * modifiers, and SDLK_LEFT if it is unset. |
2238 | * - "french_numbers": The number row on French keyboards is inverted, so |
2239 | * pressing the 1 key would yield the keycode SDLK_1, or '1', instead of |
2240 | * SDLK_AMPERSAND, or '&' |
2241 | * - "latin_letters": For keyboards using non-Latin letters, such as Russian |
2242 | * or Thai, the letter keys generate keycodes as though it had an en_US |
2243 | * layout. e.g. pressing the key associated with SDL_SCANCODE_A on a Russian |
2244 | * keyboard would yield 'a' instead of a Cyrillic letter. |
2245 | * |
2246 | * The default value for this hint is "french_numbers,latin_letters" |
2247 | * |
2248 | * Some platforms like Emscripten only provide modified keycodes and the |
2249 | * options are not used. |
2250 | * |
2251 | * These options do not affect the return value of SDL_GetKeyFromScancode() or |
2252 | * SDL_GetScancodeFromKey(), they just apply to the keycode included in key |
2253 | * events. |
2254 | * |
2255 | * This hint can be set anytime. |
2256 | * |
2257 | * \since This hint is available since SDL 3.2.0. |
2258 | */ |
2259 | #define SDL_HINT_KEYCODE_OPTIONS "SDL_KEYCODE_OPTIONS" |
2260 | |
2261 | /** |
2262 | * A variable that controls what KMSDRM device to use. |
2263 | * |
2264 | * SDL might open something like "/dev/dri/cardNN" to access KMSDRM |
2265 | * functionality, where "NN" is a device index number. SDL makes a guess at |
2266 | * the best index to use (usually zero), but the app or user can set this hint |
2267 | * to a number between 0 and 99 to force selection. |
2268 | * |
2269 | * This hint should be set before SDL is initialized. |
2270 | * |
2271 | * \since This hint is available since SDL 3.2.0. |
2272 | */ |
2273 | #define SDL_HINT_KMSDRM_DEVICE_INDEX "SDL_KMSDRM_DEVICE_INDEX" |
2274 | |
2275 | /** |
2276 | * A variable that controls whether SDL requires DRM master access in order to |
2277 | * initialize the KMSDRM video backend. |
2278 | * |
2279 | * The DRM subsystem has a concept of a "DRM master" which is a DRM client |
2280 | * that has the ability to set planes, set cursor, etc. When SDL is DRM |
2281 | * master, it can draw to the screen using the SDL rendering APIs. Without DRM |
2282 | * master, SDL is still able to process input and query attributes of attached |
2283 | * displays, but it cannot change display state or draw to the screen |
2284 | * directly. |
2285 | * |
2286 | * In some cases, it can be useful to have the KMSDRM backend even if it |
2287 | * cannot be used for rendering. An app may want to use SDL for input |
2288 | * processing while using another rendering API (such as an MMAL overlay on |
2289 | * Raspberry Pi) or using its own code to render to DRM overlays that SDL |
2290 | * doesn't support. |
2291 | * |
2292 | * The variable can be set to the following values: |
2293 | * |
2294 | * - "0": SDL will allow usage of the KMSDRM backend without DRM master. |
2295 | * - "1": SDL Will require DRM master to use the KMSDRM backend. (default) |
2296 | * |
2297 | * This hint should be set before SDL is initialized. |
2298 | * |
2299 | * \since This hint is available since SDL 3.2.0. |
2300 | */ |
2301 | #define SDL_HINT_KMSDRM_REQUIRE_DRM_MASTER "SDL_KMSDRM_REQUIRE_DRM_MASTER" |
2302 | |
2303 | /** |
2304 | * A variable controlling the default SDL log levels. |
2305 | * |
2306 | * This variable is a comma separated set of category=level tokens that define |
2307 | * the default logging levels for SDL applications. |
2308 | * |
2309 | * The category can be a numeric category, one of "app", "error", "assert", |
2310 | * "system", "audio", "video", "render", "input", "test", or `*` for any |
2311 | * unspecified category. |
2312 | * |
2313 | * The level can be a numeric level, one of "verbose", "debug", "info", |
2314 | * "warn", "error", "critical", or "quiet" to disable that category. |
2315 | * |
2316 | * You can omit the category if you want to set the logging level for all |
2317 | * categories. |
2318 | * |
2319 | * If this hint isn't set, the default log levels are equivalent to: |
2320 | * |
2321 | * `app=info,assert=warn,test=verbose,*=error` |
2322 | * |
2323 | * This hint can be set anytime. |
2324 | * |
2325 | * \since This hint is available since SDL 3.2.0. |
2326 | */ |
2327 | #define SDL_HINT_LOGGING "SDL_LOGGING" |
2328 | |
2329 | /** |
2330 | * A variable controlling whether to force the application to become the |
2331 | * foreground process when launched on macOS. |
2332 | * |
2333 | * The variable can be set to the following values: |
2334 | * |
2335 | * - "0": The application is brought to the foreground when launched. |
2336 | * (default) |
2337 | * - "1": The application may remain in the background when launched. |
2338 | * |
2339 | * This hint needs to be set before SDL_Init(). |
2340 | * |
2341 | * \since This hint is available since SDL 3.2.0. |
2342 | */ |
2343 | #define SDL_HINT_MAC_BACKGROUND_APP "SDL_MAC_BACKGROUND_APP" |
2344 | |
2345 | /** |
2346 | * A variable that determines whether Ctrl+Click should generate a right-click |
2347 | * event on macOS. |
2348 | * |
2349 | * The variable can be set to the following values: |
2350 | * |
2351 | * - "0": Ctrl+Click does not generate a right mouse button click event. |
2352 | * (default) |
2353 | * - "1": Ctrl+Click generated a right mouse button click event. |
2354 | * |
2355 | * This hint can be set anytime. |
2356 | * |
2357 | * \since This hint is available since SDL 3.2.0. |
2358 | */ |
2359 | #define SDL_HINT_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK "SDL_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK" |
2360 | |
2361 | /** |
2362 | * A variable controlling whether dispatching OpenGL context updates should |
2363 | * block the dispatching thread until the main thread finishes processing on |
2364 | * macOS. |
2365 | * |
2366 | * The variable can be set to the following values: |
2367 | * |
2368 | * - "0": Dispatching OpenGL context updates will block the dispatching thread |
2369 | * until the main thread finishes processing. (default) |
2370 | * - "1": Dispatching OpenGL context updates will allow the dispatching thread |
2371 | * to continue execution. |
2372 | * |
2373 | * Generally you want the default, but if you have OpenGL code in a background |
2374 | * thread on a Mac, and the main thread hangs because it's waiting for that |
2375 | * background thread, but that background thread is also hanging because it's |
2376 | * waiting for the main thread to do an update, this might fix your issue. |
2377 | * |
2378 | * This hint can be set anytime. |
2379 | * |
2380 | * \since This hint is available since SDL 3.2.0. |
2381 | */ |
2382 | #define SDL_HINT_MAC_OPENGL_ASYNC_DISPATCH "SDL_MAC_OPENGL_ASYNC_DISPATCH" |
2383 | |
2384 | /** |
2385 | * A variable controlling whether the Option key on macOS should be remapped |
2386 | * to act as the Alt key. |
2387 | * |
2388 | * The variable can be set to the following values: |
2389 | * |
2390 | * - "none": The Option key is not remapped to Alt. (default) |
2391 | * - "only_left": Only the left Option key is remapped to Alt. |
2392 | * - "only_right": Only the right Option key is remapped to Alt. |
2393 | * - "both": Both Option keys are remapped to Alt. |
2394 | * |
2395 | * This will prevent the triggering of key compositions that rely on the |
2396 | * Option key, but will still send the Alt modifier for keyboard events. In |
2397 | * the case that both Alt and Option are pressed, the Option key will be |
2398 | * ignored. This is particularly useful for applications like terminal |
2399 | * emulators and graphical user interfaces (GUIs) that rely on Alt key |
2400 | * functionality for shortcuts or navigation. This does not apply to |
2401 | * SDL_GetKeyFromScancode and only has an effect if IME is enabled. |
2402 | * |
2403 | * This hint can be set anytime. |
2404 | * |
2405 | * \since This hint is available since SDL 3.2.0. |
2406 | */ |
2407 | #define SDL_HINT_MAC_OPTION_AS_ALT "SDL_MAC_OPTION_AS_ALT" |
2408 | |
2409 | /** |
2410 | * A variable controlling whether SDL_EVENT_MOUSE_WHEEL event values will have |
2411 | * momentum on macOS. |
2412 | * |
2413 | * The variable can be set to the following values: |
2414 | * |
2415 | * - "0": The mouse wheel events will have no momentum. (default) |
2416 | * - "1": The mouse wheel events will have momentum. |
2417 | * |
2418 | * This hint needs to be set before SDL_Init(). |
2419 | * |
2420 | * \since This hint is available since SDL 3.2.0. |
2421 | */ |
2422 | #define SDL_HINT_MAC_SCROLL_MOMENTUM "SDL_MAC_SCROLL_MOMENTUM" |
2423 | |
2424 | /** |
2425 | * Request SDL_AppIterate() be called at a specific rate. |
2426 | * |
2427 | * If this is set to a number, it represents Hz, so "60" means try to iterate |
2428 | * 60 times per second. "0" means to iterate as fast as possible. Negative |
2429 | * values are illegal, but reserved, in case they are useful in a future |
2430 | * revision of SDL. |
2431 | * |
2432 | * There are other strings that have special meaning. If set to "waitevent", |
2433 | * SDL_AppIterate will not be called until new event(s) have arrived (and been |
2434 | * processed by SDL_AppEvent). This can be useful for apps that are completely |
2435 | * idle except in response to input. |
2436 | * |
2437 | * On some platforms, or if you are using SDL_main instead of SDL_AppIterate, |
2438 | * this hint is ignored. When the hint can be used, it is allowed to be |
2439 | * changed at any time. |
2440 | * |
2441 | * This defaults to 0, and specifying NULL for the hint's value will restore |
2442 | * the default. |
2443 | * |
2444 | * This hint can be set anytime. |
2445 | * |
2446 | * \since This hint is available since SDL 3.2.0. |
2447 | */ |
2448 | #define SDL_HINT_MAIN_CALLBACK_RATE "SDL_MAIN_CALLBACK_RATE" |
2449 | |
2450 | /** |
2451 | * A variable controlling whether the mouse is captured while mouse buttons |
2452 | * are pressed. |
2453 | * |
2454 | * The variable can be set to the following values: |
2455 | * |
2456 | * - "0": The mouse is not captured while mouse buttons are pressed. |
2457 | * - "1": The mouse is captured while mouse buttons are pressed. |
2458 | * |
2459 | * By default the mouse is captured while mouse buttons are pressed so if the |
2460 | * mouse is dragged outside the window, the application continues to receive |
2461 | * mouse events until the button is released. |
2462 | * |
2463 | * This hint can be set anytime. |
2464 | * |
2465 | * \since This hint is available since SDL 3.2.0. |
2466 | */ |
2467 | #define SDL_HINT_MOUSE_AUTO_CAPTURE "SDL_MOUSE_AUTO_CAPTURE" |
2468 | |
2469 | /** |
2470 | * A variable setting the double click radius, in pixels. |
2471 | * |
2472 | * This hint can be set anytime. |
2473 | * |
2474 | * \since This hint is available since SDL 3.2.0. |
2475 | */ |
2476 | #define SDL_HINT_MOUSE_DOUBLE_CLICK_RADIUS "SDL_MOUSE_DOUBLE_CLICK_RADIUS" |
2477 | |
2478 | /** |
2479 | * A variable setting the double click time, in milliseconds. |
2480 | * |
2481 | * This hint can be set anytime. |
2482 | * |
2483 | * \since This hint is available since SDL 3.2.0. |
2484 | */ |
2485 | #define SDL_HINT_MOUSE_DOUBLE_CLICK_TIME "SDL_MOUSE_DOUBLE_CLICK_TIME" |
2486 | |
2487 | /** |
2488 | * A variable setting which system cursor to use as the default cursor. |
2489 | * |
2490 | * This should be an integer corresponding to the SDL_SystemCursor enum. The |
2491 | * default value is zero (SDL_SYSTEM_CURSOR_DEFAULT). |
2492 | * |
2493 | * This hint needs to be set before SDL_Init(). |
2494 | * |
2495 | * \since This hint is available since SDL 3.2.0. |
2496 | */ |
2497 | #define SDL_HINT_MOUSE_DEFAULT_SYSTEM_CURSOR "SDL_MOUSE_DEFAULT_SYSTEM_CURSOR" |
2498 | |
2499 | /** |
2500 | * A variable controlling whether warping a hidden mouse cursor will activate |
2501 | * relative mouse mode. |
2502 | * |
2503 | * When this hint is set, the mouse cursor is hidden, and multiple warps to |
2504 | * the window center occur within a short time period, SDL will emulate mouse |
2505 | * warps using relative mouse mode. This can provide smoother and more |
2506 | * reliable mouse motion for some older games, which continuously calculate |
2507 | * the distance travelled by the mouse pointer and warp it back to the center |
2508 | * of the window, rather than using relative mouse motion. |
2509 | * |
2510 | * Note that relative mouse mode may have different mouse acceleration |
2511 | * behavior than pointer warps. |
2512 | * |
2513 | * If your application needs to repeatedly warp the hidden mouse cursor at a |
2514 | * high-frequency for other purposes, it should disable this hint. |
2515 | * |
2516 | * The variable can be set to the following values: |
2517 | * |
2518 | * - "0": Attempts to warp the mouse will always be made. |
2519 | * - "1": Some mouse warps will be emulated by forcing relative mouse mode. |
2520 | * (default) |
2521 | * |
2522 | * If not set, this is automatically enabled unless an application uses |
2523 | * relative mouse mode directly. |
2524 | * |
2525 | * This hint can be set anytime. |
2526 | * |
2527 | * \since This hint is available since SDL 3.2.0. |
2528 | */ |
2529 | #define SDL_HINT_MOUSE_EMULATE_WARP_WITH_RELATIVE "SDL_MOUSE_EMULATE_WARP_WITH_RELATIVE" |
2530 | |
2531 | /** |
2532 | * Allow mouse click events when clicking to focus an SDL window. |
2533 | * |
2534 | * The variable can be set to the following values: |
2535 | * |
2536 | * - "0": Ignore mouse clicks that activate a window. (default) |
2537 | * - "1": Generate events for mouse clicks that activate a window. |
2538 | * |
2539 | * This hint can be set anytime. |
2540 | * |
2541 | * \since This hint is available since SDL 3.2.0. |
2542 | */ |
2543 | #define SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH "SDL_MOUSE_FOCUS_CLICKTHROUGH" |
2544 | |
2545 | /** |
2546 | * A variable setting the speed scale for mouse motion, in floating point, |
2547 | * when the mouse is not in relative mode. |
2548 | * |
2549 | * This hint can be set anytime. |
2550 | * |
2551 | * \since This hint is available since SDL 3.2.0. |
2552 | */ |
2553 | #define SDL_HINT_MOUSE_NORMAL_SPEED_SCALE "SDL_MOUSE_NORMAL_SPEED_SCALE" |
2554 | |
2555 | /** |
2556 | * A variable controlling whether relative mouse mode constrains the mouse to |
2557 | * the center of the window. |
2558 | * |
2559 | * Constraining to the center of the window works better for FPS games and |
2560 | * when the application is running over RDP. Constraining to the whole window |
2561 | * works better for 2D games and increases the chance that the mouse will be |
2562 | * in the correct position when using high DPI mice. |
2563 | * |
2564 | * The variable can be set to the following values: |
2565 | * |
2566 | * - "0": Relative mouse mode constrains the mouse to the window. |
2567 | * - "1": Relative mouse mode constrains the mouse to the center of the |
2568 | * window. (default) |
2569 | * |
2570 | * This hint can be set anytime. |
2571 | * |
2572 | * \since This hint is available since SDL 3.2.0. |
2573 | */ |
2574 | #define SDL_HINT_MOUSE_RELATIVE_MODE_CENTER "SDL_MOUSE_RELATIVE_MODE_CENTER" |
2575 | |
2576 | /** |
2577 | * A variable setting the scale for mouse motion, in floating point, when the |
2578 | * mouse is in relative mode. |
2579 | * |
2580 | * This hint can be set anytime. |
2581 | * |
2582 | * \since This hint is available since SDL 3.2.0. |
2583 | */ |
2584 | #define SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE "SDL_MOUSE_RELATIVE_SPEED_SCALE" |
2585 | |
2586 | /** |
2587 | * A variable controlling whether the system mouse acceleration curve is used |
2588 | * for relative mouse motion. |
2589 | * |
2590 | * The variable can be set to the following values: |
2591 | * |
2592 | * - "0": Relative mouse motion will be unscaled. (default) |
2593 | * - "1": Relative mouse motion will be scaled using the system mouse |
2594 | * acceleration curve. |
2595 | * |
2596 | * If SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE is set, that will be applied after |
2597 | * system speed scale. |
2598 | * |
2599 | * This hint can be set anytime. |
2600 | * |
2601 | * \since This hint is available since SDL 3.2.0. |
2602 | */ |
2603 | #define SDL_HINT_MOUSE_RELATIVE_SYSTEM_SCALE "SDL_MOUSE_RELATIVE_SYSTEM_SCALE" |
2604 | |
2605 | /** |
2606 | * A variable controlling whether a motion event should be generated for mouse |
2607 | * warping in relative mode. |
2608 | * |
2609 | * The variable can be set to the following values: |
2610 | * |
2611 | * - "0": Warping the mouse will not generate a motion event in relative mode |
2612 | * - "1": Warping the mouse will generate a motion event in relative mode |
2613 | * |
2614 | * By default warping the mouse will not generate motion events in relative |
2615 | * mode. This avoids the application having to filter out large relative |
2616 | * motion due to warping. |
2617 | * |
2618 | * This hint can be set anytime. |
2619 | * |
2620 | * \since This hint is available since SDL 3.2.0. |
2621 | */ |
2622 | #define SDL_HINT_MOUSE_RELATIVE_WARP_MOTION "SDL_MOUSE_RELATIVE_WARP_MOTION" |
2623 | |
2624 | /** |
2625 | * A variable controlling whether the hardware cursor stays visible when |
2626 | * relative mode is active. |
2627 | * |
2628 | * This variable can be set to the following values: |
2629 | * |
2630 | * - "0": The cursor will be hidden while relative mode is active (default) |
2631 | * - "1": The cursor will remain visible while relative mode is active |
2632 | * |
2633 | * Note that for systems without raw hardware inputs, relative mode is |
2634 | * implemented using warping, so the hardware cursor will visibly warp between |
2635 | * frames if this is enabled on those systems. |
2636 | * |
2637 | * This hint can be set anytime. |
2638 | * |
2639 | * \since This hint is available since SDL 3.2.0. |
2640 | */ |
2641 | #define SDL_HINT_MOUSE_RELATIVE_CURSOR_VISIBLE "SDL_MOUSE_RELATIVE_CURSOR_VISIBLE" |
2642 | |
2643 | /** |
2644 | * A variable controlling whether mouse events should generate synthetic touch |
2645 | * events. |
2646 | * |
2647 | * The variable can be set to the following values: |
2648 | * |
2649 | * - "0": Mouse events will not generate touch events. (default for desktop |
2650 | * platforms) |
2651 | * - "1": Mouse events will generate touch events. (default for mobile |
2652 | * platforms, such as Android and iOS) |
2653 | * |
2654 | * This hint can be set anytime. |
2655 | * |
2656 | * \since This hint is available since SDL 3.2.0. |
2657 | */ |
2658 | #define SDL_HINT_MOUSE_TOUCH_EVENTS "SDL_MOUSE_TOUCH_EVENTS" |
2659 | |
2660 | /** |
2661 | * A variable controlling whether the keyboard should be muted on the console. |
2662 | * |
2663 | * Normally the keyboard is muted while SDL applications are running so that |
2664 | * keyboard input doesn't show up as key strokes on the console. This hint |
2665 | * allows you to turn that off for debugging purposes. |
2666 | * |
2667 | * The variable can be set to the following values: |
2668 | * |
2669 | * - "0": Allow keystrokes to go through to the console. |
2670 | * - "1": Mute keyboard input so it doesn't show up on the console. (default) |
2671 | * |
2672 | * This hint should be set before SDL is initialized. |
2673 | * |
2674 | * \since This hint is available since SDL 3.2.0. |
2675 | */ |
2676 | #define SDL_HINT_MUTE_CONSOLE_KEYBOARD "SDL_MUTE_CONSOLE_KEYBOARD" |
2677 | |
2678 | /** |
2679 | * Tell SDL not to catch the SIGINT or SIGTERM signals on POSIX platforms. |
2680 | * |
2681 | * The variable can be set to the following values: |
2682 | * |
2683 | * - "0": SDL will install a SIGINT and SIGTERM handler, and when it catches a |
2684 | * signal, convert it into an SDL_EVENT_QUIT event. (default) |
2685 | * - "1": SDL will not install a signal handler at all. |
2686 | * |
2687 | * This hint should be set before SDL is initialized. |
2688 | * |
2689 | * \since This hint is available since SDL 3.2.0. |
2690 | */ |
2691 | #define SDL_HINT_NO_SIGNAL_HANDLERS "SDL_NO_SIGNAL_HANDLERS" |
2692 | |
2693 | /** |
2694 | * Specify the OpenGL library to load. |
2695 | * |
2696 | * This hint should be set before creating an OpenGL window or creating an |
2697 | * OpenGL context. If this hint isn't set, SDL will choose a reasonable |
2698 | * default. |
2699 | * |
2700 | * \since This hint is available since SDL 3.2.0. |
2701 | */ |
2702 | #define SDL_HINT_OPENGL_LIBRARY "SDL_OPENGL_LIBRARY" |
2703 | |
2704 | /** |
2705 | * Specify the EGL library to load. |
2706 | * |
2707 | * This hint should be set before creating an OpenGL window or creating an |
2708 | * OpenGL context. This hint is only considered if SDL is using EGL to manage |
2709 | * OpenGL contexts. If this hint isn't set, SDL will choose a reasonable |
2710 | * default. |
2711 | * |
2712 | * \since This hint is available since SDL 3.2.0. |
2713 | */ |
2714 | #define SDL_HINT_EGL_LIBRARY "SDL_EGL_LIBRARY" |
2715 | |
2716 | /** |
2717 | * A variable controlling what driver to use for OpenGL ES contexts. |
2718 | * |
2719 | * On some platforms, currently Windows and X11, OpenGL drivers may support |
2720 | * creating contexts with an OpenGL ES profile. By default SDL uses these |
2721 | * profiles, when available, otherwise it attempts to load an OpenGL ES |
2722 | * library, e.g. that provided by the ANGLE project. This variable controls |
2723 | * whether SDL follows this default behaviour or will always load an OpenGL ES |
2724 | * library. |
2725 | * |
2726 | * Circumstances where this is useful include - Testing an app with a |
2727 | * particular OpenGL ES implementation, e.g ANGLE, or emulator, e.g. those |
2728 | * from ARM, Imagination or Qualcomm. - Resolving OpenGL ES function addresses |
2729 | * at link time by linking with the OpenGL ES library instead of querying them |
2730 | * at run time with SDL_GL_GetProcAddress(). |
2731 | * |
2732 | * Caution: for an application to work with the default behaviour across |
2733 | * different OpenGL drivers it must query the OpenGL ES function addresses at |
2734 | * run time using SDL_GL_GetProcAddress(). |
2735 | * |
2736 | * This variable is ignored on most platforms because OpenGL ES is native or |
2737 | * not supported. |
2738 | * |
2739 | * The variable can be set to the following values: |
2740 | * |
2741 | * - "0": Use ES profile of OpenGL, if available. (default) |
2742 | * - "1": Load OpenGL ES library using the default library names. |
2743 | * |
2744 | * This hint should be set before SDL is initialized. |
2745 | * |
2746 | * \since This hint is available since SDL 3.2.0. |
2747 | */ |
2748 | #define SDL_HINT_OPENGL_ES_DRIVER "SDL_OPENGL_ES_DRIVER" |
2749 | |
2750 | /** |
2751 | * Mechanism to specify openvr_api library location |
2752 | * |
2753 | * By default, when using the OpenVR driver, it will search for the API |
2754 | * library in the current folder. But, if you wish to use a system API you can |
2755 | * specify that by using this hint. This should be the full or relative path |
2756 | * to a .dll on Windows or .so on Linux. |
2757 | * |
2758 | * \since This hint is available since SDL 3.2.0. |
2759 | */ |
2760 | #define SDL_HINT_OPENVR_LIBRARY "SDL_OPENVR_LIBRARY" |
2761 | |
2762 | /** |
2763 | * A variable controlling which orientations are allowed on iOS/Android. |
2764 | * |
2765 | * In some circumstances it is necessary to be able to explicitly control |
2766 | * which UI orientations are allowed. |
2767 | * |
2768 | * This variable is a space delimited list of the following values: |
2769 | * |
2770 | * - "LandscapeLeft" |
2771 | * - "LandscapeRight" |
2772 | * - "Portrait" |
2773 | * - "PortraitUpsideDown" |
2774 | * |
2775 | * This hint should be set before SDL is initialized. |
2776 | * |
2777 | * \since This hint is available since SDL 3.2.0. |
2778 | */ |
2779 | #define SDL_HINT_ORIENTATIONS "SDL_ORIENTATIONS" |
2780 | |
2781 | /** |
2782 | * A variable controlling the use of a sentinel event when polling the event |
2783 | * queue. |
2784 | * |
2785 | * When polling for events, SDL_PumpEvents is used to gather new events from |
2786 | * devices. If a device keeps producing new events between calls to |
2787 | * SDL_PumpEvents, a poll loop will become stuck until the new events stop. |
2788 | * This is most noticeable when moving a high frequency mouse. |
2789 | * |
2790 | * The variable can be set to the following values: |
2791 | * |
2792 | * - "0": Disable poll sentinels. |
2793 | * - "1": Enable poll sentinels. (default) |
2794 | * |
2795 | * This hint can be set anytime. |
2796 | * |
2797 | * \since This hint is available since SDL 3.2.0. |
2798 | */ |
2799 | #define SDL_HINT_POLL_SENTINEL "SDL_POLL_SENTINEL" |
2800 | |
2801 | /** |
2802 | * Override for SDL_GetPreferredLocales(). |
2803 | * |
2804 | * If set, this will be favored over anything the OS might report for the |
2805 | * user's preferred locales. Changing this hint at runtime will not generate a |
2806 | * SDL_EVENT_LOCALE_CHANGED event (but if you can change the hint, you can |
2807 | * push your own event, if you want). |
2808 | * |
2809 | * The format of this hint is a comma-separated list of language and locale, |
2810 | * combined with an underscore, as is a common format: "en_GB". Locale is |
2811 | * optional: "en". So you might have a list like this: "en_GB,jp,es_PT" |
2812 | * |
2813 | * This hint can be set anytime. |
2814 | * |
2815 | * \since This hint is available since SDL 3.2.0. |
2816 | */ |
2817 | #define SDL_HINT_PREFERRED_LOCALES "SDL_PREFERRED_LOCALES" |
2818 | |
2819 | /** |
2820 | * A variable that decides whether to send SDL_EVENT_QUIT when closing the |
2821 | * last window. |
2822 | * |
2823 | * The variable can be set to the following values: |
2824 | * |
2825 | * - "0": SDL will not send an SDL_EVENT_QUIT event when the last window is |
2826 | * requesting to close. Note that in this case, there are still other |
2827 | * legitimate reasons one might get an SDL_EVENT_QUIT event: choosing "Quit" |
2828 | * from the macOS menu bar, sending a SIGINT (ctrl-c) on Unix, etc. |
2829 | * - "1": SDL will send a quit event when the last window is requesting to |
2830 | * close. (default) |
2831 | * |
2832 | * If there is at least one active system tray icon, SDL_EVENT_QUIT will |
2833 | * instead be sent when both the last window will be closed and the last tray |
2834 | * icon will be destroyed. |
2835 | * |
2836 | * This hint can be set anytime. |
2837 | * |
2838 | * \since This hint is available since SDL 3.2.0. |
2839 | */ |
2840 | #define SDL_HINT_QUIT_ON_LAST_WINDOW_CLOSE "SDL_QUIT_ON_LAST_WINDOW_CLOSE" |
2841 | |
2842 | /** |
2843 | * A variable controlling whether the Direct3D device is initialized for |
2844 | * thread-safe operations. |
2845 | * |
2846 | * The variable can be set to the following values: |
2847 | * |
2848 | * - "0": Thread-safety is not enabled. (default) |
2849 | * - "1": Thread-safety is enabled. |
2850 | * |
2851 | * This hint should be set before creating a renderer. |
2852 | * |
2853 | * \since This hint is available since SDL 3.2.0. |
2854 | */ |
2855 | #define SDL_HINT_RENDER_DIRECT3D_THREADSAFE "SDL_RENDER_DIRECT3D_THREADSAFE" |
2856 | |
2857 | /** |
2858 | * A variable controlling whether to enable Direct3D 11+'s Debug Layer. |
2859 | * |
2860 | * This variable does not have any effect on the Direct3D 9 based renderer. |
2861 | * |
2862 | * The variable can be set to the following values: |
2863 | * |
2864 | * - "0": Disable Debug Layer use. (default) |
2865 | * - "1": Enable Debug Layer use. |
2866 | * |
2867 | * This hint should be set before creating a renderer. |
2868 | * |
2869 | * \since This hint is available since SDL 3.2.0. |
2870 | */ |
2871 | #define SDL_HINT_RENDER_DIRECT3D11_DEBUG "SDL_RENDER_DIRECT3D11_DEBUG" |
2872 | |
2873 | /** |
2874 | * A variable controlling whether to enable Vulkan Validation Layers. |
2875 | * |
2876 | * This variable can be set to the following values: |
2877 | * |
2878 | * - "0": Disable Validation Layer use |
2879 | * - "1": Enable Validation Layer use |
2880 | * |
2881 | * By default, SDL does not use Vulkan Validation Layers. |
2882 | * |
2883 | * \since This hint is available since SDL 3.2.0. |
2884 | */ |
2885 | #define SDL_HINT_RENDER_VULKAN_DEBUG "SDL_RENDER_VULKAN_DEBUG" |
2886 | |
2887 | /** |
2888 | * A variable controlling whether to create the GPU device in debug mode. |
2889 | * |
2890 | * This variable can be set to the following values: |
2891 | * |
2892 | * - "0": Disable debug mode use (default) |
2893 | * - "1": Enable debug mode use |
2894 | * |
2895 | * This hint should be set before creating a renderer. |
2896 | * |
2897 | * \since This hint is available since SDL 3.2.0. |
2898 | */ |
2899 | #define SDL_HINT_RENDER_GPU_DEBUG "SDL_RENDER_GPU_DEBUG" |
2900 | |
2901 | /** |
2902 | * A variable controlling whether to prefer a low-power GPU on multi-GPU |
2903 | * systems. |
2904 | * |
2905 | * This variable can be set to the following values: |
2906 | * |
2907 | * - "0": Prefer high-performance GPU (default) |
2908 | * - "1": Prefer low-power GPU |
2909 | * |
2910 | * This hint should be set before creating a renderer. |
2911 | * |
2912 | * \since This hint is available since SDL 3.2.0. |
2913 | */ |
2914 | #define SDL_HINT_RENDER_GPU_LOW_POWER "SDL_RENDER_GPU_LOW_POWER" |
2915 | |
2916 | /** |
2917 | * A variable specifying which render driver to use. |
2918 | * |
2919 | * If the application doesn't pick a specific renderer to use, this variable |
2920 | * specifies the name of the preferred renderer. If the preferred renderer |
2921 | * can't be initialized, creating a renderer will fail. |
2922 | * |
2923 | * This variable is case insensitive and can be set to the following values: |
2924 | * |
2925 | * - "direct3d" |
2926 | * - "direct3d11" |
2927 | * - "direct3d12" |
2928 | * - "opengl" |
2929 | * - "opengles2" |
2930 | * - "opengles" |
2931 | * - "metal" |
2932 | * - "vulkan" |
2933 | * - "gpu" |
2934 | * - "software" |
2935 | * |
2936 | * This hint accepts a comma-separated list of driver names, and each will be |
2937 | * tried in the order listed when creating a renderer until one succeeds or |
2938 | * all of them fail. |
2939 | * |
2940 | * The default varies by platform, but it's the first one in the list that is |
2941 | * available on the current platform. |
2942 | * |
2943 | * This hint should be set before creating a renderer. |
2944 | * |
2945 | * \since This hint is available since SDL 3.2.0. |
2946 | */ |
2947 | #define SDL_HINT_RENDER_DRIVER "SDL_RENDER_DRIVER" |
2948 | |
2949 | /** |
2950 | * A variable controlling how the 2D render API renders lines. |
2951 | * |
2952 | * The variable can be set to the following values: |
2953 | * |
2954 | * - "0": Use the default line drawing method (Bresenham's line algorithm) |
2955 | * - "1": Use the driver point API using Bresenham's line algorithm (correct, |
2956 | * draws many points) |
2957 | * - "2": Use the driver line API (occasionally misses line endpoints based on |
2958 | * hardware driver quirks |
2959 | * - "3": Use the driver geometry API (correct, draws thicker diagonal lines) |
2960 | * |
2961 | * This hint should be set before creating a renderer. |
2962 | * |
2963 | * \since This hint is available since SDL 3.2.0. |
2964 | */ |
2965 | #define SDL_HINT_RENDER_LINE_METHOD "SDL_RENDER_LINE_METHOD" |
2966 | |
2967 | /** |
2968 | * A variable controlling whether the Metal render driver select low power |
2969 | * device over default one. |
2970 | * |
2971 | * The variable can be set to the following values: |
2972 | * |
2973 | * - "0": Use the preferred OS device. (default) |
2974 | * - "1": Select a low power device. |
2975 | * |
2976 | * This hint should be set before creating a renderer. |
2977 | * |
2978 | * \since This hint is available since SDL 3.2.0. |
2979 | */ |
2980 | #define SDL_HINT_RENDER_METAL_PREFER_LOW_POWER_DEVICE "SDL_RENDER_METAL_PREFER_LOW_POWER_DEVICE" |
2981 | |
2982 | /** |
2983 | * A variable controlling whether updates to the SDL screen surface should be |
2984 | * synchronized with the vertical refresh, to avoid tearing. |
2985 | * |
2986 | * This hint overrides the application preference when creating a renderer. |
2987 | * |
2988 | * The variable can be set to the following values: |
2989 | * |
2990 | * - "0": Disable vsync. (default) |
2991 | * - "1": Enable vsync. |
2992 | * |
2993 | * This hint should be set before creating a renderer. |
2994 | * |
2995 | * \since This hint is available since SDL 3.2.0. |
2996 | */ |
2997 | #define SDL_HINT_RENDER_VSYNC "SDL_RENDER_VSYNC" |
2998 | |
2999 | /** |
3000 | * A variable to control whether the return key on the soft keyboard should |
3001 | * hide the soft keyboard on Android and iOS. |
3002 | * |
3003 | * This hint sets the default value of SDL_PROP_TEXTINPUT_MULTILINE_BOOLEAN. |
3004 | * |
3005 | * The variable can be set to the following values: |
3006 | * |
3007 | * - "0": The return key will be handled as a key event. (default) |
3008 | * - "1": The return key will hide the keyboard. |
3009 | * |
3010 | * This hint can be set anytime. |
3011 | * |
3012 | * \since This hint is available since SDL 3.2.0. |
3013 | */ |
3014 | #define SDL_HINT_RETURN_KEY_HIDES_IME "SDL_RETURN_KEY_HIDES_IME" |
3015 | |
3016 | /** |
3017 | * A variable containing a list of ROG gamepad capable mice. |
3018 | * |
3019 | * The format of the string is a comma separated list of USB VID/PID pairs in |
3020 | * hexadecimal form, e.g. |
3021 | * |
3022 | * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` |
3023 | * |
3024 | * The variable can also take the form of "@file", in which case the named |
3025 | * file will be loaded and interpreted as the value of the variable. |
3026 | * |
3027 | * This hint should be set before SDL is initialized. |
3028 | * |
3029 | * \since This hint is available since SDL 3.2.0. |
3030 | * |
3031 | * \sa SDL_HINT_ROG_GAMEPAD_MICE_EXCLUDED |
3032 | */ |
3033 | #define SDL_HINT_ROG_GAMEPAD_MICE "SDL_ROG_GAMEPAD_MICE" |
3034 | |
3035 | /** |
3036 | * A variable containing a list of devices that are not ROG gamepad capable |
3037 | * mice. |
3038 | * |
3039 | * This will override SDL_HINT_ROG_GAMEPAD_MICE and the built in device list. |
3040 | * |
3041 | * The format of the string is a comma separated list of USB VID/PID pairs in |
3042 | * hexadecimal form, e.g. |
3043 | * |
3044 | * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` |
3045 | * |
3046 | * The variable can also take the form of "@file", in which case the named |
3047 | * file will be loaded and interpreted as the value of the variable. |
3048 | * |
3049 | * This hint should be set before SDL is initialized. |
3050 | * |
3051 | * \since This hint is available since SDL 3.2.0. |
3052 | */ |
3053 | #define SDL_HINT_ROG_GAMEPAD_MICE_EXCLUDED "SDL_ROG_GAMEPAD_MICE_EXCLUDED" |
3054 | |
3055 | /** |
3056 | * A variable controlling which Dispmanx layer to use on a Raspberry PI. |
3057 | * |
3058 | * Also known as Z-order. The variable can take a negative or positive value. |
3059 | * The default is 10000. |
3060 | * |
3061 | * This hint should be set before SDL is initialized. |
3062 | * |
3063 | * \since This hint is available since SDL 3.2.0. |
3064 | */ |
3065 | #define SDL_HINT_RPI_VIDEO_LAYER "SDL_RPI_VIDEO_LAYER" |
3066 | |
3067 | /** |
3068 | * Specify an "activity name" for screensaver inhibition. |
3069 | * |
3070 | * Some platforms, notably Linux desktops, list the applications which are |
3071 | * inhibiting the screensaver or other power-saving features. |
3072 | * |
3073 | * This hint lets you specify the "activity name" sent to the OS when |
3074 | * SDL_DisableScreenSaver() is used (or the screensaver is automatically |
3075 | * disabled). The contents of this hint are used when the screensaver is |
3076 | * disabled. You should use a string that describes what your program is doing |
3077 | * (and, therefore, why the screensaver is disabled). For example, "Playing a |
3078 | * game" or "Watching a video". |
3079 | * |
3080 | * Setting this to "" or leaving it unset will have SDL use a reasonable |
3081 | * default: "Playing a game" or something similar. |
3082 | * |
3083 | * This hint should be set before calling SDL_DisableScreenSaver() |
3084 | * |
3085 | * \since This hint is available since SDL 3.2.0. |
3086 | */ |
3087 | #define SDL_HINT_SCREENSAVER_INHIBIT_ACTIVITY_NAME "SDL_SCREENSAVER_INHIBIT_ACTIVITY_NAME" |
3088 | |
3089 | /** |
3090 | * A variable controlling whether SDL calls dbus_shutdown() on quit. |
3091 | * |
3092 | * This is useful as a debug tool to validate memory leaks, but shouldn't ever |
3093 | * be set in production applications, as other libraries used by the |
3094 | * application might use dbus under the hood and this can cause crashes if |
3095 | * they continue after SDL_Quit(). |
3096 | * |
3097 | * The variable can be set to the following values: |
3098 | * |
3099 | * - "0": SDL will not call dbus_shutdown() on quit. (default) |
3100 | * - "1": SDL will call dbus_shutdown() on quit. |
3101 | * |
3102 | * This hint can be set anytime. |
3103 | * |
3104 | * \since This hint is available since SDL 3.2.0. |
3105 | */ |
3106 | #define SDL_HINT_SHUTDOWN_DBUS_ON_QUIT "SDL_SHUTDOWN_DBUS_ON_QUIT" |
3107 | |
3108 | /** |
3109 | * A variable that specifies a backend to use for title storage. |
3110 | * |
3111 | * By default, SDL will try all available storage backends in a reasonable |
3112 | * order until it finds one that can work, but this hint allows the app or |
3113 | * user to force a specific target, such as "pc" if, say, you are on Steam but |
3114 | * want to avoid SteamRemoteStorage for title data. |
3115 | * |
3116 | * This hint should be set before SDL is initialized. |
3117 | * |
3118 | * \since This hint is available since SDL 3.2.0. |
3119 | */ |
3120 | #define SDL_HINT_STORAGE_TITLE_DRIVER "SDL_STORAGE_TITLE_DRIVER" |
3121 | |
3122 | /** |
3123 | * A variable that specifies a backend to use for user storage. |
3124 | * |
3125 | * By default, SDL will try all available storage backends in a reasonable |
3126 | * order until it finds one that can work, but this hint allows the app or |
3127 | * user to force a specific target, such as "pc" if, say, you are on Steam but |
3128 | * want to avoid SteamRemoteStorage for user data. |
3129 | * |
3130 | * This hint should be set before SDL is initialized. |
3131 | * |
3132 | * \since This hint is available since SDL 3.2.0. |
3133 | */ |
3134 | #define SDL_HINT_STORAGE_USER_DRIVER "SDL_STORAGE_USER_DRIVER" |
3135 | |
3136 | /** |
3137 | * Specifies whether SDL_THREAD_PRIORITY_TIME_CRITICAL should be treated as |
3138 | * realtime. |
3139 | * |
3140 | * On some platforms, like Linux, a realtime priority thread may be subject to |
3141 | * restrictions that require special handling by the application. This hint |
3142 | * exists to let SDL know that the app is prepared to handle said |
3143 | * restrictions. |
3144 | * |
3145 | * On Linux, SDL will apply the following configuration to any thread that |
3146 | * becomes realtime: |
3147 | * |
3148 | * - The SCHED_RESET_ON_FORK bit will be set on the scheduling policy, |
3149 | * - An RLIMIT_RTTIME budget will be configured to the rtkit specified limit. |
3150 | * - Exceeding this limit will result in the kernel sending SIGKILL to the |
3151 | * app, refer to the man pages for more information. |
3152 | * |
3153 | * The variable can be set to the following values: |
3154 | * |
3155 | * - "0": default platform specific behaviour |
3156 | * - "1": Force SDL_THREAD_PRIORITY_TIME_CRITICAL to a realtime scheduling |
3157 | * policy |
3158 | * |
3159 | * This hint should be set before calling SDL_SetCurrentThreadPriority() |
3160 | * |
3161 | * \since This hint is available since SDL 3.2.0. |
3162 | */ |
3163 | #define SDL_HINT_THREAD_FORCE_REALTIME_TIME_CRITICAL "SDL_THREAD_FORCE_REALTIME_TIME_CRITICAL" |
3164 | |
3165 | /** |
3166 | * A string specifying additional information to use with |
3167 | * SDL_SetCurrentThreadPriority. |
3168 | * |
3169 | * By default SDL_SetCurrentThreadPriority will make appropriate system |
3170 | * changes in order to apply a thread priority. For example on systems using |
3171 | * pthreads the scheduler policy is changed automatically to a policy that |
3172 | * works well with a given priority. Code which has specific requirements can |
3173 | * override SDL's default behavior with this hint. |
3174 | * |
3175 | * pthread hint values are "current", "other", "fifo" and "rr". Currently no |
3176 | * other platform hint values are defined but may be in the future. |
3177 | * |
3178 | * On Linux, the kernel may send SIGKILL to realtime tasks which exceed the |
3179 | * distro configured execution budget for rtkit. This budget can be queried |
3180 | * through RLIMIT_RTTIME after calling SDL_SetCurrentThreadPriority(). |
3181 | * |
3182 | * This hint should be set before calling SDL_SetCurrentThreadPriority() |
3183 | * |
3184 | * \since This hint is available since SDL 3.2.0. |
3185 | */ |
3186 | #define SDL_HINT_THREAD_PRIORITY_POLICY "SDL_THREAD_PRIORITY_POLICY" |
3187 | |
3188 | /** |
3189 | * A variable that controls the timer resolution, in milliseconds. |
3190 | * |
3191 | * The higher resolution the timer, the more frequently the CPU services timer |
3192 | * interrupts, and the more precise delays are, but this takes up power and |
3193 | * CPU time. This hint is only used on Windows. |
3194 | * |
3195 | * See this blog post for more information: |
3196 | * http://randomascii.wordpress.com/2013/07/08/windows-timer-resolution-megawatts-wasted/ |
3197 | * |
3198 | * The default value is "1". |
3199 | * |
3200 | * If this variable is set to "0", the system timer resolution is not set. |
3201 | * |
3202 | * This hint can be set anytime. |
3203 | * |
3204 | * \since This hint is available since SDL 3.2.0. |
3205 | */ |
3206 | #define SDL_HINT_TIMER_RESOLUTION "SDL_TIMER_RESOLUTION" |
3207 | |
3208 | /** |
3209 | * A variable controlling whether touch events should generate synthetic mouse |
3210 | * events. |
3211 | * |
3212 | * The variable can be set to the following values: |
3213 | * |
3214 | * - "0": Touch events will not generate mouse events. |
3215 | * - "1": Touch events will generate mouse events. (default) |
3216 | * |
3217 | * This hint can be set anytime. |
3218 | * |
3219 | * \since This hint is available since SDL 3.2.0. |
3220 | */ |
3221 | #define SDL_HINT_TOUCH_MOUSE_EVENTS "SDL_TOUCH_MOUSE_EVENTS" |
3222 | |
3223 | /** |
3224 | * A variable controlling whether trackpads should be treated as touch |
3225 | * devices. |
3226 | * |
3227 | * On macOS (and possibly other platforms in the future), SDL will report |
3228 | * touches on a trackpad as mouse input, which is generally what users expect |
3229 | * from this device; however, these are often actually full multitouch-capable |
3230 | * touch devices, so it might be preferable to some apps to treat them as |
3231 | * such. |
3232 | * |
3233 | * The variable can be set to the following values: |
3234 | * |
3235 | * - "0": Trackpad will send mouse events. (default) |
3236 | * - "1": Trackpad will send touch events. |
3237 | * |
3238 | * This hint should be set before SDL is initialized. |
3239 | * |
3240 | * \since This hint is available since SDL 3.2.0. |
3241 | */ |
3242 | #define SDL_HINT_TRACKPAD_IS_TOUCH_ONLY "SDL_TRACKPAD_IS_TOUCH_ONLY" |
3243 | |
3244 | /** |
3245 | * A variable controlling whether the Android / tvOS remotes should be listed |
3246 | * as joystick devices, instead of sending keyboard events. |
3247 | * |
3248 | * The variable can be set to the following values: |
3249 | * |
3250 | * - "0": Remotes send enter/escape/arrow key events. |
3251 | * - "1": Remotes are available as 2 axis, 2 button joysticks. (default) |
3252 | * |
3253 | * This hint should be set before SDL is initialized. |
3254 | * |
3255 | * \since This hint is available since SDL 3.2.0. |
3256 | */ |
3257 | #define SDL_HINT_TV_REMOTE_AS_JOYSTICK "SDL_TV_REMOTE_AS_JOYSTICK" |
3258 | |
3259 | /** |
3260 | * A variable controlling whether the screensaver is enabled. |
3261 | * |
3262 | * The variable can be set to the following values: |
3263 | * |
3264 | * - "0": Disable screensaver. (default) |
3265 | * - "1": Enable screensaver. |
3266 | * |
3267 | * This hint should be set before SDL is initialized. |
3268 | * |
3269 | * \since This hint is available since SDL 3.2.0. |
3270 | */ |
3271 | #define SDL_HINT_VIDEO_ALLOW_SCREENSAVER "SDL_VIDEO_ALLOW_SCREENSAVER" |
3272 | |
3273 | /** |
3274 | * A comma separated list containing the names of the displays that SDL should |
3275 | * sort to the front of the display list. |
3276 | * |
3277 | * When this hint is set, displays with matching name strings will be |
3278 | * prioritized in the list of displays, as exposed by calling |
3279 | * SDL_GetDisplays(), with the first listed becoming the primary display. The |
3280 | * naming convention can vary depending on the environment, but it is usually |
3281 | * a connector name (e.g. 'DP-1', 'DP-2', 'HDMI-A-1',etc...). |
3282 | * |
3283 | * On Wayland and X11 desktops, the connector names associated with displays |
3284 | * can typically be found by using the `xrandr` utility. |
3285 | * |
3286 | * This hint is currently supported on the following drivers: |
3287 | * |
3288 | * - KMSDRM (kmsdrm) |
3289 | * - Wayland (wayland) |
3290 | * - X11 (x11) |
3291 | * |
3292 | * This hint should be set before SDL is initialized. |
3293 | * |
3294 | * \since This hint is available since SDL 3.2.0. |
3295 | */ |
3296 | #define SDL_HINT_VIDEO_DISPLAY_PRIORITY "SDL_VIDEO_DISPLAY_PRIORITY" |
3297 | |
3298 | /** |
3299 | * Tell the video driver that we only want a double buffer. |
3300 | * |
3301 | * By default, most lowlevel 2D APIs will use a triple buffer scheme that |
3302 | * wastes no CPU time on waiting for vsync after issuing a flip, but |
3303 | * introduces a frame of latency. On the other hand, using a double buffer |
3304 | * scheme instead is recommended for cases where low latency is an important |
3305 | * factor because we save a whole frame of latency. |
3306 | * |
3307 | * We do so by waiting for vsync immediately after issuing a flip, usually |
3308 | * just after eglSwapBuffers call in the backend's *_SwapWindow function. |
3309 | * |
3310 | * This hint is currently supported on the following drivers: |
3311 | * |
3312 | * - Raspberry Pi (raspberrypi) |
3313 | * - Wayland (wayland) |
3314 | * |
3315 | * This hint should be set before SDL is initialized. |
3316 | * |
3317 | * \since This hint is available since SDL 3.2.0. |
3318 | */ |
3319 | #define SDL_HINT_VIDEO_DOUBLE_BUFFER "SDL_VIDEO_DOUBLE_BUFFER" |
3320 | |
3321 | /** |
3322 | * A variable that specifies a video backend to use. |
3323 | * |
3324 | * By default, SDL will try all available video backends in a reasonable order |
3325 | * until it finds one that can work, but this hint allows the app or user to |
3326 | * force a specific target, such as "x11" if, say, you are on Wayland but want |
3327 | * to try talking to the X server instead. |
3328 | * |
3329 | * This hint accepts a comma-separated list of driver names, and each will be |
3330 | * tried in the order listed during init, until one succeeds or all of them |
3331 | * fail. |
3332 | * |
3333 | * This hint should be set before SDL is initialized. |
3334 | * |
3335 | * \since This hint is available since SDL 3.2.0. |
3336 | */ |
3337 | #define SDL_HINT_VIDEO_DRIVER "SDL_VIDEO_DRIVER" |
3338 | |
3339 | /** |
3340 | * A variable controlling whether the dummy video driver saves output frames. |
3341 | * |
3342 | * - "0": Video frames are not saved to disk. (default) |
3343 | * - "1": Video frames are saved to files in the format "SDL_windowX-Y.bmp", |
3344 | * where X is the window ID, and Y is the frame number. |
3345 | * |
3346 | * This hint can be set anytime. |
3347 | * |
3348 | * \since This hint is available since SDL 3.2.0. |
3349 | */ |
3350 | #define SDL_HINT_VIDEO_DUMMY_SAVE_FRAMES "SDL_VIDEO_DUMMY_SAVE_FRAMES" |
3351 | |
3352 | /** |
3353 | * If eglGetPlatformDisplay fails, fall back to calling eglGetDisplay. |
3354 | * |
3355 | * The variable can be set to one of the following values: |
3356 | * |
3357 | * - "0": Do not fall back to eglGetDisplay. |
3358 | * - "1": Fall back to eglGetDisplay if eglGetPlatformDisplay fails. (default) |
3359 | * |
3360 | * This hint should be set before SDL is initialized. |
3361 | * |
3362 | * \since This hint is available since SDL 3.2.0. |
3363 | */ |
3364 | #define SDL_HINT_VIDEO_EGL_ALLOW_GETDISPLAY_FALLBACK "SDL_VIDEO_EGL_ALLOW_GETDISPLAY_FALLBACK" |
3365 | |
3366 | /** |
3367 | * A variable controlling whether the OpenGL context should be created with |
3368 | * EGL. |
3369 | * |
3370 | * The variable can be set to the following values: |
3371 | * |
3372 | * - "0": Use platform-specific GL context creation API (GLX, WGL, CGL, etc). |
3373 | * (default) |
3374 | * - "1": Use EGL |
3375 | * |
3376 | * This hint should be set before SDL is initialized. |
3377 | * |
3378 | * \since This hint is available since SDL 3.2.0. |
3379 | */ |
3380 | #define SDL_HINT_VIDEO_FORCE_EGL "SDL_VIDEO_FORCE_EGL" |
3381 | |
3382 | /** |
3383 | * A variable that specifies the policy for fullscreen Spaces on macOS. |
3384 | * |
3385 | * The variable can be set to the following values: |
3386 | * |
3387 | * - "0": Disable Spaces support (FULLSCREEN_DESKTOP won't use them and |
3388 | * SDL_WINDOW_RESIZABLE windows won't offer the "fullscreen" button on their |
3389 | * titlebars). |
3390 | * - "1": Enable Spaces support (FULLSCREEN_DESKTOP will use them and |
3391 | * SDL_WINDOW_RESIZABLE windows will offer the "fullscreen" button on their |
3392 | * titlebars). (default) |
3393 | * |
3394 | * This hint should be set before creating a window. |
3395 | * |
3396 | * \since This hint is available since SDL 3.2.0. |
3397 | */ |
3398 | #define SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES "SDL_VIDEO_MAC_FULLSCREEN_SPACES" |
3399 | |
3400 | /** |
3401 | * A variable that specifies the menu visibility when a window is fullscreen |
3402 | * in Spaces on macOS. |
3403 | * |
3404 | * The variable can be set to the following values: |
3405 | * |
3406 | * - "0": The menu will be hidden when the window is in a fullscreen space, |
3407 | * and not accessible by moving the mouse to the top of the screen. |
3408 | * - "1": The menu will be accessible when the window is in a fullscreen |
3409 | * space. |
3410 | * - "auto": The menu will be hidden if fullscreen mode was toggled on |
3411 | * programmatically via `SDL_SetWindowFullscreen()`, and accessible if |
3412 | * fullscreen was entered via the "fullscreen" button on the window title |
3413 | * bar. (default) |
3414 | * |
3415 | * This hint can be set anytime. |
3416 | * |
3417 | * \since This hint is available since SDL 3.2.0. |
3418 | */ |
3419 | #define "SDL_VIDEO_MAC_FULLSCREEN_MENU_VISIBILITY" |
3420 | |
3421 | /** |
3422 | * A variable controlling whether SDL will attempt to automatically set the |
3423 | * destination display to a mode most closely matching that of the previous |
3424 | * display if an exclusive fullscreen window is moved onto it. |
3425 | * |
3426 | * The variable can be set to the following values: |
3427 | * |
3428 | * - "0": SDL will not attempt to automatically set a matching mode on the |
3429 | * destination display. If an exclusive fullscreen window is moved to a new |
3430 | * display, the window will become fullscreen desktop. |
3431 | * - "1": SDL will attempt to automatically set a mode on the destination |
3432 | * display that most closely matches the mode of the display that the |
3433 | * exclusive fullscreen window was previously on. (default) |
3434 | * |
3435 | * This hint can be set anytime. |
3436 | * |
3437 | * \since This hint is available since SDL 3.4.0. |
3438 | */ |
3439 | #define SDL_HINT_VIDEO_MATCH_EXCLUSIVE_MODE_ON_MOVE "SDL_VIDEO_MATCH_EXCLUSIVE_MODE_ON_MOVE" |
3440 | |
3441 | /** |
3442 | * A variable controlling whether fullscreen windows are minimized when they |
3443 | * lose focus. |
3444 | * |
3445 | * The variable can be set to the following values: |
3446 | * |
3447 | * - "0": Fullscreen windows will not be minimized when they lose focus. |
3448 | * (default) |
3449 | * - "1": Fullscreen windows are minimized when they lose focus. |
3450 | * |
3451 | * This hint can be set anytime. |
3452 | * |
3453 | * \since This hint is available since SDL 3.2.0. |
3454 | */ |
3455 | #define SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS "SDL_VIDEO_MINIMIZE_ON_FOCUS_LOSS" |
3456 | |
3457 | /** |
3458 | * A variable controlling whether the offscreen video driver saves output |
3459 | * frames. |
3460 | * |
3461 | * This only saves frames that are generated using software rendering, not |
3462 | * accelerated OpenGL rendering. |
3463 | * |
3464 | * - "0": Video frames are not saved to disk. (default) |
3465 | * - "1": Video frames are saved to files in the format "SDL_windowX-Y.bmp", |
3466 | * where X is the window ID, and Y is the frame number. |
3467 | * |
3468 | * This hint can be set anytime. |
3469 | * |
3470 | * \since This hint is available since SDL 3.2.0. |
3471 | */ |
3472 | #define SDL_HINT_VIDEO_OFFSCREEN_SAVE_FRAMES "SDL_VIDEO_OFFSCREEN_SAVE_FRAMES" |
3473 | |
3474 | /** |
3475 | * A variable controlling whether all window operations will block until |
3476 | * complete. |
3477 | * |
3478 | * Window systems that run asynchronously may not have the results of window |
3479 | * operations that resize or move the window applied immediately upon the |
3480 | * return of the requesting function. Setting this hint will cause such |
3481 | * operations to block after every call until the pending operation has |
3482 | * completed. Setting this to '1' is the equivalent of calling |
3483 | * SDL_SyncWindow() after every function call. |
3484 | * |
3485 | * Be aware that amount of time spent blocking while waiting for window |
3486 | * operations to complete can be quite lengthy, as animations may have to |
3487 | * complete, which can take upwards of multiple seconds in some cases. |
3488 | * |
3489 | * The variable can be set to the following values: |
3490 | * |
3491 | * - "0": Window operations are non-blocking. (default) |
3492 | * - "1": Window operations will block until completed. |
3493 | * |
3494 | * This hint can be set anytime. |
3495 | * |
3496 | * \since This hint is available since SDL 3.2.0. |
3497 | */ |
3498 | #define SDL_HINT_VIDEO_SYNC_WINDOW_OPERATIONS "SDL_VIDEO_SYNC_WINDOW_OPERATIONS" |
3499 | |
3500 | /** |
3501 | * A variable controlling whether the libdecor Wayland backend is allowed to |
3502 | * be used. |
3503 | * |
3504 | * libdecor is used over xdg-shell when xdg-decoration protocol is |
3505 | * unavailable. |
3506 | * |
3507 | * The variable can be set to the following values: |
3508 | * |
3509 | * - "0": libdecor use is disabled. |
3510 | * - "1": libdecor use is enabled. (default) |
3511 | * |
3512 | * This hint should be set before SDL is initialized. |
3513 | * |
3514 | * \since This hint is available since SDL 3.2.0. |
3515 | */ |
3516 | #define SDL_HINT_VIDEO_WAYLAND_ALLOW_LIBDECOR "SDL_VIDEO_WAYLAND_ALLOW_LIBDECOR" |
3517 | |
3518 | /** |
3519 | * A variable controlling whether video mode emulation is enabled under |
3520 | * Wayland. |
3521 | * |
3522 | * When this hint is set, a standard set of emulated CVT video modes will be |
3523 | * exposed for use by the application. If it is disabled, the only modes |
3524 | * exposed will be the logical desktop size and, in the case of a scaled |
3525 | * desktop, the native display resolution. |
3526 | * |
3527 | * The variable can be set to the following values: |
3528 | * |
3529 | * - "0": Video mode emulation is disabled. |
3530 | * - "1": Video mode emulation is enabled. (default) |
3531 | * |
3532 | * This hint should be set before SDL is initialized. |
3533 | * |
3534 | * \since This hint is available since SDL 3.2.0. |
3535 | */ |
3536 | #define SDL_HINT_VIDEO_WAYLAND_MODE_EMULATION "SDL_VIDEO_WAYLAND_MODE_EMULATION" |
3537 | |
3538 | /** |
3539 | * A variable controlling how modes with a non-native aspect ratio are |
3540 | * displayed under Wayland. |
3541 | * |
3542 | * When this hint is set, the requested scaling will be used when displaying |
3543 | * fullscreen video modes that don't match the display's native aspect ratio. |
3544 | * This is contingent on compositor viewport support. |
3545 | * |
3546 | * The variable can be set to the following values: |
3547 | * |
3548 | * - "aspect" - Video modes will be displayed scaled, in their proper aspect |
3549 | * ratio, with black bars. |
3550 | * - "stretch" - Video modes will be scaled to fill the entire display. |
3551 | * (default) |
3552 | * - "none" - Video modes will be displayed as 1:1 with no scaling. |
3553 | * |
3554 | * This hint should be set before creating a window. |
3555 | * |
3556 | * \since This hint is available since SDL 3.2.0. |
3557 | */ |
3558 | #define SDL_HINT_VIDEO_WAYLAND_MODE_SCALING "SDL_VIDEO_WAYLAND_MODE_SCALING" |
3559 | |
3560 | /** |
3561 | * A variable controlling whether the libdecor Wayland backend is preferred |
3562 | * over native decorations. |
3563 | * |
3564 | * When this hint is set, libdecor will be used to provide window decorations, |
3565 | * even if xdg-decoration is available. (Note that, by default, libdecor will |
3566 | * use xdg-decoration itself if available). |
3567 | * |
3568 | * The variable can be set to the following values: |
3569 | * |
3570 | * - "0": libdecor is enabled only if server-side decorations are unavailable. |
3571 | * (default) |
3572 | * - "1": libdecor is always enabled if available. |
3573 | * |
3574 | * This hint should be set before SDL is initialized. |
3575 | * |
3576 | * \since This hint is available since SDL 3.2.0. |
3577 | */ |
3578 | #define SDL_HINT_VIDEO_WAYLAND_PREFER_LIBDECOR "SDL_VIDEO_WAYLAND_PREFER_LIBDECOR" |
3579 | |
3580 | /** |
3581 | * A variable forcing non-DPI-aware Wayland windows to output at 1:1 scaling. |
3582 | * |
3583 | * This must be set before initializing the video subsystem. |
3584 | * |
3585 | * When this hint is set, Wayland windows that are not flagged as being |
3586 | * DPI-aware will be output with scaling designed to force 1:1 pixel mapping. |
3587 | * |
3588 | * This is intended to allow legacy applications to be displayed without |
3589 | * desktop scaling being applied, and has issues with certain display |
3590 | * configurations, as this forces the window to behave in a way that Wayland |
3591 | * desktops were not designed to accommodate: |
3592 | * |
3593 | * - Rounding errors can result with odd window sizes and/or desktop scales, |
3594 | * which can cause the window contents to appear slightly blurry. |
3595 | * - Positioning the window may be imprecise due to unit conversions and |
3596 | * rounding. |
3597 | * - The window may be unusably small on scaled desktops. |
3598 | * - The window may jump in size when moving between displays of different |
3599 | * scale factors. |
3600 | * - Displays may appear to overlap when using a multi-monitor setup with |
3601 | * scaling enabled. |
3602 | * - Possible loss of cursor precision due to the logical size of the window |
3603 | * being reduced. |
3604 | * |
3605 | * New applications should be designed with proper DPI awareness handling |
3606 | * instead of enabling this. |
3607 | * |
3608 | * The variable can be set to the following values: |
3609 | * |
3610 | * - "0": Windows will be scaled normally. |
3611 | * - "1": Windows will be forced to scale to achieve 1:1 output. |
3612 | * |
3613 | * This hint should be set before creating a window. |
3614 | * |
3615 | * \since This hint is available since SDL 3.2.0. |
3616 | */ |
3617 | #define SDL_HINT_VIDEO_WAYLAND_SCALE_TO_DISPLAY "SDL_VIDEO_WAYLAND_SCALE_TO_DISPLAY" |
3618 | |
3619 | /** |
3620 | * A variable specifying which shader compiler to preload when using the |
3621 | * Chrome ANGLE binaries. |
3622 | * |
3623 | * SDL has EGL and OpenGL ES2 support on Windows via the ANGLE project. It can |
3624 | * use two different sets of binaries, those compiled by the user from source |
3625 | * or those provided by the Chrome browser. In the later case, these binaries |
3626 | * require that SDL loads a DLL providing the shader compiler. |
3627 | * |
3628 | * The variable can be set to the following values: |
3629 | * |
3630 | * - "d3dcompiler_46.dll" - best for Vista or later. (default) |
3631 | * - "d3dcompiler_43.dll" - for XP support. |
3632 | * - "none" - do not load any library, useful if you compiled ANGLE from |
3633 | * source and included the compiler in your binaries. |
3634 | * |
3635 | * This hint should be set before SDL is initialized. |
3636 | * |
3637 | * \since This hint is available since SDL 3.2.0. |
3638 | */ |
3639 | #define SDL_HINT_VIDEO_WIN_D3DCOMPILER "SDL_VIDEO_WIN_D3DCOMPILER" |
3640 | |
3641 | /** |
3642 | * A variable controlling whether SDL should call XSelectInput() to enable |
3643 | * input events on X11 windows wrapped by SDL windows. |
3644 | * |
3645 | * The variable can be set to the following values: |
3646 | * |
3647 | * - "0": Don't call XSelectInput(), assuming the native window code has done |
3648 | * it already. |
3649 | * - "1": Call XSelectInput() to enable input events. (default) |
3650 | * |
3651 | * This hint should be set before creating a window. |
3652 | * |
3653 | * \since This hint is available since SDL 3.2.10. |
3654 | */ |
3655 | #define SDL_HINT_VIDEO_X11_EXTERNAL_WINDOW_INPUT "SDL_VIDEO_X11_EXTERNAL_WINDOW_INPUT" |
3656 | |
3657 | /** |
3658 | * A variable controlling whether the X11 _NET_WM_BYPASS_COMPOSITOR hint |
3659 | * should be used. |
3660 | * |
3661 | * The variable can be set to the following values: |
3662 | * |
3663 | * - "0": Disable _NET_WM_BYPASS_COMPOSITOR. |
3664 | * - "1": Enable _NET_WM_BYPASS_COMPOSITOR. (default) |
3665 | * |
3666 | * This hint should be set before creating a window. |
3667 | * |
3668 | * \since This hint is available since SDL 3.2.0. |
3669 | */ |
3670 | #define SDL_HINT_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR "SDL_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR" |
3671 | |
3672 | /** |
3673 | * A variable controlling whether the X11 _NET_WM_PING protocol should be |
3674 | * supported. |
3675 | * |
3676 | * By default SDL will use _NET_WM_PING, but for applications that know they |
3677 | * will not always be able to respond to ping requests in a timely manner they |
3678 | * can turn it off to avoid the window manager thinking the app is hung. |
3679 | * |
3680 | * The variable can be set to the following values: |
3681 | * |
3682 | * - "0": Disable _NET_WM_PING. |
3683 | * - "1": Enable _NET_WM_PING. (default) |
3684 | * |
3685 | * This hint should be set before creating a window. |
3686 | * |
3687 | * \since This hint is available since SDL 3.2.0. |
3688 | */ |
3689 | #define SDL_HINT_VIDEO_X11_NET_WM_PING "SDL_VIDEO_X11_NET_WM_PING" |
3690 | |
3691 | /** |
3692 | * A variable controlling whether SDL uses DirectColor visuals. |
3693 | * |
3694 | * The variable can be set to the following values: |
3695 | * |
3696 | * - "0": Disable DirectColor visuals. |
3697 | * - "1": Enable DirectColor visuals. (default) |
3698 | * |
3699 | * This hint should be set before initializing the video subsystem. |
3700 | * |
3701 | * \since This hint is available since SDL 3.2.0. |
3702 | */ |
3703 | #define SDL_HINT_VIDEO_X11_NODIRECTCOLOR "SDL_VIDEO_X11_NODIRECTCOLOR" |
3704 | |
3705 | /** |
3706 | * A variable forcing the content scaling factor for X11 displays. |
3707 | * |
3708 | * The variable can be set to a floating point value in the range 1.0-10.0f |
3709 | * |
3710 | * This hint should be set before SDL is initialized. |
3711 | * |
3712 | * \since This hint is available since SDL 3.2.0. |
3713 | */ |
3714 | #define SDL_HINT_VIDEO_X11_SCALING_FACTOR "SDL_VIDEO_X11_SCALING_FACTOR" |
3715 | |
3716 | /** |
3717 | * A variable forcing the visual ID used for X11 display modes. |
3718 | * |
3719 | * This hint should be set before initializing the video subsystem. |
3720 | * |
3721 | * \since This hint is available since SDL 3.2.0. |
3722 | */ |
3723 | #define SDL_HINT_VIDEO_X11_VISUALID "SDL_VIDEO_X11_VISUALID" |
3724 | |
3725 | /** |
3726 | * A variable forcing the visual ID chosen for new X11 windows. |
3727 | * |
3728 | * This hint should be set before creating a window. |
3729 | * |
3730 | * \since This hint is available since SDL 3.2.0. |
3731 | */ |
3732 | #define SDL_HINT_VIDEO_X11_WINDOW_VISUALID "SDL_VIDEO_X11_WINDOW_VISUALID" |
3733 | |
3734 | /** |
3735 | * A variable controlling whether the X11 XRandR extension should be used. |
3736 | * |
3737 | * The variable can be set to the following values: |
3738 | * |
3739 | * - "0": Disable XRandR. |
3740 | * - "1": Enable XRandR. (default) |
3741 | * |
3742 | * This hint should be set before SDL is initialized. |
3743 | * |
3744 | * \since This hint is available since SDL 3.2.0. |
3745 | */ |
3746 | #define SDL_HINT_VIDEO_X11_XRANDR "SDL_VIDEO_X11_XRANDR" |
3747 | |
3748 | /** |
3749 | * A variable controlling whether touch should be enabled on the back panel of |
3750 | * the PlayStation Vita. |
3751 | * |
3752 | * The variable can be set to the following values: |
3753 | * |
3754 | * - "0": Disable touch on the back panel. |
3755 | * - "1": Enable touch on the back panel. (default) |
3756 | * |
3757 | * This hint should be set before SDL is initialized. |
3758 | * |
3759 | * \since This hint is available since SDL 3.2.0. |
3760 | */ |
3761 | #define SDL_HINT_VITA_ENABLE_BACK_TOUCH "SDL_VITA_ENABLE_BACK_TOUCH" |
3762 | |
3763 | /** |
3764 | * A variable controlling whether touch should be enabled on the front panel |
3765 | * of the PlayStation Vita. |
3766 | * |
3767 | * The variable can be set to the following values: |
3768 | * |
3769 | * - "0": Disable touch on the front panel. |
3770 | * - "1": Enable touch on the front panel. (default) |
3771 | * |
3772 | * This hint should be set before SDL is initialized. |
3773 | * |
3774 | * \since This hint is available since SDL 3.2.0. |
3775 | */ |
3776 | #define SDL_HINT_VITA_ENABLE_FRONT_TOUCH "SDL_VITA_ENABLE_FRONT_TOUCH" |
3777 | |
3778 | /** |
3779 | * A variable controlling the module path on the PlayStation Vita. |
3780 | * |
3781 | * This hint defaults to "app0:module" |
3782 | * |
3783 | * This hint should be set before SDL is initialized. |
3784 | * |
3785 | * \since This hint is available since SDL 3.2.0. |
3786 | */ |
3787 | #define SDL_HINT_VITA_MODULE_PATH "SDL_VITA_MODULE_PATH" |
3788 | |
3789 | /** |
3790 | * A variable controlling whether to perform PVR initialization on the |
3791 | * PlayStation Vita. |
3792 | * |
3793 | * - "0": Skip PVR initialization. |
3794 | * - "1": Perform the normal PVR initialization. (default) |
3795 | * |
3796 | * This hint should be set before SDL is initialized. |
3797 | * |
3798 | * \since This hint is available since SDL 3.2.0. |
3799 | */ |
3800 | #define SDL_HINT_VITA_PVR_INIT "SDL_VITA_PVR_INIT" |
3801 | |
3802 | /** |
3803 | * A variable overriding the resolution reported on the PlayStation Vita. |
3804 | * |
3805 | * The variable can be set to the following values: |
3806 | * |
3807 | * - "544": 544p (default) |
3808 | * - "720": 725p for PSTV |
3809 | * - "1080": 1088i for PSTV |
3810 | * |
3811 | * This hint should be set before SDL is initialized. |
3812 | * |
3813 | * \since This hint is available since SDL 3.2.0. |
3814 | */ |
3815 | #define SDL_HINT_VITA_RESOLUTION "SDL_VITA_RESOLUTION" |
3816 | |
3817 | /** |
3818 | * A variable controlling whether OpenGL should be used instead of OpenGL ES |
3819 | * on the PlayStation Vita. |
3820 | * |
3821 | * The variable can be set to the following values: |
3822 | * |
3823 | * - "0": Use OpenGL ES. (default) |
3824 | * - "1": Use OpenGL. |
3825 | * |
3826 | * This hint should be set before SDL is initialized. |
3827 | * |
3828 | * \since This hint is available since SDL 3.2.0. |
3829 | */ |
3830 | #define SDL_HINT_VITA_PVR_OPENGL "SDL_VITA_PVR_OPENGL" |
3831 | |
3832 | /** |
3833 | * A variable controlling which touchpad should generate synthetic mouse |
3834 | * events. |
3835 | * |
3836 | * The variable can be set to the following values: |
3837 | * |
3838 | * - "0": Only front touchpad should generate mouse events. (default) |
3839 | * - "1": Only back touchpad should generate mouse events. |
3840 | * - "2": Both touchpads should generate mouse events. |
3841 | * |
3842 | * This hint can be set anytime. |
3843 | * |
3844 | * \since This hint is available since SDL 3.2.0. |
3845 | */ |
3846 | #define SDL_HINT_VITA_TOUCH_MOUSE_DEVICE "SDL_VITA_TOUCH_MOUSE_DEVICE" |
3847 | |
3848 | /** |
3849 | * A variable overriding the display index used in SDL_Vulkan_CreateSurface() |
3850 | * |
3851 | * The display index starts at 0, which is the default. |
3852 | * |
3853 | * This hint should be set before calling SDL_Vulkan_CreateSurface() |
3854 | * |
3855 | * \since This hint is available since SDL 3.2.0. |
3856 | */ |
3857 | #define SDL_HINT_VULKAN_DISPLAY "SDL_VULKAN_DISPLAY" |
3858 | |
3859 | /** |
3860 | * Specify the Vulkan library to load. |
3861 | * |
3862 | * This hint should be set before creating a Vulkan window or calling |
3863 | * SDL_Vulkan_LoadLibrary(). |
3864 | * |
3865 | * \since This hint is available since SDL 3.2.0. |
3866 | */ |
3867 | #define SDL_HINT_VULKAN_LIBRARY "SDL_VULKAN_LIBRARY" |
3868 | |
3869 | /** |
3870 | * A variable controlling how the fact chunk affects the loading of a WAVE |
3871 | * file. |
3872 | * |
3873 | * The fact chunk stores information about the number of samples of a WAVE |
3874 | * file. The Standards Update from Microsoft notes that this value can be used |
3875 | * to 'determine the length of the data in seconds'. This is especially useful |
3876 | * for compressed formats (for which this is a mandatory chunk) if they |
3877 | * produce multiple sample frames per block and truncating the block is not |
3878 | * allowed. The fact chunk can exactly specify how many sample frames there |
3879 | * should be in this case. |
3880 | * |
3881 | * Unfortunately, most application seem to ignore the fact chunk and so SDL |
3882 | * ignores it by default as well. |
3883 | * |
3884 | * The variable can be set to the following values: |
3885 | * |
3886 | * - "truncate" - Use the number of samples to truncate the wave data if the |
3887 | * fact chunk is present and valid. |
3888 | * - "strict" - Like "truncate", but raise an error if the fact chunk is |
3889 | * invalid, not present for non-PCM formats, or if the data chunk doesn't |
3890 | * have that many samples. |
3891 | * - "ignorezero" - Like "truncate", but ignore fact chunk if the number of |
3892 | * samples is zero. |
3893 | * - "ignore" - Ignore fact chunk entirely. (default) |
3894 | * |
3895 | * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() |
3896 | * |
3897 | * \since This hint is available since SDL 3.2.0. |
3898 | */ |
3899 | #define SDL_HINT_WAVE_FACT_CHUNK "SDL_WAVE_FACT_CHUNK" |
3900 | |
3901 | /** |
3902 | * A variable controlling the maximum number of chunks in a WAVE file. |
3903 | * |
3904 | * This sets an upper bound on the number of chunks in a WAVE file to avoid |
3905 | * wasting time on malformed or corrupt WAVE files. This defaults to "10000". |
3906 | * |
3907 | * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() |
3908 | * |
3909 | * \since This hint is available since SDL 3.2.0. |
3910 | */ |
3911 | #define SDL_HINT_WAVE_CHUNK_LIMIT "SDL_WAVE_CHUNK_LIMIT" |
3912 | |
3913 | /** |
3914 | * A variable controlling how the size of the RIFF chunk affects the loading |
3915 | * of a WAVE file. |
3916 | * |
3917 | * The size of the RIFF chunk (which includes all the sub-chunks of the WAVE |
3918 | * file) is not always reliable. In case the size is wrong, it's possible to |
3919 | * just ignore it and step through the chunks until a fixed limit is reached. |
3920 | * |
3921 | * Note that files that have trailing data unrelated to the WAVE file or |
3922 | * corrupt files may slow down the loading process without a reliable |
3923 | * boundary. By default, SDL stops after 10000 chunks to prevent wasting time. |
3924 | * Use SDL_HINT_WAVE_CHUNK_LIMIT to adjust this value. |
3925 | * |
3926 | * The variable can be set to the following values: |
3927 | * |
3928 | * - "force" - Always use the RIFF chunk size as a boundary for the chunk |
3929 | * search. |
3930 | * - "ignorezero" - Like "force", but a zero size searches up to 4 GiB. |
3931 | * (default) |
3932 | * - "ignore" - Ignore the RIFF chunk size and always search up to 4 GiB. |
3933 | * - "maximum" - Search for chunks until the end of file. (not recommended) |
3934 | * |
3935 | * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() |
3936 | * |
3937 | * \since This hint is available since SDL 3.2.0. |
3938 | */ |
3939 | #define SDL_HINT_WAVE_RIFF_CHUNK_SIZE "SDL_WAVE_RIFF_CHUNK_SIZE" |
3940 | |
3941 | /** |
3942 | * A variable controlling how a truncated WAVE file is handled. |
3943 | * |
3944 | * A WAVE file is considered truncated if any of the chunks are incomplete or |
3945 | * the data chunk size is not a multiple of the block size. By default, SDL |
3946 | * decodes until the first incomplete block, as most applications seem to do. |
3947 | * |
3948 | * The variable can be set to the following values: |
3949 | * |
3950 | * - "verystrict" - Raise an error if the file is truncated. |
3951 | * - "strict" - Like "verystrict", but the size of the RIFF chunk is ignored. |
3952 | * - "dropframe" - Decode until the first incomplete sample frame. |
3953 | * - "dropblock" - Decode until the first incomplete block. (default) |
3954 | * |
3955 | * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() |
3956 | * |
3957 | * \since This hint is available since SDL 3.2.0. |
3958 | */ |
3959 | #define SDL_HINT_WAVE_TRUNCATION "SDL_WAVE_TRUNCATION" |
3960 | |
3961 | /** |
3962 | * A variable controlling whether the window is activated when the |
3963 | * SDL_RaiseWindow function is called. |
3964 | * |
3965 | * The variable can be set to the following values: |
3966 | * |
3967 | * - "0": The window is not activated when the SDL_RaiseWindow function is |
3968 | * called. |
3969 | * - "1": The window is activated when the SDL_RaiseWindow function is called. |
3970 | * (default) |
3971 | * |
3972 | * This hint can be set anytime. |
3973 | * |
3974 | * \since This hint is available since SDL 3.2.0. |
3975 | */ |
3976 | #define SDL_HINT_WINDOW_ACTIVATE_WHEN_RAISED "SDL_WINDOW_ACTIVATE_WHEN_RAISED" |
3977 | |
3978 | /** |
3979 | * A variable controlling whether the window is activated when the |
3980 | * SDL_ShowWindow function is called. |
3981 | * |
3982 | * The variable can be set to the following values: |
3983 | * |
3984 | * - "0": The window is not activated when the SDL_ShowWindow function is |
3985 | * called. |
3986 | * - "1": The window is activated when the SDL_ShowWindow function is called. |
3987 | * (default) |
3988 | * |
3989 | * This hint can be set anytime. |
3990 | * |
3991 | * \since This hint is available since SDL 3.2.0. |
3992 | */ |
3993 | #define SDL_HINT_WINDOW_ACTIVATE_WHEN_SHOWN "SDL_WINDOW_ACTIVATE_WHEN_SHOWN" |
3994 | |
3995 | /** |
3996 | * If set to "0" then never set the top-most flag on an SDL Window even if the |
3997 | * application requests it. |
3998 | * |
3999 | * This is a debugging aid for developers and not expected to be used by end |
4000 | * users. |
4001 | * |
4002 | * The variable can be set to the following values: |
4003 | * |
4004 | * - "0": don't allow topmost |
4005 | * - "1": allow topmost (default) |
4006 | * |
4007 | * This hint can be set anytime. |
4008 | * |
4009 | * \since This hint is available since SDL 3.2.0. |
4010 | */ |
4011 | #define SDL_HINT_WINDOW_ALLOW_TOPMOST "SDL_WINDOW_ALLOW_TOPMOST" |
4012 | |
4013 | /** |
4014 | * A variable controlling whether the window frame and title bar are |
4015 | * interactive when the cursor is hidden. |
4016 | * |
4017 | * The variable can be set to the following values: |
4018 | * |
4019 | * - "0": The window frame is not interactive when the cursor is hidden (no |
4020 | * move, resize, etc). |
4021 | * - "1": The window frame is interactive when the cursor is hidden. (default) |
4022 | * |
4023 | * This hint can be set anytime. |
4024 | * |
4025 | * \since This hint is available since SDL 3.2.0. |
4026 | */ |
4027 | #define SDL_HINT_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN "SDL_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN" |
4028 | |
4029 | /** |
4030 | * A variable controlling whether SDL generates window-close events for Alt+F4 |
4031 | * on Windows. |
4032 | * |
4033 | * The variable can be set to the following values: |
4034 | * |
4035 | * - "0": SDL will only do normal key handling for Alt+F4. |
4036 | * - "1": SDL will generate a window-close event when it sees Alt+F4. |
4037 | * (default) |
4038 | * |
4039 | * This hint can be set anytime. |
4040 | * |
4041 | * \since This hint is available since SDL 3.2.0. |
4042 | */ |
4043 | #define SDL_HINT_WINDOWS_CLOSE_ON_ALT_F4 "SDL_WINDOWS_CLOSE_ON_ALT_F4" |
4044 | |
4045 | /** |
4046 | * A variable controlling whether menus can be opened with their keyboard |
4047 | * shortcut (Alt+mnemonic). |
4048 | * |
4049 | * If the mnemonics are enabled, then menus can be opened by pressing the Alt |
4050 | * key and the corresponding mnemonic (for example, Alt+F opens the File |
4051 | * menu). However, in case an invalid mnemonic is pressed, Windows makes an |
4052 | * audible beep to convey that nothing happened. This is true even if the |
4053 | * window has no menu at all! |
4054 | * |
4055 | * Because most SDL applications don't have menus, and some want to use the |
4056 | * Alt key for other purposes, SDL disables mnemonics (and the beeping) by |
4057 | * default. |
4058 | * |
4059 | * Note: This also affects keyboard events: with mnemonics enabled, when a |
4060 | * menu is opened from the keyboard, you will not receive a KEYUP event for |
4061 | * the mnemonic key, and *might* not receive one for Alt. |
4062 | * |
4063 | * The variable can be set to the following values: |
4064 | * |
4065 | * - "0": Alt+mnemonic does nothing, no beeping. (default) |
4066 | * - "1": Alt+mnemonic opens menus, invalid mnemonics produce a beep. |
4067 | * |
4068 | * This hint can be set anytime. |
4069 | * |
4070 | * \since This hint is available since SDL 3.2.0. |
4071 | */ |
4072 | #define "SDL_WINDOWS_ENABLE_MENU_MNEMONICS" |
4073 | |
4074 | /** |
4075 | * A variable controlling whether the windows message loop is processed by |
4076 | * SDL. |
4077 | * |
4078 | * The variable can be set to the following values: |
4079 | * |
4080 | * - "0": The window message loop is not run. |
4081 | * - "1": The window message loop is processed in SDL_PumpEvents(). (default) |
4082 | * |
4083 | * This hint can be set anytime. |
4084 | * |
4085 | * \since This hint is available since SDL 3.2.0. |
4086 | */ |
4087 | #define SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP "SDL_WINDOWS_ENABLE_MESSAGELOOP" |
4088 | |
4089 | /** |
4090 | * A variable controlling whether GameInput is used for raw keyboard and mouse |
4091 | * on Windows. |
4092 | * |
4093 | * The variable can be set to the following values: |
4094 | * |
4095 | * - "0": GameInput is not used for raw keyboard and mouse events. |
4096 | * - "1": GameInput is used for raw keyboard and mouse events, if available. |
4097 | * (default) |
4098 | * |
4099 | * This hint should be set before SDL is initialized. |
4100 | * |
4101 | * \since This hint is available since SDL 3.2.0. |
4102 | */ |
4103 | #define SDL_HINT_WINDOWS_GAMEINPUT "SDL_WINDOWS_GAMEINPUT" |
4104 | |
4105 | /** |
4106 | * A variable controlling whether raw keyboard events are used on Windows. |
4107 | * |
4108 | * The variable can be set to the following values: |
4109 | * |
4110 | * - "0": The Windows message loop is used for keyboard events. (default) |
4111 | * - "1": Low latency raw keyboard events are used. |
4112 | * |
4113 | * This hint can be set anytime. |
4114 | * |
4115 | * \since This hint is available since SDL 3.2.0. |
4116 | */ |
4117 | #define SDL_HINT_WINDOWS_RAW_KEYBOARD "SDL_WINDOWS_RAW_KEYBOARD" |
4118 | |
4119 | /** |
4120 | * A variable controlling whether SDL uses Kernel Semaphores on Windows. |
4121 | * |
4122 | * Kernel Semaphores are inter-process and require a context switch on every |
4123 | * interaction. On Windows 8 and newer, the WaitOnAddress API is available. |
4124 | * Using that and atomics to implement semaphores increases performance. SDL |
4125 | * will fall back to Kernel Objects on older OS versions or if forced to by |
4126 | * this hint. |
4127 | * |
4128 | * The variable can be set to the following values: |
4129 | * |
4130 | * - "0": Use Atomics and WaitOnAddress API when available, otherwise fall |
4131 | * back to Kernel Objects. (default) |
4132 | * - "1": Force the use of Kernel Objects in all cases. |
4133 | * |
4134 | * This hint should be set before SDL is initialized. |
4135 | * |
4136 | * \since This hint is available since SDL 3.2.0. |
4137 | */ |
4138 | #define SDL_HINT_WINDOWS_FORCE_SEMAPHORE_KERNEL "SDL_WINDOWS_FORCE_SEMAPHORE_KERNEL" |
4139 | |
4140 | /** |
4141 | * A variable to specify custom icon resource id from RC file on Windows |
4142 | * platform. |
4143 | * |
4144 | * This hint should be set before SDL is initialized. |
4145 | * |
4146 | * \since This hint is available since SDL 3.2.0. |
4147 | */ |
4148 | #define SDL_HINT_WINDOWS_INTRESOURCE_ICON "SDL_WINDOWS_INTRESOURCE_ICON" |
4149 | |
4150 | /** |
4151 | * A variable to specify custom icon resource id from RC file on Windows |
4152 | * platform. |
4153 | * |
4154 | * This hint should be set before SDL is initialized. |
4155 | * |
4156 | * \since This hint is available since SDL 3.2.0. |
4157 | */ |
4158 | #define SDL_HINT_WINDOWS_INTRESOURCE_ICON_SMALL "SDL_WINDOWS_INTRESOURCE_ICON_SMALL" |
4159 | |
4160 | /** |
4161 | * A variable controlling whether SDL uses the D3D9Ex API introduced in |
4162 | * Windows Vista, instead of normal D3D9. |
4163 | * |
4164 | * Direct3D 9Ex contains changes to state management that can eliminate device |
4165 | * loss errors during scenarios like Alt+Tab or UAC prompts. D3D9Ex may |
4166 | * require some changes to your application to cope with the new behavior, so |
4167 | * this is disabled by default. |
4168 | * |
4169 | * For more information on Direct3D 9Ex, see: |
4170 | * |
4171 | * - https://docs.microsoft.com/en-us/windows/win32/direct3darticles/graphics-apis-in-windows-vista#direct3d-9ex |
4172 | * - https://docs.microsoft.com/en-us/windows/win32/direct3darticles/direct3d-9ex-improvements |
4173 | * |
4174 | * The variable can be set to the following values: |
4175 | * |
4176 | * - "0": Use the original Direct3D 9 API. (default) |
4177 | * - "1": Use the Direct3D 9Ex API on Vista and later (and fall back if D3D9Ex |
4178 | * is unavailable) |
4179 | * |
4180 | * This hint should be set before SDL is initialized. |
4181 | * |
4182 | * \since This hint is available since SDL 3.2.0. |
4183 | */ |
4184 | #define SDL_HINT_WINDOWS_USE_D3D9EX "SDL_WINDOWS_USE_D3D9EX" |
4185 | |
4186 | /** |
4187 | * A variable controlling whether SDL will clear the window contents when the |
4188 | * WM_ERASEBKGND message is received. |
4189 | * |
4190 | * The variable can be set to the following values: |
4191 | * |
4192 | * - "0"/"never": Never clear the window. |
4193 | * - "1"/"initial": Clear the window when the first WM_ERASEBKGND event fires. |
4194 | * (default) |
4195 | * - "2"/"always": Clear the window on every WM_ERASEBKGND event. |
4196 | * |
4197 | * This hint should be set before creating a window. |
4198 | * |
4199 | * \since This hint is available since SDL 3.2.0. |
4200 | */ |
4201 | #define SDL_HINT_WINDOWS_ERASE_BACKGROUND_MODE "SDL_WINDOWS_ERASE_BACKGROUND_MODE" |
4202 | |
4203 | /** |
4204 | * A variable controlling whether X11 windows are marked as override-redirect. |
4205 | * |
4206 | * If set, this _might_ increase framerate at the expense of the desktop not |
4207 | * working as expected. Override-redirect windows aren't noticed by the window |
4208 | * manager at all. |
4209 | * |
4210 | * You should probably only use this for fullscreen windows, and you probably |
4211 | * shouldn't even use it for that. But it's here if you want to try! |
4212 | * |
4213 | * The variable can be set to the following values: |
4214 | * |
4215 | * - "0": Do not mark the window as override-redirect. (default) |
4216 | * - "1": Mark the window as override-redirect. |
4217 | * |
4218 | * This hint should be set before creating a window. |
4219 | * |
4220 | * \since This hint is available since SDL 3.2.0. |
4221 | */ |
4222 | #define SDL_HINT_X11_FORCE_OVERRIDE_REDIRECT "SDL_X11_FORCE_OVERRIDE_REDIRECT" |
4223 | |
4224 | /** |
4225 | * A variable specifying the type of an X11 window. |
4226 | * |
4227 | * During SDL_CreateWindow, SDL uses the _NET_WM_WINDOW_TYPE X11 property to |
4228 | * report to the window manager the type of window it wants to create. This |
4229 | * might be set to various things if SDL_WINDOW_TOOLTIP or |
4230 | * SDL_WINDOW_POPUP_MENU, etc, were specified. For "normal" windows that |
4231 | * haven't set a specific type, this hint can be used to specify a custom |
4232 | * type. For example, a dock window might set this to |
4233 | * "_NET_WM_WINDOW_TYPE_DOCK". |
4234 | * |
4235 | * This hint should be set before creating a window. |
4236 | * |
4237 | * \since This hint is available since SDL 3.2.0. |
4238 | */ |
4239 | #define SDL_HINT_X11_WINDOW_TYPE "SDL_X11_WINDOW_TYPE" |
4240 | |
4241 | /** |
4242 | * Specify the XCB library to load for the X11 driver. |
4243 | * |
4244 | * The default is platform-specific, often "libX11-xcb.so.1". |
4245 | * |
4246 | * This hint should be set before initializing the video subsystem. |
4247 | * |
4248 | * \since This hint is available since SDL 3.2.0. |
4249 | */ |
4250 | #define SDL_HINT_X11_XCB_LIBRARY "SDL_X11_XCB_LIBRARY" |
4251 | |
4252 | /** |
4253 | * A variable controlling whether XInput should be used for controller |
4254 | * handling. |
4255 | * |
4256 | * The variable can be set to the following values: |
4257 | * |
4258 | * - "0": XInput is not enabled. |
4259 | * - "1": XInput is enabled. (default) |
4260 | * |
4261 | * This hint should be set before SDL is initialized. |
4262 | * |
4263 | * \since This hint is available since SDL 3.2.0. |
4264 | */ |
4265 | #define SDL_HINT_XINPUT_ENABLED "SDL_XINPUT_ENABLED" |
4266 | |
4267 | /** |
4268 | * A variable controlling response to SDL_assert failures. |
4269 | * |
4270 | * The variable can be set to the following case-sensitive values: |
4271 | * |
4272 | * - "abort": Program terminates immediately. |
4273 | * - "break": Program triggers a debugger breakpoint. |
4274 | * - "retry": Program reruns the SDL_assert's test again. |
4275 | * - "ignore": Program continues on, ignoring this assertion failure this |
4276 | * time. |
4277 | * - "always_ignore": Program continues on, ignoring this assertion failure |
4278 | * for the rest of the run. |
4279 | * |
4280 | * Note that SDL_SetAssertionHandler offers a programmatic means to deal with |
4281 | * assertion failures through a callback, and this hint is largely intended to |
4282 | * be used via environment variables by end users and automated tools. |
4283 | * |
4284 | * This hint should be set before an assertion failure is triggered and can be |
4285 | * changed at any time. |
4286 | * |
4287 | * \since This hint is available since SDL 3.2.0. |
4288 | */ |
4289 | #define SDL_HINT_ASSERT "SDL_ASSERT" |
4290 | |
4291 | /** |
4292 | * A variable controlling whether pen events should generate synthetic mouse |
4293 | * events. |
4294 | * |
4295 | * The variable can be set to the following values: |
4296 | * |
4297 | * - "0": Pen events will not generate mouse events. |
4298 | * - "1": Pen events will generate mouse events. (default) |
4299 | * |
4300 | * This hint can be set anytime. |
4301 | * |
4302 | * \since This hint is available since SDL 3.2.0. |
4303 | */ |
4304 | #define SDL_HINT_PEN_MOUSE_EVENTS "SDL_PEN_MOUSE_EVENTS" |
4305 | |
4306 | /** |
4307 | * A variable controlling whether pen events should generate synthetic touch |
4308 | * events. |
4309 | * |
4310 | * The variable can be set to the following values: |
4311 | * |
4312 | * - "0": Pen events will not generate touch events. |
4313 | * - "1": Pen events will generate touch events. (default) |
4314 | * |
4315 | * This hint can be set anytime. |
4316 | * |
4317 | * \since This hint is available since SDL 3.2.0. |
4318 | */ |
4319 | #define SDL_HINT_PEN_TOUCH_EVENTS "SDL_PEN_TOUCH_EVENTS" |
4320 | |
4321 | |
4322 | /** |
4323 | * An enumeration of hint priorities. |
4324 | * |
4325 | * \since This enum is available since SDL 3.2.0. |
4326 | */ |
4327 | typedef enum SDL_HintPriority |
4328 | { |
4329 | SDL_HINT_DEFAULT, |
4330 | SDL_HINT_NORMAL, |
4331 | SDL_HINT_OVERRIDE |
4332 | } SDL_HintPriority; |
4333 | |
4334 | /** |
4335 | * Set a hint with a specific priority. |
4336 | * |
4337 | * The priority controls the behavior when setting a hint that already has a |
4338 | * value. Hints will replace existing hints of their priority and lower. |
4339 | * Environment variables are considered to have override priority. |
4340 | * |
4341 | * \param name the hint to set. |
4342 | * \param value the value of the hint variable. |
4343 | * \param priority the SDL_HintPriority level for the hint. |
4344 | * \returns true on success or false on failure; call SDL_GetError() for more |
4345 | * information. |
4346 | * |
4347 | * \threadsafety It is safe to call this function from any thread. |
4348 | * |
4349 | * \since This function is available since SDL 3.2.0. |
4350 | * |
4351 | * \sa SDL_GetHint |
4352 | * \sa SDL_ResetHint |
4353 | * \sa SDL_SetHint |
4354 | */ |
4355 | extern SDL_DECLSPEC bool SDLCALL SDL_SetHintWithPriority(const char *name, const char *value, SDL_HintPriority priority); |
4356 | |
4357 | /** |
4358 | * Set a hint with normal priority. |
4359 | * |
4360 | * Hints will not be set if there is an existing override hint or environment |
4361 | * variable that takes precedence. You can use SDL_SetHintWithPriority() to |
4362 | * set the hint with override priority instead. |
4363 | * |
4364 | * \param name the hint to set. |
4365 | * \param value the value of the hint variable. |
4366 | * \returns true on success or false on failure; call SDL_GetError() for more |
4367 | * information. |
4368 | * |
4369 | * \threadsafety It is safe to call this function from any thread. |
4370 | * |
4371 | * \since This function is available since SDL 3.2.0. |
4372 | * |
4373 | * \sa SDL_GetHint |
4374 | * \sa SDL_ResetHint |
4375 | * \sa SDL_SetHintWithPriority |
4376 | */ |
4377 | extern SDL_DECLSPEC bool SDLCALL SDL_SetHint(const char *name, const char *value); |
4378 | |
4379 | /** |
4380 | * Reset a hint to the default value. |
4381 | * |
4382 | * This will reset a hint to the value of the environment variable, or NULL if |
4383 | * the environment isn't set. Callbacks will be called normally with this |
4384 | * change. |
4385 | * |
4386 | * \param name the hint to set. |
4387 | * \returns true on success or false on failure; call SDL_GetError() for more |
4388 | * information. |
4389 | * |
4390 | * \threadsafety It is safe to call this function from any thread. |
4391 | * |
4392 | * \since This function is available since SDL 3.2.0. |
4393 | * |
4394 | * \sa SDL_SetHint |
4395 | * \sa SDL_ResetHints |
4396 | */ |
4397 | extern SDL_DECLSPEC bool SDLCALL SDL_ResetHint(const char *name); |
4398 | |
4399 | /** |
4400 | * Reset all hints to the default values. |
4401 | * |
4402 | * This will reset all hints to the value of the associated environment |
4403 | * variable, or NULL if the environment isn't set. Callbacks will be called |
4404 | * normally with this change. |
4405 | * |
4406 | * \threadsafety It is safe to call this function from any thread. |
4407 | * |
4408 | * \since This function is available since SDL 3.2.0. |
4409 | * |
4410 | * \sa SDL_ResetHint |
4411 | */ |
4412 | extern SDL_DECLSPEC void SDLCALL SDL_ResetHints(void); |
4413 | |
4414 | /** |
4415 | * Get the value of a hint. |
4416 | * |
4417 | * \param name the hint to query. |
4418 | * \returns the string value of a hint or NULL if the hint isn't set. |
4419 | * |
4420 | * \threadsafety It is safe to call this function from any thread, however the |
4421 | * return value only remains valid until the hint is changed; if |
4422 | * another thread might do so, the app should supply locks |
4423 | * and/or make a copy of the string. Note that using a hint |
4424 | * callback instead is always thread-safe, as SDL holds a lock |
4425 | * on the thread subsystem during the callback. |
4426 | * |
4427 | * \since This function is available since SDL 3.2.0. |
4428 | * |
4429 | * \sa SDL_SetHint |
4430 | * \sa SDL_SetHintWithPriority |
4431 | */ |
4432 | extern SDL_DECLSPEC const char * SDLCALL SDL_GetHint(const char *name); |
4433 | |
4434 | /** |
4435 | * Get the boolean value of a hint variable. |
4436 | * |
4437 | * \param name the name of the hint to get the boolean value from. |
4438 | * \param default_value the value to return if the hint does not exist. |
4439 | * \returns the boolean value of a hint or the provided default value if the |
4440 | * hint does not exist. |
4441 | * |
4442 | * \threadsafety It is safe to call this function from any thread. |
4443 | * |
4444 | * \since This function is available since SDL 3.2.0. |
4445 | * |
4446 | * \sa SDL_GetHint |
4447 | * \sa SDL_SetHint |
4448 | */ |
4449 | extern SDL_DECLSPEC bool SDLCALL SDL_GetHintBoolean(const char *name, bool default_value); |
4450 | |
4451 | /** |
4452 | * A callback used to send notifications of hint value changes. |
4453 | * |
4454 | * This is called an initial time during SDL_AddHintCallback with the hint's |
4455 | * current value, and then again each time the hint's value changes. |
4456 | * |
4457 | * \param userdata what was passed as `userdata` to SDL_AddHintCallback(). |
4458 | * \param name what was passed as `name` to SDL_AddHintCallback(). |
4459 | * \param oldValue the previous hint value. |
4460 | * \param newValue the new value hint is to be set to. |
4461 | * |
4462 | * \threadsafety This callback is fired from whatever thread is setting a new |
4463 | * hint value. SDL holds a lock on the hint subsystem when |
4464 | * calling this callback. |
4465 | * |
4466 | * \since This datatype is available since SDL 3.2.0. |
4467 | * |
4468 | * \sa SDL_AddHintCallback |
4469 | */ |
4470 | typedef void(SDLCALL *SDL_HintCallback)(void *userdata, const char *name, const char *oldValue, const char *newValue); |
4471 | |
4472 | /** |
4473 | * Add a function to watch a particular hint. |
4474 | * |
4475 | * The callback function is called _during_ this function, to provide it an |
4476 | * initial value, and again each time the hint's value changes. |
4477 | * |
4478 | * \param name the hint to watch. |
4479 | * \param callback An SDL_HintCallback function that will be called when the |
4480 | * hint value changes. |
4481 | * \param userdata a pointer to pass to the callback function. |
4482 | * \returns true on success or false on failure; call SDL_GetError() for more |
4483 | * information. |
4484 | * |
4485 | * \threadsafety It is safe to call this function from any thread. |
4486 | * |
4487 | * \since This function is available since SDL 3.2.0. |
4488 | * |
4489 | * \sa SDL_RemoveHintCallback |
4490 | */ |
4491 | extern SDL_DECLSPEC bool SDLCALL SDL_AddHintCallback(const char *name, SDL_HintCallback callback, void *userdata); |
4492 | |
4493 | /** |
4494 | * Remove a function watching a particular hint. |
4495 | * |
4496 | * \param name the hint being watched. |
4497 | * \param callback an SDL_HintCallback function that will be called when the |
4498 | * hint value changes. |
4499 | * \param userdata a pointer being passed to the callback function. |
4500 | * |
4501 | * \threadsafety It is safe to call this function from any thread. |
4502 | * |
4503 | * \since This function is available since SDL 3.2.0. |
4504 | * |
4505 | * \sa SDL_AddHintCallback |
4506 | */ |
4507 | extern SDL_DECLSPEC void SDLCALL SDL_RemoveHintCallback(const char *name, |
4508 | SDL_HintCallback callback, |
4509 | void *userdata); |
4510 | |
4511 | /* Ends C function definitions when using C++ */ |
4512 | #ifdef __cplusplus |
4513 | } |
4514 | #endif |
4515 | #include <SDL3/SDL_close_code.h> |
4516 | |
4517 | #endif /* SDL_hints_h_ */ |
4518 | |