Repository navigation
Expand file tree
/
Copy pathSDL_hints.h
More file actions
3334 lines (3105 loc) · 118 KB
/
Copy pathSDL_hints.h
File metadata and controls
3334 lines (3105 loc) · 118 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/*
Simple DirectMedia Layer
Copyright (C) 1997-2026 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.
Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:
1. The origin of this software must not be misrepresented; you must not
claim that you wrote the original software. If you use this software
in a product, an acknowledgment in the product documentation would be
appreciated but is not required.
2. Altered source versions must be plainly marked as such, and must not be
misrepresented as being the original software.
3. This notice may not be removed or altered from any source distribution.
*/
/**
* # CategoryHints
*
* Official documentation for SDL configuration variables
*
* This file contains functions to set and get configuration hints, as well as
* listing each of them alphabetically.
*
* The convention for naming hints is SDL_HINT_X, where "SDL_X" is the
* environment variable that can be used to override the default.
*
* In general these hints are just that - they may or may not be supported or
* applicable on any given platform, but they provide a way for an application
* or user to give the library a hint as to how they would like the library to
* work.
*/
#ifndef SDL_hints_h_
#define SDL_hints_h_
#include "SDL_stdinc.h"
#include "begin_code.h"
/* Set up for C function definitions, even when using C++ */
#ifdef __cplusplus
extern "C" {
#endif
/**
* A variable controlling whether the Android / iOS built-in accelerometer
* should be listed as a joystick device.
*
* This variable can be set to the following values:
*
* - "0": The accelerometer is not listed as a joystick
* - "1": The accelerometer is available as a 3 axis joystick (the default).
*/
#define SDL_HINT_ACCELEROMETER_AS_JOYSTICK "SDL_ACCELEROMETER_AS_JOYSTICK"
/**
* Specify the behavior of Alt+Tab while the keyboard is grabbed.
*
* By default, SDL emulates Alt+Tab functionality while the keyboard is
* grabbed and your window is full-screen. This prevents the user from getting
* stuck in your application if you've enabled keyboard grab.
*
* The variable can be set to the following values:
*
* - "0": SDL will not handle Alt+Tab. Your application is responsible for
* handling Alt+Tab while the keyboard is grabbed.
* - "1": SDL will minimize your window when Alt+Tab is pressed (default)
*/
#define SDL_HINT_ALLOW_ALT_TAB_WHILE_GRABBED "SDL_ALLOW_ALT_TAB_WHILE_GRABBED"
/**
* If set to "0" then never set the top most bit on a SDL Window, even if the
* video mode expects it.
*
* This is a debugging aid for developers and not expected to be used by end
* users. The default is "1"
*
* This variable can be set to the following values:
*
* - "0": don't allow topmost
* - "1": allow topmost
*/
#define SDL_HINT_ALLOW_TOPMOST "SDL_ALLOW_TOPMOST"
/**
* Android APK expansion main file version.
*
* Should be a string number like "1", "2" etc.
*
* Must be set together with
* SDL_HINT_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION.
*
* If both hints were set then SDL_RWFromFile() will look into expansion files
* after a given relative path was not found in the internal storage and
* assets.
*
* By default this hint is not set and the APK expansion files are not
* searched.
*/
#define SDL_HINT_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION "SDL_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION"
/**
* Android APK expansion patch file version.
*
* Should be a string number like "1", "2" etc.
*
* Must be set together with SDL_HINT_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION.
*
* If both hints were set then SDL_RWFromFile() will look into expansion files
* after a given relative path was not found in the internal storage and
* assets.
*
* By default this hint is not set and the APK expansion files are not
* searched.
*/
#define SDL_HINT_ANDR
7438
OID_APK_EXPANSION_PATCH_FILE_VERSION "SDL_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION"
/**
* A variable to control whether the event loop will block itself when the app
* is paused.
*
* The variable can be set to the following values:
*
* - "0": Non blocking.
* - "1": Blocking. (default)
*
* The value should be set before SDL is initialized.
*/
#define SDL_HINT_ANDROID_BLOCK_ON_PAUSE "SDL_ANDROID_BLOCK_ON_PAUSE"
/**
* A variable to control whether SDL will pause audio in background (Requires
* SDL_ANDROID_BLOCK_ON_PAUSE as "Non blocking")
*
* The variable can be set to the following values:
*
* - "0": Non paused.
* - "1": Paused. (default)
*
* The value should be set before SDL is initialized.
*/
#define SDL_HINT_ANDROID_BLOCK_ON_PAUSE_PAUSEAUDIO "SDL_ANDROID_BLOCK_ON_PAUSE_PAUSEAUDIO"
/**
* A variable to control whether we trap the Android back button to handle it
* manually.
*
* This is necessary for the right mouse button to work on some Android
* devices, or to be able to trap the back button for use in your code
* reliably. If set to true, the back button will show up as an SDL_KEYDOWN /
* SDL_KEYUP pair with a keycode of SDL_SCANCODE_AC_BACK.
*
* The variable can be set to the following values:
*
* - "0": Back button will be handled as usual for system. (default)
* - "1": Back button will be trapped, allowing you to handle the key press
* manually. (This will also let right mouse click work on systems where the
* right mouse button functions as back.)
*
* The value of this hint is used at runtime, so it can be changed at any
* time.
*/
#define SDL_HINT_ANDROID_TRAP_BACK_BUTTON "SDL_ANDROID_TRAP_BACK_BUTTON"
/**
* Specify an application name.
*
* This hint lets you specify the application name sent to the OS when
* required. For example, this will often appear in volume control applets for
* audio streams, and in lists of applications which are inhibiting the
* screensaver. You should use a string that describes your program ("My Game
* 2: The Revenge")
*
* Setting this to "" or leaving it unset will have SDL use a reasonable
* default: probably the application's name or "SDL Application" if SDL
* doesn't have any better information.
*
* Note that, for audio streams, this can be overridden with
* SDL_HINT_AUDIO_DEVICE_APP_NAME.
*
* On targets where this is not supported, this hint does nothing.
*/
#define SDL_HINT_APP_NAME "SDL_APP_NAME"
/**
* A variable controlling whether controllers used with the Apple TV generate
* UI events.
*
* When UI events are generated by controller input, the app will be
* backgrounded when the Apple TV remote's menu button is pressed, and when
* the pause or B buttons on gamepads are pressed.
*
* More information about properly making use of controllers for the Apple TV
* can be found here:
* https://developer.apple.com/tvos/human-interface-guidelines/remote-and-controllers/
*
* This variable can be set to the following values:
*
* - "0": Controller input does not generate UI events (the default).
* - "1": Controller input generates UI events.
*/
#define SDL_HINT_APPLE_TV_CONTROLLER_UI_EVENTS "SDL_APPLE_TV_CONTROLLER_UI_EVENTS"
/**
* A variable controlling whether the Apple TV remote's joystick axes will
* automatically match the rotation of the remote.
*
* This variable can be set to the following values:
*
* - "0": Remote orientation does not affect joystick axes (the default).
* - "1": Joystick axes are based on the orientation of the remote.
*/
#define SDL_HINT_APPLE_TV_REMOTE_ALLOW_ROTATION "SDL_APPLE_TV_REMOTE_ALLOW_ROTATION"
/**
* A variable controlling the audio category on iOS and Mac OS X
*
* This variable can be set to the following values:
*
* - "ambient": Use the AVAudioSessionCategoryAmbient audio category, will be
* muted by the phone mute switch (default)
* - "playback": Use the AVAudioSessionCategoryPlayback category
*
* For more information, see Apple's documentation:
* https://developer.apple.com/library/content/documentation/Audio/Conceptual/AudioSessionProgrammingGuide/AudioSessionCategoriesandModes/AudioSessionCategoriesandModes.html
*/
#define SDL_HINT_AUDIO_CATEGORY "SDL_AUDIO_CATEGORY"
/**
* Specify an application name for an audio device.
*
* Some audio backends (such as PulseAudio) allow you to describe your audio
* stream. Among other things, this description might show up in a system
* control panel that lets the user adjust the volume on specific audio
* streams instead of using one giant master volume slider.
*
* This hints lets you transmit that information to the OS. The contents of
* this hint are used while opening an audio device. You should use a string
* that describes your program ("My Game 2: The Revenge")
*
* Setting this to "" or leaving it unset will have SDL use a reasonable
* default: this will be the name set with SDL_HINT_APP_NAME, if that hint is
* set. Otherwise, it'll probably the application's name or "SDL Application"
* if SDL doesn't have any better information.
*
* On targets where this is not supported, this hint does nothing.
*/
#define SDL_HINT_AUDIO_DEVICE_APP_NAME "SDL_AUDIO_DEVICE_APP_NAME"
/**
* Specify an application name for an audio device.
*
* Some audio backends (such as PulseAudio) allow you to describe your audio
* stream. Among other things, this description might show up in a system
* control panel that lets the user adjust the volume on specific audio
* streams instead of using one giant master volume slider.
*
* This hints lets you transmit that information to the OS. The contents of
* this hint are used while opening an audio device. You should use a string
* that describes your what your program is playing ("audio stream" is
* probably sufficient in many cases, but this could be useful for something
* like "team chat" if you have a headset playing VoIP audio separately).
*
* Setting this to "" or leaving it unset will have SDL use a reasonable
* default: "audio stream" or something similar.
*
* On targets where this is not supported, this hint does nothing.
*/
#define SDL_HINT_AUDIO_DEVICE_STREAM_NAME "SDL_AUDIO_DEVICE_STREAM_NAME"
/**
* Specify an application role for an audio device.
*
* Some audio backends (such as Pipewire) allow you to describe the role of
* your audio stream. Among other things, this description might show up in a
* system control panel or software for displaying and manipulating media
* playback/capture graphs.
*
* This hints lets you transmit that information to the OS. The contents of
* this hint are used while opening an audio device. You should use a string
* that describes your what your program is playing (Game, Music, Movie,
* etc...).
*
* Setting this to "" or leaving it unset will have SDL use a reasonable
* default: "Game" or something similar.
*
* On targets where this is not supported, this hint does nothing.
*/
#define SDL_HINT_AUDIO_DEVICE_STREAM_ROLE "SDL_AUDIO_DEVICE_STREAM_ROLE"
/**
* A variable controlling speed/quality tradeoff of audio resampling.
*
* If available, SDL can use libsamplerate ( http://www.mega-nerd.com/SRC/ )
* to handle audio resampling. There are different resampling modes available
* that produce different levels of quality, using more CPU.
*
* If this hint isn't specified to a valid setting, or libsamplerate isn't
* available, SDL will use the default, internal resampling algorithm.
*
* As of SDL 2.26, SDL_ConvertAudio() respects this hint when libsamplerate is
* available.
*
* This hint is currently only checked at audio subsystem initialization.
*
* This variable can be set to the following values:
*
* - "0" or "default": Use SDL's internal resampling (Default when not set -
* low quality, fast)
* - "1" or "fast": Use fast, slightly higher quality resampling, if available
* - "2" or "medium": Use medium quality resampling, if available
* - "3" or "best": Use high quality resampling, if available
*/
#define SDL_HINT_AUDIO_RESAMPLING_MODE "SDL_AUDIO_RESAMPLING_MODE"
/**
* A variable controlling whether SDL updates joystick state when getting
* input events
*
* This variable can be set to the following values:
*
* - "0": You'll call SDL_JoystickUpdate() manually
* - "1": SDL will automatically call SDL_JoystickUpdate() (default)
*
* This hint can be toggled on and off at runtime.
*/
#define SDL_HINT_AUTO_UPDATE_JOYSTICKS "SDL_AUTO_UPDATE_JOYSTICKS"
/**
* A variable controlling whether SDL updates sensor state when getting input
* events
*
* This variable can be set to the following values:
*
* - "0": You'll call SDL_SensorUpdate() manually
* - "1": SDL will automatically call SDL_SensorUpdate() (default)
*
* This hint can be toggled on and off at runtime.
*/
#define SDL_HINT_AUTO_UPDATE_SENSORS "SDL_AUTO_UPDATE_SENSORS"
/**
* Prevent SDL from using version 4 of the bitmap header when saving BMPs.
*
* The bitmap header version 4 is required for proper alpha channel support
* and SDL will use it when required. Should this not be desired, this hint
* can force the use of the 40 byte header version which is supported
* everywhere.
*
* The variable can be set to the following values:
*
* - "0": Surfaces with a colorkey or an alpha channel are saved to a 32-bit
* BMP file with an alpha mask. SDL will use the bitmap header version 4 and
* set the alpha mask accordingly.
* - "1": Surfaces with a colorkey or an alpha channel are saved to a 32-bit
* BMP file without an alpha mask. The alpha channel data will be in the
* file, but applications are going to ignore it.
*
* The default value is "0".
*/
#define SDL_HINT_BMP_SAVE_LEGACY_FORMAT "SDL_BMP_SAVE_LEGACY_FORMAT"
/**
* Override for SDL_GetDisplayUsableBounds()
*
* If set, this hint will override the expected results for
* SDL_GetDisplayUsableBounds() for display index 0. Generally you don't want
* to do this, but this allows an embedded system to request that some of the
* screen be reserved for other uses when paired with a well-behaved
* application.
*
* The contents of this hint must be 4 comma-separated integers, the first is
* the bounds x, then y, width and height, in that order.
*/
#define SDL_HINT_DISPLAY_USABLE_BOUNDS "SDL_DISPLAY_USABLE_BOUNDS"
/**
* Disable giving back control to the browser automatically when running with
* asyncify
*
* With -s ASYNCIFY, SDL2 calls emscripten_sleep during operations such as
* refreshing the screen or polling events.
*
* This hint only applies to the emscripten platform
*
* The variable can be set to the following values:
*
* - "0": Disable emscripten_sleep calls (if you give back browser control
* manually or use asyncify for other purposes)
* - "1": Enable emscripten_sleep calls (the default)
*/
#define SDL_HINT_EMSCRIPTEN_ASYNCIFY "SDL_EMSCRIPTEN_ASYNCIFY"
/**
* override the binding element for keyboard inputs for Emscripten builds
*
* This hint only applies to the emscripten platform.
*
* The variable can be one of:
*
* - "#window": the javascript window object (this is the default)
* - "#document": the javascript document object
* - "#screen": the javascript window.screen object
* - "#canvas": the WebGL canvas element
*
* Any other string without a leading # sign applies to the element on the
* page with that ID.
*/
#define SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT "SDL_EMSCRIPTEN_KEYBOARD_ELEMENT"
/**
* A variable that controls whether the on-screen keyboard should be shown
* when text input is active
*
* The variable can be set to the following values:
*
* - "0": Do not show the on-screen keyboard
* - "1": Show the on-screen keyboard
*
* The default value is "1". This hint must be set before text input is
* activated.
*/
#define SDL_HINT_ENABLE_SCREEN_KEYBOARD "SDL_ENABLE_SCREEN_KEYBOARD"
/**
* A variable controlling verbosity of the logging of SDL events pushed onto
* the internal queue.
*
* This variable can be set to the following values, from least to most
* verbose:
*
* - "0": Don't log any events (default)
* - "1": Log most events (other than the really spammy ones).
* - "2": Include mouse and finger motion events.
* - "3": Include SDL_SysWMEvent events.
*
* This is generally meant to be used to debug SDL itself, but can be useful
* for application developers that need better visibility into what is going
* on in the event queue. Logged events are sent through SDL_Log(), which
* means by default they appear on stdout on most platforms or maybe
* OutputDebugString() on Windows, and can be funneled by the app with
* SDL_LogSetOutputFunction(), etc.
*
* This hint can be toggled on and off at runtime, if you only need to log
* events for a small subset of program execution.
*/
#define SDL_HINT_EVENT_LOGGING "SDL_EVENT_LOGGING"
/**
* A variable controlling whether raising the window should be done more
* forcefully
*
* This variable can be set to the following values:
*
* - "0": No forcing (the default)
* - "1": Extra level of forcing
*
* At present, this is only an issue under MS Windows, which makes it nearly
* impossible to programmatically move a window to the foreground, for
* "security" reasons. See http://stackoverflow.com/a/34414846 for a
* discussion.
*/
#define SDL_HINT_FORCE_RAISEWINDOW "SDL_HINT_FORCE_RAISEWINDOW"
/**
* A variable controlling how 3D acceleration is used to accelerate the SDL
* screen surface.
*
* SDL can try to accelerate the SDL screen surface by using streaming
* textures with a 3D rendering engine. This variable controls whether and how
* this is done.
*
* This variable can be set to the following values:
*
* - "0": Disable 3D acceleration
* - "1": Enable 3D acceleration, using the default renderer.
* - "X": Enable 3D acceleration, using X where X is one of the valid
* rendering drivers. (e.g. "direct3d", "opengl", etc.)
*
* By default SDL tries to make a best guess for each platform whether to use
* acceleration or not.
*/
#define SDL_HINT_FRAMEBUFFER_ACCELERATION "SDL_FRAMEBUFFER_ACCELERATION"
/**
* A variable that lets you manually hint extra gamecontroller db entries.
*
* The variable should be newline delimited rows of gamecontroller config
* data, see SDL_gamecontroller.h
*
* This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER) You
* can update mappings after the system is initialized with
* SDL_GameControllerMappingForGUID() and SDL_GameControllerAddMapping()
*/
#define SDL_HINT_GAMECONTROLLERCONFIG "SDL_GAMECONTROLLERCONFIG"
/**
* A variable that lets you provide a file with extra gamecontroller db
* entries.
*
* The file should contain lines of gamecontroller config data, see
* SDL_gamecontroller.h
*
* This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER) You
* can update mappings after the system is initialized with
* SDL_GameControllerMappingForGUID() and SDL_GameControllerAddMapping()
*/
#define SDL_HINT_GAMECONTROLLERCONFIG_FILE "SDL_GAMECONTROLLERCONFIG_FILE"
/**
* A variable that overrides the automatic controller type detection
*
* The variable should be comma separated entries, in the form: VID/PID=type
*
* The VID and PID should be hexadecimal with exactly 4 digits, e.g. 0x00fd
*
* The type should be one of: Xbox360 XboxOne PS3 PS4 PS5 SwitchPro
*
* This hint affects what driver is used, and must be set before calling
* SDL_Init(SDL_INIT_GAMECONTROLLER)
*/
#define SDL_HINT_GAMECONTROLLERTYPE "SDL_GAMECONTROLLERTYPE"
/**
* A variable containing a list of devices to skip when scanning for game
* controllers.
*
* The format of the string is a comma separated list of USB VID/PID pairs in
* hexadecimal form, e.g.
*
* 0xAAAA/0xBBBB,0xCCCC/0xDDDD
*
* The variable can also take the form of @file, in which case the named file
* will be loaded and interpreted as the value of the variable.
*/
#define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES "SDL_GAMECONTROLLER_IGNORE_DEVICES"
/**
* If set, all devices will be skipped when scanning for game controllers
* except for the ones listed in this variable.
*
* The format of the string is a comma separated list of USB VID/PID pairs in
* hexadecimal form, e.g.
*
* 0xAAAA/0xBBBB,0xCCCC/0xDDDD
*
* The variable can also take the form of @file, in which case the named file
* will be loaded and interpreted as the value of the variable.
*/
#define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT "SDL_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT"
/**
* If set, game controller face buttons report their values according to their
* labels instead of their positional layout.
*
* For example, on Nintendo Switch controllers, normally you'd get:
*
* ```
* (Y)
* (X) (B)
* (A)
* ```
*
* but if this hint is set, you'll get:
*
* ```
* (X)
* (Y) (A)
* (B)
* ```
*
* The variable can be set to the following values:
*
* - "0": Report the face buttons by position, as though they were on an Xbox
* controller.
* - "1": Report the face buttons by label instead of position
*
* The default value is "1". This hint may be set at any time.
*/
#define SDL_HINT_GAMECONTROLLER_USE_BUTTON_LABELS "SDL_GAMECONTROLLER_USE_BUTTON_LABELS"
/**
* A variable controlling whether grabbing input grabs the keyboard
*
* This variable can be set to the following values:
*
* - "0": Grab will affect only the mouse
* - "1": Grab will affect mouse and keyboard
*
* By default SDL will not grab the keyboard so system shortcuts still work.
*/
#define SDL_HINT_GRAB_KEYBOARD "SDL_GRAB_KEYBOARD"
/**
* A variable containing a list of devices to ignore in SDL_hid_enumerate()
*
* For example, to ignore the Shanwan DS3 controller and any Valve controller,
* you might have the string "0x2563/0x0523,0x28de/0x0000"
*/
#define SDL_HINT_HIDAPI_IGNORE_DEVICES "SDL_HIDAPI_IGNORE_DEVICES"
/**
* A variable controlling whether the idle timer is disabled on iOS.
*
* When an iOS app does not receive touches for some time, the screen is
* dimmed automatically. For games where the accelerometer is the only input
* this is problematic. This functionality can be disabled by setting this
* hint.
*
* As of SDL 2.0.4, SDL_EnableScreenSaver() and SDL_DisableScreenSaver()
* accomplish the same thing on iOS. They should be preferred over this hint.
*
* This variable can be set to the following values:
*
* - "0": Enable idle timer
* - "1": Disable idle timer
*/
#define SDL_HINT_IDLE_TIMER_DISABLED "SDL_IOS_IDLE_TIMER_DISABLED"
/**
* A variable to control whether certain IMEs should handle text editing
* internally instead of sending SDL_TEXTEDITING events.
*
* The variable can be set to the following values:
*
* - "0": SDL_TEXTEDITING events are sent, and it is the application's
* responsibility to render the text from these events and differentiate it
* somehow from committed text. (default)
* - "1": If supported by the IME then SDL_TEXTEDITING events are not sent,
* and text that is being composed will be rendered in its own UI.
*/
#define SDL_HINT_IME_INTERNAL_EDITING "SDL_IME_INTERNAL_EDITING"
/**
* A variable to control whether certain IMEs should show native UI components
* (such as the Candidate List) instead of suppressing them.
*
* The variable can be set to the following values:
*
* - "0": Native UI components are not display. (default)
* - "1": Native UI components are displayed.
*/
#define SDL_HINT_IME_SHOW_UI "SDL_IME_SHOW_UI"
/**
* A variable to control if extended IME text support is enabled.
*
* If enabled then SDL_TextEditingExtEvent will be issued if the text would be
* truncated otherwise. Additionally SDL_TextInputEvent will be dispatched
* multiple times so that it is not truncated.
*
* The variable can be set to the following values:
*
* - "0": Legacy behavior. Text can be truncated, no heap allocations.
* (default)
* - "1": Modern behavior.
*/
#define SDL_HINT_IME_SUPPORT_EXTENDED_TEXT "SDL_IME_SUPPORT_EXTENDED_TEXT"
/**
* A variable controlling whether the home indicator bar on iPhone X should be
* hidden.
*
* This variable can be set to the following values:
*
* - "0": The indicator bar is not hidden (default for windowed applications)
* - "1": The indicator bar is hidden and is shown when the screen is touched
* (useful for movie playback applications)
* - "2": The indicator bar is dim and the first swipe makes it visible and
* the second swipe performs the "home" action (default for fullscreen
* applications)
*/
#define SDL_HINT_IOS_HIDE_HOME_INDICATOR "SDL_IOS_HIDE_HOME_INDICATOR"
/**
* A variable that lets you enable joystick (and gamecontroller) events even
* when your app is in the background.
*
* The variable can be set to the following values:
*
* - "0": Disable joystick & gamecontroller input events when the application
* is in the background.
* - "1": Enable joystick & gamecontroller input events when the application
* is in the background.
*
* The default value is "0". This hint may be set at any time.
*/
#define SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS "SDL_JOYSTICK_ALLOW_BACKGROUND_EVENTS"
/**
* A variable containing a list of arcade stick style controllers.
*
* The format of the string is a comma separated list of USB VID/PID pairs in
* hexadecimal form, e.g.
*
* 0xAAAA/0xBBBB,0xCCCC/0xDDDD
*
* The variable can also take the form of @file, in which case the named file
* will be loaded and interpreted as the value of the variable.
*/
#define SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES "SDL_JOYSTICK_ARCADESTICK_DEVICES"
/**
* A variable containing a list of devices that are not arcade stick style
* controllers.
*
* This will override SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES and the built in
* device list.
*
* The format of the string is a comma separated list of USB VID/PID pairs in
* hexadecimal form, e.g.
*
* 0xAAAA/0xBBBB,0xCCCC/0xDDDD
*
* The variable can also take the form of @file, in which case the named file
* will be loaded and interpreted as the value of the variable.
*/
#define SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED "SDL_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED"
/**
* A variable containing a list of devices that should not be considerd
* joysticks.
*
* The format of the string is a comma separated list of USB VID/PID pairs in
* hexadecimal form, e.g.
*
* 0xAAAA/0xBBBB,0xCCCC/0xDDDD
*
* The variable can also take the form of @file, in which case the named file
* will be loaded and interpreted as the value of the variable.
*/
#define SDL_HINT_JOYSTICK_BLACKLIST_DEVICES "SDL_JOYSTICK_BLACKLIST_DEVICES"
/**
* A variable containing a list of devices that should be considered
* joysticks.
*
* This will override SDL_HINT_JOYSTICK_BLACKLIST_DEVICES and the built in
* device list.
*
* The format of the string is a comma separated list of USB VID/PID pairs in
* hexadecimal form, e.g.
*
* 0xAAAA/0xBBBB,0xCCCC/0xDDDD
*
* The variable can also take the form of @file, in which case the named file
* will be loaded and interpreted as the value of the variable.
*/
#define SDL_HINT_JOYSTICK_BLACKLIST_DEVICES_EXCLUDED "SDL_JOYSTICK_BLACKLIST_DEVICES_EXCLUDED"
/**
* A variable containing a list of flightstick style controllers.
*
* The format of the string is a comma separated list of USB VID/PID pairs in
* hexadecimal form, e.g.
*
* 0xAAAA/0xBBBB,0xCCCC/0xDDDD
*
* The variable can also take the form of @file, in which case the named file
* will be loaded and interpreted as the value of the variable.
*/
#define SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES "SDL_JOYSTICK_FLIGHTSTICK_DEVICES"
/**
* A variable containing a list of devices that are not flightstick style
* controllers.
*
* This will override SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES and the built in
* device list.
*
* The format of the string is a comma separated list of USB VID/PID pairs in
* hexadecimal form, e.g.
*
* 0xAAAA/0xBBBB,0xCCCC/0xDDDD
*
* The variable can also take the form of @file, in which case the named file
* will be loaded and interpreted as the value of the variable.
*/
#define SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED "SDL_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED"
/**
* A variable containing a list of devices known to have a GameCube form
* factor.
*
* The format of the string is a comma separated list of USB VID/PID pairs in
* hexadecimal form, e.g.
*
* 0xAAAA/0xBBBB,0xCCCC/0xDDDD
*
* The variable can also take the form of @file, in which case the named file
* will be loaded and interpreted as the value of the variable.
*/
#define SDL_HINT_JOYSTICK_GAMECUBE_DEVICES "SDL_JOYSTICK_GAMECUBE_DEVICES"
/**
* A variable containing a list of devices known not to have a GameCube form
* factor.
*
* This will override SDL_HINT_JOYSTICK_GAMECUBE_DEVICES and the built in
* device list.
*
* The format of the string is a comma separated list of USB VID/PID pairs in
* hexadecimal form, e.g.
*
* 0xAAAA/0xBBBB,0xCCCC/0xDDDD
*
* The variable can also take the form of @file, in which case the named file
* will be loaded and interpreted as the value of the variable.
*/
#define SDL_HINT_JOYSTICK_GAMECUBE_DEVICES_EXCLUDED "SDL_JOYSTICK_GAMECUBE_DEVICES_EXCLUDED"
/**
* A variable controlling whether the HIDAPI joystick drivers should be used.
*
* This variable can be set to the following values:
*
* - "0": HIDAPI drivers are not used
* - "1": HIDAPI drivers are used (the default)
*
* This variable is the default for all drivers, but can be overridden by the
* hints for specific drivers below.
*/
#define SDL_HINT_JOYSTICK_HIDAPI "SDL_JOYSTICK_HIDAPI"
/**
* A variable controlling whether the HIDAPI driver for Nintendo GameCube
* controllers should be used.
*
* This variable can be set to the following values:
*
* - "0": HIDAPI driver is not used
* - "1": HIDAPI driver is used
*
* The default is the value of SDL_HINT_JOYSTICK_HIDAPI
*/
#define SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE "SDL_JOYSTICK_HIDAPI_GAMECUBE"
/**
* A variable controlling whether "low_frequency_rumble" and
* "high_frequency_rumble" is used to implement the GameCube controller's 3
* rumble modes, Stop(0), Rumble(1), and StopHard(2) this is useful for
* applications that need full compatibility for things like ADSR envelopes.
*
* Stop is implemented by setting "low_frequency_rumble" to "0" and
* "high_frequency_rumble" ">0" Rumble is both at any arbitrary value,
* StopHard is implemented by setting both "low_frequency_rumble" and
* "high_frequency_rumble" to "0"
*
* This variable can be set to the following values:
*
* - "0": Normal rumble behavior is behavior is used (default)
* - "1": Proper GameCube controller rumble behavior is used
*/
#define SDL_HINT_JOYSTICK_GAMECUBE_RUMBLE_BRAKE "SDL_JOYSTICK_GAMECUBE_RUMBLE_BRAKE"
/**
* A variable controlling whether the HIDAPI driver for Nintendo Switch
* Joy-Cons should be used.
*
* This variable can be set to the following values:
*
* - "0": HIDAPI driver is not used
* - "1": HIDAPI driver is used
*
* The default is the value of SDL_HINT_JOYSTICK_HIDAPI
*/
#define SDL_HINT_JOYSTICK_HIDAPI_JOY_CONS "SDL_JOYSTICK_HIDAPI_JOY_CONS"
/**
* A variable controlling whether Nintendo Switch Joy-Con controllers will be
* combined into a single Pro-like controller when using the HIDAPI driver
*
* This variable can be set to the following values:
*
* - "0": Left and right Joy-Con controllers will not be combined and each
* will be a mini-gamepad
* - "1": Left and right Joy-Con controllers will be combined into a single
* controller (the default)
*/
#define SDL_HINT_JOYSTICK_HIDAPI_COMBINE_JOY_CONS "SDL_JOYSTICK_HIDAPI_COMBINE_JOY_CONS"
/**
* A variable controlling whether Nintendo Switch Joy-Con controllers will be
* in vertical mode when using the HIDAPI driver
*
* This variable can be set to the following values:
*
* - "0": Left and right Joy-Con controllers will not be in vertical mode (the
* default)
* - "1": Left and right Joy-Con controllers will be in vertical mode
*
* This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER)
*/
#define SDL_HINT_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS "SDL_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS"
/**
* A variable controlling whether the HIDAPI driver for Amazon Luna
* controllers connected via Bluetooth should be used.
*
* This variable can be set to the following values:
*
* - "0": HIDAPI driver is not used
* - "1": HIDAPI driver is used
*
* The default is the value of SDL_HINT_JOYSTICK_HIDAPI
*/
#define SDL_HINT_JOYSTICK_HIDAPI_LUNA "SDL_JOYSTICK_HIDAPI_LUNA"
/**
* A variable controlling whether the HIDAPI driver for Nintendo Online
* classic controllers should be used.
*
* This variable can be set to the following values:
*
* - "0": HIDAPI driver is not used
* - "1": HIDAPI driver is used
*
* The default is the value of SDL_HINT_JOYSTICK_HIDAPI
*/
#define SDL_HINT_JOYSTICK_HIDAPI_NINTENDO_CLASSIC "SDL_JOYSTICK_HIDAPI_NINTENDO_CLASSIC"
/**
* A variable controlling whether the HIDAPI driver for NVIDIA SHIELD
* controllers should be used.
*
* This variable can be set to the following values:
*
* - "0": HIDAPI driver is not used
* - "1": HIDAPI driver is used
*
* The default is the value of SDL_HINT_JOYSTICK_HIDAPI
*/
#define SDL_HINT_JOYSTICK_HIDAPI_SHIELD "SDL_JOYSTICK_HIDAPI_SHIELD"
/**
* A variable controlling whether the HIDAPI driver for PS3 controllers should
* be used.
*
* This variable can be set to the following values:
*
* - "0": HIDAPI driver is not used
* - "1": HIDAPI driver is used
*
* The default is the value of SDL_HINT_JOYSTICK_HIDAPI on macOS, and "0" on
* other platforms.
*
* It is not possible to use this driver on Windows, due to limitations in the
* default drivers installed. See https://github.com/ViGEm/DsHidMini for an
* alternative driver on Windows.
*/
#define SDL_HINT_JOYSTICK_HIDAPI_PS3 "SDL_JOYSTICK_HIDAPI_PS3"
/**
* A variable controlling whether the HIDAPI driver for PS4 controllers should
* be used.
*
* This variable can be set to the following values:
*
* - "0": HIDAPI driver is not used
* - "1": HIDAPI driver is used
*
* The default is the value of SDL_HINT_JOYSTICK_HIDAPI
*/
#define SDL_HINT_JOYSTICK_HIDAPI_PS4 "SDL_JOYSTICK_HIDAPI_PS4"
/**
* A variable controlling whether extended input reports should be used for
* PS4 controllers when using the HIDAPI driver.
*
* This variable can be set to the following values:
*
* - "0": extended reports are not enabled (the default)
* - "1": extended reports
*
* Extended input reports allow rumble on Bluetooth PS4 controllers, but break
* DirectInput handling for applications that don't use SDL.
*
* Once extended reports are enabled, they can not be disabled without power
* cycling the controller.
*
* For compatibility with applications written for versions of SDL prior to
* the introduction of PS5 controller support, this value will also control
* the state of extended reports on PS5 controllers when the
* SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE hint is not explicitly set.
*/
#define SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE "SDL_JOYSTICK_HIDAPI_PS4_RUMBLE"
/**
* A variable controlling whether the HIDAPI driver for PS5 controllers should
* be used.
*
* This variable can be set to the following values:
*
* - "0": HIDAPI driver is not used
* - "1": HIDAPI driver is used