1 /* 2 DSDL 3 Copyright (C) 2025 Inochi2D Project <luna@foxgirls.gay> 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 Simple DirectMedia Layer 24 Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org> 25 26 This software is provided 'as-is', without any express or implied 27 warranty. In no event will the authors be held liable for any damages 28 arising from the use of this software. 29 30 Permission is granted to anyone to use this software for any purpose, 31 including commercial applications, and to alter it and redistribute it 32 freely, subject to the following restrictions: 33 34 1. The origin of this software must not be misrepresented; you must not 35 claim that you wrote the original software. If you use this software 36 in a product, an acknowledgment in the product documentation would be 37 appreciated but is not required. 38 2. Altered source versions must be plainly marked as such, and must not be 39 misrepresented as being the original software. 40 3. This notice may not be removed or altered from any source distribution. 41 */ 42 43 /** 44 SDL Haptic 45 46 See_Also: 47 $(LINK2 https://wiki.libsdl.org/SDL3/CategoryHaptic, SDL3 Haptic Documentation) 48 49 Copyright: © 2025 Inochi2D Project, © 1997-2025 Sam Lantinga 50 License: Subject to the terms of the Zlib License, as written in the LICENSE file. 51 Authors: 52 Luna Nielsen 53 */ 54 module sdl.haptic; 55 import sdl.joystick; 56 import sdl.stdc; 57 58 extern (C) nothrow @nogc: 59 60 /** 61 The haptic structure used to identify an SDL haptic. 62 63 See_Also: 64 $(D SDL_OpenHaptic) 65 $(D SDL_OpenHapticFromJoystick) 66 $(D SDL_CloseHaptic) 67 */ 68 struct SDL_Haptic; 69 70 71 /** 72 Used to play a device an infinite number of times. 73 74 \sa SDL_RunHapticEffect 75 */ 76 enum SDL_HAPTIC_INFINITY = 4294967295U; 77 78 79 /** 80 Type of haptic effect. 81 */ 82 alias SDL_HapticEffectType = Uint16; 83 84 /** 85 Constant effect supported. 86 87 Constant haptic effect. 88 89 \sa SDL_HapticCondition 90 */ 91 enum SDL_HAPTIC_CONSTANT = (1u<<0); 92 93 /** 94 Sine wave effect supported. 95 96 Periodic haptic effect that simulates sine waves. 97 98 \sa SDL_HapticPeriodic 99 */ 100 enum SDL_HAPTIC_SINE = (1u<<1); 101 102 /** 103 Square wave effect supported. 104 105 Periodic haptic effect that simulates square waves. 106 107 \sa SDL_HapticPeriodic 108 */ 109 enum SDL_HAPTIC_SQUARE = (1u<<2); 110 111 /** 112 Triangle wave effect supported. 113 114 Periodic haptic effect that simulates triangular waves. 115 116 \sa SDL_HapticPeriodic 117 */ 118 enum SDL_HAPTIC_TRIANGLE = (1u<<3); 119 120 /** 121 Sawtoothup wave effect supported. 122 123 Periodic haptic effect that simulates saw tooth up waves. 124 125 \sa SDL_HapticPeriodic 126 */ 127 enum SDL_HAPTIC_SAWTOOTHUP = (1u<<4); 128 129 /** 130 Sawtoothdown wave effect supported. 131 132 Periodic haptic effect that simulates saw tooth down waves. 133 134 \sa SDL_HapticPeriodic 135 */ 136 enum SDL_HAPTIC_SAWTOOTHDOWN = (1u<<5); 137 138 /** 139 Ramp effect supported. 140 141 Ramp haptic effect. 142 143 \sa SDL_HapticRamp 144 */ 145 enum SDL_HAPTIC_RAMP = (1u<<6); 146 147 /** 148 Spring effect supported - uses axes position. 149 150 Condition haptic effect that simulates a spring. Effect is based on the 151 axes position. 152 153 \sa SDL_HapticCondition 154 */ 155 enum SDL_HAPTIC_SPRING = (1u<<7); 156 157 /** 158 Damper effect supported - uses axes velocity. 159 160 Condition haptic effect that simulates dampening. Effect is based on the 161 axes velocity. 162 163 \sa SDL_HapticCondition 164 */ 165 enum SDL_HAPTIC_DAMPER = (1u<<8); 166 167 /** 168 Inertia effect supported - uses axes acceleration. 169 170 Condition haptic effect that simulates inertia. Effect is based on the axes 171 acceleration. 172 173 \sa SDL_HapticCondition 174 */ 175 enum SDL_HAPTIC_INERTIA = (1u<<9); 176 177 /** 178 Friction effect supported - uses axes movement. 179 180 Condition haptic effect that simulates friction. Effect is based on the 181 axes movement. 182 183 \sa SDL_HapticCondition 184 */ 185 enum SDL_HAPTIC_FRICTION = (1u<<10); 186 187 /** 188 Left/Right effect supported. 189 190 Haptic effect for direct control over high/low frequency motors. 191 192 \sa SDL_HapticLeftRight 193 */ 194 enum SDL_HAPTIC_LEFTRIGHT = (1u<<11); 195 196 /** 197 Reserved for future use. 198 */ 199 enum SDL_HAPTIC_RESERVED1 = (1u<<12); 200 201 /** 202 Reserved for future use. 203 */ 204 enum SDL_HAPTIC_RESERVED2 = (1u<<13); 205 206 /** 207 Reserved for future use. 208 */ 209 enum SDL_HAPTIC_RESERVED3 = (1u<<14); 210 211 /** 212 Custom effect is supported. 213 214 User defined custom haptic effect. 215 */ 216 enum SDL_HAPTIC_CUSTOM = (1u<<15); 217 218 /** 219 Device can set global gain. 220 221 Device supports setting the global gain. 222 223 \sa SDL_SetHapticGain 224 */ 225 enum SDL_HAPTIC_GAIN = (1u<<16); 226 227 /** 228 Device can set autocenter. 229 230 Device supports setting autocenter. 231 232 \sa SDL_SetHapticAutocenter 233 */ 234 enum SDL_HAPTIC_AUTOCENTER = (1u<<17); 235 236 /** 237 Device can be queried for effect status. 238 239 Device supports querying effect status. 240 241 \sa SDL_GetHapticEffectStatus 242 */ 243 enum SDL_HAPTIC_STATUS = (1u<<18); 244 245 /** 246 Device can be paused. 247 248 Devices supports being paused. 249 250 \sa SDL_PauseHaptic 251 \sa SDL_ResumeHaptic 252 */ 253 enum SDL_HAPTIC_PAUSE = (1u<<19); 254 255 /** 256 Type of coordinates used for haptic direction. 257 */ 258 alias SDL_HapticDirectionType = Uint8; 259 260 /** 261 Uses polar coordinates for the direction. 262 263 \sa SDL_HapticDirection 264 */ 265 enum SDL_HAPTIC_POLAR = 0; 266 267 /** 268 Uses cartesian coordinates for the direction. 269 270 \sa SDL_HapticDirection 271 */ 272 enum SDL_HAPTIC_CARTESIAN = 1; 273 274 /** 275 Uses spherical coordinates for the direction. 276 277 \sa SDL_HapticDirection 278 */ 279 enum SDL_HAPTIC_SPHERICAL = 2; 280 281 /** 282 Use this value to play an effect on the steering wheel axis. 283 284 This provides better compatibility across platforms and devices as SDL will 285 guess the correct axis. 286 287 \sa SDL_HapticDirection 288 */ 289 enum SDL_HAPTIC_STEERING_AXIS = 3; 290 291 /** 292 ID for haptic effects. 293 294 This is -1 if the ID is invalid. 295 296 \sa SDL_CreateHapticEffect 297 */ 298 alias SDL_HapticEffectID = int; 299 300 301 /** 302 Structure that represents a haptic direction. 303 304 This is the direction where the force comes from, instead of the direction 305 in which the force is exerted. 306 307 Directions can be specified by: 308 309 - SDL_HAPTIC_POLAR : Specified by polar coordinates. 310 - SDL_HAPTIC_CARTESIAN : Specified by cartesian coordinates. 311 - SDL_HAPTIC_SPHERICAL : Specified by spherical coordinates. 312 313 Cardinal directions of the haptic device are relative to the positioning of 314 the device. North is considered to be away from the user. 315 316 The following diagram represents the cardinal directions: 317 318 ``` 319 .--. 320 |__| .-------. 321 |=.| |.-----.| 322 |--| || || 323 | | |'-----'| 324 |__|~')_____(' 325 [ COMPUTER ] 326 327 328 North (0,-1) 329 ^ 330 | 331 | 332 (-1,0) West <----[ HAPTIC ]----> East (1,0) 333 | 334 | 335 v 336 South (0,1) 337 338 339 [ USER ] 340 \|||/ 341 (o o) 342 ---ooO-(_)-Ooo--- 343 ``` 344 345 If type is SDL_HAPTIC_POLAR, direction is encoded by hundredths of a degree 346 starting north and turning clockwise. SDL_HAPTIC_POLAR only uses the first 347 `dir` parameter. The cardinal directions would be: 348 349 - North: 0 (0 degrees) 350 - East: 9000 (90 degrees) 351 - South: 18000 (180 degrees) 352 - West: 27000 (270 degrees) 353 354 If type is SDL_HAPTIC_CARTESIAN, direction is encoded by three positions (X 355 axis, Y axis and Z axis (with 3 axes)). SDL_HAPTIC_CARTESIAN uses the first 356 three `dir` parameters. The cardinal directions would be: 357 358 - North: 0,-1, 0 359 - East: 1, 0, 0 360 - South: 0, 1, 0 361 - West: -1, 0, 0 362 363 The Z axis represents the height of the effect if supported, otherwise it's 364 unused. In cartesian encoding (1, 2) would be the same as (2, 4), you can 365 use any multiple you want, only the direction matters. 366 367 If type is SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations. The 368 first two `dir` parameters are used. The `dir` parameters are as follows 369 (all values are in hundredths of degrees): 370 371 - Degrees from (1, 0) rotated towards (0, 1). 372 - Degrees towards (0, 0, 1) (device needs at least 3 axes). 373 374 Example of force coming from the south with all encodings (force coming 375 from the south means the user will have to pull the stick to counteract): 376 377 ```c 378 SDL_HapticDirection direction; 379 380 // Cartesian directions 381 direction.type = SDL_HAPTIC_CARTESIAN; // Using cartesian direction encoding. 382 direction.dir[0] = 0; // X position 383 direction.dir[1] = 1; // Y position 384 // Assuming the device has 2 axes, we don't need to specify third parameter. 385 386 // Polar directions 387 direction.type = SDL_HAPTIC_POLAR; // We'll be using polar direction encoding. 388 direction.dir[0] = 18000; // Polar only uses first parameter 389 390 // Spherical coordinates 391 direction.type = SDL_HAPTIC_SPHERICAL; // Spherical encoding 392 direction.dir[0] = 9000; // Since we only have two axes we don't need more parameters. 393 ``` 394 395 \since This struct is available since SDL 3.2.0. 396 397 \sa SDL_HAPTIC_POLAR 398 \sa SDL_HAPTIC_CARTESIAN 399 \sa SDL_HAPTIC_SPHERICAL 400 \sa SDL_HAPTIC_STEERING_AXIS 401 \sa SDL_HapticEffect 402 \sa SDL_GetNumHapticAxes 403 */ 404 struct SDL_HapticDirection { 405 406 /** 407 The type of encoding. 408 */ 409 SDL_HapticDirectionType type; 410 411 /** 412 The encoded direction. 413 */ 414 Sint32[3] dir; 415 } 416 417 418 /** 419 A structure containing a template for a Constant effect. 420 421 This struct is exclusively for the SDL_HAPTIC_CONSTANT effect. 422 423 A constant effect applies a constant force in the specified direction to 424 the joystick. 425 426 \since This struct is available since SDL 3.2.0. 427 428 \sa SDL_HAPTIC_CONSTANT 429 \sa SDL_HapticEffect 430 */ 431 struct SDL_HapticConstant { 432 433 /** 434 SDL_HAPTIC_CONSTANT 435 */ 436 SDL_HapticEffectType type = SDL_HAPTIC_CONSTANT; 437 438 /** 439 Direction of the effect. 440 */ 441 SDL_HapticDirection direction; 442 443 /** 444 Duration of the effect. 445 */ 446 Uint32 length; 447 448 /** 449 Delay before starting the effect. 450 */ 451 Uint16 delay; 452 453 /** 454 Button that triggers the effect. 455 */ 456 Uint16 button; 457 458 /** 459 How soon it can be triggered again after button. 460 */ 461 Uint16 interval; 462 463 /** 464 Strength of the constant effect. 465 */ 466 Sint16 level; 467 468 /** 469 Duration of the attack. 470 */ 471 Uint16 attack_length; 472 473 /** 474 Level at the start of the attack. 475 */ 476 Uint16 attack_level; 477 478 /** 479 Duration of the fade. 480 */ 481 Uint16 fade_length; 482 483 /** 484 Level at the end of the fade. 485 */ 486 Uint16 fade_level; 487 } 488 489 /** 490 A structure containing a template for a Periodic effect. 491 492 The struct handles the following effects: 493 494 - SDL_HAPTIC_SINE 495 - SDL_HAPTIC_SQUARE 496 - SDL_HAPTIC_TRIANGLE 497 - SDL_HAPTIC_SAWTOOTHUP 498 - SDL_HAPTIC_SAWTOOTHDOWN 499 500 A periodic effect consists in a wave-shaped effect that repeats itself over 501 time. The type determines the shape of the wave and the parameters 502 determine the dimensions of the wave. 503 504 Phase is given by hundredth of a degree meaning that giving the phase a 505 value of 9000 will displace it 25% of its period. Here are sample values: 506 507 - 0: No phase displacement. 508 - 9000: Displaced 25% of its period. 509 - 18000: Displaced 50% of its period. 510 - 27000: Displaced 75% of its period. 511 - 36000: Displaced 100% of its period, same as 0, but 0 is preferred. 512 513 Examples: 514 515 ``` 516 SDL_HAPTIC_SINE 517 __ __ __ __ 518 / \ / \ / \ / 519 / \__/ \__/ \__/ 520 521 SDL_HAPTIC_SQUARE 522 __ __ __ __ __ 523 | | | | | | | | | | 524 | |__| |__| |__| |__| | 525 526 SDL_HAPTIC_TRIANGLE 527 /\ /\ /\ /\ /\ 528 / \ / \ / \ / \ / 529 / \/ \/ \/ \/ 530 531 SDL_HAPTIC_SAWTOOTHUP 532 /| /| /| /| /| /| /| 533 / | / | / | / | / | / | / | 534 / |/ |/ |/ |/ |/ |/ | 535 536 SDL_HAPTIC_SAWTOOTHDOWN 537 \ |\ |\ |\ |\ |\ |\ | 538 \ | \ | \ | \ | \ | \ | \ | 539 \| \| \| \| \| \| \| 540 ``` 541 542 \since This struct is available since SDL 3.2.0. 543 544 \sa SDL_HAPTIC_SINE 545 \sa SDL_HAPTIC_SQUARE 546 \sa SDL_HAPTIC_TRIANGLE 547 \sa SDL_HAPTIC_SAWTOOTHUP 548 \sa SDL_HAPTIC_SAWTOOTHDOWN 549 \sa SDL_HapticEffect 550 */ 551 struct SDL_HapticPeriodic { 552 553 /** 554 SDL_HAPTIC_SINE, SDL_HAPTIC_SQUARE SDL_HAPTIC_TRIANGLE, SDL_HAPTIC_SAWTOOTHUP or SDL_HAPTIC_SAWTOOTHDOWN 555 */ 556 SDL_HapticEffectType type; 557 558 /** 559 Direction of the effect. 560 */ 561 SDL_HapticDirection direction; 562 563 /** 564 Duration of the effect. 565 */ 566 Uint32 length; 567 568 /** 569 Delay before starting the effect. 570 */ 571 Uint16 delay; 572 573 /** 574 Button that triggers the effect. 575 */ 576 Uint16 button; 577 578 /** 579 How soon it can be triggered again after button. 580 */ 581 Uint16 interval; 582 583 /** 584 Period of the wave. 585 */ 586 Uint16 period; 587 588 /** 589 Peak value; if negative, equivalent to 180 degrees extra phase shift. 590 */ 591 Sint16 magnitude; 592 593 /** 594 Mean value of the wave. 595 */ 596 Sint16 offset; 597 598 /** 599 Positive phase shift given by hundredth of a degree. 600 */ 601 Uint16 phase; 602 603 /** 604 Duration of the attack. 605 */ 606 Uint16 attack_length; 607 608 /** 609 Level at the start of the attack. 610 */ 611 Uint16 attack_level; 612 613 /** 614 Duration of the fade. 615 */ 616 Uint16 fade_length; 617 618 /** 619 Level at the end of the fade. 620 */ 621 Uint16 fade_level; 622 } 623 624 /** 625 A structure containing a template for a Condition effect. 626 627 The struct handles the following effects: 628 629 - SDL_HAPTIC_SPRING: Effect based on axes position. 630 - SDL_HAPTIC_DAMPER: Effect based on axes velocity. 631 - SDL_HAPTIC_INERTIA: Effect based on axes acceleration. 632 - SDL_HAPTIC_FRICTION: Effect based on axes movement. 633 634 Direction is handled by condition internals instead of a direction member. 635 The condition effect specific members have three parameters. The first 636 refers to the X axis, the second refers to the Y axis and the third refers 637 to the Z axis. The right terms refer to the positive side of the axis and 638 the left terms refer to the negative side of the axis. Please refer to the 639 SDL_HapticDirection diagram for which side is positive and which is 640 negative. 641 642 \since This struct is available since SDL 3.2.0. 643 644 \sa SDL_HapticDirection 645 \sa SDL_HAPTIC_SPRING 646 \sa SDL_HAPTIC_DAMPER 647 \sa SDL_HAPTIC_INERTIA 648 \sa SDL_HAPTIC_FRICTION 649 \sa SDL_HapticEffect 650 */ 651 struct SDL_HapticCondition { 652 653 /** 654 SDL_HAPTIC_SPRING, SDL_HAPTIC_DAMPER, SDL_HAPTIC_INERTIA or SDL_HAPTIC_FRICTION 655 */ 656 SDL_HapticEffectType type; 657 658 /** 659 Direction of the effect. 660 */ 661 SDL_HapticDirection direction; 662 663 /** 664 Duration of the effect. 665 */ 666 Uint32 length; 667 668 /** 669 Delay before starting the effect. 670 */ 671 Uint16 delay; 672 673 /** 674 Button that triggers the effect. 675 */ 676 Uint16 button; 677 678 /** 679 How soon it can be triggered again after button. 680 */ 681 Uint16 interval; 682 683 /** 684 Level when joystick is to the positive side; max 0xFFFF. 685 */ 686 Uint16[3] right_sat; 687 688 /** 689 Level when joystick is to the negative side; max 0xFFFF. 690 */ 691 Uint16[3] left_sat; 692 693 /** 694 How fast to increase the force towards the positive side. 695 */ 696 Sint16[3] right_coeff; 697 698 /** 699 How fast to increase the force towards the negative side. 700 */ 701 Sint16[3] left_coeff; 702 703 /** 704 Size of the dead zone; max 0xFFFF: whole axis-range when 0-centered. 705 */ 706 Uint16[3] deadband; 707 708 /** 709 Position of the dead zone. 710 */ 711 Sint16[3] center; 712 } 713 714 /** 715 A structure containing a template for a Ramp effect. 716 717 This struct is exclusively for the SDL_HAPTIC_RAMP effect. 718 719 The ramp effect starts at start strength and ends at end strength. It 720 augments in linear fashion. If you use attack and fade with a ramp the 721 effects get added to the ramp effect making the effect become quadratic 722 instead of linear. 723 724 \since This struct is available since SDL 3.2.0. 725 726 \sa SDL_HAPTIC_RAMP 727 \sa SDL_HapticEffect 728 */ 729 struct SDL_HapticRamp { 730 731 /** 732 SDL_HAPTIC_RAMP 733 */ 734 SDL_HapticEffectType type = SDL_HAPTIC_RAMP; 735 736 /** 737 Direction of the effect. 738 */ 739 SDL_HapticDirection direction; 740 741 /** 742 Duration of the effect. 743 */ 744 Uint32 length; 745 746 /** 747 Delay before starting the effect. 748 */ 749 Uint16 delay; 750 751 /** 752 Button that triggers the effect. 753 */ 754 Uint16 button; 755 756 /** 757 How soon it can be triggered again after button. 758 */ 759 Uint16 interval; 760 761 /** 762 Beginning strength level. 763 */ 764 Sint16 start; 765 766 /** 767 Ending strength level. 768 */ 769 Sint16 end; 770 771 /** 772 Duration of the attack. 773 */ 774 Uint16 attack_length; 775 776 /** 777 Level at the start of the attack. 778 */ 779 Uint16 attack_level; 780 781 /** 782 Duration of the fade. 783 */ 784 Uint16 fade_length; 785 786 /** 787 Level at the end of the fade. 788 */ 789 Uint16 fade_level; 790 } 791 792 /** 793 A structure containing a template for a Left/Right effect. 794 795 This struct is exclusively for the SDL_HAPTIC_LEFTRIGHT effect. 796 797 The Left/Right effect is used to explicitly control the large and small 798 motors, commonly found in modern game controllers. The small (right) motor 799 is high frequency, and the large (left) motor is low frequency. 800 801 \since This struct is available since SDL 3.2.0. 802 803 \sa SDL_HAPTIC_LEFTRIGHT 804 \sa SDL_HapticEffect 805 */ 806 struct SDL_HapticLeftRight { 807 808 /** 809 SDL_HAPTIC_LEFTRIGHT 810 */ 811 SDL_HapticEffectType type = SDL_HAPTIC_LEFTRIGHT; 812 813 /** 814 Duration of the effect in milliseconds. 815 */ 816 Uint32 length; 817 818 /** 819 Control of the large controller motor. 820 */ 821 Uint16 large_magnitude; 822 823 /** 824 Control of the small controller motor. 825 */ 826 Uint16 small_magnitude; 827 } 828 829 /** 830 A structure containing a template for the SDL_HAPTIC_CUSTOM effect. 831 832 This struct is exclusively for the SDL_HAPTIC_CUSTOM effect. 833 834 A custom force feedback effect is much like a periodic effect, where the 835 application can define its exact shape. You will have to allocate the data 836 yourself. Data should consist of channels* samples Uint16 samples. 837 838 If channels is one, the effect is rotated using the defined direction. 839 Otherwise it uses the samples in data for the different axes. 840 841 \since This struct is available since SDL 3.2.0. 842 843 \sa SDL_HAPTIC_CUSTOM 844 \sa SDL_HapticEffect 845 */ 846 struct SDL_HapticCustom { 847 848 /** 849 SDL_HAPTIC_CUSTOM 850 */ 851 SDL_HapticEffectType type = SDL_HAPTIC_CUSTOM; 852 853 /** 854 Direction of the effect. 855 */ 856 SDL_HapticDirection direction; 857 858 /** 859 Duration of the effect. 860 */ 861 Uint32 length; 862 863 /** 864 Delay before starting the effect. 865 */ 866 Uint16 delay; 867 868 /** 869 Button that triggers the effect. 870 */ 871 Uint16 button; 872 873 /** 874 How soon it can be triggered again after button. 875 */ 876 Uint16 interval; 877 878 /** 879 Axes to use, minimum of one. 880 */ 881 Uint8 channels; 882 883 /** 884 Sample periods. 885 */ 886 Uint16 period; 887 888 /** 889 Amount of samples. 890 */ 891 Uint16 samples; 892 893 /** 894 Should contain channels*samples items. 895 */ 896 Uint16* data; 897 898 /** 899 Duration of the attack. 900 */ 901 Uint16 attack_length; 902 903 /** 904 Level at the start of the attack. 905 */ 906 Uint16 attack_level; 907 908 /** 909 Duration of the fade. 910 */ 911 Uint16 fade_length; 912 913 /** 914 Level at the end of the fade. 915 */ 916 Uint16 fade_level; 917 } 918 919 /** 920 The generic template for any haptic effect. 921 922 All values max at 32767 (0x7FFF). Signed values also can be negative. Time 923 values unless specified otherwise are in milliseconds. 924 925 You can also pass SDL_HAPTIC_INFINITY to length instead of a 0-32767 value. 926 Neither delay, interval, attack_length nor fade_length support 927 SDL_HAPTIC_INFINITY. Fade will also not be used since effect never ends. 928 929 Additionally, the SDL_HAPTIC_RAMP effect does not support a duration of 930 SDL_HAPTIC_INFINITY. 931 932 Button triggers may not be supported on all devices, it is advised to not 933 use them if possible. Buttons start at index 1 instead of index 0 like the 934 joystick. 935 936 If both attack_length and fade_level are 0, the envelope is not used, 937 otherwise both values are used. 938 939 Common parts: 940 941 ```c 942 // Replay - All effects have this 943 Uint32 length; // Duration of effect (ms). 944 Uint16 delay; // Delay before starting effect. 945 946 // Trigger - All effects have this 947 Uint16 button; // Button that triggers effect. 948 Uint16 interval; // How soon before effect can be triggered again. 949 950 // Envelope - All effects except condition effects have this 951 Uint16 attack_length; // Duration of the attack (ms). 952 Uint16 attack_level; // Level at the start of the attack. 953 Uint16 fade_length; // Duration of the fade out (ms). 954 Uint16 fade_level; // Level at the end of the fade. 955 ``` 956 957 Here we have an example of a constant effect evolution in time: 958 959 ``` 960 Strength 961 ^ 962 | 963 | effect level --> _________________ 964 | / \ 965 | / \ 966 | / \ 967 | / \ 968 | attack_level --> | \ 969 | | | <--- fade_level 970 | 971 +--------------------------------------------------> Time 972 [--] [---] 973 attack_length fade_length 974 975 [------------------][-----------------------] 976 delay length 977 ``` 978 979 Note either the attack_level or the fade_level may be above the actual 980 effect level. 981 982 \since This struct is available since SDL 3.2.0. 983 984 \sa SDL_HapticConstant 985 \sa SDL_HapticPeriodic 986 \sa SDL_HapticCondition 987 \sa SDL_HapticRamp 988 \sa SDL_HapticLeftRight 989 \sa SDL_HapticCustom 990 */ 991 union SDL_HapticEffect { 992 993 /** 994 Effect type. 995 */ 996 SDL_HapticEffectType type; 997 998 /** 999 Constant effect. 1000 */ 1001 SDL_HapticConstant constant; 1002 1003 /** 1004 Periodic effect. 1005 */ 1006 SDL_HapticPeriodic periodic; 1007 1008 /** 1009 Condition effect. 1010 */ 1011 SDL_HapticCondition condition; 1012 1013 /** 1014 Ramp effect. 1015 */ 1016 SDL_HapticRamp ramp; 1017 1018 /** 1019 Left/Right effect. 1020 */ 1021 SDL_HapticLeftRight leftright; 1022 1023 /** 1024 Custom effect. 1025 */ 1026 SDL_HapticCustom custom; 1027 } 1028 1029 /** 1030 This is a unique ID for a haptic device for the time it is connected to the 1031 system, and is never reused for the lifetime of the application. 1032 1033 If the haptic device is disconnected and reconnected, it will get a new ID. 1034 1035 The value 0 is an invalid ID. 1036 1037 \since This datatype is available since SDL 3.2.0. 1038 */ 1039 alias SDL_HapticID = Uint32; 1040 1041 /** 1042 Get a list of currently connected haptic devices. 1043 1044 \param count a pointer filled in with the number of haptic devices 1045 returned, may be NULL. 1046 \returns a 0 terminated array of haptic device instance IDs or NULL on 1047 failure; call SDL_GetError() for more information. This should be 1048 freed with SDL_free() when it is no longer needed. 1049 1050 \since This function is available since SDL 3.2.0. 1051 1052 \sa SDL_OpenHaptic 1053 */ 1054 extern SDL_HapticID* SDL_GetHaptics(int* count); 1055 1056 /** 1057 Get the implementation dependent name of a haptic device. 1058 1059 This can be called before any haptic devices are opened. 1060 1061 \param instance_id the haptic device instance ID. 1062 \returns the name of the selected haptic device. If no name can be found, 1063 this function returns NULL; call SDL_GetError() for more 1064 information. 1065 1066 \since This function is available since SDL 3.2.0. 1067 1068 \sa SDL_GetHapticName 1069 \sa SDL_OpenHaptic 1070 */ 1071 extern const(char)* SDL_GetHapticNameForID(SDL_HapticID instance_id); 1072 1073 /** 1074 Open a haptic device for use. 1075 1076 The index passed as an argument refers to the N'th haptic device on this 1077 system. 1078 1079 When opening a haptic device, its gain will be set to maximum and 1080 autocenter will be disabled. To modify these values use SDL_SetHapticGain() 1081 and SDL_SetHapticAutocenter(). 1082 1083 \param instance_id the haptic device instance ID. 1084 \returns the device identifier or NULL on failure; call SDL_GetError() for 1085 more information. 1086 1087 \since This function is available since SDL 3.2.0. 1088 1089 \sa SDL_CloseHaptic 1090 \sa SDL_GetHaptics 1091 \sa SDL_OpenHapticFromJoystick 1092 \sa SDL_OpenHapticFromMouse 1093 \sa SDL_SetHapticAutocenter 1094 \sa SDL_SetHapticGain 1095 */ 1096 extern SDL_Haptic* SDL_OpenHaptic(SDL_HapticID instance_id); 1097 1098 1099 /** 1100 Get the SDL_Haptic associated with an instance ID, if it has been opened. 1101 1102 \param instance_id the instance ID to get the SDL_Haptic for. 1103 \returns an SDL_Haptic on success or NULL on failure or if it hasn't been 1104 opened yet; call SDL_GetError() for more information. 1105 1106 \since This function is available since SDL 3.2.0. 1107 */ 1108 extern SDL_Haptic* SDL_GetHapticFromID(SDL_HapticID instance_id); 1109 1110 /** 1111 Get the instance ID of an opened haptic device. 1112 1113 \param haptic the SDL_Haptic device to query. 1114 \returns the instance ID of the specified haptic device on success or 0 on 1115 failure; call SDL_GetError() for more information. 1116 1117 \since This function is available since SDL 3.2.0. 1118 */ 1119 extern SDL_HapticID SDL_GetHapticID(SDL_Haptic* haptic); 1120 1121 /** 1122 Get the implementation dependent name of a haptic device. 1123 1124 \param haptic the SDL_Haptic obtained from SDL_OpenJoystick(). 1125 \returns the name of the selected haptic device. If no name can be found, 1126 this function returns NULL; call SDL_GetError() for more 1127 information. 1128 1129 \since This function is available since SDL 3.2.0. 1130 1131 \sa SDL_GetHapticNameForID 1132 */ 1133 extern const(char)* SDL_GetHapticName(SDL_Haptic* haptic); 1134 1135 /** 1136 Query whether or not the current mouse has haptic capabilities. 1137 1138 \returns true if the mouse is haptic or false if it isn't. 1139 1140 \since This function is available since SDL 3.2.0. 1141 1142 \sa SDL_OpenHapticFromMouse 1143 */ 1144 extern bool SDL_IsMouseHaptic(); 1145 1146 /** 1147 Try to open a haptic device from the current mouse. 1148 1149 \returns the haptic device identifier or NULL on failure; call 1150 SDL_GetError() for more information. 1151 1152 \since This function is available since SDL 3.2.0. 1153 1154 \sa SDL_CloseHaptic 1155 \sa SDL_IsMouseHaptic 1156 */ 1157 extern SDL_Haptic* SDL_OpenHapticFromMouse(); 1158 1159 /** 1160 Query if a joystick has haptic features. 1161 1162 \param joystick the SDL_Joystick to test for haptic capabilities. 1163 \returns true if the joystick is haptic or false if it isn't. 1164 1165 \since This function is available since SDL 3.2.0. 1166 1167 \sa SDL_OpenHapticFromJoystick 1168 */ 1169 extern bool SDL_IsJoystickHaptic(SDL_Joystick* joystick); 1170 1171 /** 1172 Open a haptic device for use from a joystick device. 1173 1174 You must still close the haptic device separately. It will not be closed 1175 with the joystick. 1176 1177 When opened from a joystick you should first close the haptic device before 1178 closing the joystick device. If not, on some implementations the haptic 1179 device will also get unallocated and you'll be unable to use force feedback 1180 on that device. 1181 1182 \param joystick the SDL_Joystick to create a haptic device from. 1183 \returns a valid haptic device identifier on success or NULL on failure; 1184 call SDL_GetError() for more information. 1185 1186 \since This function is available since SDL 3.2.0. 1187 1188 \sa SDL_CloseHaptic 1189 \sa SDL_IsJoystickHaptic 1190 */ 1191 extern SDL_Haptic* SDL_OpenHapticFromJoystick(SDL_Joystick* joystick); 1192 1193 /** 1194 Close a haptic device previously opened with SDL_OpenHaptic(). 1195 1196 \param haptic the SDL_Haptic device to close. 1197 1198 \since This function is available since SDL 3.2.0. 1199 1200 \sa SDL_OpenHaptic 1201 */ 1202 extern void SDL_CloseHaptic(SDL_Haptic* haptic); 1203 1204 /** 1205 Get the number of effects a haptic device can store. 1206 1207 On some platforms this isn't fully supported, and therefore is an 1208 approximation. Always check to see if your created effect was actually 1209 created and do not rely solely on SDL_GetMaxHapticEffects(). 1210 1211 \param haptic the SDL_Haptic device to query. 1212 \returns the number of effects the haptic device can store or a negative 1213 error code on failure; call SDL_GetError() for more information. 1214 1215 \since This function is available since SDL 3.2.0. 1216 1217 \sa SDL_GetMaxHapticEffectsPlaying 1218 \sa SDL_GetHapticFeatures 1219 */ 1220 extern int SDL_GetMaxHapticEffects(SDL_Haptic* haptic); 1221 1222 /** 1223 Get the number of effects a haptic device can play at the same time. 1224 1225 This is not supported on all platforms, but will always return a value. 1226 1227 \param haptic the SDL_Haptic device to query maximum playing effects. 1228 \returns the number of effects the haptic device can play at the same time 1229 or -1 on failure; call SDL_GetError() for more information. 1230 1231 \since This function is available since SDL 3.2.0. 1232 1233 \sa SDL_GetMaxHapticEffects 1234 \sa SDL_GetHapticFeatures 1235 */ 1236 extern int SDL_GetMaxHapticEffectsPlaying(SDL_Haptic* haptic); 1237 1238 /** 1239 Get the haptic device's supported features in bitwise manner. 1240 1241 \param haptic the SDL_Haptic device to query. 1242 \returns a list of supported haptic features in bitwise manner (OR'd), or 0 1243 on failure; call SDL_GetError() for more information. 1244 1245 \since This function is available since SDL 3.2.0. 1246 1247 \sa SDL_HapticEffectSupported 1248 \sa SDL_GetMaxHapticEffects 1249 */ 1250 extern Uint32 SDL_GetHapticFeatures(SDL_Haptic* haptic); 1251 1252 /** 1253 Get the number of haptic axes the device has. 1254 1255 The number of haptic axes might be useful if working with the 1256 SDL_HapticDirection effect. 1257 1258 \param haptic the SDL_Haptic device to query. 1259 \returns the number of axes on success or -1 on failure; call 1260 SDL_GetError() for more information. 1261 1262 \since This function is available since SDL 3.2.0. 1263 */ 1264 extern int SDL_GetNumHapticAxes(SDL_Haptic* haptic); 1265 1266 /** 1267 Check to see if an effect is supported by a haptic device. 1268 1269 \param haptic the SDL_Haptic device to query. 1270 \param effect the desired effect to query. 1271 \returns true if the effect is supported or false if it isn't. 1272 1273 \since This function is available since SDL 3.2.0. 1274 1275 \sa SDL_CreateHapticEffect 1276 \sa SDL_GetHapticFeatures 1277 */ 1278 extern bool SDL_HapticEffectSupported(SDL_Haptic* haptic, const SDL_HapticEffect* effect); 1279 1280 /** 1281 Create a new haptic effect on a specified device. 1282 1283 \param haptic an SDL_Haptic device to create the effect on. 1284 \param effect an SDL_HapticEffect structure containing the properties of 1285 the effect to create. 1286 \returns the ID of the effect on success or -1 on failure; call 1287 SDL_GetError() for more information. 1288 1289 \since This function is available since SDL 3.2.0. 1290 1291 \sa SDL_DestroyHapticEffect 1292 \sa SDL_RunHapticEffect 1293 \sa SDL_UpdateHapticEffect 1294 */ 1295 extern SDL_HapticEffectID SDL_CreateHapticEffect(SDL_Haptic* haptic, const SDL_HapticEffect* effect); 1296 1297 /** 1298 Update the properties of an effect. 1299 1300 Can be used dynamically, although behavior when dynamically changing 1301 direction may be strange. Specifically the effect may re-upload itself and 1302 start playing from the start. You also cannot change the type either when 1303 running SDL_UpdateHapticEffect(). 1304 1305 \param haptic the SDL_Haptic device that has the effect. 1306 \param effect the identifier of the effect to update. 1307 \param data an SDL_HapticEffect structure containing the new effect 1308 properties to use. 1309 \returns true on success or false on failure; call SDL_GetError() for more 1310 information. 1311 1312 \since This function is available since SDL 3.2.0. 1313 1314 \sa SDL_CreateHapticEffect 1315 \sa SDL_RunHapticEffect 1316 */ 1317 extern bool SDL_UpdateHapticEffect(SDL_Haptic* haptic, SDL_HapticEffectID effect, const SDL_HapticEffect* data); 1318 1319 /** 1320 Run the haptic effect on its associated haptic device. 1321 1322 To repeat the effect over and over indefinitely, set `iterations` to 1323 `SDL_HAPTIC_INFINITY`. (Repeats the envelope - attack and fade.) To make 1324 one instance of the effect last indefinitely (so the effect does not fade), 1325 set the effect's `length` in its structure/union to `SDL_HAPTIC_INFINITY` 1326 instead. 1327 1328 \param haptic the SDL_Haptic device to run the effect on. 1329 \param effect the ID of the haptic effect to run. 1330 \param iterations the number of iterations to run the effect; use 1331 `SDL_HAPTIC_INFINITY` to repeat forever. 1332 \returns true on success or false on failure; call SDL_GetError() for more 1333 information. 1334 1335 \since This function is available since SDL 3.2.0. 1336 1337 \sa SDL_GetHapticEffectStatus 1338 \sa SDL_StopHapticEffect 1339 \sa SDL_StopHapticEffects 1340 */ 1341 extern bool SDL_RunHapticEffect(SDL_Haptic* haptic, SDL_HapticEffectID effect, Uint32 iterations); 1342 1343 /** 1344 Stop the haptic effect on its associated haptic device. 1345 1346 \param haptic the SDL_Haptic device to stop the effect on. 1347 \param effect the ID of the haptic effect to stop. 1348 \returns true on success or false on failure; call SDL_GetError() for more 1349 information. 1350 1351 \since This function is available since SDL 3.2.0. 1352 1353 \sa SDL_RunHapticEffect 1354 \sa SDL_StopHapticEffects 1355 */ 1356 extern bool SDL_StopHapticEffect(SDL_Haptic* haptic, SDL_HapticEffectID effect); 1357 1358 /** 1359 Destroy a haptic effect on the device. 1360 1361 This will stop the effect if it's running. Effects are automatically 1362 destroyed when the device is closed. 1363 1364 \param haptic the SDL_Haptic device to destroy the effect on. 1365 \param effect the ID of the haptic effect to destroy. 1366 1367 \since This function is available since SDL 3.2.0. 1368 1369 \sa SDL_CreateHapticEffect 1370 */ 1371 extern void SDL_DestroyHapticEffect(SDL_Haptic* haptic, SDL_HapticEffectID effect); 1372 1373 /** 1374 Get the status of the current effect on the specified haptic device. 1375 1376 Device must support the SDL_HAPTIC_STATUS feature. 1377 1378 \param haptic the SDL_Haptic device to query for the effect status on. 1379 \param effect the ID of the haptic effect to query its status. 1380 \returns true if it is playing, false if it isn't playing or haptic status 1381 isn't supported. 1382 1383 \since This function is available since SDL 3.2.0. 1384 1385 \sa SDL_GetHapticFeatures 1386 */ 1387 extern bool SDL_GetHapticEffectStatus(SDL_Haptic* haptic, SDL_HapticEffectID effect); 1388 1389 /** 1390 Set the global gain of the specified haptic device. 1391 1392 Device must support the SDL_HAPTIC_GAIN feature. 1393 1394 The user may specify the maximum gain by setting the environment variable 1395 `SDL_HAPTIC_GAIN_MAX` which should be between 0 and 100. All calls to 1396 SDL_SetHapticGain() will scale linearly using `SDL_HAPTIC_GAIN_MAX` as the 1397 maximum. 1398 1399 \param haptic the SDL_Haptic device to set the gain on. 1400 \param gain value to set the gain to, should be between 0 and 100 (0 - 1401 100). 1402 \returns true on success or false on failure; call SDL_GetError() for more 1403 information. 1404 1405 \since This function is available since SDL 3.2.0. 1406 1407 \sa SDL_GetHapticFeatures 1408 */ 1409 extern bool SDL_SetHapticGain(SDL_Haptic* haptic, int gain); 1410 1411 /** 1412 Set the global autocenter of the device. 1413 1414 Autocenter should be between 0 and 100. Setting it to 0 will disable 1415 autocentering. 1416 1417 Device must support the SDL_HAPTIC_AUTOCENTER feature. 1418 1419 \param haptic the SDL_Haptic device to set autocentering on. 1420 \param autocenter value to set autocenter to (0-100). 1421 \returns true on success or false on failure; call SDL_GetError() for more 1422 information. 1423 1424 \since This function is available since SDL 3.2.0. 1425 1426 \sa SDL_GetHapticFeatures 1427 */ 1428 extern bool SDL_SetHapticAutocenter(SDL_Haptic* haptic, int autocenter); 1429 1430 /** 1431 Pause a haptic device. 1432 1433 Device must support the `SDL_HAPTIC_PAUSE` feature. Call SDL_ResumeHaptic() 1434 to resume playback. 1435 1436 Do not modify the effects nor add new ones while the device is paused. That 1437 can cause all sorts of weird errors. 1438 1439 \param haptic the SDL_Haptic device to pause. 1440 \returns true on success or false on failure; call SDL_GetError() for more 1441 information. 1442 1443 \since This function is available since SDL 3.2.0. 1444 1445 \sa SDL_ResumeHaptic 1446 */ 1447 extern bool SDL_PauseHaptic(SDL_Haptic* haptic); 1448 1449 /** 1450 Resume a haptic device. 1451 1452 Call to unpause after SDL_PauseHaptic(). 1453 1454 \param haptic the SDL_Haptic device to unpause. 1455 \returns true on success or false on failure; call SDL_GetError() for more 1456 information. 1457 1458 \since This function is available since SDL 3.2.0. 1459 1460 \sa SDL_PauseHaptic 1461 */ 1462 extern bool SDL_ResumeHaptic(SDL_Haptic* haptic); 1463 1464 /** 1465 Stop all the currently playing effects on a haptic device. 1466 1467 \param haptic the SDL_Haptic device to stop. 1468 \returns true on success or false on failure; call SDL_GetError() for more 1469 information. 1470 1471 \since This function is available since SDL 3.2.0. 1472 1473 \sa SDL_RunHapticEffect 1474 \sa SDL_StopHapticEffects 1475 */ 1476 extern bool SDL_StopHapticEffects(SDL_Haptic* haptic); 1477 1478 /** 1479 Check whether rumble is supported on a haptic device. 1480 1481 \param haptic haptic device to check for rumble support. 1482 \returns true if the effect is supported or false if it isn't. 1483 1484 \since This function is available since SDL 3.2.0. 1485 1486 \sa SDL_InitHapticRumble 1487 */ 1488 extern bool SDL_HapticRumbleSupported(SDL_Haptic* haptic); 1489 1490 /** 1491 Initialize a haptic device for simple rumble playback. 1492 1493 \param haptic the haptic device to initialize for simple rumble playback. 1494 \returns true on success or false on failure; call SDL_GetError() for more 1495 information. 1496 1497 \since This function is available since SDL 3.2.0. 1498 1499 \sa SDL_PlayHapticRumble 1500 \sa SDL_StopHapticRumble 1501 \sa SDL_HapticRumbleSupported 1502 */ 1503 extern bool SDL_InitHapticRumble(SDL_Haptic* haptic); 1504 1505 /** 1506 Run a simple rumble effect on a haptic device. 1507 1508 \param haptic the haptic device to play the rumble effect on. 1509 \param strength strength of the rumble to play as a 0-1 float value. 1510 \param length length of the rumble to play in milliseconds. 1511 \returns true on success or false on failure; call SDL_GetError() for more 1512 information. 1513 1514 \since This function is available since SDL 3.2.0. 1515 1516 \sa SDL_InitHapticRumble 1517 \sa SDL_StopHapticRumble 1518 */ 1519 extern bool SDL_PlayHapticRumble(SDL_Haptic* haptic, float strength, Uint32 length); 1520 1521 /** 1522 Stop the simple rumble on a haptic device. 1523 1524 \param haptic the haptic device to stop the rumble effect on. 1525 \returns true on success or false on failure; call SDL_GetError() for more 1526 information. 1527 1528 \since This function is available since SDL 3.2.0. 1529 1530 \sa SDL_PlayHapticRumble 1531 */ 1532 extern bool SDL_StopHapticRumble(SDL_Haptic* haptic);