First shot at merging the wiki documentation into the headers.
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 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 2052 2053 2054 2055 2056 2057 2058 2059 2060 2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076 2077 2078 2079 2080 2081 2082 2083 2084 2085 2086 2087 2088 2089 2090 2091 2092 2093 2094 2095 2096 2097 2098 2099 2100 2101 2102 2103 2104 2105 2106 2107 2108 2109 2110 2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128 2129 2130 2131 2132 2133 2134 2135 2136 2137 2138 2139 2140 2141 2142 2143 2144 2145 2146 2147 2148 2149 2150 2151 2152 2153 2154 2155 2156 2157 2158 2159 2160 2161 2162 2163 2164 2165 2166 2167 2168 2169 2170 2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201 2202 2203 2204 2205 2206 2207 2208 2209 2210 2211 2212 2213 2214 2215 2216 2217 2218 2219 2220 2221 2222 2223 2224 2225 2226 2227 2228 2229 2230 2231 2232 2233 2234 2235 2236 2237 2238 2239 2240 2241 2242 2243 2244 2245 2246 2247 2248 2249 2250 2251 2252 2253 2254 2255 2256 2257 2258 2259 2260 2261 2262 2263 2264 2265 2266 2267 2268 2269 2270 2271 2272 2273 2274 2275 2276 2277 2278 2279 2280 2281 2282 2283 2284 2285 2286 2287 2288 2289 2290 2291 2292 2293 2294 2295 2296 2297 2298 2299 2300 2301 2302 2303 2304 2305 2306 2307 2308 2309 2310 2311 2312 2313 2314 2315 2316 2317 2318 2319 2320 2321 2322 2323 2324 2325 2326 2327 2328 2329 2330 2331 2332 2333 2334 2335 2336 2337 2338 2339 2340 2341 2342 2343 2344 2345 2346 2347 2348 2349 2350 2351 2352 2353 2354 2355 2356 2357 2358 2359 2360 2361 2362 2363 2364 2365 2366 2367 2368 2369 2370 2371 2372 2373 2374 2375 2376 2377 2378 2379 2380 2381 2382 2383 2384 2385 2386 2387 2388 2389 2390 2391 2392 2393 2394 2395 2396 2397 2398 2399 2400 2401 2402 2403 2404 2405 2406 2407 2408 2409 2410 2411 2412 2413 2414 2415 2416 2417 2418 2419 2420 2421 2422 2423 2424 2425 2426 2427 2428 2429 2430 2431 2432 2433 2434 2435 2436 2437 2438 2439 2440 2441 2442 2443 2444 2445 2446 2447 2448 2449 2450 2451 2452 2453 2454 2455 2456 2457 2458 2459 2460 2461 2462 2463 2464 2465 2466 2467 2468 2469 2470 2471 2472 2473 2474 2475 2476 2477 2478 2479 2480 2481 2482 2483 2484 2485 2486 2487 2488 2489 2490 2491 2492 2493 2494 2495 2496 2497 2498 2499 2500 2501 2502 2503 2504 2505 2506 2507 2508 2509 2510 2511 2512 2513 2514 2515 2516 2517 2518 2519 2520 2521 2522 2523 2524 2525 2526 2527 2528 2529 2530 2531 2532 2533 2534 2535 2536 2537 2538 2539 2540 2541 2542 2543 2544 2545 2546 2547 2548 2549 2550 2551 2552 2553 2554 2555 2556 2557 2558 2559 2560 2561 2562 2563 2564 2565 2566 2567 2568 2569 2570 2571 2572 2573 2574 2575 2576 2577 2578 2579 2580 2581 2582 2583 2584 2585 2586 2587 2588 2589 2590 2591 2592 2593 2594 2595 2596 2597 2598 2599 2600 2601 2602 2603 2604 2605 2606 2607 2608 2609 2610 2611 2612 2613 2614 2615 2616 2617 2618 2619 2620 2621 2622 2623 2624 2625 2626 2627 2628 2629 2630 2631 2632 2633 2634 2635 2636 2637 2638 2639 2640 2641 2642 2643 2644 2645 2646 2647 2648 2649 2650 2651 2652 2653 2654 2655 2656 2657 2658 2659 2660 2661 2662 2663 2664 2665 2666 2667 2668 2669 2670 2671 2672 2673 2674 2675 2676 2677 2678 2679 2680 2681 2682 2683 2684 2685 2686 2687 2688 2689 2690 2691 2692 2693 2694 2695 2696 2697 2698 2699 2700 2701 2702 2703 2704 2705 2706 2707 2708 2709 2710 2711 2712 2713 2714 2715 2716 2717 2718 2719 2720 2721 2722 2723 2724 2725 2726 2727 2728 2729 2730 2731 2732 2733 2734 2735 2736 2737 2738 2739 2740 2741 2742 2743 2744 2745 2746 2747 2748 2749 2750 2751 2752 2753 2754 2755 2756 2757 2758 2759 2760 2761 2762 2763 2764 2765 2766 2767 2768 2769 2770 2771 2772 2773 2774 2775 2776 2777 2778 2779 2780 2781 2782 2783 2784 2785 2786 2787 2788 2789 2790 2791 2792 2793 2794 2795 2796 2797 2798 2799 2800 2801 2802 2803 2804 2805 2806 2807 2808 2809 2810 2811 2812 2813 2814 2815 2816 2817 2818 2819 2820 2821 2822 2823 2824 2825 2826 2827 2828 2829 2830 2831 2832 2833 2834 2835 2836 2837 2838 2839 2840 2841 2842 2843 2844 2845 2846 2847 2848 2849 2850 2851 2852 2853 2854 2855 2856 2857 2858 2859 2860 2861 2862 2863 2864 2865 2866 2867 2868 2869 2870 2871 2872 2873 2874 2875 2876 2877 2878 2879 2880 2881 2882 2883 2884 2885 2886 2887 2888 2889 2890 2891 2892 2893 2894 2895 2896 2897 2898 2899 2900 2901 2902 2903 2904 2905 2906 2907 2908 2909 2910 2911 2912 2913 2914 2915 2916 2917 2918 2919 2920 2921 2922 2923 2924 2925 2926 2927 2928 2929 2930 2931 2932 2933 2934 2935 2936 2937 2938 2939 2940 2941 2942 2943 2944 2945 2946 2947 2948 2949 2950 2951 2952 2953 2954 2955 2956 2957 2958 2959 2960 2961 2962 2963 2964 2965 2966 2967 2968 2969 2970 2971 2972 2973 2974 2975 2976 2977 2978 2979 2980 2981 2982 2983 2984 2985 2986 2987 2988 2989 2990 2991 2992 2993 2994 2995 2996 2997 2998 2999 3000 3001 3002 3003 3004 3005 3006 3007 3008 3009 3010 3011 3012 3013 3014 3015 3016 3017 3018 3019 3020 3021 3022 3023 3024 3025 3026 3027 3028 3029 3030 3031 3032 3033 3034 3035 3036 3037 3038 3039 3040 3041 3042 3043 3044 3045 3046 3047 3048 3049 3050 3051 3052 3053 3054 3055 3056 3057 3058 3059 3060 3061 3062 3063 3064 3065 3066 3067 3068 3069 3070 3071 3072 3073 3074 3075 3076 3077 3078 3079 3080 3081 3082 3083 3084 3085 3086 3087 3088 3089 3090 3091 3092 3093 3094 3095 3096 3097 3098 3099 3100 3101 3102 3103 3104 3105 3106 3107 3108 3109 3110 3111 3112 3113 3114 3115 3116 3117 3118 3119 3120 3121 3122 3123 3124 3125 3126 3127 3128 3129 3130 3131 3132 3133 3134 3135 3136 3137 3138 3139 3140 3141 3142 3143 3144 3145 3146 3147 3148 3149 3150 3151 3152 3153 3154 3155 3156 3157 3158 3159 3160 3161 3162 3163 3164 3165 3166 3167 3168 3169 3170 3171 3172 3173 3174 3175 3176 3177 3178 3179 3180 3181 3182 3183 3184 3185 3186 3187 3188 3189 3190 3191 3192 3193 3194 3195 3196 3197 3198 3199 3200 3201 3202 3203 3204 3205 3206 3207 3208 3209 3210 3211 3212 3213 3214 3215 3216 3217 3218 3219 3220 3221 3222 3223 3224 3225 3226 3227 3228 3229 3230 3231 3232 3233 3234 3235 3236 3237 3238 3239 3240 3241 3242 3243 3244 3245 3246 3247 3248 3249 3250 3251 3252 3253 3254 3255 3256 3257 3258 3259 3260 3261 3262 3263 3264 3265 3266 3267 3268 3269 3270 3271 3272 3273 3274 3275 3276 3277 3278 3279 3280 3281 3282 3283 3284 3285 3286 3287 3288 3289 3290 3291 3292 3293 3294 3295 3296 3297 3298 3299 3300 3301 3302 3303 3304 3305 3306 3307 3308 3309 3310 3311 3312 3313 3314 3315 3316 3317 3318 3319 3320 3321 3322 3323 3324 3325 3326 3327 3328 3329 3330 3331 3332 3333 3334 3335 3336 3337 3338 3339 3340 3341 3342 3343 3344 3345 3346 3347 3348 3349 3350 3351 3352 3353 3354 3355 3356 3357 3358 3359 3360 3361 3362 3363 3364 3365 3366 3367 3368 3369 3370 3371 3372 3373 3374 3375 3376 3377 3378 3379 3380 3381 3382 3383 3384 3385 3386 3387 3388 3389 3390 3391 3392 3393 3394 3395 3396 3397 3398 3399 3400 3401 3402 3403 3404 3405 3406 3407 3408 3409 3410 3411 3412 3413 3414 3415 3416 3417 3418 3419 3420 3421 3422 3423 3424 3425 3426 3427 3428 3429 3430 3431 3432 3433 3434 3435 3436 3437 3438 3439 3440 3441 3442 3443 3444 3445 3446 3447 3448 3449 3450 3451 3452 3453 3454 3455 3456 3457 3458 3459 3460 3461 3462 3463 3464 3465 3466 3467 3468 3469 3470 3471 3472 3473 3474 3475 3476 3477 3478 3479 3480 3481 3482 3483 3484 3485 3486 3487 3488 3489 3490 3491 3492 3493 3494 3495 3496 3497 3498 3499 3500 3501 3502 3503 3504 3505 3506 3507 3508 3509 3510 3511 3512 3513 3514 3515 3516 3517 3518 3519 3520 3521 3522 3523 3524 3525 3526 3527 3528 3529 3530 3531 3532 3533 3534 3535 3536 3537 3538 3539 3540 3541 3542 3543 3544 3545 3546 3547 3548 3549 3550 3551 3552 3553 3554 3555 3556 3557 3558 3559 3560 3561 3562 3563 3564 3565 3566 3567 3568 3569 3570 3571 3572 3573 3574 3575 3576 3577 3578 3579 3580 3581 3582 3583 3584 3585 3586 3587 3588 3589 3590 3591 3592 3593 3594 3595 3596 3597 3598 3599 3600 3601 3602 3603 3604 3605 3606 3607 3608 3609 3610 3611 3612 3613 3614 3615 3616 3617 3618 3619 3620 3621 3622 3623 3624 3625 3626 3627 3628 3629 3630 3631 3632 3633 3634 3635 3636 3637 3638 3639 3640 3641 3642 3643 3644 3645 3646 3647 3648 3649 3650 3651 3652 3653 3654 3655 3656 3657 3658 3659 3660 3661 3662 3663 3664 3665 3666 3667 3668 3669 3670 3671 3672 3673 3674 3675 3676 3677 3678 3679 3680 3681 3682 3683 3684 3685 3686 3687 3688 3689 3690 3691 3692 3693 3694 3695 3696 3697 3698 3699 3700 3701 3702 3703 3704 3705 3706 3707 3708 3709 3710 3711 3712 3713 3714 3715 3716 3717 3718 3719 3720 3721 3722 3723 3724 3725 3726 3727 3728 3729 3730 3731 3732 3733 3734 3735 3736 3737 3738 3739 3740 3741 3742 3743 3744 3745 3746 3747 3748 3749 3750 3751 3752 3753 3754 3755 3756 3757 3758 3759 3760 3761 3762 3763 3764 3765 3766 3767 3768 3769 3770 3771 3772 3773 3774 3775 3776 3777 3778 3779 3780 3781 3782 3783 3784 3785 3786 3787 3788 3789 3790 3791 3792 3793 3794 3795 3796 3797 3798 3799 3800 3801 3802 3803 3804 3805 3806 3807 3808 3809 3810 3811 3812 3813 3814 3815 3816 3817 3818 3819 3820 3821 3822 3823 3824 3825 3826 3827 3828 3829 3830 3831 3832 3833 3834 3835 3836 3837 3838 3839 3840 3841 3842 3843 3844 3845 3846 3847 3848 3849 3850 3851 3852 3853 3854 3855 3856 3857 3858 3859 3860 3861 3862 3863 3864 3865 3866 3867 3868 3869 3870 3871 3872 3873 3874 3875 3876 3877 3878 3879 3880 3881 3882 3883 3884 3885 3886 3887 3888 3889 3890 3891 3892 3893 3894 3895 3896 3897 3898 3899 3900 3901 3902 3903 3904 3905 3906 3907 3908 3909 3910 3911 3912 3913 3914 3915 3916 3917 3918 3919 3920 3921 3922 3923 3924 3925 3926 3927 3928 3929 3930 3931 3932 3933 3934 3935 3936 3937 3938 3939 3940 3941 3942 3943 3944 3945 3946 3947 3948 3949 3950 3951 3952 3953 3954 3955 3956 3957 3958 3959 3960 3961 3962 3963 3964 3965 3966 3967 3968 3969 3970 3971 3972 3973 3974 3975 3976 3977 3978 3979 3980 3981 3982 3983 3984 3985 3986 3987 3988 3989 3990 3991 3992 3993 3994 3995 3996 3997 3998 3999 4000 4001 4002 4003 4004 4005 4006 4007 4008 4009 4010 4011 4012 4013 4014 4015 4016 4017 4018 4019 4020 4021 4022 4023 4024 4025 4026 4027 4028 4029 4030 4031 4032 4033 4034 4035 4036 4037 4038 4039 4040 4041 4042 4043 4044 4045 4046 4047 4048 4049 4050 4051 4052 4053 4054 4055 4056 4057 4058 4059 4060 4061 4062 4063 4064 4065 4066 4067 4068 4069 4070 4071 4072 4073 4074 4075 4076 4077 4078 4079 4080 4081 4082 4083 4084 4085 4086 4087 4088 4089 4090 4091 4092 4093 4094 4095 4096 4097 4098 4099 4100 4101 4102 4103 4104 4105 4106 4107 4108 4109 4110 4111 4112 4113 4114 4115 4116 4117 4118 4119 4120 4121 4122 4123 4124 4125 4126 4127 4128 4129 4130 4131 4132 4133 4134 4135 4136 4137 4138 4139 4140 4141 4142 4143 4144 4145 4146 4147 4148 4149 4150 4151 4152 4153 4154 4155 4156 4157 4158 4159 4160 4161 4162 4163 4164 4165 4166 4167 4168 4169 4170 4171 4172 4173 4174 4175 4176 4177 4178 4179 4180 4181 4182 4183 4184 4185 4186 4187 4188 4189 4190 4191 4192 4193 4194 4195 4196 4197 4198 4199 4200 4201 4202 4203 4204 4205 4206 4207 4208 4209 4210 4211 4212 4213 4214 4215 4216 4217 4218 4219 4220 4221 4222 4223 4224 4225 4226 4227 4228 4229 4230 4231 4232 4233 4234 4235 4236 4237 4238 4239 4240 4241 4242 4243 4244 4245 4246 4247 4248 4249 4250 4251 4252 4253 4254 4255 4256 4257 4258 4259 4260 4261 4262 4263 4264 4265 4266 4267 4268 4269 4270 4271 4272 4273 4274 4275 4276 4277 4278 4279 4280 4281 4282 4283 4284 4285 4286 4287 4288 4289 4290 4291 4292 4293 4294 4295 4296 4297 4298 4299 4300 4301 4302 4303 4304 4305 4306 4307 4308 4309 4310 4311 4312 4313 4314 4315 4316 4317 4318 4319 4320 4321 4322 4323 4324 4325 4326 4327 4328 4329 4330 4331 4332 4333 4334 4335 4336 4337 4338 4339 4340 4341 4342 4343 4344 4345 4346 4347 4348 4349 4350 4351 4352 4353 4354 4355 4356 4357 4358 4359 4360 4361 4362 4363 4364 4365 4366 4367 4368 4369 4370 4371 4372 4373 4374 4375 4376 4377 4378 4379 4380 4381 4382 4383 4384 4385 4386 4387 4388 4389 4390 4391 4392 4393 4394 4395 4396 4397 4398 4399 4400 4401 4402 4403 4404 4405 4406 4407 4408 4409 4410 4411 4412 4413 4414 4415 4416 4417 4418 4419 4420 4421 4422 4423 4424 4425 4426 4427 4428 4429 4430 4431 4432 4433 4434 4435 4436 4437 4438 4439 4440 4441 4442 4443 4444 4445 4446 4447 4448 4449 4450 4451 4452 4453 4454 4455 4456 4457 4458 4459 4460 4461 4462 4463 4464 4465 4466 4467 4468 4469 4470 4471 4472 4473 4474 4475 4476 4477 4478 4479 4480 4481 4482 4483 4484 4485 4486 4487 4488 4489 4490 4491 4492 4493 4494 4495 4496 4497 4498 4499 4500 4501 4502 4503 4504 4505 4506 4507 4508 4509 4510 4511 4512 4513 4514 4515 4516 4517 4518 4519 4520 4521 4522 4523 4524 4525 4526 4527 4528 4529 4530 4531 4532 4533 4534 4535 4536 4537 4538 4539 4540 4541 4542 4543 4544 4545 4546 4547 4548 4549 4550 4551 4552 4553 4554 4555 4556 4557 4558 4559 4560 4561 4562 4563 4564 4565 4566 4567 4568 4569 4570 4571 4572 4573 4574 4575 4576 4577 4578 4579 4580 4581 4582 4583 4584 4585 4586 4587 4588 4589 4590 4591 4592 4593 4594 4595 4596 4597 4598 4599 4600 4601 4602 4603 4604 4605 4606 4607 4608 4609 4610 4611 4612 4613 4614 4615 4616 4617 4618 4619 4620 4621 4622 4623 4624 4625 4626 4627 4628 4629 4630 4631 4632 4633 4634 4635 4636 4637 4638 4639 4640 4641 4642 4643 4644 4645 4646 4647 4648 4649 4650 4651 4652 4653 4654 4655 4656 4657 4658 4659 4660 4661 4662 4663 4664 4665 4666 4667 4668 4669 4670 4671 4672 4673 4674 4675 4676 4677 4678 4679 4680 4681 4682 4683 4684 4685 4686 4687 4688 4689 4690 4691 4692 4693 4694 4695 4696 4697 4698 4699 4700 4701 4702 4703 4704 4705 4706 4707 4708 4709 4710 4711 4712 4713 4714 4715 4716 4717 4718 4719 4720 4721 4722 4723 4724 4725 4726 4727 4728 4729 4730 4731 4732 4733 4734 4735 4736 4737 4738 4739 4740 4741 4742 4743 4744 4745 4746 4747 4748 4749 4750 4751 4752 4753 4754 4755 4756 4757 4758 4759 4760 4761 4762 4763 4764 4765 4766 4767 4768 4769 4770 4771 4772 4773 4774 4775 4776 4777 4778 4779 4780 4781 4782 4783 4784 4785 4786 4787 4788 4789 4790 4791 4792 4793 4794 4795 4796 4797 4798 4799 4800 4801 4802 4803 4804 4805 4806 4807 4808 4809 4810 4811 4812 4813 4814 4815 4816 4817 4818 4819 4820 4821 4822 4823 4824 4825 4826 4827 4828 4829 4830 4831 4832 4833 4834 4835 4836 4837 4838 4839 4840 4841 4842 4843 4844 4845 4846 4847 4848 4849 4850 4851 4852 4853 4854 4855 4856 4857 4858 4859 4860 4861 4862 4863 4864 4865 4866 4867 4868 4869 4870 4871 4872 4873 4874 4875 4876 4877 4878 4879 4880 4881 4882 4883 4884 4885 4886 4887 4888 4889 4890 4891 4892 4893 4894 4895 4896 4897 4898 4899 4900 4901 4902 4903 4904 4905 4906 4907 4908 4909 4910 4911 4912 4913 4914 4915 4916 4917 4918 4919 4920 4921 4922 4923 4924 4925 4926 4927 4928 4929 4930 4931 4932 4933 4934 4935 4936 4937 4938 4939 4940 4941 4942 4943 4944 4945 4946 4947 4948 4949 4950 4951 4952 4953 4954 4955 4956 4957 4958 4959 4960 4961 4962 4963 4964 4965 4966 4967 4968 4969 4970 4971 4972 4973 4974 4975 4976 4977 4978 4979 4980 4981 4982 4983 4984 4985 4986 4987 4988 4989 4990 4991 4992 4993 4994 4995 4996 4997 4998 4999 5000 5001 5002 5003 5004 5005 5006 5007 5008 5009 5010 5011 5012 5013 5014 5015 5016 5017 5018 5019 5020 5021 5022 5023 5024 5025 5026 5027 5028 5029 5030 5031 5032 5033 5034 5035 5036 5037 5038 5039 5040 5041 5042 5043 5044 5045 5046 5047 5048 5049 5050 5051 5052 5053 5054 5055 5056 5057 5058 5059 5060 5061 5062 5063 5064 5065 5066 5067 5068 5069 5070 5071 5072 5073 5074 5075 5076 5077 5078 5079 5080 5081 5082 5083 5084 5085 5086 5087 5088 5089 5090 5091 5092 5093 5094 5095 5096 5097 5098 5099 5100 5101 5102 5103 5104 5105 5106 5107 5108 5109 5110 5111 5112 5113 5114 5115 5116 5117 5118 5119 5120 5121 5122 5123 5124 5125 5126 5127 5128 5129 5130 5131 5132 5133 5134 5135 5136 5137 5138 5139 5140 5141 5142 5143 5144 5145 5146 5147 5148 5149 5150 5151 5152 5153 5154 5155 5156 5157 5158 5159 5160 5161 5162 5163 5164 5165 5166 5167 5168 5169 5170 5171 5172 5173 5174 5175 5176 5177 5178 5179 5180 5181 5182 5183 5184 5185 5186 5187 5188 5189 5190 5191 5192 5193 5194 5195 5196 5197 5198 5199 5200 5201 5202 5203 5204 5205 5206 5207 5208 5209 5210 5211 5212 5213 5214 5215 5216 5217 5218 5219 5220 5221 5222 5223 5224 5225 5226 5227 5228 5229 5230 5231 5232 5233 5234 5235 5236 5237 5238 5239 5240 5241 5242 5243 5244 5245 5246 5247 5248 5249 5250 5251 5252 5253 5254 5255 5256 5257 5258 5259 5260 5261 5262 5263 5264 5265 5266 5267 5268 5269 5270 5271 5272 5273 5274 5275 5276 5277 5278 5279 5280 5281 5282 5283 5284 5285 5286 5287 5288 5289 5290 5291 5292 5293 5294 5295 5296 5297 5298 5299 5300 5301 5302 5303 5304 5305 5306 5307 5308 5309 5310 5311 5312 5313 5314 5315 5316 5317 5318 5319 5320 5321 5322 5323 5324 5325 5326 5327 5328 5329 5330 5331 5332 5333 5334 5335 5336 5337 5338 5339 5340 5341 5342 5343 5344 5345 5346 5347 5348 5349 5350 5351 5352 5353 5354 5355 5356 5357 5358 5359 5360 5361 5362 5363 5364 5365 5366 5367 5368 5369 5370 5371 5372 5373 5374 5375 5376 5377 5378 5379 5380 5381 5382 5383 5384 5385 5386 5387 5388 5389 5390 5391 5392 5393 5394 5395 5396 5397 5398 5399 5400 5401 5402 5403 5404 5405 5406 5407 5408 5409 5410 5411 5412 5413 5414 5415 5416 5417 5418 5419 5420 5421 5422 5423 5424 5425 5426 5427 5428 5429 5430 5431 5432 5433 5434 5435 5436 5437 5438 5439 5440 5441 5442 5443 5444 5445 5446 5447 5448 5449 5450 5451 5452 5453 5454 5455 5456 5457 5458 5459 5460 5461 5462 5463 5464 5465 5466 5467 5468 5469 5470 5471 5472 5473 5474 5475 5476 5477 5478 5479 5480 5481 5482 5483 5484 5485 5486 5487 5488 5489 5490 5491 5492 5493 5494 5495 5496 5497 5498 5499 5500 5501 5502 5503 5504 5505 5506 5507 5508 5509 5510 5511 5512 5513 5514 5515 5516 5517 5518 5519 5520 5521 5522 5523 5524 5525 5526 5527 5528 5529 5530 5531 5532 5533 5534 5535 5536 5537 5538 5539 5540 5541 5542 5543 5544 5545 5546 5547 5548 5549 5550 5551 5552 5553 5554 5555 5556 5557 5558 5559 5560 5561 5562 5563 5564 5565 5566 5567 5568 5569 5570 5571 5572 5573 5574 5575 5576 5577 5578 5579 5580 5581 5582 5583 5584 5585 5586 5587 5588 5589 5590 5591 5592 5593 5594 5595 5596 5597 5598 5599 5600 5601 5602 5603 5604 5605 5606 5607 5608 5609 5610 5611 5612 5613 5614 5615 5616 5617 5618 5619 5620 5621 5622 5623 5624 5625 5626 5627 5628 5629 5630 5631 5632 5633 5634 5635 5636 5637 5638 5639 5640 5641 5642 5643 5644 5645 5646 5647 5648 5649 5650 5651 5652 5653 5654 5655 5656 5657 5658 5659 5660 5661 5662 5663 5664 5665 5666 5667 5668 5669 5670 5671 5672 5673 5674 5675 5676 5677 5678 5679 5680 5681 5682 5683 5684 5685 5686 5687 5688 5689 5690 5691 5692 5693 5694 5695 5696 5697 5698 5699 5700 5701 5702 5703 5704 5705 5706 5707 5708 5709 5710 5711 5712 5713 5714 5715 5716 5717 5718 5719 5720 5721 5722 5723 5724 5725 5726 5727 5728 5729 5730 5731 5732 5733 5734 5735 5736 5737 5738 5739 5740 5741 5742 5743 5744 5745 5746 5747 5748 5749 5750 5751 5752 5753 5754 5755 5756 5757 5758 5759 5760 5761 5762 5763 5764 5765 5766 5767 5768 5769 5770 5771 5772 5773 5774 5775 5776 5777 5778 5779 5780 5781 5782 5783 5784 5785 5786 5787 5788 5789 5790 5791 5792 5793 5794 5795 5796 5797 5798 5799 5800 5801 5802 5803 5804 5805 5806 5807 5808 5809 5810 5811 5812 5813 5814 5815 5816 5817 5818 5819 5820 5821 5822 5823 5824 5825 5826 5827 5828 5829 5830 5831 5832 5833 5834 5835 5836 5837 5838 5839 5840 5841 5842 5843 5844 5845 5846 5847 5848 5849 5850 5851 5852 5853 5854 5855 5856 5857 5858 5859 5860 5861 5862 5863 5864 5865 5866 5867 5868 5869 5870 5871 5872 5873 5874 5875 5876 5877 5878 5879 5880 5881 5882 5883 5884 5885 5886 5887 5888 5889 5890 5891 5892 5893 5894 5895 5896 5897 5898 5899 5900 5901 5902 5903 5904 5905 5906 5907 5908 5909 5910 5911 5912 5913 5914 5915 5916 5917 5918 5919 5920 5921 5922 5923 5924 5925 5926 5927 5928 5929 5930 5931 5932 5933 5934 5935 5936 5937 5938 5939 5940 5941 5942 5943 5944 5945 5946 5947 5948 5949 5950 5951 5952 5953 5954 5955 5956 5957 5958 5959 5960 5961 5962 5963 5964 5965 5966 5967 5968 5969 5970 5971 5972 5973 5974 5975 5976 5977 5978 5979 5980 5981 5982 5983 5984 5985 5986 5987 5988 5989 5990 5991 5992 5993 5994 5995 5996 5997 5998 5999 6000 6001 6002 6003 6004 6005 6006 6007 6008 6009 6010 6011 6012 6013 6014 6015 6016 6017 6018 6019 6020 6021 6022 6023 6024 6025 6026 6027 6028 6029 6030 6031 6032 6033 6034 6035 6036 6037 6038 6039 6040 6041 6042 6043 6044 6045 6046 6047 6048 6049 6050 6051 6052 6053 6054 6055 6056 6057 6058 6059 6060 6061 6062 6063 6064 6065 6066 6067 6068 6069 6070 6071 6072 6073 6074 6075 6076 6077 6078 6079 6080 6081 6082 6083 6084 6085 6086 6087 6088 6089 6090 6091 6092 6093 6094 6095 6096 6097 6098 6099 6100 6101 6102 6103 6104 6105 6106 6107 6108 6109 6110 6111 6112 6113 6114 6115 6116 6117 6118 6119 6120 6121 6122 6123 6124 6125 6126 6127 6128 6129 6130 6131 6132 6133 6134 6135 6136 6137 6138 6139 6140 6141 6142 6143 6144 6145 6146 6147 6148 6149 6150 6151 6152 6153 6154 6155 6156 6157 6158 6159 6160 6161 6162 6163 6164 6165 6166 6167 6168 6169 6170 6171 6172 6173 6174 6175 6176 6177 6178 6179 6180 6181 6182 6183 6184 6185 6186 6187 6188 6189 6190 6191 6192 6193 6194 6195 6196 6197 6198 6199 6200 6201 6202 6203 6204 6205 6206 6207 6208 6209 6210 6211 6212 6213 6214 6215 6216 6217 6218 6219 6220 6221 6222 6223 6224 6225 6226 6227 6228 6229 6230 6231 6232 6233 6234 6235 6236 6237 6238 6239 6240 6241 6242 6243 6244 6245 6246 6247 6248 6249 6250 6251 6252 6253 6254 6255 6256 6257 6258 6259 6260 6261 6262 6263 6264 6265 6266 6267 6268 6269 6270 6271 6272 6273 6274 6275 6276 6277 6278 6279 6280 6281 6282 6283 6284 6285 6286 6287 6288 6289 6290 6291 6292 6293 6294 6295 6296 6297 6298 6299 6300 6301 6302 6303 6304 6305 6306 6307 6308 6309 6310 6311 6312 6313 6314 6315 6316 6317 6318 6319 6320 6321 6322 6323 6324 6325 6326 6327 6328 6329 6330 6331 6332 6333 6334 6335 6336 6337 6338 6339 6340 6341 6342 6343 6344 6345 6346 6347 6348 6349 6350 6351 6352 6353 6354 6355 6356 6357 6358 6359 6360 6361 6362 6363 6364 6365 6366 6367 6368 6369 6370 6371 6372 6373 6374 6375 6376 6377 6378 6379 6380 6381 6382 6383 6384 6385 6386 6387 6388 6389 6390 6391 6392 6393 6394 6395 6396 6397 6398 6399 6400 6401 6402 6403 6404 6405 6406 6407 6408 6409 6410 6411 6412 6413 6414 6415 6416 6417 6418 6419 6420 6421 6422 6423 6424 6425 6426 6427 6428 6429 6430 6431 6432 6433 6434 6435 6436 6437 6438 6439 6440 6441 6442 6443 6444 6445 6446 6447 6448 6449 6450 6451 6452 6453 6454 6455 6456 6457 6458 6459 6460 6461 6462 6463 6464 6465 6466 6467 6468 6469 6470 6471 6472 6473 6474 6475 6476 6477 6478 6479 6480 6481 6482 6483 6484 6485 6486 6487 6488 6489 6490 6491 6492 6493 6494 6495 6496 6497 6498 6499 6500 6501 6502 6503 6504 6505 6506 6507 6508 6509 6510 6511 6512 6513 6514 6515 6516 6517 6518 6519 6520 6521 6522 6523 6524 6525 6526 6527 6528 6529 6530 6531 6532 6533 6534 6535 6536 6537 6538 6539 6540 6541 6542 6543 6544 6545 6546 6547 6548 6549 6550 6551 6552 6553 6554 6555 6556 6557 6558 6559 6560 6561 6562 6563 6564 6565 6566 6567 6568 6569 6570 6571 6572 6573 6574 6575 6576 6577 6578 6579 6580 6581 6582 6583 6584 6585 6586 6587 6588 6589 6590 6591 6592 6593 6594 6595 6596 6597 6598 6599 6600 6601 6602 6603 6604 6605 6606 6607 6608 6609 6610 6611 6612 6613 6614 6615 6616 6617 6618 6619 6620 6621 6622 6623 6624 6625 6626 6627 6628 6629 6630 6631 6632 6633 6634 6635 6636 6637 6638 6639 6640 6641 6642 6643 6644 6645 6646 6647 6648 6649 6650 6651 6652 6653 6654 6655 6656 6657 6658 6659 6660 6661 6662 6663 6664 6665 6666 6667 6668 6669 6670 6671 6672 6673 6674 6675 6676 6677 6678 6679 6680 6681 6682 6683 6684 6685 6686 6687 6688 6689 6690 6691 6692 6693 6694 6695 6696 6697 6698 6699 6700 6701 6702 6703 6704 6705 6706 6707 6708 6709 6710 6711 6712 6713 6714 6715 6716 6717 6718 6719 6720 6721 6722 6723 6724 6725 6726 6727 6728 6729 6730 6731 6732 6733 6734 6735 6736 6737 6738 6739 6740 6741 6742 6743 6744 6745 6746 6747 6748 6749 6750 6751 6752 6753 6754 6755 6756 6757 6758 6759 6760 6761 6762 6763 6764 6765 6766 6767 6768 6769 6770 6771 6772 6773 6774 6775 6776 6777 6778 6779 6780 6781 6782 6783 6784 6785 6786 6787 6788 6789 6790 6791 6792 6793 6794 6795 6796 6797 6798 6799 6800 6801 6802 6803 6804 6805 6806 6807 6808 6809 6810 6811 6812 6813 6814 6815 6816 6817 6818 6819 6820 6821 6822 6823 6824 6825 6826 6827 6828 6829 6830 6831 6832 6833 6834 6835 6836 6837 6838 6839 6840 6841 6842 6843 6844 6845 6846 6847 6848 6849 6850 6851 6852 6853 6854 6855 6856 6857 6858 6859 6860 6861 6862 6863 6864 6865 6866 6867 6868 6869 6870 6871 6872 6873 6874 6875 6876 6877 6878 6879 6880 6881 6882 6883 6884 6885 6886 6887 6888 6889 6890 6891 6892 6893 6894 6895 6896 6897 6898 6899 6900 6901 6902 6903 6904 6905 6906 6907 6908 6909 6910 6911 6912 6913 6914 6915 6916 6917 6918 6919 6920 6921 6922 6923 6924 6925 6926 6927 6928 6929 6930 6931 6932 6933 6934 6935 6936 6937 6938 6939 6940 6941 6942 6943 6944 6945 6946 6947 6948 6949 6950 6951 6952 6953 6954 6955 6956 6957 6958 6959 6960 6961 6962 6963 6964 6965 6966 6967 6968 6969 6970 6971 6972 6973 6974 6975 6976 6977 6978 6979 6980 6981 6982 6983 6984 6985 6986 6987 6988 6989 6990 6991 6992 6993 6994 6995 6996 6997 6998 6999 7000 7001 7002 7003 7004 7005 7006 7007 7008 7009 7010 7011 7012 7013 7014 7015 7016 7017 7018 7019 7020 7021 7022 7023 7024 7025 7026 7027 7028 7029 7030 7031 7032 7033 7034 7035 7036 7037 7038 7039 7040 7041 7042 7043 7044 7045 7046 7047 7048 7049 7050 7051 7052 7053 7054 7055 7056 7057 7058 7059 7060 7061 7062 7063 7064 7065 7066 7067 7068 7069 7070 7071 7072 7073 7074 7075 7076 7077 7078 7079 7080 7081 7082 7083 7084 7085 7086 7087 7088 7089 7090 7091 7092 7093 7094 7095 7096 7097 7098 7099 7100 7101 7102 7103 7104 7105 7106 7107 7108 7109 7110 7111 7112 7113 7114 7115 7116 7117 7118 7119 7120 7121 7122 7123 7124 7125 7126 7127 7128 7129 7130 7131 7132 7133 7134 7135 7136 7137 7138 7139 7140 7141 7142 7143 7144 7145 7146 7147 7148 7149 7150 7151 7152 7153 7154 7155 7156 7157 7158 7159 7160 7161 7162 7163 7164 7165 7166 7167 7168 7169 7170 7171 7172 7173 7174 7175 7176 7177 7178 7179 7180 7181 7182 7183 7184 7185 7186 7187 7188 7189 7190 7191 7192 7193 7194 7195 7196 7197 7198 7199 7200 7201 7202 7203 7204 7205 7206 7207 7208 7209 7210 7211 7212 7213 7214 7215 7216 7217 7218 7219 7220 7221 7222 7223 7224 7225 7226 7227 7228 7229 7230 7231 7232 7233 7234 7235 7236 7237 7238 7239 7240 7241 7242 7243 7244 7245 7246 7247 7248 7249 7250 7251 7252 7253 7254 7255 7256 7257 7258 7259 7260 7261 7262 7263 7264 7265 7266 7267 7268 7269 7270 7271 7272 7273 7274 7275 7276 7277 7278 7279 7280 7281 7282 7283 7284 7285 7286 7287 7288 7289 7290 7291 7292 7293 7294 7295 7296 7297 7298 7299 7300 7301 7302 7303 7304 7305 7306 7307 7308 7309 7310 7311 7312 7313 7314 7315 7316 7317 7318 7319 7320 7321 7322 7323 7324 7325 7326 7327 7328 7329 7330 7331 7332 7333 7334 7335 7336 7337 7338 7339 7340 7341 7342 7343 7344 7345 7346 7347 7348 7349 7350 7351 7352 7353 7354 7355 7356 7357 7358 7359 7360 7361 7362 7363 7364 7365 7366 7367 7368 7369 7370 7371 7372 7373 7374 7375 7376 7377 7378 7379 7380 7381 7382 7383 7384 7385 7386 7387 7388 7389 7390 7391 7392 7393 7394 7395 7396 7397 7398 7399 7400 7401 7402 7403 7404 7405 7406 7407 7408 7409 7410 7411 7412 7413 7414 7415 7416 7417 7418 7419 7420 7421 7422 7423 7424 7425 7426 7427 7428 7429 7430 7431 7432 7433 7434 7435 7436 7437 7438 7439 7440 7441 7442 7443 7444 7445 7446 7447 7448 7449 7450 7451 7452 7453 7454 7455 7456 7457 7458 7459 7460 7461 7462 7463 7464 7465 7466 7467 7468 7469 7470 7471 7472 7473 7474 7475 7476 7477 7478 7479 7480 7481 7482 7483 7484 7485 7486 7487 7488 7489 7490 7491 7492 7493 7494 7495 7496 7497 7498 7499 7500 7501 7502 7503 7504 7505 7506 7507 7508 7509 7510 7511 7512 7513 7514 7515 7516 7517 7518 7519 7520 7521 7522 7523 7524 7525 7526 7527 7528 7529 7530 7531 7532 7533 7534 7535 7536 7537 7538 7539 7540 7541 7542 7543 7544 7545 7546 7547 7548 7549 7550 7551 7552 7553 7554 7555 7556 7557 7558 7559 7560 7561 7562 7563 7564 7565 7566 7567 7568 7569 7570 7571 7572 7573 7574 7575 7576 7577 7578 7579 7580 7581 7582 7583 7584 7585 7586 7587 7588 7589 7590 7591 7592 7593 7594 7595 7596 7597 7598 7599 7600 7601 7602 7603 7604 7605 7606 7607 7608 7609 7610 7611 7612 7613 7614 7615 7616 7617 7618 7619 7620 7621 7622 7623 7624 7625 7626 7627 7628 7629 7630 7631 7632 7633 7634 7635 7636 7637 7638 7639 7640 7641 7642 7643 7644 7645 7646 7647 7648 7649 7650 7651 7652 7653 7654 7655 7656 7657 7658 7659 7660 7661 7662 7663 7664 7665 7666 7667 7668 7669 7670 7671 7672 7673 7674 7675 7676 7677 7678 7679 7680 7681 7682 7683 7684 7685 7686 7687 7688 7689 7690 7691 7692 7693 7694 7695 7696 7697 7698 7699 7700 7701 7702 7703 7704 7705 7706 7707 7708 7709 7710 7711 7712 7713 7714 7715 7716 7717 7718 7719 7720 7721 7722 7723 7724 7725 7726 7727 7728 7729 7730 7731 7732 7733 7734 7735 7736 7737 7738 7739 7740 7741 7742 7743 7744 7745 7746 7747 7748 7749 7750 7751 7752 7753 7754 7755 7756 7757 7758 7759 7760 7761 7762 7763 7764 7765 7766 7767 7768 7769 7770 7771 7772 7773 7774 7775 7776 7777 7778 7779 7780 7781 7782 7783 7784 7785 7786 7787 7788 7789 7790 7791 7792 7793 7794 7795 7796 7797 7798 7799 7800 7801 7802 7803 7804 7805 7806 7807 7808 7809 7810 7811 7812 7813 7814 7815 7816 7817 7818 7819 7820 7821 7822 7823 7824 7825 7826 7827 7828 7829 7830 7831 7832 7833 7834 7835 7836 7837 7838 7839 7840 7841 7842 7843 7844 7845 7846 7847 7848 7849 7850 7851 7852 7853 7854 7855 7856 7857 7858 7859 7860 7861 7862 7863 7864 7865 7866 7867 7868 7869 7870 7871 7872 7873 7874 7875 7876 7877 7878 7879 7880 7881 7882 7883 7884 7885 7886 7887 7888 7889 7890 7891 7892 7893 7894 7895 7896 7897 7898 7899 7900 7901 7902 7903 7904 7905 7906 7907 7908 7909 7910 7911 7912 7913 7914 7915 7916 7917 7918 7919 7920 7921 7922 7923 7924 7925 7926 7927 7928 7929 7930 7931 7932 7933 7934 7935 7936 7937 7938 7939 7940 7941 7942 7943 7944 7945 7946 7947 7948 7949 7950 7951 7952 7953 7954 7955 7956 7957 7958 7959 7960 7961 7962 7963 7964 7965 7966 7967 7968 7969 7970 7971 7972 7973 7974 7975 7976 7977 7978 7979 7980 7981 7982 7983 7984 7985 7986 7987 7988 7989 7990 7991 7992 7993 7994 7995 7996 7997 7998 7999 8000 8001 8002 8003 8004 8005 8006 8007 8008 8009 8010 8011 8012 8013 8014 8015 8016 8017 8018 8019 8020 8021 8022 8023 8024 8025 8026 8027 8028 8029 8030 8031 8032 8033 8034 8035 8036 8037 8038 8039 8040 8041 8042 8043 8044 8045 8046 8047 8048 8049 8050 8051 8052 8053 8054 8055 8056 8057 8058 8059 8060 8061 8062 8063 8064 8065 8066 8067 8068 8069 8070 8071 8072 8073 8074 8075 8076 8077 8078 8079 8080 8081 8082 8083 8084 8085 8086 8087 8088 8089 8090 8091 8092 8093 8094 8095 8096 8097 8098 8099 8100 8101 8102 8103 8104 8105 8106 8107 8108 8109 8110 8111 8112 8113 8114 8115 8116 8117 8118 8119 8120 8121 8122 8123 8124 8125 8126 8127 8128 8129 8130 8131 8132 8133 8134 8135 8136 8137 8138 8139 8140 8141 8142 8143 8144 8145 8146 8147 8148 8149 8150 8151 8152 8153 8154 8155 8156 8157 8158 8159 8160 8161 8162 8163 8164 8165 8166 8167 8168 8169 8170 8171 8172 8173 8174 8175 8176 8177 8178 8179 8180 8181 8182 8183 8184 8185 8186 8187 8188 8189 8190 8191 8192 8193 8194 8195 8196 8197 8198 8199 8200 8201 8202 8203 8204 8205 8206 8207 8208 8209 8210 8211 8212 8213 8214 8215 8216 8217 8218 8219 8220 8221 8222 8223 8224 8225 8226 8227 8228 8229 8230 8231 8232 8233 8234 8235 8236 8237 8238 8239 8240 8241 8242 8243 8244 8245 8246 8247 8248 8249 8250 8251 8252 8253 8254 8255 8256 8257 8258 8259 8260 8261 8262 8263 8264 8265 8266 8267 8268 8269 8270 8271 8272 8273 8274 8275 8276 8277 8278 8279 8280 8281 8282 8283 8284 8285 8286 8287 8288 8289 8290 8291 8292 8293 8294 8295 8296 8297 8298 8299 8300 8301 8302 8303 8304 8305 8306 8307 8308 8309 8310 8311 8312 8313 8314 8315 8316 8317 8318 8319 8320 8321 8322 8323 8324 8325 8326 8327 8328 8329 8330 8331 8332 8333 8334 8335 8336 8337 8338 8339 8340 8341 8342 8343 8344 8345 8346 8347 8348 8349 8350 8351 8352 8353 8354 8355 8356 8357 8358 8359 8360 8361 8362 8363 8364 8365 8366 8367 8368 8369 8370 8371 8372 8373 8374 8375 8376 8377 8378 8379 8380 8381 8382 8383 8384 8385 8386 8387 8388 8389 8390 8391 8392 8393 8394 8395 8396 8397 8398 8399 8400 8401 8402 8403 8404 8405 8406 8407 8408 8409 8410 8411 8412 8413 8414 8415 8416 8417 8418 8419 8420 8421 8422 8423 8424 8425 8426 8427 8428 8429 8430 8431 8432 8433 8434 8435 8436 8437 8438 8439 8440 8441 8442 8443 8444 8445 8446 8447 8448 8449 8450 8451 8452 8453 8454 8455 8456 8457 8458 8459 8460 8461 8462 8463 8464 8465 8466 8467 8468 8469 8470 8471 8472 8473 8474 8475 8476 8477 8478 8479 8480 8481 8482 8483 8484 8485 8486 8487 8488 8489 8490 8491 8492 8493 8494 8495 8496 8497 8498 8499 8500 8501 8502 8503 8504 8505 8506 8507 8508 8509 8510 8511 8512 8513 8514 8515 8516 8517 8518 8519 8520 8521 8522 8523 8524 8525 8526 8527 8528 8529 8530 8531 8532 8533 8534 8535 8536 8537 8538 8539 8540 8541 8542 8543 8544 8545 8546 8547 8548 8549 8550 8551 8552 8553 8554 8555 8556 8557 8558 8559 8560 8561 8562 8563 8564 8565 8566 8567 8568 8569 8570 8571 8572 8573 8574 8575 8576 8577 8578 8579 8580 8581 8582 8583 8584 8585 8586 8587 8588 8589 8590 8591 8592 8593 8594 8595 8596 8597 8598 8599 8600 8601 8602 8603 8604 8605 8606 8607 8608 8609 8610 8611 8612 8613 8614 8615 8616 8617 8618 8619 8620 8621 8622 8623 8624 8625 8626 8627 8628 8629 8630 8631 8632 8633 8634 8635 8636 8637 8638 8639 8640 8641 8642 8643 8644 8645 8646 8647 8648 8649 8650 8651 8652 8653 8654 8655 8656 8657 8658 8659 8660 8661 8662 8663 8664 8665 8666 8667 8668 8669 8670 8671 8672 8673 8674 8675 8676 8677 8678 8679 8680 8681 8682 8683 8684 8685 8686 8687 8688 8689 8690 8691 8692 8693 8694 8695 8696 8697 8698 8699 8700 8701 8702 8703 8704 8705 8706 8707 8708 8709 8710 8711 8712 8713 8714 8715 8716 8717 8718 8719 8720 8721 8722 8723 8724 8725 8726 8727 8728 8729 8730 8731 8732 8733 8734 8735 8736 8737 8738 8739 8740 8741 8742 8743 8744 8745 8746 8747 8748 8749 8750 8751 8752 8753 8754 8755 8756 8757 8758 8759 8760 8761 8762 8763 8764 8765 8766 8767 8768 8769 8770 8771 8772 8773 8774 8775 8776 8777 8778 8779 8780 8781 8782 8783 8784 8785 8786 8787 8788 8789 8790 8791 8792 8793 8794 8795 8796 8797 8798 8799 8800 8801 8802 8803 8804 8805 8806 8807 8808 8809 8810 8811 8812 8813 8814 8815 8816 8817 8818 8819 8820 8821 8822 8823 8824 8825 8826 8827 8828 8829 8830 8831 8832 8833 8834 8835 8836 8837 8838 8839 8840 8841 8842 8843 8844 8845 8846 8847 8848 8849 8850 8851 8852 8853 8854 8855 8856 8857 8858 8859 8860 8861 8862 8863 8864 8865 8866 8867 8868 8869 8870 8871 8872 8873 8874 8875 8876 8877 8878 8879 8880 8881 8882 8883 8884 8885 8886 8887 8888 8889 8890 8891 8892 8893 8894 8895 8896 8897 8898 8899 8900 8901 8902 8903 8904 8905 8906 8907 8908 8909 8910 8911 8912 8913 8914 8915 8916 8917 8918 8919 8920 8921 8922 8923 8924 8925 8926 8927 8928 8929 8930 8931 8932 8933 8934 8935 8936 8937 8938 8939 8940 8941 8942 8943 8944 8945 8946 8947 8948 8949 8950 8951 8952 8953 8954 8955 8956 8957 8958 8959 8960 8961 8962 8963 8964 8965 8966 8967 8968 8969 8970 8971 8972 8973 8974 8975 8976 8977 8978 8979 8980 8981 8982 8983 8984 8985 8986 8987 8988 8989 8990 8991 8992 8993 8994 8995 8996 8997 8998 8999 9000 9001 9002 9003 9004 9005 9006 9007 9008 9009 9010 9011 9012 9013 9014 9015 9016 9017 9018 9019 9020 9021 9022 9023 9024 9025 9026 9027 9028 9029 9030 9031 9032 9033 9034 9035 9036 9037 9038 9039 9040 9041 9042 9043 9044 9045 9046 9047 9048 9049 9050 9051 9052 9053 9054 9055 9056 9057 9058 9059 9060 9061 9062 9063 9064 9065 9066 9067 9068 9069 9070 9071 9072 9073 9074 9075 9076 9077 9078 9079 9080 9081 9082 9083 9084 9085 9086 9087 9088 9089 9090 9091 9092 9093 9094 9095 9096 9097 9098 9099 9100 9101 9102 9103 9104 9105 9106 9107 9108 9109 9110 9111 9112 9113 9114 9115 9116 9117 9118 9119 9120 9121 9122 9123 9124 9125 9126 9127 9128 9129 9130 9131 9132 9133 9134 9135 9136 9137 9138 9139 9140 9141 9142 9143 9144 9145 9146 9147 9148 9149 9150 9151 9152 9153 9154 9155 9156 9157 9158 9159 9160 9161 9162 9163 9164 9165 9166 9167 9168 9169 9170 9171 9172 9173 9174 9175 9176 9177 9178 9179 9180 9181 9182 9183 9184 9185 9186 9187 9188 9189 9190 9191 9192 9193 9194 9195 9196 9197 9198 9199 9200 9201 9202 9203 9204 9205 9206 9207 9208 9209 9210 9211 9212 9213 9214 9215 9216 9217 9218 9219 9220 9221 9222 9223 9224 9225 9226 9227 9228 9229 9230 9231 9232 9233 9234 9235 9236 9237 9238 9239 9240 9241 9242 9243 9244 9245 9246 9247 9248 9249 9250 9251 9252 9253 9254 9255 9256 9257 9258 9259 9260 9261 9262 9263 9264 9265 9266 9267 9268 9269 9270 9271 9272 9273 9274 9275 9276 9277 9278 9279 9280 9281 9282 9283 9284 9285 9286 9287 9288 9289 9290 9291 9292 9293 9294 9295 9296 9297 9298 9299 9300 9301 9302 9303 9304 9305 9306 9307 9308 9309 9310 9311 9312 9313 9314 9315 9316 9317 9318 9319 9320 9321 9322 9323 9324 9325 9326 9327 9328 9329 9330 9331 9332 9333 9334 9335 9336 9337 9338 9339 9340 9341 9342 9343 9344 9345 9346 9347 9348 9349 9350 9351 9352 9353 9354 9355 9356 9357 9358 9359 9360 9361 9362 9363 9364 9365 9366 9367 9368 9369 9370 9371 9372 9373 9374 9375 9376 9377 9378 9379 9380 9381 9382 9383 9384 9385 9386 9387 9388 9389 9390 9391 9392 9393 9394 9395 9396 9397 9398 9399 9400 9401 9402 9403 9404 9405 9406 9407 9408 9409 9410 9411 9412 9413 9414 9415 9416 9417 9418 9419 9420 9421 9422 9423 9424 9425 9426 9427 9428 9429 9430 9431 9432 9433 9434 9435 9436 9437 9438 9439 9440 9441 9442 9443 9444 9445 9446 9447 9448 9449 9450 9451 9452 9453 9454 9455 9456 9457 9458 9459 9460 9461 9462 9463 9464 9465 9466 9467 9468 9469 9470 9471 9472 9473 9474 9475 9476 9477 9478 9479 9480 9481 9482 9483 9484 9485 9486 9487 9488 9489 9490 9491 9492 9493 9494 9495 9496 9497 9498 9499 9500 9501 9502 9503 9504 9505 9506 9507 9508 9509 9510 9511 9512 9513 9514 9515 9516 9517 9518 9519 9520 9521 9522 9523 9524 9525 9526 9527 9528 9529 9530 9531 9532 9533 9534 9535 9536 9537 9538 9539 9540 9541 9542 9543 9544 9545 9546 9547 9548 9549 9550 9551 9552 9553 9554 9555 9556 9557 9558 9559 9560 9561 9562 9563 9564 9565 9566 9567 9568 9569 9570 9571 9572 9573 9574 9575 9576 9577 9578 9579 9580 9581 9582 9583 9584 9585 9586 9587 9588 9589 9590 9591 9592 9593 9594 9595 9596 9597 9598 9599 9600 9601 9602 9603 9604 9605 9606 9607 9608 9609 9610 9611 9612 9613 9614 9615 9616 9617 9618 9619 9620 9621 9622 9623 9624 9625 9626 9627 9628 9629 9630 9631 9632 9633 9634 9635 9636 9637 9638 9639 9640 9641 9642 9643 9644 9645 9646 9647 9648 9649 9650 9651 9652 9653 9654 9655 9656 9657 9658 9659 9660 9661 9662 9663 9664 9665 9666 9667 9668 9669 9670 9671 9672 9673 9674 9675 9676 9677 9678 9679 9680 9681 9682 9683 9684 9685 9686 9687 9688 9689 9690 9691 9692 9693 9694 9695 9696 9697 9698 9699 9700 9701 9702 9703 9704 9705 9706 9707 9708 9709 9710 9711 9712 9713 9714 9715 9716 9717 9718 9719 9720 9721 9722 9723 9724 9725 9726 9727 9728 9729 9730 9731 9732 9733 9734 9735 9736 9737 9738 9739 9740 9741 9742 9743 9744 9745 9746 9747 9748 9749 9750 9751 9752 9753 9754 9755 9756 9757 9758 9759 9760 9761 9762 9763 9764 9765 9766 9767 9768 9769 9770 9771 9772 9773 9774 9775 9776 9777 9778 9779 9780 9781 9782 9783 9784 9785 9786 9787 9788 9789 9790 9791 9792 9793 9794 9795 9796 9797 9798 9799 9800 9801 9802 9803 9804 9805 9806 9807 9808 9809 9810 9811 9812 9813 9814 9815 9816 9817 9818 9819 9820 9821 9822 9823 9824 9825 9826 9827 9828 9829 9830 9831 9832 9833 9834 9835 9836 9837 9838 9839 9840 9841 9842 9843 9844 9845 9846 9847 9848 9849 9850 9851 9852 9853 9854 9855 9856 9857 9858 9859 9860 9861 9862 9863 9864 9865 9866 9867 9868 9869 9870 9871 9872 9873 9874 9875 9876 9877 9878 9879 9880 9881 9882 9883 9884 9885 9886 9887 9888 9889 9890 9891 9892 9893 9894 9895 9896 9897 9898 9899 9900 9901 9902 9903 9904 9905 9906 9907 9908 9909 9910 9911 9912 9913 9914 9915 9916 9917 9918 9919 9920 9921 9922 9923 9924 9925 9926 9927 9928 9929 9930 9931 9932 9933 9934 9935 9936 9937 9938 9939 9940 9941 9942 9943 9944 9945 9946 9947 9948 9949 9950 9951 9952 9953 9954 9955 9956 9957 9958 9959 9960 9961 9962 9963 9964 9965 9966 9967 9968 9969 9970 9971 9972 9973 9974 9975 9976 9977 9978 9979 9980 9981 9982 9983 9984 9985 9986 9987 9988 9989 9990 9991 9992 9993 9994 9995 9996 9997 9998 9999 10000 10001 10002 10003 10004 10005 10006 10007 10008 10009 10010 10011 10012 10013 10014 10015 10016 10017 10018 10019 10020 10021 10022 10023 10024 10025 10026 10027 10028 10029 10030 10031 10032 10033 10034 10035 10036 10037 10038 10039 10040 10041 10042 10043 10044 10045 10046 10047 10048 10049 10050 10051 10052 10053 10054 10055 10056 10057 10058 10059 10060 10061 10062 10063 10064 10065 10066 10067 10068 10069 10070 10071 10072 10073 10074 10075 10076 10077 10078 10079 10080 10081 10082 10083 10084 10085 10086 10087 10088 10089 10090 10091 10092 10093 10094 10095 10096 10097 10098 10099 10100 10101 10102 10103 10104 10105 10106 10107 10108 10109 10110 10111 10112 10113 10114 10115 10116 10117 10118 10119 10120 10121 10122 10123 10124 10125 10126 10127 10128 10129 10130 10131 10132 10133 10134 10135 10136 10137 10138 10139 10140 10141 10142 10143 10144 10145 10146 10147 10148 10149 10150 10151 10152 10153 10154 10155 10156 10157 10158 10159 10160 10161 10162 10163 10164 10165 10166 10167 10168 10169 10170 10171 10172 10173 10174 10175 10176 10177 10178 10179 10180 10181 10182 10183 10184 10185 10186 10187 10188 10189 10190 10191 10192 10193 10194 10195 10196 10197 10198 10199 10200 10201 10202 10203 10204 10205 10206 10207 10208 10209 10210 10211 10212 10213 10214 10215 10216 10217 10218 10219 10220 10221 10222 10223 10224 10225 10226 10227 10228 10229 10230 10231 10232 10233 10234 10235 10236 10237 10238 10239 10240 10241 10242 10243 10244 10245 10246 10247 10248 10249 10250 10251 10252 10253 10254 10255 10256 10257 10258 10259 10260 10261 10262 10263 10264 10265 10266 10267 10268 10269 10270 10271 10272 10273 10274 10275 10276 10277 10278 10279 10280 10281 10282 10283 10284 10285 10286 10287 10288 10289 10290 10291 10292 10293 10294 10295 10296 10297 10298 10299 10300 10301 10302 10303 10304 10305 10306 10307 10308 10309 10310 10311 10312 10313 10314 10315 10316 10317 10318 10319 10320 10321 10322 10323 10324 10325 10326 10327 10328 10329 10330 10331 10332 10333 10334 10335 10336 10337 10338 10339 10340 10341 10342 10343 10344 10345 10346 10347 10348 10349 10350 10351 10352 10353 10354 10355 10356 10357 10358 10359 10360 10361 10362 10363 10364 10365 10366 10367 10368 10369 10370 10371 10372 10373 10374 10375 10376 10377 10378 10379 10380 10381 10382 10383 10384 10385 10386 10387 10388 10389 10390 10391 10392 10393 10394 10395 10396 10397 10398 10399 10400 10401 10402 10403 10404 10405 10406 10407 10408 10409 10410 10411 10412 10413 10414 10415 10416 10417 10418 10419 10420 10421 10422 10423 10424 10425 10426 10427 10428 10429 10430 10431 10432 10433 10434 10435 10436 10437 10438 10439 10440 10441 10442 10443 10444 10445 10446 10447 10448 10449 10450 10451 10452 10453 10454 10455 10456 10457 10458 10459 10460 10461 10462 10463 10464 10465 10466 10467 10468 10469 10470 10471 10472 10473 10474 10475 10476 10477 10478 10479 10480 10481 10482 10483 10484 10485 10486 10487 10488 10489 10490 10491 10492 10493 10494 10495 10496 10497 10498 10499 10500 10501 10502 10503 10504 10505 10506 10507 10508 10509 10510 10511 10512 10513 10514 10515 10516 10517 10518 10519 10520 10521 10522 10523 10524 10525 10526 10527 10528 10529 10530 10531 10532 10533 10534 10535 10536 10537 10538 10539 10540 10541 10542 10543 10544 10545 10546 10547 10548 10549 10550 10551 10552 10553 10554 10555 10556 10557 10558 10559 10560 10561 10562 10563 10564 10565 10566 10567 10568 10569 10570 10571 10572 10573 10574 10575 10576 10577 10578 10579 10580 10581 10582 10583 10584 10585 10586 10587 10588 10589 10590 10591 10592 10593 10594 10595 10596 10597 10598 10599 10600 10601 10602 10603 10604 10605 10606 10607 10608 10609 10610 10611 10612 10613 10614 10615 10616 10617 10618 10619 10620 10621 10622 10623 10624 10625 10626 10627 10628 10629 10630 10631 10632 10633 10634 10635 10636 10637 10638 10639 10640 10641 10642 10643 10644 10645 10646 10647 10648 10649 10650 10651 10652 10653 10654 10655 10656 10657 10658 10659 10660 10661 10662 10663 10664 10665 10666 10667 10668 10669 10670 10671 10672 10673 10674 10675 10676 10677 10678 10679 10680 10681 10682 10683 10684 10685 10686 10687 10688 10689 10690 10691 10692 10693 10694 10695 10696 10697 10698 10699 10700 10701 10702 10703 10704 10705 10706 10707 10708 10709 10710 10711 10712 10713 10714 10715 10716 10717 10718 10719 10720 10721 10722 10723 10724 10725 10726 10727 10728 10729 10730 10731 10732 10733 10734 10735 10736 10737 10738 10739 10740 10741 10742 10743 10744 10745 10746 10747 10748 10749 10750 10751 10752 10753 10754 10755 10756 10757 10758 10759 10760 10761 10762 10763 10764 10765 10766 10767 10768 10769 10770 10771 10772 10773 10774 10775 10776 10777 10778 10779 10780 10781 10782 10783 10784 10785 10786 10787 10788 10789 10790 10791 10792 10793 10794 10795 10796 10797 10798 10799 10800 10801 10802 10803 10804 10805 10806 10807 10808 10809 10810 10811 10812 10813 10814 10815 10816 10817 10818 10819 10820 10821 10822 10823 10824 10825 10826 10827 10828 10829 10830 10831 10832 10833 10834 10835 10836 10837 10838 10839 10840 10841 10842 10843 10844 10845 10846 10847 10848 10849 10850 10851 10852 10853 10854 10855 10856 10857 10858 10859 10860 10861 10862 10863 10864 10865 10866 10867 10868 10869 10870 10871 10872 10873 10874 10875 10876 10877 10878 10879 10880 10881 10882 10883 10884 10885 10886 10887 10888 10889 10890 10891 10892 10893 10894 10895 10896 10897 10898 10899 10900 10901 10902 10903 10904 10905 10906 10907 10908 10909 10910 10911 10912 10913 10914 10915 10916 10917 10918 10919 10920 10921 10922 10923 10924 10925 10926 10927 10928 10929 10930 10931 10932 10933 10934 10935 10936 10937 10938 10939 10940 10941 10942 10943 10944 10945 10946 10947 10948 10949 10950 10951 10952 10953 10954 10955 10956 10957 10958 10959 10960 10961 10962 10963 10964 10965 10966 10967 10968 10969 10970 10971 10972 10973 10974 10975 10976 10977 10978 10979 10980 10981 10982 10983 10984 10985 10986 10987 10988 10989 10990 10991 10992 10993 10994 10995 10996 10997 10998 10999 11000 11001 11002 11003 11004 11005 11006 11007 11008 11009 11010 11011 11012 11013 11014 11015 11016 11017 11018 11019 11020 11021 11022 11023 11024 11025 11026 11027 11028 11029 11030 11031 11032 11033 11034 11035 11036 11037 11038 11039 11040 11041 11042 11043 11044 11045 11046 11047 11048 11049 11050 11051 11052 11053 11054 11055 11056 11057 11058 11059 11060 11061 11062 11063 11064 11065 11066 11067 11068 11069 11070 11071 11072 11073 11074 11075 11076 11077 11078 11079 11080 11081 11082 11083 11084 11085 11086 11087 11088 11089 11090 11091 11092 11093 11094 11095 11096 11097 11098 11099 11100 11101 11102 11103 11104 11105 11106 11107 11108 11109 11110 11111 11112 11113 11114 11115 11116 11117 11118 11119 11120 11121 11122 11123 11124 11125 11126 11127 11128 11129 11130 11131 11132 11133 11134 11135 11136 11137 11138 11139 11140 11141 11142 11143 11144 11145 11146 11147 11148 11149 11150 11151 11152 11153 11154 11155 11156 11157 11158 11159 11160 11161 11162 11163 11164 11165 11166 11167 11168 11169 11170 11171 11172 11173 11174 11175 11176 11177 11178 11179 11180 11181 11182 11183 11184 11185 11186 11187 11188 11189 11190 11191 11192 11193 11194 11195 11196 11197 11198 11199 11200 11201 11202 11203 11204 11205 11206 11207 11208 11209 11210 11211 11212 11213 11214 11215 11216 11217 11218 11219 11220 11221 11222 11223 11224 11225 11226 11227 11228 11229 11230 11231 11232 11233 11234 11235 11236 11237 11238 11239 11240 11241 11242 11243 11244 11245 11246 11247 11248 11249 11250 11251 11252 11253 11254 11255 11256 11257 11258 11259 11260 11261 11262 11263 11264 11265 11266 11267 11268 11269 11270 11271 11272 11273 11274 11275 11276 11277 11278 11279 11280 11281 11282 11283 11284 11285 11286 11287 11288 11289 11290 11291 11292 11293 11294 11295 11296 11297 11298 11299 11300 11301 11302 11303 11304 11305 11306 11307 11308 11309 11310 11311 11312 11313 11314 11315 11316 11317 11318 11319 11320 11321 11322 11323 11324 11325 11326 11327 11328 11329 11330 11331 11332 11333 11334 11335 11336 11337 11338 11339 11340 11341 11342 11343 11344 11345 11346 11347 11348 11349 11350 11351 11352 11353 11354 11355 11356 11357 11358 11359 11360 11361 11362 11363 11364 11365 11366 11367 11368 11369 11370 11371 11372 11373 11374 11375 11376 11377 11378 11379 11380 11381 11382 11383 11384 11385 11386 11387 11388 11389 11390 11391 11392 11393 11394 11395 11396 11397 11398 11399 11400 11401 11402 11403 11404 11405 11406 11407 11408 11409 11410 11411 11412 11413 11414 11415 11416 11417 11418 11419 11420 11421 11422 11423 11424 11425 11426 11427 11428 11429 11430 11431 11432 11433 11434 11435 11436 11437 11438 11439 11440 11441 11442 11443 11444 11445 11446 11447 11448 11449 11450 11451 11452 11453 11454 11455 11456 11457 11458 11459 11460 11461 11462 11463 11464 11465 11466 11467 11468 11469 11470 11471 11472 11473 11474 11475 11476 11477 11478 11479 11480 11481 11482 11483 11484 11485 11486 11487 11488 11489 11490 11491 11492 11493 11494 11495 11496 11497 11498 11499 11500 11501 11502 11503 11504 11505 11506 11507 11508 11509 11510 11511 11512 11513 11514 11515 11516 11517 11518 11519 11520 11521 11522 11523 11524 11525 11526 11527 11528 11529 11530 11531 11532 11533 11534 11535 11536 11537 11538 11539 11540 11541 11542 11543 11544 11545 11546 11547 11548 11549 11550 11551 11552 11553 11554 11555 11556 11557 11558 11559 11560 11561 11562 11563 11564 11565 11566 11567 11568 11569 11570 11571 11572 11573 11574 11575 11576 11577 11578 11579 11580 11581 11582 11583 11584 11585 11586 11587 11588 11589 11590 11591 11592 11593 11594 11595 11596 11597 11598 11599 11600 11601 11602 11603 11604 11605 11606 11607 11608 11609 11610 11611 11612 11613 11614 11615 11616 11617 11618 11619 11620 11621 11622 11623 11624 11625 11626 11627 11628 11629 11630 11631 11632 11633 11634 11635 11636 11637 11638 11639 11640 11641 11642 11643 11644 11645 11646 11647 11648 11649 11650 11651 11652 11653 11654 11655 11656 11657 11658 11659 11660 11661 11662 11663 11664 11665 11666 11667 11668 11669 11670 11671 11672 11673 11674 11675 11676 11677 11678 11679 11680 11681 11682 11683 11684 11685 11686 11687 11688 11689 11690 11691 11692 11693 11694 11695 11696 11697 11698 11699 11700 11701 11702 11703 11704 11705 11706 11707 11708 11709 11710 11711 11712 11713 11714 11715 11716 11717 11718 11719 11720 11721 11722 11723 11724 11725 11726 11727 11728 11729 11730 11731 11732 11733 11734 11735 11736 11737 11738 11739 11740 11741 11742 11743 11744 11745 11746 11747 11748 11749 11750 11751 11752 11753 11754 11755 11756 11757 11758 11759 11760 11761 11762 11763 11764 11765 11766 11767 11768 11769 11770 11771 11772 11773 11774 11775 11776 11777 11778 11779 11780 11781 11782 11783 11784 11785 11786 11787 11788 11789 11790 11791 11792 11793 11794 11795 11796 11797 11798 11799 11800 11801 11802 11803 11804 11805 11806 11807 11808 11809 11810 11811 11812 11813 11814 11815 11816 11817 11818 11819 11820 11821 11822 11823 11824 11825 11826 11827 11828 11829 11830 11831 11832 11833 11834 11835 11836 11837 11838 11839 11840 11841 11842 11843 11844 11845 11846 11847 11848 11849 11850 11851 11852 11853 11854 11855 11856 11857 11858 11859 11860 11861 11862 11863 11864 11865 11866 11867 11868 11869 11870 11871 11872 11873 11874 11875 11876 11877 11878 11879 11880 11881 11882 11883 11884 11885 11886 11887 11888 11889 11890 11891 11892 11893 11894 11895 11896 11897 11898 11899 11900 11901 11902 11903 11904 11905 11906 11907 11908 11909 11910 11911 11912 11913 11914 11915 11916 11917 11918 11919 11920 11921 11922 11923 11924 11925 11926 11927 11928 11929 11930 11931 11932 11933 11934 11935 11936 11937 11938 11939 11940 11941 11942 11943 11944 11945 11946 11947 11948 11949 11950 11951 11952 11953 11954 11955 11956 11957 11958 11959 11960 11961 11962 11963 11964 11965 11966 11967 11968 11969 11970 11971 11972 11973 11974 11975 11976 11977 11978 11979 11980 11981 11982 11983 11984 11985 11986 11987 11988 11989 11990 11991 11992 11993 11994 11995 11996 11997 11998 11999 12000 12001 12002 12003 12004 12005 12006 12007 12008 12009 12010 12011 12012 12013 12014 12015 12016 12017 12018 12019 12020 12021 12022 12023 12024 12025 12026 12027 12028 12029 12030 12031 12032 12033 12034 12035 12036 12037 12038 12039 12040 12041 12042 12043 12044 12045 12046 12047 12048 12049 12050 12051 12052 12053 12054 12055 12056 12057 12058 12059 12060 12061 12062 12063 12064 12065 12066 12067 12068 12069 12070 12071 12072 12073 12074 12075 12076 12077 12078 12079 12080 12081 12082 12083 12084 12085 12086 12087 12088 12089 12090 12091 12092 12093 12094 12095 12096 12097 12098 12099 12100 12101 12102 12103 12104 12105 12106 12107 12108 12109 12110 12111 12112 12113 12114 12115 12116 12117 12118 12119 12120 12121 12122 12123 12124 12125 12126 12127 12128 12129 12130 12131 12132 12133 12134 12135 12136 12137 12138 12139 12140 12141 12142 12143 12144 12145 12146 12147 12148 12149 12150 12151 12152 12153 12154 12155 12156 12157 12158 12159 12160 12161 12162 12163 12164 12165 12166 12167 12168 12169 12170 12171 12172 12173 12174 12175 12176 12177 12178 12179 12180 12181 12182 12183 12184 12185 12186 12187 12188 12189 12190 12191 12192 12193 12194 12195 12196 12197 12198 12199 12200 12201 12202 12203 12204 12205 12206 12207 12208 12209 12210 12211 12212 12213 12214 12215 12216 12217 12218 12219 12220 12221 12222 12223 12224 12225 12226 12227 12228 12229 12230 12231 12232 12233 12234 12235 12236 12237 12238 12239 12240 12241 12242 12243 12244 12245 12246 12247 12248 12249 12250 12251 12252 12253 12254 12255 12256 12257 12258 12259 12260 12261 12262 12263 12264 12265 12266 12267 12268 12269 12270 12271 12272 12273 12274 12275 12276 12277 12278 12279 12280 12281 12282 12283 12284 12285 12286 12287 12288 12289 12290 12291 12292 12293 12294 12295 12296 12297 12298 12299 12300 12301 12302 12303 12304 12305 12306 12307 12308 12309 12310 12311 12312 12313 12314 12315 12316 12317 12318 12319 12320 12321 12322 12323 12324 12325 12326 12327 12328 12329 12330 12331 12332 12333 12334 12335 12336 12337 12338 12339 12340 12341 12342 12343 12344 12345 12346 12347 12348 12349 12350 12351 12352 12353 12354 12355 12356 12357 12358 12359 12360 12361 12362 12363 12364 12365 12366 12367 12368 12369 12370 12371 12372 12373 12374 12375 12376 12377 12378 12379 12380 12381 12382 12383 12384 12385 12386 12387 12388 12389 12390 12391 12392 12393 12394 12395 12396 12397 12398 12399 12400 12401 12402 12403 12404 12405 12406 12407 12408 12409 12410 12411 12412 12413 12414 12415 12416 12417 12418 12419 12420 12421 12422 12423 12424 12425 12426 12427 12428 12429 12430 12431 12432 12433 12434 12435 12436 12437 12438 12439 12440 12441 12442 12443 12444 12445 12446 12447 12448 12449 12450 12451 12452 12453 12454 12455 12456 12457 12458 12459 12460 12461 12462 12463 12464 12465 12466 12467 12468 12469 12470 12471 12472 12473 12474 12475 12476 12477 12478 12479 12480 12481 12482 12483 12484 12485 12486 12487 12488 12489 12490 12491 12492 12493 12494 12495 12496 12497 12498 12499 12500 12501 12502 12503 12504 12505 12506 12507 12508 12509 12510 12511 12512 12513 12514 12515 12516 12517 12518 12519 12520 12521 12522 12523 12524 12525 12526 12527 12528 12529 12530 12531 12532 12533 12534 12535 12536 12537 12538 12539 12540 12541 12542 12543 12544 12545 12546 12547 12548 12549 12550 12551 12552 12553 12554 12555 12556 12557 12558 12559 12560 12561 12562 12563 12564 12565 12566 12567 12568 12569 12570 12571 12572 12573 12574 12575 12576 12577 12578 12579 12580 12581 12582 12583 12584 12585 12586 12587 12588 12589 12590 12591 12592 12593 12594 12595 12596 12597 12598 12599 12600 12601 12602 12603 12604 12605 12606 12607 12608 12609 12610 12611 12612 12613 12614 12615 12616 12617 12618 12619 12620 12621 12622 12623 12624 12625 12626 12627 12628 12629 12630 12631 12632 12633 12634 12635 12636 12637 12638 12639 12640 12641 12642 12643 12644 12645 12646 12647 12648 12649 12650 12651 12652 12653 12654 12655 12656 12657 12658 12659 12660 12661 12662 12663 12664 12665 12666 12667 12668 12669 12670 12671 12672 12673 12674 12675 12676 12677 12678 12679 12680 12681 12682 12683 12684 12685 12686 12687 12688 12689 12690 12691 12692 12693 12694 12695 12696 12697 12698 12699 12700 12701 12702 12703 12704 12705 12706 12707 12708 12709 12710 12711 12712 12713 12714 12715 12716 12717 12718 12719 12720 12721 12722 12723 12724 12725 12726 12727 12728 12729 12730 12731 12732 12733 12734 12735 12736 12737 12738 12739 12740 12741 12742 12743 12744 12745 12746 12747 12748 12749 12750 12751 12752 12753 12754 12755 12756 12757 12758 12759 12760 12761 12762 12763 12764 12765 12766 12767 12768 12769 12770 12771 12772 12773 12774 12775 12776 12777 12778 12779 12780 12781 12782 12783 12784 12785 12786 12787 12788 12789 12790 12791 12792 12793 12794 12795 12796 12797 12798 12799 12800 12801 12802 12803 12804 12805 12806 12807 12808 12809 12810 12811 12812 12813 12814 12815 12816 12817 12818 12819 12820 12821 12822 12823 12824 12825 12826 12827 12828 12829 12830 12831 12832 12833 12834 12835 12836 12837 12838 12839 12840 12841 12842 12843 12844 12845 12846 12847 12848 12849 12850 12851 12852 12853 12854 12855 12856 12857 12858 12859 12860 12861 12862 12863 12864 12865 12866 12867 12868 12869 12870 12871 12872 12873 12874 12875 12876 12877 12878 12879 12880 12881 12882 12883 12884 12885 12886 12887 12888 12889 12890 12891 12892 12893 12894 12895 12896 12897 12898 12899 12900 12901 12902 12903 12904 12905 12906 12907 12908 12909 12910 12911 12912 12913 12914 12915 12916 12917 12918 12919 12920 12921 12922 12923 12924 12925 12926 12927 12928 12929 12930 12931 12932 12933 12934 12935 12936 12937 12938 12939 12940 12941 12942 12943 12944 12945 12946 12947 12948 12949 12950 12951 12952 12953 12954 12955 12956 12957 12958 12959 12960 12961 12962 12963 12964 12965 12966 12967 12968 12969 12970 12971 12972 12973 12974 12975 12976 12977 12978 12979 12980 12981 12982 12983 12984 12985 12986 12987 12988 12989 12990 12991 12992 12993 12994 12995 12996 12997 12998 12999 13000 13001 13002 13003 13004 13005 13006 13007 13008 13009 13010 13011 13012 13013 13014 13015 13016 13017 13018 13019 13020 13021 13022 13023 13024 13025 13026 13027 13028 13029 13030 13031 13032 13033 13034 13035 13036 13037 13038 13039 13040 13041 13042 13043 13044 13045 13046 13047 13048 13049 13050 13051 13052 13053 13054 13055 13056 13057 13058 13059 13060 13061 13062 13063 13064 13065 13066 13067 13068 13069 13070 13071 13072 13073 13074 13075 13076 13077 13078 13079 13080 13081 13082 13083 13084 13085 13086 13087 13088 13089 13090 13091 13092 13093 13094 13095 13096 13097 13098 13099 13100 13101 13102 13103 13104 13105 13106 13107 13108 13109 13110 13111 13112 13113 13114 13115 13116 13117 13118 13119 13120 13121 13122 13123 13124 13125 13126 13127 13128 13129 13130 13131 13132 13133 13134 13135 13136 13137 13138 13139 13140 13141 13142 13143 13144 13145 13146 13147 13148 13149 13150 13151 13152 13153 13154 13155 13156 13157 13158 13159 13160 13161 13162 13163 13164 13165 13166 13167 13168 13169 13170 13171 13172 13173 13174 13175 13176 13177 13178 13179 13180 13181 13182 13183 13184 13185 13186 13187 13188 13189 13190 13191 13192 13193 13194 13195 13196 13197 13198 13199 13200 13201 13202 13203 13204 13205 13206 13207 13208 13209 13210 13211 13212 13213 13214 13215 13216 13217 13218 13219 13220 13221 13222 13223 13224 13225 13226 13227 13228 13229 13230 13231 13232 13233 13234 13235 13236 13237 13238 13239 13240 13241 13242 13243 13244 13245 13246 13247 13248 13249 13250 13251 13252 13253 13254 13255 13256 13257 13258 13259 13260 13261 13262 13263 13264 13265 13266 13267 13268 13269 13270 13271 13272 13273 13274 13275 13276 13277 13278 13279 13280 13281 13282 13283 13284 13285 13286 13287 13288 13289 13290 13291 13292 13293 13294 13295 13296 13297 13298 13299 13300 13301 13302 13303 13304 13305 13306 13307 13308 13309 13310 13311 13312 13313 13314 13315 13316 13317 13318 13319 13320 13321 13322 13323 13324 13325 13326 13327 13328 13329 13330 13331 13332 13333 13334 13335 13336 13337 13338 13339 13340 13341 13342 13343 13344 13345 13346 13347 13348 13349 13350 13351 13352 13353 13354 13355 13356 13357 13358 13359 13360 13361 13362 13363 13364 13365 13366 13367 13368 13369 13370 13371 13372 13373 13374 13375 13376 13377 13378 13379 13380 13381 13382 13383 13384 13385 13386 13387 13388 13389 13390 13391 13392 13393 13394 13395 13396 13397 13398 13399 13400 13401 13402 13403 13404 13405 13406 13407 13408 13409 13410 13411 13412 13413 13414 13415 13416 13417 13418 13419 13420 13421 13422 13423 13424 13425 13426 13427 13428 13429 13430 13431 13432 13433 13434 13435 13436 13437 13438 13439 13440 13441 13442 13443 13444 13445 13446 13447 13448 13449 13450 13451 13452 13453 13454 13455 13456 13457 13458 13459 13460 13461 13462 13463 13464 13465 13466 13467 13468 13469 13470 13471 13472 13473 13474 13475 13476 13477 13478 13479 13480 13481 13482 13483 13484 13485 13486 13487 13488 13489 13490 13491 13492 13493 13494 13495 13496 13497 13498 13499 13500 13501 13502 13503 13504 13505 13506 13507 13508 13509 13510 13511 13512 13513 13514 13515 13516 13517 13518 13519 13520 13521 13522 13523 13524 13525 13526 13527 13528 13529 13530 13531 13532 13533 13534 13535 13536 13537 13538 13539 13540 13541 13542 13543 13544 13545 13546 13547 13548 13549 13550 13551 13552 13553 13554 13555 13556 13557 13558 13559 13560 13561 13562 13563 13564 13565 13566 13567 13568 13569 13570 13571 13572 13573 13574 13575 13576 13577 13578 13579 13580 13581 13582 13583 13584 13585 13586 13587 13588 13589 13590 13591 13592 13593 13594 13595 13596 13597 13598 13599 13600 13601 13602 13603 13604 13605 13606 13607 13608 13609 13610 13611 13612 13613 13614 13615 13616 13617 13618 13619 13620 13621 13622 13623 13624 13625 13626 13627 13628 13629 13630 13631 13632 13633 13634 13635 13636 13637 13638 13639 13640 13641 13642 13643 13644 13645 13646 13647 13648 13649 13650 13651 13652 13653 13654 13655 13656 13657 13658 13659 13660 13661 13662 13663 13664 13665 13666 13667 13668 13669 13670 13671 13672 13673 13674 13675 13676 13677 13678 13679 13680 13681 13682 13683 13684 13685 13686 13687 13688 13689 13690 13691 13692 13693 13694 13695 13696 13697 13698 13699 13700 13701 13702 13703 13704 13705 13706 13707 13708 13709 13710 13711 13712 13713 13714 13715 13716 13717 13718 13719 13720 13721 13722 13723 13724 13725 13726 13727 13728 13729 13730 13731 13732 13733 13734 13735 13736 13737 13738 13739 13740 13741 13742 13743 13744 13745 13746 13747 13748 13749 13750 13751 13752 13753 13754 13755 13756 13757 13758 13759 13760 13761 13762 13763 13764 13765 13766 13767 13768 13769 13770 13771 13772 13773 13774 13775 13776 13777 13778 13779 13780 13781 13782 13783 13784 13785 13786 13787 13788 13789 13790 13791 13792 13793 13794 13795 13796 13797 13798 13799 13800 13801 13802 13803 13804 13805 13806 13807 13808 13809 13810 13811 13812 13813 13814 13815 13816 13817 13818 13819 13820 13821 13822 13823 13824 13825 13826 13827 13828 13829 13830 13831 13832 13833 13834 13835 13836 13837 13838 13839 13840 13841 13842 13843 13844 13845 13846 13847 13848 13849 13850 13851 13852 13853 13854 13855 13856 13857 13858 13859 13860 13861 13862 13863 13864 13865 13866 13867 13868 13869 13870 13871 13872 13873 13874 13875 13876 13877 13878 13879 13880 13881 13882 13883 13884 13885 13886 13887 13888 13889 13890 13891 13892 13893 13894 13895 13896 13897 13898 13899 13900 13901 13902 13903 13904 13905 13906 13907 13908 13909 13910 13911 13912 13913 13914 13915 13916 13917 13918 13919 13920 13921 13922 13923 13924 13925 13926 13927 13928 13929 13930 13931 13932 13933 13934 13935 13936 13937 13938 13939 13940 13941 13942 13943 13944 13945 13946 13947 13948 13949 13950 13951 13952 13953 13954 13955 13956 13957 13958 13959 13960 13961 13962 13963 13964 13965 13966 13967 13968 13969 13970 13971 13972 13973 13974 13975 13976 13977 13978 13979 13980 13981 13982 13983 13984 13985 13986 13987 13988 13989 13990 13991 13992 13993 13994 13995 13996 13997 13998 13999 14000 14001 14002 14003 14004 14005 14006 14007 14008 14009 14010 14011 14012 14013 14014 14015 14016 14017 14018 14019 14020 14021 14022 14023 14024 14025 14026 14027 14028 14029 14030 14031 14032 14033 14034 14035 14036 14037 14038 14039 14040 14041 14042 14043 14044 14045 14046 14047 14048 14049 14050 14051 14052 14053 14054 14055 14056 14057 14058 14059 14060 14061 14062 14063 14064 14065 14066 14067 14068 14069 14070 14071 14072 14073 14074 14075 14076 14077 14078 14079 14080 14081 14082 14083 14084 14085 14086 14087 14088 14089 14090 14091 14092 14093 14094 14095 14096 14097 14098 14099 14100 14101 14102 14103 14104 14105 14106 14107 14108 14109 14110 14111 14112 14113 14114 14115 14116 14117 14118 14119 14120 14121 14122 14123 14124 14125 14126 14127 14128 14129 14130 14131 14132 14133 14134 14135 14136 14137 14138 14139 14140 14141 14142 14143 14144 14145 14146 14147 14148 14149 14150 14151 14152 14153 14154 14155 14156 14157 14158 14159 14160 14161 14162 14163 14164 14165 14166 14167 14168 14169 14170 14171 14172 14173 14174 14175 14176 14177 14178 14179 14180 14181 14182 14183 14184 14185 14186 14187 14188 14189 14190 14191 14192 14193 14194 14195 14196 14197 14198 14199 14200 14201 14202 14203 14204 14205 14206 14207 14208 14209 14210 14211 14212 14213 14214 14215 14216 14217 14218 14219 14220 14221 14222 14223 14224 14225 14226 14227 14228 14229 14230 14231 14232 14233 14234 14235 14236 14237 14238 14239 14240 14241 14242 14243 14244 14245 14246 14247 14248 14249 14250 14251 14252 14253 14254 14255 14256 14257 14258 14259 14260 14261 14262 14263 14264 14265 14266 14267 14268 14269 14270 14271 14272 14273 14274 14275 14276 14277 14278 14279 14280 14281 14282 14283 14284 14285 14286 14287 14288 14289 14290 14291 14292 14293 14294 14295 14296 14297 14298 14299 14300 14301 14302 14303 14304 14305 14306 14307 14308 14309 14310 14311 14312 14313 14314 14315 14316 14317 14318 14319 14320 14321 14322 14323 14324 14325 14326 14327 14328 14329 14330 14331 14332 14333 14334 14335 14336 14337 14338 14339 14340 14341 14342 14343 14344 14345 14346 14347 14348 14349 14350 14351 14352 14353 14354 14355 14356 14357 14358 14359 14360 14361 14362 14363 14364 14365 14366 14367 14368 14369 14370 14371 14372 14373 14374 14375 14376 14377 14378 14379 14380 14381 14382 14383 14384 14385 14386 14387 14388 14389 14390 14391 14392 14393 14394 14395 14396 14397 14398 14399 14400 14401 14402 14403 14404 14405 14406 14407 14408 14409 14410 14411 14412 14413 14414 14415 14416 14417 14418 14419 14420 14421 14422 14423 14424 14425 14426 14427 14428 14429 14430 14431 14432 14433 14434 14435 14436 14437 14438 14439 14440 14441 14442 14443 14444 14445 14446 14447 14448 14449 14450 14451 14452 14453 14454 14455 14456 14457 14458 14459 14460 14461 14462 14463 14464 14465 14466 14467 14468 14469 14470 14471 14472 14473 14474 14475 14476 14477 14478 14479 14480 14481 14482 14483 14484 14485 14486 14487 14488 14489 14490 14491 14492 14493 14494 14495 14496 14497 14498 14499 14500 14501 14502 14503 14504 14505 14506 14507 14508 14509 14510 14511 14512 14513 14514 14515 14516 14517 14518 14519 14520 14521 14522 14523 14524 14525 14526 14527 14528 14529 14530 14531 14532 14533 14534 14535 14536 14537 14538 14539 14540 14541 14542 14543 14544 14545 14546 14547 14548 14549 14550 14551 14552 14553 14554 14555 14556 14557 14558 14559 14560 14561 14562 14563 14564 14565 14566 14567 14568 14569 14570 14571 14572 14573 14574 14575 14576 14577 14578 14579 14580 14581 14582 14583 14584 14585 14586 14587 14588 14589 14590 14591 14592 14593 14594 14595 14596 14597 14598 14599 14600 14601 14602 14603 14604 14605 14606 14607 14608 14609 14610 14611 14612 14613 14614 14615 14616 14617 14618 14619 14620 14621 14622 14623 14624 14625 14626 14627 14628 14629 14630 14631 14632 14633 14634 14635 14636 14637 14638 14639 14640 14641 14642 14643 14644 14645 14646 14647 14648 14649 14650 14651 14652 14653 14654 14655 14656 14657 14658 14659 14660 14661 14662 14663 14664 14665 14666 14667 14668 14669 14670 14671 14672 14673 14674 14675 14676 14677 14678 14679 14680 14681 14682 14683 14684 14685 14686 14687 14688 14689 14690 14691 14692 14693 14694 14695 14696 14697 14698 14699 14700 14701 14702 14703 14704 14705 14706 14707 14708 14709 14710 14711 14712 14713 14714 14715 14716 14717 14718 14719 14720 14721 14722 14723 14724 14725 14726 14727 14728 14729 14730 14731 14732 14733 14734 14735 14736 14737 14738 14739 14740 14741 14742 14743 14744 14745 14746 14747 14748 14749 14750 14751 14752 14753 14754 14755 14756 14757 14758 14759 14760 14761 14762 14763 14764 14765 14766 14767 14768 14769 14770 14771 14772 14773 14774 14775 14776 14777 14778 14779 14780 14781 14782 14783 14784 14785 14786 14787 14788 14789 14790 14791 14792 14793 14794 14795 14796 14797 14798 14799 14800 14801 14802 14803 14804 14805 14806 14807 14808 14809 14810 14811 14812 14813 14814 14815 14816 14817 14818 14819 14820
diff --git a/include/SDL.h b/include/SDL.h
index 02203f2..a695416 100644
--- a/include/SDL.h
+++ b/include/SDL.h
@@ -93,37 +93,121 @@ extern "C" {
/* @} */
/**
- * This function initializes the subsystems specified by \c flags
+ * Initialize the SDL library.
+ *
+ * SDL_Init() simply forwards to calling SDL_InitSubSystem(). Therefore, the
+ * two may be used interchangeably. Though for readability of your code
+ * SDL_InitSubSystem() might be preferred.
+ *
+ * The file I/O (for example: SDL_RWFromFile) and threading (SDL_CreateThread)
+ * subsystems are initialized by default. Message boxes
+ * (SDL_ShowSimpleMessageBox) also attempt to work without initializing the
+ * video subsystem, in hopes of being useful in showing an error dialog when
+ * SDL_Init fails. You must specifically initialize other subsystems if you
+ * use them in your application.
+ *
+ * Logging (such as SDL_Log) works without initialization, too.
+ *
+ * `flags` may be any of the following OR'd together:
+ *
+ * - `SDL_INIT_TIMER`: timer subsystem
+ * - `SDL_INIT_AUDIO`: audio subsystem
+ * - `SDL_INIT_VIDEO`: video subsystem; automatically initializes the events
+ * subsystem
+ * - `SDL_INIT_JOYSTICK`: joystick subsystem; automatically initializes the
+ * events subsystem
+ * - `SDL_INIT_HAPTIC`: haptic (force feedback) subsystem
+ * - `SDL_INIT_GAMECONTROLLER`: controller subsystem; automatically
+ * initializes the joystick subsystem
+ * - `SDL_INIT_EVENTS`: events subsystem
+ * - `SDL_INIT_EVERYTHING`: all of the above subsystems
+ * - `SDL_INIT_NOPARACHUTE`: compatibility; this flag is ignored
+ *
+ * Subsystem initialization is ref-counted, you must call SDL_QuitSubSystem()
+ * for each SDL_InitSubSystem() to correctly shutdown a subsystem manually (or
+ * call SDL_Quit() to force shutdown). If a subsystem is already loaded then
+ * this call will increase the ref-count and return.
+ *
+ * \param flags subsystem initialization flags
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_InitSubSystem
+ * \sa SDL_Quit
+ * \sa SDL_SetMainReady
+ * \sa SDL_WasInit
*/
extern DECLSPEC int SDLCALL SDL_Init(Uint32 flags);
/**
- * This function initializes specific SDL subsystems
+ * Compatibility function to initialize the SDL library.
+ *
+ * In SDL2, this function and SDL_Init() are interchangeable.
+ *
+ * \param flags any of the flags used by SDL_Init(); see SDL_Init for details.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * Subsystem initialization is ref-counted, you must call
- * SDL_QuitSubSystem() for each SDL_InitSubSystem() to correctly
- * shutdown a subsystem manually (or call SDL_Quit() to force shutdown).
- * If a subsystem is already loaded then this call will
- * increase the ref-count and return.
+ * \sa SDL_Init
+ * \sa SDL_Quit
+ * \sa SDL_QuitSubSystem
*/
extern DECLSPEC int SDLCALL SDL_InitSubSystem(Uint32 flags);
/**
- * This function cleans up specific SDL subsystems
+ * Shut down specific SDL subsystems.
+ *
+ * If you start a subsystem using a call to that subsystem's init function
+ * (for example SDL_VideoInit()) instead of SDL_Init() or SDL_InitSubSystem(),
+ * SDL_QuitSubSystem() and SDL_WasInit() will not work. You will need to use
+ * that subsystem's quit function (SDL_VideoQuit()) directly instead. But
+ * generally, you should not be using those functions directly anyhow; use
+ * SDL_Init() instead.
+ *
+ * You still need to call SDL_Quit() even if you close all open subsystems
+ * with SDL_QuitSubSystem().
+ *
+ * \param flags any of the flags used by SDL_Init(); see SDL_Init for details.
+ *
+ * \sa SDL_InitSubSystem
+ * \sa SDL_Quit
*/
extern DECLSPEC void SDLCALL SDL_QuitSubSystem(Uint32 flags);
/**
- * This function returns a mask of the specified subsystems which have
- * previously been initialized.
+ * Get a mask of the specified subsystems which are currently initialized.
+ *
+ * \param flags any of the flags used by SDL_Init(); see SDL_Init for details.
+ * \returns If `flags` is 0 it returns a mask of all initialized subsystems,
+ * otherwise it returns the initialization status of the specified
+ * subsystems.
*
- * If \c flags is 0, it returns a mask of all initialized subsystems.
+ * The return value does not include SDL_INIT_NOPARACHUTE.
+ *
+ * \sa SDL_Init
+ * \sa SDL_InitSubSystem
*/
extern DECLSPEC Uint32 SDLCALL SDL_WasInit(Uint32 flags);
/**
- * This function cleans up all initialized subsystems. You should
- * call it upon all exit conditions.
+ * Clean up all initialized subsystems.
+ *
+ * You should call this function even if you have already shutdown each
+ * initialized subsystem with SDL_QuitSubSystem(). It is safe to call this
+ * function even in the case of errors in initialization.
+ *
+ * If you start a subsystem using a call to that subsystem's init function
+ * (for example SDL_VideoInit()) instead of SDL_Init() or SDL_InitSubSystem(),
+ * then you must use that subsystem's quit function (SDL_VideoQuit()) to shut
+ * it down before calling SDL_Quit(). But generally, you should not be using
+ * those functions directly anyhow; use SDL_Init() instead.
+ *
+ * You can use this function with atexit() to ensure that it is run when your
+ * application is shutdown, but it is not wise to do this from a library or
+ * other dynamically loaded code.
+ *
+ * \sa SDL_Init
+ * \sa SDL_QuitSubSystem
*/
extern DECLSPEC void SDLCALL SDL_Quit(void);
diff --git a/include/SDL_assert.h b/include/SDL_assert.h
index b1355b3..6a5bc00 100644
--- a/include/SDL_assert.h
+++ b/include/SDL_assert.h
@@ -193,88 +193,119 @@ typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)(
const SDL_AssertData* data, void* userdata);
/**
- * \brief Set an application-defined assertion handler.
+ * Set an application-defined assertion handler.
*
- * This allows an app to show its own assertion UI and/or force the
- * response to an assertion failure. If the app doesn't provide this, SDL
- * will try to do the right thing, popping up a system-specific GUI dialog,
- * and probably minimizing any fullscreen windows.
+ * This function allows an application to show its own assertion UI and/or
+ * force the response to an assertion failure. If the application doesn't
+ * provide this, SDL will try to do the right thing, popping up a
+ * system-specific GUI dialog, and probably minimizing any fullscreen windows.
*
- * This callback may fire from any thread, but it runs wrapped in a mutex, so
- * it will only fire from one thread at a time.
+ * The function prototype for `handler` is:
*
- * Setting the callback to NULL restores SDL's original internal handler.
+ * ```c
+ * SDL_AssertState YourAssertionHandler(const SDL_AssertData* data, void* userdata)
+ * ```
*
- * This callback is NOT reset to SDL's internal handler upon SDL_Quit()!
+ * where `YourAssertionHandler` is the name of your function and its
+ * parameters are:
*
- * Return SDL_AssertState value of how to handle the assertion failure.
+ * - `data`: a pointer to the SDL_AssertData structure corresponding to the
+ * current assertion
+ * - `userdata`: what was passed as `userdata` to SDL_SetAssertionHandler()
*
- * \param handler Callback function, called when an assertion fails.
- * \param userdata A pointer passed to the callback as-is.
+ * This callback should return an SDL_AssertState value indicating how to
+ * handle the assertion failure.
+ *
+ * This callback may fire from any thread, but it runs wrapped in a mutex, so
+ * it will only fire from one thread at a time.
+ *
+ * This callback is NOT reset to SDL's internal handler upon SDL_Quit()!
+ *
+ * \param handler the function to call when an assertion fails or NULL for the
+ * default handler
+ * \param userdata a pointer that is passed to `handler`
+ *
+ * \sa SDL_GetAssertionHandler
*/
extern DECLSPEC void SDLCALL SDL_SetAssertionHandler(
SDL_AssertionHandler handler,
void *userdata);
/**
- * \brief Get the default assertion handler.
+ * Get the default assertion handler.
+ *
+ * This returns the function pointer that is called by default when an
+ * assertion is triggered. This is an internal function provided by SDL, that
+ * is used for assertions when SDL_SetAssertionHandler() hasn't been used to
+ * provide a different function.
*
- * This returns the function pointer that is called by default when an
- * assertion is triggered. This is an internal function provided by SDL,
- * that is used for assertions when SDL_SetAssertionHandler() hasn't been
- * used to provide a different function.
+ * \returns the default SDL_AssertionHandler that is called when an assert
+ * triggers.
*
- * \return The default SDL_AssertionHandler that is called when an assert triggers.
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \sa SDL_GetAssertionHandler
*/
extern DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetDefaultAssertionHandler(void);
/**
- * \brief Get the current assertion handler.
+ * Get the current assertion handler.
+ *
+ * This returns the function pointer that is called when an assertion is
+ * triggered. This is either the value last passed to
+ * SDL_SetAssertionHandler(), or if no application-specified function is set,
+ * is equivalent to calling SDL_GetDefaultAssertionHandler().
+ *
+ * The parameter `puserdata` is a pointer to a void*, which will store the
+ * "userdata" pointer that was passed to SDL_SetAssertionHandler(). This value
+ * will always be NULL for the default handler. If you don't care about this
+ * data, it is safe to pass a NULL pointer to this function to ignore it.
*
- * This returns the function pointer that is called when an assertion is
- * triggered. This is either the value last passed to
- * SDL_SetAssertionHandler(), or if no application-specified function is
- * set, is equivalent to calling SDL_GetDefaultAssertionHandler().
+ * \param puserdata pointer which is filled with the "userdata" pointer that
+ * was passed to SDL_SetAssertionHandler()
+ * \returns the SDL_AssertionHandler that is called when an assert triggers.
*
- * \param puserdata Pointer to a void*, which will store the "userdata"
- * pointer that was passed to SDL_SetAssertionHandler().
- * This value will always be NULL for the default handler.
- * If you don't care about this data, it is safe to pass
- * a NULL pointer to this function to ignore it.
- * \return The SDL_AssertionHandler that is called when an assert triggers.
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \sa SDL_SetAssertionHandler
*/
extern DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetAssertionHandler(void **puserdata);
/**
- * \brief Get a list of all assertion failures.
+ * Get a list of all assertion failures.
+ *
+ * This function gets all assertions triggered since the last call to
+ * SDL_ResetAssertionReport(), or the start of the program.
*
- * Get all assertions triggered since last call to SDL_ResetAssertionReport(),
- * or the start of the program.
+ * The proper way to examine this data looks something like this:
*
- * The proper way to examine this data looks something like this:
+ * ```c
+ * const SDL_AssertData *item = SDL_GetAssertionReport();
+ * while (item) {
+ * printf("'%s', %s (%s:%d), triggered %u times, always ignore: %s.\\n",
+ * item->condition, item->function, item->filename,
+ * item->linenum, item->trigger_count,
+ * item->always_ignore ? "yes" : "no");
+ * item = item->next;
+ * }
+ * ```
*
- * <code>
- * const SDL_AssertData *item = SDL_GetAssertionReport();
- * while (item) {
- * printf("'%s', %s (%s:%d), triggered %u times, always ignore: %s.\\n",
- * item->condition, item->function, item->filename,
- * item->linenum, item->trigger_count,
- * item->always_ignore ? "yes" : "no");
- * item = item->next;
- * }
- * </code>
+ * \returns a list of all failed assertions or NULL if the list is empty. This
+ * memory should not be modified or freed by the application.
*
- * \return List of all assertions.
- * \sa SDL_ResetAssertionReport
+ * \sa SDL_ResetAssertionReport
*/
extern DECLSPEC const SDL_AssertData * SDLCALL SDL_GetAssertionReport(void);
/**
- * \brief Reset the list of all assertion failures.
+ * Clear the list of all assertion failures.
*
- * Reset list of all assertions triggered.
+ * This function will clear the list of all assertions triggered up to that
+ * point. Immediately following this call, SDL_GetAssertionReport will return
+ * no items. In addition, any previously-triggered assertions will be reset to
+ * a trigger_count of zero, and their always_ignore state will be false.
*
- * \sa SDL_GetAssertionReport
+ * \sa SDL_GetAssertionReport
*/
extern DECLSPEC void SDLCALL SDL_ResetAssertionReport(void);
diff --git a/include/SDL_atomic.h b/include/SDL_atomic.h
index 5f62bd7..df2974b 100644
--- a/include/SDL_atomic.h
+++ b/include/SDL_atomic.h
@@ -89,25 +89,47 @@ extern "C" {
typedef int SDL_SpinLock;
/**
- * \brief Try to lock a spin lock by setting it to a non-zero value.
+ * Try to lock a spin lock by setting it to a non-zero value.
*
- * \param lock Points to the lock.
+ * ***Please note that spinlocks are dangerous if you don't know what you're
+ * doing. Please be careful using any sort of spinlock!***
*
- * \return SDL_TRUE if the lock succeeded, SDL_FALSE if the lock is already held.
+ * \param lock a pointer to a lock variable
+ * \returns SDL_TRUE if the lock succeeded, SDL_FALSE if the lock is already
+ * held.
+ *
+ * \sa SDL_AtomicLock
+ * \sa SDL_AtomicUnlock
*/
extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTryLock(SDL_SpinLock *lock);
/**
- * \brief Lock a spin lock by setting it to a non-zero value.
+ * Lock a spin lock by setting it to a non-zero value.
+ *
+ * ***Please note that spinlocks are dangerous if you don't know what you're
+ * doing. Please be careful using any sort of spinlock!***
*
- * \param lock Points to the lock.
+ * \param lock a pointer to a lock variable
+ *
+ * \sa SDL_AtomicTryLock
+ * \sa SDL_AtomicUnlock
*/
extern DECLSPEC void SDLCALL SDL_AtomicLock(SDL_SpinLock *lock);
/**
- * \brief Unlock a spin lock by setting it to 0. Always returns immediately
+ * Unlock a spin lock by setting it to 0.
+ *
+ * Always returns immediately.
+ *
+ * ***Please note that spinlocks are dangerous if you don't know what you're
+ * doing. Please be careful using any sort of spinlock!***
+ *
+ * \param lock a pointer to a lock variable
+ *
+ * \since This function is available since SDL 2.0.0.
*
- * \param lock Points to the lock.
+ * \sa SDL_AtomicLock
+ * \sa SDL_AtomicTryLock
*/
extern DECLSPEC void SDLCALL SDL_AtomicUnlock(SDL_SpinLock *lock);
@@ -216,32 +238,68 @@ typedef void (*SDL_KernelMemoryBarrierFunc)();
typedef struct { int value; } SDL_atomic_t;
/**
- * \brief Set an atomic variable to a new value if it is currently an old value.
+ * Set an atomic variable to a new value if it is
+ * currently an old value.
*
- * \return SDL_TRUE if the atomic variable was set, SDL_FALSE otherwise.
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
*
- * \note If you don't know what this function is for, you shouldn't use it!
-*/
+ * \param a a pointer to an SDL_atomic_t variable to be modified
+ * \param oldval the old value
+ * \param newval the new value
+ * \returns SDL_TRUE if the atomic variable was set, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AtomicCASPtr
+ * \sa SDL_AtomicGet
+ * \sa SDL_AtomicSet
+ */
extern DECLSPEC SDL_bool SDLCALL SDL_AtomicCAS(SDL_atomic_t *a, int oldval, int newval);
/**
- * \brief Set an atomic variable to a value.
+ * Set an atomic variable to a value.
+ *
+ * This function also acts as a full memory barrier.
+ *
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
+ *
+ * \param a a pointer to an SDL_atomic_t variable to be modified
+ * \param v the desired value
+ * \returns the previous value of the atomic variable.
*
- * \return The previous value of the atomic variable.
+ * \sa SDL_AtomicGet
*/
extern DECLSPEC int SDLCALL SDL_AtomicSet(SDL_atomic_t *a, int v);
/**
- * \brief Get the value of an atomic variable
+ * Get the value of an atomic variable.
+ *
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
+ *
+ * \param a a pointer to an SDL_atomic_t variable
+ * \returns the current value of an atomic variable.
+ *
+ * \sa SDL_AtomicSet
*/
extern DECLSPEC int SDLCALL SDL_AtomicGet(SDL_atomic_t *a);
/**
- * \brief Add to an atomic variable.
+ * Add to an atomic variable.
+ *
+ * This function also acts as a full memory barrier.
*
- * \return The previous value of the atomic variable.
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
*
- * \note This same style can be used for any number operation
+ * \param a a pointer to an SDL_atomic_t variable to be modified
+ * \param v the desired value to add
+ * \returns the previous value of the atomic variable.
+ *
+ * \sa SDL_AtomicDecRef
+ * \sa SDL_AtomicIncRef
*/
extern DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_atomic_t *a, int v);
@@ -263,23 +321,51 @@ extern DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_atomic_t *a, int v);
#endif
/**
- * \brief Set a pointer to a new value if it is currently an old value.
+ * Set a pointer to a new value if it is currently an old
+ * value.
*
- * \return SDL_TRUE if the pointer was set, SDL_FALSE otherwise.
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
*
- * \note If you don't know what this function is for, you shouldn't use it!
-*/
+ * \param a a pointer to a pointer
+ * \param oldval the old pointer value
+ * \param newval the new pointer value
+ * \returns SDL_TRUE if the pointer was set, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AtomicCAS
+ * \sa SDL_AtomicGetPtr
+ * \sa SDL_AtomicSetPtr
+ */
extern DECLSPEC SDL_bool SDLCALL SDL_AtomicCASPtr(void **a, void *oldval, void *newval);
/**
- * \brief Set a pointer to a value atomically.
+ * Set a pointer to a value atomically.
+ *
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
+ *
+ * \param a a pointer to a pointer
+ * \param v the desired pointer value
+ * \returns the previous value of the pointer.
*
- * \return The previous value of the pointer.
+ * \sa SDL_AtomicCASPtr
+ * \sa SDL_AtomicGetPtr
*/
extern DECLSPEC void* SDLCALL SDL_AtomicSetPtr(void **a, void* v);
/**
- * \brief Get the value of a pointer atomically.
+ * Get the value of a pointer atomically.
+ *
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
+ *
+ * \param a a pointer to a pointer
+ * \returns the current value of a pointer.
+ *
+ * \sa SDL_AtomicCASPtr
+ * \sa SDL_AtomicSetPtr
*/
extern DECLSPEC void* SDLCALL SDL_AtomicGetPtr(void **a);
diff --git a/include/SDL_audio.h b/include/SDL_audio.h
index 46fefe2..99d8a2b 100644
--- a/include/SDL_audio.h
+++ b/include/SDL_audio.h
@@ -19,6 +19,8 @@
3. This notice may not be removed or altered from any source distribution.
*/
+/* !!! FIXME: several functions in here need Doxygen comments. */
+
/**
* \file SDL_audio.h
*
@@ -265,55 +267,69 @@ extern DECLSPEC void SDLCALL SDL_AudioQuit(void);
/* @} */
/**
- * This function returns the name of the current audio driver, or NULL
- * if no driver has been initialized.
+ * Get the name of the current audio driver.
+ *
+ * The returned string points to internal static memory and thus never becomes
+ * invalid, even if you quit the audio subsystem and initialize a new driver
+ * (although such a case would return a different static string from another
+ * call to this function, of course). As such, you should not modify or free
+ * the returned string.
+ *
+ * \returns the name of the current audio driver or NULL if no driver has been
+ * initialized.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AudioInit
*/
extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void);
/**
- * This function opens the audio device with the desired parameters, and
- * returns 0 if successful, placing the actual hardware parameters in the
- * structure pointed to by \c obtained. If \c obtained is NULL, the audio
- * data passed to the callback function will be guaranteed to be in the
- * requested format, and will be automatically converted to the hardware
- * audio format if necessary. This function returns -1 if it failed
- * to open the audio device, or couldn't set up the audio thread.
- *
- * When filling in the desired audio spec structure,
- * - \c desired->freq should be the desired audio frequency in samples-per-
- * second.
- * - \c desired->format should be the desired audio format.
- * - \c desired->samples is the desired size of the audio buffer, in
- * samples. This number should be a power of two, and may be adjusted by
- * the audio driver to a value more suitable for the hardware. Good values
- * seem to range between 512 and 8096 inclusive, depending on the
- * application and CPU speed. Smaller values yield faster response time,
- * but can lead to underflow if the application is doing heavy processing
- * and cannot fill the audio buffer in time. A stereo sample consists of
- * both right and left channels in LR ordering.
- * Note that the number of samples is directly related to time by the
- * following formula: \code ms = (samples*1000)/freq \endcode
- * - \c desired->size is the size in bytes of the audio buffer, and is
- * calculated by SDL_OpenAudio().
- * - \c desired->silence is the value used to set the buffer to silence,
- * and is calculated by SDL_OpenAudio().
- * - \c desired->callback should be set to a function that will be called
- * when the audio device is ready for more data. It is passed a pointer
- * to the audio buffer, and the length in bytes of the audio buffer.
- * This function usually runs in a separate thread, and so you should
- * protect data structures that it accesses by calling SDL_LockAudio()
- * and SDL_UnlockAudio() in your code. Alternately, you may pass a NULL
- * pointer here, and call SDL_QueueAudio() with some frequency, to queue
- * more audio samples to be played (or for capture devices, call
- * SDL_DequeueAudio() with some frequency, to obtain audio samples).
- * - \c desired->userdata is passed as the first parameter to your callback
- * function. If you passed a NULL callback, this value is ignored.
- *
- * The audio device starts out playing silence when it's opened, and should
- * be enabled for playing by calling \c SDL_PauseAudio(0) when you are ready
- * for your audio callback function to be called. Since the audio driver
- * may modify the requested size of the audio buffer, you should allocate
- * any local mixing buffers after you open the audio device.
+ * This function is a legacy means of opening the audio device.
+ *
+ * This function remains for compatibility with SDL 1.2, but also because it's
+ * slightly easier to use than the new functions in SDL 2.0. The new, more
+ * powerful, and preferred way to do this is SDL_OpenAudioDevice().
+ *
+ * This function is roughly equivalent to:
+ *
+ * ```c++
+ * SDL_OpenAudioDevice(NULL, 0, desired, obtained, SDL_AUDIO_ALLOW_ANY_CHANGE);
+ * ```
+ *
+ * With two notable exceptions:
+ *
+ * - If `obtained` is NULL, we use `desired` (and allow no changes), which
+ * means desired will be modified to have the correct values for silence, etc,
+ * and SDL will convert any differences between your app's specific request
+ * and the hardware behind the scenes.
+ *
+ * - The return value is always success or failure, and not a device ID, which
+ * means you can only have one device open at a time with this function.
+ *
+ * \param desired an SDL_AudioSpec structure representing the desired output
+ * format. Please refer to the SDL_OpenAudioDevice documentation
+ * for details on how to prepare this structure.
+ * \param obtained an SDL_AudioSpec structure filled in with the actual
+ * parameters, or NULL.
+ * \returns This function opens the audio device with the desired parameters,
+ * and returns 0 if successful, placing the actual hardware
+ * parameters in the structure pointed to by `obtained`.
+ *
+ * If `obtained` is NULL, the audio data passed to the callback
+ * function will be guaranteed to be in the requested format, and
+ * will be automatically converted to the actual hardware audio
+ * format if necessary. If `obtained` is NULL, `desired` will
+ * have fields modified.
+ *
+ * This function returns a negative error code on failure to open the
+ * audio device or failure to set up the audio thread; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_CloseAudio
+ * \sa SDL_LockAudio
+ * \sa SDL_PauseAudio
+ * \sa SDL_UnlockAudio
*/
extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired,
SDL_AudioSpec * obtained);
@@ -330,49 +346,97 @@ extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired,
typedef Uint32 SDL_AudioDeviceID;
/**
- * Get the number of available devices exposed by the current driver.
- * Only valid after a successfully initializing the audio subsystem.
- * Returns -1 if an explicit list of devices can't be determined; this is
- * not an error. For example, if SDL is set up to talk to a remote audio
- * server, it can't list every one available on the Internet, but it will
- * still allow a specific host to be specified to SDL_OpenAudioDevice().
+ * Get the number of built-in audio devices.
+ *
+ * This function is only valid after successfully initializing the audio
+ * subsystem.
+ *
+ * Note that audio capture support is not implemented as of SDL 2.0.4, so the
+ * `iscapture` parameter is for future expansion and should always be zero
+ * for now.
+ *
+ * This function will return -1 if an explicit list of devices can't be
+ * determined. Returning -1 is not an error. For example, if SDL is set up to
+ * talk to a remote audio server, it can't list every one available on the
+ * Internet, but it will still allow a specific host to be specified in
+ * SDL_OpenAudioDevice().
+ *
+ * In many common cases, when this function returns a value <= 0, it can still
+ * successfully open the default device (NULL for first argument of
+ * SDL_OpenAudioDevice()).
*
- * In many common cases, when this function returns a value <= 0, it can still
- * successfully open the default device (NULL for first argument of
- * SDL_OpenAudioDevice()).
+ * This function may trigger a complete redetect of available hardware. It
+ * should not be called for each iteration of a loop, but rather once at the
+ * start of a loop:
+ *
+ * ```c++
+ * // Don't do this:
+ * for (int i = 0; i < SDL_GetNumAudioDevices(0); i++)
+ *
+ * // do this instead:
+ * const int count = SDL_GetNumAudioDevices(0);
+ * for (int i = 0; i < count; ++i) { do_something_here(); }
+ * ```
+ *
+ * \param iscapture zero to request playback devices, non-zero to request
+ * recording devices
+ * \returns the number of available devices exposed by the current driver or
+ * -1 if an explicit list of devices can't be determined. A return
+ * value of -1 does not necessarily mean an error condition.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetAudioDeviceName
+ * \sa SDL_OpenAudioDevice
*/
extern DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture);
/**
- * Get the human-readable name of a specific audio device.
- * Must be a value between 0 and (number of audio devices-1).
- * Only valid after a successfully initializing the audio subsystem.
- * The values returned by this function reflect the latest call to
- * SDL_GetNumAudioDevices(); recall that function to redetect available
- * hardware.
- *
- * The string returned by this function is UTF-8 encoded, read-only, and
- * managed internally. You are not to free it. If you need to keep the
- * string for any length of time, you should make your own copy of it, as it
- * will be invalid next time any of several other SDL functions is called.
+ * Get the human-readable name of a specific audio device.
+ *
+ * This function is only valid after successfully initializing the audio
+ * subsystem. The values returned by this function reflect the latest call to
+ * SDL_GetNumAudioDevices(); re-call that function to redetect available
+ * hardware.
+ *
+ * The string returned by this function is UTF-8 encoded, read-only, and
+ * managed internally. You are not to free it. If you need to keep the string
+ * for any length of time, you should make your own copy of it, as it will be
+ * invalid next time any of several other SDL functions are called.
+ *
+ * \param index the index of the audio device; valid values range from 0 to
+ * SDL_GetNumAudioDevices() - 1
+ * \param iscapture non-zero to query the list of recording devices, zero to
+ * query the list of output devices.
+ * \returns the name of the audio device at the requested index, or NULL on
+ * error.
+ *
+ * \sa SDL_GetNumAudioDevices
*/
extern DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(int index,
int iscapture);
/**
- * Get the audio format of a specific audio device.
- * Must be a value between 0 and (number of audio devices-1).
- * Only valid after a successfully initializing the audio subsystem.
- * The values returned by this function reflect the latest call to
- * SDL_GetNumAudioDevices(); recall that function to redetect available
- * hardware.
- *
- * The spec will be filled with the sample rate, sample format, and channel
- * count. All other values in the structure are filled with 0. When the
- * supported struct members are 0, SDL was unable to get the property from the
- * backend.
- *
- * \return 0 on success, nonzero on error
+ * Get the preferred audio format of a specific audio device.
+ *
+ * This function is only valid after a successfully initializing the audio
+ * subsystem. The values returned by this function reflect the latest call to
+ * SDL_GetNumAudioDevices(); re-call that function to redetect available
+ * hardware.
+ *
+ * `spec` will be filled with the sample rate, sample format, and channel
+ * count. All other values in the structure are filled with 0. When the
+ * supported struct members are 0, SDL was unable to get the property from the
+ * backend.
+ *
+ * \param index the index of the audio device; valid values range from 0 to
+ * SDL_GetNumAudioDevices() - 1
+ * \param iscapture non-zero to query the list of recording devices, zero to
+ * query the list of output devices.
+ * \param spec The SDL_AudioSpec to be initialized by this function.
+ * \returns 0 on success, nonzero on error
+ *
+ * \sa SDL_GetNumAudioDevices
*/
extern DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index,
int iscapture,
@@ -380,17 +444,116 @@ extern DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index,
/**
- * Open a specific audio device. Passing in a device name of NULL requests
- * the most reasonable default (and is equivalent to calling SDL_OpenAudio()).
- *
- * The device name is a UTF-8 string reported by SDL_GetAudioDeviceName(), but
- * some drivers allow arbitrary and driver-specific strings, such as a
- * hostname/IP address for a remote audio server, or a filename in the
- * diskaudio driver.
- *
- * \return 0 on error, a valid device ID that is >= 2 on success.
- *
- * SDL_OpenAudio(), unlike this function, always acts on device ID 1.
+ * Open a specific audio device.
+ *
+ * SDL_OpenAudio(), unlike this function, always acts on device ID 1. As such,
+ * this function will never return a 1 so as not to conflict with the legacy
+ * function.
+ *
+ * Please note that SDL 2.0 before 2.0.5 did not support recording; as such,
+ * this function would fail if `iscapture` was not zero. Starting with SDL
+ * 2.0.5, recording is implemented and this value can be non-zero.
+ *
+ * Passing in a `device` name of NULL requests the most reasonable default
+ * (and is equivalent to what SDL_OpenAudio() does to choose a device). The
+ * `device` name is a UTF-8 string reported by SDL_GetAudioDeviceName(), but
+ * some drivers allow arbitrary and driver-specific strings, such as a
+ * hostname/IP address for a remote audio server, or a filename in the
+ * diskaudio driver.
+ *
+ * When filling in the desired audio spec structure:
+ *
+ * - `desired->freq` should be the frequency in sample-frames-per-second (Hz).
+ *
+ * - `desired->format` should be the audio format (`AUDIO_S16SYS`, etc).
+ *
+ * - `desired->samples` is the desired size of the audio buffer, in
+ * _sample frames_ (with stereo output, two samples--left and right--would
+ * make a single sample frame). This number should be a power of two, and
+ * may be adjusted by the audio driver to a value more suitable for the
+ * hardware. Good values seem to range between 512 and 8096 inclusive,
+ * depending on the application and CPU speed. Smaller values reduce
+ * latency, but can lead to underflow if the application is doing heavy
+ * processing and cannot fill the audio buffer in time. Note that the
+ * number of sample frames is directly related to time by the following
+ * formula: `ms = (sampleframes*1000)/freq`
+ *
+ * - `desired->size` is the size in _bytes_ of the audio buffer, and is
+ * calculated by SDL_OpenAudioDevice(). You don't initialize this.
+ *
+ * - `desired->silence` is the value used to set the buffer to silence,
+ * and is calculated by SDL_OpenAudioDevice(). You don't initialize this.
+ *
+ * - `desired->callback` should be set to a function that will be called
+ * when the audio device is ready for more data. It is passed a pointer
+ * to the audio buffer, and the length in bytes of the audio buffer.
+ * This function usually runs in a separate thread, and so you should
+ * protect data structures that it accesses by calling SDL_LockAudioDevice()
+ * and SDL_UnlockAudioDevice() in your code. Alternately, you may pass a NULL
+ * pointer here, and call SDL_QueueAudio() with some frequency, to queue
+ * more audio samples to be played (or for capture devices, call
+ * SDL_DequeueAudio() with some frequency, to obtain audio samples).
+ *
+ * - `desired->userdata` is passed as the first parameter to your callback
+ * function. If you passed a NULL callback, this value is ignored.
+ *
+ * `allowed_changes` can have the following flags OR'd together:
+ *
+ * - `SDL_AUDIO_ALLOW_FREQUENCY_CHANGE`
+ * - `SDL_AUDIO_ALLOW_FORMAT_CHANGE`
+ * - `SDL_AUDIO_ALLOW_CHANNELS_CHANGE`
+ * - `SDL_AUDIO_ALLOW_ANY_CHANGE`
+ *
+ * These flags specify how SDL should behave when a device cannot offer a
+ * specific feature. If the application requests a feature that the hardware
+ * doesn't offer, SDL will always try to get the closest equivalent.
+ *
+ * For example, if you ask for float32 audio format, but the sound card only
+ * supports int16, SDL will set the hardware to int16. If you had set
+ * SDL_AUDIO_ALLOW_FORMAT_CHANGE, SDL will change the format in the
+ * `obtained` structure. If that flag was *not* set, SDL will prepare to
+ * convert your callback's float32 audio to int16 before feeding it to the
+ * hardware and will keep the originally requested format in the `obtained`
+ * structure.
+ *
+ * If your application can only handle one specific data format, pass a zero
+ * for `allowed_changes` and let SDL transparently handle any differences.
+ *
+ * An opened audio device starts out paused, and should be enabled for playing
+ * by calling SDL_PauseAudioDevice(devid, 0) when you are ready for your audio
+ * callback function to be called. Since the audio driver may modify the
+ * requested size of the audio buffer, you should allocate any local mixing
+ * buffers after you open the audio device.
+ *
+ * The audio callback runs in a separate thread in most cases; you can prevent
+ * race conditions between your callback and other threads without fully
+ * pausing playback with SDL_LockAudioDevice(). For more information about the
+ * callback, see SDL_AudioSpec.
+ *
+ * \param device a UTF-8 string reported by SDL_GetAudioDeviceName() or a
+ * driver-specific name as appropriate. NULL requests the most
+ * reasonable default device.
+ * \param iscapture non-zero to specify a device should be opened for
+ * recording, not playback
+ * \param desired an SDL_AudioSpec structure representing the desired output
+ * format; see SDL_OpenAudio() for more information
+ * \param obtained an SDL_AudioSpec structure filled in with the actual output
+ * format; see SDL_OpenAudio() for more information
+ * \param allowed_changes 0, or one or more flags OR'd together
+ * \returns a valid device ID that is > 0 on success or 0 on failure; call
+ * SDL_GetError() for more information.
+ *
+ * For compatibility with SDL 1.2, this will never return 1, since
+ * SDL reserves that ID for the legacy SDL_OpenAudio() function.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_CloseAudioDevice
+ * \sa SDL_GetAudioDeviceName
+ * \sa SDL_LockAudioDevice
+ * \sa SDL_OpenAudio
+ * \sa SDL_PauseAudioDevice
+ * \sa SDL_UnlockAudioDevice
*/
extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(const char
*device,
@@ -418,9 +581,7 @@ typedef enum
SDL_AUDIO_PAUSED
} SDL_AudioStatus;
extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioStatus(void);
-
-extern DECLSPEC SDL_AudioStatus SDLCALL
-SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev);
+extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev);
/* @} *//* Audio State */
/**
@@ -439,56 +600,79 @@ extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev,
/* @} *//* Pause audio functions */
/**
- * \brief Load the audio data of a WAVE file into memory
- *
- * Loading a WAVE file requires \c src, \c spec, \c audio_buf and \c audio_len
- * to be valid pointers. The entire data portion of the file is then loaded
- * into memory and decoded if necessary.
- *
- * If \c freesrc is non-zero, the data source gets automatically closed and
- * freed before the function returns.
- *
- * Supported are RIFF WAVE files with the formats PCM (8, 16, 24, and 32 bits),
- * IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits), and A-law and
- * µ-law (8 bits). Other formats are currently unsupported and cause an error.
- *
- * If this function succeeds, the pointer returned by it is equal to \c spec
- * and the pointer to the audio data allocated by the function is written to
- * \c audio_buf and its length in bytes to \c audio_len. The \ref SDL_AudioSpec
- * members \c freq, \c channels, and \c format are set to the values of the
- * audio data in the buffer. The \c samples member is set to a sane default and
- * all others are set to zero.
- *
- * It's necessary to use SDL_FreeWAV() to free the audio data returned in
- * \c audio_buf when it is no longer used.
- *
- * Because of the underspecification of the Waveform format, there are many
- * problematic files in the wild that cause issues with strict decoders. To
- * provide compatibility with these files, this decoder is lenient in regards
- * to the truncation of the file, the fact chunk, and the size of the RIFF
- * chunk. The hints SDL_HINT_WAVE_RIFF_CHUNK_SIZE, SDL_HINT_WAVE_TRUNCATION,
- * and SDL_HINT_WAVE_FACT_CHUNK can be used to tune the behavior of the
- * loading process.
- *
- * Any file that is invalid (due to truncation, corruption, or wrong values in
- * the headers), too big, or unsupported causes an error. Additionally, any
- * critical I/O error from the data source will terminate the loading process
- * with an error. The function returns NULL on error and in all cases (with the
- * exception of \c src being NULL), an appropriate error message will be set.
- *
- * It is required that the data source supports seeking.
- *
- * Example:
- * \code
- * SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...);
- * \endcode
- *
- * \param src The data source with the WAVE data
- * \param freesrc A integer value that makes the function close the data source if non-zero
- * \param spec A pointer filled with the audio format of the audio data
- * \param audio_buf A pointer filled with the audio data allocated by the function
- * \param audio_len A pointer filled with the length of the audio data buffer in bytes
- * \return NULL on error, or non-NULL on success.
+ * Load the audio data of a WAVE file into memory.
+ *
+ * Loading a WAVE file requires `src`, `spec`, `audio_buf` and `audio_len`
+ * to be valid pointers. The entire data portion of the file is then loaded
+ * into memory and decoded if necessary.
+ *
+ * If `freesrc` is non-zero, the data source gets automatically closed and
+ * freed before the function returns.
+ *
+ * Supported formats are RIFF WAVE files with the formats PCM (8, 16, 24, and
+ * 32 bits), IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits),
+ * and A-law and mu-law (8 bits). Other formats are currently unsupported and
+ * cause an error.
+ *
+ * If this function succeeds, the pointer returned by it is equal to `spec`
+ * and the pointer to the audio data allocated by the function is written to
+ * `audio_buf` and its length in bytes to `audio_len`. The SDL_AudioSpec
+ * members `freq`, `channels`, and `format` are set to the values of the
+ * audio data in the buffer. The `samples` member is set to a sane default
+ * and all others are set to zero.
+ *
+ * It's necessary to use SDL_FreeWAV() to free the audio data returned in
+ * `audio_buf` when it is no longer used.
+ *
+ * Because of the underspecification of the .WAV format, there are many
+ * problematic files in the wild that cause issues with strict decoders. To
+ * provide compatibility with these files, this decoder is lenient in regards
+ * to the truncation of the file, the fact chunk, and the size of the RIFF
+ * chunk. The hints `SDL_HINT_WAVE_RIFF_CHUNK_SIZE`, `SDL_HINT_WAVE_TRUNCATION`,
+ * and `SDL_HINT_WAVE_FACT_CHUNK` can be used to tune the behavior of the
+ * loading process.
+ *
+ * Any file that is invalid (due to truncation, corruption, or wrong values in
+ * the headers), too big, or unsupported causes an error. Additionally, any
+ * critical I/O error from the data source will terminate the loading process
+ * with an error. The function returns NULL on error and in all cases (with the
+ * exception of `src` being NULL), an appropriate error message will be set.
+ *
+ * It is required that the data source supports seeking.
+ *
+ * Example:
+ * ```c++
+ * SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, &spec, &buf, &len);
+ * ```
+ *
+ * Note that the SDL_LoadWAV macro does this same thing for you, but in a less
+ * messy way:
+ *
+ * ```c++
+ * SDL_LoadWAV("sample.wav", &spec, &buf, &len);
+ * ```
+ *
+ * \param src The data source for the WAVE data
+ * \param freesrc If non-zero, SDL will _always_ free the data source
+ * \param spec An SDL_AudioSpec that will be filled in with the wave file's
+ * format details
+ * \param audio_buf A pointer filled with the audio data, allocated by the function.
+ * \param audio_len A pointer filled with the length of the audio data buffer in bytes
+ * \returns This function, if successfully called, returns `spec`, which will
+ * be filled with the audio data format of the wave source data.
+ * `audio_buf` will be filled with a pointer to an allocated buffer
+ * containing the audio data, and `audio_len` is filled with the
+ * length of that audio buffer in bytes.
+ *
+ * This function returns NULL if the .WAV file cannot be opened, uses
+ * an unknown data format, or is corrupt; call SDL_GetError() for
+ * more information.
+ *
+ * When the application is done with the data returned in
+ * `audio_buf`, it should call SDL_FreeWAV() to dispose of it.
+ *
+ * \sa SDL_FreeWAV
+ * \sa SDL_LoadWAV
*/
extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src,
int freesrc,
@@ -504,18 +688,50 @@ extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src,
SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len)
/**
- * This function frees data previously allocated with SDL_LoadWAV_RW()
+ * Free data previously allocated with SDL_LoadWAV() or SDL_LoadWAV_RW().
+ *
+ * After a WAVE file has been opened with SDL_LoadWAV() or SDL_LoadWAV_RW()
+ * its data can eventually be freed with SDL_FreeWAV(). It is safe to call
+ * this function with a NULL pointer.
+ *
+ * \param audio_buf a pointer to the buffer created by SDL_LoadWAV() or
+ * SDL_LoadWAV_RW()
+ *
+ * \sa SDL_LoadWAV
+ * \sa SDL_LoadWAV_RW
*/
extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 * audio_buf);
/**
- * This function takes a source format and rate and a destination format
- * and rate, and initializes the \c cvt structure with information needed
- * by SDL_ConvertAudio() to convert a buffer of audio data from one format
- * to the other. An unsupported format causes an error and -1 will be returned.
- *
- * \return 0 if no conversion is needed, 1 if the audio filter is set up,
- * or -1 on error.
+ * Initialize an SDL_AudioCVT structure for conversion.
+ *
+ * Before an SDL_AudioCVT structure can be used to convert audio data it must
+ * be initialized with source and destination information.
+ *
+ * This function will zero out every field of the SDL_AudioCVT, so it must be
+ * called before the application fills in the final buffer information.
+ *
+ * Once this function has returned successfully, and reported that a
+ * conversion is necessary, the application fills in the rest of the fields in
+ * SDL_AudioCVT, now that it knows how large a buffer it needs to allocate,
+ * and then can call SDL_ConvertAudio() to complete the conversion.
+ *
+ * \param cvt an SDL_AudioCVT structure filled in with audio conversion
+ * information
+ * \param src_format the source format of the audio data; for more info see
+ * SDL_AudioFormat
+ * \param src_channels the number of channels in the source
+ * \param src_rate the frequency (sample-frames-per-second) of the source
+ * \param dst_format the destination format of the audio data; for more info
+ * see SDL_AudioFormat
+ * \param dst_channels the number of channels in the destination
+ * \param dst_rate the frequency (sample-frames-per-second) of the
+ * destination
+ * \returns 1 if the audio filter is prepared, 0 if no conversion is needed,
+ * or a negative error code on failure; call SDL_GetError() for more
+ * information.
+ *
+ * \sa SDL_ConvertAudio
*/
extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
SDL_AudioFormat src_format,
@@ -526,16 +742,40 @@ extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
int dst_rate);
/**
- * Once you have initialized the \c cvt structure using SDL_BuildAudioCVT(),
- * created an audio buffer \c cvt->buf, and filled it with \c cvt->len bytes of
- * audio data in the source format, this function will convert it in-place
- * to the desired format.
- *
- * The data conversion may expand the size of the audio data, so the buffer
- * \c cvt->buf should be allocated after the \c cvt structure is initialized by
- * SDL_BuildAudioCVT(), and should be \c cvt->len*cvt->len_mult bytes long.
- *
- * \return 0 on success or -1 if \c cvt->buf is NULL.
+ * Convert audio data to a desired audio format.
+ *
+ * This function does the actual audio data conversion, after the application
+ * has called SDL_BuildAudioCVT() to prepare the conversion information and
+ * then filled in the buffer details.
+ *
+ * Once the application has initialized the `cvt` structure using
+ * SDL_BuildAudioCVT(), allocated an audio buffer and filled it with audio
+ * data in the source format, this function will convert the buffer, in-place,
+ * to the desired format.
+ *
+ * The data conversion may go through several passes; any given pass may
+ * possibly temporarily increase the size of the data. For example, SDL might
+ * expand 16-bit data to 32 bits before resampling to a lower frequency,
+ * shrinking the data size after having grown it briefly. Since the supplied
+ * buffer will be both the source and destination, converting as necessary
+ * in-place, the application must allocate a buffer that will fully contain
+ * the data during its largest conversion pass. After SDL_BuildAudioCVT()
+ * returns, the application should set the `cvt->len` field to the size, in
+ * bytes, of the source data, and allocate a buffer that is
+ * `cvt->len * cvt->len_mult` bytes long for the `buf` field.
+ *
+ * The source data should be copied into this buffer before the call to
+ * SDL_ConvertAudio(). Upon successful return, this buffer will contain the
+ * converted audio, and `cvt->len_cvt` will be the size of the converted data,
+ * in bytes. Any bytes in the buffer past `cvt->len_cvt` are undefined once
+ * this function returns.
+ *
+ * \param cvt an SDL_AudioCVT structure that was previously set up by
+ * SDL_BuildAudioCVT().
+ * \returns 0 if the conversion was completed successfully or a negative error
+ * code on failure; call SDL_GetError() for more information.
+ *
+ * \sa SDL_BuildAudioCVT
*/
extern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT * cvt);
@@ -551,7 +791,7 @@ struct _SDL_AudioStream;
typedef struct _SDL_AudioStream SDL_AudioStream;
/**
- * Create a new audio stream
+ * Create a new audio stream.
*
* \param src_format The format of the source audio
* \param src_channels The number of channels of the source audio
@@ -559,7 +799,7 @@ typedef struct _SDL_AudioStream SDL_AudioStream;
* \param dst_format The format of the desired audio output
* \param dst_channels The number of channels of the desired audio output
* \param dst_rate The sampling rate of the desired audio output
- * \return 0 on success, or -1 on error.
+ * \returns 0 on success, or -1 on error.
*
* \sa SDL_AudioStreamPut
* \sa SDL_AudioStreamGet
@@ -576,12 +816,12 @@ extern DECLSPEC SDL_AudioStream * SDLCALL SDL_NewAudioStream(const SDL_AudioForm
const int dst_rate);
/**
- * Add data to be converted/resampled to the stream
+ * Add data to be converted/resampled to the stream.
*
* \param stream The stream the audio data is being added to
* \param buf A pointer to the audio data to add
* \param len The number of bytes to write to the stream
- * \return 0 on success, or -1 on error.
+ * \returns 0 on success, or -1 on error.
*
* \sa SDL_NewAudioStream
* \sa SDL_AudioStreamGet
@@ -598,7 +838,7 @@ extern DECLSPEC int SDLCALL SDL_AudioStreamPut(SDL_AudioStream *stream, const vo
* \param stream The stream the audio is being requested from
* \param buf A buffer to fill with audio data
* \param len The maximum number of bytes to fill
- * \return The number of bytes read from the stream, or -1 on error
+ * \returns the number of bytes read from the stream, or -1 on error
*
* \sa SDL_NewAudioStream
* \sa SDL_AudioStreamPut
@@ -667,19 +907,55 @@ extern DECLSPEC void SDLCALL SDL_FreeAudioStream(SDL_AudioStream *stream);
#define SDL_MIX_MAXVOLUME 128
/**
- * This takes two audio buffers of the playing audio format and mixes
- * them, performing addition, volume adjustment, and overflow clipping.
- * The volume ranges from 0 - 128, and should be set to ::SDL_MIX_MAXVOLUME
- * for full audio volume. Note this does not change hardware volume.
- * This is provided for convenience -- you can mix your own audio data.
+ * This function is a legacy means of mixing audio.
+ *
+ * This function is equivalent to calling
+ *
+ * ```c++
+ * SDL_MixAudioFormat(dst, src, format, len, volume);
+ * ```
+ *
+ * where `format` is the obtained format of the audio device from the legacy
+ * SDL_OpenAudio() function.
+ *
+ * \param dst the destination for the mixed audio
+ * \param src the source audio buffer to be mixed
+ * \param len the length of the audio buffer in bytes
+ * \param volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME
+ * for full audio volume
+ *
+ * \sa SDL_MixAudioFormat
*/
extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src,
Uint32 len, int volume);
/**
- * This works like SDL_MixAudio(), but you specify the audio format instead of
- * using the format of audio device 1. Thus it can be used when no audio
- * device is open at all.
+ * Mix audio data in a specified format.
+ *
+ * This takes an audio buffer `src` of `len` bytes of `format` data and
+ * mixes it into `dst`, performing addition, volume adjustment, and overflow
+ * clipping. The buffer pointed to by `dst` must also be `len` bytes of
+ * `format` data.
+ *
+ * This is provided for convenience -- you can mix your own audio data.
+ *
+ * Do not use this function for mixing together more than two streams of
+ * sample data. The output from repeated application of this function may be
+ * distorted by clipping, because there is no accumulator with greater range
+ * than the input (not to mention this being an inefficient way of doing it).
+ *
+ * It is a common misconception that this function is required to write audio
+ * data to an output stream in an audio callback. While you can do that,
+ * SDL_MixAudioFormat() is really only needed when you're mixing a single
+ * audio stream with a volume adjustment.
+ *
+ * \param dst the destination for the mixed audio
+ * \param src the source audio buffer to be mixed
+ * \param format the SDL_AudioFormat structure representing the desired audio
+ * format
+ * \param len the length of the audio buffer in bytes
+ * \param volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME
+ * for full audio volume
*/
extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst,
const Uint8 * src,
@@ -687,161 +963,163 @@ extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst,
Uint32 len, int volume);
/**
- * Queue more audio on non-callback devices.
- *
- * (If you are looking to retrieve queued audio from a non-callback capture
- * device, you want SDL_DequeueAudio() instead. This will return -1 to
- * signify an error if you use it with capture devices.)
- *
- * SDL offers two ways to feed audio to the device: you can either supply a
- * callback that SDL triggers with some frequency to obtain more audio
- * (pull method), or you can supply no callback, and then SDL will expect
- * you to supply data at regular intervals (push method) with this function.
- *
- * There are no limits on the amount of data you can queue, short of
- * exhaustion of address space. Queued data will drain to the device as
- * necessary without further intervention from you. If the device needs
- * audio but there is not enough queued, it will play silence to make up
- * the difference. This means you will have skips in your audio playback
- * if you aren't routinely queueing sufficient data.
- *
- * This function copies the supplied data, so you are safe to free it when
- * the function returns. This function is thread-safe, but queueing to the
- * same device from two threads at once does not promise which buffer will
- * be queued first.
- *
- * You may not queue audio on a device that is using an application-supplied
- * callback; doing so returns an error. You have to use the audio callback
- * or queue audio with this function, but not both.
- *
- * You should not call SDL_LockAudio() on the device before queueing; SDL
- * handles locking internally for this function.
- *
- * \param dev The device ID to which we will queue audio.
- * \param data The data to queue to the device for later playback.
- * \param len The number of bytes (not samples!) to which (data) points.
- * \return 0 on success, or -1 on error.
- *
- * \sa SDL_GetQueuedAudioSize
- * \sa SDL_ClearQueuedAudio
+ * Queue more audio on non-callback devices.
+ *
+ * If you are looking to retrieve queued audio from a non-callback capture
+ * device, you want SDL_DequeueAudio() instead. SDL_QueueAudio() will return
+ * -1 to signify an error if you use it with capture devices.
+ *
+ * SDL offers two ways to feed audio to the device: you can either supply a
+ * callback that SDL triggers with some frequency to obtain more audio (pull
+ * method), or you can supply no callback, and then SDL will expect you to
+ * supply data at regular intervals (push method) with this function.
+ *
+ * There are no limits on the amount of data you can queue, short of
+ * exhaustion of address space. Queued data will drain to the device as
+ * necessary without further intervention from you. If the device needs audio
+ * but there is not enough queued, it will play silence to make up the
+ * difference. This means you will have skips in your audio playback if you
+ * aren't routinely queueing sufficient data.
+ *
+ * This function copies the supplied data, so you are safe to free it when the
+ * function returns. This function is thread-safe, but queueing to the same
+ * device from two threads at once does not promise which buffer will be
+ * queued first.
+ *
+ * You may not queue audio on a device that is using an application-supplied
+ * callback; doing so returns an error. You have to use the audio callback or
+ * queue audio with this function, but not both.
+ *
+ * You should not call SDL_LockAudio() on the device before queueing; SDL
+ * handles locking internally for this function.
+ *
+ * \param dev the device ID to which we will queue audio
+ * \param data the data to queue to the device for later playback
+ * \param len the number of bytes (not samples!) to which `data` points
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.4.
+ *
+ * \sa SDL_ClearQueuedAudio
+ * \sa SDL_GetQueuedAudioSize
*/
extern DECLSPEC int SDLCALL SDL_QueueAudio(SDL_AudioDeviceID dev, const void *data, Uint32 len);
/**
- * Dequeue more audio on non-callback devices.
- *
- * (If you are looking to queue audio for output on a non-callback playback
- * device, you want SDL_QueueAudio() instead. This will always return 0
- * if you use it with playback devices.)
- *
- * SDL offers two ways to retrieve audio from a capture device: you can
- * either supply a callback that SDL triggers with some frequency as the
- * device records more audio data, (push method), or you can supply no
- * callback, and then SDL will expect you to retrieve data at regular
- * intervals (pull method) with this function.
- *
- * There are no limits on the amount of data you can queue, short of
- * exhaustion of address space. Data from the device will keep queuing as
- * necessary without further intervention from you. This means you will
- * eventually run out of memory if you aren't routinely dequeueing data.
- *
- * Capture devices will not queue data when paused; if you are expecting
- * to not need captured audio for some length of time, use
- * SDL_PauseAudioDevice() to stop the capture device from queueing more
- * data. This can be useful during, say, level loading times. When
- * unpaused, capture devices will start queueing data from that point,
- * having flushed any capturable data available while paused.
- *
- * This function is thread-safe, but dequeueing from the same device from
- * two threads at once does not promise which thread will dequeued data
- * first.
- *
- * You may not dequeue audio from a device that is using an
- * application-supplied callback; doing so returns an error. You have to use
- * the audio callback, or dequeue audio with this function, but not both.
- *
- * You should not call SDL_LockAudio() on the device before queueing; SDL
- * handles locking internally for this function.
- *
- * \param dev The device ID from which we will dequeue audio.
- * \param data A pointer into where audio data should be copied.
- * \param len The number of bytes (not samples!) to which (data) points.
- * \return number of bytes dequeued, which could be less than requested.
- *
- * \sa SDL_GetQueuedAudioSize
- * \sa SDL_ClearQueuedAudio
+ * Dequeue more audio on non-callback devices.
+ *
+ * If you are looking to queue audio for output on a non-callback playback
+ * device, you want SDL_QueueAudio() instead. SDL_DequeueAudio() will always
+ * return 0 if you use it with playback devices.
+ *
+ * SDL offers two ways to retrieve audio from a capture device: you can either
+ * supply a callback that SDL triggers with some frequency as the device
+ * records more audio data, (push method), or you can supply no callback, and
+ * then SDL will expect you to retrieve data at regular intervals (pull
+ * method) with this function.
+ *
+ * There are no limits on the amount of data you can queue, short of
+ * exhaustion of address space. Data from the device will keep queuing as
+ * necessary without further intervention from you. This means you will
+ * eventually run out of memory if you aren't routinely dequeueing data.
+ *
+ * Capture devices will not queue data when paused; if you are expecting to
+ * not need captured audio for some length of time, use SDL_PauseAudioDevice()
+ * to stop the capture device from queueing more data. This can be useful
+ * during, say, level loading times. When unpaused, capture devices will start
+ * queueing data from that point, having flushed any capturable data available
+ * while paused.
+ *
+ * This function is thread-safe, but dequeueing from the same device from two
+ * threads at once does not promise which thread will dequeue data first.
+ *
+ * You may not dequeue audio from a device that is using an
+ * application-supplied callback; doing so returns an error. You have to use
+ * the audio callback, or dequeue audio with this function, but not both.
+ *
+ * You should not call SDL_LockAudio() on the device before dequeueing; SDL
+ * handles locking internally for this function.
+ *
+ * \param dev the device ID from which we will dequeue audio
+ * \param data a pointer into where audio data should be copied
+ * \param len the number of bytes (not samples!) to which (data) points
+ * \returns number of bytes dequeued, which could be less than requested; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.5.
+ *
+ * \sa SDL_ClearQueuedAudio
+ * \sa SDL_GetQueuedAudioSize
*/
extern DECLSPEC Uint32 SDLCALL SDL_DequeueAudio(SDL_AudioDeviceID dev, void *data, Uint32 len);
/**
- * Get the number of bytes of still-queued audio.
+ * Get the number of bytes of still-queued audio.
*
- * For playback device:
+ * For playback devices: this is the number of bytes that have been queued
+ * for playback with SDL_QueueAudio(), but have not yet been sent to the
+ * hardware.
*
- * This is the number of bytes that have been queued for playback with
- * SDL_QueueAudio(), but have not yet been sent to the hardware. This
- * number may shrink at any time, so this only informs of pending data.
+ * Once we've sent it to the hardware, this function can not decide the exact
+ * byte boundary of what has been played. It's possible that we just gave the
+ * hardware several kilobytes right before you called this function, but it
+ * hasn't played any of it yet, or maybe half of it, etc.
*
- * Once we've sent it to the hardware, this function can not decide the
- * exact byte boundary of what has been played. It's possible that we just
- * gave the hardware several kilobytes right before you called this
- * function, but it hasn't played any of it yet, or maybe half of it, etc.
+ * For capture devices, this is the number of bytes that have been captured by
+ * the device and are waiting for you to dequeue. This number may grow at any
+ * time, so this only informs of the lower-bound of available data.
*
- * For capture devices:
+ * You may not queue or dequeue audio on a device that is using an
+ * application-supplied callback; calling this function on such a device
+ * always returns 0. You have to use the audio callback or queue audio, but
+ * not both.
*
- * This is the number of bytes that have been captured by the device and
- * are waiting for you to dequeue. This number may grow at any time, so
- * this only informs of the lower-bound of available data.
+ * You should not call SDL_LockAudio() on the device before querying; SDL
+ * handles locking internally for this function.
*
- * You may not queue audio on a device that is using an application-supplied
- * callback; calling this function on such a device always returns 0.
- * You have to queue audio with SDL_QueueAudio()/SDL_DequeueAudio(), or use
- * the audio callback, but not both.
+ * \param dev the device ID of which we will query queued audio size
+ * \returns the number of bytes (not samples!) of queued audio.
*
- * You should not call SDL_LockAudio() on the device before querying; SDL
- * handles locking internally for this function.
+ * \since This function is available since SDL 2.0.4.
*
- * \param dev The device ID of which we will query queued audio size.
- * \return Number of bytes (not samples!) of queued audio.
- *
- * \sa SDL_QueueAudio
- * \sa SDL_ClearQueuedAudio
+ * \sa SDL_ClearQueuedAudio
+ * \sa SDL_QueueAudio
+ * \sa SDL_DequeueAudio
*/
extern DECLSPEC Uint32 SDLCALL SDL_GetQueuedAudioSize(SDL_AudioDeviceID dev);
/**
- * Drop any queued audio data. For playback devices, this is any queued data
- * still waiting to be submitted to the hardware. For capture devices, this
- * is any data that was queued by the device that hasn't yet been dequeued by
- * the application.
+ * Drop any queued audio data waiting to be sent to the hardware.
+ *
+ * Immediately after this call, SDL_GetQueuedAudioSize() will return 0. For
+ * output devices, the hardware will start playing silence if more audio isn't
+ * queued. For capture devices, the hardware will start filling the empty
+ * queue with new data if the capture device isn't paused.
*
- * Immediately after this call, SDL_GetQueuedAudioSize() will return 0. For
- * playback devices, the hardware will start playing silence if more audio
- * isn't queued. Unpaused capture devices will start filling the queue again
- * as soon as they have more data available (which, depending on the state
- * of the hardware and the thread, could be before this function call
- * returns!).
+ * This will not prevent playback of queued audio that's already been sent to
+ * the hardware, as we can not undo that, so expect there to be some fraction
+ * of a second of audio that might still be heard. This can be useful if you
+ * want to, say, drop any pending music or any unprocessed microphone input
+ * during a level change in your game.
*
- * This will not prevent playback of queued audio that's already been sent
- * to the hardware, as we can not undo that, so expect there to be some
- * fraction of a second of audio that might still be heard. This can be
- * useful if you want to, say, drop any pending music during a level change
- * in your game.
+ * You may not queue or dequeue audio on a device that is using an
+ * application-supplied callback; calling this function on such a device
+ * always returns 0. You have to use the audio callback or queue audio, but
+ * not both.
*
- * You may not queue audio on a device that is using an application-supplied
- * callback; calling this function on such a device is always a no-op.
- * You have to queue audio with SDL_QueueAudio()/SDL_DequeueAudio(), or use
- * the audio callback, but not both.
+ * You should not call SDL_LockAudio() on the device before clearing the
+ * queue; SDL handles locking internally for this function.
*
- * You should not call SDL_LockAudio() on the device before clearing the
- * queue; SDL handles locking internally for this function.
+ * This function always succeeds and thus returns void.
*
- * This function always succeeds and thus returns void.
+ * \param dev the device ID of which to clear the audio queue
*
- * \param dev The device ID of which to clear the audio queue.
+ * \since This function is available since SDL 2.0.4.
*
- * \sa SDL_QueueAudio
- * \sa SDL_GetQueuedAudioSize
+ * \sa SDL_GetQueuedAudioSize
+ * \sa SDL_QueueAudio
+ * \sa SDL_DequeueAudio
*/
extern DECLSPEC void SDLCALL SDL_ClearQueuedAudio(SDL_AudioDeviceID dev);
@@ -862,7 +1140,17 @@ extern DECLSPEC void SDLCALL SDL_UnlockAudioDevice(SDL_AudioDeviceID dev);
/* @} *//* Audio lock functions */
/**
- * This function shuts down audio processing and closes the audio device.
+ * This function is a legacy means of closing the audio device.
+ *
+ * This function is equivalent to calling
+ *
+ * ```c++
+ * SDL_CloseAudioDevice(1);
+ * ```
+ *
+ * and is only useful if you used the legacy SDL_OpenAudio() function.
+ *
+ * \sa SDL_OpenAudio
*/
extern DECLSPEC void SDLCALL SDL_CloseAudio(void);
extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev);
diff --git a/include/SDL_blendmode.h b/include/SDL_blendmode.h
index 4c45cad..919588a 100644
--- a/include/SDL_blendmode.h
+++ b/include/SDL_blendmode.h
@@ -91,19 +91,106 @@ typedef enum
} SDL_BlendFactor;
/**
- * \brief Create a custom blend mode, which may or may not be supported by a given renderer
- *
- * \param srcColorFactor source color factor
- * \param dstColorFactor destination color factor
- * \param colorOperation color operation
- * \param srcAlphaFactor source alpha factor
- * \param dstAlphaFactor destination alpha factor
- * \param alphaOperation alpha operation
- *
- * The result of the blend mode operation will be:
- * dstRGB = dstRGB * dstColorFactor colorOperation srcRGB * srcColorFactor
- * and
- * dstA = dstA * dstAlphaFactor alphaOperation srcA * srcAlphaFactor
+ * Compose a custom blend mode for renderers.
+ *
+ * The functions SDL_SetRenderDrawBlendMode and SDL_SetTextureBlendMode accept
+ * the SDL_BlendMode returned by this function if the renderer supports it.
+ *
+ * A blend mode controls how the pixels from a drawing operation (source) get
+ * combined with the pixels from the render target (destination). First, the
+ * components of the source and destination pixels get multiplied with their
+ * blend factors. Then, the blend operation takes the two products and
+ * calculates the result that will get stored in the render target.
+ *
+ * Expressed in pseudocode, it would look like this:
+ *
+ * ```c
+ * dstRGB = colorOperation(srcRGB * srcColorFactor, dstRGB * dstColorFactor);
+ * dstA = alphaOperation(srcA * srcAlphaFactor, dstA * dstAlphaFactor);
+ * ```
+ *
+ * Where the functions `colorOperation(src, dst)` and
+ * `alphaOperation(src, dst)` can return one of the following:
+ *
+ * - `src + dst`
+ *
+ * - `src - dst`
+ *
+ * - `dst - src`
+ *
+ * - `min(src, dst)`
+ *
+ * - `max(src, dst)`
+ *
+ * The red, green, and blue components are always multiplied with the first,
+ * second, and third components of the SDL_BlendFactor, respectively. The
+ * fourth component is not used.
+ *
+ * The alpha component is always multiplied with the fourth component of the
+ * SDL_BlendFactor. The other components are not used in the alpha
+ * calculation.
+ *
+ * Support for these blend modes varies for each renderer. To check if a
+ * specific SDL_BlendMode is supported, create a renderer and pass it to
+ * either SDL_SetRenderDrawBlendMode or SDL_SetTextureBlendMode. They will
+ * return with an error if the blend mode is not supported.
+ *
+ * This list describes the support of custom blend modes for each renderer in
+ * SDL 2.0.6. All renderers support the four blend modes listed in the
+ * SDL_BlendMode enumeration.
+ *
+ * - **direct3d**: Supports `SDL_BLENDOPERATION_ADD` with all factors.
+ *
+ * - **direct3d11**: Supports all operations with all factors. However, some
+ * factors produce unexpected results with `SDL_BLENDOPERATION_MINIMUM` and
+ * `SDL_BLENDOPERATION_MAXIMUM`.
+ *
+ * - **opengl**: Supports the `SDL_BLENDOPERATION_ADD` operation with all
+ * factors. OpenGL versions 1.1, 1.2, and 1.3 do not work correctly with
+ * SDL 2.0.6.
+ *
+ * - **opengles**: Supports the `SDL_BLENDOPERATION_ADD` operation with all
+ * factors. Color and alpha factors need to be the same. OpenGL ES 1
+ * implementation specific: May also support `SDL_BLENDOPERATION_SUBTRACT`
+ * and `SDL_BLENDOPERATION_REV_SUBTRACT`. May support color and alpha
+ * operations being different from each other. May support color and alpha
+ * factors being different from each other.
+ *
+ * - **opengles2**: Supports the `SDL_BLENDOPERATION_ADD`,
+ * `SDL_BLENDOPERATION_SUBTRACT`, `SDL_BLENDOPERATION_REV_SUBTRACT` operations
+ * with all factors.
+ *
+ * - **psp**: No custom blend mode support.
+ *
+ * - **software**: No custom blend mode support.
+ *
+ * Some renderers do not provide an alpha component for the default render
+ * target. The `SDL_BLENDFACTOR_DST_ALPHA` and
+ * `SDL_BLENDFACTOR_ONE_MINUS_DST_ALPHA` factors do not have an effect in this
+ * case.
+ *
+ * \param srcColorFactor the SDL_BlendFactor applied to the red, green, and
+ * blue components of the source pixels
+ * \param dstColorFactor the SDL_BlendFactor applied to the red, green, and
+ * blue components of the destination pixels
+ * \param colorOperation the SDL_BlendOperation used to combine the red,
+ * green, and blue components of the source and
+ * destination pixels
+ * \param srcAlphaFactor the SDL_BlendFactor applied to the alpha component of
+ * the source pixels
+ * \param dstAlphaFactor the SDL_BlendFactor applied to the alpha component of
+ * the destination pixels
+ * \param alphaOperation the SDL_BlendOperation used to combine the alpha
+ * component of the source and destination pixels
+ * \returns an SDL_BlendMode that represents the chosen factors and
+ * operations.
+ *
+ * \since This function is available in SDL 2.0.6.
+ *
+ * \sa SDL_SetRenderDrawBlendMode
+ * \sa SDL_GetRenderDrawBlendMode
+ * \sa SDL_SetTextureBlendMode
+ * \sa SDL_GetTextureBlendMode
*/
extern DECLSPEC SDL_BlendMode SDLCALL SDL_ComposeCustomBlendMode(SDL_BlendFactor srcColorFactor,
SDL_BlendFactor dstColorFactor,
diff --git a/include/SDL_clipboard.h b/include/SDL_clipboard.h
index 1455348..79e4dcc 100644
--- a/include/SDL_clipboard.h
+++ b/include/SDL_clipboard.h
@@ -39,23 +39,41 @@ extern "C" {
/* Function prototypes */
/**
- * \brief Put UTF-8 text into the clipboard
+ * Put UTF-8 text into the clipboard.
*
- * \sa SDL_GetClipboardText()
+ * \param text the text to store in the clipboard
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_GetClipboardText
+ * \sa SDL_HasClipboardText
*/
extern DECLSPEC int SDLCALL SDL_SetClipboardText(const char *text);
/**
- * \brief Get UTF-8 text from the clipboard, which must be freed with SDL_free()
+ * Get UTF-8 text from the clipboard, which must be freed with SDL_free().
+ *
+ * This functions returns NULL if there was not enough memory left for a copy
+ * of the clipboard's content.
+ *
+ * \returns the clipboard text on success or NULL on failure; call
+ * SDL_GetError() for more information. Caller must call SDL_free()
+ * on the returned pointer when done with it.
*
- * \sa SDL_SetClipboardText()
+ * \sa SDL_HasClipboardText
+ * \sa SDL_SetClipboardText
*/
extern DECLSPEC char * SDLCALL SDL_GetClipboardText(void);
/**
- * \brief Returns a flag indicating whether the clipboard exists and contains a text string that is non-empty
+ * Query whether the clipboard exists and contains a non-empty text string.
+ *
+ * \returns SDL_TRUE if the clipboard has text, or SDL_FALSE if it does not.
+ *
+ * \since This function is available since SDL 2.0.0.
*
- * \sa SDL_GetClipboardText()
+ * \sa SDL_GetClipboardText
+ * \sa SDL_SetClipboardText
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasClipboardText(void);
diff --git a/include/SDL_cpuinfo.h b/include/SDL_cpuinfo.h
index d3984be..d527311 100644
--- a/include/SDL_cpuinfo.h
+++ b/include/SDL_cpuinfo.h
@@ -117,136 +117,340 @@ extern "C" {
#define SDL_CACHELINE_SIZE 128
/**
- * This function returns the number of CPU cores available.
+ * Get the number of CPU cores available.
+ *
+ * \returns the total number of logical CPU cores. On CPUs that include
+ * technologies such as hyperthreading, the number of logical cores
+ * may be more than the number of physical cores.
+ *
+ * \since This function is available since SDL 2.0.0.
*/
extern DECLSPEC int SDLCALL SDL_GetCPUCount(void);
/**
- * This function returns the L1 cache line size of the CPU
+ * Determine the L1 cache line size of the CPU.
+ *
+ * This is useful for determining multi-threaded structure padding or SIMD
+ * prefetch sizes.
+ *
+ * \returns the L1 cache line size of the CPU, in bytes.
*
- * This is useful for determining multi-threaded structure padding
- * or SIMD prefetch sizes.
+ * \since This function is available since SDL 2.0.0.
*/
extern DECLSPEC int SDLCALL SDL_GetCPUCacheLineSize(void);
/**
- * This function returns true if the CPU has the RDTSC instruction.
+ * Determine whether the CPU has the RDTSC instruction.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has the RDTSC instruction or SDL_FALSE if not.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasRDTSC(void);
/**
- * This function returns true if the CPU has AltiVec features.
+ * Determine whether the CPU has AltiVec features.
+ *
+ * This always returns false on CPUs that aren't using PowerPC instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has AltiVec features or SDL_FALSE if not.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasAltiVec(void);
/**
- * This function returns true if the CPU has MMX features.
+ * Determine whether the CPU has MMX features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has MMX features or SDL_FALSE if not.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasMMX(void);
/**
- * This function returns true if the CPU has 3DNow! features.
+ * Determine whether the CPU has 3DNow! features.
+ *
+ * This always returns false on CPUs that aren't using AMD instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has 3DNow! features or SDL_FALSE if not.
+ *
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_Has3DNow(void);
/**
- * This function returns true if the CPU has SSE features.
+ * Determine whether the CPU has SSE features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has SSE features or SDL_FALSE if not.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE(void);
/**
- * This function returns true if the CPU has SSE2 features.
+ * Determine whether the CPU has SSE2 features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has SSE2 features or SDL_FALSE if not.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE2(void);
/**
- * This function returns true if the CPU has SSE3 features.
+ * Determine whether the CPU has SSE3 features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has SSE3 features or SDL_FALSE if not.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE3(void);
/**
- * This function returns true if the CPU has SSE4.1 features.
+ * Determine whether the CPU has SSE4.1 features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has SSE4.1 features or SDL_FALSE if not.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE41(void);
/**
- * This function returns true if the CPU has SSE4.2 features.
+ * Determine whether the CPU has SSE4.2 features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has SSE4.2 features or SDL_FALSE if not.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE42(void);
/**
- * This function returns true if the CPU has AVX features.
+ * Determine whether the CPU has AVX features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has AVX features or SDL_FALSE if not.
+ *
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX2
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasAVX(void);
/**
- * This function returns true if the CPU has AVX2 features.
+ * Determine whether the CPU has AVX2 features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has AVX2 features or SDL_FALSE if not.
+ *
+ * \since This function is available since SDL 2.0.4.
+ *
+ * \sa SDL_Has3DNow
+ * \sa SDL_HasAltiVec
+ * \sa SDL_HasAVX
+ * \sa SDL_HasMMX
+ * \sa SDL_HasRDTSC
+ * \sa SDL_HasSSE
+ * \sa SDL_HasSSE2
+ * \sa SDL_HasSSE3
+ * \sa SDL_HasSSE41
+ * \sa SDL_HasSSE42
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasAVX2(void);
/**
- * This function returns true if the CPU has AVX-512F (foundation) features.
+ * Determine whether the CPU has AVX-512F (foundation) features.
+ *
+ * This always returns false on CPUs that aren't using Intel instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has AVX-512F features or SDL_FALSE if not.
+ *
+ * \sa SDL_HasAVX
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasAVX512F(void);
/**
- * This function returns true if the CPU has ARM SIMD (ARMv6) features.
+ * Determine whether the CPU has ARM SIMD (ARMv6) features.
+ *
+ * This is different from ARM NEON, which is a different instruction set.
+ *
+ * This always returns false on CPUs that aren't using ARM instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has ARM SIMD features or SDL_FALSE if not.
+ *
+ * \sa SDL_HasNEON
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasARMSIMD(void);
/**
- * This function returns true if the CPU has NEON (ARM SIMD) features.
+ * Determine whether the CPU has NEON (ARM SIMD) features.
+ *
+ * This always returns false on CPUs that aren't using ARM instruction sets.
+ *
+ * \returns SDL_TRUE if the CPU has ARM NEON features or SDL_FALSE if not.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasNEON(void);
/**
- * This function returns the amount of RAM configured in the system, in MB.
+ * Get the amount of RAM configured in the system.
+ *
+ * \returns the amount of RAM configured in the system in MB.
+ *
+ * \since This function is available since SDL 2.0.1.
*/
extern DECLSPEC int SDLCALL SDL_GetSystemRAM(void);
/**
- * \brief Report the alignment this system needs for SIMD allocations.
+ * Report the alignment this system needs for SIMD allocations.
*
* This will return the minimum number of bytes to which a pointer must be
- * aligned to be compatible with SIMD instructions on the current machine.
- * For example, if the machine supports SSE only, it will return 16, but if
- * it supports AVX-512F, it'll return 64 (etc). This only reports values for
- * instruction sets SDL knows about, so if your SDL build doesn't have
- * SDL_HasAVX512F(), then it might return 16 for the SSE support it sees and
- * not 64 for the AVX-512 instructions that exist but SDL doesn't know about.
- * Plan accordingly.
+ * aligned to be compatible with SIMD instructions on the current machine.
+ * For example, if the machine supports SSE only, it will return 16, but if
+ * it supports AVX-512F, it'll return 64 (etc). This only reports values for
+ * instruction sets SDL knows about, so if your SDL build doesn't have
+ * SDL_HasAVX512F(), then it might return 16 for the SSE support it sees and
+ * not 64 for the AVX-512 instructions that exist but SDL doesn't know about.
+ * Plan accordingly.
+ *
+ * \returns Alignment in bytes needed for available, known SIMD instructions.
*/
extern DECLSPEC size_t SDLCALL SDL_SIMDGetAlignment(void);
/**
- * \brief Allocate memory in a SIMD-friendly way.
+ * Allocate memory in a SIMD-friendly way.
*
* This will allocate a block of memory that is suitable for use with SIMD
- * instructions. Specifically, it will be properly aligned and padded for
- * the system's supported vector instructions.
+ * instructions. Specifically, it will be properly aligned and padded for
+ * the system's supported vector instructions.
*
* The memory returned will be padded such that it is safe to read or write
- * an incomplete vector at the end of the memory block. This can be useful
- * so you don't have to drop back to a scalar fallback at the end of your
- * SIMD processing loop to deal with the final elements without overflowing
- * the allocated buffer.
+ * an incomplete vector at the end of the memory block. This can be useful
+ * so you don't have to drop back to a scalar fallback at the end of your
+ * SIMD processing loop to deal with the final elements without overflowing
+ * the allocated buffer.
*
* You must free this memory with SDL_FreeSIMD(), not free() or SDL_free()
- * or delete[], etc.
+ * or delete[], etc.
*
* Note that SDL will only deal with SIMD instruction sets it is aware of;
- * for example, SDL 2.0.8 knows that SSE wants 16-byte vectors
- * (SDL_HasSSE()), and AVX2 wants 32 bytes (SDL_HasAVX2()), but doesn't
- * know that AVX-512 wants 64. To be clear: if you can't decide to use an
- * instruction set with an SDL_Has*() function, don't use that instruction
- * set with memory allocated through here.
+ * for example, SDL 2.0.8 knows that SSE wants 16-byte vectors
+ * (SDL_HasSSE()), and AVX2 wants 32 bytes (SDL_HasAVX2()), but doesn't
+ * know that AVX-512 wants 64. To be clear: if you can't decide to use an
+ * instruction set with an SDL_Has*() function, don't use that instruction
+ * set with memory allocated through here.
*
* SDL_AllocSIMD(0) will return a non-NULL pointer, assuming the system isn't
- * out of memory.
+ * out of memory, but you are not allowed to dereference it (because you only
+ * own zero bytes of that buffer).
*
- * \param len The length, in bytes, of the block to allocated. The actual
- * allocated block might be larger due to padding, etc.
- * \return Pointer to newly-allocated block, NULL if out of memory.
+ * \param len The length, in bytes, of the block to allocate. The actual
+ * allocated block might be larger due to padding, etc.
+ * \returns Pointer to newly-allocated block, NULL if out of memory.
*
* \sa SDL_SIMDAlignment
* \sa SDL_SIMDRealloc
@@ -255,20 +459,20 @@ extern DECLSPEC size_t SDLCALL SDL_SIMDGetAlignment(void);
extern DECLSPEC void * SDLCALL SDL_SIMDAlloc(const size_t len);
/**
- * \brief Reallocate memory obtained from SDL_SIMDAlloc
+ * Reallocate memory obtained from SDL_SIMDAlloc
*
* It is not valid to use this function on a pointer from anything but
- * SDL_SIMDAlloc(). It can't be used on pointers from malloc, realloc,
- * SDL_malloc, memalign, new[], etc.
- *
- * \param mem The pointer obtained from SDL_SIMDAlloc. This function also
- * accepts NULL, at which point this function is the same as
- * calling SDL_realloc with a NULL pointer.
- * \param len The length, in bytes, of the block to allocated. The actual
- * allocated block might be larger due to padding, etc. Passing 0
- * will return a non-NULL pointer, assuming the system isn't out of
- * memory.
- * \return Pointer to newly-reallocated block, NULL if out of memory.
+ * SDL_SIMDAlloc(). It can't be used on pointers from malloc, realloc,
+ * SDL_malloc, memalign, new[], etc.
+ *
+ * \param mem The pointer obtained from SDL_SIMDAlloc. This function also
+ * accepts NULL, at which point this function is the same as
+ * calling SDL_SIMDAlloc with a NULL pointer.
+ * \param len The length, in bytes, of the block to allocated. The actual
+ * allocated block might be larger due to padding, etc. Passing 0
+ * will return a non-NULL pointer, assuming the system isn't out of
+ * memory.
+ * \returns Pointer to newly-reallocated block, NULL if out of memory.
*
* \sa SDL_SIMDAlignment
* \sa SDL_SIMDAlloc
@@ -277,20 +481,27 @@ extern DECLSPEC void * SDLCALL SDL_SIMDAlloc(const size_t len);
extern DECLSPEC void * SDLCALL SDL_SIMDRealloc(void *mem, const size_t len);
/**
- * \brief Deallocate memory obtained from SDL_SIMDAlloc
+ * Deallocate memory obtained from SDL_SIMDAlloc
*
* It is not valid to use this function on a pointer from anything but
- * SDL_SIMDAlloc(). It can't be used on pointers from malloc, realloc,
- * SDL_malloc, memalign, new[], etc.
+ * SDL_SIMDAlloc() or SDL_SIMDRealloc(). It can't be used on pointers from
+ * malloc, realloc, SDL_malloc, memalign, new[], etc.
*
* However, SDL_SIMDFree(NULL) is a legal no-op.
*
+ * The memory pointed to by `ptr` is no longer valid for access upon return,
+ * and may be returned to the system or reused by a future allocation.
+ * The pointer passed to this function is no longer safe to dereference once
+ * this function returns, and should be discarded.
+ *
+ * \param ptr The pointer, returned from SDL_SIMDAlloc or SDL_SIMDRealloc,
+ * to deallocate. NULL is a legal no-op.
+ *
* \sa SDL_SIMDAlloc
* \sa SDL_SIMDRealloc
*/
extern DECLSPEC void SDLCALL SDL_SIMDFree(void *ptr);
-/* vi: set ts=4 sw=4 expandtab: */
/* Ends C function definitions when using C++ */
#ifdef __cplusplus
}
diff --git a/include/SDL_error.h b/include/SDL_error.h
index 144a170..bb200c5 100644
--- a/include/SDL_error.h
+++ b/include/SDL_error.h
@@ -40,41 +40,83 @@ extern "C" {
/**
- * \brief Set the error message for the current thread
+ * Set the SDL error message for the current thread.
*
- * \return -1, there is no error handling for this function
+ * Calling this function will replace any previous error message that was set.
+ *
+ * This function always returns -1, since SDL frequently uses -1 to signify
+ * an failing result, leading to this idiom:
+ *
+ * ```c
+ * if (error_code) {
+ * return SDL_SetError("This operation has failed: %d", error_code);
+ * }
+ * ```
+ *
+ * \param fmt a printf()-style message format string
+ * \param ... additional parameters matching % tokens in the `fmt` string,
+ * if any
+ * \returns always -1.
+ *
+ * \sa SDL_ClearError
+ * \sa SDL_GetError
*/
extern DECLSPEC int SDLCALL SDL_SetError(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1);
/**
- * \brief Get the last error message that was set
+ * Retrieve a message about the last error that occurred on the current thread.
+ *
+ * It is possible for multiple errors to occur before calling SDL_GetError().
+ * Only the last error is returned.
+ *
+ * The message is only applicable when an SDL function has signaled an error.
+ * You must check the return values of SDL function calls to determine when
+ * to appropriately call SDL_GetError(). You should _not_ use the results
+ * of SDL_GetError() to decide if an error has occurred! Sometimes SDL will
+ * set an error string even when reporting success.
*
- * SDL API functions may set error messages and then succeed, so you should
- * only use the error value if a function fails.
- *
- * This returns a pointer to a static buffer for convenience and should not
- * be called by multiple threads simultaneously.
+ * SDL will _not_ clear the error string for successful API calls. You _must_
+ * check return values for failure cases before you can assume the error
+ * string applies.
*
- * \return a pointer to the last error message that was set
+ * Error strings are set per-thread, so an error set in a different thread
+ * will not interfere with the current thread's operation.
+ *
+ * The returned string is internally allocated and must not be freed by the
+ * application.
+ *
+ * \returns a message with information about the specific error that occurred,
+ * or an empty string if there hasn't been an error message set since
+ * the last call to SDL_ClearError(). The message is only applicable when an
+ * SDL function has signaled an error. You must check the return
+ * values of SDL function calls to determine when to appropriately
+ * call SDL_GetError().
+ *
+ * \sa SDL_ClearError
+ * \sa SDL_SetError
*/
extern DECLSPEC const char *SDLCALL SDL_GetError(void);
/**
- * \brief Get the last error message that was set for the current thread
+ * Get the last error message that was set for the current thread.
*
- * SDL API functions may set error messages and then succeed, so you should
- * only use the error value if a function fails.
- *
- * \param errstr A buffer to fill with the last error message that was set
+ * This allows the caller to copy the error string into a provided buffer,
+ * but otherwise operates exactly the same as SDL_GetError().
+ *
+ * \param errstr A buffer to fill with the last error message that was set
* for the current thread
- * \param maxlen The size of the buffer pointed to by the errstr parameter
+ * \param maxlen The size of the buffer pointed to by the errstr parameter
+ * \returns The pointer passed in as the `errstr` parameter.
*
- * \return errstr
+ * \sa SDL_GetError
*/
extern DECLSPEC char * SDLCALL SDL_GetErrorMsg(char *errstr, int maxlen);
/**
- * \brief Clear the error message for the current thread
+ * Clear any previous error message for this thread.
+ *
+ * \sa SDL_GetError
+ * \sa SDL_SetError
*/
extern DECLSPEC void SDLCALL SDL_ClearError(void);
diff --git a/include/SDL_events.h b/include/SDL_events.h
index c775b10..a2f3e3c 100644
--- a/include/SDL_events.h
+++ b/include/SDL_events.h
@@ -50,7 +50,7 @@ extern "C" {
#define SDL_PRESSED 1
/**
- * \brief The types of events that can be delivered.
+ * The types of events that can be delivered.
*/
typedef enum
{
@@ -637,11 +637,24 @@ SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == 56);
/* Function prototypes */
/**
- * Pumps the event loop, gathering events from the input devices.
+ * Pump the event loop, gathering events from the input devices.
*
- * This function updates the event queue and internal input device state.
+ * This function updates the event queue and internal input device state.
*
- * This should only be run in the thread that sets the video mode.
+ * **WARNING**: This should only be run in the thread that initialized the
+ * video subsystem, and for extra safety, you should consider only doing those
+ * things on the main thread in any case.
+ *
+ * SDL_PumpEvents() gathers all the pending input information from devices and
+ * places it in the event queue. Without calls to SDL_PumpEvents() no events
+ * would ever be placed on the queue. Often the need for calls to
+ * SDL_PumpEvents() is hidden from the user since SDL_PollEvent() and
+ * SDL_WaitEvent() implicitly call SDL_PumpEvents(). However, if you are not
+ * polling or waiting for events (e.g. you are filtering them), then you must
+ * call SDL_PumpEvents() to force an event queue update.
+ *
+ * \sa SDL_PollEvent
+ * \sa SDL_WaitEvent
*/
extern DECLSPEC void SDLCALL SDL_PumpEvents(void);
@@ -654,22 +667,42 @@ typedef enum
} SDL_eventaction;
/**
- * Checks the event queue for messages and optionally returns them.
+ * Check the event queue for messages and optionally return them.
+ *
+ * `action` may be any of the following:
+ *
+ * - `SDL_ADDEVENT`: up to `numevents` events will be added to the back of
+ * the event queue.
+ *
+ * - `SDL_PEEKEVENT`: `numevents` events at the front of the event queue,
+ * within the specified minimum and maximum type, will be returned to the
+ * caller and will _not_ be removed from the queue.
*
- * If \c action is ::SDL_ADDEVENT, up to \c numevents events will be added to
- * the back of the event queue.
+ * - `SDL_GETEVENT`: up to `numevents` events at the front of the event queue,
+ * within the specified minimum and maximum type, will be returned to the
+ * caller and will be removed from the queue.
*
- * If \c action is ::SDL_PEEKEVENT, up to \c numevents events at the front
- * of the event queue, within the specified minimum and maximum type,
- * will be returned and will not be removed from the queue.
+ * You may have to call SDL_PumpEvents() before calling this function.
+ * Otherwise, the events may not be ready to be filtered when you call
+ * SDL_PeepEvents().
*
- * If \c action is ::SDL_GETEVENT, up to \c numevents events at the front
- * of the event queue, within the specified minimum and maximum type,
- * will be returned and will be removed from the queue.
+ * This function is thread-safe.
*
- * \return The number of events actually stored, or -1 if there was an error.
+ * \param events destination buffer for the retrieved events
+ * \param numevents if action is SDL_ADDEVENT, the number of events to add
+ * back to the event queue; if action is SDL_PEEKEVENT or
+ * SDL_GETEVENT, the maximum number of events to retrieve
+ * \param action action to take; see [[#action|Remarks]] for details
+ * \param minType minimum value of the event type to be considered;
+ * SDL_FIRSTEVENT is a safe choice
+ * \param maxType maximum value of the event type to be considered;
+ * SDL_LASTEVENT is a safe choice
+ * \returns the number of events actually stored or a negative error code on
+ * failure; call SDL_GetError() for more information.
*
- * This function is thread-safe.
+ * \sa SDL_PollEvent
+ * \sa SDL_PumpEvents
+ * \sa SDL_PushEvent
*/
extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents,
SDL_eventaction action,
@@ -677,113 +710,330 @@ extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents,
/* @} */
/**
- * Checks to see if certain event types are in the event queue.
+ * Check for the existence of a certain event type in the event queue.
+ *
+ * If you need to check for a range of event types, use SDL_HasEvents()
+ * instead.
+ *
+ * \param type the type of event to be queried; see SDL_EventType for details
+ * \returns SDL_TRUE if events matching `type` are present, or SDL_FALSE if
+ * events matching `type` are not present.
+ *
+ * \sa SDL_HasEvents
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type);
+
+
+/**
+ * Check for the existence of certain event types in the event queue.
+ *
+ * If you need to check for a single event type, use SDL_HasEvent() instead.
+ *
+ * \param minType the low end of event type to be queried, inclusive; see
+ * SDL_EventType for details
+ * \param maxType the high end of event type to be queried, inclusive; see
+ * SDL_EventType for details
+ * \returns SDL_TRUE if events with type >= `minType` and <= `maxType` are
+ * present, or SDL_FALSE if not.
+ *
+ * \sa SDL_HasEvents
+ */
extern DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType);
/**
- * This function clears events from the event queue
- * This function only affects currently queued events. If you want to make
- * sure that all pending OS events are flushed, you can call SDL_PumpEvents()
- * on the main thread immediately before the flush call.
+ * Clear events of a specific type from the event queue.
+ *
+ * This will unconditionally remove any events from the queue that match
+ * `type`. If you need to remove a range of event types, use SDL_FlushEvents()
+ * instead.
+ *
+ * It's also normal to just ignore events you don't care about in your event
+ * loop without calling this function.
+ *
+ * This function only affects currently queued events. If you want to make
+ * sure that all pending OS events are flushed, you can call SDL_PumpEvents()
+ * on the main thread immediately before the flush call.
+ *
+ * \param type the type of event to be cleared; see SDL_EventType for details
+ *
+ * \sa SDL_FlushEvents
*/
extern DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type);
+
+/**
+ * Clear events of a range of types from the event queue.
+ *
+ * This will unconditionally remove any events from the queue that are in the
+ * range of `minType` to `maxType`, inclusive. If you need to remove a single
+ * event type, use SDL_FlushEvent() instead.
+ *
+ * It's also normal to just ignore events you don't care about in your event
+ * loop without calling this function.
+ *
+ * This function only affects currently queued events. If you want to make
+ * sure that all pending OS events are flushed, you can call SDL_PumpEvents()
+ * on the main thread immediately before the flush call.
+ *
+ * \param minType the low end of event type to be cleared, inclusive; see
+ * SDL_EventType for details
+ * \param maxType the high end of event type to be cleared, inclusive; see
+ * SDL_EventType for details
+ *
+ * \sa SDL_FlushEvent
+ */
extern DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType);
/**
- * \brief Polls for currently pending events.
+ * Poll for currently pending events.
+ *
+ * If `event` is not NULL, the next event is removed from the queue and
+ * stored in the SDL_Event structure pointed to by `event`. The 1 returned
+ * refers to this event, immediately stored in the SDL Event structure -- not
+ * an event to follow.
+ *
+ * If `event` is NULL, it simply returns 1 if there is an event in the queue,
+ * but will not remove it from the queue.
*
- * \return 1 if there are any pending events, or 0 if there are none available.
+ * As this function implicitly calls SDL_PumpEvents(), you can only call this
+ * function in the thread that set the video mode.
*
- * \param event If not NULL, the next event is removed from the queue and
- * stored in that area.
+ * SDL_PollEvent() is the favored way of receiving system events since it can
+ * be done from the main loop and does not suspend the main loop while waiting
+ * on an event to be posted.
+ *
+ * The common practice is to fully process the event queue once every frame,
+ * usually as a first step before updating the game's state:
+ *
+ * ```c
+ * while (game_is_still_running) {
+ * SDL_Event event;
+ * while (SDL_PollEvent(&event)) { // poll until all events are handled!
+ * // decide what to do with this event.
+ * }
+ *
+ * // update game state, draw the current frame
+ * }
+ * ```
+ *
+ * \param event the SDL_Event structure to be filled with the next event from
+ * the queue, or NULL
+ * \returns 1 if there is a pending event or 0 if there are none available.
+ *
+ * \sa SDL_GetEventFilter
+ * \sa SDL_PeepEvents
+ * \sa SDL_PushEvent
+ * \sa SDL_SetEventFilter
+ * \sa SDL_WaitEvent
+ * \sa SDL_WaitEventTimeout
*/
extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
/**
- * \brief Waits indefinitely for the next available event.
+ * Wait indefinitely for the next available event.
*
- * \return 1, or 0 if there was an error while waiting for events.
+ * If `event` is not NULL, the next event is removed from the queue and
+ * stored in the SDL_Event structure pointed to by `event`.
*
- * \param event If not NULL, the next event is removed from the queue and
- * stored in that area.
+ * As this function implicitly calls SDL_PumpEvents(), you can only call this
+ * function in the thread that initialized the video subsystem.
+ *
+ * \param event the SDL_Event structure to be filled in with the next event
+ * from the queue, or NULL
+ * \returns 1 on success or 0 if there was an error while waiting for events;
+ * call SDL_GetError() for more information.
+ *
+ * \sa SDL_PollEvent
+ * \sa SDL_PumpEvents
+ * \sa SDL_WaitEventTimeout
*/
extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * event);
/**
- * \brief Waits until the specified timeout (in milliseconds) for the next
- * available event.
+ * Wait until the specified timeout (in milliseconds) for
+ * the next available event.
+ *
+ * If `event` is not NULL, the next event is removed from the queue and
+ * stored in the SDL_Event structure pointed to by `event`.
+ *
+ * As this function implicitly calls SDL_PumpEvents(), you can only call this
+ * function in the thread that initialized the video subsystem.
*
- * \return 1, or 0 if there was an error while waiting for events.
+ * \param event the SDL_Event structure to be filled in with the next event
+ * from the queue, or NULL
+ * \param timeout the maximum number of milliseconds to wait for the next
+ * available event
+ * \returns 1 on success or 0 if there was an error while waiting for events;
+ * call SDL_GetError() for more information. This also returns 0 if
+ * the timeout elapsed without an event arriving.
*
- * \param event If not NULL, the next event is removed from the queue and
- * stored in that area.
- * \param timeout The timeout (in milliseconds) to wait for next event.
+ * \sa SDL_PollEvent
+ * \sa SDL_PumpEvents
+ * \sa SDL_WaitEvent
*/
extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event * event,
int timeout);
/**
- * \brief Add an event to the event queue.
+ * Add an event to the event queue.
*
- * \return 1 on success, 0 if the event was filtered, or -1 if the event queue
- * was full or there was some other error.
+ * The event queue can actually be used as a two way communication channel.
+ * Not only can events be read from the queue, but the user can also push
+ * their own events onto it. `event` is a pointer to the event structure you
+ * wish to push onto the queue. The event is copied into the queue, and the
+ * caller may dispose of the memory pointed to after SDL_PushEvent() returns.
+ *
+ * Note: Pushing device input events onto the queue doesn't modify the state
+ * of the device within SDL.
+ *
+ * This function is thread-safe, and can be called from other threads safely.
+ *
+ * Note: Events pushed onto the queue with SDL_PushEvent() get passed through
+ * the event filter but events added with SDL_PeepEvents() do not.
+ *
+ * For pushing application-specific events, please use SDL_RegisterEvents() to
+ * get an event type that does not conflict with other code that also wants
+ * its own custom event types.
+ *
+ * \param event the SDL_Event to be added to the queue
+ * \returns 1 on success, 0 if the event was filtered, or a negative error
+ * code on failure; call SDL_GetError() for more information. A
+ * common reason for error is the event queue being full.
+ *
+ * \sa SDL_PeepEvents
+ * \sa SDL_PollEvent
+ * \sa SDL_RegisterEvents
*/
extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event);
+/**
+ * A function pointer used for callbacks that watch the event queue.
+ *
+ * \param userdata what was passed as `userdata` to SDL_SetEventFilter()
+ * or SDL_AddEventWatch, etc
+ * \param event the event that triggered the callback
+ * \returns Filters return 1 to permit event to be added to the queue, and
+ * 0 to disallow it. When used with SDL_AddEventWatch, the return
+ * value is ignored.
+ *
+ * \sa SDL_SetEventFilter
+ * \sa SDL_AddEventWatch
+ */
typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
/**
- * Sets up a filter to process all events before they change internal state and
- * are posted to the internal event queue.
+ * Set up a filter to process all events before they change internal state and
+ * are posted to the internal event queue.
*
- * The filter is prototyped as:
- * \code
- * int SDL_EventFilter(void *userdata, SDL_Event * event);
- * \endcode
+ * If the filter function returns 1 when called, then the event will be added
+ * to the internal queue. If it returns 0, then the event will be dropped from
+ * the queue, but the internal state will still be updated. This allows
+ * selective filtering of dynamically arriving events.
*
- * If the filter returns 1, then the event will be added to the internal queue.
- * If it returns 0, then the event will be dropped from the queue, but the
- * internal state will still be updated. This allows selective filtering of
- * dynamically arriving events.
+ * **WARNING**: Be very careful of what you do in the event filter function,
+ * as it may run in a different thread!
*
- * \warning Be very careful of what you do in the event filter function, as
- * it may run in a different thread!
+ * On platforms that support it, if the quit event is generated by an
+ * interrupt signal (e.g. pressing Ctrl-C), it will be delivered to the
+ * application at the next event poll.
*
- * There is one caveat when dealing with the ::SDL_QuitEvent event type. The
- * event filter is only called when the window manager desires to close the
- * application window. If the event filter returns 1, then the window will
- * be closed, otherwise the window will remain open if possible.
+ * There is one caveat when dealing with the ::SDL_QuitEvent event type. The
+ * event filter is only called when the window manager desires to close the
+ * application window. If the event filter returns 1, then the window will
+ * be closed, otherwise the window will remain open if possible.
*
- * If the quit event is generated by an interrupt signal, it will bypass the
- * internal queue and be delivered to the application at the next event poll.
+ * Note: Disabled events never make it to the event filter function; see
+ * SDL_EventState().
+ *
+ * Note: If you just want to inspect events without filtering, you should use
+ * SDL_AddEventWatch() instead.
+ *
+ * Note: Events pushed onto the queue with SDL_PushEvent() get passed through
+ * the event filter, but events pushed onto the queue with SDL_PeepEvents() do
+ * not.
+ *
+ * \param filter An SDL_EventFilter function to call when an event happens
+ * \param userdata a pointer that is passed to `filter`
+ *
+ * \sa SDL_AddEventWatch
+ * \sa SDL_EventState
+ * \sa SDL_GetEventFilter
+ * \sa SDL_PeepEvents
+ * \sa SDL_PushEvent
*/
extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter,
void *userdata);
/**
- * Return the current event filter - can be used to "chain" filters.
- * If there is no event filter set, this function returns SDL_FALSE.
+ * Query the current event filter.
+ *
+ * This function can be used to "chain" filters, by saving the existing filter
+ * before replacing it with a function that will call that saved filter.
+ *
+ * \param filter the current callback function will be stored here
+ * \param userdata the pointer that is passed to the current event filter will
+ * be stored here
+ * \returns SDL_TRUE on success or SDL_FALSE if there is no event filter set.
+ *
+ * \sa SDL_SetEventFilter
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter,
void **userdata);
/**
- * Add a function which is called when an event is added to the queue.
+ * Add a callback to be triggered when an event is added to the event queue.
+ *
+ * `filter` will be called when an event happens, and its return value is
+ * ignored.
+ *
+ * **WARNING**: Be very careful of what you do in the event filter function,
+ * as it may run in a different thread!
+ *
+ * If the quit event is generated by a signal (e.g. SIGINT), it will bypass
+ * the internal queue and be delivered to the watch callback immediately, and
+ * arrive at the next event poll.
+ *
+ * Note: the callback is called for events posted by the user through
+ * SDL_PushEvent(), but not for disabled events, nor for events by a filter
+ * callback set with SDL_SetEventFilter(), nor for events posted by the user
+ * through SDL_PeepEvents().
+ *
+ * \param filter an SDL_EventFilter function to call when an event happens.
+ * \param userdata a pointer that is passed to `filter`
+ *
+ * \sa SDL_DelEventWatch
+ * \sa SDL_SetEventFilter
*/
extern DECLSPEC void SDLCALL SDL_AddEventWatch(SDL_EventFilter filter,
void *userdata);
/**
- * Remove an event watch function added with SDL_AddEventWatch()
+ * Remove an event watch callback added with
+ * SDL_AddEventWatch().
+ *
+ * This function takes the same input as SDL_AddEventWatch() to identify and
+ * delete the corresponding callback.
+ *
+ * \param filter the function originally passed to SDL_AddEventWatch()
+ * \param userdata the pointer originally passed to SDL_AddEventWatch()
+ *
+ * \sa SDL_AddEventWatch
*/
extern DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter,
void *userdata);
/**
- * Run the filter function on the current event queue, removing any
- * events for which the filter returns 0.
+ * Run a specific filter function on the current event
+ * queue, removing any events for which the filter returns 0.
+ *
+ * See SDL_SetEventFilter() for more information. Unlike SDL_SetEventFilter(),
+ * this function does not change the filter permanently, it only uses the
+ * supplied filter until this function returns.
+ *
+ * \param filter the SDL_EventFilter function to call when an event happens
+ * \param userdata a pointer that is passed to `filter`
+ *
+ * \sa SDL_GetEventFilter
+ * \sa SDL_SetEventFilter
*/
extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter,
void *userdata);
@@ -795,24 +1045,45 @@ extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter,
#define SDL_ENABLE 1
/**
- * This function allows you to set the state of processing certain events.
- * - If \c state is set to ::SDL_IGNORE, that event will be automatically
- * dropped from the event queue and will not be filtered.
- * - If \c state is set to ::SDL_ENABLE, that event will be processed
- * normally.
- * - If \c state is set to ::SDL_QUERY, SDL_EventState() will return the
- * current processing state of the specified event.
+ * Set the state of processing events by type.
+ *
+ * `state` may be any of the following:
+ *
+ * - `SDL_QUERY`: returns the current processing state of the specified event
+ *
+ * - `SDL_IGNORE` (aka `SDL_DISABLE`): the event will automatically be dropped
+ * from the event queue and will not be filtered
+ *
+ * - `SDL_ENABLE`: the event will be processed normally
+ *
+ * \param type the type of event; see SDL_EventType for details
+ * \param state how to process the event
+ * \returns `SDL_DISABLE` or `SDL_ENABLE`, representing the processing state
+ * of the event before this function makes any changes to it.
+ *
+ * \sa SDL_GetEventState
*/
extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint32 type, int state);
/* @} */
#define SDL_GetEventState(type) SDL_EventState(type, SDL_QUERY)
/**
- * This function allocates a set of user-defined events, and returns
- * the beginning event number for that set of events.
+ * Allocate a set of user-defined events, and return the beginning event
+ * number for that set of events.
+ *
+ * Calling this function with `numevents` <= 0 is an error and will return
+ * (Uint32)-1.
+ *
+ * Note, (Uint32)-1 means the maximum unsigned 32-bit integer value (or
+ * 0xFFFFFFFF), but is clearer to write.
+ *
+ * \param numevents the number of events to be allocated
+ * \returns The beginning event number, or (Uint32)-1 if there are not enough
+ * user-defined events left.
+ *
+ * \since This function is available since SDL 2.0.0.
*
- * If there aren't enough user-defined events left, this function
- * returns (Uint32)-1
+ * \sa SDL_PushEvent
*/
extern DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents);
diff --git a/include/SDL_filesystem.h b/include/SDL_filesystem.h
index c3b6602..55c93ee 100644
--- a/include/SDL_filesystem.h
+++ b/include/SDL_filesystem.h
@@ -38,88 +38,102 @@ extern "C" {
#endif
/**
- * \brief Get the path where the application resides.
+ * Get the directory where the application was run from.
*
- * Get the "base path". This is the directory where the application was run
- * from, which is probably the installation directory, and may or may not
- * be the process's current working directory.
+ * This is not necessarily a fast call, so you should call this once near
+ * startup and save the string if you need it.
*
- * This returns an absolute path in UTF-8 encoding, and is guaranteed to
- * end with a path separator ('\\' on Windows, '/' most other places).
+ * **Mac OS X and iOS Specific Functionality**: If the application is in a
+ * ".app" bundle, this function returns the Resource directory (e.g.
+ * MyApp.app/Contents/Resources/). This behaviour can be overridden by adding
+ * a property to the Info.plist file. Adding a string key with the name
+ * SDL_FILESYSTEM_BASE_DIR_TYPE with a supported value will change the
+ * behaviour.
*
- * The pointer returned by this function is owned by you. Please call
- * SDL_free() on the pointer when you are done with it, or it will be a
- * memory leak. This is not necessarily a fast call, though, so you should
- * call this once near startup and save the string if you need it.
+ * Supported values for the SDL_FILESYSTEM_BASE_DIR_TYPE property (Given an
+ * application in /Applications/SDLApp/MyApp.app):
*
- * Some platforms can't determine the application's path, and on other
- * platforms, this might be meaningless. In such cases, this function will
- * return NULL.
+ * - `resource`: bundle resource directory (the default). For example:
+ * `/Applications/SDLApp/MyApp.app/Contents/Resources`
*
- * \return String of base dir in UTF-8 encoding, or NULL on error.
+ * - `bundle`: the Bundle directory. Fpr example:
+ * `/Applications/SDLApp/MyApp.app/`
+ *
+ * - `parent`: the containing directory of the bundle. For example:
+ * `/Applications/SDLApp/`
+ *
+ * The returned path is guaranteed to end with a path separator ('\' on
+ * Windows, '/' on most other platforms).
+ *
+ * The pointer returned is owned by the caller. Please call SDL_free() on
+ * the pointer when done with it.
+ *
+ * \returns an absolute path in UTF-8 encoding to the application data
+ * directory. NULL will be returned on error or when the platform
+ * doesn't implement this functionality, call SDL_GetError() for more
+ * information.
+ *
+ * \since This function is available since SDL 2.0.1.
*
* \sa SDL_GetPrefPath
*/
extern DECLSPEC char *SDLCALL SDL_GetBasePath(void);
/**
- * \brief Get the user-and-app-specific path where files can be written.
+ * Get the user-and-app-specific path where files can be written.
*
* Get the "pref dir". This is meant to be where users can write personal
- * files (preferences and save games, etc) that are specific to your
- * application. This directory is unique per user, per application.
+ * files (preferences and save games, etc) that are specific to your
+ * application. This directory is unique per user, per application.
*
* This function will decide the appropriate location in the native filesystem,
- * create the directory if necessary, and return a string of the absolute
- * path to the directory in UTF-8 encoding.
+ * create the directory if necessary, and return a string of the absolute
+ * path to the directory in UTF-8 encoding.
*
* On Windows, the string might look like:
- * "C:\\Users\\bob\\AppData\\Roaming\\My Company\\My Program Name\\"
*
- * On Linux, the string might look like:
- * "/home/bob/.local/share/My Program Name/"
+ * `C:\\Users\\bob\\AppData\\Roaming\\My Company\\My Program Name\\`
+ *
+ * On Linux, the string might look like"
+ *
+ * `/home/bob/.local/share/My Program Name/`
*
* On Mac OS X, the string might look like:
- * "/Users/bob/Library/Application Support/My Program Name/"
- *
- * (etc.)
- *
- * You specify the name of your organization (if it's not a real organization,
- * your name or an Internet domain you own might do) and the name of your
- * application. These should be untranslated proper names.
- *
- * Both the org and app strings may become part of a directory name, so
- * please follow these rules:
- *
- * - Try to use the same org string (including case-sensitivity) for
- * all your applications that use this function.
- * - Always use a unique app string for each one, and make sure it never
- * changes for an app once you've decided on it.
- * - Unicode characters are legal, as long as it's UTF-8 encoded, but...
- * - ...only use letters, numbers, and spaces. Avoid punctuation like
- * "Game Name 2: Bad Guy's Revenge!" ... "Game Name 2" is sufficient.
- *
- * This returns an absolute path in UTF-8 encoding, and is guaranteed to
- * end with a path separator ('\\' on Windows, '/' most other places).
- *
- * The pointer returned by this function is owned by you. Please call
- * SDL_free() on the pointer when you are done with it, or it will be a
- * memory leak. This is not necessarily a fast call, though, so you should
- * call this once near startup and save the string if you need it.
- *
- * You should assume the path returned by this function is the only safe
- * place to write files (and that SDL_GetBasePath(), while it might be
- * writable, or even the parent of the returned path, aren't where you
- * should be writing things).
- *
- * Some platforms can't determine the pref path, and on other
- * platforms, this might be meaningless. In such cases, this function will
- * return NULL.
- *
- * \param org The name of your organization.
- * \param app The name of your application.
- * \return UTF-8 string of user dir in platform-dependent notation. NULL
- * if there's a problem (creating directory failed, etc).
+ *
+ * `/Users/bob/Library/Application Support/My Program Name/`
+ *
+ * You should assume the path returned by this function is the only safe place
+ * to write files (and that SDL_GetBasePath(), while it might be writable, or
+ * even the parent of the returned path, isn't where you should be writing
+ * things).
+ *
+ * Both the org and app strings may become part of a directory name, so please
+ * follow these rules:
+ *
+ * - Try to use the same org string (_including case-sensitivity_) for all
+ * your applications that use this function.
+ *
+ * - Always use a unique app string for each one, and make sure it never
+ * changes for an app once you've decided on it.
+ *
+ * - Unicode characters are legal, as long as it's UTF-8 encoded, but...
+ *
+ * - ...only use letters, numbers, and spaces. Avoid punctuation like "Game
+ * Name 2: Bad Guy's Revenge!" ... "Game Name 2" is sufficient.
+ *
+ * The returned path is guaranteed to end with a path separator ('\' on
+ * Windows, '/' on most other platforms).
+ *
+ * The pointer returned is owned by the caller. Please call SDL_free() on
+ * the pointer when done with it.
+ *
+ * \param org the name of your organization
+ * \param app the name of your application
+ * \returns a UTF-8 string of the user directory in platform-dependent
+ * notation. NULL if there's a problem (creating directory failed,
+ * etc.).
+ *
+ * \since This function is available since SDL 2.0.1.
*
* \sa SDL_GetBasePath
*/
diff --git a/include/SDL_gamecontroller.h b/include/SDL_gamecontroller.h
index aa4b479..5b6461e 100644
--- a/include/SDL_gamecontroller.h
+++ b/include/SDL_gamecontroller.h
@@ -124,12 +124,32 @@ typedef struct SDL_GameControllerButtonBind
*/
/**
- * Load a set of mappings from a seekable SDL data stream (memory or file), filtered by the current SDL_GetPlatform()
- * A community sourced database of controllers is available at https://raw.github.com/gabomdq/SDL_GameControllerDB/master/gamecontrollerdb.txt
+ * Load a set of Game Controller mappings from a seekable SDL data stream.
*
- * If \c freerw is non-zero, the stream will be closed after being read.
- *
- * \return number of mappings added, -1 on error
+ * You can call this function several times, if needed, to load different
+ * database files.
+ *
+ * If a new mapping is loaded for an already known controller GUID, the later
+ * version will overwrite the one currently loaded.
+ *
+ * Mappings not belonging to the current platform or with no platform field
+ * specified will be ignored (i.e. mappings for Linux will be ignored in
+ * Windows, etc).
+ *
+ * This function will load the text database entirely in memory before
+ * processing it, so take this into consideration if you are in a memory
+ * constrained environment.
+ *
+ * \param rw the data stream for the mappings to be added
+ * \param freerw non-zero to close the stream after being read
+ * \returns the number of mappings added or -1 on error; call SDL_GetError()
+ * for more information.
+ *
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \sa SDL_GameControllerAddMapping
+ * \sa SDL_GameControllerAddMappingsFromFile
+ * \sa SDL_GameControllerMappingForGUID
*/
extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw, int freerw);
@@ -141,161 +161,338 @@ extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw,
#define SDL_GameControllerAddMappingsFromFile(file) SDL_GameControllerAddMappingsFromRW(SDL_RWFromFile(file, "rb"), 1)
/**
- * Add or update an existing mapping configuration
+ * Add support for controllers that SDL is unaware of or
+ * to cause an existing controller to have a different binding.
*
- * \return 1 if mapping is added, 0 if updated, -1 on error
+ * The mapping string has the format "GUID,name,mapping", where GUID is the
+ * string value from SDL_JoystickGetGUIDString(), name is the human readable
+ * string for the device and mappings are controller mappings to joystick
+ * ones. Under Windows there is a reserved GUID of "xinput" that covers all
+ * XInput devices. The mapping format for joystick is: {| |bX |a joystick
+ * button, index X |- |hX.Y |hat X with value Y |- |aX |axis X of the joystick
+ * |} Buttons can be used as a controller axes and vice versa.
+ *
+ * This string shows an example of a valid mapping for a controller:
+ *
+ * ```
+ * "341a3608000000000000504944564944,Afterglow PS3 Controller,a:b1,b:b2,y:b3,x:b0,start:b9,guide:b12,back:b8,dpup:h0.1,dpleft:h0.8,dpdown:h0.4,dpright:h0.2,leftshoulder:b4,rightshoulder:b5,leftstick:b10,rightstick:b11,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:b6,righttrigger:b7"
+ * ```
+ *
+ * \param mappingString the mapping string
+ * \returns 1 if a new mapping is added, 0 if an existing mapping is updated,
+ * -1 on error; call SDL_GetError() for more information.
+ *
+ * \sa SDL_GameControllerMapping
+ * \sa SDL_GameControllerMappingForGUID
*/
extern DECLSPEC int SDLCALL SDL_GameControllerAddMapping(const char* mappingString);
/**
- * Get the number of mappings installed
+ * Get the number of mappings installed.
*
- * \return the number of mappings
+ * \returns the number of mappings.
*/
extern DECLSPEC int SDLCALL SDL_GameControllerNumMappings(void);
/**
- * Get the mapping at a particular index.
+ * Get the mapping at a particular index.
*
- * \return the mapping string. Must be freed with SDL_free(). Returns NULL if the index is out of range.
+ * \returns the mapping string. Must be freed with SDL_free().
+ * Returns NULL if the index is out of range.
*/
extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForIndex(int mapping_index);
/**
- * Get a mapping string for a GUID
+ * Get the game controller mapping string for a given GUID.
+ *
+ * The returned string must be freed with SDL_free().
+ *
+ * \param guid a structure containing the GUID for which a mapping is desired
+ * \returns a mapping string or NULL on error; call SDL_GetError() for more
+ * information.
*
- * \return the mapping string. Must be freed with SDL_free(). Returns NULL if no mapping is available
+ * \sa SDL_JoystickGetDeviceGUID
+ * \sa SDL_JoystickGetGUID
*/
extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForGUID(SDL_JoystickGUID guid);
/**
- * Get a mapping string for an open GameController
+ * Get the current mapping of a Game Controller.
*
- * \return the mapping string. Must be freed with SDL_free(). Returns NULL if no mapping is available
+ * The returned string must be freed with SDL_free().
+ *
+ * Details about mappings are discussed with SDL_GameControllerAddMapping().
+ *
+ * \param gamecontroller the game controller you want to get the current
+ * mapping for
+ * \returns a string that has the controller's mapping or NULL if no mapping
+ * is available; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerAddMapping
+ * \sa SDL_GameControllerMappingForGUID
*/
extern DECLSPEC char * SDLCALL SDL_GameControllerMapping(SDL_GameController *gamecontroller);
/**
- * Is the joystick on this index supported by the game controller interface?
+ * Check if the given joystick is supported by the game controller interface.
+ *
+ * `joystick_index` is the same as the `device_index` passed to
+ * SDL_JoystickOpen().
+ *
+ * \param joystick_index the device_index of a device, up to
+ * SDL_NumJoysticks()
+ * \returns SDL_TRUE if the given joystick is supported by the game controller
+ * interface, SDL_FALSE if it isn't or it's an invalid index.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerNameForIndex
+ * \sa SDL_GameControllerOpen
*/
extern DECLSPEC SDL_bool SDLCALL SDL_IsGameController(int joystick_index);
/**
- * Get the implementation dependent name of a game controller.
- * This can be called before any controllers are opened.
- * If no name can be found, this function returns NULL.
+ * Get the implementation dependent name for the game
+ * controller.
+ *
+ * This function can be called before any controllers are opened.
+ *
+ * `joystick_index` is the same as the `device_index` passed to
+ * SDL_JoystickOpen().
+ *
+ * \param joystick_index the device_index of a device, from zero to
+ * SDL_NumJoysticks()-1
+ * \returns the implementation-dependent name for the game controller, or NULL
+ * if there is no name or the index is invalid.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerName
+ * \sa SDL_GameControllerOpen
+ * \sa SDL_IsGameController
*/
extern DECLSPEC const char *SDLCALL SDL_GameControllerNameForIndex(int joystick_index);
/**
- * Get the type of a game controller.
- * This can be called before any controllers are opened.
+ * Get the type of a game controller.
+ *
+ * This can be called before any controllers are opened.
+ *
+ * \param joystick_index the device_index of a device, from zero to
+ * SDL_NumJoysticks()-1
+ * \returns the controller type.
*/
extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerTypeForIndex(int joystick_index);
/**
- * Get the mapping of a game controller.
- * This can be called before any controllers are opened.
+ * Get the mapping of a game controller.
*
- * \return the mapping string. Must be freed with SDL_free(). Returns NULL if no mapping is available
+ * This can be called before any controllers are opened.
+ *
+ * \param joystick_index the device_index of a device, from zero to
+ * SDL_NumJoysticks()-1
+ * \returns the mapping string. Must be freed with SDL_free(). Returns NULL
+ * if no mapping is available.
*/
extern DECLSPEC char *SDLCALL SDL_GameControllerMappingForDeviceIndex(int joystick_index);
/**
- * Open a game controller for use.
- * The index passed as an argument refers to the N'th game controller on the system.
- * This index is not the value which will identify this controller in future
- * controller events. The joystick's instance id (::SDL_JoystickID) will be
- * used there instead.
+ * Open a game controller for use.
+ *
+ * `joystick_index` is the same as the `device_index` passed to
+ * SDL_JoystickOpen().
+ *
+ * The index passed as an argument refers to the N'th game controller on the
+ * system. This index is not the value which will identify this controller in
+ * future controller events. The joystick's instance id (SDL_JoystickID) will
+ * be used there instead.
*
- * \return A controller identifier, or NULL if an error occurred.
+ * \param joystick_index the device_index of a device, up to
+ * SDL_NumJoysticks()
+ * \returns a gamecontroller identifier or NULL if an error occurred; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerClose
+ * \sa SDL_GameControllerNameForIndex
+ * \sa SDL_IsGameController
*/
extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerOpen(int joystick_index);
/**
- * Return the SDL_GameController associated with an instance id.
+ * Get the SDL_GameController associated with an instance id.
+ *
+ * \param joyid the instance id to get the SDL_GameController for
+ * \returns an SDL_GameController on success or NULL on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.4.
*/
extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerFromInstanceID(SDL_JoystickID joyid);
/**
- * Return the SDL_GameController associated with a player index.
+ * Get the SDL_GameController associated with a player index.
+ *
+ * Please note that the player index is _not_ the device index, nor is it
+ * the instance id!
+ *
+ * \param player_index the player index, which is not the device index or
+ * the instance id!
+ * \returns the SDL_GameController associated with a player index.
+ *
+ * \sa SDL_GameControllerGetPlayerIndex
+ * \sa SDL_GameControllerSetPlayerIndex
*/
extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerFromPlayerIndex(int player_index);
/**
- * Return the name for this currently opened controller
+ * Get the implementation-dependent name for an opened game controller.
+ *
+ * This is the same name as returned by SDL_GameControllerNameForIndex(), but
+ * it takes a controller identifier instead of the (unstable) device index.
+ *
+ * \param gamecontroller a game controller identifier previously returned by
+ * SDL_GameControllerOpen()
+ * \returns the implementation dependent name for the game controller, or NULL
+ * if there is no name or the identifier passed is invalid.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerNameForIndex
+ * \sa SDL_GameControllerOpen
*/
extern DECLSPEC const char *SDLCALL SDL_GameControllerName(SDL_GameController *gamecontroller);
/**
- * Return the type of this currently opened controller
+ * Get the type of this currently opened controller
+ *
+ * This is the same name as returned by SDL_GameControllerTypeForIndex(), but
+ * it takes a controller identifier instead of the (unstable) device index.
+ *
+ * \param gamecontroller the game controller object to query.
+ * \returns the controller type.
*/
extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerGetType(SDL_GameController *gamecontroller);
/**
- * Get the player index of an opened game controller, or -1 if it's not available
+ * Get the player index of an opened game controller.
*
* For XInput controllers this returns the XInput user index.
+ *
+ * \param gamecontroller the game controller object to query.
+ * \returns player index for controller, or -1 if it's not available.
*/
extern DECLSPEC int SDLCALL SDL_GameControllerGetPlayerIndex(SDL_GameController *gamecontroller);
/**
- * Set the player index of an opened game controller
+ * Set the player index of an opened game controller.
+ *
+ * \param gamecontroller the game controller object to adjust.
+ * \param player_index Player index to assign to this controller.
*/
extern DECLSPEC void SDLCALL SDL_GameControllerSetPlayerIndex(SDL_GameController *gamecontroller, int player_index);
/**
- * Get the USB vendor ID of an opened controller, if available.
- * If the vendor ID isn't available this function returns 0.
+ * Get the USB vendor ID of an opened controller, if available.
+ *
+ * If the vendor ID isn't available this function returns 0.
+ *
+ * \param gamecontroller the game controller object to query.
+ * \return USB vendor ID, or zero if unavailable.
*/
extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetVendor(SDL_GameController *gamecontroller);
/**
- * Get the USB product ID of an opened controller, if available.
- * If the product ID isn't available this function returns 0.
+ * Get the USB product ID of an opened controller, if available.
+ *
+ * If the product ID isn't available this function returns 0.
+ *
+ * \param gamecontroller the game controller object to query.
+ * \return USB product ID, or zero if unavailable.
*/
extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProduct(SDL_GameController *gamecontroller);
/**
- * Get the product version of an opened controller, if available.
- * If the product version isn't available this function returns 0.
+ * Get the product version of an opened controller, if available.
+ *
+ * If the product version isn't available this function returns 0.
+ *
+ * \param gamecontroller the game controller object to query.
+ * \return USB product version, or zero if unavailable.
*/
extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProductVersion(SDL_GameController *gamecontroller);
/**
- * Get the serial number of an opened controller, if available.
+ * Get the serial number of an opened controller, if available.
*
- * Returns the serial number of the controller, or NULL if it is not available.
+ * Returns the serial number of the controller, or NULL if it is not available.
+ *
+ * \param gamecontroller the game controller object to query.
+ * \return Serial number, or NULL if unavailable.
*/
extern DECLSPEC const char * SDLCALL SDL_GameControllerGetSerial(SDL_GameController *gamecontroller);
/**
- * Returns SDL_TRUE if the controller has been opened and currently connected,
- * or SDL_FALSE if it has not.
+ * Check if a controller has been opened and is currently connected.
+ *
+ * \param gamecontroller a game controller identifier previously returned by
+ * SDL_GameControllerOpen()
+ * \returns SDL_TRUE if the controller has been opened and is currently
+ * connected, or SDL_FALSE if not.
+ *
+ * \sa SDL_GameControllerClose
+ * \sa SDL_GameControllerOpen
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerGetAttached(SDL_GameController *gamecontroller);
/**
- * Get the underlying joystick object used by a controller
+ * Get the Joystick ID from a Game Controller.
+ *
+ * This function will give you a SDL_Joystick object, which allows you to use
+ * the SDL_Joystick functions with a SDL_GameController object. This would be
+ * useful for getting a joystick's position at any given time, even if it
+ * hasn't moved (moving it would produce an event, which would have the axis'
+ * value).
+ *
+ * The pointer returned is owned by the SDL_GameController. You should not
+ * call SDL_JoystickClose() on it, for example, since doing so will likely
+ * cause SDL to crash.
+ *
+ * \param gamecontroller the game controller object that you want to get a
+ * joystick from
+ * \returns a SDL_Joystick object; call SDL_GetError() for more information.
*/
extern DECLSPEC SDL_Joystick *SDLCALL SDL_GameControllerGetJoystick(SDL_GameController *gamecontroller);
/**
- * Enable/disable controller event polling.
+ * Query or change current state of Game Controller events.
+ *
+ * If controller events are disabled, you must call SDL_GameControllerUpdate()
+ * yourself and check the state of the controller when you want controller
+ * information.
+ *
+ * Any number can be passed to SDL_GameControllerEventState(), but only -1, 0,
+ * and 1 will have any effect. Other numbers will just be returned.
+ *
+ * \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE`
+ * \returns the same value passed to the function, with exception to -1
+ * (SDL_QUERY), which will return the current state.
*
- * If controller events are disabled, you must call SDL_GameControllerUpdate()
- * yourself and check the state of the controller when you want controller
- * information.
+ * \since This function is available since SDL 2.0.0.
*
- * The state can be one of ::SDL_QUERY, ::SDL_ENABLE or ::SDL_IGNORE.
+ * \sa SDL_JoystickEventState
*/
extern DECLSPEC int SDLCALL SDL_GameControllerEventState(int state);
/**
- * Update the current state of the open game controllers.
+ * Manually pump game controller updates if not using the loop.
*
- * This is called automatically by the event loop if any game controller
- * events are enabled.
+ * This function is called automatically by the event loop if events are
+ * enabled. Under such circumstances, it will not be necessary to call this
+ * function.
*/
extern DECLSPEC void SDLCALL SDL_GameControllerUpdate(void);
@@ -322,35 +519,81 @@ typedef enum
} SDL_GameControllerAxis;
/**
- * turn this string into a axis mapping
+ * Convert a string into SDL_GameControllerAxis enum.
+ *
+ * This function is called internally to translate SDL_GameController mapping
+ * strings for the underlying joystick device into the consistent
+ * SDL_GameController mapping. You do not normally need to call this function
+ * unless you are parsing SDL_GameController mappings in your own code.
+ *
+ * \param str string representing a SDL_GameController axis
+ * \returns the SDL_GameControllerAxis enum corresponding to the input string,
+ * or `SDL_CONTROLLER_AXIS_INVALID` if no match was found.
+ *
+ * \sa SDL_GameControllerGetStringForAxis
*/
-extern DECLSPEC SDL_GameControllerAxis SDLCALL SDL_GameControllerGetAxisFromString(const char *pchString);
+extern DECLSPEC SDL_GameControllerAxis SDLCALL SDL_GameControllerGetAxisFromString(const char *str);
/**
- * turn this axis enum into a string mapping
+ * Convert from an SDL_GameControllerAxis enum to a string.
+ *
+ * The caller should not SDL_free() the returned string.
+ *
+ * \param axis an enum value for a given SDL_GameControllerAxis
+ * \returns a string for the given axis, or NULL if an invalid axis is
+ * specified. The string returned is of the format used by
+ * SDL_GameController mapping strings.
+ *
+ * \sa SDL_GameControllerGetAxisFromString
*/
extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForAxis(SDL_GameControllerAxis axis);
/**
- * Get the SDL joystick layer binding for this controller button mapping
+ * Get the SDL joystick layer binding for a controller axis mapping.
+ *
+ * \param gamecontroller a game controller
+ * \param axis an axis enum value (one of the SDL_GameControllerAxis values)
+ * \returns a SDL_GameControllerButtonBind describing the bind. On
+ * failure (like the given Controller axis doesn't exist on the
+ * device), its `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerGetBindForButton
*/
extern DECLSPEC SDL_GameControllerButtonBind SDLCALL
SDL_GameControllerGetBindForAxis(SDL_GameController *gamecontroller,
SDL_GameControllerAxis axis);
/**
- * Return whether a game controller has a given axis
+ * Query whether a game controller has a given axis.
+ *
+ * This merely reports whether the controller's mapping defined this axis, as
+ * that is all the information SDL has about the physical device.
+ *
+ * \param gamecontroller a game controller
+ * \param axis an axis enum value (an SDL_GameControllerAxis value)
+ * \returns SDL_TRUE if the controller has this axis, SDL_FALSE otherwise.
*/
extern DECLSPEC SDL_bool SDLCALL
SDL_GameControllerHasAxis(SDL_GameController *gamecontroller, SDL_GameControllerAxis axis);
/**
- * Get the current state of an axis control on a game controller.
+ * Get the current state of an axis control on a game controller.
+ *
+ * The axis indices start at index 0.
*
- * The state is a value ranging from -32768 to 32767 (except for the triggers,
- * which range from 0 to 32767).
+ * The state is a value ranging from -32768 to 32767. Triggers, however, range
+ * from 0 to 32767 (they never return a negative value).
*
- * The axis indices start at index 0.
+ * \param gamecontroller a game controller
+ * \param axis an axis index (one of the SDL_GameControllerAxis values)
+ * \returns axis state (including 0) on success or 0 (also) on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerGetButton
*/
extern DECLSPEC Sint16 SDLCALL
SDL_GameControllerGetAxis(SDL_GameController *gamecontroller, SDL_GameControllerAxis axis);
@@ -386,150 +629,207 @@ typedef enum
} SDL_GameControllerButton;
/**
- * turn this string into a button mapping
+ * Convert a string into an SDL_GameControllerButton enum.
+ *
+ * This function is called internally to translate SDL_GameController mapping
+ * strings for the underlying joystick device into the consistent
+ * SDL_GameController mapping. You do not normally need to call this function
+ * unless you are parsing SDL_GameController mappings in your own code.
+ *
+ * \param str string representing a SDL_GameController axis
+ * \returns the SDL_GameControllerButton enum corresponding to the input
+ * string, or `SDL_CONTROLLER_AXIS_INVALID` if no match was found.
+ *
*/
-extern DECLSPEC SDL_GameControllerButton SDLCALL SDL_GameControllerGetButtonFromString(const char *pchString);
+extern DECLSPEC SDL_GameControllerButton SDLCALL SDL_GameControllerGetButtonFromString(const char *str);
/**
- * turn this button enum into a string mapping
+ * Convert from an SDL_GameControllerButton enum to a string.
+ *
+ * The caller should not SDL_free() the returned string.
+ *
+ * \param button an enum value for a given SDL_GameControllerButton
+ * \returns a string for the given button, or NULL if an invalid axis is
+ * specified. The string returned is of the format used by
+ * SDL_GameController mapping strings.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerGetButtonFromString
*/
extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForButton(SDL_GameControllerButton button);
/**
- * Get the SDL joystick layer binding for this controller button mapping
+ * Get the SDL joystick layer binding for a controller button mapping.
+ *
+ * \param gamecontroller a game controller
+ * \param button an button enum value (an SDL_GameControllerButton value)
+ * \returns a SDL_GameControllerButtonBind describing the bind. On
+ * failure (like the given Controller button doesn't exist on the
+ * device), its `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerGetBindForAxis
*/
extern DECLSPEC SDL_GameControllerButtonBind SDLCALL
SDL_GameControllerGetBindForButton(SDL_GameController *gamecontroller,
SDL_GameControllerButton button);
/**
- * Return whether a game controller has a given button
+ * Query whether a game controller has a given button.
+ *
+ * This merely reports whether the controller's mapping defined this button,
+ * as that is all the information SDL has about the physical device.
+ *
+ * \param gamecontroller a game controller
+ * \param button a button enum value (an SDL_GameControllerButton value)
+ * \returns SDL_TRUE if the controller has this button, SDL_FALSE otherwise.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasButton(SDL_GameController *gamecontroller,
SDL_GameControllerButton button);
/**
- * Get the current state of a button on a game controller.
+ * Get the current state of a button on a game controller.
+ *
+ * \param gamecontroller a game controller
+ * \param button a button index (one of the SDL_GameControllerButton values)
+ * \returns 1 for pressed state or 0 for not pressed state or error; call
+ * SDL_GetError() for more information.
*
- * The button indices start at index 0.
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerGetAxis
*/
extern DECLSPEC Uint8 SDLCALL SDL_GameControllerGetButton(SDL_GameController *gamecontroller,
SDL_GameControllerButton button);
/**
- * Get the number of touchpads on a game controller.
+ * Get the number of touchpads on a game controller.
*/
extern DECLSPEC int SDLCALL SDL_GameControllerGetNumTouchpads(SDL_GameController *gamecontroller);
/**
- * Get the number of supported simultaneous fingers on a touchpad on a game controller.
+ * Get the number of supported simultaneous fingers on a touchpad on a game controller.
*/
extern DECLSPEC int SDLCALL SDL_GameControllerGetNumTouchpadFingers(SDL_GameController *gamecontroller, int touchpad);
/**
- * Get the current state of a finger on a touchpad on a game controller.
+ * Get the current state of a finger on a touchpad on a game controller.
*/
extern DECLSPEC int SDLCALL SDL_GameControllerGetTouchpadFinger(SDL_GameController *gamecontroller, int touchpad, int finger, Uint8 *state, float *x, float *y, float *pressure);
/**
- * Return whether a game controller has a particular sensor.
+ * Return whether a game controller has a particular sensor.
*
- * \param gamecontroller The controller to query
- * \param type The type of sensor to query
+ * \param gamecontroller The controller to query
+ * \param type The type of sensor to query
*
- * \return SDL_TRUE if the sensor exists, SDL_FALSE otherwise.
+ * \returns SDL_TRUE if the sensor exists, SDL_FALSE otherwise.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasSensor(SDL_GameController *gamecontroller, SDL_SensorType type);
/**
- * Set whether data reporting for a game controller sensor is enabled
+ * Set whether data reporting for a game controller sensor is enabled.
*
- * \param gamecontroller The controller to update
- * \param type The type of sensor to enable/disable
- * \param enabled Whether data reporting should be enabled
+ * \param gamecontroller The controller to update
+ * \param type The type of sensor to enable/disable
+ * \param enabled Whether data reporting should be enabled
*
- * \return 0 or -1 if an error occurred.
+ * \returns 0 or -1 if an error occurred.
*/
extern DECLSPEC int SDLCALL SDL_GameControllerSetSensorEnabled(SDL_GameController *gamecontroller, SDL_SensorType type, SDL_bool enabled);
/**
- * Query whether sensor data reporting is enabled for a game controller
+ * Query whether sensor data reporting is enabled for a game controller.
*
- * \param gamecontroller The controller to query
- * \param type The type of sensor to query
+ * \param gamecontroller The controller to query
+ * \param type The type of sensor to query
*
- * \return SDL_TRUE if the sensor is enabled, SDL_FALSE otherwise.
+ * \returns SDL_TRUE if the sensor is enabled, SDL_FALSE otherwise.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerIsSensorEnabled(SDL_GameController *gamecontroller, SDL_SensorType type);
/**
- * Get the current state of a game controller sensor.
- *
- * The number of values and interpretation of the data is sensor dependent.
- * See SDL_sensor.h for the details for each type of sensor.
+ * Get the current state of a game controller sensor.
*
- * \param gamecontroller The controller to query
- * \param type The type of sensor to query
- * \param data A pointer filled with the current sensor state
- * \param num_values The number of values to write to data
+ * The number of values and interpretation of the data is sensor dependent.
+ * See SDL_sensor.h for the details for each type of sensor.
*
- * \return 0 or -1 if an error occurred.
+ * \param gamecontroller The controller to query
+ * \param type The type of sensor to query
+ * \param data A pointer filled with the current sensor state
+ * \param num_values The number of values to write to data
+ * \return 0 or -1 if an error occurred.
*/
extern DECLSPEC int SDLCALL SDL_GameControllerGetSensorData(SDL_GameController *gamecontroller, SDL_SensorType type, float *data, int num_values);
/**
- * Start a rumble effect
- * Each call to this function cancels any previous rumble effect, and calling it with 0 intensity stops any rumbling.
+ * Start a rumble effect on a game controller.
*
- * \param gamecontroller The controller to vibrate
- * \param low_frequency_rumble The intensity of the low frequency (left) rumble motor, from 0 to 0xFFFF
- * \param high_frequency_rumble The intensity of the high frequency (right) rumble motor, from 0 to 0xFFFF
- * \param duration_ms The duration of the rumble effect, in milliseconds
+ * Each call to this function cancels any previous rumble effect, and calling
+ * it with 0 intensity stops any rumbling.
*
- * \return 0, or -1 if rumble isn't supported on this controller
+ * \param gamecontroller The controller to vibrate
+ * \param low_frequency_rumble The intensity of the low frequency (left)
+ * rumble motor, from 0 to 0xFFFF
+ * \param high_frequency_rumble The intensity of the high frequency (right)
+ * rumble motor, from 0 to 0xFFFF
+ * \param duration_ms The duration of the rumble effect, in milliseconds
+ * \returns 0, or -1 if rumble isn't supported on this controller
*/
extern DECLSPEC int SDLCALL SDL_GameControllerRumble(SDL_GameController *gamecontroller, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms);
/**
- * Start a rumble effect in the game controller's triggers
- * Each call to this function cancels any previous trigger rumble effect, and calling it with 0 intensity stops any rumbling.
+ * Start a rumble effect in the game controller's triggers.
+ *
+ * Each call to this function cancels any previous trigger rumble effect, and
+ * calling it with 0 intensity stops any rumbling.
*
- * \param gamecontroller The controller to vibrate
- * \param left_rumble The intensity of the left trigger rumble motor, from 0 to 0xFFFF
- * \param right_rumble The intensity of the right trigger rumble motor, from 0 to 0xFFFF
- * \param duration_ms The duration of the rumble effect, in milliseconds
+ * Note that this is rumbling of the _triggers_ and not the game controller as
+ * a whole. The first controller to offer this feature was the PlayStation 5's
+ * DualShock 5.
*
- * \return 0, or -1 if rumble isn't supported on this controller
+ * \param gamecontroller The controller to vibrate
+ * \param left_rumble The intensity of the left trigger rumble motor, from 0
+ * to 0xFFFF
+ * \param right_rumble The intensity of the right trigger rumble motor, from 0 to 0xFFFF
+ * \param duration_ms The duration of the rumble effect, in milliseconds
+ *
+ * \returns 0, or -1 if trigger rumble isn't supported on this controller
*/
extern DECLSPEC int SDLCALL SDL_GameControllerRumbleTriggers(SDL_GameController *gamecontroller, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms);
/**
- * Return whether a controller has an LED
- *
- * \param gamecontroller The controller to query
+ * Query whether a game controller has an LED.
*
- * \return SDL_TRUE, or SDL_FALSE if this controller does not have a modifiable LED
+ * \param gamecontroller The controller to query
+ * \returns SDL_TRUE, or SDL_FALSE if this controller does not have a
+ * modifiable LED
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasLED(SDL_GameController *gamecontroller);
/**
- * Update a controller's LED color.
- *
- * \param gamecontroller The controller to update
- * \param red The intensity of the red LED
- * \param green The intensity of the green LED
- * \param blue The intensity of the blue LED
+ * Update a game controller's LED color.
*
- * \return 0, or -1 if this controller does not have a modifiable LED
+ * \param gamecontroller The controller to update
+ * \param red The intensity of the red LED
+ * \param green The intensity of the green LED
+ * \param blue The intensity of the blue LED
+ * \returns 0, or -1 if this controller does not have a modifiable LED
*/
extern DECLSPEC int SDLCALL SDL_GameControllerSetLED(SDL_GameController *gamecontroller, Uint8 red, Uint8 green, Uint8 blue);
/**
- * Close a controller previously opened with SDL_GameControllerOpen().
+ * Close a game controller previously opened with SDL_GameControllerOpen().
+ *
+ * \param gamecontroller a game controller identifier previously returned by
+ * SDL_GameControllerOpen()
+ *
+ * \sa SDL_GameControllerOpen
*/
extern DECLSPEC void SDLCALL SDL_GameControllerClose(SDL_GameController *gamecontroller);
-
/* Ends C function definitions when using C++ */
#ifdef __cplusplus
}
diff --git a/include/SDL_gesture.h b/include/SDL_gesture.h
index a7382bc..530b3d5 100644
--- a/include/SDL_gesture.h
+++ b/include/SDL_gesture.h
@@ -46,36 +46,66 @@ typedef Sint64 SDL_GestureID;
/* Function prototypes */
/**
- * \brief Begin Recording a gesture on the specified touch, or all touches (-1)
+ * Begin recording a gesture on a specified touch device or all touch devices.
*
+ * If the parameter `touchId` is -1 (i.e., all devices), this function will
+ * always return 1, regardless of whether there actually are any devices.
*
+ * \param touchId the touch device id, or -1 for all touch devices
+ * \returns 1 on success or 0 if the specified device could not be found.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetTouchDevice
*/
extern DECLSPEC int SDLCALL SDL_RecordGesture(SDL_TouchID touchId);
/**
- * \brief Save all currently loaded Dollar Gesture templates
+ * Save all currently loaded Dollar Gesture templates.
+ *
+ * \param dst a SDL_RWops to save to
+ * \returns the number of saved templates on success or 0 on failure; call
+ * SDL_GetError() for more information.
*
+ * \since This function is available since SDL 2.0.0.
*
+ * \sa SDL_LoadDollarTemplates
+ * \sa SDL_SaveDollarTemplate
*/
extern DECLSPEC int SDLCALL SDL_SaveAllDollarTemplates(SDL_RWops *dst);
/**
- * \brief Save a currently loaded Dollar Gesture template
+ * Save a currently loaded Dollar Gesture template.
*
+ * \param gestureId a gesture id
+ * \param dst a SDL_RWops to save to
+ * \returns 1 on success or 0 on failure; call SDL_GetError() for more
+ * information.
*
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_LoadDollarTemplates
+ * \sa SDL_SaveAllDollarTemplates
*/
extern DECLSPEC int SDLCALL SDL_SaveDollarTemplate(SDL_GestureID gestureId,SDL_RWops *dst);
/**
- * \brief Load Dollar Gesture templates from a file
+ * Load Dollar Gesture templates from a file.
+ *
+ * \param touchId a touch id
+ * \param src a SDL_RWops to load from
+ * \returns the number of loaded templates on success or a negative error code
+ * (or 0) on failure; call SDL_GetError() for more information.
*
+ * \since This function is available since SDL 2.0.0.
*
+ * \sa SDL_SaveAllDollarTemplates
+ * \sa SDL_SaveDollarTemplate
*/
extern DECLSPEC int SDLCALL SDL_LoadDollarTemplates(SDL_TouchID touchId, SDL_RWops *src);
-
/* Ends C function definitions when using C++ */
#ifdef __cplusplus
}
diff --git a/include/SDL_haptic.h b/include/SDL_haptic.h
index 29f4506..424cbd1 100644
--- a/include/SDL_haptic.h
+++ b/include/SDL_haptic.h
@@ -821,418 +821,492 @@ typedef union SDL_HapticEffect
/* Function prototypes */
/**
- * \brief Count the number of haptic devices attached to the system.
+ * Count the number of haptic devices attached to the system.
*
- * \return Number of haptic devices detected on the system.
+ * \returns the number of haptic devices detected on the system or a negative
+ * error code on failure; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticName
*/
extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
/**
- * \brief Get the implementation dependent name of a haptic device.
+ * Get the implementation dependent name of a haptic device.
+ *
+ * This can be called before any joysticks are opened. If no name can be
+ * found, this function returns NULL.
*
- * This can be called before any joysticks are opened.
- * If no name can be found, this function returns NULL.
+ * \param device_index index of the device to query.
+ * \returns the name of the device or NULL on failure; call SDL_GetError() for
+ * more information.
*
- * \param device_index Index of the device to get its name.
- * \return Name of the device or NULL on error.
+ * \since This function is available since SDL 2.0.0.
*
- * \sa SDL_NumHaptics
+ * \sa SDL_NumHaptics
*/
extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
/**
- * \brief Opens a haptic device for use.
+ * Open a haptic device for use.
*
- * The index passed as an argument refers to the N'th haptic device on this
- * system.
+ * The index passed as an argument refers to the N'th haptic device on this
+ * system.
*
- * When opening a haptic device, its gain will be set to maximum and
- * autocenter will be disabled. To modify these values use
- * SDL_HapticSetGain() and SDL_HapticSetAutocenter().
+ * When opening a haptic device, its gain will be set to maximum and
+ * autocenter will be disabled. To modify these values use SDL_HapticSetGain()
+ * and SDL_HapticSetAutocenter().
*
- * \param device_index Index of the device to open.
- * \return Device identifier or NULL on error.
+ * \param device_index index of the device to open
+ * \returns the device identifier or NULL on failure; call SDL_GetError() for
+ * more information.
*
- * \sa SDL_HapticIndex
- * \sa SDL_HapticOpenFromMouse
- * \sa SDL_HapticOpenFromJoystick
- * \sa SDL_HapticClose
- * \sa SDL_HapticSetGain
- * \sa SDL_HapticSetAutocenter
- * \sa SDL_HapticPause
- * \sa SDL_HapticStopAll
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticClose
+ * \sa SDL_HapticIndex
+ * \sa SDL_HapticOpenFromJoystick
+ * \sa SDL_HapticOpenFromMouse
+ * \sa SDL_HapticPause
+ * \sa SDL_HapticSetAutocenter
+ * \sa SDL_HapticSetGain
+ * \sa SDL_HapticStopAll
*/
extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpen(int device_index);
/**
- * \brief Checks if the haptic device at index has been opened.
+ * Check if the haptic device at the designated index has been opened.
*
- * \param device_index Index to check to see if it has been opened.
- * \return 1 if it has been opened or 0 if it hasn't.
+ * \param device_index the index of the device to query
+ * \returns 1 if it has been opened, 0 if it hasn't or on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_HapticOpen
- * \sa SDL_HapticIndex
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticIndex
+ * \sa SDL_HapticOpen
*/
extern DECLSPEC int SDLCALL SDL_HapticOpened(int device_index);
/**
- * \brief Gets the index of a haptic device.
+ * Get the index of a haptic device.
*
- * \param haptic Haptic device to get the index of.
- * \return The index of the haptic device or -1 on error.
+ * \param haptic the SDL_Haptic device to query
+ * \returns the index of the specified haptic device or a negative error code
+ * on failure; call SDL_GetError() for more information.
*
- * \sa SDL_HapticOpen
- * \sa SDL_HapticOpened
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticOpen
+ * \sa SDL_HapticOpened
*/
extern DECLSPEC int SDLCALL SDL_HapticIndex(SDL_Haptic * haptic);
/**
- * \brief Gets whether or not the current mouse has haptic capabilities.
+ * Query whether or not the current mouse has haptic capabilities.
+ *
+ * \returns SDL_TRUE if the mouse is haptic or SDL_FALSE if it isn't.
*
- * \return SDL_TRUE if the mouse is haptic, SDL_FALSE if it isn't.
+ * \since This function is available since SDL 2.0.0.
*
- * \sa SDL_HapticOpenFromMouse
+ * \sa SDL_HapticOpenFromMouse
*/
extern DECLSPEC int SDLCALL SDL_MouseIsHaptic(void);
/**
- * \brief Tries to open a haptic device from the current mouse.
+ * Try to open a haptic device from the current mouse.
*
- * \return The haptic device identifier or NULL on error.
+ * \returns the haptic device identifier or NULL on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_MouseIsHaptic
- * \sa SDL_HapticOpen
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticOpen
+ * \sa SDL_MouseIsHaptic
*/
extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromMouse(void);
/**
- * \brief Checks to see if a joystick has haptic features.
+ * Query if a joystick has haptic features.
*
- * \param joystick Joystick to test for haptic capabilities.
- * \return SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't
- * or -1 if an error occurred.
+ * \param joystick the SDL_Joystick to test for haptic capabilities
+ * \returns SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't, or a
+ * negative error code on failure; call SDL_GetError() for more
+ * information.
*
- * \sa SDL_HapticOpenFromJoystick
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticOpenFromJoystick
*/
extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick);
/**
- * \brief Opens a haptic device for use from a joystick device.
+ * Open a haptic device for use from a joystick device.
*
- * You must still close the haptic device separately. It will not be closed
- * with the joystick.
+ * You must still close the haptic device separately. It will not be closed
+ * with the joystick.
*
- * When opening from a joystick you should first close the haptic device before
- * closing the joystick device. If not, on some implementations the haptic
- * device will also get unallocated and you'll be unable to use force feedback
- * on that device.
+ * When opened from a joystick you should first close the haptic device before
+ * closing the joystick device. If not, on some implementations the haptic
+ * device will also get unallocated and you'll be unable to use force feedback
+ * on that device.
*
- * \param joystick Joystick to create a haptic device from.
- * \return A valid haptic device identifier on success or NULL on error.
+ * \param joystick the SDL_Joystick to create a haptic device from
+ * \returns a valid haptic device identifier on success or NULL on failure;
+ * call SDL_GetError() for more information.
*
- * \sa SDL_HapticOpen
- * \sa SDL_HapticClose
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticClose
+ * \sa SDL_HapticOpen
+ * \sa SDL_JoystickIsHaptic
*/
extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromJoystick(SDL_Joystick *
joystick);
/**
- * \brief Closes a haptic device previously opened with SDL_HapticOpen().
+ * Close a haptic device previously opened with SDL_HapticOpen().
+ *
+ * \param haptic the SDL_Haptic device to close
*
- * \param haptic Haptic device to close.
+ * \sa SDL_HapticOpen
*/
extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic);
/**
- * \brief Returns the number of effects a haptic device can store.
+ * Get the number of effects a haptic device can store.
*
- * On some platforms this isn't fully supported, and therefore is an
- * approximation. Always check to see if your created effect was actually
- * created and do not rely solely on SDL_HapticNumEffects().
+ * On some platforms this isn't fully supported, and therefore is an
+ * approximation. Always check to see if your created effect was actually
+ * created and do not rely solely on SDL_HapticNumEffects().
*
- * \param haptic The haptic device to query effect max.
- * \return The number of effects the haptic device can store or
- * -1 on error.
+ * \param haptic the SDL_Haptic device to query
+ * \returns the number of effects the haptic device can store or a negative
+ * error code on failure; call SDL_GetError() for more information.
*
- * \sa SDL_HapticNumEffectsPlaying
- * \sa SDL_HapticQuery
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticNumEffectsPlaying
+ * \sa SDL_HapticQuery
*/
extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic);
/**
- * \brief Returns the number of effects a haptic device can play at the same
- * time.
+ * Get the number of effects a haptic device can play at
+ * the same time.
+ *
+ * This is not supported on all platforms, but will always return a value.
*
- * This is not supported on all platforms, but will always return a value.
- * Added here for the sake of completeness.
+ * \param haptic the SDL_Haptic device to query maximum playing effects
+ * \returns the number of effects the haptic device can play at the same time
+ * or a negative error code on failure; call SDL_GetError() for more
+ * information.
*
- * \param haptic The haptic device to query maximum playing effects.
- * \return The number of effects the haptic device can play at the same time
- * or -1 on error.
+ * \since This function is available since SDL 2.0.0.
*
- * \sa SDL_HapticNumEffects
- * \sa SDL_HapticQuery
+ * \sa SDL_HapticNumEffects
+ * \sa SDL_HapticQuery
*/
extern DECLSPEC int SDLCALL SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic);
/**
- * \brief Gets the haptic device's supported features in bitwise manner.
+ * Get the haptic device's supported features in bitwise manner.
*
- * Example:
- * \code
- * if (SDL_HapticQuery(haptic) & SDL_HAPTIC_CONSTANT) {
- * printf("We have constant haptic effect!\n");
- * }
- * \endcode
+ * \param haptic the SDL_Haptic device to query
+ * \returns a list of supported haptic features in bitwise manner (OR'd), or 0
+ * on failure; call SDL_GetError() for more information.
*
- * \param haptic The haptic device to query.
- * \return Haptic features in bitwise manner (OR'd).
+ * \since This function is available since SDL 2.0.0.
*
- * \sa SDL_HapticNumEffects
- * \sa SDL_HapticEffectSupported
+ * \sa SDL_HapticEffectSupported
+ * \sa SDL_HapticNumEffects
*/
extern DECLSPEC unsigned int SDLCALL SDL_HapticQuery(SDL_Haptic * haptic);
/**
- * \brief Gets the number of haptic axes the device has.
+ * Get the number of haptic axes the device has.
*
- * \sa SDL_HapticDirection
+ * The number of haptic axes might be useful if working with the
+ * SDL_HapticDirection effect.
+ *
+ * \param haptic the SDL_Haptic device to query
+ * \returns the number of axes on success or a negative error code on failure;
+ * call SDL_GetError() for more information.
*/
extern DECLSPEC int SDLCALL SDL_HapticNumAxes(SDL_Haptic * haptic);
/**
- * \brief Checks to see if effect is supported by haptic.
+ * Check to see if an effect is supported by a haptic
+ * device.
*
- * \param haptic Haptic device to check on.
- * \param effect Effect to check to see if it is supported.
- * \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error.
+ * \param haptic the SDL_Haptic device to query
+ * \param effect the desired effect to query
+ * \returns SDL_TRUE if effect is supported, SDL_FALSE if it isn't, or a
+ * negative error code on failure; call SDL_GetError() for more
+ * information.
*
- * \sa SDL_HapticQuery
- * \sa SDL_HapticNewEffect
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticNewEffect
+ * \sa SDL_HapticQuery
*/
extern DECLSPEC int SDLCALL SDL_HapticEffectSupported(SDL_Haptic * haptic,
SDL_HapticEffect *
effect);
/**
- * \brief Creates a new haptic effect on the device.
+ * Create a new haptic effect on a specified device.
*
- * \param haptic Haptic device to create the effect on.
- * \param effect Properties of the effect to create.
- * \return The identifier of the effect on success or -1 on error.
+ * \param haptic an SDL_Haptic device to create the effect on
+ * \param effect an SDL_HapticEffect structure containing the properties of
+ * the effect to create
+ * \returns the ID of the effect on success or a negative error code on
+ * failure; call SDL_GetError() for more information.
*
- * \sa SDL_HapticUpdateEffect
- * \sa SDL_HapticRunEffect
- * \sa SDL_HapticDestroyEffect
+ * \sa SDL_HapticDestroyEffect
+ * \sa SDL_HapticRunEffect
+ * \sa SDL_HapticUpdateEffect
*/
extern DECLSPEC int SDLCALL SDL_HapticNewEffect(SDL_Haptic * haptic,
SDL_HapticEffect * effect);
/**
- * \brief Updates the properties of an effect.
+ * Update the properties of an effect.
+ *
+ * Can be used dynamically, although behavior when dynamically changing
+ * direction may be strange. Specifically the effect may re-upload itself and
+ * start playing from the start. You also cannot change the type either when
+ * running SDL_HapticUpdateEffect().
*
- * Can be used dynamically, although behavior when dynamically changing
- * direction may be strange. Specifically the effect may reupload itself
- * and start playing from the start. You cannot change the type either when
- * running SDL_HapticUpdateEffect().
+ * \param haptic the SDL_Haptic device that has the effect
+ * \param effect the identifier of the effect to update
+ * \param data an SDL_HapticEffect structure containing the new effect
+ * properties to use
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \param haptic Haptic device that has the effect.
- * \param effect Identifier of the effect to update.
- * \param data New effect properties to use.
- * \return 0 on success or -1 on error.
+ * \since This function is available since SDL 2.0.0.
*
- * \sa SDL_HapticNewEffect
- * \sa SDL_HapticRunEffect
- * \sa SDL_HapticDestroyEffect
+ * \sa SDL_HapticDestroyEffect
+ * \sa SDL_HapticNewEffect
+ * \sa SDL_HapticRunEffect
*/
extern DECLSPEC int SDLCALL SDL_HapticUpdateEffect(SDL_Haptic * haptic,
int effect,
SDL_HapticEffect * data);
/**
- * \brief Runs the haptic effect on its associated haptic device.
+ * Run the haptic effect on its associated haptic device.
*
- * If iterations are ::SDL_HAPTIC_INFINITY, it'll run the effect over and over
- * repeating the envelope (attack and fade) every time. If you only want the
- * effect to last forever, set ::SDL_HAPTIC_INFINITY in the effect's length
- * parameter.
+ * To repeat the effect over and over indefinitely, set `iterations` to
+ * `SDL_HAPTIC_INFINITY`. (Repeats the envelope - attack and fade.) To make
+ * one instance of the effect last indefinitely (so the effect does not fade),
+ * set the effect's `length` in its structure/union to `SDL_HAPTIC_INFINITY`
+ * instead.
*
- * \param haptic Haptic device to run the effect on.
- * \param effect Identifier of the haptic effect to run.
- * \param iterations Number of iterations to run the effect. Use
- * ::SDL_HAPTIC_INFINITY for infinity.
- * \return 0 on success or -1 on error.
+ * \param haptic the SDL_Haptic device to run the effect on
+ * \param effect the ID of the haptic effect to run
+ * \param iterations the number of iterations to run the effect; use
+ * `SDL_HAPTIC_INFINITY` to repeat forever
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_HapticStopEffect
- * \sa SDL_HapticDestroyEffect
- * \sa SDL_HapticGetEffectStatus
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticDestroyEffect
+ * \sa SDL_HapticGetEffectStatus
+ * \sa SDL_HapticStopEffect
*/
extern DECLSPEC int SDLCALL SDL_HapticRunEffect(SDL_Haptic * haptic,
int effect,
Uint32 iterations);
/**
- * \brief Stops the haptic effect on its associated haptic device.
+ * Stop the haptic effect on its associated haptic device.
+ * *
+ * \param haptic the SDL_Haptic device to stop the effect on
+ * \param effect the ID of the haptic effect to stop
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \param haptic Haptic device to stop the effect on.
- * \param effect Identifier of the effect to stop.
- * \return 0 on success or -1 on error.
+ * \since This function is available since SDL 2.0.0.
*
- * \sa SDL_HapticRunEffect
- * \sa SDL_HapticDestroyEffect
+ * \sa SDL_HapticDestroyEffect
+ * \sa SDL_HapticRunEffect
*/
extern DECLSPEC int SDLCALL SDL_HapticStopEffect(SDL_Haptic * haptic,
int effect);
/**
- * \brief Destroys a haptic effect on the device.
+ * Destroy a haptic effect on the device.
+ *
+ * This will stop the effect if it's running. Effects are automatically
+ * destroyed when the device is closed.
*
- * This will stop the effect if it's running. Effects are automatically
- * destroyed when the device is closed.
+ * \param haptic the SDL_Haptic device to destroy the effect on
+ * \param effect the ID of the haptic effect to destroy
*
- * \param haptic Device to destroy the effect on.
- * \param effect Identifier of the effect to destroy.
+ * \since This function is available since SDL 2.0.0.
*
- * \sa SDL_HapticNewEffect
+ * \sa SDL_HapticNewEffect
*/
extern DECLSPEC void SDLCALL SDL_HapticDestroyEffect(SDL_Haptic * haptic,
int effect);
/**
- * \brief Gets the status of the current effect on the haptic device.
+ * Get the status of the current effect on the specified
+ * haptic device.
*
- * Device must support the ::SDL_HAPTIC_STATUS feature.
+ * Device must support the SDL_HAPTIC_STATUS feature.
*
- * \param haptic Haptic device to query the effect status on.
- * \param effect Identifier of the effect to query its status.
- * \return 0 if it isn't playing, 1 if it is playing or -1 on error.
+ * \param haptic the SDL_Haptic device to query for the effect status on
+ * \param effect the ID of the haptic effect to query its status
+ * \returns 0 if it isn't playing, 1 if it is playing, or a negative error
+ * code on failure; call SDL_GetError() for more information.
*
- * \sa SDL_HapticRunEffect
- * \sa SDL_HapticStopEffect
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticRunEffect
+ * \sa SDL_HapticStopEffect
*/
extern DECLSPEC int SDLCALL SDL_HapticGetEffectStatus(SDL_Haptic * haptic,
int effect);
/**
- * \brief Sets the global gain of the device.
+ * Set the global gain of the specified haptic device.
*
- * Device must support the ::SDL_HAPTIC_GAIN feature.
+ * Device must support the SDL_HAPTIC_GAIN feature.
*
- * The user may specify the maximum gain by setting the environment variable
- * SDL_HAPTIC_GAIN_MAX which should be between 0 and 100. All calls to
- * SDL_HapticSetGain() will scale linearly using SDL_HAPTIC_GAIN_MAX as the
- * maximum.
+ * The user may specify the maximum gain by setting the environment variable
+ * `SDL_HAPTIC_GAIN_MAX` which should be between 0 and 100. All calls to
+ * SDL_HapticSetGain() will scale linearly using `SDL_HAPTIC_GAIN_MAX` as the
+ * maximum.
*
- * \param haptic Haptic device to set the gain on.
- * \param gain Value to set the gain to, should be between 0 and 100.
- * \return 0 on success or -1 on error.
+ * \param haptic the SDL_Haptic device to set the gain on
+ * \param gain value to set the gain to, should be between 0 and 100 (0 - 100)
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_HapticQuery
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticQuery
*/
extern DECLSPEC int SDLCALL SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
/**
- * \brief Sets the global autocenter of the device.
+ * Set the global autocenter of the device.
*
- * Autocenter should be between 0 and 100. Setting it to 0 will disable
- * autocentering.
+ * Autocenter should be between 0 and 100. Setting it to 0 will disable
+ * autocentering.
*
- * Device must support the ::SDL_HAPTIC_AUTOCENTER feature.
+ * Device must support the SDL_HAPTIC_AUTOCENTER feature.
*
- * \param haptic Haptic device to set autocentering on.
- * \param autocenter Value to set autocenter to, 0 disables autocentering.
- * \return 0 on success or -1 on error.
+ * \param haptic the SDL_Haptic device to set autocentering on
+ * \param autocenter value to set autocenter to (0-100)
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_HapticQuery
+ * \sa SDL_HapticQuery
*/
extern DECLSPEC int SDLCALL SDL_HapticSetAutocenter(SDL_Haptic * haptic,
int autocenter);
/**
- * \brief Pauses a haptic device.
+ * Pause a haptic device.
*
- * Device must support the ::SDL_HAPTIC_PAUSE feature. Call
- * SDL_HapticUnpause() to resume playback.
+ * Device must support the `SDL_HAPTIC_PAUSE` feature. Call
+ * SDL_HapticUnpause() to resume playback.
*
- * Do not modify the effects nor add new ones while the device is paused.
- * That can cause all sorts of weird errors.
+ * Do not modify the effects nor add new ones while the device is paused. That
+ * can cause all sorts of weird errors.
*
- * \param haptic Haptic device to pause.
- * \return 0 on success or -1 on error.
+ * \param haptic the SDL_Haptic device to pause
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_HapticUnpause
+ * \sa SDL_HapticUnpause
*/
extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic);
/**
- * \brief Unpauses a haptic device.
+ * Unpause a haptic device.
*
- * Call to unpause after SDL_HapticPause().
+ * Call to unpause after SDL_HapticPause().
*
- * \param haptic Haptic device to unpause.
- * \return 0 on success or -1 on error.
+ * \param haptic the SDL_Haptic device to unpause
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_HapticPause
+ * \sa SDL_HapticPause
*/
extern DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic * haptic);
/**
- * \brief Stops all the currently playing effects on a haptic device.
+ * Stop all the currently playing effects on a haptic device.
*
- * \param haptic Haptic device to stop.
- * \return 0 on success or -1 on error.
+ * \param haptic the SDL_Haptic device to stop
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*/
extern DECLSPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic * haptic);
/**
- * \brief Checks to see if rumble is supported on a haptic device.
+ * Check whether rumble is supported on a haptic device.
*
- * \param haptic Haptic device to check to see if it supports rumble.
- * \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error.
+ * \param haptic haptic device to check for rumble support
+ * \returns SDL_TRUE if effect is supported, SDL_FALSE if it isn't, or a
+ * negative error code on failure; call SDL_GetError() for more
+ * information.
*
- * \sa SDL_HapticRumbleInit
- * \sa SDL_HapticRumblePlay
- * \sa SDL_HapticRumbleStop
+ * \sa SDL_HapticRumbleInit
+ * \sa SDL_HapticRumblePlay
+ * \sa SDL_HapticRumbleStop
*/
extern DECLSPEC int SDLCALL SDL_HapticRumbleSupported(SDL_Haptic * haptic);
/**
- * \brief Initializes the haptic device for simple rumble playback.
+ * Initialize a haptic device for simple rumble playback.
*
- * \param haptic Haptic device to initialize for simple rumble playback.
- * \return 0 on success or -1 on error.
+ * \param haptic the haptic device to initialize for simple rumble playback
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_HapticOpen
- * \sa SDL_HapticRumbleSupported
- * \sa SDL_HapticRumblePlay
- * \sa SDL_HapticRumbleStop
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticOpen
+ * \sa SDL_HapticRumblePlay
+ * \sa SDL_HapticRumbleStop
+ * \sa SDL_HapticRumbleSupported
*/
extern DECLSPEC int SDLCALL SDL_HapticRumbleInit(SDL_Haptic * haptic);
/**
- * \brief Runs simple rumble on a haptic device
+ * Run a simple rumble effect on a haptic device.
*
- * \param haptic Haptic device to play rumble effect on.
- * \param strength Strength of the rumble to play as a 0-1 float value.
- * \param length Length of the rumble to play in milliseconds.
- * \return 0 on success or -1 on error.
+ * \param haptic the haptic device to play the rumble effect on
+ * \param strength strength of the rumble to play as a 0-1 float value
+ * \param length length of the rumble to play in milliseconds
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_HapticRumbleSupported
- * \sa SDL_HapticRumbleInit
- * \sa SDL_HapticRumbleStop
+ * \sa SDL_HapticRumbleInit
+ * \sa SDL_HapticRumbleStop
+ * \sa SDL_HapticRumbleSupported
*/
extern DECLSPEC int SDLCALL SDL_HapticRumblePlay(SDL_Haptic * haptic, float strength, Uint32 length );
/**
- * \brief Stops the simple rumble on a haptic device.
+ * Stop the simple rumble on a haptic device.
*
- * \param haptic Haptic to stop the rumble on.
- * \return 0 on success or -1 on error.
+ * \param haptic the haptic device to stop the rumble effect on
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_HapticRumbleSupported
- * \sa SDL_HapticRumbleInit
- * \sa SDL_HapticRumblePlay
+ * \sa SDL_HapticRumbleInit
+ * \sa SDL_HapticRumblePlay
+ * \sa SDL_HapticRumbleSupported
*/
extern DECLSPEC int SDLCALL SDL_HapticRumbleStop(SDL_Haptic * haptic);
diff --git a/include/SDL_hints.h b/include/SDL_hints.h
index 097e786..90e45de 100644
--- a/include/SDL_hints.h
+++ b/include/SDL_hints.h
@@ -1671,71 +1671,113 @@ typedef enum
/**
- * \brief Set a hint with a specific priority
+ * Set a hint with a specific priority.
*
- * The priority controls the behavior when setting a hint that already
- * has a value. Hints will replace existing hints of their priority and
- * lower. Environment variables are considered to have override priority.
+ * The priority controls the behavior when setting a hint that already has a
+ * value. Hints will replace existing hints of their priority and lower.
+ * Environment variables are considered to have override priority.
*
- * \return SDL_TRUE if the hint was set, SDL_FALSE otherwise
+ * \param name the hint to set
+ * \param value the value of the hint variable
+ * \param priority the SDL_HintPriority level for the hint
+ * \returns SDL_TRUE if the hint was set, SDL_FALSE otherwise.
+ *
+ * \sa SDL_GetHint
+ * \sa SDL_SetHint
*/
extern DECLSPEC SDL_bool SDLCALL SDL_SetHintWithPriority(const char *name,
const char *value,
SDL_HintPriority priority);
/**
- * \brief Set a hint with normal priority
+ * Set a hint with normal priority.
+ *
+ * Hints will not be set if there is an existing override hint or environment
+ * variable that takes precedence. You can use SDL_SetHintWithPriority() to
+ * set the hint with override priority instead.
+ *
+ * \param name the hint to set
+ * \param value the value of the hint variable
+ * \returns SDL_TRUE if the hint was set, SDL_FALSE otherwise.
*
- * \return SDL_TRUE if the hint was set, SDL_FALSE otherwise
+ * \sa SDL_GetHint
+ * \sa SDL_SetHintWithPriority
*/
extern DECLSPEC SDL_bool SDLCALL SDL_SetHint(const char *name,
const char *value);
/**
- * \brief Get a hint
+ * Get the value of a hint.
*
- * \return The string value of a hint variable.
+ * \param name the hint to query
+ * \returns the string value of a hint or NULL if the hint isn't set.
+ *
+ * \sa SDL_SetHint
+ * \sa SDL_SetHintWithPriority
*/
extern DECLSPEC const char * SDLCALL SDL_GetHint(const char *name);
/**
- * \brief Get a hint
+ * Get the boolean value of a hint variable.
+ *
+ * \param name the name of the hint to get the boolean value from
+ * \param default_value the value to return if the hint does not exist
+ * \returns the boolean value of a hint or the provided default value if the
+ * hint does not exist.
+ *
+ * \since This function is available since SDL 2.0.5.
*
- * \return The boolean value of a hint variable.
+ * \sa SDL_GetHint
+ * \sa SDL_SetHint
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GetHintBoolean(const char *name, SDL_bool default_value);
/**
- * \brief type definition of the hint callback function.
+ * Type definition of the hint callback function.
+ *
+ * \param userdata what was passed as `userdata` to SDL_AddHintCallback()
+ * \param name what was passed as `name` to SDL_AddHintCallback()
+ * \param oldValue the previous hint value
+ * \param newValue the new value hint is to be set to
*/
typedef void (SDLCALL *SDL_HintCallback)(void *userdata, const char *name, const char *oldValue, const char *newValue);
/**
- * \brief Add a function to watch a particular hint
+ * Add a function to watch a particular hint.
+ *
+ * \param name the hint to watch
+ * \param callback An SDL_HintCallback function that will be called when the
+ * hint value changes
+ * \param userdata a pointer to pass to the callback function
+ *
+ * \since This function is available since SDL 2.0.0.
*
- * \param name The hint to watch
- * \param callback The function to call when the hint value changes
- * \param userdata A pointer to pass to the callback function
+ * \sa SDL_DelHintCallback
*/
extern DECLSPEC void SDLCALL SDL_AddHintCallback(const char *name,
SDL_HintCallback callback,
void *userdata);
/**
- * \brief Remove a function watching a particular hint
+ * Remove a function watching a particular hint.
+ *
+ * \param name the hint being watched
+ * \param callback An SDL_HintCallback function that will be called when the
+ * hint value changes
+ * \param userdata a pointer being passed to the callback function
+ *
+ * \since This function is available since SDL 2.0.0.
*
- * \param name The hint being watched
- * \param callback The function being called when the hint value changes
- * \param userdata A pointer being passed to the callback function
+ * \sa SDL_AddHintCallback
*/
extern DECLSPEC void SDLCALL SDL_DelHintCallback(const char *name,
SDL_HintCallback callback,
void *userdata);
/**
- * \brief Clear all hints
+ * Clear all hints.
*
- * This function is called during SDL_Quit() to free stored hints.
+ * This function is automatically called during SDL_Quit().
*/
extern DECLSPEC void SDLCALL SDL_ClearHints(void);
diff --git a/include/SDL_joystick.h b/include/SDL_joystick.h
index 2592040..cfdbcd8 100644
--- a/include/SDL_joystick.h
+++ b/include/SDL_joystick.h
@@ -30,10 +30,12 @@
* The term "instance_id" is the current instantiation of a joystick device in the system, if the joystick is removed and then re-inserted
* then it will get a new instance_id, instance_id's are monotonically increasing identifiers of a joystick plugged in.
*
+ * The term "player_index" is the number assigned to a player on a specific
+ * controller. For XInput controllers this returns the XInput user index.
+ * Many joysticks will not be able to supply this information.
+ *
* The term JoystickGUID is a stable 128-bit identifier for a joystick device that does not change over time, it identifies class of
* the device (a X360 wired controller for example). This identifier is platform dependent.
- *
- *
*/
#ifndef SDL_joystick_h_
@@ -124,17 +126,43 @@ typedef enum
* and game controller events will not be delivered.
*/
extern DECLSPEC void SDLCALL SDL_LockJoysticks(void);
+
+
+/**
+ * Unlocking for multi-threaded access to the joystick API
+ *
+ * If you are using the joystick API or handling events from multiple threads
+ * you should use these locking functions to protect access to the joysticks.
+ *
+ * In particular, you are guaranteed that the joystick list won't change, so
+ * the API functions that take a joystick index will be valid, and joystick
+ * and game controller events will not be delivered.
+ */
extern DECLSPEC void SDLCALL SDL_UnlockJoysticks(void);
/**
- * Count the number of joysticks attached to the system right now
+ * Count the number of joysticks attached to the system.
+ *
+ * \returns the number of attached joysticks on success or a negative error
+ * code on failure; call SDL_GetError() for more information.
+ *
+ * \sa SDL_JoystickName
+ * \sa SDL_JoystickOpen
*/
extern DECLSPEC int SDLCALL SDL_NumJoysticks(void);
/**
- * Get the implementation dependent name of a joystick.
- * This can be called before any joysticks are opened.
- * If no name can be found, this function returns NULL.
+ * Get the implementation dependent name of a joystick.
+ *
+ * This can be called before any joysticks are opened.
+ *
+ * \param device_index the index of the joystick to query (the N'th joystick
+ * on the system)
+ * \returns the name of the selected joystick. If no name can be found, this
+ * function returns NULL; call SDL_GetError() for more information.
+ *
+ * \sa SDL_JoystickName
+ * \sa SDL_JoystickOpen
*/
extern DECLSPEC const char *SDLCALL SDL_JoystickNameForIndex(int device_index);
@@ -145,69 +173,129 @@ extern DECLSPEC const char *SDLCALL SDL_JoystickNameForIndex(int device_index);
extern DECLSPEC int SDLCALL SDL_JoystickGetDevicePlayerIndex(int device_index);
/**
- * Return the GUID for the joystick at this index
- * This can be called before any joysticks are opened.
+ * Get the implementation-dependent GUID for the joystick
+ * at a given device index.
+ *
+ * This function can be called before any joysticks are opened.
+ *
+ * \param device_index the index of the joystick to query (the N'th joystick
+ * on the system
+ * \returns the GUID of the selected joystick. If called on an invalid index,
+ * this function returns a zero GUID
+ *
+ * \sa SDL_JoystickGetGUID
+ * \sa SDL_JoystickGetGUIDString
*/
extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetDeviceGUID(int device_index);
/**
- * Get the USB vendor ID of a joystick, if available.
- * This can be called before any joysticks are opened.
- * If the vendor ID isn't available this function returns 0.
+ * Get the USB vendor ID of a joystick, if available.
+ *
+ * This can be called before any joysticks are opened.
+ * If the vendor ID isn't available this function returns 0.
+ *
+ * \param device_index the index of the joystick to query (the N'th joystick
+ * on the system
+ * \returns the USB vendor ID of the selected joystick. If called on an
+ * invalid index, this function returns zero
*/
extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceVendor(int device_index);
/**
- * Get the USB product ID of a joystick, if available.
- * This can be called before any joysticks are opened.
- * If the product ID isn't available this function returns 0.
+ * Get the USB product ID of a joystick, if available.
+ *
+ * This can be called before any joysticks are opened.
+ * If the product ID isn't available this function returns 0.
+ *
+ * \param device_index the index of the joystick to query (the N'th joystick
+ * on the system
+ * \returns the USB product ID of the selected joystick. If called on an
+ * invalid index, this function returns zero
*/
extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceProduct(int device_index);
/**
- * Get the product version of a joystick, if available.
- * This can be called before any joysticks are opened.
- * If the product version isn't available this function returns 0.
+ * Get the product version of a joystick, if available.
+ *
+ * This can be called before any joysticks are opened.
+ * If the product version isn't available this function returns 0.
+ *
+ * \param device_index the index of the joystick to query (the N'th joystick
+ * on the system
+ * \returns the product version of the selected joystick. If called on an
+ * invalid index, this function returns zero
*/
extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceProductVersion(int device_index);
/**
- * Get the type of a joystick, if available.
- * This can be called before any joysticks are opened.
+ * Get the type of a joystick, if available.
+ *
+ * This can be called before any joysticks are opened.
+ *
+ * \param device_index the index of the joystick to query (the N'th joystick
+ * on the system
+ * \returns the SDL_JoystickType of the selected joystick. If called on an
+ * invalid index, this function returns `SDL_JOYSTICK_TYPE_UNKNOWN`
*/
extern DECLSPEC SDL_JoystickType SDLCALL SDL_JoystickGetDeviceType(int device_index);
/**
- * Get the instance ID of a joystick.
- * This can be called before any joysticks are opened.
- * If the index is out of range, this function will return -1.
+ * Get the instance ID of a joystick.
+ *
+ * This can be called before any joysticks are opened.
+ * If the index is out of range, this function will return -1.
+ *
+ * \param device_index the index of the joystick to query (the N'th joystick
+ * on the system
+ * \returns the instance id of the selected joystick. If called on an invalid
+ * index, this function returns zero
*/
extern DECLSPEC SDL_JoystickID SDLCALL SDL_JoystickGetDeviceInstanceID(int device_index);
/**
- * Open a joystick for use.
- * The index passed as an argument refers to the N'th joystick on the system.
- * This index is not the value which will identify this joystick in future
- * joystick events. The joystick's instance id (::SDL_JoystickID) will be used
- * there instead.
+ * Open a joystick for use.
+ *
+ * The `device_index` argument refers to the N'th joystick presently
+ * recognized by SDL on the system. It is **NOT** the same as the instance ID
+ * used to identify the joystick in future events. See
+ * SDL_JoystickInstanceID() for more details about instance IDs.
+ *
+ * The joystick subsystem must be initialized before a joystick can be opened
+ * for use.
*
- * \return A joystick identifier, or NULL if an error occurred.
+ * \param device_index the index of the joystick to query
+ * \returns a joystick identifier or NULL if an error occurred; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_JoystickClose
+ * \sa SDL_JoystickInstanceID
*/
extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickOpen(int device_index);
/**
- * Return the SDL_Joystick associated with an instance id.
+ * Get the SDL_Joystick associated with an instance id.
+ *
+ * \param joyid the instance id to get the SDL_Joystick for
+ * \returns an SDL_Joystick on success or NULL on failure; call SDL_GetError()
+ * for more information.
+ *
+ * \since This function is available since SDL 2.0.4.
*/
extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickFromInstanceID(SDL_JoystickID instance_id);
/**
- * Return the SDL_Joystick associated with a player index.
+ * Get the SDL_Joystick associated with a player index.
+ *
+ * \param player_index the player index to get the SDL_Joystick for
+ * \returns an SDL_Joystick on success or NULL on failure; call SDL_GetError()
+ * for more information.
*/
extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickFromPlayerIndex(int player_index);
/**
- * Attaches a new virtual joystick.
- * Returns the joystick's device index, or -1 if an error occurred.
+ * Attach a new virtual joystick.
+ *
+ * \returns the joystick's device index, or -1 if an error occurred.
*/
extern DECLSPEC int SDLCALL SDL_JoystickAttachVirtual(SDL_JoystickType type,
int naxes,
@@ -215,166 +303,344 @@ extern DECLSPEC int SDLCALL SDL_JoystickAttachVirtual(SDL_JoystickType type,
int nhats);
/**
- * Detaches a virtual joystick
- * Returns 0 on success, or -1 if an error occurred.
+ * Detach a virtual joystick.
+ *
+ * \param device_index a value previously returned from
+ * SDL_JoystickAttachVirtual()
+ * \returns 0 on success, or -1 if an error occurred.
*/
extern DECLSPEC int SDLCALL SDL_JoystickDetachVirtual(int device_index);
/**
- * Indicates whether or not a virtual-joystick is at a given device index.
+ * Query whether or not the joystick at a given device index is virtual.
+ *
+ * \param device_index a joystick device index.
+ * \returns SDL_TRUE if the joystick is virtual, SDL_FALSE otherwise.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_JoystickIsVirtual(int device_index);
/**
- * Set values on an opened, virtual-joystick's controls.
+ * Set values on an opened, virtual-joystick's axis.
+ *
* Please note that values set here will not be applied until the next
* call to SDL_JoystickUpdate, which can either be called directly,
- * or can be called indirectly through various other SDL APIS,
+ * or can be called indirectly through various other SDL APIs,
* including, but not limited to the following: SDL_PollEvent,
* SDL_PumpEvents, SDL_WaitEventTimeout, SDL_WaitEvent.
*
- * Returns 0 on success, -1 on error.
+ * \param joystick the virtual joystick on which to set state.
+ * \param axis the specific axis on the virtual joystick to set.
+ * \param value the new value for the specified axis.
+ * \returns 0 on success, -1 on error.
*/
extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualAxis(SDL_Joystick *joystick, int axis, Sint16 value);
+
+/**
+ * Set values on an opened, virtual-joystick's button.
+ *
+ * Please note that values set here will not be applied until the next
+ * call to SDL_JoystickUpdate, which can either be called directly,
+ * or can be called indirectly through various other SDL APIs,
+ * including, but not limited to the following: SDL_PollEvent,
+ * SDL_PumpEvents, SDL_WaitEventTimeout, SDL_WaitEvent.
+ *
+ * \param joystick the virtual joystick on which to set state.
+ * \param button the specific button on the virtual joystick to set.
+ * \param value the new value for the specified button.
+ * \returns 0 on success, -1 on error.
+ */
extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualButton(SDL_Joystick *joystick, int button, Uint8 value);
+
+/**
+ * Set values on an opened, virtual-joystick's hat.
+ *
+ * Please note that values set here will not be applied until the next
+ * call to SDL_JoystickUpdate, which can either be called directly,
+ * or can be called indirectly through various other SDL APIs,
+ * including, but not limited to the following: SDL_PollEvent,
+ * SDL_PumpEvents, SDL_WaitEventTimeout, SDL_WaitEvent.
+ *
+ * \param joystick the virtual joystick on which to set state.
+ * \param hat the specific hat on the virtual joystick to set.
+ * \param value the new value for the specified hat.
+ * \returns 0 on success, -1 on error.
+ */
extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualHat(SDL_Joystick *joystick, int hat, Uint8 value);
/**
- * Return the name for this currently opened joystick.
- * If no name can be found, this function returns NULL.
+ * Get the implementation dependent name of a joystick.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the name of the selected joystick. If no name can be found, this
+ * function returns NULL; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_JoystickNameForIndex
+ * \sa SDL_JoystickOpen
*/
extern DECLSPEC const char *SDLCALL SDL_JoystickName(SDL_Joystick *joystick);
/**
- * Get the player index of an opened joystick, or -1 if it's not available
+ * Get the player index of an opened joystick.
*
- * For XInput controllers this returns the XInput user index.
+ * For XInput controllers this returns the XInput user index. Many joysticks
+ * will not be able to supply this information.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the player index, or -1 if it's not available.
*/
extern DECLSPEC int SDLCALL SDL_JoystickGetPlayerIndex(SDL_Joystick *joystick);
/**
- * Set the player index of an opened joystick
+ * Set the player index of an opened joystick.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \param player_index the player index to set.
*/
extern DECLSPEC void SDLCALL SDL_JoystickSetPlayerIndex(SDL_Joystick *joystick, int player_index);
/**
- * Return the GUID for this opened joystick
+ * Get the implementation-dependent GUID for the joystick.
+ *
+ * This function requires an open joystick.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the GUID of the given joystick. If called on an invalid index,
+ * this function returns a zero GUID; call SDL_GetError() for more
+ * information.
+ *
+ * \sa SDL_JoystickGetDeviceGUID
+ * \sa SDL_JoystickGetGUIDString
*/
extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetGUID(SDL_Joystick *joystick);
/**
- * Get the USB vendor ID of an opened joystick, if available.
- * If the vendor ID isn't available this function returns 0.
+ * Get the USB vendor ID of an opened joystick, if available.
+ *
+ * If the vendor ID isn't available this function returns 0.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the USB vendor ID of the selected joystick, or 0 if unavailable.
*/
extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetVendor(SDL_Joystick *joystick);
/**
- * Get the USB product ID of an opened joystick, if available.
- * If the product ID isn't available this function returns 0.
+ * Get the USB product ID of an opened joystick, if available.
+ *
+ * If the product ID isn't available this function returns 0.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the USB product ID of the selected joystick, or 0 if unavailable.
*/
extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProduct(SDL_Joystick *joystick);
/**
- * Get the product version of an opened joystick, if available.
- * If the product version isn't available this function returns 0.
+ * Get the product version of an opened joystick, if available.
+ * If the product version isn't available this function returns 0.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the product version of the selected joystick, or 0 if unavailable.
*/
extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProductVersion(SDL_Joystick *joystick);
/**
- * Get the serial number of an opened joystick, if available.
+ * Get the serial number of an opened joystick, if available.
*
- * Returns the serial number of the joystick, or NULL if it is not available.
+ * Returns the serial number of the joystick, or NULL if it is not available.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the serial number of the selected joystick, or NULL if unavailable.
*/
extern DECLSPEC const char * SDLCALL SDL_JoystickGetSerial(SDL_Joystick *joystick);
/**
- * Get the type of an opened joystick.
+ * Get the type of an opened joystick.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the SDL_JoystickType of the selected joystick.
*/
extern DECLSPEC SDL_JoystickType SDLCALL SDL_JoystickGetType(SDL_Joystick *joystick);
/**
- * Return a string representation for this guid. pszGUID must point to at least 33 bytes
- * (32 for the string plus a NULL terminator).
+ * Get an ASCII string representation for a given SDL_JoystickGUID.
+ *
+ * You should supply at least 33 bytes for pszGUID.
+ *
+ * \param guid the SDL_JoystickGUID you wish to convert to string
+ * \param pszGUID buffer in which to write the ASCII string
+ * \param cbGUID the size of pszGUID
+ *
+ * \sa SDL_JoystickGetDeviceGUID
+ * \sa SDL_JoystickGetGUID
+ * \sa SDL_JoystickGetGUIDFromString
*/
extern DECLSPEC void SDLCALL SDL_JoystickGetGUIDString(SDL_JoystickGUID guid, char *pszGUID, int cbGUID);
/**
- * Convert a string into a joystick guid
+ * Convert a GUID string into a SDL_JoystickGUID structure.
+ *
+ * Performs no error checking. If this function is given a string containing
+ * an invalid GUID, the function will silently succeed, but the GUID generated
+ * will not be useful.
+ *
+ * \param pchGUID string containing an ASCII representation of a GUID
+ * \returns a SDL_JoystickGUID structure.
+ *
+ * \sa SDL_JoystickGetGUIDString
*/
extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetGUIDFromString(const char *pchGUID);
/**
- * Returns SDL_TRUE if the joystick has been opened and currently connected, or SDL_FALSE if it has not.
+ * Get the status of a specified joystick.
+ *
+ * \param joystick the joystick to query
+ * \returns SDL_TRUE if the joystick has been opened, SDL_FALSE if it has not;
+ * call SDL_GetError() for more information.
+ *
+ * \sa SDL_JoystickClose
+ * \sa SDL_JoystickOpen
*/
extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAttached(SDL_Joystick *joystick);
/**
- * Get the instance ID of an opened joystick or -1 if the joystick is invalid.
+ * Get the instance ID of an opened joystick.
+ *
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \returns the instance ID of the specified joystick on success or a negative
+ * error code on failure; call SDL_GetError() for more information.
+ *
+ * \sa SDL_JoystickOpen
*/
extern DECLSPEC SDL_JoystickID SDLCALL SDL_JoystickInstanceID(SDL_Joystick *joystick);
/**
- * Get the number of general axis controls on a joystick.
+ * Get the number of general axis controls on a joystick.
+ *
+ * Often, the directional pad on a game controller will either look like 4
+ * separate buttons or a POV hat, and not axes, but all of this is up to the
+ * device and platform.
+ *
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \returns the number of axis controls/number of axes on success or a
+ * negative error code on failure; call SDL_GetError() for more
+ * information.
+ *
+ * \sa SDL_JoystickGetAxis
+ * \sa SDL_JoystickOpen
*/
extern DECLSPEC int SDLCALL SDL_JoystickNumAxes(SDL_Joystick *joystick);
/**
- * Get the number of trackballs on a joystick.
+ * Get the number of trackballs on a joystick.
+ *
+ * Joystick trackballs have only relative motion events associated with them
+ * and their state cannot be polled.
+ *
+ * Most joysticks do not have trackballs.
+ *
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \returns the number of trackballs on success or a negative error code on
+ * failure; call SDL_GetError() for more information.
*
- * Joystick trackballs have only relative motion events associated
- * with them and their state cannot be polled.
+ * \sa SDL_JoystickGetBall
*/
extern DECLSPEC int SDLCALL SDL_JoystickNumBalls(SDL_Joystick *joystick);
/**
- * Get the number of POV hats on a joystick.
+ * Get the number of POV hats on a joystick.
+ *
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \returns the number of POV hats on success or a negative error code on
+ * failure; call SDL_GetError() for more information.
+ *
+ * \sa SDL_JoystickGetHat
+ * \sa SDL_JoystickOpen
*/
extern DECLSPEC int SDLCALL SDL_JoystickNumHats(SDL_Joystick *joystick);
/**
- * Get the number of buttons on a joystick.
+ * Get the number of buttons on a joystick.
+ *
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \returns the number of buttons on success or a negative error code on
+ * failure; call SDL_GetError() for more information.
+ *
+ * \sa SDL_JoystickGetButton
+ * \sa SDL_JoystickOpen
*/
extern DECLSPEC int SDLCALL SDL_JoystickNumButtons(SDL_Joystick *joystick);
/**
- * Update the current state of the open joysticks.
+ * Update the current state of the open joysticks.
*
- * This is called automatically by the event loop if any joystick
- * events are enabled.
+ * This is called automatically by the event loop if any joystick events are
+ * enabled.
+ *
+ * \sa SDL_JoystickEventState
*/
extern DECLSPEC void SDLCALL SDL_JoystickUpdate(void);
/**
- * Enable/disable joystick event polling.
+ * Enable/disable joystick event polling.
+ *
+ * If joystick events are disabled, you must call SDL_JoystickUpdate()
+ * yourself and manually check the state of the joystick when you want
+ * joystick information.
+ *
+ * It is recommended that you leave joystick event handling enabled.
+ *
+ * **WARNING**: Calling this function may delete all events currently in SDL's
+ * event queue.
*
- * If joystick events are disabled, you must call SDL_JoystickUpdate()
- * yourself and check the state of the joystick when you want joystick
- * information.
+ * \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE`
+ * \returns 1 if enabled, 0 if disabled, or a negative error code on failure;
+ * call SDL_GetError() for more information.
*
- * The state can be one of ::SDL_QUERY, ::SDL_ENABLE or ::SDL_IGNORE.
+ * If `state` is `SDL_QUERY` then the current state is returned,
+ * otherwise the new processing state is returned.
+ *
+ * \sa SDL_GameControllerEventState
*/
extern DECLSPEC int SDLCALL SDL_JoystickEventState(int state);
#define SDL_JOYSTICK_AXIS_MAX 32767
#define SDL_JOYSTICK_AXIS_MIN -32768
/**
- * Get the current state of an axis control on a joystick.
+ * Get the current state of an axis control on a joystick.
+ *
+ * SDL makes no promises about what part of the joystick any given axis
+ * refers to. Your game should have some sort of configuration UI to let
+ * users specify what each axis should be bound to. Alternately, SDL's
+ * higher-level Game Controller API makes a great effort to apply order
+ * to this lower-level interface, so you know that a specific axis is the
+ * "left thumb stick," etc.
*
- * The state is a value ranging from -32768 to 32767.
+ * The value returned by SDL_JoystickGetAxis() is a signed integer (-32768 to
+ * 32767) representing the current position of the axis. It may be necessary
+ * to impose certain tolerances on these values to account for jitter.
*
- * The axis indices start at index 0.
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \param axis the axis to query; the axis indices start at index 0
+ * \returns a 16-bit signed integer representing the current position of the
+ * axis or 0 on failure; call SDL_GetError() for more information.
+ *
+ * \sa SDL_JoystickNumAxes
*/
extern DECLSPEC Sint16 SDLCALL SDL_JoystickGetAxis(SDL_Joystick *joystick,
int axis);
/**
- * Get the initial state of an axis control on a joystick.
+ * Get the initial state of an axis control on a joystick.
*
- * The state is a value ranging from -32768 to 32767.
+ * The state is a value ranging from -32768 to 32767.
*
- * The axis indices start at index 0.
+ * The axis indices start at index 0.
*
- * \return SDL_TRUE if this axis has any initial value, or SDL_FALSE if not.
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \param axis the axis to query; the axis indices start at index 0
+ * \param state Upon return, the initial value is supplied here.
+ * \return SDL_TRUE if this axis has any initial value, or SDL_FALSE if not.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAxisInitialState(SDL_Joystick *joystick,
int axis, Sint16 *state);
@@ -395,96 +661,153 @@ extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAxisInitialState(SDL_Joystick *j
/* @} */
/**
- * Get the current state of a POV hat on a joystick.
+ * Get the current state of a POV hat on a joystick.
+ *
+ * The returned value will be one of the following positions:
+ *
+ * - `SDL_HAT_CENTERED`
+ *
+ * - `SDL_HAT_UP`
+ *
+ * - `SDL_HAT_RIGHT`
+ *
+ * - `SDL_HAT_DOWN`
*
- * The hat indices start at index 0.
+ * - `SDL_HAT_LEFT`
*
- * \return The return value is one of the following positions:
- * - ::SDL_HAT_CENTERED
- * - ::SDL_HAT_UP
- * - ::SDL_HAT_RIGHT
- * - ::SDL_HAT_DOWN
- * - ::SDL_HAT_LEFT
- * - ::SDL_HAT_RIGHTUP
- * - ::SDL_HAT_RIGHTDOWN
- * - ::SDL_HAT_LEFTUP
- * - ::SDL_HAT_LEFTDOWN
+ * - `SDL_HAT_RIGHTUP`
+ *
+ * - `SDL_HAT_RIGHTDOWN`
+ *
+ * - `SDL_HAT_LEFTUP`
+ *
+ * - `SDL_HAT_LEFTDOWN`
+ *
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \param hat the hat index to get the state from; hat indices start at index
+ * 0
+ * \returns the current hat position.
+ *
+ * \sa SDL_JoystickNumHats
*/
extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetHat(SDL_Joystick *joystick,
int hat);
/**
- * Get the ball axis change since the last poll.
+ * Get the ball axis change since the last poll.
+ *
+ * Trackballs can only return relative motion since the last call to
+ * SDL_JoystickGetBall(), these motion deltas are placed into `dx` and
+ * `dy`.
*
- * \return 0, or -1 if you passed it invalid parameters.
+ * Most joysticks do not have trackballs.
*
- * The ball indices start at index 0.
+ * \param joystick the SDL_Joystick to query
+ * \param ball the ball index to query; ball indices start at index 0
+ * \param dx stores the difference in the x axis position since the last poll
+ * \param dy stores the difference in the y axis position since the last poll
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_JoystickNumBalls
*/
extern DECLSPEC int SDLCALL SDL_JoystickGetBall(SDL_Joystick *joystick,
int ball, int *dx, int *dy);
/**
- * Get the current state of a button on a joystick.
+ * Get the current state of a button on a joystick.
+ *
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \param button the button index to get the state from; indices start at
+ * index 0
+ * \returns 1 if the specified button is pressed, 0 otherwise.
*
- * The button indices start at index 0.
+ * \sa SDL_JoystickNumButtons
*/
extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetButton(SDL_Joystick *joystick,
int button);
/**
- * Start a rumble effect
- * Each call to this function cancels any previous rumble effect, and calling it with 0 intensity stops any rumbling.
+ * Start a rumble effect.
*
- * \param joystick The joystick to vibrate
- * \param low_frequency_rumble The intensity of the low frequency (left) rumble motor, from 0 to 0xFFFF
- * \param high_frequency_rumble The intensity of the high frequency (right) rumble motor, from 0 to 0xFFFF
- * \param duration_ms The duration of the rumble effect, in milliseconds
+ * Each call to this function cancels any previous rumble effect, and calling
+ * it with 0 intensity stops any rumbling.
*
- * \return 0, or -1 if rumble isn't supported on this joystick
+ * \param joystick The joystick to vibrate
+ * \param low_frequency_rumble The intensity of the low frequency (left)
+ * rumble motor, from 0 to 0xFFFF
+ * \param high_frequency_rumble The intensity of the high frequency (right)
+ * rumble motor, from 0 to 0xFFFF
+ * \param duration_ms The duration of the rumble effect, in milliseconds
+ *
+ * \returns 0, or -1 if rumble isn't supported on this joystick
*/
extern DECLSPEC int SDLCALL SDL_JoystickRumble(SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms);
/**
- * Start a rumble effect in the joystick's triggers
- * Each call to this function cancels any previous trigger rumble effect, and calling it with 0 intensity stops any rumbling.
+ * Start a rumble effect in the joystick's triggers
+ *
+ * Each call to this function cancels any previous trigger rumble effect,
+ * and calling it with 0 intensity stops any rumbling.
*
- * \param joystick The joystick to vibrate
- * \param left_rumble The intensity of the left trigger rumble motor, from 0 to 0xFFFF
- * \param right_rumble The intensity of the right trigger rumble motor, from 0 to 0xFFFF
- * \param duration_ms The duration of the rumble effect, in milliseconds
+ * Note that this function is for _trigger_ rumble; the first joystick to
+ * support this was the PlayStation 5's DualShock 5 controller. If you want
+ * the (more common) whole-controller rumble, use SDL_JoystickRumble() instead.
*
- * \return 0, or -1 if trigger rumble isn't supported on this joystick
+ * \param joystick The joystick to vibrate
+ * \param left_rumble The intensity of the left trigger rumble motor, from 0
+ * to 0xFFFF
+ * \param right_rumble The intensity of the right trigger rumble motor, from 0
+ * to 0xFFFF
+ * \param duration_ms The duration of the rumble effect, in milliseconds
+ *
+ * \returns 0, or -1 if trigger rumble isn't supported on this joystick
*/
extern DECLSPEC int SDLCALL SDL_JoystickRumbleTriggers(SDL_Joystick *joystick, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms);
/**
- * Return whether a joystick has an LED
+ * Query whether a joystick has an LED.
*
- * \param joystick The joystick to query
+ * An example of a joystick LED is the light on the back of a PlayStation 4's
+ * DualShock 4 controller.
*
- * \return SDL_TRUE, or SDL_FALSE if this joystick does not have a modifiable LED
+ * \param joystick The joystick to query
+ * \return SDL_TRUE if the joystick has a modifiable LED, SDL_FALSE otherwise.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_JoystickHasLED(SDL_Joystick *joystick);
/**
- * Update a joystick's LED color.
+ * Update a joystick's LED color.
+ *
+ * An example of a joystick LED is the light on the back of a PlayStation 4's
+ * DualShock 4 controller.
*
- * \param joystick The joystick to update
- * \param red The intensity of the red LED
- * \param green The intensity of the green LED
- * \param blue The intensity of the blue LED
+ * \param joystick The joystick to update
+ * \param red The intensity of the red LED
+ * \param green The intensity of the green LED
+ * \param blue The intensity of the blue LED
*
- * \return 0, or -1 if this joystick does not have a modifiable LED
+ * \returns 0 on success, -1 if this joystick does not have a modifiable LED
*/
extern DECLSPEC int SDLCALL SDL_JoystickSetLED(SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue);
/**
- * Close a joystick previously opened with SDL_JoystickOpen().
+ * Close a joystick previously opened with SDL_JoystickOpen().
+ *
+ * \param joystick The joystick device to close
+ *
+ * \sa SDL_JoystickOpen
*/
extern DECLSPEC void SDLCALL SDL_JoystickClose(SDL_Joystick *joystick);
/**
- * Return the battery level of this joystick
+ * Get the battery level of a joystick as SDL_JoystickPowerLevel.
+ *
+ * \param joystick the SDL_Joystick to query
+ * \returns the current battery level as SDL_JoystickPowerLevel on success or
+ * `SDL_JOYSTICK_POWER_UNKNOWN` if it is unknown
+ *
+ * \since This function is available since SDL 2.0.4.
*/
extern DECLSPEC SDL_JoystickPowerLevel SDLCALL SDL_JoystickCurrentPowerLevel(SDL_Joystick *joystick);
diff --git a/include/SDL_keyboard.h b/include/SDL_keyboard.h
index 9eaeb28..3b14acb 100644
--- a/include/SDL_keyboard.h
+++ b/include/SDL_keyboard.h
@@ -55,154 +55,231 @@ typedef struct SDL_Keysym
/* Function prototypes */
/**
- * \brief Get the window which currently has keyboard focus.
+ * Query the window which currently has keyboard focus.
+ *
+ * \returns the window with keyboard focus.
*/
extern DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void);
/**
- * \brief Get a snapshot of the current state of the keyboard.
+ * Get a snapshot of the current state of the keyboard.
+ *
+ * The pointer returned is a pointer to an internal SDL array. It will be
+ * valid for the whole lifetime of the application and should not be freed
+ * by the caller.
+ *
+ * A array element with a value of 1 means that the key is pressed and a value
+ * of 0 means that it is not. Indexes into this array are obtained by using
+ * SDL_Scancode values.
*
- * \param numkeys if non-NULL, receives the length of the returned array.
+ * Use SDL_PumpEvents() to update the state array.
*
- * \return An array of key states. Indexes into this array are obtained by using ::SDL_Scancode values.
+ * This function gives you the current state after all events have been
+ * processed, so if a key or button has been pressed and released before you
+ * process events, then the pressed state will never show up in the
+ * SDL_GetKeyboardState() calls.
*
- * \b Example:
- * \code
- * const Uint8 *state = SDL_GetKeyboardState(NULL);
- * if ( state[SDL_SCANCODE_RETURN] ) {
- * printf("<RETURN> is pressed.\n");
- * }
- * \endcode
+ * Note: This function doesn't take into account whether shift has been
+ * pressed or not.
+ *
+ * \param numkeys if non-NULL, receives the length of the returned array
+ * \returns a pointer to an array of key states.
+ *
+ * \sa SDL_PumpEvents
*/
extern DECLSPEC const Uint8 *SDLCALL SDL_GetKeyboardState(int *numkeys);
/**
- * \brief Get the current key modifier state for the keyboard.
+ * Get the current key modifier state for the keyboard.
+ *
+ * \returns an OR'd combination of the modifier keys for the keyboard. See
+ * SDL_Keymod for details.
+ *
+ * \sa SDL_GetKeyboardState
+ * \sa SDL_SetModState
*/
extern DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void);
/**
- * \brief Set the current key modifier state for the keyboard.
+ * Set the current key modifier state for the keyboard.
+ *
+ * The inverse of SDL_GetModState(), SDL_SetModState() allows you to impose
+ * modifier key states on your application. Simply pass your desired modifier
+ * states into `modstate`. This value may be a bitwise, OR'd combination of
+ * SDL_Keymod values.
+ *
+ * This does not change the keyboard state, only the key modifier flags that
+ * SDL reports.
*
- * \note This does not change the keyboard state, only the key modifier flags.
+ * \param modstate the desired SDL_Keymod for the keyboard
+ *
+ * \sa SDL_GetModState
*/
extern DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate);
/**
- * \brief Get the key code corresponding to the given scancode according
- * to the current keyboard layout.
+ * Get the key code corresponding to the given scancode
+ * according to the current keyboard layout.
+ *
+ * See SDL_Keycode for details.
*
- * See ::SDL_Keycode for details.
+ * \param scancode the desired SDL_Scancode to query
+ * \returns the SDL_Keycode that corresponds to the given SDL_Scancode.
*
- * \sa SDL_GetKeyName()
+ * \sa SDL_GetKeyName
+ * \sa SDL_GetScancodeFromKey
*/
extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode);
/**
- * \brief Get the scancode corresponding to the given key code according to the
- * current keyboard layout.
+ * Get the scancode corresponding to the given key code
+ * according to the current keyboard layout.
*
- * See ::SDL_Scancode for details.
+ * See SDL_Scancode for details.
*
- * \sa SDL_GetScancodeName()
+ * \param key the desired SDL_Keycode to query
+ * \returns the SDL_Scancode that corresponds to the given SDL_Keycode.
+ *
+ * \sa SDL_GetKeyFromScancode
+ * \sa SDL_GetScancodeName
*/
extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key);
/**
- * \brief Get a human-readable name for a scancode.
+ * Get a human-readable name for a scancode.
+ *
+ * See SDL_Scancode for details.
+ *
+ * **Warning**: The returned name is by design not stable across platforms,
+ * e.g. the name for `SDL_SCANCODE_LGUI` is "Left GUI" under Linux but "Left
+ * Windows" under Microsoft Windows, and some scancodes like
+ * `SDL_SCANCODE_NONUSBACKSLASH` don't have any name at all. There are even
+ * scancodes that share names, e.g. `SDL_SCANCODE_RETURN` and
+ * `SDL_SCANCODE_RETURN2` (both called "Return"). This function is therefore
+ * unsuitable for creating a stable cross-platform two-way mapping between
+ * strings and scancodes.
*
- * \return A pointer to the name for the scancode.
- * If the scancode doesn't have a name, this function returns
- * an empty string ("").
+ * \param scancode the desired SDL_Scancode to query
+ * \returns a pointer to the name for the scancode. If the scancode doesn't
+ * have a name this function returns an empty string ("").
*
- * \sa SDL_Scancode
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetScancodeFromKey
+ * \sa SDL_GetScancodeFromName
*/
extern DECLSPEC const char *SDLCALL SDL_GetScancodeName(SDL_Scancode scancode);
/**
- * \brief Get a scancode from a human-readable name
+ * Get a scancode from a human-readable name.
+ *
+ * \param name the human-readable scancode name
+ * \returns the SDL_Scancode, or `SDL_SCANCODE_UNKNOWN` if the name wasn't
+ * recognized; call SDL_GetError() for more information.
*
- * \return scancode, or SDL_SCANCODE_UNKNOWN if the name wasn't recognized
+ * \since This function is available since SDL 2.0.0.
*
- * \sa SDL_Scancode
+ * \sa SDL_GetKeyFromName
+ * \sa SDL_GetScancodeFromKey
+ * \sa SDL_GetScancodeName
*/
extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *name);
/**
- * \brief Get a human-readable name for a key.
+ * Get a human-readable name for a key.
+ *
+ * See SDL_Scancode and SDL_Keycode for details.
*
- * \return A pointer to a UTF-8 string that stays valid at least until the next
- * call to this function. If you need it around any longer, you must
- * copy it. If the key doesn't have a name, this function returns an
- * empty string ("").
+ * \param key the desired SDL_Keycode to query
+ * \returns a pointer to a UTF-8 string that stays valid at least until the
+ * next call to this function. If you need it around any longer, you
+ * must copy it. If the key doesn't have a name, this function
+ * returns an empty string ("").
*
- * \sa SDL_Keycode
+ * \sa SDL_GetKeyFromName
+ * \sa SDL_GetKeyFromScancode
+ * \sa SDL_GetScancodeFromKey
*/
extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDL_Keycode key);
/**
- * \brief Get a key code from a human-readable name
+ * Get a key code from a human-readable name.
*
- * \return key code, or SDLK_UNKNOWN if the name wasn't recognized
+ * \param name the human-readable key name
+ * \returns key code, or `SDLK_UNKNOWN` if the name wasn't recognized; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_Keycode
+ * \sa SDL_GetKeyFromScancode
+ * \sa SDL_GetKeyName
+ * \sa SDL_GetScancodeFromName
*/
extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name);
/**
- * \brief Start accepting Unicode text input events.
- * This function will show the on-screen keyboard if supported.
+ * Start accepting Unicode text input events.
*
- * \sa SDL_StopTextInput()
- * \sa SDL_SetTextInputRect()
- * \sa SDL_HasScreenKeyboardSupport()
+ * This function will start accepting Unicode text input events in the focused
+ * SDL window, and start emitting SDL_TextInputEvent (SDL_TEXTINPUT) and
+ * SDL_TextEditingEvent (SDL_TEXTEDITING) events. Please use this function
+ * in pair with SDL_StopTextInput().
+ *
+ * On some platforms using this function activates the screen keyboard.
+ *
+ * \sa SDL_SetTextInputRect
+ * \sa SDL_StopTextInput
*/
extern DECLSPEC void SDLCALL SDL_StartTextInput(void);
/**
- * \brief Return whether or not Unicode text input events are enabled.
+ * Check whether or not Unicode text input events are enabled.
+ *
+ * \returns SDL_TRUE if text input events are enabled else SDL_FALSE.
*
- * \sa SDL_StartTextInput()
- * \sa SDL_StopTextInput()
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_StartTextInput
*/
extern DECLSPEC SDL_bool SDLCALL SDL_IsTextInputActive(void);
/**
- * \brief Stop receiving any text input events.
- * This function will hide the on-screen keyboard if supported.
+ * Stop receiving any text input events.
*
- * \sa SDL_StartTextInput()
- * \sa SDL_HasScreenKeyboardSupport()
+ * \sa SDL_StartTextInput
*/
extern DECLSPEC void SDLCALL SDL_StopTextInput(void);
/**
- * \brief Set the rectangle used to type Unicode text inputs.
- * This is used as a hint for IME and on-screen keyboard placement.
+ * Set the rectangle used to type Unicode text inputs.
+ *
+ * \param rect the SDL_Rect structure representing the rectangle to receive
+ * text (ignored if NULL)
*
- * \sa SDL_StartTextInput()
+ * \sa SDL_StartTextInput
*/
extern DECLSPEC void SDLCALL SDL_SetTextInputRect(SDL_Rect *rect);
/**
- * \brief Returns whether the platform has some screen keyboard support.
+ * Check whether the platform has screen keyboard support.
*
- * \return SDL_TRUE if some keyboard support is available else SDL_FALSE.
+ * \returns SDL_TRUE if the platform has some screen keyboard support or
+ * SDL_FALSE if not.
*
- * \note Not all screen keyboard functions are supported on all platforms.
+ * \since This function is available since SDL 2.0.0.
*
- * \sa SDL_IsScreenKeyboardShown()
+ * \sa SDL_StartTextInput
+ * \sa SDL_IsScreenKeyboardShown
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasScreenKeyboardSupport(void);
/**
- * \brief Returns whether the screen keyboard is shown for given window.
+ * Check whether the screen keyboard is shown for given window.
*
- * \param window The window for which screen keyboard should be queried.
+ * \param window the window for which screen keyboard should be queried
+ * \returns SDL_TRUE if screen keyboard is shown or SDL_FALSE if not.
*
- * \return SDL_TRUE if screen keyboard is shown else SDL_FALSE.
+ * \since This function is available since SDL 2.0.0.
*
- * \sa SDL_HasScreenKeyboardSupport()
+ * \sa SDL_HasScreenKeyboardSupport
*/
extern DECLSPEC SDL_bool SDLCALL SDL_IsScreenKeyboardShown(SDL_Window *window);
diff --git a/include/SDL_loadso.h b/include/SDL_loadso.h
index 80379bc..e6a33a0 100644
--- a/include/SDL_loadso.h
+++ b/include/SDL_loadso.h
@@ -51,22 +51,50 @@ extern "C" {
#endif
/**
- * This function dynamically loads a shared object and returns a pointer
- * to the object handle (or NULL if there was an error).
- * The 'sofile' parameter is a system dependent name of the object file.
+ * Dynamically load a shared object.
+ *
+ * \param sofile a system-dependent name of the object file
+ * \returns an opaque pointer to the object handle or NULL if there was an
+ * error; call SDL_GetError() for more information.
+ *
+ * \sa SDL_LoadFunction
+ * \sa SDL_UnloadObject
*/
extern DECLSPEC void *SDLCALL SDL_LoadObject(const char *sofile);
/**
- * Given an object handle, this function looks up the address of the
- * named function in the shared object and returns it. This address
- * is no longer valid after calling SDL_UnloadObject().
+ * Look up the address of the named function in a shared object.
+ *
+ * This function pointer is no longer valid after calling SDL_UnloadObject().
+ *
+ * This function can only look up C function names. Other languages may have
+ * name mangling and intrinsic language support that varies from compiler to
+ * compiler.
+ *
+ * Make sure you declare your function pointers with the same calling
+ * convention as the actual library function. Your code will crash
+ * mysteriously if you do not do this.
+ *
+ * If the requested function doesn't exist, NULL is returned.
+ *
+ * \param handle a valid shared object handle returned by SDL_LoadObject()
+ * \param name the name of the function to look up
+ * \returns a pointer to the function or NULL if there was an error; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_LoadObject
+ * \sa SDL_UnloadObject
*/
extern DECLSPEC void *SDLCALL SDL_LoadFunction(void *handle,
const char *name);
/**
- * Unload a shared object from memory.
+ * Unload a shared object from memory.
+ *
+ * \param handle a valid shared object handle returned by SDL_LoadObject()
+ *
+ * \sa SDL_LoadFunction
+ * \sa SDL_LoadObject
*/
extern DECLSPEC void SDLCALL SDL_UnloadObject(void *handle);
diff --git a/include/SDL_log.h b/include/SDL_log.h
index f038e20..19b437a 100644
--- a/include/SDL_log.h
+++ b/include/SDL_log.h
@@ -112,90 +112,254 @@ typedef enum
/**
- * \brief Set the priority of all log categories
+ * Set the priority of all log categories.
+ *
+ * \param priority the SDL_LogPriority to assign
+ *
+ * \sa SDL_LogSetPriority
*/
extern DECLSPEC void SDLCALL SDL_LogSetAllPriority(SDL_LogPriority priority);
/**
- * \brief Set the priority of a particular log category
+ * Set the priority of a particular log category.
+ *
+ * \param category the category to assign a priority to
+ * \param priority the SDL_LogPriority to assign
+ *
+ * \sa SDL_LogGetPriority
+ * \sa SDL_LogSetAllPriority
*/
extern DECLSPEC void SDLCALL SDL_LogSetPriority(int category,
SDL_LogPriority priority);
/**
- * \brief Get the priority of a particular log category
+ * Get the priority of a particular log category.
+ *
+ * \param category the category to query
+ * \returns the SDL_LogPriority for the requested category
+ *
+ * \sa SDL_LogSetPriority
*/
extern DECLSPEC SDL_LogPriority SDLCALL SDL_LogGetPriority(int category);
/**
- * \brief Reset all priorities to default.
+ * Reset all priorities to default.
*
- * \note This is called in SDL_Quit().
+ * This is called by SDL_Quit().
+ *
+ * \sa SDL_LogSetAllPriority
+ * \sa SDL_LogSetPriority
*/
extern DECLSPEC void SDLCALL SDL_LogResetPriorities(void);
/**
- * \brief Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO
+ * Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO.
+ *
+= * \param fmt a printf() style message format string
+ * \param ... additional parameters matching % tokens in the `fmt` string,
+ * if any
+ *
+ * \sa SDL_LogCritical
+ * \sa SDL_LogDebug
+ * \sa SDL_LogError
+ * \sa SDL_LogInfo
+ * \sa SDL_LogMessage
+ * \sa SDL_LogMessageV
+ * \sa SDL_LogVerbose
+ * \sa SDL_LogWarn
*/
extern DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1);
/**
- * \brief Log a message with SDL_LOG_PRIORITY_VERBOSE
+ * Log a message with SDL_LOG_PRIORITY_VERBOSE.
+ *
+ * \param category the category of the message
+ * \param fmt a printf() style message format string
+ * \param ... additional parameters matching % tokens in the **fmt** string,
+ * if any
+ *
+ * \sa SDL_Log
+ * \sa SDL_LogCritical
+ * \sa SDL_LogDebug
+ * \sa SDL_LogError
+ * \sa SDL_LogInfo
+ * \sa SDL_LogMessage
+ * \sa SDL_LogMessageV
+ * \sa SDL_LogWarn
*/
extern DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
/**
- * \brief Log a message with SDL_LOG_PRIORITY_DEBUG
+ * Log a message with SDL_LOG_PRIORITY_DEBUG.
+ *
+ * \param category the category of the message
+ * \param fmt a printf() style message format string
+ * \param ... additional parameters matching % tokens in the **fmt** string,
+ * if any
+ *
+ * \sa SDL_Log
+ * \sa SDL_LogCritical
+ * \sa SDL_LogError
+ * \sa SDL_LogInfo
+ * \sa SDL_LogMessage
+ * \sa SDL_LogMessageV
+ * \sa SDL_LogVerbose
+ * \sa SDL_LogWarn
*/
extern DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
/**
- * \brief Log a message with SDL_LOG_PRIORITY_INFO
+ * Log a message with SDL_LOG_PRIORITY_INFO.
+ *
+ * \param category the category of the message
+ * \param fmt a printf() style message format string
+ * \param ... additional parameters matching % tokens in the **fmt** string,
+ * if any
+ *
+ * \sa SDL_Log
+ * \sa SDL_LogCritical
+ * \sa SDL_LogDebug
+ * \sa SDL_LogError
+ * \sa SDL_LogMessage
+ * \sa SDL_LogMessageV
+ * \sa SDL_LogVerbose
+ * \sa SDL_LogWarn
*/
extern DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
/**
- * \brief Log a message with SDL_LOG_PRIORITY_WARN
+ * Log a message with SDL_LOG_PRIORITY_WARN.
+ *
+ * \param category the category of the message
+ * \param fmt a printf() style message format string
+ * \param ... additional parameters matching % tokens in the **fmt** string,
+ * if any
+ *
+ * \sa SDL_Log
+ * \sa SDL_LogCritical
+ * \sa SDL_LogDebug
+ * \sa SDL_LogError
+ * \sa SDL_LogInfo
+ * \sa SDL_LogMessage
+ * \sa SDL_LogMessageV
+ * \sa SDL_LogVerbose
*/
extern DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
/**
- * \brief Log a message with SDL_LOG_PRIORITY_ERROR
+ * Log a message with SDL_LOG_PRIORITY_ERROR.
+ *
+ * \param category the category of the message
+ * \param fmt a printf() style message format string
+ * \param ... additional parameters matching % tokens in the **fmt** string,
+ * if any
+ *
+ * \sa SDL_Log
+ * \sa SDL_LogCritical
+ * \sa SDL_LogDebug
+ * \sa SDL_LogInfo
+ * \sa SDL_LogMessage
+ * \sa SDL_LogMessageV
+ * \sa SDL_LogVerbose
+ * \sa SDL_LogWarn
*/
extern DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
/**
- * \brief Log a message with SDL_LOG_PRIORITY_CRITICAL
+ * Log a message with SDL_LOG_PRIORITY_CRITICAL.
+ *
+ * \param category the category of the message
+ * \param fmt a printf() style message format string
+ * \param ... additional parameters matching % tokens in the **fmt** string,
+ * if any
+ *
+ * \sa SDL_Log
+ * \sa SDL_LogDebug
+ * \sa SDL_LogError
+ * \sa SDL_LogInfo
+ * \sa SDL_LogMessage
+ * \sa SDL_LogMessageV
+ * \sa SDL_LogVerbose
+ * \sa SDL_LogWarn
*/
extern DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
/**
- * \brief Log a message with the specified category and priority.
+ * Log a message with the specified category and priority.
+ *
+ * \param category the category of the message
+ * \param priority the priority of the message
+ * \param fmt a printf() style message format string
+ * \param ... additional parameters matching % tokens in the **fmt** string,
+ * if any
+ *
+ * \sa SDL_Log
+ * \sa SDL_LogCritical
+ * \sa SDL_LogDebug
+ * \sa SDL_LogError
+ * \sa SDL_LogInfo
+ * \sa SDL_LogMessageV
+ * \sa SDL_LogVerbose
+ * \sa SDL_LogWarn
*/
extern DECLSPEC void SDLCALL SDL_LogMessage(int category,
SDL_LogPriority priority,
SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(3);
/**
- * \brief Log a message with the specified category and priority.
+ * Log a message with the specified category and priority.
+ *
+ * \param category the category of the message
+ * \param priority the priority of the message
+ * \param fmt a printf() style message format string
+ * \param ap a variable argument list
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_Log
+ * \sa SDL_LogCritical
+ * \sa SDL_LogDebug
+ * \sa SDL_LogError
+ * \sa SDL_LogInfo
+ * \sa SDL_LogMessage
+ * \sa SDL_LogVerbose
+ * \sa SDL_LogWarn
*/
extern DECLSPEC void SDLCALL SDL_LogMessageV(int category,
SDL_LogPriority priority,
const char *fmt, va_list ap);
/**
- * \brief The prototype for the log output function
+ * The prototype for the log output callback function.
+ *
+ * This function is called by SDL when there is new text to be logged.
+ *
+ * \param userdata what was passed as `userdata` to SDL_LogSetOutputFunction()
+ * \param category the category of the message
+ * \param priority the priority of the message
+ * \param message the message being output
*/
typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_LogPriority priority, const char *message);
/**
- * \brief Get the current log output function.
+ * Get the current log output function.
+ *
+ * \param callback an SDL_LogOutputFunction filled in with the current log
+ * callback
+ * \param userdata a pointer filled in with the pointer that is passed to
+ * `callback`
+ *
+ * \sa SDL_LogSetOutputFunction
*/
extern DECLSPEC void SDLCALL SDL_LogGetOutputFunction(SDL_LogOutputFunction *callback, void **userdata);
/**
- * \brief This function allows you to replace the default log output
- * function with one of your own.
+ * Replace the default log output function with one of your own.
+ *
+ * \param callback an SDL_LogOutputFunction to call instead of the default
+ * \param userdata a pointer that is passed to `callback`
+ *
+ * \sa SDL_LogGetOutputFunction
*/
extern DECLSPEC void SDLCALL SDL_LogSetOutputFunction(SDL_LogOutputFunction callback, void *userdata);
diff --git a/include/SDL_main.h b/include/SDL_main.h
index 2d7c907..0209451 100644
--- a/include/SDL_main.h
+++ b/include/SDL_main.h
@@ -122,11 +122,14 @@ extern SDLMAIN_DECLSPEC int SDL_main(int argc, char *argv[]);
/**
- * This is called by the real SDL main function to let the rest of the
- * library know that initialization was done properly.
+ * Circumvent failure of SDL_Init() when not using SDL_main() as an entry point.
*
- * Calling this yourself without knowing what you're doing can cause
- * crashes and hard to diagnose problems with your application.
+ * This function is defined in SDL_main.h, along with the preprocessor rule to
+ * redefine main() as SDL_main(). Thus to ensure that your main() function
+ * will not be changed it is necessary to define SDL_MAIN_HANDLED before
+ * including SDL.h.
+ *
+ * \sa SDL_Init
*/
extern DECLSPEC void SDLCALL SDL_SetMainReady(void);
@@ -144,12 +147,14 @@ extern DECLSPEC void SDLCALL SDL_UnregisterApp(void);
#ifdef __WINRT__
/**
- * \brief Initializes and launches an SDL/WinRT application.
+ * Initialize and launch an SDL/WinRT application.
+ *
+ * \param mainFunction the SDL app's C-style main(), an SDL_main_func
+ * \param reserved reserved for future use; should be NULL
+ * \returns 0 on success or -1 on failure; call SDL_GetError() to retrieve
+ * more information on the failure.
*
- * \param mainFunction The SDL app's C-style main().
- * \param reserved Reserved for future use; should be NULL
- * \return 0 on success, -1 on failure. On failure, use SDL_GetError to retrieve more
- * information on the failure.
+ * \since This function is available since SDL 2.0.3.
*/
extern DECLSPEC int SDLCALL SDL_WinRTRunApp(SDL_main_func mainFunction, void * reserved);
@@ -158,12 +163,12 @@ extern DECLSPEC int SDLCALL SDL_WinRTRunApp(SDL_main_func mainFunction, void * r
#if defined(__IPHONEOS__)
/**
- * \brief Initializes and launches an SDL application.
+ * Initializes and launches an SDL application.
*
- * \param argc The argc parameter from the application's main() function
- * \param argv The argv parameter from the application's main() function
- * \param mainFunction The SDL app's C-style main().
- * \return the return value from mainFunction
+ * \param argc The argc parameter from the application's main() function
+ * \param argv The argv parameter from the application's main() function
+ * \param mainFunction The SDL app's C-style main(), an SDL_main_func
+ * \return the return value from mainFunction
*/
extern DECLSPEC int SDLCALL SDL_UIKitRunApp(int argc, char *argv[], SDL_main_func mainFunction);
diff --git a/include/SDL_messagebox.h b/include/SDL_messagebox.h
index 8caecc5..02f5469 100644
--- a/include/SDL_messagebox.h
+++ b/include/SDL_messagebox.h
@@ -32,7 +32,7 @@ extern "C" {
#endif
/**
- * \brief SDL_MessageBox flags. If supported will display warning icon, etc.
+ * SDL_MessageBox flags. If supported will display warning icon, etc.
*/
typedef enum
{
@@ -44,7 +44,7 @@ typedef enum
} SDL_MessageBoxFlags;
/**
- * \brief Flags for SDL_MessageBoxButtonData.
+ * Flags for SDL_MessageBoxButtonData.
*/
typedef enum
{
@@ -53,7 +53,7 @@ typedef enum
} SDL_MessageBoxButtonFlags;
/**
- * \brief Individual button data.
+ * Individual button data.
*/
typedef struct
{
@@ -63,7 +63,7 @@ typedef struct
} SDL_MessageBoxButtonData;
/**
- * \brief RGB value used in a message box color scheme
+ * RGB value used in a message box color scheme
*/
typedef struct
{
@@ -81,7 +81,7 @@ typedef enum
} SDL_MessageBoxColorType;
/**
- * \brief A set of colors to use for message box dialogs
+ * A set of colors to use for message box dialogs
*/
typedef struct
{
@@ -89,7 +89,7 @@ typedef struct
} SDL_MessageBoxColorScheme;
/**
- * \brief MessageBox structure containing title, text, window, etc.
+ * MessageBox structure containing title, text, window, etc.
*/
typedef struct
{
@@ -105,32 +105,79 @@ typedef struct
} SDL_MessageBoxData;
/**
- * \brief Create a modal message box.
+ * Create a modal message box.
*
- * \param messageboxdata The SDL_MessageBoxData structure with title, text, etc.
- * \param buttonid The pointer to which user id of hit button should be copied.
+ * If your needs aren't complex, it might be easier to use
+ * SDL_ShowSimpleMessageBox.
*
- * \return -1 on error, otherwise 0 and buttonid contains user id of button
- * hit or -1 if dialog was closed.
+ * This function should be called on the thread that created the parent
+ * window, or on the main thread if the messagebox has no parent. It will
+ * block execution of that thread until the user clicks a button or closes the
+ * messagebox.
*
- * \note This function should be called on the thread that created the parent
- * window, or on the main thread if the messagebox has no parent. It will
- * block execution of that thread until the user clicks a button or
- * closes the messagebox.
+ * This function may be called at any time, even before SDL_Init(). This makes
+ * it useful for reporting errors like a failure to create a renderer or
+ * OpenGL context.
+ *
+ * On X11, SDL rolls its own dialog box with X11 primitives instead of a
+ * formal toolkit like GTK+ or Qt.
+ *
+ * Note that if SDL_Init() would fail because there isn't any available video
+ * target, this function is likely to fail for the same reasons. If this is a
+ * concern, check the return value from this function and fall back to writing
+ * to stderr if you can.
+ *
+ * \param messageboxdata the SDL_MessageBoxData structure with title, text and
+ * other options
+ * \param buttonid the pointer to which user id of hit button should be copied
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_ShowSimpleMessageBox
*/
extern DECLSPEC int SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *messageboxdata, int *buttonid);
/**
- * \brief Create a simple modal message box
+ * Display a simple modal message box.
+ *
+ * If your needs aren't complex, this function is preferred over
+ * SDL_ShowMessageBox.
+ *
+ * `flags` may be any of the following:
+ *
+ * - `SDL_MESSAGEBOX_ERROR`: error dialog
+ *
+ * - `SDL_MESSAGEBOX_WARNING`: warning dialog
+ *
+ * - `SDL_MESSAGEBOX_INFORMATION`: informational dialog
+ *
+ * This function should be called on the thread that created the parent
+ * window, or on the main thread if the messagebox has no parent. It will
+ * block execution of that thread until the user clicks a button or closes the
+ * messagebox.
+ *
+ * This function may be called at any time, even before SDL_Init(). This makes
+ * it useful for reporting errors like a failure to create a renderer or
+ * OpenGL context.
+ *
+ * On X11, SDL rolls its own dialog box with X11 primitives instead of a
+ * formal toolkit like GTK+ or Qt.
*
- * \param flags ::SDL_MessageBoxFlags
- * \param title UTF-8 title text
- * \param message UTF-8 message text
- * \param window The parent window, or NULL for no parent
+ * Note that if SDL_Init() would fail because there isn't any available video
+ * target, this function is likely to fail for the same reasons. If this is a
+ * concern, check the return value from this function and fall back to writing
+ * to stderr if you can.
*
- * \return 0 on success, -1 on error
+ * \param flags an SDL_MessageBoxFlags value
+ * \param title UTF-8 title text
+ * \param message UTF-8 message text
+ * \param window the parent window, or NULL for no parent
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_ShowMessageBox
+ * \sa SDL_ShowMessageBox
*/
extern DECLSPEC int SDLCALL SDL_ShowSimpleMessageBox(Uint32 flags, const char *title, const char *message, SDL_Window *window);
diff --git a/include/SDL_misc.h b/include/SDL_misc.h
index 5eac321..7cd4d57 100644
--- a/include/SDL_misc.h
+++ b/include/SDL_misc.h
@@ -38,29 +38,33 @@ extern "C" {
#endif
/**
- * \brief Open an URL / URI in the browser or other
+ * Open a URL/URI in the browser or other appropriate external application.
*
* Open a URL in a separate, system-provided application. How this works will
- * vary wildly depending on the platform. This will likely launch what
- * makes sense to handle a specific URL's protocol (a web browser for http://,
- * etc), but it might also be able to launch file managers for directories
- * and other things.
+ * vary wildly depending on the platform. This will likely launch what makes
+ * sense to handle a specific URL's protocol (a web browser for `http://`,
+ * etc), but it might also be able to launch file managers for directories and
+ * other things.
*
* What happens when you open a URL varies wildly as well: your game window
- * may lose focus (and may or may not lose focus if your game was fullscreen
- * or grabbing input at the time). On mobile devices, your app will likely
- * move to the background or your process might be paused. Any given platform
- * may or may not handle a given URL.
+ * may lose focus (and may or may not lose focus if your game was fullscreen
+ * or grabbing input at the time). On mobile devices, your app will likely
+ * move to the background or your process might be paused. Any given platform
+ * may or may not handle a given URL.
*
* If this is unimplemented (or simply unavailable) for a platform, this will
- * fail with an error. A successful result does not mean the URL loaded, just
- * that we launched something to handle it (or at least believe we did).
+ * fail with an error. A successful result does not mean the URL loaded, just
+ * that we launched _something_ to handle it (or at least believe we did).
*
* All this to say: this function can be useful, but you should definitely
- * test it on every platform you target.
+ * test it on every platform you target.
*
- * \param url A valid URL to open.
- * \return 0 on success, or -1 on error.
+ * \param url A valid URL/URI to open. Use `file:///full/path/to/file` for
+ * local files, if supported.
+ * \returns 0 on success, or -1 on error; call SDL_GetError() for more
+ * information.
+ *
+ * \since This function is available in SDL 2.0.14 and newer
*/
extern DECLSPEC int SDLCALL SDL_OpenURL(const char *url);
diff --git a/include/SDL_mouse.h b/include/SDL_mouse.h
index 3230307..3bfc4d1 100644
--- a/include/SDL_mouse.h
+++ b/include/SDL_mouse.h
@@ -72,150 +72,220 @@ typedef enum
/* Function prototypes */
/**
- * \brief Get the window which currently has mouse focus.
+ * Get the window which currently has mouse focus.
+ *
+ * \returns the window with mouse focus.
*/
extern DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void);
/**
- * \brief Retrieve the current state of the mouse.
+ * Retrieve the current state of the mouse.
+ *
+ * The current button state is returned as a button bitmask, which can be
+ * tested using the `SDL_BUTTON(X)` macros (where `X` is generally 1 for the
+ * left, 2 for middle, 3 for the right button), and `x` and `y` are set to the
+ * mouse cursor position relative to the focus window. You can pass NULL for
+ * either `x` or `y`.
+ *
+ * \param x the x coordinate of the mouse cursor position relative to the
+ * focus window
+ * \param y the y coordinate of the mouse cursor position relative to the
+ * focus window
+ * \returns a 32-bit button bitmask of the current button state.
*
- * The current button state is returned as a button bitmask, which can
- * be tested using the SDL_BUTTON(X) macros, and x and y are set to the
- * mouse cursor position relative to the focus window for the currently
- * selected mouse. You can pass NULL for either x or y.
+ * \sa SDL_GetGlobalMouseState
+ * \sa SDL_GetRelativeMouseState
+ * \sa SDL_PumpEvents
*/
extern DECLSPEC Uint32 SDLCALL SDL_GetMouseState(int *x, int *y);
/**
- * \brief Get the current state of the mouse, in relation to the desktop
- *
- * This works just like SDL_GetMouseState(), but the coordinates will be
- * reported relative to the top-left of the desktop. This can be useful if
- * you need to track the mouse outside of a specific window and
- * SDL_CaptureMouse() doesn't fit your needs. For example, it could be
- * useful if you need to track the mouse while dragging a window, where
- * coordinates relative to a window might not be in sync at all times.
- *
- * \note SDL_GetMouseState() returns the mouse position as SDL understands
- * it from the last pump of the event queue. This function, however,
- * queries the OS for the current mouse position, and as such, might
- * be a slightly less efficient function. Unless you know what you're
- * doing and have a good reason to use this function, you probably want
- * SDL_GetMouseState() instead.
- *
- * \param x Returns the current X coord, relative to the desktop. Can be NULL.
- * \param y Returns the current Y coord, relative to the desktop. Can be NULL.
- * \return The current button state as a bitmask, which can be tested using the SDL_BUTTON(X) macros.
- *
- * \sa SDL_GetMouseState
+ * Get the current state of the mouse in relation to the desktop.
+ *
+ * This works similarly to SDL_GetMouseState(), but the coordinates will be
+ * reported relative to the top-left of the desktop. This can be useful if you
+ * need to track the mouse outside of a specific window and SDL_CaptureMouse()
+ * doesn't fit your needs. For example, it could be useful if you need to
+ * track the mouse while dragging a window, where coordinates relative to a
+ * window might not be in sync at all times.
+ *
+ * Note: SDL_GetMouseState() returns the mouse position as SDL understands it
+ * from the last pump of the event queue. This function, however, queries
+ * the OS for the current mouse position, and as such, might be a slightly
+ * less efficient function. Unless you know what you're doing and have a good
+ * reason to use this function, you probably want SDL_GetMouseState() instead.
+ *
+ * \param x filled in with the current X coord relative to the desktop; can be
+ * NULL
+ * \param y filled in with the current Y coord relative to the desktop; can be
+ * NULL
+ * \returns the current button state as a bitmask which can be tested using
+ * the SDL_BUTTON(X) macros.
+ *
+ * \since This function is available since SDL 2.0.4.
+ *
+ * \sa SDL_CaptureMouse
*/
extern DECLSPEC Uint32 SDLCALL SDL_GetGlobalMouseState(int *x, int *y);
/**
- * \brief Retrieve the relative state of the mouse.
+ * Retrieve the relative state of the mouse.
+ *
+ * The current button state is returned as a button bitmask, which can be
+ * tested using the `SDL_BUTTON(X)` macros (where `X` is generally 1 for the
+ * left, 2 for middle, 3 for the right button), and `x` and `y` are set to the
+ * mouse deltas since the last call to SDL_GetRelativeMouseState() or since
+ * event initialization. You can pass NULL for either `x` or `y`.
*
- * The current button state is returned as a button bitmask, which can
- * be tested using the SDL_BUTTON(X) macros, and x and y are set to the
- * mouse deltas since the last call to SDL_GetRelativeMouseState().
+ * \param x a pointer filled with the last recorded x coordinate of the mouse
+ * \param y a pointer filled with the last recorded y coordinate of the mouse
+ * \returns a 32-bit button bitmask of the relative button state.
+ *
+ * \sa SDL_GetMouseState
*/
extern DECLSPEC Uint32 SDLCALL SDL_GetRelativeMouseState(int *x, int *y);
/**
- * \brief Moves the mouse to the given position within the window.
+ * Move the mouse cursor to the given position within the window.
+ *
+ * This function generates a mouse motion event.
*
- * \param window The window to move the mouse into, or NULL for the current mouse focus
- * \param x The x coordinate within the window
- * \param y The y coordinate within the window
+ * \param window the window to move the mouse into, or NULL for the current
+ * mouse focus
+ * \param x the x coordinate within the window
+ * \param y the y coordinate within the window
*
- * \note This function generates a mouse motion event
+ * \sa SDL_WarpMouseGlobal
*/
extern DECLSPEC void SDLCALL SDL_WarpMouseInWindow(SDL_Window * window,
int x, int y);
/**
- * \brief Moves the mouse to the given position in global screen space.
+ * Move the mouse to the given position in global screen space.
+ *
+ * This function generates a mouse motion event.
*
- * \param x The x coordinate
- * \param y The y coordinate
- * \return 0 on success, -1 on error (usually: unsupported by a platform).
+ * A failure of this function usually means that it is unsupported by a
+ * platform.
*
- * \note This function generates a mouse motion event
+ * \param x the x coordinate
+ * \param y the y coordinate
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.4.
+ *
+ * \sa SDL_WarpMouseInWindow
*/
extern DECLSPEC int SDLCALL SDL_WarpMouseGlobal(int x, int y);
/**
- * \brief Set relative mouse mode.
+ * Set relative mouse mode.
*
- * \param enabled Whether or not to enable relative mode
+ * While the mouse is in relative mode, the cursor is hidden, and the driver
+ * will try to report continuous motion in the current window. Only relative
+ * motion events will be delivered, the mouse position will not change.
*
- * \return 0 on success, or -1 if relative mode is not supported.
+ * This function will flush any pending mouse motion.
*
- * While the mouse is in relative mode, the cursor is hidden, and the
- * driver will try to report continuous motion in the current window.
- * Only relative motion events will be delivered, the mouse position
- * will not change.
+ * \param enabled SDL_TRUE to enable relative mode, SDL_FALSE to disable.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \note This function will flush any pending mouse motion.
+ * If relative mode is not supported, this returns -1.
*
- * \sa SDL_GetRelativeMouseMode()
+ * \sa SDL_GetRelativeMouseMode
*/
extern DECLSPEC int SDLCALL SDL_SetRelativeMouseMode(SDL_bool enabled);
/**
- * \brief Capture the mouse, to track input outside an SDL window.
+ * Capture the mouse and to track input outside an SDL window.
+ *
+ * Capturing enables your app to obtain mouse events globally, instead of just
+ * within your window. Not all video targets support this function. When
+ * capturing is enabled, the current window will get all mouse events, but
+ * unlike relative mode, no change is made to the cursor and it is not
+ * restrained to your window.
*
- * \param enabled Whether or not to enable capturing
+ * This function may also deny mouse input to other windows--both those in
+ * your application and others on the system--so you should use this function
+ * sparingly, and in small bursts. For example, you might want to track the
+ * mouse while the user is dragging something, until the user releases a mouse
+ * button. It is not recommended that you capture the mouse for long periods
+ * of time, such as the entire time your app is running. For that, you should
+ * probably use SDL_SetRelativeMouseMode() or SDL_SetWindowGrab(), depending
+ * on your goals.
*
- * Capturing enables your app to obtain mouse events globally, instead of
- * just within your window. Not all video targets support this function.
- * When capturing is enabled, the current window will get all mouse events,
- * but unlike relative mode, no change is made to the cursor and it is
- * not restrained to your window.
+ * While captured, mouse events still report coordinates relative to the
+ * current (foreground) window, but those coordinates may be outside the
+ * bounds of the window (including negative values). Capturing is only allowed
+ * for the foreground window. If the window loses focus while capturing, the
+ * capture will be disabled automatically.
*
- * This function may also deny mouse input to other windows--both those in
- * your application and others on the system--so you should use this
- * function sparingly, and in small bursts. For example, you might want to
- * track the mouse while the user is dragging something, until the user
- * releases a mouse button. It is not recommended that you capture the mouse
- * for long periods of time, such as the entire time your app is running.
+ * While capturing is enabled, the current window will have the
+ * `SDL_WINDOW_MOUSE_CAPTURE` flag set.
*
- * While captured, mouse events still report coordinates relative to the
- * current (foreground) window, but those coordinates may be outside the
- * bounds of the window (including negative values). Capturing is only
- * allowed for the foreground window. If the window loses focus while
- * capturing, the capture will be disabled automatically.
+ * \param enabled SDL_TRUE to enable capturing, SDL_FALSE to disable.
+ * \returns 0 on success or -1 if not supported; call SDL_GetError() for more
+ * information.
*
- * While capturing is enabled, the current window will have the
- * SDL_WINDOW_MOUSE_CAPTURE flag set.
+ * \since This function is available since SDL 2.0.4.
*
- * \return 0 on success, or -1 if not supported.
+ * \sa SDL_GetGlobalMouseState
*/
extern DECLSPEC int SDLCALL SDL_CaptureMouse(SDL_bool enabled);
/**
- * \brief Query whether relative mouse mode is enabled.
+ * Query whether relative mouse mode is enabled.
*
- * \sa SDL_SetRelativeMouseMode()
+ * \returns SDL_TRUE if relative mode is enabled or SDL_FALSE otherwise.
+ *
+ * \sa SDL_SetRelativeMouseMode
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GetRelativeMouseMode(void);
/**
- * \brief Create a cursor, using the specified bitmap data and
- * mask (in MSB format).
- *
- * The cursor width must be a multiple of 8 bits.
- *
- * The cursor is created in black and white according to the following:
- * <table>
- * <tr><td> data </td><td> mask </td><td> resulting pixel on screen </td></tr>
- * <tr><td> 0 </td><td> 1 </td><td> White </td></tr>
- * <tr><td> 1 </td><td> 1 </td><td> Black </td></tr>
- * <tr><td> 0 </td><td> 0 </td><td> Transparent </td></tr>
- * <tr><td> 1 </td><td> 0 </td><td> Inverted color if possible, black
- * if not. </td></tr>
- * </table>
- *
- * \sa SDL_FreeCursor()
+ * Create a cursor using the specified bitmap data and
+ * mask (in MSB format).
+ *
+ * `mask` has to be in MSB (Most Significant Bit) format.
+ *
+ * The cursor width (`w`) must be a multiple of 8 bits.
+ *
+ * The cursor is created in black and white according to the following:
+ *
+ * - data=0, mask=1: white
+ *
+ * - data=1, mask=1: black
+ *
+ * - data=0, mask=1: transparent
+ *
+ * - data=1, mask=0: inverted color if possible, black if not.
+ *
+ * Cursors created with this function must be freed with SDL_FreeCursor().
+ *
+ * If you want to have a color cursor, or create your cursor from an
+ * SDL_Surface, you should use SDL_CreateColorCursor(). Alternately, you can
+ * hide the cursor and draw your own as part of your game's rendering, but it
+ * will be bound to the framerate.
+ *
+ * Also, since SDL 2.0.0, SDL_CreateSystemCursor() is available, which
+ * provides twelve readily available system cursors to pick from.
+ *
+ * \param data the color value for each pixel of the cursor
+ * \param mask the mask value for each pixel of the cursor
+ * \param w the width of the cursor
+ * \param h the height of the cursor
+ * \param hot_x the X-axis location of the upper left corner of the cursor
+ * relative to the actual mouse position
+ * \param hot_y the Y-axis location of the upper left corner of the cursor
+ * relative to the actual mouse position
+ * \returns a new cursor with the specified parameters on success or NULL on
+ * failure; call SDL_GetError() for more information.
+ *
+ * \sa SDL_FreeCursor
+ * \sa SDL_SetCursor
+ * \sa SDL_ShowCursor
*/
extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateCursor(const Uint8 * data,
const Uint8 * mask,
@@ -223,60 +293,115 @@ extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateCursor(const Uint8 * data,
int hot_y);
/**
- * \brief Create a color cursor.
+ * Create a color cursor.
+ *
+ * \param surface an SDL_Surface structure representing the cursor image
+ * \param hot_x the x position of the cursor hot spot
+ * \param hot_y the y position of the cursor hot spot
+ * \returns the new cursor on success or NULL on failure; call SDL_GetError()
+ * for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
*
- * \sa SDL_FreeCursor()
+ * \sa SDL_CreateCursor
+ * \sa SDL_FreeCursor
*/
extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateColorCursor(SDL_Surface *surface,
int hot_x,
int hot_y);
/**
- * \brief Create a system cursor.
+ * Create a system cursor.
*
- * \sa SDL_FreeCursor()
+ * \param id an SDL_SystemCursor enum value
+ * \returns a cursor on success or NULL on failure; call SDL_GetError() for
+ * more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_FreeCursor
*/
extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateSystemCursor(SDL_SystemCursor id);
/**
- * \brief Set the active cursor.
+ * Set the active cursor.
+ *
+ * This function sets the currently active cursor to the specified one. If the
+ * cursor is currently visible, the change will be immediately represented on
+ * the display. SDL_SetCursor(NULL) can be used to force cursor redraw, if
+ * this is desired for any reason.
+ *
+ * \param cursor a cursor to make active
+ *
+ * \sa SDL_CreateCursor
+ * \sa SDL_GetCursor
+ * \sa SDL_ShowCursor
*/
extern DECLSPEC void SDLCALL SDL_SetCursor(SDL_Cursor * cursor);
/**
- * \brief Return the active cursor.
+ * Get the active cursor.
+ *
+ * This function returns a pointer to the current cursor which is owned by the
+ * library. It is not necessary to free the cursor with SDL_FreeCursor().
+ *
+ * \returns the active cursor or NULL if there is no mouse.
+ *
+ * \sa SDL_SetCursor
*/
extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetCursor(void);
/**
- * \brief Return the default cursor.
+ * Get the default cursor.
+ *
+ * \returns the default cursor on success or NULL on failure.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_CreateSystemCursor
*/
extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetDefaultCursor(void);
/**
- * \brief Frees a cursor created with SDL_CreateCursor() or similar functions.
+ * Free a previously-created cursor.
+ *
+ * Use this function to free cursor resources created with SDL_CreateCursor(),
+ * SDL_CreateColorCursor() or SDL_CreateSystemCursor().
*
- * \sa SDL_CreateCursor()
- * \sa SDL_CreateColorCursor()
- * \sa SDL_CreateSystemCursor()
+ * \param cursor the cursor to free
+ *
+ * \sa SDL_CreateColorCursor
+ * \sa SDL_CreateCursor
+ * \sa SDL_CreateSystemCursor
*/
extern DECLSPEC void SDLCALL SDL_FreeCursor(SDL_Cursor * cursor);
/**
- * \brief Toggle whether or not the cursor is shown.
+ * Toggle whether or not the cursor is shown.
+ *
+ * The cursor starts off displayed but can be turned off. Passing `SDL_ENABLE`
+ * displays the cursor and passing `SDL_DISABLE` hides it.
+ *
+ * The current state of the mouse cursor can be queried by passing `SDL_QUERY`;
+ * either `SDL_DISABLE` or `SDL_ENABLE` will be returned.
*
- * \param toggle 1 to show the cursor, 0 to hide it, -1 to query the current
- * state.
+ * \param toggle `SDL_ENABLE` to show the cursor, `SDL_DISABLE` to hide it,
+ * `SDL_QUERY` to query the current state without changing it.
+ * \returns `SDL_ENABLE` if the cursor is shown, or `SDL_DISABLE` if the
+ * cursor is hidden, or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \return 1 if the cursor is shown, or 0 if the cursor is hidden.
+ * \sa SDL_CreateCursor
+ * \sa SDL_SetCursor
*/
extern DECLSPEC int SDLCALL SDL_ShowCursor(int toggle);
/**
- * Used as a mask when testing buttons in buttonstate.
- * - Button 1: Left mouse button
- * - Button 2: Middle mouse button
- * - Button 3: Right mouse button
+ * Used as a mask when testing buttons in buttonstate.
+ *
+ * - Button 1: Left mouse button
+ * - Button 2: Middle mouse button
+ * - Button 3: Right mouse button
*/
#define SDL_BUTTON(X) (1 << ((X)-1))
#define SDL_BUTTON_LEFT 1
@@ -290,7 +415,6 @@ extern DECLSPEC int SDLCALL SDL_ShowCursor(int toggle);
#define SDL_BUTTON_X1MASK SDL_BUTTON(SDL_BUTTON_X1)
#define SDL_BUTTON_X2MASK SDL_BUTTON(SDL_BUTTON_X2)
-
/* Ends C function definitions when using C++ */
#ifdef __cplusplus
}
diff --git a/include/SDL_mutex.h b/include/SDL_mutex.h
index f49b647..3b2bf19 100644
--- a/include/SDL_mutex.h
+++ b/include/SDL_mutex.h
@@ -59,38 +59,95 @@ struct SDL_mutex;
typedef struct SDL_mutex SDL_mutex;
/**
- * Create a mutex, initialized unlocked.
+ * Create a new mutex.
+ *
+ * All newly-created mutexes begin in the _unlocked_ state.
+ *
+ * Calls to SDL_LockMutex() will not return while the mutex is locked by
+ * another thread. See SDL_TryLockMutex() to attempt to lock without blocking.
+ *
+ * SDL mutexes are reentrant.
+ *
+ * \returns the initialized and unlocked mutex or NULL on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_DestroyMutex
+ * \sa SDL_LockMutex
+ * \sa SDL_TryLockMutex
+ * \sa SDL_UnlockMutex
*/
extern DECLSPEC SDL_mutex *SDLCALL SDL_CreateMutex(void);
/**
- * Lock the mutex.
+ * Lock the mutex.
+ *
+ * This will block until the mutex is available, which is to say it is in the
+ * unlocked state and the OS has chosen the caller as the next thread to lock
+ * it. Of all threads waiting to lock the mutex, only one may do so at a time.
*
- * \return 0, or -1 on error.
+ * It is legal for the owning thread to lock an already-locked mutex. It must
+ * unlock it the same number of times before it is actually made available
+ * for other threads in the system (this is known as a "recursive mutex").
+ *
+ * \param mutex the mutex to lock
+ * \return 0, or -1 on error.
*/
-#define SDL_mutexP(m) SDL_LockMutex(m)
extern DECLSPEC int SDLCALL SDL_LockMutex(SDL_mutex * mutex);
+#define SDL_mutexP(m) SDL_LockMutex(m)
/**
- * Try to lock the mutex
+ * Try to lock a mutex without blocking.
+ *
+ * This works just like SDL_LockMutex(), but if the mutex is not available,
+ * this function returns `SDL_MUTEX_TIMEOUT` immediately.
+ *
+ * This technique is useful if you need exclusive access to a resource but
+ * don't want to wait for it, and will return to it to try again later.
+ *
+ * \param mutex the mutex to try to lock
+ * \returns return 0, `SDL_MUTEX_TIMEDOUT`, or -1 on error; call
+ * SDL_GetError() for more information.
*
- * \return 0, SDL_MUTEX_TIMEDOUT, or -1 on error
+ * \sa SDL_CreateMutex
+ * \sa SDL_DestroyMutex
+ * \sa SDL_LockMutex
+ * \sa SDL_UnlockMutex
*/
extern DECLSPEC int SDLCALL SDL_TryLockMutex(SDL_mutex * mutex);
/**
- * Unlock the mutex.
+ * Unlock the mutex.
*
- * \return 0, or -1 on error.
+ * It is legal for the owning thread to lock an already-locked mutex. It must
+ * unlock it the same number of times before it is actually made available
+ * for other threads in the system (this is known as a "recursive mutex").
*
- * \warning It is an error to unlock a mutex that has not been locked by
- * the current thread, and doing so results in undefined behavior.
+ * It is an error to unlock a mutex that has not been locked by the current
+ * thread, and doing so results in undefined behavior.
+ *
+ * It is also an error to unlock a mutex that isn't locked at all.
+ *
+ * \param mutex the mutex to unlock.
+ * \returns 0, or -1 on error.
*/
-#define SDL_mutexV(m) SDL_UnlockMutex(m)
extern DECLSPEC int SDLCALL SDL_UnlockMutex(SDL_mutex * mutex);
+#define SDL_mutexV(m) SDL_UnlockMutex(m)
/**
- * Destroy a mutex.
+ * Destroy a mutex created with SDL_CreateMutex().
+ *
+ * This function must be called on any mutex that is no longer needed. Failure
+ * to destroy a mutex will result in a system memory or resource leak. While
+ * it is safe to destroy a mutex that is _unlocked_, it is not safe to attempt
+ * to destroy a locked mutex, and may result in undefined behavior depending
+ * on the platform.
+ *
+ * \param mutex the mutex to destroy
+ *
+ * \sa SDL_CreateMutex
+ * \sa SDL_LockMutex
+ * \sa SDL_TryLockMutex
+ * \sa SDL_UnlockMutex
*/
extern DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_mutex * mutex);
@@ -107,50 +164,138 @@ struct SDL_semaphore;
typedef struct SDL_semaphore SDL_sem;
/**
- * Create a semaphore, initialized with value, returns NULL on failure.
+ * Create a semaphore.
+ *
+ * This function creates a new semaphore and initializes it with the value
+ * `initial_value`. Each wait operation on the semaphore will atomically
+ * decrement the semaphore value and potentially block if the semaphore value
+ * is 0. Each post operation will atomically increment the semaphore value and
+ * wake waiting threads and allow them to retry the wait operation.
+ *
+ * \param initial_value the starting value of the semaphore
+ * \returns a new semaphore or NULL on failure; call SDL_GetError() for more
+ * information.
+ *
+ * \sa SDL_DestroySemaphore
+ * \sa SDL_SemPost
+ * \sa SDL_SemTryWait
+ * \sa SDL_SemValue
+ * \sa SDL_SemWait
+ * \sa SDL_SemWaitTimeout
*/
extern DECLSPEC SDL_sem *SDLCALL SDL_CreateSemaphore(Uint32 initial_value);
/**
- * Destroy a semaphore.
+ * Destroy a semaphore.
+ *
+ * It is not safe to destroy a semaphore if there are threads currently
+ * waiting on it.
+ *
+ * \param sem the semaphore to destroy
+ *
+ * \sa SDL_CreateSemaphore
+ * \sa SDL_SemPost
+ * \sa SDL_SemTryWait
+ * \sa SDL_SemValue
+ * \sa SDL_SemWait
+ * \sa SDL_SemWaitTimeout
*/
extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem * sem);
/**
- * This function suspends the calling thread until the semaphore pointed
- * to by \c sem has a positive count. It then atomically decreases the
- * semaphore count.
+ * Wait until a semaphore has a positive value and then decrements it.
+ *
+ * This function suspends the calling thread until either the semaphore
+ * pointed to by `sem` has a positive value or the call is interrupted by a
+ * signal or error. If the call is successful it will atomically decrement the
+ * semaphore value.
+ *
+ * This function is the equivalent of calling SDL_SemWaitTimeout() with a time
+ * length of `SDL_MUTEX_MAXWAIT`.
+ *
+ * \param sem the semaphore wait on
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_CreateSemaphore
+ * \sa SDL_DestroySemaphore
+ * \sa SDL_SemPost
+ * \sa SDL_SemTryWait
+ * \sa SDL_SemValue
+ * \sa SDL_SemWait
+ * \sa SDL_SemWaitTimeout
*/
extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem * sem);
/**
- * Non-blocking variant of SDL_SemWait().
+ * See if a semaphore has a positive value and decrement it if it does.
+ *
+ * This function checks to see if the semaphore pointed to by `sem` has a
+ * positive value and atomically decrements the semaphore value if it does. If
+ * the semaphore doesn't have a positive value, the function immediately
+ * returns SDL_MUTEX_TIMEDOUT.
*
- * \return 0 if the wait succeeds, ::SDL_MUTEX_TIMEDOUT if the wait would
- * block, and -1 on error.
+ * \param sem the semaphore to wait on
+ * \returns 0 if the wait succeeds, `SDL_MUTEX_TIMEDOUT` if the wait would
+ * block, or a negative error code on failure; call SDL_GetError()
+ * for more information.
+ *
+ * \sa SDL_CreateSemaphore
+ * \sa SDL_DestroySemaphore
+ * \sa SDL_SemPost
+ * \sa SDL_SemValue
+ * \sa SDL_SemWait
+ * \sa SDL_SemWaitTimeout
*/
extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem * sem);
/**
- * Variant of SDL_SemWait() with a timeout in milliseconds.
+ * Wait until a semaphore has a positive value and then
+ * decrements it.
+ *
+ * This function suspends the calling thread until either the semaphore
+ * pointed to by `sem` has a positive value, the call is interrupted by a
+ * signal or error, or the specified time has elapsed. If the call is
+ * successful it will atomically decrement the semaphore value.
*
- * \return 0 if the wait succeeds, ::SDL_MUTEX_TIMEDOUT if the wait does not
- * succeed in the allotted time, and -1 on error.
+ * \param sem the semaphore to wait on
+ * \param ms the length of the timeout, in milliseconds
+ * \returns 0 if the wait succeeds, `SDL_MUTEX_TIMEDOUT` if the wait does not
+ * succeed in the allotted time, or a negative error code on failure;
+ * call SDL_GetError() for more information.
*
- * \warning On some platforms this function is implemented by looping with a
- * delay of 1 ms, and so should be avoided if possible.
+ * \sa SDL_CreateSemaphore
+ * \sa SDL_DestroySemaphore
+ * \sa SDL_SemPost
+ * \sa SDL_SemTryWait
+ * \sa SDL_SemValue
+ * \sa SDL_SemWait
*/
extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem * sem, Uint32 ms);
/**
- * Atomically increases the semaphore's count (not blocking).
+ * Atomically increment a semaphore's value and wake waiting threads.
+ *
+ * \param sem the semaphore to increment
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \return 0, or -1 on error.
+ * \sa SDL_CreateSemaphore
+ * \sa SDL_DestroySemaphore
+ * \sa SDL_SemTryWait
+ * \sa SDL_SemValue
+ * \sa SDL_SemWait
+ * \sa SDL_SemWaitTimeout
*/
extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem * sem);
/**
- * Returns the current count of the semaphore.
+ * Get the current value of a semaphore.
+ *
+ * \param sem the semaphore to query
+ * \returns the current value of the semaphore.
+ *
+ * \sa SDL_CreateSemaphore
*/
extern DECLSPEC Uint32 SDLCALL SDL_SemValue(SDL_sem * sem);
@@ -167,72 +312,112 @@ struct SDL_cond;
typedef struct SDL_cond SDL_cond;
/**
- * Create a condition variable.
- *
- * Typical use of condition variables:
+ * Create a condition variable.
*
- * Thread A:
- * SDL_LockMutex(lock);
- * while ( ! condition ) {
- * SDL_CondWait(cond, lock);
- * }
- * SDL_UnlockMutex(lock);
+ * \returns a new condition variable or NULL on failure; call SDL_GetError()
+ * for more information.
*
- * Thread B:
- * SDL_LockMutex(lock);
- * ...
- * condition = true;
- * ...
- * SDL_CondSignal(cond);
- * SDL_UnlockMutex(lock);
- *
- * There is some discussion whether to signal the condition variable
- * with the mutex locked or not. There is some potential performance
- * benefit to unlocking first on some platforms, but there are some
- * potential race conditions depending on how your code is structured.
- *
- * In general it's safer to signal the condition variable while the
- * mutex is locked.
+ * \sa SDL_CondBroadcast
+ * \sa SDL_CondSignal
+ * \sa SDL_CondWait
+ * \sa SDL_CondWaitTimeout
+ * \sa SDL_DestroyCond
*/
extern DECLSPEC SDL_cond *SDLCALL SDL_CreateCond(void);
/**
- * Destroy a condition variable.
+ * Destroy a condition variable.
+ *
+ * \param cond the condition variable to destroy
+ *
+ * \sa SDL_CondBroadcast
+ * \sa SDL_CondSignal
+ * \sa SDL_CondWait
+ * \sa SDL_CondWaitTimeout
+ * \sa SDL_CreateCond
*/
extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond * cond);
/**
- * Restart one of the threads that are waiting on the condition variable.
+ * Restart one of the threads that are waiting on the condition variable.
+ *
+ * \param cond the condition variable to signal
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \return 0 or -1 on error.
+ * \sa SDL_CondBroadcast
+ * \sa SDL_CondWait
+ * \sa SDL_CondWaitTimeout
+ * \sa SDL_CreateCond
+ * \sa SDL_DestroyCond
*/
extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond * cond);
/**
- * Restart all threads that are waiting on the condition variable.
+ * Restart all threads that are waiting on the condition variable.
+ *
+ * \param cond the condition variable to signal
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \return 0 or -1 on error.
+ * \sa SDL_CondSignal
+ * \sa SDL_CondWait
+ * \sa SDL_CondWaitTimeout
+ * \sa SDL_CreateCond
+ * \sa SDL_DestroyCond
*/
extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond * cond);
/**
- * Wait on the condition variable, unlocking the provided mutex.
+ * Wait until a condition variable is signaled.
*
- * \warning The mutex must be locked before entering this function!
+ * This function unlocks the specified `mutex` and waits for another thread
+ * to call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable
+ * `cond`. Once the condition variable is signaled, the mutex is re-locked
+ * and the function returns.
*
- * The mutex is re-locked once the condition variable is signaled.
+ * The mutex must be locked before calling this function.
*
- * \return 0 when it is signaled, or -1 on error.
+ * This function is the equivalent of calling SDL_CondWaitTimeout() with a
+ * time length of `SDL_MUTEX_MAXWAIT`.
+ *
+ * \param cond the condition variable to wait on
+ * \param mutex the mutex used to coordinate thread access
+ * \returns 0 when it is signaled or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_CondBroadcast
+ * \sa SDL_CondSignal
+ * \sa SDL_CondWaitTimeout
+ * \sa SDL_CreateCond
+ * \sa SDL_DestroyCond
*/
extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond * cond, SDL_mutex * mutex);
/**
- * Waits for at most \c ms milliseconds, and returns 0 if the condition
- * variable is signaled, ::SDL_MUTEX_TIMEDOUT if the condition is not
- * signaled in the allotted time, and -1 on error.
+ * Wait until a condition variable is signaled or a certain time has passed.
+ *
+ * This function unlocks the specified `mutex` and waits for another thread
+ * to call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable
+ * `cond`, or for the specified time to elapse. Once the condition variable
+ * is signaled or the time elapsed, the mutex is re-locked and the function
+ * returns.
+ *
+ * The mutex must be locked before calling this function.
+ *
+ * \param cond the condition variable to wait on
+ * \param mutex the mutex used to coordinate thread access
+ * \param ms the maximum time to wait, in milliseconds, or `SDL_MUTEX_MAXWAIT`
+ * to wait indefinitely
+ * \returns 0 if the condition variable is signaled, `SDL_MUTEX_TIMEDOUT` if
+ * the condition is not signaled in the allotted time, or a negative
+ * error code on failure; call SDL_GetError() for more information.
*
- * \warning On some platforms this function is implemented by looping with a
- * delay of 1 ms, and so should be avoided if possible.
+ * \sa SDL_CondBroadcast
+ * \sa SDL_CondSignal
+ * \sa SDL_CondWait
+ * \sa SDL_CreateCond
+ * \sa SDL_DestroyCond
*/
extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond * cond,
SDL_mutex * mutex, Uint32 ms);
diff --git a/include/SDL_pixels.h b/include/SDL_pixels.h
index e1aedf2..a6d464c 100644
--- a/include/SDL_pixels.h
+++ b/include/SDL_pixels.h
@@ -345,16 +345,29 @@ typedef struct SDL_PixelFormat
} SDL_PixelFormat;
/**
- * \brief Get the human readable name of a pixel format
+ * Get the human readable name of a pixel format.
+ *
+ * \param format the pixel format to query
+ * \returns the human readable name of the specified pixel format or
+ * `SDL_PIXELFORMAT_UNKNOWN` if the format isn't recognized.
+ *
+ * \since This function is available since SDL 2.0.0.
*/
extern DECLSPEC const char* SDLCALL SDL_GetPixelFormatName(Uint32 format);
/**
- * \brief Convert one of the enumerated pixel formats to a bpp and RGBA masks.
+ * Convert one of the enumerated pixel formats to a bpp value and RGBA masks.
*
- * \return SDL_TRUE, or SDL_FALSE if the conversion wasn't possible.
+ * \param format one of the SDL_PixelFormatEnum values
+ * \param bpp a bits per pixel value; usually 15, 16, or 32
+ * \param Rmask a pointer filled in with the red mask for the format
+ * \param Gmask a pointer filled in with the green mask for the format
+ * \param Bmask a pointer filled in with the blue mask for the format
+ * \param Amask a pointer filled in with the alpha mask for the format
+ * \returns SDL_TRUE on success or SDL_FALSE if the conversion wasn't
+ * possible; call SDL_GetError() for more information.
*
- * \sa SDL_MasksToPixelFormatEnum()
+ * \sa SDL_MasksToPixelFormatEnum
*/
extern DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks(Uint32 format,
int *bpp,
@@ -364,12 +377,19 @@ extern DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks(Uint32 format,
Uint32 * Amask);
/**
- * \brief Convert a bpp and RGBA masks to an enumerated pixel format.
+ * Convert a bpp value and RGBA masks to an enumerated pixel format.
*
- * \return The pixel format, or ::SDL_PIXELFORMAT_UNKNOWN if the conversion
- * wasn't possible.
+ * This will return `SDL_PIXELFORMAT_UNKNOWN` if the conversion wasn't
+ * possible.
*
- * \sa SDL_PixelFormatEnumToMasks()
+ * \param bpp a bits per pixel value; usually 15, 16, or 32
+ * \param Rmask the red mask for the format
+ * \param Gmask the green mask for the format
+ * \param Bmask the blue mask for the format
+ * \param Amask the alpha mask for the format
+ * \returns one of the SDL_PixelFormatEnum values
+ *
+ * \sa SDL_PixelFormatEnumToMasks
*/
extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp,
Uint32 Rmask,
@@ -378,84 +398,193 @@ extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp,
Uint32 Amask);
/**
- * \brief Create an SDL_PixelFormat structure from a pixel format enum.
+ * Create an SDL_PixelFormat structure corresponding to a pixel format.
+ *
+ * Returned structure may come from a shared global cache (i.e. not newly
+ * allocated), and hence should not be modified, especially the palette. Weird
+ * errors such as `Blit combination not supported` may occur.
+ *
+ * \param pixel_format one of the SDL_PixelFormatEnum values
+ * \returns the new SDL_PixelFormat structure or NULL on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_FreeFormat
*/
extern DECLSPEC SDL_PixelFormat * SDLCALL SDL_AllocFormat(Uint32 pixel_format);
/**
- * \brief Free an SDL_PixelFormat structure.
+ * Free an SDL_PixelFormat structure allocated by SDL_AllocFormat().
+ *
+ * \param format the SDL_PixelFormat structure to free
+ *
+ * \sa SDL_AllocFormat
*/
extern DECLSPEC void SDLCALL SDL_FreeFormat(SDL_PixelFormat *format);
/**
- * \brief Create a palette structure with the specified number of color
- * entries.
+ * Create a palette structure with the specified number of color entries.
*
- * \return A new palette, or NULL if there wasn't enough memory.
+ * The palette entries are initialized to white.
*
- * \note The palette entries are initialized to white.
+ * \param ncolors represents the number of color entries in the color palette
+ * \returns a new SDL_Palette structure on success or NULL on failure (e.g. if
+ * there wasn't enough memory); call SDL_GetError() for more
+ * information.
*
- * \sa SDL_FreePalette()
+ * \sa SDL_FreePalette
*/
extern DECLSPEC SDL_Palette *SDLCALL SDL_AllocPalette(int ncolors);
/**
- * \brief Set the palette for a pixel format structure.
+ * Set the palette for a pixel format structure.
+ *
+ * \param format the SDL_PixelFormat structure that will use the palette
+ * \param palette the SDL_Palette structure that will be used
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_AllocPalette
+ * \sa SDL_FreePalette
*/
extern DECLSPEC int SDLCALL SDL_SetPixelFormatPalette(SDL_PixelFormat * format,
SDL_Palette *palette);
/**
- * \brief Set a range of colors in a palette.
+ * Set a range of colors in a palette.
*
- * \param palette The palette to modify.
- * \param colors An array of colors to copy into the palette.
- * \param firstcolor The index of the first palette entry to modify.
- * \param ncolors The number of entries to modify.
+ * \param palette the SDL_Palette structure to modify
+ * \param colors an array of SDL_Color structures to copy into the palette
+ * \param firstcolor the index of the first palette entry to modify
+ * \param ncolors the number of entries to modify
+ * \returns 0 on success or a negative error code if not all of the colors
+ * could be set; call SDL_GetError() for more information.
*
- * \return 0 on success, or -1 if not all of the colors could be set.
+ * \sa SDL_AllocPalette
+ * \sa SDL_CreateRGBSurface
*/
extern DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette * palette,
const SDL_Color * colors,
int firstcolor, int ncolors);
/**
- * \brief Free a palette created with SDL_AllocPalette().
+ * Free a palette created with SDL_AllocPalette().
+ *
+ * \param palette the SDL_Palette structure to be freed
*
- * \sa SDL_AllocPalette()
+ * \sa SDL_AllocPalette
*/
extern DECLSPEC void SDLCALL SDL_FreePalette(SDL_Palette * palette);
/**
- * \brief Maps an RGB triple to an opaque pixel value for a given pixel format.
+ * Map an RGB triple to an opaque pixel value for a given pixel format.
+ *
+ * This function maps the RGB color value to the specified pixel format and
+ * returns the pixel value best approximating the given RGB color value for
+ * the given pixel format.
+ *
+ * If the format has a palette (8-bit) the index of the closest matching color
+ * in the palette will be returned.
+ *
+ * If the specified pixel format has an alpha component it will be returned as
+ * all 1 bits (fully opaque).
*
- * \sa SDL_MapRGBA
+ * If the pixel format bpp (color depth) is less than 32-bpp then the unused
+ * upper bits of the return value can safely be ignored (e.g., with a 16-bpp
+ * format the return value can be assigned to a Uint16, and similarly a Uint8
+ * for an 8-bpp format).
+ *
+ * \param format an SDL_PixelFormat structure describing the pixel format
+ * \param r the red component of the pixel in the range 0-255
+ * \param g the green component of the pixel in the range 0-255
+ * \param b the blue component of the pixel in the range 0-255
+ * \returns a pixel value
+ *
+ * \sa SDL_GetRGB
+ * \sa SDL_GetRGBA
+ * \sa SDL_MapRGBA
*/
extern DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormat * format,
Uint8 r, Uint8 g, Uint8 b);
/**
- * \brief Maps an RGBA quadruple to a pixel value for a given pixel format.
+ * Map an RGBA quadruple to a pixel value for a given pixel format.
+ *
+ * This function maps the RGBA color value to the specified pixel format and
+ * returns the pixel value best approximating the given RGBA color value for
+ * the given pixel format.
+ *
+ * If the specified pixel format has no alpha component the alpha value will
+ * be ignored (as it will be in formats with a palette).
+ *
+ * If the format has a palette (8-bit) the index of the closest matching color
+ * in the palette will be returned.
+ *
+ * If the pixel format bpp (color depth) is less than 32-bpp then the unused
+ * upper bits of the return value can safely be ignored (e.g., with a 16-bpp
+ * format the return value can be assigned to a Uint16, and similarly a Uint8
+ * for an 8-bpp format).
+ *
+ * \param format an SDL_PixelFormat structure describing the format of the
+ * pixel
+ * \param r the red component of the pixel in the range 0-255
+ * \param g the green component of the pixel in the range 0-255
+ * \param b the blue component of the pixel in the range 0-255
+ * \param a the alpha component of the pixel in the range 0-255
+ * \returns a pixel value
*
- * \sa SDL_MapRGB
+ * \sa SDL_GetRGB
+ * \sa SDL_GetRGBA
+ * \sa SDL_MapRGB
*/
extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormat * format,
Uint8 r, Uint8 g, Uint8 b,
Uint8 a);
/**
- * \brief Get the RGB components from a pixel of the specified format.
+ * Get RGB values from a pixel in the specified format.
*
- * \sa SDL_GetRGBA
+ * This function uses the entire 8-bit [0..255] range when converting color
+ * components from pixel formats with less than 8-bits per RGB component
+ * (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff,
+ * 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).
+ *
+ * \param pixel a pixel value
+ * \param format an SDL_PixelFormat structure describing the format of the
+ * pixel
+ * \param r a pointer filled in with the red component
+ * \param g a pointer filled in with the green component
+ * \param b a pointer filled in with the blue component
+ *
+ * \sa SDL_GetRGBA
+ * \sa SDL_MapRGB
+ * \sa SDL_MapRGBA
*/
extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
const SDL_PixelFormat * format,
Uint8 * r, Uint8 * g, Uint8 * b);
/**
- * \brief Get the RGBA components from a pixel of the specified format.
+ * Get RGBA values from a pixel in the specified format.
+ *
+ * This function uses the entire 8-bit [0..255] range when converting color
+ * components from pixel formats with less than 8-bits per RGB component
+ * (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff,
+ * 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).
+ *
+ * If the surface has no alpha component, the alpha will be returned as 0xff
+ * (100% opaque).
*
- * \sa SDL_GetRGB
+ * \param pixel a pixel value
+ * \param format an SDL_PixelFormat structure describing the format of the
+ * pixel
+ * \param r a pointer filled in with the red component
+ * \param g a pointer filled in with the green component
+ * \param b a pointer filled in with the blue component
+ * \param a a pointer filled in with the alpha component
+ *
+ * \sa SDL_GetRGB
+ * \sa SDL_MapRGB
+ * \sa SDL_MapRGBA
*/
extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
const SDL_PixelFormat * format,
@@ -463,7 +592,12 @@ extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
Uint8 * a);
/**
- * \brief Calculate a 256 entry gamma ramp for a gamma value.
+ * Calculate a 256 entry gamma ramp for a gamma value.
+ *
+ * \param gamma a gamma value where 0.0 is black and 1.0 is identity
+ * \param ramp an array of 256 values filled in with the gamma ramp
+ *
+ * \sa SDL_SetWindowGammaRamp
*/
extern DECLSPEC void SDLCALL SDL_CalculateGammaRamp(float gamma, Uint16 * ramp);
diff --git a/include/SDL_platform.h b/include/SDL_platform.h
index 428e427..ea3aadd 100644
--- a/include/SDL_platform.h
+++ b/include/SDL_platform.h
@@ -186,7 +186,22 @@ extern "C" {
#endif
/**
- * \brief Gets the name of the platform.
+ * Get the name of the platform.
+ *
+ * Here are the names returned for some (but not all) supported platforms:
+ *
+ * - "Windows"
+ *
+ * - "Mac OS X"
+ *
+ * - "Linux"
+ *
+ * - "iOS"
+ *
+ * - "Android"
+ *
+ * \returns the name of the platform. If the correct platform name is not
+ * available, returns a string beginning with the text "Unknown".
*/
extern DECLSPEC const char * SDLCALL SDL_GetPlatform (void);
diff --git a/include/SDL_power.h b/include/SDL_power.h
index cc6160e..872be18 100644
--- a/include/SDL_power.h
+++ b/include/SDL_power.h
@@ -37,7 +37,7 @@ extern "C" {
#endif
/**
- * \brief The basic state for the system's power supply.
+ * The basic state for the system's power supply.
*/
typedef enum
{
@@ -50,17 +50,28 @@ typedef enum
/**
- * \brief Get the current power supply details.
+ * Get the current power supply details.
*
- * \param secs Seconds of battery life left. You can pass a NULL here if
- * you don't care. Will return -1 if we can't determine a
- * value, or we're not running on a battery.
+ * You should never take a battery status as absolute truth. Batteries
+ * (especially failing batteries) are delicate hardware, and the values
+ * reported here are best estimates based on what that hardware reports. It's
+ * not uncommon for older batteries to lose stored power much faster than it
+ * reports, or completely drain when reporting it has 20 percent left, etc.
*
- * \param pct Percentage of battery life left, between 0 and 100. You can
- * pass a NULL here if you don't care. Will return -1 if we
- * can't determine a value, or we're not running on a battery.
+ * Battery status can change at any time; if you are concerned with power
+ * state, you should call this function frequently, and perhaps ignore changes
+ * until they seem to be stable for a few seconds.
*
- * \return The state of the battery (if any).
+ * It's possible a platform can only report battery percentage or time left
+ * but not both.
+ *
+ * \param secs seconds of battery life left, you can pass a NULL here if you
+ * don't care, will return -1 if we can't determine a value, or
+ * we're not running on a battery
+ * \param pct percentage of battery life left, between 0 and 100, you can pass
+ * a NULL here if you don't care, will return -1 if we can't
+ * determine a value, or we're not running on a battery
+ * \returns an SDL_PowerState enum representing the current battery state.
*/
extern DECLSPEC SDL_PowerState SDLCALL SDL_GetPowerInfo(int *secs, int *pct);
diff --git a/include/SDL_rect.h b/include/SDL_rect.h
index b1897e5..ae47298 100644
--- a/include/SDL_rect.h
+++ b/include/SDL_rect.h
@@ -40,10 +40,10 @@ extern "C" {
#endif
/**
- * \brief The structure that defines a point (integer)
+ * The structure that defines a point (integer)
*
- * \sa SDL_EnclosePoints
- * \sa SDL_PointInRect
+ * \sa SDL_EnclosePoints
+ * \sa SDL_PointInRect
*/
typedef struct SDL_Point
{
@@ -52,10 +52,10 @@ typedef struct SDL_Point
} SDL_Point;
/**
- * \brief The structure that defines a point (floating point)
+ * The structure that defines a point (floating point)
*
- * \sa SDL_EnclosePoints
- * \sa SDL_PointInRect
+ * \sa SDL_EnclosePoints
+ * \sa SDL_PointInRect
*/
typedef struct SDL_FPoint
{
@@ -65,14 +65,14 @@ typedef struct SDL_FPoint
/**
- * \brief A rectangle, with the origin at the upper left (integer).
- *
- * \sa SDL_RectEmpty
- * \sa SDL_RectEquals
- * \sa SDL_HasIntersection
- * \sa SDL_IntersectRect
- * \sa SDL_UnionRect
- * \sa SDL_EnclosePoints
+ * A rectangle, with the origin at the upper left (integer).
+ *
+ * \sa SDL_RectEmpty
+ * \sa SDL_RectEquals
+ * \sa SDL_HasIntersection
+ * \sa SDL_IntersectRect
+ * \sa SDL_UnionRect
+ * \sa SDL_EnclosePoints
*/
typedef struct SDL_Rect
{
@@ -82,7 +82,7 @@ typedef struct SDL_Rect
/**
- * \brief A rectangle, with the origin at the upper left (floating point).
+ * A rectangle, with the origin at the upper left (floating point).
*/
typedef struct SDL_FRect
{
@@ -94,7 +94,7 @@ typedef struct SDL_FRect
/**
- * \brief Returns true if point resides inside a rectangle.
+ * Returns true if point resides inside a rectangle.
*/
SDL_FORCE_INLINE SDL_bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r)
{
@@ -103,7 +103,7 @@ SDL_FORCE_INLINE SDL_bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r)
}
/**
- * \brief Returns true if the rectangle has no area.
+ * Returns true if the rectangle has no area.
*/
SDL_FORCE_INLINE SDL_bool SDL_RectEmpty(const SDL_Rect *r)
{
@@ -111,7 +111,7 @@ SDL_FORCE_INLINE SDL_bool SDL_RectEmpty(const SDL_Rect *r)
}
/**
- * \brief Returns true if the two rectangles are equal.
+ * Returns true if the two rectangles are equal.
*/
SDL_FORCE_INLINE SDL_bool SDL_RectEquals(const SDL_Rect *a, const SDL_Rect *b)
{
@@ -120,33 +120,66 @@ SDL_FORCE_INLINE SDL_bool SDL_RectEquals(const SDL_Rect *a, const SDL_Rect *b)
}
/**
- * \brief Determine whether two rectangles intersect.
+ * Determine whether two rectangles intersect.
+ *
+ * If either pointer is NULL the function will return SDL_FALSE.
+ *
+ * \param A an SDL_Rect structure representing the first rectangle
+ * \param B an SDL_Rect structure representing the second rectangle
+ * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
*
- * \return SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_IntersectRect
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasIntersection(const SDL_Rect * A,
const SDL_Rect * B);
/**
- * \brief Calculate the intersection of two rectangles.
+ * Calculate the intersection of two rectangles.
+ *
+ * If `result` is NULL then this function will return SDL_FALSE.
*
- * \return SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
+ * \param A an SDL_Rect structure representing the first rectangle
+ * \param B an SDL_Rect structure representing the second rectangle
+ * \param result an SDL_Rect structure filled in with the intersection of
+ * rectangles `A` and `B`
+ * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HasIntersection
*/
extern DECLSPEC SDL_bool SDLCALL SDL_IntersectRect(const SDL_Rect * A,
const SDL_Rect * B,
SDL_Rect * result);
/**
- * \brief Calculate the union of two rectangles.
+ * Calculate the union of two rectangles.
+ *
+ * \param A an SDL_Rect structure representing the first rectangle
+ * \param B an SDL_Rect structure representing the second rectangle
+ * \param result an SDL_Rect structure filled in with the union of rectangles
+ * `A` and `B`
*/
extern DECLSPEC void SDLCALL SDL_UnionRect(const SDL_Rect * A,
const SDL_Rect * B,
SDL_Rect * result);
/**
- * \brief Calculate a minimal rectangle enclosing a set of points
+ * Calculate a minimal rectangle enclosing a set of points.
*
- * \return SDL_TRUE if any points were within the clipping rect
+ * If `clip` is not NULL then only points inside of the clipping rectangle
+ * are considered.
+ *
+ * \param points an array of SDL_Point structures representing points to be
+ * enclosed
+ * \param count the number of structures in the `points` array
+ * \param clip an SDL_Rect used for clipping or NULL to enclose all points
+ * \param result an SDL_Rect structure filled in with the minimal enclosing
+ * rectangle
+ * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the
+ * points were outside of the clipping rectangle.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_EnclosePoints(const SDL_Point * points,
int count,
@@ -154,9 +187,20 @@ extern DECLSPEC SDL_bool SDLCALL SDL_EnclosePoints(const SDL_Point * points,
SDL_Rect * result);
/**
- * \brief Calculate the intersection of a rectangle and line segment.
+ * Calculate the intersection of a rectangle and line segment.
+ *
+ * This function is used to clip a line segment to a rectangle. A line segment
+ * contained entirely within the rectangle or that does not intersect will
+ * remain unchanged. A line segment that crosses the rectangle at either or
+ * both ends will be clipped to the boundary of the rectangle and the new
+ * coordinates saved in `X1`, `Y1`, `X2`, and/or `Y2` as necessary.
*
- * \return SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
+ * \param rect an SDL_Rect structure representing the rectangle to intersect
+ * \param X1 a pointer to the starting X-coordinate of the line
+ * \param Y1 a pointer to the starting Y-coordinate of the line
+ * \param X2 a pointer to the ending X-coordinate of the line
+ * \param Y2 a pointer to the ending Y-coordinate of the line
+ * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_IntersectRectAndLine(const SDL_Rect *
rect, int *X1,
diff --git a/include/SDL_render.h b/include/SDL_render.h
index 980109a..21ce63a 100644
--- a/include/SDL_render.h
+++ b/include/SDL_render.h
@@ -59,7 +59,7 @@ extern "C" {
#endif
/**
- * \brief Flags used when creating a rendering context
+ * Flags used when creating a rendering context
*/
typedef enum
{
@@ -73,7 +73,7 @@ typedef enum
} SDL_RendererFlags;
/**
- * \brief Information on the capabilities of a render driver or context.
+ * Information on the capabilities of a render driver or context.
*/
typedef struct SDL_RendererInfo
{
@@ -86,7 +86,7 @@ typedef struct SDL_RendererInfo
} SDL_RendererInfo;
/**
- * \brief The scaling mode for a texture.
+ * The scaling mode for a texture.
*/
typedef enum
{
@@ -96,7 +96,7 @@ typedef enum
} SDL_ScaleMode;
/**
- * \brief The access pattern allowed for a texture.
+ * The access pattern allowed for a texture.
*/
typedef enum
{
@@ -106,7 +106,7 @@ typedef enum
} SDL_TextureAccess;
/**
- * \brief The texture channel modulation used in SDL_RenderCopy().
+ * The texture channel modulation used in SDL_RenderCopy().
*/
typedef enum
{
@@ -116,7 +116,7 @@ typedef enum
} SDL_TextureModulate;
/**
- * \brief Flip constants for SDL_RenderCopyEx
+ * Flip constants for SDL_RenderCopyEx
*/
typedef enum
{
@@ -126,13 +126,13 @@ typedef enum
} SDL_RendererFlip;
/**
- * \brief A structure representing rendering state
+ * A structure representing rendering state
*/
struct SDL_Renderer;
typedef struct SDL_Renderer SDL_Renderer;
/**
- * \brief An efficient driver-specific representation of pixel data
+ * An efficient driver-specific representation of pixel data
*/
struct SDL_Texture;
typedef struct SDL_Texture SDL_Texture;
@@ -141,43 +141,53 @@ typedef struct SDL_Texture SDL_Texture;
/* Function prototypes */
/**
- * \brief Get the number of 2D rendering drivers available for the current
- * display.
+ * Get the number of 2D rendering drivers available for the current display.
*
- * A render driver is a set of code that handles rendering and texture
- * management on a particular display. Normally there is only one, but
- * some drivers may have several available with different capabilities.
+ * A render driver is a set of code that handles rendering and texture
+ * management on a particular display. Normally there is only one, but some
+ * drivers may have several available with different capabilities.
*
- * \sa SDL_GetRenderDriverInfo()
- * \sa SDL_CreateRenderer()
+ * There may be none if SDL was compiled without render support.
+ *
+ * \returns a number >= 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_CreateRenderer
+ * \sa SDL_GetRenderDriverInfo
*/
extern DECLSPEC int SDLCALL SDL_GetNumRenderDrivers(void);
/**
- * \brief Get information about a specific 2D rendering driver for the current
- * display.
- *
- * \param index The index of the driver to query information about.
- * \param info A pointer to an SDL_RendererInfo struct to be filled with
- * information on the rendering driver.
+ * Get info about a specific 2D rendering driver for the current display.
*
- * \return 0 on success, -1 if the index was out of range.
+ * \param index the index of the driver to query information about
+ * \param info an SDL_RendererInfo structure to be filled with information on
+ * the rendering driver
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_CreateRenderer()
+ * \sa SDL_CreateRenderer
+ * \sa SDL_GetNumRenderDrivers
*/
extern DECLSPEC int SDLCALL SDL_GetRenderDriverInfo(int index,
SDL_RendererInfo * info);
/**
- * \brief Create a window and default renderer
+ * Create a window and default renderer.
*
- * \param width The width of the window
- * \param height The height of the window
- * \param window_flags The flags used to create the window
- * \param window A pointer filled with the window, or NULL on error
- * \param renderer A pointer filled with the renderer, or NULL on error
+ * \param width the width of the window
+ * \param height the height of the window
+ * \param window_flags the flags used to create the window (see
+ * SDL_CreateWindow())
+ * \param window a pointer filled with the window, or NULL on error
+ * \param renderer a pointer filled with the renderer, or NULL on error
+ * \returns 0 on success, or -1 on error; call SDL_GetError() for more
+ * information.
*
- * \return 0 on success, or -1 on error
+ * \sa SDL_CreateRenderer
+ * \sa SDL_CreateWindow
*/
extern DECLSPEC int SDLCALL SDL_CreateWindowAndRenderer(
int width, int height, Uint32 window_flags,
@@ -185,69 +195,106 @@ extern DECLSPEC int SDLCALL SDL_CreateWindowAndRenderer(
/**
- * \brief Create a 2D rendering context for a window.
+ * Create a 2D rendering context for a window.
*
- * \param window The window where rendering is displayed.
- * \param index The index of the rendering driver to initialize, or -1 to
- * initialize the first one supporting the requested flags.
- * \param flags ::SDL_RendererFlags.
+ * \param window the window where rendering is displayed
+ * \param index the index of the rendering driver to initialize, or -1 to
+ * initialize the first one supporting the requested flags
+ * \param flags 0, or one or more SDL_RendererFlags OR'd together
+ * \returns a valid rendering context or NULL if there was an error; call
+ * SDL_GetError() for more information.
*
- * \return A valid rendering context or NULL if there was an error.
- *
- * \sa SDL_CreateSoftwareRenderer()
- * \sa SDL_GetRendererInfo()
- * \sa SDL_DestroyRenderer()
+ * \sa SDL_CreateSoftwareRenderer
+ * \sa SDL_DestroyRenderer
+ * \sa SDL_GetNumRenderDrivers
+ * \sa SDL_GetRendererInfo
*/
extern DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRenderer(SDL_Window * window,
int index, Uint32 flags);
/**
- * \brief Create a 2D software rendering context for a surface.
+ * Create a 2D software rendering context for a surface.
*
- * \param surface The surface where rendering is done.
+ * Two other API which can be used to create SDL_Renderer:
+ * SDL_CreateRenderer() and SDL_CreateWindowAndRenderer(). These can _also_
+ * create a software renderer, but they are intended to be used with an
+ * SDL_Window as the final destination and not an SDL_Surface.
*
- * \return A valid rendering context or NULL if there was an error.
+ * \param surface the SDL_Surface structure representing the surface where
+ * rendering is done
+ * \returns a valid rendering context or NULL if there was an error; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_CreateRenderer()
- * \sa SDL_DestroyRenderer()
+ * \sa SDL_CreateRenderer
+ * \sa SDL_CreateWindowRenderer
+ * \sa SDL_DestroyRenderer
*/
extern DECLSPEC SDL_Renderer * SDLCALL SDL_CreateSoftwareRenderer(SDL_Surface * surface);
/**
- * \brief Get the renderer associated with a window.
+ * Get the renderer associated with a window.
+ *
+ * \param window the window to query
+ * \returns the rendering context on success or NULL on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_CreateRenderer
*/
extern DECLSPEC SDL_Renderer * SDLCALL SDL_GetRenderer(SDL_Window * window);
/**
- * \brief Get information about a rendering context.
+ * Get information about a rendering context.
+ *
+ * \param renderer the rendering context
+ * \param info an SDL_RendererInfo structure filled with information about the
+ * current renderer
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_CreateRenderer
*/
extern DECLSPEC int SDLCALL SDL_GetRendererInfo(SDL_Renderer * renderer,
SDL_RendererInfo * info);
/**
- * \brief Get the output size in pixels of a rendering context.
+ * Get the output size in pixels of a rendering context.
+ *
+ * Due to high-dpi displays, you might end up with a rendering context that
+ * has more pixels than the window that contains it, so use this instead of
+ * SDL_GetWindowSize() to decide how much drawing area you have.
+ *
+ * \param renderer the rendering context
+ * \param w an int filled with the width
+ * \param h an int filled with the height
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetRenderer
*/
extern DECLSPEC int SDLCALL SDL_GetRendererOutputSize(SDL_Renderer * renderer,
int *w, int *h);
/**
- * \brief Create a texture for a rendering context.
- *
- * \param renderer The renderer.
- * \param format The format of the texture.
- * \param access One of the enumerated values in ::SDL_TextureAccess.
- * \param w The width of the texture in pixels.
- * \param h The height of the texture in pixels.
+ * Create a texture for a rendering context.
*
- * \return The created texture is returned, or NULL if no rendering context was
- * active, the format was unsupported, or the width or height were out
- * of range.
+ * You can set the texture scaling method by setting
+ * `SDL_HINT_RENDER_SCALE_QUALITY` before creating the texture.
*
- * \note The contents of the texture are not defined at creation.
+ * \param renderer the rendering context
+ * \param format one of the enumerated values in SDL_PixelFormatEnum
+ * \param access one of the enumerated values in SDL_TextureAccess
+ * \param w the width of the texture in pixels
+ * \param h the height of the texture in pixels
+ * \returns a pointer to the created texture or NULL if no rendering context
+ * was active, the format was unsupported, or the width or height
+ * were out of range; call SDL_GetError() for more information.
*
- * \sa SDL_QueryTexture()
- * \sa SDL_UpdateTexture()
- * \sa SDL_DestroyTexture()
+ * \sa SDL_CreateTextureFromSurface
+ * \sa SDL_DestroyTexture
+ * \sa SDL_QueryTexture
+ * \sa SDL_UpdateTexture
*/
extern DECLSPEC SDL_Texture * SDLCALL SDL_CreateTexture(SDL_Renderer * renderer,
Uint32 format,
@@ -255,194 +302,243 @@ extern DECLSPEC SDL_Texture * SDLCALL SDL_CreateTexture(SDL_Renderer * renderer,
int h);
/**
- * \brief Create a texture from an existing surface.
+ * Create a texture from an existing surface.
*
- * \param renderer The renderer.
- * \param surface The surface containing pixel data used to fill the texture.
+ * The surface is not modified or freed by this function.
*
- * \return The created texture is returned, or NULL on error.
+ * The SDL_TextureAccess hint for the created texture is
+ * `SDL_TEXTUREACCESS_STATIC`.
*
- * \note The surface is not modified or freed by this function.
+ * The pixel format of the created texture may be different from the pixel
+ * format of the surface. Use SDL_QueryTexture() to query the pixel format of
+ * the texture.
*
- * \sa SDL_QueryTexture()
- * \sa SDL_DestroyTexture()
+ * \param renderer the rendering context
+ * \param surface the SDL_Surface structure containing pixel data used to fill
+ * the texture
+ * \returns the created texture or NULL on failure; call SDL_GetError() for
+ * more information.
+ *
+ * \sa SDL_CreateTexture
+ * \sa SDL_DestroyTexture
+ * \sa SDL_QueryTexture
*/
extern DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureFromSurface(SDL_Renderer * renderer, SDL_Surface * surface);
/**
- * \brief Query the attributes of a texture
+ * Query the attributes of a texture.
*
- * \param texture A texture to be queried.
- * \param format A pointer filled in with the raw format of the texture. The
- * actual format may differ, but pixel transfers will use this
- * format.
- * \param access A pointer filled in with the actual access to the texture.
- * \param w A pointer filled in with the width of the texture in pixels.
- * \param h A pointer filled in with the height of the texture in pixels.
+ * \param texture the texture to query
+ * \param format a pointer filled in with the raw format of the texture; the
+ * actual format may differ, but pixel transfers will use this
+ * format (one of the SDL_PixelFormatEnum values)
+ * \param access a pointer filled in with the actual access to the texture
+ * (one of the SDL_TextureAccess values)
+ * \param w a pointer filled in with the width of the texture in pixels
+ * \param h a pointer filled in with the height of the texture in pixels
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \return 0 on success, or -1 if the texture is not valid.
+ * \sa SDL_CreateTexture
*/
extern DECLSPEC int SDLCALL SDL_QueryTexture(SDL_Texture * texture,
Uint32 * format, int *access,
int *w, int *h);
/**
- * \brief Set an additional color value used in render copy operations.
+ * Set an additional color value multiplied into render copy operations.
+ *
+ * When this texture is rendered, during the copy operation each source color
+ * channel is modulated by the appropriate color value according to the
+ * following formula:
*
- * \param texture The texture to update.
- * \param r The red color value multiplied into copy operations.
- * \param g The green color value multiplied into copy operations.
- * \param b The blue color value multiplied into copy operations.
+ * `srcC = srcC * (color / 255)`
*
- * \return 0 on success, or -1 if the texture is not valid or color modulation
- * is not supported.
+ * Color modulation is not always supported by the renderer; it will return -1
+ * if color modulation is not supported.
*
- * \sa SDL_GetTextureColorMod()
+ * \param texture the texture to update
+ * \param r the red color value multiplied into copy operations
+ * \param g the green color value multiplied into copy operations
+ * \param b the blue color value multiplied into copy operations
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_GetTextureColorMod
+ * \sa SDL_SetTextureAlphaMod
*/
extern DECLSPEC int SDLCALL SDL_SetTextureColorMod(SDL_Texture * texture,
Uint8 r, Uint8 g, Uint8 b);
/**
- * \brief Get the additional color value used in render copy operations.
- *
- * \param texture The texture to query.
- * \param r A pointer filled in with the current red color value.
- * \param g A pointer filled in with the current green color value.
- * \param b A pointer filled in with the current blue color value.
+ * Get the additional color value multiplied into render copy operations.
*
- * \return 0 on success, or -1 if the texture is not valid.
+ * \param texture the texture to query
+ * \param r a pointer filled in with the current red color value
+ * \param g a pointer filled in with the current green color value
+ * \param b a pointer filled in with the current blue color value
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_SetTextureColorMod()
+ * \sa SDL_GetTextureAlphaMod
+ * \sa SDL_SetTextureColorMod
*/
extern DECLSPEC int SDLCALL SDL_GetTextureColorMod(SDL_Texture * texture,
Uint8 * r, Uint8 * g,
Uint8 * b);
/**
- * \brief Set an additional alpha value used in render copy operations.
+ * Set an additional alpha value multiplied into render copy operations.
*
- * \param texture The texture to update.
- * \param alpha The alpha value multiplied into copy operations.
+ * When this texture is rendered, during the copy operation the source alpha
+ * value is modulated by this alpha value according to the following formula:
*
- * \return 0 on success, or -1 if the texture is not valid or alpha modulation
- * is not supported.
+ * `srcA = srcA * (alpha / 255)`
*
- * \sa SDL_GetTextureAlphaMod()
+ * Alpha modulation is not always supported by the renderer; it will return -1
+ * if alpha modulation is not supported.
+ *
+ * \param texture the texture to update
+ * \param alpha the source alpha value multiplied into copy operations
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_GetTextureAlphaMod
+ * \sa SDL_SetTextureColorMod
*/
extern DECLSPEC int SDLCALL SDL_SetTextureAlphaMod(SDL_Texture * texture,
Uint8 alpha);
/**
- * \brief Get the additional alpha value used in render copy operations.
- *
- * \param texture The texture to query.
- * \param alpha A pointer filled in with the current alpha value.
+ * Get the additional alpha value multiplied into render
+ * copy operations.
*
- * \return 0 on success, or -1 if the texture is not valid.
+ * \param texture the texture to query
+ * \param alpha a pointer filled in with the current alpha value
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_SetTextureAlphaMod()
+ * \sa SDL_GetTextureColorMod
+ * \sa SDL_SetTextureAlphaMod
*/
extern DECLSPEC int SDLCALL SDL_GetTextureAlphaMod(SDL_Texture * texture,
Uint8 * alpha);
/**
- * \brief Set the blend mode used for texture copy operations.
+ * Set the blend mode for a texture, used by
+ * SDL_RenderCopy().
*
- * \param texture The texture to update.
- * \param blendMode ::SDL_BlendMode to use for texture blending.
+ * If the blend mode is not supported, the closest supported mode is chosen
+ * and this function returns -1.
*
- * \return 0 on success, or -1 if the texture is not valid or the blend mode is
- * not supported.
+ * \param texture the texture to update
+ * \param blendMode the SDL_BlendMode to use for texture blending
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \note If the blend mode is not supported, the closest supported mode is
- * chosen.
- *
- * \sa SDL_GetTextureBlendMode()
+ * \sa SDL_GetTextureBlendMode
+ * \sa SDL_RenderCopy
*/
extern DECLSPEC int SDLCALL SDL_SetTextureBlendMode(SDL_Texture * texture,
SDL_BlendMode blendMode);
/**
- * \brief Get the blend mode used for texture copy operations.
- *
- * \param texture The texture to query.
- * \param blendMode A pointer filled in with the current blend mode.
+ * Get the blend mode used for texture copy operations.
*
- * \return 0 on success, or -1 if the texture is not valid.
+ * \param texture the texture to query
+ * \param blendMode a pointer filled in with the current SDL_BlendMode
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_SetTextureBlendMode()
+ * \sa SDL_SetTextureBlendMode
*/
extern DECLSPEC int SDLCALL SDL_GetTextureBlendMode(SDL_Texture * texture,
SDL_BlendMode *blendMode);
/**
- * \brief Set the scale mode used for texture scale operations.
+ * Set the scale mode used for texture scale operations.
*
- * \param texture The texture to update.
- * \param scaleMode ::SDL_ScaleMode to use for texture scaling.
+ * If the scale mode is not supported, the closest supported mode is chosen.
*
- * \return 0 on success, or -1 if the texture is not valid.
+ * \param texture The texture to update.
+ * \param scaleMode the SDL_ScaleMode to use for texture scaling.
+ * \returns 0 on success, or -1 if the texture is not valid.
*
- * \note If the scale mode is not supported, the closest supported mode is
- * chosen.
- *
- * \sa SDL_GetTextureScaleMode()
+ * \sa SDL_GetTextureScaleMode()
*/
extern DECLSPEC int SDLCALL SDL_SetTextureScaleMode(SDL_Texture * texture,
SDL_ScaleMode scaleMode);
/**
- * \brief Get the scale mode used for texture scale operations.
- *
- * \param texture The texture to query.
- * \param scaleMode A pointer filled in with the current scale mode.
+ * Get the scale mode used for texture scale operations.
*
- * \return 0 on success, or -1 if the texture is not valid.
+ * \param texture the texture to query.
+ * \param scaleMode a pointer filled in with the current scale mode.
+ * \return 0 on success, or -1 if the texture is not valid.
*
- * \sa SDL_SetTextureScaleMode()
+ * \sa SDL_SetTextureScaleMode()
*/
extern DECLSPEC int SDLCALL SDL_GetTextureScaleMode(SDL_Texture * texture,
SDL_ScaleMode *scaleMode);
/**
- * \brief Update the given texture rectangle with new pixel data.
+ * Update the given texture rectangle with new pixel data.
*
- * \param texture The texture to update
- * \param rect A pointer to the rectangle of pixels to update, or NULL to
- * update the entire texture.
- * \param pixels The raw pixel data in the format of the texture.
- * \param pitch The number of bytes in a row of pixel data, including padding between lines.
+ * The pixel data must be in the pixel format of the texture. Use
+ * SDL_QueryTexture() to query the pixel format of the texture.
*
- * The pixel data must be in the format of the texture. The pixel format can be
- * queried with SDL_QueryTexture.
+ * This is a fairly slow function, intended for use with static textures that
+ * do not change often.
*
- * \return 0 on success, or -1 if the texture is not valid.
+ * If the texture is intended to be updated often, it is preferred to create
+ * the texture as streaming and use the locking functions referenced below.
+ * While this function will work with streaming textures, for optimization
+ * reasons you may not get the pixels back if you lock the texture afterward.
*
- * \note This is a fairly slow function.
+ * \param texture the texture to update
+ * \param rect an SDL_Rect structure representing the area to update, or NULL
+ * to update the entire texture
+ * \param pixels the raw pixel data in the format of the texture
+ * \param pitch the number of bytes in a row of pixel data, including padding
+ * between lines
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_CreateTexture
+ * \sa SDL_LockTexture
+ * \sa SDL_UnlockTexture
*/
extern DECLSPEC int SDLCALL SDL_UpdateTexture(SDL_Texture * texture,
const SDL_Rect * rect,
const void *pixels, int pitch);
/**
- * \brief Update a rectangle within a planar YV12 or IYUV texture with new pixel data.
+ * Update a rectangle within a planar YV12 or IYUV
+ * texture with new pixel data.
+ *
+ * You can use SDL_UpdateTexture() as long as your pixel data is a contiguous
+ * block of Y and U/V planes in the proper order, but this function is
+ * available if your pixel data is not contiguous.
*
- * \param texture The texture to update
- * \param rect A pointer to the rectangle of pixels to update, or NULL to
- * update the entire texture.
- * \param Yplane The raw pixel data for the Y plane.
- * \param Ypitch The number of bytes between rows of pixel data for the Y plane.
- * \param Uplane The raw pixel data for the U plane.
- * \param Upitch The number of bytes between rows of pixel data for the U plane.
- * \param Vplane The raw pixel data for the V plane.
- * \param Vpitch The number of bytes between rows of pixel data for the V plane.
+ * \param texture the texture to update
+ * \param rect a pointer to the rectangle of pixels to update, or NULL to
+ * update the entire texture
+ * \param Yplane the raw pixel data for the Y plane
+ * \param Ypitch the number of bytes between rows of pixel data for the Y
+ * plane
+ * \param Uplane the raw pixel data for the U plane
+ * \param Upitch the number of bytes between rows of pixel data for the U
+ * plane
+ * \param Vplane the raw pixel data for the V plane
+ * \param Vpitch the number of bytes between rows of pixel data for the V
+ * plane
+ * \returns 0 on success or -1 if the texture is not valid; call
+ * SDL_GetError() for more information.
*
- * \return 0 on success, or -1 if the texture is not valid.
+ * \since This function is available since SDL 2.0.1.
*
- * \note You can use SDL_UpdateTexture() as long as your pixel data is
- * a contiguous block of Y and U/V planes in the proper order, but
- * this function is available if your pixel data is not contiguous.
+ * \sa SDL_UpdateTexture
*/
extern DECLSPEC int SDLCALL SDL_UpdateYUVTexture(SDL_Texture * texture,
const SDL_Rect * rect,
@@ -451,21 +547,20 @@ extern DECLSPEC int SDLCALL SDL_UpdateYUVTexture(SDL_Texture * texture,
const Uint8 *Vplane, int Vpitch);
/**
- * \brief Update a rectangle within a planar NV12 or NV21 texture with new pixel data.
- *
- * \param texture The texture to update
- * \param rect A pointer to the rectangle of pixels to update, or NULL to
- * update the entire texture.
- * \param Yplane The raw pixel data for the Y plane.
- * \param Ypitch The number of bytes between rows of pixel data for the Y plane.
- * \param UVplane The raw pixel data for the UV plane.
- * \param UVpitch The number of bytes between rows of pixel data for the UV plane.
+ * Update a rectangle within a planar NV12 or NV21 texture with new pixels.
*
- * \return 0 on success, or -1 if the texture is not valid.
+ * You can use SDL_UpdateTexture() as long as your pixel data is a contiguous
+ * block of NV12/21 planes in the proper order, but this function is available
+ * if your pixel data is not contiguous.
*
- * \note You can use SDL_UpdateTexture() as long as your pixel data is
- * a contiguous block of NV12/21 planes in the proper order, but
- * this function is available if your pixel data is not contiguous.
+ * \param texture the texture to update
+ * \param rect a pointer to the rectangle of pixels to update, or NULL to
+ * update the entire texture.
+ * \param Yplane the raw pixel data for the Y plane.
+ * \param Ypitch the number of bytes between rows of pixel data for the Y plane.
+ * \param UVplane the raw pixel data for the UV plane.
+ * \param UVpitch the number of bytes between rows of pixel data for the UV plane.
+ * \return 0 on success, or -1 if the texture is not valid.
*/
extern DECLSPEC int SDLCALL SDL_UpdateNVTexture(SDL_Texture * texture,
const SDL_Rect * rect,
@@ -473,421 +568,662 @@ extern DECLSPEC int SDLCALL SDL_UpdateNVTexture(SDL_Texture * texture,
const Uint8 *UVplane, int UVpitch);
/**
- * \brief Lock a portion of the texture for write-only pixel access.
+ * Lock a portion of the texture for **write-only** pixel access.
*
- * \param texture The texture to lock for access, which was created with
- * ::SDL_TEXTUREACCESS_STREAMING.
- * \param rect A pointer to the rectangle to lock for access. If the rect
- * is NULL, the entire texture will be locked.
- * \param pixels This is filled in with a pointer to the locked pixels,
- * appropriately offset by the locked area.
- * \param pitch This is filled in with the pitch of the locked pixels.
+ * As an optimization, the pixels made available for editing don't necessarily
+ * contain the old texture data. This is a write-only operation, and if you
+ * need to keep a copy of the texture data you should do that at the
+ * application level.
*
- * \return 0 on success, or -1 if the texture is not valid or was not created with ::SDL_TEXTUREACCESS_STREAMING.
+ * You must use SDL_UnlockTexture() to unlock the pixels and apply any
+ * changes.
*
- * \sa SDL_UnlockTexture()
+ * \param texture the texture to lock for access, which was created with
+ * `SDL_TEXTUREACCESS_STREAMING`
+ * \param rect an SDL_Rect structure representing the area to lock for access;
+ * NULL to lock the entire texture
+ * \param pixels this is filled in with a pointer to the locked pixels,
+ * appropriately offset by the locked area
+ * \param pitch this is filled in with the pitch of the locked pixels; the
+ * pitch is the length of one row in bytes
+ * \returns 0 on success or a negative error code if the texture is not valid
+ * or was not created with `SDL_TEXTUREACCESS_STREAMING`; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_UnlockTexture
*/
extern DECLSPEC int SDLCALL SDL_LockTexture(SDL_Texture * texture,
const SDL_Rect * rect,
void **pixels, int *pitch);
/**
- * \brief Lock a portion of the texture for write-only pixel access.
- * Expose it as a SDL surface.
+ * Lock a portion of the texture for **write-only** pixel access, and expose
+ * it as a SDL surface.
+ *
+ * Besides providing an SDL_Surface instead of raw pixel data, this function
+ * operates like SDL_LockTexture.
+ *
+ * As an optimization, the pixels made available for editing don't necessarily
+ * contain the old texture data. This is a write-only operation, and if you
+ * need to keep a copy of the texture data you should do that at the
+ * application level.
+ *
+ * You must use SDL_UnlockTexture() to unlock the pixels and apply any
+ * changes.
*
- * \param texture The texture to lock for access, which was created with
- * ::SDL_TEXTUREACCESS_STREAMING.
- * \param rect A pointer to the rectangle to lock for access. If the rect
- * is NULL, the entire texture will be locked.
- * \param surface This is filled in with a SDL surface representing the locked area
- * Surface is freed internally after calling SDL_UnlockTexture or SDL_DestroyTexture.
+ * The returned surface is freed internally after calling SDL_UnlockTexture()
+ * or SDL_DestroyTexture(). The caller should not free it.
*
- * \return 0 on success, or -1 if the texture is not valid or was not created with ::SDL_TEXTUREACCESS_STREAMING.
+ * \param texture the texture to lock for access, which was created with
+ * `SDL_TEXTUREACCESS_STREAMING`
+ * \param rect a pointer to the rectangle to lock for access. If the rect is
+ * NULL, the entire texture will be locked
+ * \param surface this is filled in with an SDL surface representing the
+ * locked area
+ * \returns 0 on success, or -1 if the texture is not valid or was not created
+ * with `SDL_TEXTUREACCESS_STREAMING`
*
- * \sa SDL_UnlockTexture()
+ * \sa SDL_LockTexture()
+ * \sa SDL_UnlockTexture()
*/
extern DECLSPEC int SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture,
const SDL_Rect *rect,
SDL_Surface **surface);
/**
- * \brief Unlock a texture, uploading the changes to video memory, if needed.
- * If SDL_LockTextureToSurface() was called for locking, the SDL surface is freed.
+ * Unlock a texture, uploading the changes to video memory, if needed.
+ *
+ * **Warning**: Please note that SDL_LockTexture() is intended to be
+ * write-only; it will notguarantee the previous contents of the texture will
+ * be provided. You must fully initialize any area of a texture that you lock
+ * before unlocking it, as the pixels might otherwise be uninitialized memory.
+ *
+ * Which is to say: locking and immediately unlocking a texture can result
+ * in corrupted textures, depending on the renderer in use.
+ *
+ * \param texture a texture locked by SDL_LockTexture()
*
- * \sa SDL_LockTexture()
- * \sa SDL_LockTextureToSurface()
+ * \sa SDL_LockTexture
*/
extern DECLSPEC void SDLCALL SDL_UnlockTexture(SDL_Texture * texture);
/**
- * \brief Determines whether a window supports the use of render targets
+ * Determine whether a renderer supports the use of render targets.
*
- * \param renderer The renderer that will be checked
+ * \param renderer the renderer that will be checked
+ * \returns SDL_TRUE if supported or SDL_FALSE if not.
*
- * \return SDL_TRUE if supported, SDL_FALSE if not.
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_SetRenderTarget
*/
extern DECLSPEC SDL_bool SDLCALL SDL_RenderTargetSupported(SDL_Renderer *renderer);
/**
- * \brief Set a texture as the current rendering target.
+ * Set a texture as the current rendering target.
*
- * \param renderer The renderer.
- * \param texture The targeted texture, which must be created with the SDL_TEXTUREACCESS_TARGET flag, or NULL for the default render target
+ * Before using this function, you should check the
+ * `SDL_RENDERER_TARGETTEXTURE` bit in the flags of SDL_RendererInfo to see
+ * if render targets are supported.
*
- * \return 0 on success, or -1 on error
+ * The default render target is the window for which the renderer was created.
+ * To stop rendering to a texture and render to the window again, call this
+ * function with a NULL `texture`.
+ *
+ * \param renderer the rendering context
+ * \param texture the targeted texture, which must be created with the
+ * `SDL_TEXTUREACCESS_TARGET` flag, or NULL
+ * to render to the window instead of a texture.
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
*
- * \sa SDL_GetRenderTarget()
+ * \sa SDL_GetRenderTarget
*/
extern DECLSPEC int SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer,
SDL_Texture *texture);
/**
- * \brief Get the current render target or NULL for the default render target.
+ * Get the current render target.
*
- * \return The current render target
+ * The default render target is the window for which the renderer was created,
+ * and is reported a NULL here.
*
- * \sa SDL_SetRenderTarget()
+ * \param renderer the rendering context
+ * \returns the current render target or NULL for the default render target.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_SetRenderTarget
*/
extern DECLSPEC SDL_Texture * SDLCALL SDL_GetRenderTarget(SDL_Renderer *renderer);
/**
- * \brief Set device independent resolution for rendering
+ * Set a device independent resolution for rendering.
+ *
+ * This function uses the viewport and scaling functionality to allow a fixed
+ * logical resolution for rendering, regardless of the actual output
+ * resolution. If the actual output resolution doesn't have the same aspect
+ * ratio the output rendering will be centered within the output display.
*
- * \param renderer The renderer for which resolution should be set.
- * \param w The width of the logical resolution
- * \param h The height of the logical resolution
+ * If the output display is a window, mouse and touch events in the window
+ * will be filtered and scaled so they seem to arrive within the logical
+ * resolution.
*
- * This function uses the viewport and scaling functionality to allow a fixed logical
- * resolution for rendering, regardless of the actual output resolution. If the actual
- * output resolution doesn't have the same aspect ratio the output rendering will be
- * centered within the output display.
+ * If this function results in scaling or subpixel drawing by the rendering
+ * backend, it will be handled using the appropriate quality hints.
*
- * If the output display is a window, mouse events in the window will be filtered
- * and scaled so they seem to arrive within the logical resolution.
+ * \param renderer the renderer for which resolution should be set
+ * \param w the width of the logical resolution
+ * \param h the height of the logical resolution
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \note If this function results in scaling or subpixel drawing by the
- * rendering backend, it will be handled using the appropriate
- * quality hints.
+ * \since This function is available since SDL 2.0.0.
*
- * \sa SDL_RenderGetLogicalSize()
- * \sa SDL_RenderSetScale()
- * \sa SDL_RenderSetViewport()
+ * \sa SDL_RenderGetLogicalSize
*/
extern DECLSPEC int SDLCALL SDL_RenderSetLogicalSize(SDL_Renderer * renderer, int w, int h);
/**
- * \brief Get device independent resolution for rendering
+ * Get device independent resolution for rendering.
*
- * \param renderer The renderer from which resolution should be queried.
- * \param w A pointer filled with the width of the logical resolution
- * \param h A pointer filled with the height of the logical resolution
+ * This may return 0 for `w` and `h` if the SDL_Renderer has never had its
+ * logical size set by SDL_RenderSetLogicalSize() and never had a render
+ * target set.
*
- * \sa SDL_RenderSetLogicalSize()
+ * \param renderer a rendering context
+ * \param w an int to be filled with the width
+ * \param h an int to be filled with the height
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_RenderSetLogicalSize
*/
extern DECLSPEC void SDLCALL SDL_RenderGetLogicalSize(SDL_Renderer * renderer, int *w, int *h);
/**
- * \brief Set whether to force integer scales for resolution-independent rendering
+ * Set whether to force integer scales for resolution-independent rendering.
*
- * \param renderer The renderer for which integer scaling should be set.
- * \param enable Enable or disable integer scaling
+ * This function restricts the logical viewport to integer values - that is,
+ * when a resolution is between two multiples of a logical size, the viewport
+ * size is rounded down to the lower multiple.
*
- * This function restricts the logical viewport to integer values - that is, when
- * a resolution is between two multiples of a logical size, the viewport size is
- * rounded down to the lower multiple.
+ * \param renderer the renderer for which integer scaling should be set
+ * \param enable enable or disable the integer scaling for rendering
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_RenderSetLogicalSize()
+ * \since This function is available since SDL 2.0.5.
+ *
+ * \sa SDL_RenderGetIntegerScale
+ * \sa SDL_RenderSetLogicalSize
*/
extern DECLSPEC int SDLCALL SDL_RenderSetIntegerScale(SDL_Renderer * renderer,
SDL_bool enable);
/**
- * \brief Get whether integer scales are forced for resolution-independent rendering
+ * Get whether integer scales are forced for resolution-independent rendering.
+ *
+ * \param renderer the renderer from which integer scaling should be queried
+ * \returns SDL_TRUE if integer scales are forced or SDL_FALSE if not and on
+ * failure; call SDL_GetError() for more information.
*
- * \param renderer The renderer from which integer scaling should be queried.
+ * \since This function is available since SDL 2.0.5.
*
- * \sa SDL_RenderSetIntegerScale()
+ * \sa SDL_RenderSetIntegerScale
*/
extern DECLSPEC SDL_bool SDLCALL SDL_RenderGetIntegerScale(SDL_Renderer * renderer);
/**
- * \brief Set the drawing area for rendering on the current target.
+ * Set the drawing area for rendering on the current target.
*
- * \param renderer The renderer for which the drawing area should be set.
- * \param rect The rectangle representing the drawing area, or NULL to set the viewport to the entire target.
+ * When the window is resized, the viewport is reset to fill the entire
+ * new window size.
*
- * The x,y of the viewport rect represents the origin for rendering.
+ * \param renderer the rendering context
+ * \param rect the SDL_Rect structure representing the drawing area, or NULL
+ * to set the viewport to the entire target
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \return 0 on success, or -1 on error
- *
- * \note If the window associated with the renderer is resized, the viewport is automatically reset.
- *
- * \sa SDL_RenderGetViewport()
- * \sa SDL_RenderSetLogicalSize()
+ * \sa SDL_RenderGetViewport
*/
extern DECLSPEC int SDLCALL SDL_RenderSetViewport(SDL_Renderer * renderer,
const SDL_Rect * rect);
/**
- * \brief Get the drawing area for the current target.
+ * Get the drawing area for the current target.
+ *
+ * \param renderer the rendering context
+ * \param rect an SDL_Rect structure filled in with the current drawing area
*
- * \sa SDL_RenderSetViewport()
+ * \sa SDL_RenderSetViewport
*/
extern DECLSPEC void SDLCALL SDL_RenderGetViewport(SDL_Renderer * renderer,
SDL_Rect * rect);
/**
- * \brief Set the clip rectangle for the current target.
+ * Set the clip rectangle for rendering on the specified target.
*
- * \param renderer The renderer for which clip rectangle should be set.
- * \param rect A pointer to the rectangle to set as the clip rectangle,
- * relative to the viewport, or NULL to disable clipping.
+ * \param renderer the rendering context for which clip rectangle should be
+ * set
+ * \param rect an SDL_Rect structure representing the clip area, relative to
+ * the viewport, or NULL to disable clipping
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \return 0 on success, or -1 on error
- *
- * \sa SDL_RenderGetClipRect()
+ * \sa SDL_RenderGetClipRect
+ * \sa SDL_RenderIsClipEnabled
*/
extern DECLSPEC int SDLCALL SDL_RenderSetClipRect(SDL_Renderer * renderer,
const SDL_Rect * rect);
/**
- * \brief Get the clip rectangle for the current target.
+ * Get the clip rectangle for the current target.
*
- * \param renderer The renderer from which clip rectangle should be queried.
- * \param rect A pointer filled in with the current clip rectangle, or
- * an empty rectangle if clipping is disabled.
+ * \param renderer the rendering context from which clip rectangle should be
+ * queried
+ * \param rect an SDL_Rect structure filled in with the current clipping area
+ * or an empty rectangle if clipping is disabled
*
- * \sa SDL_RenderSetClipRect()
+ * \sa SDL_RenderIsClipEnabled
+ * \sa SDL_RenderSetClipRect
*/
extern DECLSPEC void SDLCALL SDL_RenderGetClipRect(SDL_Renderer * renderer,
SDL_Rect * rect);
/**
- * \brief Get whether clipping is enabled on the given renderer.
+ * Get whether clipping is enabled on the given renderer.
+ *
+ * \param renderer the renderer from which clip state should be queried
+ * \returns SDL_TRUE if clipping is enabled or SDL_FALSE if not; call
+ * SDL_GetError() for more information.
*
- * \param renderer The renderer from which clip state should be queried.
+ * \since This function is available since SDL 2.0.4.
*
- * \sa SDL_RenderGetClipRect()
+ * \sa SDL_RenderGetClipRect
+ * \sa SDL_RenderSetClipRect
*/
extern DECLSPEC SDL_bool SDLCALL SDL_RenderIsClipEnabled(SDL_Renderer * renderer);
/**
- * \brief Set the drawing scale for rendering on the current target.
+ * Set the drawing scale for rendering on the current target.
+ *
+ * The drawing coordinates are scaled by the x/y scaling factors before they
+ * are used by the renderer. This allows resolution independent drawing with a
+ * single coordinate system.
*
- * \param renderer The renderer for which the drawing scale should be set.
- * \param scaleX The horizontal scaling factor
- * \param scaleY The vertical scaling factor
+ * If this results in scaling or subpixel drawing by the rendering backend, it
+ * will be handled using the appropriate quality hints. For best results use
+ * integer scaling factors.
*
- * The drawing coordinates are scaled by the x/y scaling factors
- * before they are used by the renderer. This allows resolution
- * independent drawing with a single coordinate system.
+ * \param renderer a rendering context
+ * \param scaleX the horizontal scaling factor
+ * \param scaleY the vertical scaling factor
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \note If this results in scaling or subpixel drawing by the
- * rendering backend, it will be handled using the appropriate
- * quality hints. For best results use integer scaling factors.
+ * \since This function is available since SDL 2.0.0.
*
- * \sa SDL_RenderGetScale()
- * \sa SDL_RenderSetLogicalSize()
+ * \sa SDL_RenderGetScale
+ * \sa SDL_RenderSetLogicalSize
*/
extern DECLSPEC int SDLCALL SDL_RenderSetScale(SDL_Renderer * renderer,
float scaleX, float scaleY);
/**
- * \brief Get the drawing scale for the current target.
+ * Get the drawing scale for the current target.
*
- * \param renderer The renderer from which drawing scale should be queried.
- * \param scaleX A pointer filled in with the horizontal scaling factor
- * \param scaleY A pointer filled in with the vertical scaling factor
+ * \param renderer the renderer from which drawing scale should be queried
+ * \param scaleX a pointer filled in with the horizontal scaling factor
+ * \param scaleY a pointer filled in with the vertical scaling factor
*
- * \sa SDL_RenderSetScale()
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_RenderSetScale
*/
extern DECLSPEC void SDLCALL SDL_RenderGetScale(SDL_Renderer * renderer,
float *scaleX, float *scaleY);
/**
- * \brief Set the color used for drawing operations (Rect, Line and Clear).
- *
- * \param renderer The renderer for which drawing color should be set.
- * \param r The red value used to draw on the rendering target.
- * \param g The green value used to draw on the rendering target.
- * \param b The blue value used to draw on the rendering target.
- * \param a The alpha value used to draw on the rendering target, usually
- * ::SDL_ALPHA_OPAQUE (255).
- *
- * \return 0 on success, or -1 on error
+ * Set the color used for drawing operations (Rect, Line and Clear).
+ *
+ * Set the color for drawing or filling rectangles, lines, and points,
+ * and for SDL_RenderClear().
+ *
+ * \param renderer the rendering context
+ * \param r the red value used to draw on the rendering target
+ * \param g the green value used to draw on the rendering target
+ * \param b the blue value used to draw on the rendering target
+ * \param a the alpha value used to draw on the rendering target; usually
+ * `SDL_ALPHA_OPAQUE` (255). Use SDL_SetRenderDrawBlendMode to
+ * specify how the alpha channel is used
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_GetRenderDrawColor
+ * \sa SDL_RenderClear
+ * \sa SDL_RenderDrawLine
+ * \sa SDL_RenderDrawLines
+ * \sa SDL_RenderDrawPoint
+ * \sa SDL_RenderDrawPoints
+ * \sa SDL_RenderDrawRect
+ * \sa SDL_RenderDrawRects
+ * \sa SDL_RenderFillRect
+ * \sa SDL_RenderFillRects
*/
extern DECLSPEC int SDLCALL SDL_SetRenderDrawColor(SDL_Renderer * renderer,
Uint8 r, Uint8 g, Uint8 b,
Uint8 a);
/**
- * \brief Get the color used for drawing operations (Rect, Line and Clear).
+ * Get the color used for drawing operations (Rect, Line and Clear).
*
- * \param renderer The renderer from which drawing color should be queried.
- * \param r A pointer to the red value used to draw on the rendering target.
- * \param g A pointer to the green value used to draw on the rendering target.
- * \param b A pointer to the blue value used to draw on the rendering target.
- * \param a A pointer to the alpha value used to draw on the rendering target,
- * usually ::SDL_ALPHA_OPAQUE (255).
+ * \param renderer the rendering context
+ * \param r a pointer filled in with the red value used to draw on the
+ * rendering target
+ * \param g a pointer filled in with the green value used to draw on the
+ * rendering target
+ * \param b a pointer filled in with the blue value used to draw on the
+ * rendering target
+ * \param a a pointer filled in with the alpha value used to draw on the
+ * rendering target; usually `SDL_ALPHA_OPAQUE` (255)
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \return 0 on success, or -1 on error
+ * \sa SDL_SetRenderDrawColor
*/
extern DECLSPEC int SDLCALL SDL_GetRenderDrawColor(SDL_Renderer * renderer,
Uint8 * r, Uint8 * g, Uint8 * b,
Uint8 * a);
/**
- * \brief Set the blend mode used for drawing operations (Fill and Line).
+ * Set the blend mode used for drawing operations (Fill and Line).
*
- * \param renderer The renderer for which blend mode should be set.
- * \param blendMode ::SDL_BlendMode to use for blending.
+ * If the blend mode is not supported, the closest supported mode is chosen.
*
- * \return 0 on success, or -1 on error
+ * \param renderer the rendering context
+ * \param blendMode the SDL_BlendMode to use for blending
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \note If the blend mode is not supported, the closest supported mode is
- * chosen.
- *
- * \sa SDL_GetRenderDrawBlendMode()
+ * \sa SDL_GetRenderDrawBlendMode
+ * \sa SDL_RenderDrawLine
+ * \sa SDL_RenderDrawLines
+ * \sa SDL_RenderDrawPoint
+ * \sa SDL_RenderDrawPoints
+ * \sa SDL_RenderDrawRect
+ * \sa SDL_RenderDrawRects
+ * \sa SDL_RenderFillRect
+ * \sa SDL_RenderFillRects
*/
extern DECLSPEC int SDLCALL SDL_SetRenderDrawBlendMode(SDL_Renderer * renderer,
SDL_BlendMode blendMode);
/**
- * \brief Get the blend mode used for drawing operations.
- *
- * \param renderer The renderer from which blend mode should be queried.
- * \param blendMode A pointer filled in with the current blend mode.
+ * Get the blend mode used for drawing operations.
*
- * \return 0 on success, or -1 on error
+ * \param renderer the rendering context
+ * \param blendMode a pointer filled in with the current SDL_BlendMode
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_SetRenderDrawBlendMode()
+ * \sa SDL_SetRenderDrawBlendMode
*/
extern DECLSPEC int SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer * renderer,
SDL_BlendMode *blendMode);
/**
- * \brief Clear the current rendering target with the drawing color
+ * Clear the current rendering target with the drawing color.
+ *
+ * This function clears the entire rendering target, ignoring the viewport and
+ * the clip rectangle.
+ *
+ * \param renderer the rendering context
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * This function clears the entire rendering target, ignoring the viewport and
- * the clip rectangle.
+ * \since This function is available since SDL 2.0.0.
*
- * \return 0 on success, or -1 on error
+ * \sa SDL_SetRenderDrawColor
*/
extern DECLSPEC int SDLCALL SDL_RenderClear(SDL_Renderer * renderer);
/**
- * \brief Draw a point on the current rendering target.
+ * Draw a point on the current rendering target.
*
- * \param renderer The renderer which should draw a point.
- * \param x The x coordinate of the point.
- * \param y The y coordinate of the point.
+ * SDL_RenderDrawPoint() draws a single point. If you want to draw multiple,
+ * use SDL_RenderDrawPoints() instead.
*
- * \return 0 on success, or -1 on error
+ * \param renderer the rendering context
+ * \param x the x coordinate of the point
+ * \param y the y coordinate of the point
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_RenderDrawLine
+ * \sa SDL_RenderDrawLines
+ * \sa SDL_RenderDrawPoints
+ * \sa SDL_RenderDrawRect
+ * \sa SDL_RenderDrawRects
+ * \sa SDL_RenderFillRect
+ * \sa SDL_RenderFillRects
+ * \sa SDL_RenderPresent
+ * \sa SDL_SetRenderDrawBlendMode
+ * \sa SDL_SetRenderDrawColor
*/
extern DECLSPEC int SDLCALL SDL_RenderDrawPoint(SDL_Renderer * renderer,
int x, int y);
/**
- * \brief Draw multiple points on the current rendering target.
+ * Draw multiple points on the current rendering target.
*
- * \param renderer The renderer which should draw multiple points.
- * \param points The points to draw
- * \param count The number of points to draw
+ * \param renderer the rendering context
+ * \param points an array of SDL_Point structures that represent the points to
+ * draw
+ * \param count the number of points to draw
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \return 0 on success, or -1 on error
+ * \sa SDL_RenderDrawLine
+ * \sa SDL_RenderDrawLines
+ * \sa SDL_RenderDrawPoint
+ * \sa SDL_RenderDrawRect
+ * \sa SDL_RenderDrawRects
+ * \sa SDL_RenderFillRect
+ * \sa SDL_RenderFillRects
+ * \sa SDL_RenderPresent
+ * \sa SDL_SetRenderDrawBlendMode
+ * \sa SDL_SetRenderDrawColor
*/
extern DECLSPEC int SDLCALL SDL_RenderDrawPoints(SDL_Renderer * renderer,
const SDL_Point * points,
int count);
/**
- * \brief Draw a line on the current rendering target.
+ * Draw a line on the current rendering target.
+ *
+ * SDL_RenderDrawLine() draws the line to include both end points. If you want
+ * to draw multiple, connecting lines use SDL_RenderDrawLines() instead.
+ *
+ * \param renderer the rendering context
+ * \param x1 the x coordinate of the start point
+ * \param y1 the y coordinate of the start point
+ * \param x2 the x coordinate of the end point
+ * \param y2 the y coordinate of the end point
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \param renderer The renderer which should draw a line.
- * \param x1 The x coordinate of the start point.
- * \param y1 The y coordinate of the start point.
- * \param x2 The x coordinate of the end point.
- * \param y2 The y coordinate of the end point.
+ * \since This function is available since SDL 2.0.0.
*
- * \return 0 on success, or -1 on error
+ * \sa SDL_RenderDrawLines
+ * \sa SDL_RenderDrawPoint
+ * \sa SDL_RenderDrawPoints
+ * \sa SDL_RenderDrawRect
+ * \sa SDL_RenderDrawRects
+ * \sa SDL_RenderFillRect
+ * \sa SDL_RenderFillRects
+ * \sa SDL_RenderPresent
+ * \sa SDL_SetRenderDrawBlendMode
+ * \sa SDL_SetRenderDrawColor
*/
extern DECLSPEC int SDLCALL SDL_RenderDrawLine(SDL_Renderer * renderer,
int x1, int y1, int x2, int y2);
/**
- * \brief Draw a series of connected lines on the current rendering target.
+ * Draw a series of connected lines on the current rendering target.
*
- * \param renderer The renderer which should draw multiple lines.
- * \param points The points along the lines
- * \param count The number of points, drawing count-1 lines
+ * \param renderer the rendering context
+ * \param points an array of SDL_Point structures representing points along
+ * the lines
+ * \param count the number of points, drawing count-1 lines
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \return 0 on success, or -1 on error
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_RenderDrawLine
+ * \sa SDL_RenderDrawPoint
+ * \sa SDL_RenderDrawPoints
+ * \sa SDL_RenderDrawRect
+ * \sa SDL_RenderDrawRects
+ * \sa SDL_RenderFillRect
+ * \sa SDL_RenderFillRects
+ * \sa SDL_RenderPresent
+ * \sa SDL_SetRenderDrawBlendMode
+ * \sa SDL_SetRenderDrawColor
*/
extern DECLSPEC int SDLCALL SDL_RenderDrawLines(SDL_Renderer * renderer,
const SDL_Point * points,
int count);
/**
- * \brief Draw a rectangle on the current rendering target.
+ * Draw a rectangle on the current rendering target.
*
- * \param renderer The renderer which should draw a rectangle.
- * \param rect A pointer to the destination rectangle, or NULL to outline the entire rendering target.
+ * \param renderer the rendering context
+ * \param rect an SDL_Rect structure representing the rectangle to draw, or
+ * NULL to outline the entire rendering target
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \return 0 on success, or -1 on error
+ * \sa SDL_RenderDrawLine
+ * \sa SDL_RenderDrawLines
+ * \sa SDL_RenderDrawPoint
+ * \sa SDL_RenderDrawPoints
+ * \sa SDL_RenderDrawRects
+ * \sa SDL_RenderFillRect
+ * \sa SDL_RenderFillRects
+ * \sa SDL_RenderPresent
+ * \sa SDL_SetRenderDrawBlendMode
+ * \sa SDL_SetRenderDrawColor
*/
extern DECLSPEC int SDLCALL SDL_RenderDrawRect(SDL_Renderer * renderer,
const SDL_Rect * rect);
/**
- * \brief Draw some number of rectangles on the current rendering target.
+ * Draw some number of rectangles on the current rendering target.
*
- * \param renderer The renderer which should draw multiple rectangles.
- * \param rects A pointer to an array of destination rectangles.
- * \param count The number of rectangles.
+ * \param renderer the rendering context
+ * \param rects an array of SDL_Rect structures representing the rectangles to
+ * be drawn
+ * \param count the number of rectangles
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \return 0 on success, or -1 on error
+ * \sa SDL_RenderDrawLine
+ * \sa SDL_RenderDrawLines
+ * \sa SDL_RenderDrawPoint
+ * \sa SDL_RenderDrawPoints
+ * \sa SDL_RenderDrawRect
+ * \sa SDL_RenderFillRect
+ * \sa SDL_RenderFillRects
+ * \sa SDL_RenderPresent
+ * \sa SDL_SetRenderDrawBlendMode
+ * \sa SDL_SetRenderDrawColor
*/
extern DECLSPEC int SDLCALL SDL_RenderDrawRects(SDL_Renderer * renderer,
const SDL_Rect * rects,
int count);
/**
- * \brief Fill a rectangle on the current rendering target with the drawing color.
+ * Fill a rectangle on the current rendering target with the drawing color.
+ *
+ * The current drawing color is set by SDL_SetRenderDrawColor(), and the
+ * color's alpha value is ignored unless blending is enabled with the
+ * appropriate call to SDL_SetRenderDrawBlendMode().
*
- * \param renderer The renderer which should fill a rectangle.
- * \param rect A pointer to the destination rectangle, or NULL for the entire
- * rendering target.
+ * \param renderer the rendering context
+ * \param rect the SDL_Rect structure representing the rectangle to fill, or
+ * NULL for the entire rendering target
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \return 0 on success, or -1 on error
+ * \sa SDL_RenderDrawLine
+ * \sa SDL_RenderDrawLines
+ * \sa SDL_RenderDrawPoint
+ * \sa SDL_RenderDrawPoints
+ * \sa SDL_RenderDrawRect
+ * \sa SDL_RenderDrawRects
+ * \sa SDL_RenderFillRects
+ * \sa SDL_RenderPresent
+ * \sa SDL_SetRenderDrawBlendMode
+ * \sa SDL_SetRenderDrawColor
*/
extern DECLSPEC int SDLCALL SDL_RenderFillRect(SDL_Renderer * renderer,
const SDL_Rect * rect);
/**
- * \brief Fill some number of rectangles on the current rendering target with the drawing color.
+ * Fill some number of rectangles on the current rendering target with the
+ * drawing color.
*
- * \param renderer The renderer which should fill multiple rectangles.
- * \param rects A pointer to an array of destination rectangles.
- * \param count The number of rectangles.
+ * \param renderer the rendering context
+ * \param rects an array of SDL_Rect structures representing the rectangles to
+ * be filled
+ * \param count the number of rectangles
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \return 0 on success, or -1 on error
+ * \sa SDL_RenderDrawLine
+ * \sa SDL_RenderDrawLines
+ * \sa SDL_RenderDrawPoint
+ * \sa SDL_RenderDrawPoints
+ * \sa SDL_RenderDrawRect
+ * \sa SDL_RenderDrawRects
+ * \sa SDL_RenderFillRect
+ * \sa SDL_RenderPresent
*/
extern DECLSPEC int SDLCALL SDL_RenderFillRects(SDL_Renderer * renderer,
const SDL_Rect * rects,
int count);
/**
- * \brief Copy a portion of the texture to the current rendering target.
+ * Copy a portion of the texture to the current rendering target.
+ *
+ * The texture is blended with the destination based on its blend mode set
+ * with SDL_SetTextureBlendMode().
+ *
+ * The texture color is affected based on its color modulation set by
+ * SDL_SetTextureColorMod().
*
- * \param renderer The renderer which should copy parts of a texture.
- * \param texture The source texture.
- * \param srcrect A pointer to the source rectangle, or NULL for the entire
- * texture.
- * \param dstrect A pointer to the destination rectangle, or NULL for the
- * entire rendering target.
+ * The texture alpha is affected based on its alpha modulation set by
+ * SDL_SetTextureAlphaMod().
*
- * \return 0 on success, or -1 on error
+ * \param renderer the rendering context
+ * \param texture the source texture
+ * \param srcrect the source SDL_Rect structure or NULL for the entire texture
+ * \param dstrect the destination SDL_Rect structure or NULL for the entire
+ * rendering target; the texture will be stretched to fill the
+ * given rectangle
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_RenderCopyEx
+ * \sa SDL_SetTextureAlphaMod
+ * \sa SDL_SetTextureBlendMode
+ * \sa SDL_SetTextureColorMod
*/
extern DECLSPEC int SDLCALL SDL_RenderCopy(SDL_Renderer * renderer,
SDL_Texture * texture,
@@ -895,19 +1231,41 @@ extern DECLSPEC int SDLCALL SDL_RenderCopy(SDL_Renderer * renderer,
const SDL_Rect * dstrect);
/**
- * \brief Copy a portion of the source texture to the current rendering target, rotating it by angle around the given center
+ * Copy a portion of the texture to the current rendering, with optional
+ * rotation and flipping.
+ *
+ * Copy a portion of the texture to the current rendering
+ * target, optionally rotating it by angle around the given center and also
+ * flipping it top-bottom and/or left-right.
+ *
+ * The texture is blended with the destination based on its blend mode set
+ * with SDL_SetTextureBlendMode().
*
- * \param renderer The renderer which should copy parts of a texture.
- * \param texture The source texture.
- * \param srcrect A pointer to the source rectangle, or NULL for the entire
- * texture.
- * \param dstrect A pointer to the destination rectangle, or NULL for the
- * entire rendering target.
- * \param angle An angle in degrees that indicates the rotation that will be applied to dstrect, rotating it in a clockwise direction
- * \param center A pointer to a point indicating the point around which dstrect will be rotated (if NULL, rotation will be done around dstrect.w/2, dstrect.h/2).
- * \param flip An SDL_RendererFlip value stating which flipping actions should be performed on the texture
+ * The texture color is affected based on its color modulation set by
+ * SDL_SetTextureColorMod().
*
- * \return 0 on success, or -1 on error
+ * The texture alpha is affected based on its alpha modulation set by
+ * SDL_SetTextureAlphaMod().
+ *
+ * \param renderer the rendering context
+ * \param texture the source texture
+ * \param srcrect the source SDL_Rect structure or NULL for the entire texture
+ * \param dstrect the destination SDL_Rect structure or NULL for the entire
+ * rendering target
+ * \param angle an angle in degrees that indicates the rotation that will be
+ * applied to dstrect, rotating it in a clockwise direction
+ * \param center a pointer to a point indicating the point around which
+ * dstrect will be rotated (if NULL, rotation will be done
+ * around `dstrect.w / 2`, `dstrect.h / 2`)
+ * \param flip a SDL_RendererFlip value stating which flipping actions should
+ * be performed on the texture
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_RenderCopy
+ * \sa SDL_SetTextureAlphaMod
+ * \sa SDL_SetTextureBlendMode
+ * \sa SDL_SetTextureColorMod
*/
extern DECLSPEC int SDLCALL SDL_RenderCopyEx(SDL_Renderer * renderer,
SDL_Texture * texture,
@@ -919,117 +1277,113 @@ extern DECLSPEC int SDLCALL SDL_RenderCopyEx(SDL_Renderer * renderer,
/**
- * \brief Draw a point on the current rendering target.
+ * Draw a point on the current rendering target at subpixel precision.
*
- * \param renderer The renderer which should draw a point.
- * \param x The x coordinate of the point.
- * \param y The y coordinate of the point.
- *
- * \return 0 on success, or -1 on error
+ * \param renderer The renderer which should draw a point.
+ * \param x The x coordinate of the point.
+ * \param y The y coordinate of the point.
+ * \return 0 on success, or -1 on error
*/
extern DECLSPEC int SDLCALL SDL_RenderDrawPointF(SDL_Renderer * renderer,
float x, float y);
/**
- * \brief Draw multiple points on the current rendering target.
+ * Draw multiple points on the current rendering target at subpixel precision.
*
- * \param renderer The renderer which should draw multiple points.
- * \param points The points to draw
- * \param count The number of points to draw
- *
- * \return 0 on success, or -1 on error
+ * \param renderer The renderer which should draw multiple points.
+ * \param points The points to draw
+ * \param count The number of points to draw
+ * \return 0 on success, or -1 on error
*/
extern DECLSPEC int SDLCALL SDL_RenderDrawPointsF(SDL_Renderer * renderer,
const SDL_FPoint * points,
int count);
/**
- * \brief Draw a line on the current rendering target.
- *
- * \param renderer The renderer which should draw a line.
- * \param x1 The x coordinate of the start point.
- * \param y1 The y coordinate of the start point.
- * \param x2 The x coordinate of the end point.
- * \param y2 The y coordinate of the end point.
+ * Draw a line on the current rendering target at subpixel precision.
*
- * \return 0 on success, or -1 on error
+ * \param renderer The renderer which should draw a line.
+ * \param x1 The x coordinate of the start point.
+ * \param y1 The y coordinate of the start point.
+ * \param x2 The x coordinate of the end point.
+ * \param y2 The y coordinate of the end point.
+ * \return 0 on success, or -1 on error
*/
extern DECLSPEC int SDLCALL SDL_RenderDrawLineF(SDL_Renderer * renderer,
float x1, float y1, float x2, float y2);
/**
- * \brief Draw a series of connected lines on the current rendering target.
- *
- * \param renderer The renderer which should draw multiple lines.
- * \param points The points along the lines
- * \param count The number of points, drawing count-1 lines
+ * Draw a series of connected lines on the current rendering target at
+ * subpixel precision.
*
- * \return 0 on success, or -1 on error
+ * \param renderer The renderer which should draw multiple lines.
+ * \param points The points along the lines
+ * \param count The number of points, drawing count-1 lines
+ * \return 0 on success, or -1 on error
*/
extern DECLSPEC int SDLCALL SDL_RenderDrawLinesF(SDL_Renderer * renderer,
- const SDL_FPoint * points,
- int count);
+ const SDL_FPoint * points,
+ int count);
/**
- * \brief Draw a rectangle on the current rendering target.
- *
- * \param renderer The renderer which should draw a rectangle.
- * \param rect A pointer to the destination rectangle, or NULL to outline the entire rendering target.
+ * Draw a rectangle on the current rendering target at subpixel precision.
*
- * \return 0 on success, or -1 on error
+ * \param renderer The renderer which should draw a rectangle.
+ * \param rect A pointer to the destination rectangle, or NULL to outline the entire rendering target.
+ * \return 0 on success, or -1 on error
*/
extern DECLSPEC int SDLCALL SDL_RenderDrawRectF(SDL_Renderer * renderer,
- const SDL_FRect * rect);
+ const SDL_FRect * rect);
/**
- * \brief Draw some number of rectangles on the current rendering target.
+ * Draw some number of rectangles on the current rendering target at subpixel
+ * precision.
*
- * \param renderer The renderer which should draw multiple rectangles.
- * \param rects A pointer to an array of destination rectangles.
- * \param count The number of rectangles.
- *
- * \return 0 on success, or -1 on error
+ * \param renderer The renderer which should draw multiple rectangles.
+ * \param rects A pointer to an array of destination rectangles.
+ * \param count The number of rectangles.
+ * \return 0 on success, or -1 on error
*/
extern DECLSPEC int SDLCALL SDL_RenderDrawRectsF(SDL_Renderer * renderer,
const SDL_FRect * rects,
int count);
/**
- * \brief Fill a rectangle on the current rendering target with the drawing color.
+ * Fill a rectangle on the current rendering target with the drawing color
+ * at subpixel precision.
*
- * \param renderer The renderer which should fill a rectangle.
- * \param rect A pointer to the destination rectangle, or NULL for the entire
- * rendering target.
- *
- * \return 0 on success, or -1 on error
+ * \param renderer The renderer which should fill a rectangle.
+ * \param rect A pointer to the destination rectangle, or NULL for the entire
+ * rendering target.
+ * \return 0 on success, or -1 on error
*/
extern DECLSPEC int SDLCALL SDL_RenderFillRectF(SDL_Renderer * renderer,
const SDL_FRect * rect);
/**
- * \brief Fill some number of rectangles on the current rendering target with the drawing color.
- *
- * \param renderer The renderer which should fill multiple rectangles.
- * \param rects A pointer to an array of destination rectangles.
- * \param count The number of rectangles.
+ * Fill some number of rectangles on the current rendering target with the
+ * drawing color at subpixel precision.
*
- * \return 0 on success, or -1 on error
+ * \param renderer The renderer which should fill multiple rectangles.
+ * \param rects A pointer to an array of destination rectangles.
+ * \param count The number of rectangles.
+ * \return 0 on success, or -1 on error
*/
extern DECLSPEC int SDLCALL SDL_RenderFillRectsF(SDL_Renderer * renderer,
const SDL_FRect * rects,
int count);
/**
- * \brief Copy a portion of the texture to the current rendering target.
- *
- * \param renderer The renderer which should copy parts of a texture.
- * \param texture The source texture.
- * \param srcrect A pointer to the source rectangle, or NULL for the entire
- * texture.
- * \param dstrect A pointer to the destination rectangle, or NULL for the
- * entire rendering target.
+ * Copy a portion of the texture to the current rendering target at subpixel
+ * precision.
*
- * \return 0 on success, or -1 on error
+ * \param renderer The renderer which should copy parts of a texture.
+ * \param texture The source texture.
+ * \param srcrect A pointer to the source rectangle, or NULL for the entire
+ * texture.
+ * \param dstrect A pointer to the destination rectangle, or NULL for the
+ * entire rendering target.
+ * \return 0 on success, or -1 on error
*/
extern DECLSPEC int SDLCALL SDL_RenderCopyF(SDL_Renderer * renderer,
SDL_Texture * texture,
@@ -1037,19 +1391,20 @@ extern DECLSPEC int SDLCALL SDL_RenderCopyF(SDL_Renderer * renderer,
const SDL_FRect * dstrect);
/**
- * \brief Copy a portion of the source texture to the current rendering target, rotating it by angle around the given center
+ * Copy a portion of the source texture to the current rendering target,
+ * with rotation and flipping, at subpixel precision.
*
- * \param renderer The renderer which should copy parts of a texture.
- * \param texture The source texture.
- * \param srcrect A pointer to the source rectangle, or NULL for the entire
- * texture.
- * \param dstrect A pointer to the destination rectangle, or NULL for the
- * entire rendering target.
- * \param angle An angle in degrees that indicates the rotation that will be applied to dstrect, rotating it in a clockwise direction
- * \param center A pointer to a point indicating the point around which dstrect will be rotated (if NULL, rotation will be done around dstrect.w/2, dstrect.h/2).
- * \param flip An SDL_RendererFlip value stating which flipping actions should be performed on the texture
+ * \param renderer The renderer which should copy parts of a texture.
+ * \param texture The source texture.
+ * \param srcrect A pointer to the source rectangle, or NULL for the entire
+ * texture.
+ * \param dstrect A pointer to the destination rectangle, or NULL for the
+ * entire rendering target.
+ * \param angle An angle in degrees that indicates the rotation that will be applied to dstrect, rotating it in a clockwise direction
+ * \param center A pointer to a point indicating the point around which dstrect will be rotated (if NULL, rotation will be done around dstrect.w/2, dstrect.h/2).
+ * \param flip An SDL_RendererFlip value stating which flipping actions should be performed on the texture
*
- * \return 0 on success, or -1 on error
+ * \return 0 on success, or -1 on error
*/
extern DECLSPEC int SDLCALL SDL_RenderCopyExF(SDL_Renderer * renderer,
SDL_Texture * texture,
@@ -1060,19 +1415,27 @@ extern DECLSPEC int SDLCALL SDL_RenderCopyExF(SDL_Renderer * renderer,
const SDL_RendererFlip flip);
/**
- * \brief Read pixels from the current rendering target.
+ * Read pixels from the current rendering target to an array of pixels.
*
- * \param renderer The renderer from which pixels should be read.
- * \param rect A pointer to the rectangle to read, or NULL for the entire
- * render target.
- * \param format The desired format of the pixel data, or 0 to use the format
- * of the rendering target
- * \param pixels A pointer to be filled in with the pixel data
- * \param pitch The pitch of the pixels parameter.
+ * **WARNING**: This is a very slow operation, and should not be used
+ * frequently.
*
- * \return 0 on success, or -1 if pixel reading is not supported.
+ * `pitch` specifies the number of bytes between rows in the destination
+ * `pixels data. This allows you to write to a subrectangle or have padded
+ * rows in the destination. Generally, `pitch` should equal the number of
+ * pixels per row in the `pixels` data times the number of bytes per pixel,
+ * but it might contain additional padding (for example, 24bit RGB Windows
+ * Bitmap data pads all rows to multiples of 4 bytes).
*
- * \warning This is a very slow operation, and should not be used frequently.
+ * \param renderer the rendering context
+ * \param rect an SDL_Rect structure representing the area to read, or NULL
+ * for the entire render target
+ * \param format an SDL_PixelFormatEnum value of the desired format of the
+ * pixel data, or 0 to use the format of the rendering target
+ * \param pixels a pointer to the pixel data to copy into
+ * \param pitch the pitch of the `pixels` parameter
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*/
extern DECLSPEC int SDLCALL SDL_RenderReadPixels(SDL_Renderer * renderer,
const SDL_Rect * rect,
@@ -1080,90 +1443,168 @@ extern DECLSPEC int SDLCALL SDL_RenderReadPixels(SDL_Renderer * renderer,
void *pixels, int pitch);
/**
- * \brief Update the screen with rendering performed.
+ * Update the screen with any rendering performed since
+ * the previous call.
+ *
+ * SDL's rendering functions operate on a backbuffer; that is, calling a
+ * rendering function such as SDL_RenderDrawLine() does not directly put a
+ * line on the screen, but rather updates the backbuffer. As such, you compose
+ * your entire scene and *present* the composed backbuffer to the screen as a
+ * complete picture.
+ *
+ * Therefore, when using SDL's rendering API, one does all drawing intended
+ * for the frame, and then calls this function once per frame to present the
+ * final drawing to the user.
+ *
+ * The backbuffer should be considered invalidated after each present; do not
+ * assume that previous contents will exist between frames. You are strongly
+ * encouraged to call SDL_RenderClear() to initialize the backbuffer before
+ * starting each new frame's drawing, even if you plan to overwrite every
+ * pixel.
+ *
+ * \param renderer the rendering context
+ *
+ * \sa SDL_RenderClear
+ * \sa SDL_RenderDrawLine
+ * \sa SDL_RenderDrawLines
+ * \sa SDL_RenderDrawPoint
+ * \sa SDL_RenderDrawPoints
+ * \sa SDL_RenderDrawRect
+ * \sa SDL_RenderDrawRects
+ * \sa SDL_RenderFillRect
+ * \sa SDL_RenderFillRects
+ * \sa SDL_SetRenderDrawBlendMode
+ * \sa SDL_SetRenderDrawColor
*/
extern DECLSPEC void SDLCALL SDL_RenderPresent(SDL_Renderer * renderer);
/**
- * \brief Destroy the specified texture.
+ * Destroy the specified texture.
+ *
+ * Passing NULL or an otherwise invalid texture will set the SDL error message
+ * to "Invalid texture".
+ *
+ * \param texture the texture to destroy
*
- * \sa SDL_CreateTexture()
- * \sa SDL_CreateTextureFromSurface()
+ * \sa SDL_CreateTexture
+ * \sa SDL_CreateTextureFromSurface
*/
extern DECLSPEC void SDLCALL SDL_DestroyTexture(SDL_Texture * texture);
/**
- * \brief Destroy the rendering context for a window and free associated
- * textures.
+ * Destroy the rendering context for a window and free associated textures.
*
- * \sa SDL_CreateRenderer()
+ * \param renderer the rendering context
+ *
+ * \sa SDL_CreateRenderer
*/
extern DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_Renderer * renderer);
/**
- * \brief Force the rendering context to flush any pending commands to the
- * underlying rendering API.
+ * Force the rendering context to flush any pending commands to the underlying
+ * rendering API.
+ *
+ * You do not need to (and in fact, shouldn't) call this function unless
+ * you are planning to call into OpenGL/Direct3D/Metal/whatever directly
+ * in addition to using an SDL_Renderer.
+ *
+ * This is for a very-specific case: if you are using SDL's render API, you
+ * asked for a specific renderer backend (OpenGL, Direct3D, etc), you set
+ * SDL_HINT_RENDER_BATCHING to "1", and you plan to make OpenGL/D3D/whatever
+ * calls in addition to SDL render API calls. If all of this applies, you
+ * should call SDL_RenderFlush() between calls to SDL's render API and the
+ * low-level API you're using in cooperation.
*
- * You do not need to (and in fact, shouldn't) call this function unless
- * you are planning to call into OpenGL/Direct3D/Metal/whatever directly
- * in addition to using an SDL_Renderer.
+ * In all other cases, you can ignore this function. This is only here to get
+ * maximum performance out of a specific situation. In all other cases, SDL
+ * will do the right thing, perhaps at a performance loss.
*
- * This is for a very-specific case: if you are using SDL's render API,
- * you asked for a specific renderer backend (OpenGL, Direct3D, etc),
- * you set SDL_HINT_RENDER_BATCHING to "1", and you plan to make
- * OpenGL/D3D/whatever calls in addition to SDL render API calls. If all of
- * this applies, you should call SDL_RenderFlush() between calls to SDL's
- * render API and the low-level API you're using in cooperation.
+ * This function is first available in SDL 2.0.10, and is not needed in
+ * 2.0.9 and earlier, as earlier versions did not queue rendering commands
+ * at all, instead flushing them to the OS immediately.
*
- * In all other cases, you can ignore this function. This is only here to
- * get maximum performance out of a specific situation. In all other cases,
- * SDL will do the right thing, perhaps at a performance loss.
+ * \param renderer the rendering context
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * This function is first available in SDL 2.0.10, and is not needed in
- * 2.0.9 and earlier, as earlier versions did not queue rendering commands
- * at all, instead flushing them to the OS immediately.
+ * \since This function is available since SDL 2.0.10.
*/
extern DECLSPEC int SDLCALL SDL_RenderFlush(SDL_Renderer * renderer);
/**
- * \brief Bind the texture to the current OpenGL/ES/ES2 context for use with
- * OpenGL instructions.
+ * Bind an OpenGL/ES/ES2 texture to the current context.
*
- * \param texture The SDL texture to bind
- * \param texw A pointer to a float that will be filled with the texture width
- * \param texh A pointer to a float that will be filled with the texture height
+ * This is for use with OpenGL instructions when rendering OpenGL primitives
+ * directly.
*
- * \return 0 on success, or -1 if the operation is not supported
+ * If not NULL, `texw` and `texh` will be filled with the width and height
+ * values suitable for the provided texture. In most cases, both will be 1.0,
+ * however, on systems that support the GL_ARB_texture_rectangle extension,
+ * these values will actually be the pixel width and height used to create the
+ * texture, so this factor needs to be taken into account when providing
+ * texture coordinates to OpenGL.
+ *
+ * You need a renderer to create an SDL_Texture, therefore you can only use
+ * this function with an implicit OpenGL context from SDL_CreateRenderer(),
+ * not with your own OpenGL context. If you need control over your OpenGL
+ * context, you need to write your own texture-loading methods.
+ *
+ * Also note that SDL may upload RGB textures as BGR (or vice-versa), and
+ * re-order the color channels in the shaders phase, so the uploaded texture
+ * may have swapped color channels.
+ *
+ * \param texture the texture to bind to the current OpenGL/ES/ES2 context
+ * \param texw a pointer to a float value which will be filled with the
+ * texture width or NULL if you don't need that value
+ * \param texh a pointer to a float value which will be filled with the
+ * texture height or NULL if you don't need that value
+ * \returns 0 on success, or -1 if the operation is not supported; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GL_MakeCurrent
+ * \sa SDL_GL_UnbindTexture
*/
extern DECLSPEC int SDLCALL SDL_GL_BindTexture(SDL_Texture *texture, float *texw, float *texh);
/**
- * \brief Unbind a texture from the current OpenGL/ES/ES2 context.
+ * Unbind an OpenGL/ES/ES2 texture from the current context.
+ *
+ * See SDL_GL_BindTexture() for examples on how to use these functions
*
- * \param texture The SDL texture to unbind
+ * \param texture the texture to unbind from the current OpenGL/ES/ES2 context
+ * \returns 0 on success, or -1 if the operation is not supported
*
- * \return 0 on success, or -1 if the operation is not supported
+ * \sa SDL_GL_BindTexture
+ * \sa SDL_GL_MakeCurrent
*/
extern DECLSPEC int SDLCALL SDL_GL_UnbindTexture(SDL_Texture *texture);
/**
- * \brief Get the CAMetalLayer associated with the given Metal renderer
+ * Get the CAMetalLayer associated with the given Metal renderer.
*
- * \param renderer The renderer to query
+ * This function returns `void *`, so SDL doesn't have to include Metal's
+ * headers, but it can be safely cast to a `CAMetalLayer *`.
*
- * \return CAMetalLayer* on success, or NULL if the renderer isn't a Metal renderer
+ * \param renderer The renderer to query
+ * \returns CAMetalLayer* on success, or NULL if the renderer isn't a Metal
+ * renderer
*
- * \sa SDL_RenderGetMetalCommandEncoder()
+ * \sa SDL_RenderGetMetalCommandEncoder()
*/
extern DECLSPEC void *SDLCALL SDL_RenderGetMetalLayer(SDL_Renderer * renderer);
/**
- * \brief Get the Metal command encoder for the current frame
+ * Get the Metal command encoder for the current frame
*
- * \param renderer The renderer to query
+ * This function returns `void *`, so SDL doesn't have to include Metal's
+ * headers, but it can be safely cast to an `id<MTLRenderCommandEncoder>`.
*
- * \return id<MTLRenderCommandEncoder> on success, or NULL if the renderer isn't a Metal renderer
+ * \param renderer The renderer to query
+ * \returns `id<MTLRenderCommandEncoder>` on success, or NULL if the renderer
+ * isn't a Metal renderer.
*
* \sa SDL_RenderGetMetalLayer()
*/
diff --git a/include/SDL_rwops.h b/include/SDL_rwops.h
index e730807..88003e4 100644
--- a/include/SDL_rwops.h
+++ b/include/SDL_rwops.h
@@ -182,77 +182,194 @@ extern DECLSPEC void SDLCALL SDL_FreeRW(SDL_RWops * area);
#define RW_SEEK_END 2 /**< Seek relative to the end of data */
/**
- * Return the size of the file in this rwops, or -1 if unknown
+ * Use this macro to get the size of the data stream in an SDL_RWops.
+ *
+ * \param context the SDL_RWops to get the size of the data stream from
+ * \returns the size of the data stream in the SDL_RWops on success, -1 if
+ * unknown or a negative error code on failure; call SDL_GetError()
+ * for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
*/
extern DECLSPEC Sint64 SDLCALL SDL_RWsize(SDL_RWops *context);
/**
- * Seek to \c offset relative to \c whence, one of stdio's whence values:
- * RW_SEEK_SET, RW_SEEK_CUR, RW_SEEK_END
+ * Seek within an SDL_RWops data stream.
+ *
+ * This function seeks to byte `offset`, relative to `whence`.
+ *
+ * `whence` may be any of the following values:
+ *
+ * - `RW_SEEK_SET`: seek from the beginning of data
+ *
+ * - `RW_SEEK_CUR`: seek relative to current read point
+ *
+ * - `RW_SEEK_END`: seek relative to the end of data
*
- * \return the final offset in the data stream, or -1 on error.
+ * If this stream can not seek, it will return -1.
+ *
+ * SDL_RWseek() is actually a wrapper function that calls the SDL_RWops's
+ * `seek` method appropriately, to simplify application development.
+ *
+ * \param context a pointer to an SDL_RWops structure
+ * \param offset an offset in bytes, relative to **whence** location; can be
+ * negative
+ * \param whence any of `RW_SEEK_SET`, `RW_SEEK_CUR`, `RW_SEEK_END`
+ * \returns the final offset in the data stream after the seek or -1 on error.
+ *
+ * \sa SDL_RWclose
+ * \sa SDL_RWFromConstMem
+ * \sa SDL_RWFromFile
+ * \sa SDL_RWFromFP
+ * \sa SDL_RWFromMem
+ * \sa SDL_RWread
+ * \sa SDL_RWtell
+ * \sa SDL_RWwrite
*/
extern DECLSPEC Sint64 SDLCALL SDL_RWseek(SDL_RWops *context,
Sint64 offset, int whence);
/**
- * Return the current offset in the data stream, or -1 on error.
+ * Determine the current read/write offset in an SDL_RWops data stream.
+ *
+ * SDL_RWtell is actually a wrapper function that calls the SDL_RWops's
+ * `seek` method, with an offset of 0 bytes from `RW_SEEK_CUR`, to simplify
+ * application development.
+ *
+ * \param context a SDL_RWops data stream object from which to get the current
+ * offset
+ * \returns the current offset in the stream, or -1 if the information can not
+ * be determined.
+ *
+ * \sa SDL_RWclose
+ * \sa SDL_RWFromConstMem
+ * \sa SDL_RWFromFile
+ * \sa SDL_RWFromFP
+ * \sa SDL_RWFromMem
+ * \sa SDL_RWread
+ * \sa SDL_RWseek
+ * \sa SDL_RWwrite
*/
extern DECLSPEC Sint64 SDLCALL SDL_RWtell(SDL_RWops *context);
/**
- * Read up to \c maxnum objects each of size \c size from the data
- * stream to the area pointed at by \c ptr.
+ * Read from a data source.
+ *
+ * This function reads up to `maxnum` objects each of size `size` from the
+ * data source to the area pointed at by `ptr`. This function may read less
+ * objects than requested. It will return zero when there has been an error or
+ * the data stream is completely read.
*
- * \return the number of objects read, or 0 at error or end of file.
+ * SDL_RWread() is actually a function wrapper that calls the SDL_RWops's
+ * `read` method appropriately, to simplify application development.
+ *
+ * \param context a pointer to an SDL_RWops structure
+ * \param ptr a pointer to a buffer to read data into
+ * \param size the size of each object to read, in bytes
+ * \param maxnum the maximum number of objects to be read
+ * \returns the number of objects read, or 0 at error or end of file; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_RWclose
+ * \sa SDL_RWFromConstMem
+ * \sa SDL_RWFromFile
+ * \sa SDL_RWFromFP
+ * \sa SDL_RWFromMem
+ * \sa SDL_RWseek
+ * \sa SDL_RWwrite
*/
extern DECLSPEC size_t SDLCALL SDL_RWread(SDL_RWops *context,
- void *ptr, size_t size, size_t maxnum);
+ void *ptr, size_t size,
+ size_t maxnum);
/**
- * Write exactly \c num objects each of size \c size from the area
- * pointed at by \c ptr to data stream.
+ * Write to an SDL_RWops data stream.
+ *
+ * This function writes exactly `num` objects each of size `size` from the
+ * area pointed at by `ptr` to the stream. If this fails for any reason,
+ * it'll return less than `num` to demonstrate how far the write progressed.
+ * On success, it returns `num`.
+ *
+ * SDL_RWwrite is actually a function wrapper that calls the SDL_RWops's
+ * `write` method appropriately, to simplify application development.
*
- * \return the number of objects written, or 0 at error or end of file.
+ * \param context a pointer to an SDL_RWops structure
+ * \param ptr a pointer to a buffer containing data to write
+ * \param size the size of an object to write, in bytes
+ * \param num the number of objects to write
+ * \returns the number of objects written, which will be less than **num** on
+ * error; call SDL_GetError() for more information.
+ *
+ * \sa SDL_RWclose
+ * \sa SDL_RWFromConstMem
+ * \sa SDL_RWFromFile
+ * \sa SDL_RWFromFP
+ * \sa SDL_RWFromMem
+ * \sa SDL_RWread
+ * \sa SDL_RWseek
*/
extern DECLSPEC size_t SDLCALL SDL_RWwrite(SDL_RWops *context,
- const void *ptr, size_t size, size_t num);
+ const void *ptr, size_t size,
+ size_t num);
/**
- * Close and free an allocated SDL_RWops structure.
+ * Close and free an allocated SDL_RWops structure.
+ *
+ * SDL_RWclose() closes and cleans up the SDL_RWops stream. It releases any
+ * resources used by the stream and frees the SDL_RWops itself with
+ * SDL_FreeRW(). This returns 0 on success, or -1 if the stream failed to
+ * flush to its output (e.g. to disk).
+ *
+ * Note that if this fails to flush the stream to disk, this function reports
+ * an error, but the SDL_RWops is still invalid once this function returns.
*
- * \return 0 if successful or -1 on write error when flushing data.
+ * SDL_RWclose() is actually a macro that calls the SDL_RWops's `close`
+ * method appropriately, to simplify application development.
+ *
+ * \param context SDL_RWops structure to close
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_RWFromConstMem
+ * \sa SDL_RWFromFile
+ * \sa SDL_RWFromFP
+ * \sa SDL_RWFromMem
+ * \sa SDL_RWread
+ * \sa SDL_RWseek
+ * \sa SDL_RWwrite
*/
extern DECLSPEC int SDLCALL SDL_RWclose(SDL_RWops *context);
/**
- * Load all the data from an SDL data stream.
- *
- * The data is allocated with a zero byte at the end (null terminated)
+ * Load all the data from an SDL data stream.
*
- * If \c datasize is not NULL, it is filled with the size of the data read.
+ * The data is allocated with a zero byte at the end (null terminated) for
+ * convenience. This extra byte is not included in the value reported via
+ * `datasize`.
*
- * If \c freesrc is non-zero, the stream will be closed after being read.
+ * The data should be freed with SDL_free().
*
- * The data should be freed with SDL_free().
- *
- * \return the data, or NULL if there was an error.
+ * \param src the SDL_RWops to read all available data from
+ * \param datasize if not NULL, will store the number of bytes read
+ * \param freesrc if non-zero, calls SDL_RWclose() on `src` before returning
+ * \returns the data, or NULL if there was an error.
*/
-extern DECLSPEC void *SDLCALL SDL_LoadFile_RW(SDL_RWops * src, size_t *datasize,
- int freesrc);
+extern DECLSPEC void *SDLCALL SDL_LoadFile_RW(SDL_RWops *src,
+ size_t *datasize,
+ int freesrc);
/**
- * Load an entire file.
- *
- * The data is allocated with a zero byte at the end (null terminated)
- *
- * If \c datasize is not NULL, it is filled with the size of the data read.
+ * Load all the data from a file path.
*
- * If \c freesrc is non-zero, the stream will be closed after being read.
+ * The data is allocated with a zero byte at the end (null terminated) for
+ * convenience. This extra byte is not included in the value reported via
+ * `datasize`.
*
- * The data should be freed with SDL_free().
+ * The data should be freed with SDL_free().
*
- * \return the data, or NULL if there was an error.
+ * \param file the path to read all available data from
+ * \param datasize if not NULL, will store the number of bytes read
+ * \returns the data, or NULL if there was an error.
*/
extern DECLSPEC void *SDLCALL SDL_LoadFile(const char *file, size_t *datasize);
diff --git a/include/SDL_sensor.h b/include/SDL_sensor.h
index b89e687..6b2a330 100644
--- a/include/SDL_sensor.h
+++ b/include/SDL_sensor.h
@@ -138,118 +138,122 @@ extern DECLSPEC void SDLCALL SDL_LockSensors(void);
extern DECLSPEC void SDLCALL SDL_UnlockSensors(void);
/**
- * \brief Count the number of sensors attached to the system right now
+ * Count the number of sensors attached to the system right now.
+ *
+ * \returns The number of sensors detected.
*/
extern DECLSPEC int SDLCALL SDL_NumSensors(void);
/**
- * \brief Get the implementation dependent name of a sensor.
+ * Get the implementation dependent name of a sensor.
*
- * This can be called before any sensors are opened.
- *
- * \return The sensor name, or NULL if device_index is out of range.
+ * \param device_index The sensor to obtain name from
+ * \returns The sensor name, or NULL if `device_index` is out of range.
*/
extern DECLSPEC const char *SDLCALL SDL_SensorGetDeviceName(int device_index);
/**
- * \brief Get the type of a sensor.
- *
- * This can be called before any sensors are opened.
+ * Get the type of a sensor.
*
- * \return The sensor type, or SDL_SENSOR_INVALID if device_index is out of range.
+ * \param device_index The sensor to get the type from
+ * \returns The SDL_SensorType, or `SDL_SENSOR_INVALID` if `device_index` is
+ * out of range.
*/
extern DECLSPEC SDL_SensorType SDLCALL SDL_SensorGetDeviceType(int device_index);
/**
- * \brief Get the platform dependent type of a sensor.
+ * Get the platform dependent type of a sensor.
*
- * This can be called before any sensors are opened.
- *
- * \return The sensor platform dependent type, or -1 if device_index is out of range.
+ * \param device_index The sensor to check
+ * \returns The sensor platform dependent type, or -1 if `device_index` is out
+ * of range.
*/
extern DECLSPEC int SDLCALL SDL_SensorGetDeviceNonPortableType(int device_index);
/**
- * \brief Get the instance ID of a sensor.
- *
- * This can be called before any sensors are opened.
+ * Get the instance ID of a sensor.
*
- * \return The sensor instance ID, or -1 if device_index is out of range.
+ * \param device_index The sensor to get instance id from
+ * \returns The sensor instance ID, or -1 if `device_index` is out of range.
*/
extern DECLSPEC SDL_SensorID SDLCALL SDL_SensorGetDeviceInstanceID(int device_index);
/**
- * \brief Open a sensor for use.
- *
- * The index passed as an argument refers to the N'th sensor on the system.
+ * Open a sensor for use.
*
- * \return A sensor identifier, or NULL if an error occurred.
+ * \param device_index The sensor to open
+ * \returns An SDL_Sensor sensor object, or NULL if an error occurred.
*/
extern DECLSPEC SDL_Sensor *SDLCALL SDL_SensorOpen(int device_index);
/**
* Return the SDL_Sensor associated with an instance id.
+ *
+ * \param instance_id The sensor from instance id
+ * \returns An SDL_Sensor object.
*/
extern DECLSPEC SDL_Sensor *SDLCALL SDL_SensorFromInstanceID(SDL_SensorID instance_id);
/**
- * \brief Get the implementation dependent name of a sensor.
+ * Get the implementation dependent name of a sensor
*
- * \return The sensor name, or NULL if the sensor is NULL.
+ * \param sensor The SDL_Sensor object
+ * \returns The sensor name, or NULL if `sensor` is NULL.
*/
extern DECLSPEC const char *SDLCALL SDL_SensorGetName(SDL_Sensor *sensor);
/**
- * \brief Get the type of a sensor.
- *
- * This can be called before any sensors are opened.
+ * Get the type of a sensor.
*
- * \return The sensor type, or SDL_SENSOR_INVALID if the sensor is NULL.
+ * \param sensor The SDL_Sensor object to inspect
+ * \returns The SDL_SensorType type, or `SDL_SENSOR_INVALID` if `sensor` is
+ * NULL.
*/
extern DECLSPEC SDL_SensorType SDLCALL SDL_SensorGetType(SDL_Sensor *sensor);
/**
- * \brief Get the platform dependent type of a sensor.
- *
- * This can be called before any sensors are opened.
+ * Get the platform dependent type of a sensor.
*
- * \return The sensor platform dependent type, or -1 if the sensor is NULL.
+ * \param sensor The SDL_Sensor object to inspect
+ * \returns The sensor platform dependent type, or -1 if `sensor` is NULL.
*/
extern DECLSPEC int SDLCALL SDL_SensorGetNonPortableType(SDL_Sensor *sensor);
/**
- * \brief Get the instance ID of a sensor.
+ * Get the instance ID of a sensor.
*
- * This can be called before any sensors are opened.
- *
- * \return The sensor instance ID, or -1 if the sensor is NULL.
+ * \param sensor The SDL_Sensor object to inspect
+ * \returns The sensor instance ID, or -1 if `sensor` is NULL.
*/
extern DECLSPEC SDL_SensorID SDLCALL SDL_SensorGetInstanceID(SDL_Sensor *sensor);
/**
- * Get the current state of an opened sensor.
+ * Get the current state of an opened sensor.
*
* The number of values and interpretation of the data is sensor dependent.
*
- * \param sensor The sensor to query
- * \param data A pointer filled with the current sensor state
- * \param num_values The number of values to write to data
- *
- * \return 0 or -1 if an error occurred.
+ * \param sensor The SDL_Sensor object to query
+ * \param data A pointer filled with the current sensor state
+ * \param num_values The number of values to write to data
+ * \returns 0 or -1 if an error occurred.
*/
extern DECLSPEC int SDLCALL SDL_SensorGetData(SDL_Sensor * sensor, float *data, int num_values);
/**
- * Close a sensor previously opened with SDL_SensorOpen()
+ * Close a sensor previously opened with SDL_SensorOpen().
+ *
+ * \param sensor The SDL_Sensor object to close
*/
extern DECLSPEC void SDLCALL SDL_SensorClose(SDL_Sensor * sensor);
/**
- * Update the current state of the open sensors.
+ * Update the current state of the open sensors.
*
- * This is called automatically by the event loop if sensor events are enabled.
+ * This is called automatically by the event loop if sensor events are
+ * enabled.
*
- * This needs to be called from the thread that initialized the sensor subsystem.
+ * This needs to be called from the thread that initialized the sensor
+ * subsystem.
*/
extern DECLSPEC void SDLCALL SDL_SensorUpdate(void);
diff --git a/include/SDL_surface.h b/include/SDL_surface.h
index d9b1195..2051aba 100644
--- a/include/SDL_surface.h
+++ b/include/SDL_surface.h
@@ -112,31 +112,101 @@ typedef enum
} SDL_YUV_CONVERSION_MODE;
/**
- * Allocate and free an RGB surface.
+ * Allocate a new RGB surface.
*
- * If the depth is 4 or 8 bits, an empty palette is allocated for the surface.
- * If the depth is greater than 8 bits, the pixel format is set using the
- * flags '[RGB]mask'.
+ * If `depth` is 4 or 8 bits, an empty palette is allocated for the surface.
+ * If `depth` is greater than 8 bits, the pixel format is set using the
+ * [RGBA]mask parameters.
*
- * If the function runs out of memory, it will return NULL.
+ * The [RGBA]mask parameters are the bitmasks used to extract that color from
+ * a pixel. For instance, `Rmask` being 0xFF000000 means the red data is
+ * stored in the most significant byte. Using zeros for the RGB masks sets a
+ * default value, based on the depth. For example:
*
- * \param flags The \c flags are obsolete and should be set to 0.
- * \param width The width in pixels of the surface to create.
- * \param height The height in pixels of the surface to create.
- * \param depth The depth in bits of the surface to create.
- * \param Rmask The red mask of the surface to create.
- * \param Gmask The green mask of the surface to create.
- * \param Bmask The blue mask of the surface to create.
- * \param Amask The alpha mask of the surface to create.
+ * ```c++
+ * SDL_CreateRGBSurface(0,w,h,32,0,0,0,0);
+ * ```
+ *
+ * However, using zero for the Amask results in an Amask of 0.
+ *
+ * By default surfaces with an alpha mask are set up for blending as with:
+ *
+ * ```c++
+ * SDL_SetSurfaceBlendMode(surface, SDL_BLENDMODE_BLEND)
+ * ```
+ *
+ * You can change this by calling SDL_SetSurfaceBlendMode() and selecting a
+ * different `blendMode`.
+ *
+ * \param flags the flags are unused and should be set to 0
+ * \param width the width of the surface
+ * \param height the height of the surface
+ * \param depth the depth of the surface in bits
+ * \param Rmask the red mask for the pixels
+ * \param Gmask the green mask for the pixels
+ * \param Bmask the blue mask for the pixels
+ * \param Amask the alpha mask for the pixels
+ * \returns the new SDL_Surface structure that is created or NULL if it fails;
+ * call SDL_GetError() for more information.
+ *
+ * \sa SDL_CreateRGBSurfaceFrom
+ * \sa SDL_CreateRGBSurfaceWithFormat
+ * \sa SDL_FreeSurface
*/
extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurface
(Uint32 flags, int width, int height, int depth,
Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
+
/* !!! FIXME for 2.1: why does this ask for depth? Format provides that. */
+/**
+ * Allocate a new RGB surface with a specific pixel format.
+ *
+ * This function operates mostly like SDL_CreateRGBSurface(), except instead
+ * of providing pixel color masks, you provide it with a predefined format
+ * from SDL_PixelFormatEnum.
+ *
+ * \param flags the flags are unused and should be set to 0
+ * \param width the width of the surface
+ * \param height the height of the surface
+ * \param depth the depth of the surface in bits
+ * \param format the SDL_PixelFormatEnum for the new surface's pixel format.
+ * \returns the new SDL_Surface structure that is created or NULL if it fails;
+ * call SDL_GetError() for more information.
+ *
+ * \sa SDL_CreateRGBSurface
+ * \sa SDL_CreateRGBSurfaceFrom
+ * \sa SDL_FreeSurface
+ */
extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceWithFormat
(Uint32 flags, int width, int height, int depth, Uint32 format);
+/**
+ * Allocate a new RGB surface with existing pixel data.
+ *
+ * This function operates mostly like SDL_CreateRGBSurface(), except it does
+ * not allocate memory for the pixel data, instead the caller provides an
+ * existing buffer of data for the surface to use.
+ *
+ * No copy is made of the pixel data. Pixel data is not managed
+ * automatically; you must free the surface before you free the pixel data.
+ *
+ * \param pixels a pointer to existing pixel data
+ * \param width the width of the surface
+ * \param height the height of the surface
+ * \param depth the depth of the surface in bits
+ * \param pitch the pitch of the surface in bytes
+ * \param Rmask the red mask for the pixels
+ * \param Gmask the green mask for the pixels
+ * \param Bmask the blue mask for the pixels
+ * \param Amask the alpha mask for the pixels
+ * \returns the new SDL_Surface structure that is created or NULL if it fails;
+ * call SDL_GetError() for more information.
+ *
+ * \sa SDL_CreateRGBSurface
+ * \sa SDL_CreateRGBSurfaceWithFormat
+ * \sa SDL_FreeSurface
+ */
extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels,
int width,
int height,
@@ -146,74 +216,133 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels,
Uint32 Gmask,
Uint32 Bmask,
Uint32 Amask);
+
+/* !!! FIXME for 2.1: why does this ask for depth? Format provides that. */
+/**
+ * Allocate a new RGB surface with with a specific pixel format and existing
+ * pixel data.
+ *
+ * This function operates mostly like SDL_CreateRGBSurfaceFrom(), except
+ * instead of providing pixel color masks, you provide it with a predefined
+ * format from SDL_PixelFormatEnum.
+ *
+ * No copy is made of the pixel data. Pixel data is not managed
+ * automatically; you must free the surface before you free the pixel data.
+ *
+ * \param pixels a pointer to existing pixel data
+ * \param width the width of the surface
+ * \param height the height of the surface
+ * \param depth the depth of the surface in bits
+ * \param pitch the pitch of the surface in bytes
+ * \param format the SDL_PixelFormatEnum for the new surface's pixel format.
+ * \returns the new SDL_Surface structure that is created or NULL if it fails;
+ * call SDL_GetError() for more information.
+ *
+ * \sa SDL_CreateRGBSurfaceFrom
+ * \sa SDL_CreateRGBSurfaceWithFormat
+ * \sa SDL_FreeSurface
+ */
extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceWithFormatFrom
(void *pixels, int width, int height, int depth, int pitch, Uint32 format);
+
+/**
+ * Free an RGB surface.
+ *
+ * It is safe to pass NULL to this function.
+ *
+ * \param surface the SDL_Surface to free.
+ *
+ * \sa SDL_CreateRGBSurface
+ * \sa SDL_CreateRGBSurfaceFrom
+ * \sa SDL_LoadBMP
+ * \sa SDL_LoadBMP_RW
+ */
extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface * surface);
/**
- * \brief Set the palette used by a surface.
+ * Set the palette used by a surface.
*
- * \return 0, or -1 if the surface format doesn't use a palette.
+ * A single palette can be shared with many surfaces.
*
- * \note A single palette can be shared with many surfaces.
+ * \param surface the SDL_Surface structure to update
+ * \param palette the SDL_Palette structure to use
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*/
extern DECLSPEC int SDLCALL SDL_SetSurfacePalette(SDL_Surface * surface,
SDL_Palette * palette);
/**
- * \brief Sets up a surface for directly accessing the pixels.
+ * Set up a surface for directly accessing the pixels.
*
- * Between calls to SDL_LockSurface() / SDL_UnlockSurface(), you can write
- * to and read from \c surface->pixels, using the pixel format stored in
- * \c surface->format. Once you are done accessing the surface, you should
- * use SDL_UnlockSurface() to release it.
+ * Between calls to SDL_LockSurface() / SDL_UnlockSurface(), you can write to
+ * and read from `surface->pixels`, using the pixel format stored in
+ * `surface->format`. Once you are done accessing the surface, you should use
+ * SDL_UnlockSurface() to release it.
*
- * Not all surfaces require locking. If SDL_MUSTLOCK(surface) evaluates
- * to 0, then you can read and write to the surface at any time, and the
- * pixel format of the surface will not change.
+ * Not all surfaces require locking. If `SDL_MUSTLOCK(surface)` evaluates to
+ * 0, then you can read and write to the surface at any time, and the pixel
+ * format of the surface will not change.
*
- * No operating system or library calls should be made between lock/unlock
- * pairs, as critical system locks may be held during this time.
+ * \param surface the SDL_Surface structure to be locked
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * SDL_LockSurface() returns 0, or -1 if the surface couldn't be locked.
- *
- * \sa SDL_UnlockSurface()
+ * \sa SDL_MUSTLOCK
+ * \sa SDL_UnlockSurface
*/
extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface * surface);
-/** \sa SDL_LockSurface() */
+
+/**
+ * Release a surface after directly accessing the pixels.
+ *
+ * \param surface the SDL_Surface structure to be unlocked
+ *
+ * \sa SDL_LockSurface()
+ */
extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface * surface);
/**
- * Load a surface from a seekable SDL data stream (memory or file).
+ * Load a BMP image from a seekable SDL data stream.
*
- * If \c freesrc is non-zero, the stream will be closed after being read.
+ * The new surface should be freed with SDL_FreeSurface().
*
- * The new surface should be freed with SDL_FreeSurface().
+ * \param src the data stream for the surface
+ * \param freesrc non-zero to close the stream after being read
+ * \returns a pointer to a new SDL_Surface structure or NULL if there was an
+ * error; call SDL_GetError() for more information.
*
- * \return the new surface, or NULL if there was an error.
+ * \sa SDL_FreeSurface
+ * \sa SDL_LoadBMP
+ * \sa SDL_SaveBMP_RW
*/
extern DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_RW(SDL_RWops * src,
int freesrc);
/**
- * Load a surface from a file.
+ * Load a surface from a file.
*
- * Convenience macro.
+ * Convenience macro.
*/
#define SDL_LoadBMP(file) SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1)
/**
- * Save a surface to a seekable SDL data stream (memory or file).
+ * Save a surface to a seekable SDL data stream in BMP format.
*
- * Surfaces with a 24-bit, 32-bit and paletted 8-bit format get saved in the
- * BMP directly. Other RGB formats with 8-bit or higher get converted to a
- * 24-bit surface or, if they have an alpha mask or a colorkey, to a 32-bit
- * surface before they are saved. YUV and paletted 1-bit and 4-bit formats are
- * not supported.
+ * Surfaces with a 24-bit, 32-bit and paletted 8-bit format get saved in the
+ * BMP directly. Other RGB formats with 8-bit or higher get converted to a
+ * 24-bit surface or, if they have an alpha mask or a colorkey, to a 32-bit
+ * surface before they are saved. YUV and paletted 1-bit and 4-bit formats are
+ * not supported.
*
- * If \c freedst is non-zero, the stream will be closed after being written.
+ * \param surface the SDL_Surface structure containing the image to be saved
+ * \param dst a data stream to save to
+ * \param freedst non-zero to close the stream after being written
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \return 0 if successful or -1 if there was an error.
+ * \sa SDL_LoadBMP_RW
+ * \sa SDL_SaveBMP
*/
extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
(SDL_Surface * surface, SDL_RWops * dst, int freedst);
@@ -227,190 +356,300 @@ extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1)
/**
- * \brief Sets the RLE acceleration hint for a surface.
+ * Set the RLE acceleration hint for a surface.
+ *
+ * If RLE is enabled, color key and alpha blending blits are much faster, but
+ * the surface must be locked before directly accessing the pixels.
*
- * \return 0 on success, or -1 if the surface is not valid
+ * \param surface the SDL_Surface structure to optimize
+ * \param flag 0 to disable, non-zero to enable RLE acceleration
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \note If RLE is enabled, colorkey and alpha blending blits are much faster,
- * but the surface must be locked before directly accessing the pixels.
+ * \sa SDL_BlitSurface
+ * \sa SDL_LockSurface
+ * \sa SDL_UnlockSurface
*/
extern DECLSPEC int SDLCALL SDL_SetSurfaceRLE(SDL_Surface * surface,
int flag);
/**
- * \brief Returns whether the surface is RLE enabled
+ * Returns whether the surface is RLE enabled
*
- * \return SDL_TRUE if the surface is RLE enabled, or SDL_FALSE if the surface is NULL or not RLE enabled
+ * It is safe to pass a NULL `surface` here; it will return SDL_FALSE.
+ *
+ * \param surface the SDL_Surface structure to query
+ * \returns SDL_TRUE if the surface is RLE enabled, SDL_FALSE otherwise.
+ *
+ * \sa SDL_SetSurfaceRLE
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasSurfaceRLE(SDL_Surface * surface);
/**
- * \brief Sets the color key (transparent pixel) in a blittable surface.
+ * Set the color key (transparent pixel) in a surface.
+ *
+ * The color key defines a pixel value that will be treated as transparent in
+ * a blit. It is a pixel of the format used by the surface, as generated by
+ * SDL_MapRGB().
*
- * \param surface The surface to update
- * \param flag Non-zero to enable colorkey and 0 to disable colorkey
- * \param key The transparent pixel in the native surface format
+ * RLE acceleration can substantially speed up blitting of images with large
+ * horizontal runs of transparent pixels. See SDL_SetSurfaceRLE() for details.
*
- * \return 0 on success, or -1 if the surface is not valid
+ * \param surface the SDL_Surface structure to update
+ * \param flag SDL_TRUE to enable color key, SDL_FALSE to disable color key
+ * \param key the transparent pixel
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * You can pass SDL_RLEACCEL to enable RLE accelerated blits.
+ * \sa SDL_BlitSurface
+ * \sa SDL_GetColorKey
*/
extern DECLSPEC int SDLCALL SDL_SetColorKey(SDL_Surface * surface,
int flag, Uint32 key);
/**
- * \brief Returns whether the surface has a color key
+ * Returns whether the surface has a color key
+ *
+ * It is safe to pass a NULL `surface` here; it will return SDL_FALSE.
+ *
+ * \param surface the SDL_Surface structure to query
+ * \return SDL_TRUE if the surface has a color key, SDL_FALSE otherwise.
*
- * \return SDL_TRUE if the surface has a color key, or SDL_FALSE if the surface is NULL or has no color key
+ * \sa SDL_SetColorKey
+ * \sa SDL_GetColorKey
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasColorKey(SDL_Surface * surface);
/**
- * \brief Gets the color key (transparent pixel) in a blittable surface.
+ * Get the color key (transparent pixel) for a surface.
*
- * \param surface The surface to update
- * \param key A pointer filled in with the transparent pixel in the native
- * surface format
+ * The color key is a pixel of the format used by the surface, as generated by
+ * SDL_MapRGB().
*
- * \return 0 on success, or -1 if the surface is not valid or colorkey is not
- * enabled.
+ * If the surface doesn't have color key enabled this function returns -1.
+ *
+ * \param surface the SDL_Surface structure to query
+ * \param key a pointer filled in with the transparent pixel
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_BlitSurface
+ * \sa SDL_SetColorKey
*/
extern DECLSPEC int SDLCALL SDL_GetColorKey(SDL_Surface * surface,
Uint32 * key);
/**
- * \brief Set an additional color value used in blit operations.
+ * Set an additional color value multiplied into blit operations.
+ *
+ * When this surface is blitted, during the blit operation each source color
+ * channel is modulated by the appropriate color value according to the
+ * following formula:
*
- * \param surface The surface to update.
- * \param r The red color value multiplied into blit operations.
- * \param g The green color value multiplied into blit operations.
- * \param b The blue color value multiplied into blit operations.
+ * `srcC = srcC * (color / 255)`
*
- * \return 0 on success, or -1 if the surface is not valid.
+ * \param surface the SDL_Surface structure to update
+ * \param r the red color value multiplied into blit operations
+ * \param g the green color value multiplied into blit operations
+ * \param b the blue color value multiplied into blit operations
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_GetSurfaceColorMod()
+ * \sa SDL_GetSurfaceColorMod
+ * \sa SDL_SetSurfaceAlphaMod
*/
extern DECLSPEC int SDLCALL SDL_SetSurfaceColorMod(SDL_Surface * surface,
Uint8 r, Uint8 g, Uint8 b);
/**
- * \brief Get the additional color value used in blit operations.
+ * Get the additional color value multiplied into blit operations.
*
- * \param surface The surface to query.
- * \param r A pointer filled in with the current red color value.
- * \param g A pointer filled in with the current green color value.
- * \param b A pointer filled in with the current blue color value.
+ * \param surface the SDL_Surface structure to query
+ * \param r a pointer filled in with the current red color value
+ * \param g a pointer filled in with the current green color value
+ * \param b a pointer filled in with the current blue color value
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \return 0 on success, or -1 if the surface is not valid.
- *
- * \sa SDL_SetSurfaceColorMod()
+ * \sa SDL_GetSurfaceAlphaMod
+ * \sa SDL_SetSurfaceColorMod
*/
extern DECLSPEC int SDLCALL SDL_GetSurfaceColorMod(SDL_Surface * surface,
Uint8 * r, Uint8 * g,
Uint8 * b);
/**
- * \brief Set an additional alpha value used in blit operations.
+ * Set an additional alpha value used in blit operations.
+ *
+ * When this surface is blitted, during the blit operation the source alpha
+ * value is modulated by this alpha value according to the following formula:
*
- * \param surface The surface to update.
- * \param alpha The alpha value multiplied into blit operations.
+ * `srcA = srcA * (alpha / 255)`
*
- * \return 0 on success, or -1 if the surface is not valid.
+ * \param surface the SDL_Surface structure to update
+ * \param alpha the alpha value multiplied into blit operations
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_GetSurfaceAlphaMod()
+ * \sa SDL_GetSurfaceAlphaMod
+ * \sa SDL_SetSurfaceColorMod
*/
extern DECLSPEC int SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface * surface,
Uint8 alpha);
/**
- * \brief Get the additional alpha value used in blit operations.
- *
- * \param surface The surface to query.
- * \param alpha A pointer filled in with the current alpha value.
+ * Get the additional alpha value used in blit operations.
*
- * \return 0 on success, or -1 if the surface is not valid.
+ * \param surface the SDL_Surface structure to query
+ * \param alpha a pointer filled in with the current alpha value
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_SetSurfaceAlphaMod()
+ * \sa SDL_GetSurfaceColorMod
+ * \sa SDL_SetSurfaceAlphaMod
*/
extern DECLSPEC int SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface * surface,
Uint8 * alpha);
/**
- * \brief Set the blend mode used for blit operations.
+ * Set the blend mode used for blit operations.
*
- * \param surface The surface to update.
- * \param blendMode ::SDL_BlendMode to use for blit blending.
+ * To copy a surface to another surface (or texture) without blending with the
+ * existing data, the blendmode of the SOURCE surface should be set to
+ * `SDL_BLENDMODE_NONE`.
*
- * \return 0 on success, or -1 if the parameters are not valid.
+ * \param surface the SDL_Surface structure to update
+ * \param blendMode the SDL_BlendMode to use for blit blending
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_GetSurfaceBlendMode()
+ * \sa SDL_GetSurfaceBlendMode
*/
extern DECLSPEC int SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface * surface,
SDL_BlendMode blendMode);
/**
- * \brief Get the blend mode used for blit operations.
+ * Get the blend mode used for blit operations.
*
- * \param surface The surface to query.
- * \param blendMode A pointer filled in with the current blend mode.
+ * \param surface the SDL_Surface structure to query
+ * \param blendMode a pointer filled in with the current SDL_BlendMode
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \return 0 on success, or -1 if the surface is not valid.
- *
- * \sa SDL_SetSurfaceBlendMode()
+ * \sa SDL_SetSurfaceBlendMode
*/
extern DECLSPEC int SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface * surface,
SDL_BlendMode *blendMode);
/**
- * Sets the clipping rectangle for the destination surface in a blit.
+ * Set the clipping rectangle for a surface.
+ *
+ * When `surface` is the destination of a blit, only the area within the
+ * clip rectangle is drawn into.
*
- * If the clip rectangle is NULL, clipping will be disabled.
+ * Note that blits are automatically clipped to the edges of the source and
+ * destination surfaces.
*
- * If the clip rectangle doesn't intersect the surface, the function will
- * return SDL_FALSE and blits will be completely clipped. Otherwise the
- * function returns SDL_TRUE and blits to the surface will be clipped to
- * the intersection of the surface area and the clipping rectangle.
+ * \param surface the SDL_Surface structure to be clipped
+ * \param rect the SDL_Rect structure representing the clipping rectangle, or
+ * NULL to disable clipping
+ * \returns SDL_TRUE if the rectangle intersects the surface, otherwise
+ * SDL_FALSE and blits will be completely clipped.
*
- * Note that blits are automatically clipped to the edges of the source
- * and destination surfaces.
+ * \sa SDL_BlitSurface
+ * \sa SDL_GetClipRect
*/
extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface * surface,
const SDL_Rect * rect);
/**
- * Gets the clipping rectangle for the destination surface in a blit.
+ * Get the clipping rectangle for a surface.
+ *
+ * When `surface` is the destination of a blit, only the area within the
+ * clip rectangle is drawn into.
*
- * \c rect must be a pointer to a valid rectangle which will be filled
- * with the correct values.
+ * \param surface the SDL_Surface structure representing the surface to be
+ * clipped
+ * \param rect an SDL_Rect structure filled in with the clipping rectangle for
+ * the surface
+ *
+ * \sa SDL_BlitSurface
+ * \sa SDL_SetClipRect
*/
extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface * surface,
SDL_Rect * rect);
/*
- * Creates a new surface identical to the existing surface
+ * Creates a new surface identical to the existing surface.
+ *
+ * The returned surface should be freed with SDL_FreeSurface().
+ *
+ * \param surface the surface to duplicate.
+ * \returns a copy of the surface, or NULL on failure; call SDL_GetError() for
+ * more information.
*/
extern DECLSPEC SDL_Surface *SDLCALL SDL_DuplicateSurface(SDL_Surface * surface);
/**
- * Creates a new surface of the specified format, and then copies and maps
- * the given surface to it so the blit of the converted surface will be as
- * fast as possible. If this function fails, it returns NULL.
+ * Copy an existing surface to a new surface of the specified format.
+ *
+ * This function is used to optimize images for faster *repeat* blitting. This
+ * is accomplished by converting the original and storing the result as a new
+ * surface. The new, optimized surface can then be used as the source for
+ * future blits, making them faster.
+ *
+ * \param src the existing SDL_Surface structure to convert
+ * \param fmt the SDL_PixelFormat structure that the new surface is optimized
+ * for
+ * \param flags the flags are unused and should be set to 0; this is a
+ * leftover from SDL 1.2's API
+ * \returns the new SDL_Surface structure that is created or NULL if it fails;
+ * call SDL_GetError() for more information.
*
- * The \c flags parameter is passed to SDL_CreateRGBSurface() and has those
- * semantics. You can also pass ::SDL_RLEACCEL in the flags parameter and
- * SDL will try to RLE accelerate colorkey and alpha blits in the resulting
- * surface.
+ * \sa SDL_AllocFormat
+ * \sa SDL_ConvertSurfaceFormat
+ * \sa SDL_CreateRGBSurface
*/
extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface
(SDL_Surface * src, const SDL_PixelFormat * fmt, Uint32 flags);
+
+/**
+ * Copy an existing surface to a new surface of the specified format enum.
+ *
+ * This function operates just like SDL_ConvertSurface(), but accepts an
+ * SDL_PixelFormatEnum value instead of an SDL_PixelFormat structure. As
+ * such, it might be easier to call but it doesn't have access to palette
+ * information for the destination surface, in case that would be important.
+ *
+ * \param src the existing SDL_Surface structure to convert
+ * \param pixel_format the SDL_PixelFormatEnum that the new surface is
+ * optimized for
+ * \param flags the flags are unused and should be set to 0; this is a
+ * leftover from SDL 1.2's API
+ * \returns the new SDL_Surface structure that is created or NULL if it fails;
+ * call SDL_GetError() for more information.
+ *
+ * \sa SDL_AllocFormat
+ * \sa SDL_ConvertSurfaceFormat
+ * \sa SDL_CreateRGBSurface
+ */
extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurfaceFormat
(SDL_Surface * src, Uint32 pixel_format, Uint32 flags);
/**
- * \brief Copy a block of pixels of one format to another format
+ * Copy a block of pixels of one format to another format.
*
- * \return 0 on success, or -1 if there was an error
+ * \param width the width of the block to copy, in pixels
+ * \param height the height of the block to copy, in pixels
+ * \param src_format an SDL_PixelFormatEnum value of the `src` pixels format
+ * \param src a pointer to the source pixels
+ * \param src_pitch the pitch of the block to copy, in bytes
+ * \param dst_format an SDL_PixelFormatEnum value of the `dst` pixels format
+ * \param dst a pointer to be filled in with new pixel data
+ * \param dst_pitch the pitch of the destination pixels, in bytes
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*/
extern DECLSPEC int SDLCALL SDL_ConvertPixels(int width, int height,
Uint32 src_format,
@@ -419,20 +658,54 @@ extern DECLSPEC int SDLCALL SDL_ConvertPixels(int width, int height,
void * dst, int dst_pitch);
/**
- * Performs a fast fill of the given rectangle with \c color.
+ * Perform a fast fill of a rectangle with a specific color.
*
- * If \c rect is NULL, the whole surface will be filled with \c color.
+ * `color` should be a pixel of the format used by the surface, and can be
+ * generated by SDL_MapRGB() or SDL_MapRGBA(). If the color value contains an
+ * alpha component then the destination is simply filled with that alpha
+ * information, no blending takes place.
*
- * The color should be a pixel of the format used by the surface, and
- * can be generated by the SDL_MapRGB() function.
+ * If there is a clip rectangle set on the destination (set via
+ * SDL_SetClipRect()), then this function will fill based on the intersection
+ * of the clip rectangle and `rect`.
*
- * \return 0 on success, or -1 on error.
+ * \param dst the SDL_Surface structure that is the drawing target
+ * \param rect the SDL_Rect structure representing the rectangle to fill, or
+ * NULL to fill the entire surface
+ * \param color the color to fill with
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_FillRects
*/
extern DECLSPEC int SDLCALL SDL_FillRect
(SDL_Surface * dst, const SDL_Rect * rect, Uint32 color);
+
+/**
+ * Perform a fast fill of a set of rectangles with a specific color.
+ *
+ * `color` should be a pixel of the format used by the surface, and can be
+ * generated by SDL_MapRGB() or SDL_MapRGBA(). If the color value contains an
+ * alpha component then the destination is simply filled with that alpha
+ * information, no blending takes place.
+ *
+ * If there is a clip rectangle set on the destination (set via
+ * SDL_SetClipRect()), then this function will fill based on the intersection
+ * of the clip rectangle and `rect`.
+ *
+ * \param dst the SDL_Surface structure that is the drawing target
+ * \param rects an array of SDL_Rects representing the rectangles to fill.
+ * \param count the number of rectangles in the array
+ * \param color the color to fill with
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_FillRect
+ */
extern DECLSPEC int SDLCALL SDL_FillRects
(SDL_Surface * dst, const SDL_Rect * rects, int count, Uint32 color);
+/* !!! FIXME: merge this documentation with the wiki */
/**
* Performs a fast blit from the source surface to the destination surface.
*
@@ -493,36 +766,57 @@ extern DECLSPEC int SDLCALL SDL_FillRects
#define SDL_BlitSurface SDL_UpperBlit
/**
- * This is the public blit function, SDL_BlitSurface(), and it performs
- * rectangle validation and clipping before passing it to SDL_LowerBlit()
+ * Perform a fast blit from the source surface to the destination surface.
+ *
+ * SDL_UpperBlit() has been replaced by SDL_BlitSurface(), which is merely
+ * a macro for this function with a less confusing name.
+ *
+ * \sa SDL_BlitSurface
*/
extern DECLSPEC int SDLCALL SDL_UpperBlit
(SDL_Surface * src, const SDL_Rect * srcrect,
SDL_Surface * dst, SDL_Rect * dstrect);
/**
- * This is a semi-private blit function and it performs low-level surface
- * blitting only.
+ * Perform low-level surface blitting only.
+ *
+ * This is a semi-private blit function and it performs low-level surface
+ * blitting, assuming the input rectangles have already been clipped.
+ *
+ * Unless you know what you're doing, you should be using SDL_BlitSurface()
+ * instead.
+ *
+ * \param src the SDL_Surface structure to be copied from
+ * \param srcrect the SDL_Rect structure representing the rectangle to be
+ * copied, or NULL to copy the entire surface
+ * \param dst the SDL_Surface structure that is the blit target
+ * \param dstrect the SDL_Rect structure representing the rectangle that is
+ * copied into
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_BlitSurface
*/
extern DECLSPEC int SDLCALL SDL_LowerBlit
(SDL_Surface * src, SDL_Rect * srcrect,
SDL_Surface * dst, SDL_Rect * dstrect);
-/**
- * \brief Perform a fast, low quality, stretch blit between two surfaces of the
- * same pixel format.
- *
- * \note This function uses a static buffer, and is not thread-safe.
- */
+
+ /**
+ * Perform a fast, low quality, stretch blit between two surfaces of the
+ * same format.
+ *
+ * **Warning**: This function uses a static buffer, and is not thread-safe.
+ *
+ * Please use SDL_BlitScaled() instead.
+ */
extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface * src,
const SDL_Rect * srcrect,
SDL_Surface * dst,
const SDL_Rect * dstrect);
/**
- * \brief Perform a bilinear scaling between two surfaces of the
- * same pixel format, 32BPP.
- *
+ * Perform bilinear scaling between two surfaces of the same format, 32BPP.
*/
extern DECLSPEC int SDLCALL SDL_SoftStretchLinear(SDL_Surface * src,
const SDL_Rect * srcrect,
@@ -533,33 +827,50 @@ extern DECLSPEC int SDLCALL SDL_SoftStretchLinear(SDL_Surface * src,
#define SDL_BlitScaled SDL_UpperBlitScaled
/**
- * This is the public scaled blit function, SDL_BlitScaled(), and it performs
- * rectangle validation and clipping before passing it to SDL_LowerBlitScaled()
+ * Perform a scaled surface copy to a destination surface.
+ *
+ * SDL_UpperBlitScaled() has been replaced by SDL_BlitScaled(), which is
+ * merely a macro for this function with a less confusing name.
+ *
+ * \sa SDL_BlitScaled
*/
extern DECLSPEC int SDLCALL SDL_UpperBlitScaled
(SDL_Surface * src, const SDL_Rect * srcrect,
SDL_Surface * dst, SDL_Rect * dstrect);
/**
- * This is a semi-private blit function and it performs low-level surface
- * scaled blitting only.
+ * Perform low-level surface scaled blitting only.
+ *
+ * This is a semi-private function and it performs low-level surface blitting,
+ * assuming the input rectangles have already been clipped.
+ *
+ * \param src the SDL_Surface structure to be copied from
+ * \param srcrect the SDL_Rect structure representing the rectangle to be
+ * copied
+ * \param dst the SDL_Surface structure that is the blit target
+ * \param dstrect the SDL_Rect structure representing the rectangle that is
+ * copied into
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_BlitScaled
*/
extern DECLSPEC int SDLCALL SDL_LowerBlitScaled
(SDL_Surface * src, SDL_Rect * srcrect,
SDL_Surface * dst, SDL_Rect * dstrect);
/**
- * \brief Set the YUV conversion mode
+ * Set the YUV conversion mode
*/
extern DECLSPEC void SDLCALL SDL_SetYUVConversionMode(SDL_YUV_CONVERSION_MODE mode);
/**
- * \brief Get the YUV conversion mode
+ * Get the YUV conversion mode
*/
extern DECLSPEC SDL_YUV_CONVERSION_MODE SDLCALL SDL_GetYUVConversionMode(void);
/**
- * \brief Get the YUV conversion mode, returning the correct mode for the resolution when the current conversion mode is SDL_YUV_CONVERSION_AUTOMATIC
+ * Get the YUV conversion mode, returning the correct mode for the resolution when the current conversion mode is SDL_YUV_CONVERSION_AUTOMATIC
*/
extern DECLSPEC SDL_YUV_CONVERSION_MODE SDLCALL SDL_GetYUVConversionModeForResolution(int width, int height);
diff --git a/include/SDL_system.h b/include/SDL_system.h
index e62c9e5..753272e 100644
--- a/include/SDL_system.h
+++ b/include/SDL_system.h
@@ -43,41 +43,78 @@ extern "C" {
/* Platform specific functions for Windows */
#ifdef __WIN32__
-/**
- \brief Set a function that is called for every windows message, before TranslateMessage()
-*/
typedef void (SDLCALL * SDL_WindowsMessageHook)(void *userdata, void *hWnd, unsigned int message, Uint64 wParam, Sint64 lParam);
-extern DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHook callback, void *userdata);
/**
- \brief Returns the D3D9 adapter index that matches the specified display index.
+ * Set a callback for every Windows message, run before TranslateMessage().
+ *
+ * \param callback The SDL_WindowsMessageHook function to call.
+ * \param userdata a pointer to pass to every iteration of `callback`
+ */
+extern DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHook callback, void *userdata);
- This adapter index can be passed to IDirect3D9::CreateDevice and controls
- on which monitor a full screen application will appear.
-*/
+/**
+ * Get the D3D9 adapter index that matches the specified display index.
+ *
+ * The returned adapter index can be passed to `IDirect3D9::CreateDevice` and
+ * controls on which monitor a full screen application will appear.
+ *
+ * \param displayIndex the display index for which to get the D3D9 adapter
+ * index
+ * \returns the D3D9 adapter index on success or a negative error code on
+ * failure; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.1.
+ */
extern DECLSPEC int SDLCALL SDL_Direct3D9GetAdapterIndex( int displayIndex );
typedef struct IDirect3DDevice9 IDirect3DDevice9;
-/**
- \brief Returns the D3D9 device associated with a renderer, or NULL if it's not a D3D9 renderer.
- Once you are done using the device, you should release it to avoid a resource leak.
+/**
+ * Get the D3D9 device associated with a renderer.
+ *
+ * Once you are done using the device, you should release it to avoid a
+ * resource leak.
+ *
+ * \param renderer the renderer from which to get the associated D3D device
+ * \returns the D3D9 device associated with given renderer or NULL if it is
+ * not a D3D9 renderer; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.1.
*/
extern DECLSPEC IDirect3DDevice9* SDLCALL SDL_RenderGetD3D9Device(SDL_Renderer * renderer);
typedef struct ID3D11Device ID3D11Device;
-/**
- \brief Returns the D3D11 device associated with a renderer, or NULL if it's not a D3D11 renderer.
- Once you are done using the device, you should release it to avoid a resource leak.
+/**
+ * Get the D3D11 device associated with a renderer.
+ *
+ * Once you are done using the device, you should release it to avoid a
+ * resource leak.
+ *
+ * \param renderer the renderer from which to get the associated D3D11 device
+ * \returns the D3D11 device associated with given renderer or NULL if it is
+ * not a D3D11 renderer; call SDL_GetError() for more information.
*/
extern DECLSPEC ID3D11Device* SDLCALL SDL_RenderGetD3D11Device(SDL_Renderer * renderer);
/**
- \brief Returns the DXGI Adapter and Output indices for the specified display index.
-
- These can be passed to EnumAdapters and EnumOutputs respectively to get the objects
- required to create a DX10 or DX11 device and swap chain.
+ * Get the DXGI Adapter and Output indices for the specified display index.
+ *
+ * The DXGI Adapter and Output indices can be passed to `EnumAdapters` and
+ * `EnumOutputs` respectively to get the objects required to create a DX10 or
+ * DX11 device and swap chain.
+ *
+ * Before SDL 2.0.4 this function did not return a value. Since SDL 2.0.4 it
+ * returns an SDL_bool.
+ *
+ * \param displayIndex the display index for which to get both indices
+ * \param adapterIndex a pointer to be filled in with the adapter index
+ * \param outputIndex a pointer to be filled in with the output index
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ * for more information.
+ *
+ * \since This function is available since SDL 2.0.2.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_DXGIGetOutputInfo( int displayIndex, int *adapterIndex, int *outputIndex );
@@ -88,9 +125,13 @@ extern DECLSPEC SDL_bool SDLCALL SDL_DXGIGetOutputInfo( int displayIndex, int *a
#ifdef __LINUX__
/**
- \brief Sets the UNIX nice value for a thread, using setpriority() if possible, and RealtimeKit if available.
-
- \return 0 on success, or -1 on error.
+ * Sets the UNIX nice value for a thread.
+ *
+ * This uses setpriority() if possible, and RealtimeKit if available.
+ *
+ * \param threadID the Unix thread ID to change priority of.
+ * \param priority The new, Unix-specific, priority value.
+ * \returns 0 on success, or -1 on error.
*/
extern DECLSPEC int SDLCALL SDL_LinuxSetThreadPriority(Sint64 threadID, int priority);
@@ -112,66 +153,118 @@ extern DECLSPEC void SDLCALL SDL_iPhoneSetEventPump(SDL_bool enabled);
#ifdef __ANDROID__
/**
- \brief Get the JNI environment for the current thread
-
- This returns JNIEnv*, but the prototype is void* so we don't need jni.h
+ * Get the Android Java Native Interface Environment of the current thread.
+ *
+ * This is the JNIEnv one needs to access the Java virtual machine from native
+ * code, and is needed for many Android APIs to be usable from C.
+ *
+ * The prototype of the function in SDL's code actually declare a void* return
+ * type, even if the implementation returns a pointer to a JNIEnv. The
+ * rationale being that the SDL headers can avoid including jni.h.
+ *
+ * \returns a pointer to Java native interface object (JNIEnv) to which the
+ * current thread is attached, or 0 on error.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AndroidGetActivity
*/
extern DECLSPEC void * SDLCALL SDL_AndroidGetJNIEnv(void);
/**
- \brief Get the SDL Activity object for the application
-
- This returns jobject, but the prototype is void* so we don't need jni.h
- The jobject returned by SDL_AndroidGetActivity is a local reference.
- It is the caller's responsibility to properly release it
- (using env->Push/PopLocalFrame or manually with env->DeleteLocalRef)
+ * Retrieve the Java instance of the Android activity class.
+ *
+ * The prototype of the function in SDL's code actually declares a void*
+ * return type, even if the implementation returns a jobject. The rationale
+ * being that the SDL headers can avoid including jni.h.
+ *
+ * The jobject returned by the function is a local reference and must
+ * be released by the caller. See the PushLocalFrame() and PopLocalFrame() or
+ * DeleteLocalRef() functions of the Java native interface:
+ *
+ * https://docs.oracle.com/javase/1.5.0/docs/guide/jni/spec/functions.html
+ *
+ * \returns the jobject representing the instance of the Activity class of the
+ * Android application, or NULL on error.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AndroidGetJNIEnv
*/
extern DECLSPEC void * SDLCALL SDL_AndroidGetActivity(void);
/**
- \brief Return API level of the current device
-
- API level 30: Android 11
- API level 29: Android 10
- API level 28: Android 9
- API level 27: Android 8.1
- API level 26: Android 8.0
- API level 25: Android 7.1
- API level 24: Android 7.0
- API level 23: Android 6.0
- API level 22: Android 5.1
- API level 21: Android 5.0
- API level 20: Android 4.4W
- API level 19: Android 4.4
- API level 18: Android 4.3
- API level 17: Android 4.2
- API level 16: Android 4.1
- API level 15: Android 4.0.3
- API level 14: Android 4.0
- API level 13: Android 3.2
- API level 12: Android 3.1
- API level 11: Android 3.0
- API level 10: Android 2.3.3
+ * Query Android API level of the current device.
+ *
+ * - API level 30: Android 11
+ *
+ * - API level 29: Android 10
+ *
+ * - API level 28: Android 9
+ *
+ * - API level 27: Android 8.1
+ *
+ * - API level 26: Android 8.0
+ *
+ * - API level 25: Android 7.1
+ *
+ * - API level 24: Android 7.0
+ *
+ * - API level 23: Android 6.0
+ *
+ * - API level 22: Android 5.1
+ *
+ * - API level 21: Android 5.0
+ *
+ * - API level 20: Android 4.4W
+ *
+ * - API level 19: Android 4.4
+ *
+ * - API level 18: Android 4.3
+ *
+ * - API level 17: Android 4.2
+ *
+ * - API level 16: Android 4.1
+ *
+ * - API level 15: Android 4.0.3
+ *
+ * - API level 14: Android 4.0
+ *
+ * - API level 13: Android 3.2
+ *
+ * - API level 12: Android 3.1
+ *
+ * - API level 11: Android 3.0
+ *
+ * - API level 10: Android 2.3.3
+ *
+ * \returns Android API level.
*/
extern DECLSPEC int SDLCALL SDL_GetAndroidSDKVersion(void);
/**
- \brief Return true if the application is running on Android TV
+ * Query if the application is running on Android TV.
+ *
+ * \returns SDL_TRUE if this is Android TV, SDL_FALSE otherwise.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_IsAndroidTV(void);
/**
- \brief Return true if the application is running on a Chromebook
+ * Query if the application is running on a Chromebook.
+ *
+ * \returns SDL_TRUE if this is a Chromebook, SDL_FALSE otherwise.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_IsChromebook(void);
/**
- \brief Return true is the application is running on a Samsung DeX docking station
+ * Query if the application is running on a Samsung DeX docking station.
+ *
+ * \returns SDL_TRUE if this is a DeX docking station, SDL_FALSE otherwise.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_IsDeXMode(void);
/**
- \brief Trigger the Android system back button behavior.
+ * Trigger the Android system back button behavior.
*/
extern DECLSPEC void SDLCALL SDL_AndroidBackButton(void);
@@ -183,54 +276,91 @@ extern DECLSPEC void SDLCALL SDL_AndroidBackButton(void);
#define SDL_ANDROID_EXTERNAL_STORAGE_WRITE 0x02
/**
- \brief Get the path used for internal storage for this application.
-
- This path is unique to your application and cannot be written to
- by other applications.
+ * Get the path used for internal storage for this application.
+ *
+ * This path is unique to your application and cannot be written to by other
+ * applications.
+ *
+ * Your internal storage path is typically:
+ * `/data/data/your.app.package/files`.
+ *
+ * \returns the path used for internal storage or NULL on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AndroidGetExternalStorageState
*/
extern DECLSPEC const char * SDLCALL SDL_AndroidGetInternalStoragePath(void);
/**
- \brief Get the current state of external storage, a bitmask of these values:
- SDL_ANDROID_EXTERNAL_STORAGE_READ
- SDL_ANDROID_EXTERNAL_STORAGE_WRITE
-
- If external storage is currently unavailable, this will return 0.
-*/
+ * Get the current state of external storage.
+ *
+ * The current state of external storage, a bitmask of these values:
+ * `SDL_ANDROID_EXTERNAL_STORAGE_READ`, `SDL_ANDROID_EXTERNAL_STORAGE_WRITE`.
+ *
+ * If external storage is currently unavailable, this will return 0.
+ *
+ * \returns the current state of external storage on success or 0 on failure;
+ * call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AndroidGetExternalStoragePath
+ */
extern DECLSPEC int SDLCALL SDL_AndroidGetExternalStorageState(void);
/**
- \brief Get the path used for external storage for this application.
-
- This path is unique to your application, but is public and can be
- written to by other applications.
+ * Get the path used for external storage for this application.
+ *
+ * This path is unique to your application, but is public and can be written
+ * to by other applications.
+ *
+ * Your external storage path is typically:
+ * `/storage/sdcard0/Android/data/your.app.package/files`.
+ *
+ * \returns the path used for external storage for this application on success
+ * or NULL on failure; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AndroidGetExternalStorageState
*/
extern DECLSPEC const char * SDLCALL SDL_AndroidGetExternalStoragePath(void);
/**
- \brief Request permissions at runtime.
-
- This blocks the calling thread until the permission is granted or
- denied. Returns SDL_TRUE if the permission was granted.
+ * Request permissions at runtime.
+ *
+ * This blocks the calling thread until the permission is granted or
+ * denied.
+ *
+ * \param permission The permission to request.
+ * \returns SDL_TRUE if the permission was granted, SDL_FALSE otherwise.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_AndroidRequestPermission(const char *permission);
/**
- \brief Shows android toast notification
-
- \note Shows toast in UI thread [https://developer.android.com/guide/topics/ui/notifiers/toasts]
-
- \param message : text message to be shown
- duration : 0 - short [https://developer.android.com/reference/android/widget/Toast#LENGTH_SHORT],
- 1 - long [https://developer.android.com/reference/android/widget/Toast#LENGTH_LONG]
- gravity : the location at which the notification should appear on the screen.
- It's an optional parameter. Set -1 if you don't want specify any gravity or
- choose some value from https://developer.android.com/reference/android/view/Gravity
- xOffset : set this parameter only when gravity >=0
- yOffset : set this parameter only when gravity >=0
- \return 0 if success, -1 if any error occurs.
-*/
-extern DECLSPEC int SDLCALL SDL_AndroidShowToast(const char* message, int duration, int gravity, int xOffset, int yOffset);
+ * Shows an Android toast notification.
+ *
+ * Toasts are a sort of lightweight notification that are unique to Android.
+ *
+ * https://developer.android.com/guide/topics/ui/notifiers/toasts
+ *
+ * Shows toast in UI thread.
+ *
+ * For the `gravity` parameter, choose a value from here, or -1 if you don't
+ * have a preference:
+ *
+ * https://developer.android.com/reference/android/view/Gravity
+ *
+ * \param message text message to be shown
+ * \param duration 0=short, 1=long
+ * \param gravity where the notification should appear on the screen.
+ * \param xoffset set this parameter only when gravity >=0
+ * \param yoffset set this parameter only when gravity >=0
+ * \returns 0 if success, -1 if any error occurs.
+ */
+extern DECLSPEC int SDLCALL SDL_AndroidShowToast(const char* message, int duration, int gravity, int xoffset, int yoffset);
#endif /* __ANDROID__ */
@@ -281,50 +411,66 @@ typedef enum
/**
- * \brief Retrieves a WinRT defined path on the local file system
- *
- * \note Documentation on most app-specific path types on WinRT
- * can be found on MSDN, at the URL:
- * http://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx
- *
- * \param pathType The type of path to retrieve.
- * \return A UCS-2 string (16-bit, wide-char) containing the path, or NULL
- * if the path is not available for any reason. Not all paths are
- * available on all versions of Windows. This is especially true on
- * Windows Phone. Check the documentation for the given
- * SDL_WinRT_Path for more information on which path types are
- * supported where.
+ * Retrieve a WinRT defined path on the local file system.
+ *
+ * Not all paths are available on all versions of Windows. This is especially
+ * true on Windows Phone. Check the documentation for the given SDL_WinRT_Path
+ * for more information on which path types are supported where.
+ *
+ * Documentation on most app-specific path types on WinRT can be found on
+ * MSDN, at the URL:
+ *
+ * https://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx
+ *
+ * \param pathType the type of path to retrieve, one of SDL_WinRT_Path
+ * \returns a UCS-2 string (16-bit, wide-char) containing the path, or NULL if
+ * the path is not available for any reason; call SDL_GetError() for
+ * more information.
+ *
+ * \since This function is available since SDL 2.0.3.
+ *
+ * \sa SDL_WinRTGetFSPathUTF8
*/
extern DECLSPEC const wchar_t * SDLCALL SDL_WinRTGetFSPathUNICODE(SDL_WinRT_Path pathType);
/**
- * \brief Retrieves a WinRT defined path on the local file system
- *
- * \note Documentation on most app-specific path types on WinRT
- * can be found on MSDN, at the URL:
- * http://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx
- *
- * \param pathType The type of path to retrieve.
- * \return A UTF-8 string (8-bit, multi-byte) containing the path, or NULL
- * if the path is not available for any reason. Not all paths are
- * available on all versions of Windows. This is especially true on
- * Windows Phone. Check the documentation for the given
- * SDL_WinRT_Path for more information on which path types are
- * supported where.
+ * Retrieve a WinRT defined path on the local file system.
+ *
+ * Not all paths are available on all versions of Windows. This is especially
+ * true on Windows Phone. Check the documentation for the given SDL_WinRT_Path
+ * for more information on which path types are supported where.
+ *
+ * Documentation on most app-specific path types on WinRT can be found on
+ * MSDN, at the URL:
+ *
+ * https://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx
+ *
+ * \param pathType the type of path to retrieve, one of SDL_WinRT_Path
+ * \returns a UTF-8 string (8-bit, multi-byte) containing the path, or NULL if
+ * the path is not available for any reason; call SDL_GetError() for
+ * more information.
+ *
+ * \since This function is available since SDL 2.0.3.
+ *
+ * \sa SDL_WinRTGetFSPathUNICODE
*/
extern DECLSPEC const char * SDLCALL SDL_WinRTGetFSPathUTF8(SDL_WinRT_Path pathType);
/**
- * \brief Detects the device family of WinRT plattform on runtime
+ * Detects the device family of WinRT plattform at runtime.
*
- * \return Device family
+ * \returns A value from the SDL_WinRT_DeviceFamily enum.
*/
extern DECLSPEC SDL_WinRT_DeviceFamily SDLCALL SDL_WinRTGetDeviceFamily();
#endif /* __WINRT__ */
/**
- \brief Return true if the current device is a tablet.
+ * Query if the current device is a tablet.
+ *
+ * If SDL can't determine this, it will return SDL_FALSE.
+ *
+ * \returns SDL_TRUE if the device is a tablet, SDL_FALSE otherwise.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_IsTablet(void);
diff --git a/include/SDL_syswm.h b/include/SDL_syswm.h
index 1d15849..12e86a1 100644
--- a/include/SDL_syswm.h
+++ b/include/SDL_syswm.h
@@ -344,23 +344,23 @@ struct SDL_SysWMinfo
typedef struct SDL_SysWMinfo SDL_SysWMinfo;
-/* Function prototypes */
+
/**
- * \brief This function allows access to driver-dependent window information.
+ * Get driver-specific information about a window.
+ *
+ * You must include SDL_syswm.h for the declaration of SDL_SysWMinfo.
*
- * \param window The window about which information is being requested
- * \param info This structure must be initialized with the SDL version, and is
- * then filled in with information about the given window.
+ * The caller must initialize the `info` structure's version by using
+ * `SDL_VERSION(&info.version)`, and then this function will fill in the
+ * rest of the structure with information about the given window.
*
- * \return SDL_TRUE if the function is implemented and the version member of
- * the \c info struct is valid, SDL_FALSE otherwise.
+ * \param window the window about which information is being requested
+ * \param info an SDL_SysWMinfo structure filled in with window information
+ * \returns SDL_TRUE if the function is implemented and the `version` member
+ * of the `info` struct is valid, or SDL_FALSE if the information
+ * could not be retrieved; call SDL_GetError() for more information.
*
- * You typically use this function like this:
- * \code
- * SDL_SysWMinfo info;
- * SDL_VERSION(&info.version);
- * if ( SDL_GetWindowWMInfo(window, &info) ) { ... }
- * \endcode
+ * \since This function is available since SDL 2.0.0.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowWMInfo(SDL_Window * window,
SDL_SysWMinfo * info);
diff --git a/include/SDL_thread.h b/include/SDL_thread.h
index 4b71083..49168c5 100644
--- a/include/SDL_thread.h
+++ b/include/SDL_thread.h
@@ -69,11 +69,14 @@ typedef enum {
} SDL_ThreadPriority;
/**
- * The function passed to SDL_CreateThread().
- * It is passed a void* user context parameter and returns an int.
+ * The function passed to SDL_CreateThread().
+ *
+ * \param data what was passed as `data` to SDL_CreateThread()
+ * \returns a value that can be reported through SDL_WaitThread().
*/
typedef int (SDLCALL * SDL_ThreadFunction) (void *data);
+
#if defined(__WIN32__)
/**
* \file SDL_thread.h
@@ -183,39 +186,68 @@ SDL_CreateThreadWithStackSize(SDL_ThreadFunction fn, const char *name, const siz
#else
/**
- * Create a thread with a default stack size.
+ * Create a new thread with a default stack size.
+ *
+ * This is equivalent to calling:
*
- * This is equivalent to calling:
- * SDL_CreateThreadWithStackSize(fn, name, 0, data);
+ * ```c
+ * SDL_CreateThreadWithStackSize(fn, name, 0, data);
+ * ```
+ *
+ * \param fn the SDL_ThreadFunction function to call in the new thread
+ * \param name the name of the thread
+ * \param data a pointer that is passed to `fn`
+ * \returns an opaque pointer to the new thread object on success, NULL if the
+ * new thread could not be created; call SDL_GetError() for more
+ * information.
+ *
+ * \sa SDL_CreateThreadWithStackSize
+ * \sa SDL_WaitThread
*/
extern DECLSPEC SDL_Thread *SDLCALL
SDL_CreateThread(SDL_ThreadFunction fn, const char *name, void *data);
/**
- * Create a thread.
- *
- * Thread naming is a little complicated: Most systems have very small
- * limits for the string length (Haiku has 32 bytes, Linux currently has 16,
- * Visual C++ 6.0 has nine!), and possibly other arbitrary rules. You'll
- * have to see what happens with your system's debugger. The name should be
- * UTF-8 (but using the naming limits of C identifiers is a better bet).
- * There are no requirements for thread naming conventions, so long as the
- * string is null-terminated UTF-8, but these guidelines are helpful in
- * choosing a name:
- *
- * http://stackoverflow.com/questions/149932/naming-conventions-for-threads
- *
- * If a system imposes requirements, SDL will try to munge the string for
- * it (truncate, etc), but the original string contents will be available
- * from SDL_GetThreadName().
- *
- * The size (in bytes) of the new stack can be specified. Zero means "use
- * the system default" which might be wildly different between platforms
- * (x86 Linux generally defaults to eight megabytes, an embedded device
- * might be a few kilobytes instead).
- *
- * In SDL 2.1, stacksize will be folded into the original SDL_CreateThread
- * function.
+ * Create a new thread with a specific stack size.
+ *
+ * SDL makes an attempt to report `name` to the system, so that debuggers
+ * can display it. Not all platforms support this.
+ *
+ * Thread naming is a little complicated: Most systems have very small
+ * limits for the string length (Haiku has 32 bytes, Linux currently has 16,
+ * Visual C++ 6.0 has _nine_!), and possibly other arbitrary rules. You'll
+ * have to see what happens with your system's debugger. The name should be
+ * UTF-8 (but using the naming limits of C identifiers is a better bet).
+ * There are no requirements for thread naming conventions, so long as the
+ * string is null-terminated UTF-8, but these guidelines are helpful in
+ * choosing a name:
+ *
+ * https://stackoverflow.com/questions/149932/naming-conventions-for-threads
+ *
+ * If a system imposes requirements, SDL will try to munge the string for
+ * it (truncate, etc), but the original string contents will be available
+ * from SDL_GetThreadName().
+ *
+ * The size (in bytes) of the new stack can be specified. Zero means "use
+ * the system default" which might be wildly different between platforms.
+ * x86 Linux generally defaults to eight megabytes, an embedded device
+ * might be a few kilobytes instead. You generally need to specify a stack
+ * that is a multiple of the system's page size (in many cases, this is 4
+ * kilobytes, but check your system documentation).
+ *
+ * In SDL 2.1, stack size will be folded into the original SDL_CreateThread
+ * function, but for backwards compatibility, this is currently a separate
+ * function.
+ *
+ * \param fn the SDL_ThreadFunction function to call in the new thread
+ * \param name the name of the thread
+ * \param stacksize the size, in bytes, to allocate for the new thread stack.
+ * \param data a pointer that is passed to `fn`
+ * \returns an opaque pointer to the new thread object on success, NULL if the
+ * new thread could not be created; call SDL_GetError() for more
+ * information.
+ *
+ * \sa SDL_WaitThread
*/
extern DECLSPEC SDL_Thread *SDLCALL
SDL_CreateThreadWithStackSize(SDL_ThreadFunction fn, const char *name, const size_t stacksize, void *data);
@@ -223,134 +255,183 @@ SDL_CreateThreadWithStackSize(SDL_ThreadFunction fn, const char *name, const siz
#endif
/**
- * Get the thread name, as it was specified in SDL_CreateThread().
- * This function returns a pointer to a UTF-8 string that names the
- * specified thread, or NULL if it doesn't have a name. This is internal
- * memory, not to be free()'d by the caller, and remains valid until the
- * specified thread is cleaned up by SDL_WaitThread().
+ * Get the thread name as it was specified in SDL_CreateThread().
+ *
+ * This is internal memory, not to be freed by the caller, and remains valid
+ * until the specified thread is cleaned up by SDL_WaitThread().
+ *
+ * \param thread the thread to query
+ * \returns a pointer to a UTF-8 string that names the specified thread, or
+ * NULL if it doesn't have a name.
+ *
+ * \sa SDL_CreateThread
*/
extern DECLSPEC const char *SDLCALL SDL_GetThreadName(SDL_Thread *thread);
/**
- * Get the thread identifier for the current thread.
+ * Get the thread identifier for the current thread.
+ *
+ * This thread identifier is as reported by the underlying operating system.
+ * If SDL is running on a platform that does not support threads the return
+ * value will always be zero.
+ *
+ * This function also returns a valid thread ID when called from the main
+ * thread.
+ *
+ * \returns the ID of the current thread.
+ *
+ * \sa SDL_GetThreadID
*/
extern DECLSPEC SDL_threadID SDLCALL SDL_ThreadID(void);
/**
- * Get the thread identifier for the specified thread.
+ * Get the thread identifier for the specified thread.
+ *
+ * This thread identifier is as reported by the underlying operating system.
+ * If SDL is running on a platform that does not support threads the return
+ * value will always be zero.
*
- * Equivalent to SDL_ThreadID() if the specified thread is NULL.
+ * \param thread the thread to query
+ * \returns the ID of the specified thread, or the ID of the current thread if
+ * `thread` is NULL.
+ *
+ * \sa SDL_ThreadID
*/
extern DECLSPEC SDL_threadID SDLCALL SDL_GetThreadID(SDL_Thread * thread);
/**
- * Set the priority for the current thread
+ * Set the priority for the current thread.
+ *
+ * Note that some platforms will not let you alter the priority (or at least,
+ * promote the thread to a higher priority) at all, and some require you
+ * to be an administrator account. Be prepared for this to fail.
+ *
+ * \param priority the SDL_ThreadPriority to set
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*/
extern DECLSPEC int SDLCALL SDL_SetThreadPriority(SDL_ThreadPriority priority);
/**
- * Wait for a thread to finish. Threads that haven't been detached will
- * remain (as a "zombie") until this function cleans them up. Not doing so
- * is a resource leak.
+ * Wait for a thread to finish.
+ *
+ * Threads that haven't been detached will remain (as a "zombie") until this
+ * function cleans them up. Not doing so is a resource leak.
+ *
+ * Once a thread has been cleaned up through this function, the SDL_Thread
+ * that references it becomes invalid and should not be referenced again. As
+ * such, only one thread may call SDL_WaitThread() on another.
*
- * Once a thread has been cleaned up through this function, the SDL_Thread
- * that references it becomes invalid and should not be referenced again.
- * As such, only one thread may call SDL_WaitThread() on another.
+ * The return code for the thread function is placed in the area pointed to by
+ * `status`, if `status` is not NULL.
*
- * The return code for the thread function is placed in the area
- * pointed to by \c status, if \c status is not NULL.
+ * You may not wait on a thread that has been used in a call to
+ * SDL_DetachThread(). Use either that function or this one, but not both, or
+ * behavior is undefined.
*
- * You may not wait on a thread that has been used in a call to
- * SDL_DetachThread(). Use either that function or this one, but not
- * both, or behavior is undefined.
+ * It is safe to pass a NULL thread to this function; it is a no-op.
*
- * It is safe to pass NULL to this function; it is a no-op.
+ * Note that the thread pointer is freed by this function and is not valid
+ * afterward.
+ *
+ * \param thread the SDL_Thread pointer that was returned from the
+ * SDL_CreateThread() call that started this thread
+ * \param status pointer to an integer that will receive the value returned
+ * from the thread function by its 'return', or NULL to not
+ * receive such value back.
+ *
+ * \sa SDL_CreateThread
+ * \sa SDL_DetachThread
*/
extern DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread * thread, int *status);
/**
- * A thread may be "detached" to signify that it should not remain until
- * another thread has called SDL_WaitThread() on it. Detaching a thread
- * is useful for long-running threads that nothing needs to synchronize
- * with or further manage. When a detached thread is done, it simply
- * goes away.
- *
- * There is no way to recover the return code of a detached thread. If you
- * need this, don't detach the thread and instead use SDL_WaitThread().
- *
- * Once a thread is detached, you should usually assume the SDL_Thread isn't
- * safe to reference again, as it will become invalid immediately upon
- * the detached thread's exit, instead of remaining until someone has called
- * SDL_WaitThread() to finally clean it up. As such, don't detach the same
- * thread more than once.
- *
- * If a thread has already exited when passed to SDL_DetachThread(), it will
- * stop waiting for a call to SDL_WaitThread() and clean up immediately.
- * It is not safe to detach a thread that might be used with SDL_WaitThread().
- *
- * You may not call SDL_WaitThread() on a thread that has been detached.
- * Use either that function or this one, but not both, or behavior is
- * undefined.
- *
- * It is safe to pass NULL to this function; it is a no-op.
+ * Let a thread clean up on exit without intervention.
+ *
+ * A thread may be "detached" to signify that it should not remain until
+ * another thread has called SDL_WaitThread() on it. Detaching a thread is
+ * useful for long-running threads that nothing needs to synchronize with or
+ * further manage. When a detached thread is done, it simply goes away.
+ *
+ * There is no way to recover the return code of a detached thread. If you
+ * need this, don't detach the thread and instead use SDL_WaitThread().
+ *
+ * Once a thread is detached, you should usually assume the SDL_Thread isn't
+ * safe to reference again, as it will become invalid immediately upon the
+ * detached thread's exit, instead of remaining until someone has called
+ * SDL_WaitThread() to finally clean it up. As such, don't detach the same
+ * thread more than once.
+ *
+ * If a thread has already exited when passed to SDL_DetachThread(), it will
+ * stop waiting for a call to SDL_WaitThread() and clean up immediately. It is
+ * not safe to detach a thread that might be used with SDL_WaitThread().
+ *
+ * You may not call SDL_WaitThread() on a thread that has been detached. Use
+ * either that function or this one, but not both, or behavior is undefined.
+ *
+ * It is safe to pass NULL to this function; it is a no-op.
+ *
+ * \param thread the SDL_Thread pointer that was returned from the
+ * SDL_CreateThread() call that started this thread
+ *
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \sa SDL_CreateThread
+ * \sa SDL_WaitThread
*/
extern DECLSPEC void SDLCALL SDL_DetachThread(SDL_Thread * thread);
/**
- * \brief Create an identifier that is globally visible to all threads but refers to data that is thread-specific.
- *
- * \return The newly created thread local storage identifier, or 0 on error
- *
- * \code
- * static SDL_SpinLock tls_lock;
- * static SDL_TLSID thread_local_storage;
- *
- * void SetMyThreadData(void *value)
- * {
- * if (!thread_local_storage) {
- * SDL_AtomicLock(&tls_lock);
- * if (!thread_local_storage) {
- * thread_local_storage = SDL_TLSCreate();
- * }
- * SDL_AtomicUnlock(&tls_lock);
- * }
- * SDL_TLSSet(thread_local_storage, value, 0);
- * }
- *
- * void *GetMyThreadData(void)
- * {
- * return SDL_TLSGet(thread_local_storage);
- * }
- * \endcode
- *
- * \sa SDL_TLSGet()
- * \sa SDL_TLSSet()
+ * Create a piece of thread-local storage.
+ *
+ * This creates an identifier that is globally visible to all
+ * threads but refers to data that is thread-specific.
+ *
+ * \returns the newly created thread local storage identifier or 0 on error.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_TLSGet
+ * \sa SDL_TLSSet
*/
extern DECLSPEC SDL_TLSID SDLCALL SDL_TLSCreate(void);
/**
- * \brief Get the value associated with a thread local storage ID for the current thread.
+ * Get the current thread's value associated with a thread local storage ID.
*
- * \param id The thread local storage ID
+ * \param id the thread local storage ID
+ * \returns the value associated with the ID for the current thread or NULL if
+ * no value has been set; call SDL_GetError() for more information.
*
- * \return The value associated with the ID for the current thread, or NULL if no value has been set.
+ * \since This function is available since SDL 2.0.0.
*
- * \sa SDL_TLSCreate()
- * \sa SDL_TLSSet()
+ * \sa SDL_TLSCreate
+ * \sa SDL_TLSSet
*/
extern DECLSPEC void * SDLCALL SDL_TLSGet(SDL_TLSID id);
/**
- * \brief Set the value associated with a thread local storage ID for the current thread.
+ * Set the current thread's value associated with a thread local storage ID.
+ *
+ * The function prototype for `destructor` is:
+ *
+ * ```c
+ * void destructor(void *value)
+ * ```
+ *
+ * where its parameter `value` is what was passed as `value` to SDL_TLSSet().
*
- * \param id The thread local storage ID
- * \param value The value to associate with the ID for the current thread
- * \param destructor A function called when the thread exits, to free the value.
+ * \param id the thread local storage ID
+ * \param value the value to associate with the ID for the current thread
+ * \param destructor a function called when the thread exits, to free the
+ * value
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \return 0 on success, -1 on error
+ * \since This function is available since SDL 2.0.0.
*
- * \sa SDL_TLSCreate()
- * \sa SDL_TLSGet()
+ * \sa SDL_TLSCreate
+ * \sa SDL_TLSGet
*/
extern DECLSPEC int SDLCALL SDL_TLSSet(SDL_TLSID id, const void *value, void (SDLCALL *destructor)(void*));
diff --git a/include/SDL_timer.h b/include/SDL_timer.h
index 66ab2d9..04696dc 100644
--- a/include/SDL_timer.h
+++ b/include/SDL_timer.h
@@ -38,45 +38,75 @@ extern "C" {
#endif
/**
- * \brief Get the number of milliseconds since the SDL library initialization.
+ * Get the number of milliseconds since SDL library initialization.
*
- * \note This value wraps if the program runs for more than ~49 days.
+ * This value wraps if the program runs for more than ~49 days.
+ *
+ * \returns an unsigned 32-bit value representing the number of milliseconds
+ * since the SDL library initialized.
+ *
+ * \sa SDL_TICKS_PASSED
*/
extern DECLSPEC Uint32 SDLCALL SDL_GetTicks(void);
/**
- * \brief Compare SDL ticks values, and return true if A has passed B
+ * Compare SDL ticks values, and return true if `A` has passed `B`.
+ *
+ * For example, if you want to wait 100 ms, you could do this:
*
- * e.g. if you want to wait 100 ms, you could do this:
- * Uint32 timeout = SDL_GetTicks() + 100;
- * while (!SDL_TICKS_PASSED(SDL_GetTicks(), timeout)) {
- * ... do work until timeout has elapsed
- * }
+ * ```c++
+ * Uint32 timeout = SDL_GetTicks() + 100;
+ * while (!SDL_TICKS_PASSED(SDL_GetTicks(), timeout)) {
+ * // ... do work until timeout has elapsed
+ * }
+ * ```
*/
#define SDL_TICKS_PASSED(A, B) ((Sint32)((B) - (A)) <= 0)
/**
- * \brief Get the current value of the high resolution counter
+ * Get the current value of the high resolution counter.
+ *
+ * This function is typically used for profiling.
+ *
+ * The counter values are only meaningful relative to each other. Differences
+ * between values can be converted to times by using
+ * SDL_GetPerformanceFrequency().
+ *
+ * \returns the current counter value.
+ *
+ * \sa SDL_GetPerformanceFrequency
*/
extern DECLSPEC Uint64 SDLCALL SDL_GetPerformanceCounter(void);
/**
- * \brief Get the count per second of the high resolution counter
+ * Get the count per second of the high resolution counter.
+ *
+ * \returns a platform-specific count per second.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetPerformanceCounter
*/
extern DECLSPEC Uint64 SDLCALL SDL_GetPerformanceFrequency(void);
/**
- * \brief Wait a specified number of milliseconds before returning.
+ * Wait a specified number of milliseconds before returning.
+ *
+ * This function waits a specified number of milliseconds before returning. It
+ * waits at least the specified time, but possibly longer due to OS
+ * scheduling.
+ *
+ * \param ms the number of milliseconds to delay
*/
extern DECLSPEC void SDLCALL SDL_Delay(Uint32 ms);
/**
- * Function prototype for the timer callback function.
+ * Function prototype for the timer callback function.
*
- * The callback function is passed the current timer interval and returns
- * the next timer interval. If the returned value is the same as the one
- * passed in, the periodic alarm continues, otherwise a new alarm is
- * scheduled. If the callback returns 0, the periodic alarm is cancelled.
+ * The callback function is passed the current timer interval and returns
+ * the next timer interval. If the returned value is the same as the one
+ * passed in, the periodic alarm continues, otherwise a new alarm is
+ * scheduled. If the callback returns 0, the periodic alarm is cancelled.
*/
typedef Uint32 (SDLCALL * SDL_TimerCallback) (Uint32 interval, void *param);
@@ -86,20 +116,47 @@ typedef Uint32 (SDLCALL * SDL_TimerCallback) (Uint32 interval, void *param);
typedef int SDL_TimerID;
/**
- * \brief Add a new timer to the pool of timers already running.
+ * Call a callback function at a future time.
+ *
+ * If you use this function, you must pass `SDL_INIT_TIMER` to SDL_Init().
+ *
+ * The callback function is passed the current timer interval and the user
+ * supplied parameter from the SDL_AddTimer() call and should return the next
+ * timer interval. If the value returned from the callback is 0, the timer is
+ * canceled.
+ *
+ * The callback is run on a separate thread.
+ *
+ * Timers take into account the amount of time it took to execute the
+ * callback. For example, if the callback took 250 ms to execute and returned
+ * 1000 (ms), the timer would only wait another 750 ms before its next
+ * iteration.
+ *
+ * Timing may be inexact due to OS scheduling. Be sure to note the current
+ * time with SDL_GetTicks() or SDL_GetPerformanceCounter() in case your
+ * callback needs to adjust for variances.
+ *
+ * \param interval the timer delay, in milliseconds, passed to `callback`
+ * \param callback the SDL_TimerCallback function to call when the specified
+ * `interval` elapses
+ * \param param a pointer that is passed to `callback`
+ * \returns a timer ID or 0 if an error occurs; call SDL_GetError() for more
+ * information.
*
- * \return A timer ID, or 0 when an error occurs.
+ * \sa SDL_RemoveTimer
*/
extern DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval,
SDL_TimerCallback callback,
void *param);
/**
- * \brief Remove a timer knowing its ID.
+ * Remove a timer created with SDL_AddTimer().
*
- * \return A boolean value indicating success or failure.
+ * \param id the ID of the timer to remove
+ * \returns SDL_TRUE if the timer is removed or SDL_FALSE if the timer wasn't
+ * found.
*
- * \warning It is not safe to remove a timer multiple times.
+ * \sa SDL_AddTimer
*/
extern DECLSPEC SDL_bool SDLCALL SDL_RemoveTimer(SDL_TimerID id);
diff --git a/include/SDL_touch.h b/include/SDL_touch.h
index 323cd22..f370a67 100644
--- a/include/SDL_touch.h
+++ b/include/SDL_touch.h
@@ -64,30 +64,66 @@ typedef struct SDL_Finger
#define SDL_MOUSE_TOUCHID ((Sint64)-1)
-/* Function prototypes */
-
/**
- * \brief Get the number of registered touch devices.
+ * Get the number of registered touch devices.
+ *
+ * On some platforms SDL first sees the touch device if it was actually used.
+ * Therefore SDL_GetNumTouchDevices() may return 0 although devices are
+ * available. After using all devices at least once the number will be
+ * correct.
+ *
+ * This was fixed for Android in SDL 2.0.1.
+ *
+ * \returns the number of registered touch devices.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetTouchDevice
*/
extern DECLSPEC int SDLCALL SDL_GetNumTouchDevices(void);
/**
- * \brief Get the touch ID with the given index, or 0 if the index is invalid.
+ * Get the touch ID with the given index.
+ *
+ * \param index the touch device index
+ * \returns the touch ID with the given index on success or 0 if the index is
+ * invalid; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetNumTouchDevices
*/
extern DECLSPEC SDL_TouchID SDLCALL SDL_GetTouchDevice(int index);
/**
- * \brief Get the type of the given touch device.
+ * Get the type of the given touch device.
*/
extern DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_TouchID touchID);
/**
- * \brief Get the number of active fingers for a given touch device.
+ * Get the number of active fingers for a given touch device.
+ *
+ * \param touchID the ID of a touch device
+ * \returns the number of active fingers for a given touch device on success
+ * or 0 on failure; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetTouchFinger
*/
extern DECLSPEC int SDLCALL SDL_GetNumTouchFingers(SDL_TouchID touchID);
/**
- * \brief Get the finger object of the given touch, with the given index.
+ * Get the finger object for specified touch device ID and finger index.
+ *
+ * The returned resource is owned by SDL and should not be deallocated.
+ *
+ * \param touchID the ID of the requested touch device
+ * \param index the index of the requested finger
+ * \returns a pointer to the SDL_Finger object or NULL if no object at the
+ * given ID and index could be found.
+ *
+ * \sa SDL_RecordGesture
*/
extern DECLSPEC SDL_Finger * SDLCALL SDL_GetTouchFinger(SDL_TouchID touchID, int index);
diff --git a/include/SDL_version.h b/include/SDL_version.h
index a78ac72..362a0c5 100644
--- a/include/SDL_version.h
+++ b/include/SDL_version.h
@@ -37,16 +37,16 @@ extern "C" {
#endif
/**
- * \brief Information the version of SDL in use.
+ * Information about the version of SDL in use.
*
- * Represents the library's version as three levels: major revision
- * (increments with massive changes, additions, and enhancements),
- * minor revision (increments with backwards-compatible changes to the
- * major revision), and patchlevel (increments with fixes to the minor
- * revision).
+ * Represents the library's version as three levels: major revision
+ * (increments with massive changes, additions, and enhancements),
+ * minor revision (increments with backwards-compatible changes to the
+ * major revision), and patchlevel (increments with fixes to the minor
+ * revision).
*
- * \sa SDL_VERSION
- * \sa SDL_GetVersion
+ * \sa SDL_VERSION
+ * \sa SDL_GetVersion
*/
typedef struct SDL_version
{
@@ -62,19 +62,19 @@ typedef struct SDL_version
#define SDL_PATCHLEVEL 15
/**
- * \brief Macro to determine SDL version program was compiled against.
+ * Macro to determine SDL version program was compiled against.
*
- * This macro fills in a SDL_version structure with the version of the
- * library you compiled against. This is determined by what header the
- * compiler uses. Note that if you dynamically linked the library, you might
- * have a slightly newer or older version at runtime. That version can be
- * determined with SDL_GetVersion(), which, unlike SDL_VERSION(),
- * is not a macro.
+ * This macro fills in a SDL_version structure with the version of the
+ * library you compiled against. This is determined by what header the
+ * compiler uses. Note that if you dynamically linked the library, you might
+ * have a slightly newer or older version at runtime. That version can be
+ * determined with SDL_GetVersion(), which, unlike SDL_VERSION(),
+ * is not a macro.
*
- * \param x A pointer to a SDL_version struct to initialize.
+ * \param x A pointer to a SDL_version struct to initialize.
*
- * \sa SDL_version
- * \sa SDL_GetVersion
+ * \sa SDL_version
+ * \sa SDL_GetVersion
*/
#define SDL_VERSION(x) \
{ \
@@ -107,48 +107,56 @@ typedef struct SDL_version
(SDL_COMPILEDVERSION >= SDL_VERSIONNUM(X, Y, Z))
/**
- * \brief Get the version of SDL that is linked against your program.
+ * Get the version of SDL that is linked against your program.
*
- * If you are linking to SDL dynamically, then it is possible that the
- * current version will be different than the version you compiled against.
- * This function returns the current version, while SDL_VERSION() is a
- * macro that tells you what version you compiled with.
+ * If you are linking to SDL dynamically, then it is possible that the current
+ * version will be different than the version you compiled against. This
+ * function returns the current version, while SDL_VERSION() is a macro that
+ * tells you what version you compiled with.
*
- * \code
- * SDL_version compiled;
- * SDL_version linked;
+ * This function may be called safely at any time, even before SDL_Init().
*
- * SDL_VERSION(&compiled);
- * SDL_GetVersion(&linked);
- * printf("We compiled against SDL version %d.%d.%d ...\n",
- * compiled.major, compiled.minor, compiled.patch);
- * printf("But we linked against SDL version %d.%d.%d.\n",
- * linked.major, linked.minor, linked.patch);
- * \endcode
+ * \param ver the SDL_version structure that contains the version information
*
- * This function may be called safely at any time, even before SDL_Init().
- *
- * \sa SDL_VERSION
+ * \sa SDL_GetRevision
*/
extern DECLSPEC void SDLCALL SDL_GetVersion(SDL_version * ver);
/**
- * \brief Get the code revision of SDL that is linked against your program.
+ * Get the code revision of SDL that is linked against your program.
+ *
+ * This value is the revision of the code you are linked with and may be
+ * different from the code you are compiling with, which is found in the
+ * constant SDL_REVISION.
+ *
+ * The revision is arbitrary string (a hash value) uniquely identifying the
+ * exact revision of the SDL library in use, and is only useful in comparing
+ * against other revisions. It is NOT an incrementing number.
+ *
+ * If SDL wasn't built from a git repository with the appropriate tools, this
+ * will return an empty string.
+ *
+ * Prior to SDL 2.0.16, before development moved to GitHub, this returned a
+ * hash for a Mercurial repository.
+ *
+ * You shouldn't use this function for anything but logging it for debugging
+ * purposes. The string is not intended to be reliable in any way.
+ *
+ * \returns an arbitrary string, uniquely identifying the exact revision of
+ * the SDL library in use.
*
- * Returns an arbitrary string (a hash value) uniquely identifying the
- * exact revision of the SDL library in use, and is only useful in comparing
- * against other revisions. It is NOT an incrementing number.
+ * \sa SDL_GetVersion
*/
extern DECLSPEC const char *SDLCALL SDL_GetRevision(void);
/**
- * \brief Obsolete function, do not use.
+ * Obsolete function, do not use.
*
- * When SDL was hosted in a Mercurial repository, and was built carefully,
- * this would return the revision number that the build was created from.
- * This number was not reliable for several reasons, but more importantly,
- * SDL is now hosted in a git repository, which does not offer numbers at
- * all, only hashes. This function only ever returns zero now. Don't use it.
+ * When SDL was hosted in a Mercurial repository, and was built carefully,
+ * this would return the revision number that the build was created from.
+ * This number was not reliable for several reasons, but more importantly,
+ * SDL is now hosted in a git repository, which does not offer numbers at
+ * all, only hashes. This function only ever returns zero now. Don't use it.
*/
extern SDL_DEPRECATED DECLSPEC int SDLCALL SDL_GetRevisionNumber(void);
diff --git a/include/SDL_video.h b/include/SDL_video.h
index 0860ea0..b9e3782 100644
--- a/include/SDL_video.h
+++ b/include/SDL_video.h
@@ -265,798 +265,1137 @@ typedef enum
/* Function prototypes */
/**
- * \brief Get the number of video drivers compiled into SDL
+ * Get the number of video drivers compiled into SDL.
*
- * \sa SDL_GetVideoDriver()
+ * \returns a number >= 1 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_GetVideoDriver
*/
extern DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void);
/**
- * \brief Get the name of a built in video driver.
+ * Get the name of a built in video driver.
+ *
+ * The video drivers are presented in the order in which they are normally
+ * checked during initialization.
*
- * \note The video drivers are presented in the order in which they are
- * normally checked during initialization.
+ * \param index the index of a video driver
+ * \returns the name of the video driver with the given **index**.
*
- * \sa SDL_GetNumVideoDrivers()
+ * \sa SDL_GetNumVideoDrivers
*/
extern DECLSPEC const char *SDLCALL SDL_GetVideoDriver(int index);
/**
- * \brief Initialize the video subsystem, optionally specifying a video driver.
+ * Initialize the video subsystem, optionally specifying a video driver.
+ *
+ * This function initializes the video subsystem, setting up a connection to
+ * the window manager, etc, and determines the available display modes and
+ * pixel formats, but does not initialize a window or graphics mode.
+ *
+ * If you use this function and you haven't used the SDL_INIT_VIDEO flag with
+ * either SDL_Init() or SDL_InitSubSystem(), you should call SDL_VideoQuit()
+ * before calling SDL_Quit().
*
- * \param driver_name Initialize a specific driver by name, or NULL for the
- * default video driver.
+ * It is safe to call this function multiple times. SDL_VideoInit() will call
+ * SDL_VideoQuit() itself if the video subsystem has already been initialized.
*
- * \return 0 on success, -1 on error
+ * You can use SDL_GetNumVideoDrivers() and SDL_GetVideoDriver() to find a
+ * specific `driver_name`.
*
- * This function initializes the video subsystem; setting up a connection
- * to the window manager, etc, and determines the available display modes
- * and pixel formats, but does not initialize a window or graphics mode.
+ * \param driver_name the name of a video driver to initialize, or NULL for
+ * the default driver
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_VideoQuit()
+ * \sa SDL_GetNumVideoDrivers
+ * \sa SDL_GetVideoDriver
+ * \sa SDL_InitSubSystem
+ * \sa SDL_VideoQuit
*/
extern DECLSPEC int SDLCALL SDL_VideoInit(const char *driver_name);
/**
- * \brief Shuts down the video subsystem.
+ * Shut down the video subsystem, if initialized with SDL_VideoInit().
*
- * This function closes all windows, and restores the original video mode.
+ * This function closes all windows, and restores the original video mode.
*
- * \sa SDL_VideoInit()
+ * \sa SDL_VideoInit
*/
extern DECLSPEC void SDLCALL SDL_VideoQuit(void);
/**
- * \brief Returns the name of the currently initialized video driver.
+ * Get the name of the currently initialized video driver.
*
- * \return The name of the current video driver or NULL if no driver
- * has been initialized
+ * \returns the name of the current video driver or NULL if no driver has been
+ * initialized.
*
- * \sa SDL_GetNumVideoDrivers()
- * \sa SDL_GetVideoDriver()
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetNumVideoDrivers
+ * \sa SDL_GetVideoDriver
*/
extern DECLSPEC const char *SDLCALL SDL_GetCurrentVideoDriver(void);
/**
- * \brief Returns the number of available video displays.
+ * Get the number of available video displays.
+ *
+ * \returns a number >= 1 or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
*
- * \sa SDL_GetDisplayBounds()
+ * \sa SDL_GetDisplayBounds
*/
extern DECLSPEC int SDLCALL SDL_GetNumVideoDisplays(void);
/**
- * \brief Get the name of a display in UTF-8 encoding
+ * Get the name of a display in UTF-8 encoding.
*
- * \return The name of a display, or NULL for an invalid display index.
+ * \param displayIndex the index of display from which the name should be
+ * queried
+ * \returns the name of a display or NULL for an invalid display index or
+ * failure; call SDL_GetError() for more information.
*
- * \sa SDL_GetNumVideoDisplays()
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetNumVideoDisplays
*/
extern DECLSPEC const char * SDLCALL SDL_GetDisplayName(int displayIndex);
/**
- * \brief Get the desktop area represented by a display, with the primary
- * display located at 0,0
+ * Get the desktop area represented by a display.
+ *
+ * The primary display (`displayIndex` zero) is always located at 0,0.
*
- * \return 0 on success, or -1 if the index is out of range.
+ * \param displayIndex the index of the display to query
+ * \param rect the SDL_Rect structure filled in with the display bounds
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_GetNumVideoDisplays()
+ * \sa SDL_GetNumVideoDisplays
*/
extern DECLSPEC int SDLCALL SDL_GetDisplayBounds(int displayIndex, SDL_Rect * rect);
/**
- * \brief Get the usable desktop area represented by a display, with the
- * primary display located at 0,0
+ * Get the usable desktop area represented by a display.
+ *
+ * The primary display (`displayIndex` zero) is always located at 0,0.
+ *
+ * This is the same area as SDL_GetDisplayBounds() reports, but with portions
+ * reserved by the system removed. For example, on Apple's macOS, this
+ * subtracts the area occupied by the menu bar and dock.
+ *
+ * Setting a window to be fullscreen generally bypasses these unusable areas,
+ * so these are good guidelines for the maximum space available to a
+ * non-fullscreen window.
+ *
+ * The parameter `rect` is ignored if it is NULL.
*
- * This is the same area as SDL_GetDisplayBounds() reports, but with portions
- * reserved by the system removed. For example, on Mac OS X, this subtracts
- * the area occupied by the menu bar and dock.
+ * This function also returns -1 if the parameter `displayIndex` is out of
+ * range.
*
- * Setting a window to be fullscreen generally bypasses these unusable areas,
- * so these are good guidelines for the maximum space available to a
- * non-fullscreen window.
+ * \param displayIndex the index of the display to query the usable bounds
+ * from
+ * \param rect the SDL_Rect structure filled in with the display bounds
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \return 0 on success, or -1 if the index is out of range.
+ * \since This function is available since SDL 2.0.5.
*
- * \sa SDL_GetDisplayBounds()
- * \sa SDL_GetNumVideoDisplays()
+ * \sa SDL_GetDisplayBounds
+ * \sa SDL_GetNumVideoDisplays
*/
extern DECLSPEC int SDLCALL SDL_GetDisplayUsableBounds(int displayIndex, SDL_Rect * rect);
/**
- * \brief Get the dots/pixels-per-inch for a display
+ * Get the dots/pixels-per-inch for a display.
*
- * \note Diagonal, horizontal and vertical DPI can all be optionally
- * returned if the parameter is non-NULL.
+ * Diagonal, horizontal and vertical DPI can all be optionally returned if the
+ * appropriate parameter is non-NULL.
*
- * \return 0 on success, or -1 if no DPI information is available or the index is out of range.
+ * A failure of this function usually means that either no DPI information is
+ * available or the `displayIndex` is out of range.
*
- * \sa SDL_GetNumVideoDisplays()
+ * \param displayIndex the index of the display from which DPI information
+ * should be queried
+ * \param ddpi a pointer filled in with the diagonal DPI of the display; may
+ * be NULL
+ * \param hdpi a pointer filled in with the horizontal DPI of the display; may
+ * be NULL
+ * \param vdpi a pointer filled in with the vertical DPI of the display; may
+ * be NULL
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.4.
+ *
+ * \sa SDL_GetNumVideoDisplays
*/
extern DECLSPEC int SDLCALL SDL_GetDisplayDPI(int displayIndex, float * ddpi, float * hdpi, float * vdpi);
/**
- * \brief Get the orientation of a display
+ * Get the orientation of a display.
*
- * \return The orientation of the display, or SDL_ORIENTATION_UNKNOWN if it isn't available.
+ * \params displayIndex the index of the display to query
+ * \returns The SDL_DisplayOrientation enum value of the display, or
+ * `SDL_ORIENTATION_UNKNOWN` if it isn't available.
*
- * \sa SDL_GetNumVideoDisplays()
+ * \sa SDL_GetNumVideoDisplays()
*/
extern DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetDisplayOrientation(int displayIndex);
/**
- * \brief Returns the number of available display modes.
+ * Get the number of available display modes.
*
- * \sa SDL_GetDisplayMode()
+ * The `displayIndex` needs to be in the range from 0 to
+ * SDL_GetNumVideoDisplays() - 1.
+ *
+ * \param displayIndex the index of the display to query
+ * \returns a number >= 1 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetDisplayMode
+ * \sa SDL_GetNumVideoDisplays
*/
extern DECLSPEC int SDLCALL SDL_GetNumDisplayModes(int displayIndex);
/**
- * \brief Fill in information about a specific display mode.
+ * Get information about a specific display mode.
*
- * \note The display modes are sorted in this priority:
- * \li bits per pixel -> more colors to fewer colors
- * \li width -> largest to smallest
- * \li height -> largest to smallest
- * \li refresh rate -> highest to lowest
+ * The display modes are sorted in this priority:
*
- * \sa SDL_GetNumDisplayModes()
+ * - width -> largest to smallest
+ *
+ * - height -> largest to smallest
+ *
+ * - bits per pixel -> more colors to fewer colors
+ *
+ * - packed pixel layout -> largest to smallest
+ *
+ * - refresh rate -> highest to lowest
+ *
+ * \param displayIndex the index of the display to query
+ * \param modeIndex the index of the display mode to query
+ * \param mode an SDL_DisplayMode structure filled in with the mode at
+ * `modeIndex`
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_GetNumDisplayModes
*/
extern DECLSPEC int SDLCALL SDL_GetDisplayMode(int displayIndex, int modeIndex,
SDL_DisplayMode * mode);
/**
- * \brief Fill in information about the desktop display mode.
+ * Get information about the desktop's display mode.
+ *
+ * There's a difference between this function and SDL_GetCurrentDisplayMode()
+ * when SDL runs fullscreen and has changed the resolution. In that case this
+ * function will return the previous native display mode, and not the current
+ * display mode.
+ *
+ * \param displayIndex the index of the display to query
+ * \param mode an SDL_DisplayMode structure filled in with the current display
+ * mode
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_GetCurrentDisplayMode
+ * \sa SDL_GetDisplayMode
+ * \sa SDL_SetWindowDisplayMode
*/
extern DECLSPEC int SDLCALL SDL_GetDesktopDisplayMode(int displayIndex, SDL_DisplayMode * mode);
/**
- * \brief Fill in information about the current display mode.
+ * Get information about the current display mode.
+ *
+ * There's a difference between this function and SDL_GetDesktopDisplayMode()
+ * when SDL runs fullscreen and has changed the resolution. In that case this
+ * function will return the current display mode, and not the previous native
+ * display mode.
+ *
+ * \param displayIndex the index of the display to query
+ * \param mode an SDL_DisplayMode structure filled in with the current display
+ * mode
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_GetDesktopDisplayMode
+ * \sa SDL_GetDisplayMode
+ * \sa SDL_GetNumVideoDisplays
+ * \sa SDL_SetWindowDisplayMode
*/
extern DECLSPEC int SDLCALL SDL_GetCurrentDisplayMode(int displayIndex, SDL_DisplayMode * mode);
/**
- * \brief Get the closest match to the requested display mode.
- *
- * \param displayIndex The index of display from which mode should be queried.
- * \param mode The desired display mode
- * \param closest A pointer to a display mode to be filled in with the closest
- * match of the available display modes.
+ * Get the closest match to the requested display mode.
*
- * \return The passed in value \c closest, or NULL if no matching video mode
- * was available.
+ * The available display modes are scanned and `closest` is filled in with
+ * the closest mode matching the requested mode and returned. The mode format
+ * and refresh rate default to the desktop mode if they are set to 0. The
+ * modes are scanned with size being first priority, format being second
+ * priority, and finally checking the refresh rate. If all the available modes
+ * are too small, then NULL is returned.
*
- * The available display modes are scanned, and \c closest is filled in with the
- * closest mode matching the requested mode and returned. The mode format and
- * refresh_rate default to the desktop mode if they are 0. The modes are
- * scanned with size being first priority, format being second priority, and
- * finally checking the refresh_rate. If all the available modes are too
- * small, then NULL is returned.
+ * \param displayIndex the index of the display to query
+ * \param mode an SDL_DisplayMode structure containing the desired display
+ * mode
+ * \param closest an SDL_DisplayMode structure filled in with the closest
+ * match of the available display modes
+ * \returns the passed in value `closest` or NULL if no matching video mode
+ * was available; call SDL_GetError() for more information.
*
- * \sa SDL_GetNumDisplayModes()
- * \sa SDL_GetDisplayMode()
+ * \sa SDL_GetDisplayMode
+ * \sa SDL_GetNumDisplayModes
*/
extern DECLSPEC SDL_DisplayMode * SDLCALL SDL_GetClosestDisplayMode(int displayIndex, const SDL_DisplayMode * mode, SDL_DisplayMode * closest);
/**
- * \brief Get the display index associated with a window.
+ * Get the index of the display associated with a window.
+ *
+ * \param window the window to query
+ * \returns the index of the display containing the center of the window on
+ * success or a negative error code on failure; call SDL_GetError()
+ * for more information.
*
- * \return the display index of the display containing the center of the
- * window, or -1 on error.
+ * \sa SDL_GetDisplayBounds
+ * \sa SDL_GetNumVideoDisplays
*/
extern DECLSPEC int SDLCALL SDL_GetWindowDisplayIndex(SDL_Window * window);
/**
- * \brief Set the display mode used when a fullscreen window is visible.
- *
- * By default the window's dimensions and the desktop format and refresh rate
- * are used.
+ * Set the display mode to use when a window is visible at fullscreen.
*
- * \param window The window for which the display mode should be set.
- * \param mode The mode to use, or NULL for the default mode.
+ * This only affects the display mode used when the window is fullscreen. To
+ * change the window size when the window is not fullscreen, use
+ * SDL_SetWindowSize().
*
- * \return 0 on success, or -1 if setting the display mode failed.
+ * \param window the window to affect
+ * \param mode the SDL_DisplayMode structure representing the mode to use, or
+ * NULL to use the window's dimensions and the desktop's format
+ * and refresh rate
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_GetWindowDisplayMode()
- * \sa SDL_SetWindowFullscreen()
+ * \sa SDL_GetWindowDisplayMode
+ * \sa SDL_SetWindowFullscreen
*/
extern DECLSPEC int SDLCALL SDL_SetWindowDisplayMode(SDL_Window * window,
- const SDL_DisplayMode
- * mode);
+ const SDL_DisplayMode * mode);
/**
- * \brief Fill in information about the display mode used when a fullscreen
- * window is visible.
+ * Query the display mode to use when a window is visible at fullscreen.
*
- * \sa SDL_SetWindowDisplayMode()
- * \sa SDL_SetWindowFullscreen()
+ * \param window the window to query
+ * \param mode an SDL_DisplayMode structure filled in with the fullscreen
+ * display mode
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_SetWindowDisplayMode
+ * \sa SDL_SetWindowFullscreen
*/
extern DECLSPEC int SDLCALL SDL_GetWindowDisplayMode(SDL_Window * window,
SDL_DisplayMode * mode);
/**
- * \brief Get the pixel format associated with the window.
+ * Get the pixel format associated with the window.
+ *
+ * \param window the window to query
+ * \returns the pixel format of the window on success or
+ * SDL_PIXELFORMAT_UNKNOWN on failure; call SDL_GetError() for more
+ * information.
*/
extern DECLSPEC Uint32 SDLCALL SDL_GetWindowPixelFormat(SDL_Window * window);
/**
- * \brief Create a window with the specified position, dimensions, and flags.
+ * Create a window with the specified position, dimensions, and flags.
*
- * \param title The title of the window, in UTF-8 encoding.
- * \param x The x position of the window, ::SDL_WINDOWPOS_CENTERED, or
- * ::SDL_WINDOWPOS_UNDEFINED.
- * \param y The y position of the window, ::SDL_WINDOWPOS_CENTERED, or
- * ::SDL_WINDOWPOS_UNDEFINED.
- * \param w The width of the window, in screen coordinates.
- * \param h The height of the window, in screen coordinates.
- * \param flags The flags for the window, a mask of any of the following:
- * ::SDL_WINDOW_FULLSCREEN, ::SDL_WINDOW_OPENGL,
- * ::SDL_WINDOW_HIDDEN, ::SDL_WINDOW_BORDERLESS,
- * ::SDL_WINDOW_RESIZABLE, ::SDL_WINDOW_MAXIMIZED,
- * ::SDL_WINDOW_MINIMIZED, ::SDL_WINDOW_MOUSE_GRABBED,
- * ::SDL_WINDOW_ALLOW_HIGHDPI, ::SDL_WINDOW_KEYBOARD_GRABBED,
- * ::SDL_WINDOW_VULKAN, ::SDL_WINDOW_METAL.
+ * `flags` may be any of the following OR'd together:
*
- * \return The created window, or NULL if window creation failed.
+ * - `SDL_WINDOW_FULLSCREEN`: fullscreen window
*
- * If the window is created with the SDL_WINDOW_ALLOW_HIGHDPI flag, its size
- * in pixels may differ from its size in screen coordinates on platforms with
- * high-DPI support (e.g. iOS and Mac OS X). Use SDL_GetWindowSize() to query
- * the client area's size in screen coordinates, and SDL_GL_GetDrawableSize(),
- * SDL_Vulkan_GetDrawableSize(), or SDL_GetRendererOutputSize() to query the
- * drawable size in pixels.
+ * - `SDL_WINDOW_FULLSCREEN_DESKTOP: fullscreen window at desktop resolution
*
- * If the window is created with any of the SDL_WINDOW_OPENGL or
- * SDL_WINDOW_VULKAN flags, then the corresponding LoadLibrary function
- * (SDL_GL_LoadLibrary or SDL_Vulkan_LoadLibrary) is called and the
- * corresponding UnloadLibrary function is called by SDL_DestroyWindow().
+ * - `SDL_WINDOW_OPENGL`: window usable with an OpenGL context
*
- * If SDL_WINDOW_VULKAN is specified and there isn't a working Vulkan driver,
- * SDL_CreateWindow() will fail because SDL_Vulkan_LoadLibrary() will fail.
+ * - `SDL_WINDOW_VULKAN`: window usable with a Vulkan instance
*
- * If SDL_WINDOW_METAL is specified on an OS that does not support Metal,
- * SDL_CreateWindow() will fail.
+ * - `SDL_WINDOW_METAL`: window usable with a Metal instance
*
- * \note On non-Apple devices, SDL requires you to either not link to the
- * Vulkan loader or link to a dynamic library version. This limitation
- * may be removed in a future version of SDL.
+ * - `SDL_WINDOW_HIDDEN`: window is not visible
*
- * \sa SDL_DestroyWindow()
- * \sa SDL_GL_LoadLibrary()
- * \sa SDL_Vulkan_LoadLibrary()
+ * - `SDL_WINDOW_BORDERLESS`: no window decoration
+ *
+ * - `SDL_WINDOW_RESIZABLE`: window can be resized
+ *
+ * - `SDL_WINDOW_MINIMIZED`: window is minimized
+ *
+ * - `SDL_WINDOW_MAXIMIZED`: window is maximized
+ *
+ * - `SDL_WINDOW_INPUT_GRABBED`: window has grabbed input focus
+ *
+ * - `SDL_WINDOW_ALLOW_HIGHDPI`: window should be created in high-DPI mode if
+ * supported (>= SDL 2.0.1)
+ *
+ * `SDL_WINDOW_SHOWN` is ignored by SDL_CreateWindow(). The SDL_Window is
+ * implicitly shown if SDL_WINDOW_HIDDEN is not set. `SDL_WINDOW_SHOWN` may be
+ * queried later using SDL_GetWindowFlags().
+ *
+ * On Apple's macOS, you **must** set the NSHighResolutionCapable Info.plist
+ * property to YES, otherwise you will not receive a High-DPI OpenGL canvas.
+ *
+ * If the window is created with the `SDL_WINDOW_ALLOW_HIGHDPI` flag, its size
+ * in pixels may differ from its size in screen coordinates on platforms with
+ * high-DPI support (e.g. iOS and macOS). Use SDL_GetWindowSize() to query
+ * the client area's size in screen coordinates, and SDL_GL_GetDrawableSize()
+ * or SDL_GetRendererOutputSize() to query the drawable size in pixels.
+ *
+ * If the window is set fullscreen, the width and height parameters `w` and
+ * `h` will not be used. However, invalid size parameters (e.g. too large)
+ * may still fail. Window size is actually limited to 16384 x 16384 for all
+ * platforms at window creation.
+ *
+ * If the window is created with any of the SDL_WINDOW_OPENGL or
+ * SDL_WINDOW_VULKAN flags, then the corresponding LoadLibrary function
+ * (SDL_GL_LoadLibrary or SDL_Vulkan_LoadLibrary) is called and the
+ * corresponding UnloadLibrary function is called by SDL_DestroyWindow().
+ *
+ * If SDL_WINDOW_VULKAN is specified and there isn't a working Vulkan driver,
+ * SDL_CreateWindow() will fail because SDL_Vulkan_LoadLibrary() will fail.
+ *
+ * If SDL_WINDOW_METAL is specified on an OS that does not support Metal,
+ * SDL_CreateWindow() will fail.
+ *
+ * On non-Apple devices, SDL requires you to either not link to the Vulkan
+ * loader or link to a dynamic library version. This limitation may be removed
+ * in a future version of SDL.
+ *
+ * \param title the title of the window, in UTF-8 encoding
+ * \param x the x position of the window, `SDL_WINDOWPOS_CENTERED`, or
+ * `SDL_WINDOWPOS_UNDEFINED`
+ * \param y the y position of the window, `SDL_WINDOWPOS_CENTERED`, or
+ * `SDL_WINDOWPOS_UNDEFINED`
+ * \param w the width of the window, in screen coordinates
+ * \param h the height of the window, in screen coordinates
+ * \param flags 0, or one or more SDL_WindowFlags OR'd together
+ * \returns the window that was created or NULL on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_CreateWindowFrom
+ * \sa SDL_DestroyWindow
*/
extern DECLSPEC SDL_Window * SDLCALL SDL_CreateWindow(const char *title,
int x, int y, int w,
int h, Uint32 flags);
/**
- * \brief Create an SDL window from an existing native window.
+ * Create an SDL window from an existing native window.
*
- * \param data A pointer to driver-dependent window creation data
+ * In some cases (e.g. OpenGL) and on some platforms (e.g. Microsoft Windows)
+ * the hint `SDL_HINT_VIDEO_WINDOW_SHARE_PIXEL_FORMAT` needs to be configured
+ * before using SDL_CreateWindowFrom().
*
- * \return The created window, or NULL if window creation failed.
+ * \param data a pointer to driver-dependent window creation data, typically
+ * your native window cast to a void*
+ * \returns the window that was created or NULL on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_DestroyWindow()
+ * \sa SDL_CreateWindow
+ * \sa SDL_DestroyWindow
*/
extern DECLSPEC SDL_Window * SDLCALL SDL_CreateWindowFrom(const void *data);
/**
- * \brief Get the numeric ID of a window, for logging purposes.
+ * Get the numeric ID of a window.
+ *
+ * The numeric ID is what SDL_WindowEvent references, and is necessary to map
+ * these events to specific SDL_Window objects.
+ *
+ * \param window the window to query
+ * \returns the ID of the window on success or 0 on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetWindowFromID
*/
extern DECLSPEC Uint32 SDLCALL SDL_GetWindowID(SDL_Window * window);
/**
- * \brief Get a window from a stored ID, or NULL if it doesn't exist.
+ * Get a window from a stored ID.
+ *
+ * The numeric ID is what SDL_WindowEvent references, and is necessary to map
+ * these events to specific SDL_Window objects.
+ *
+ * \param id the ID of the window
+ * \returns the window associated with `id` or NULL if it doesn't exist;
+ * call SDL_GetError() for more information.
+ *
+ * \sa SDL_GetWindowID
*/
extern DECLSPEC SDL_Window * SDLCALL SDL_GetWindowFromID(Uint32 id);
/**
- * \brief Get the window flags.
+ * Get the window flags.
+ *
+ * \param window the window to query
+ * \returns a mask of the SDL_WindowFlags associated with `window`
+ *
+ * \sa SDL_CreateWindow
+ * \sa SDL_HideWindow
+ * \sa SDL_MaximizeWindow
+ * \sa SDL_MinimizeWindow
+ * \sa SDL_SetWindowFullscreen
+ * \sa SDL_SetWindowGrab
+ * \sa SDL_ShowWindow
*/
extern DECLSPEC Uint32 SDLCALL SDL_GetWindowFlags(SDL_Window * window);
/**
- * \brief Set the title of a window, in UTF-8 format.
+ * Set the title of a window.
*
- * \sa SDL_GetWindowTitle()
+ * This string is expected to be in UTF-8 encoding.
+ *
+ * \param window the window to change
+ * \param title the desired window title in UTF-8 format
+ *
+ * \sa SDL_GetWindowTitle
*/
extern DECLSPEC void SDLCALL SDL_SetWindowTitle(SDL_Window * window,
const char *title);
/**
- * \brief Get the title of a window, in UTF-8 format.
+ * Get the title of a window.
*
- * \sa SDL_SetWindowTitle()
+ * \param window the window to query
+ * \returns the title of the window in UTF-8 format or "" if there is no
+ * title.
+ *
+ * \sa SDL_SetWindowTitle
*/
extern DECLSPEC const char *SDLCALL SDL_GetWindowTitle(SDL_Window * window);
/**
- * \brief Set the icon for a window.
+ * Set the icon for a window.
*
- * \param window The window for which the icon should be set.
- * \param icon The icon for the window.
+ * \param window the window to change
+ * \param icon an SDL_Surface structure containing the icon for the window
*/
extern DECLSPEC void SDLCALL SDL_SetWindowIcon(SDL_Window * window,
SDL_Surface * icon);
/**
- * \brief Associate an arbitrary named pointer with a window.
- *
- * \param window The window to associate with the pointer.
- * \param name The name of the pointer.
- * \param userdata The associated pointer.
+ * Associate an arbitrary named pointer with a window.
*
- * \return The previous value associated with 'name'
+ * `name` is case-sensitive.
*
- * \note The name is case-sensitive.
+ * \param window the window to associate with the pointer
+ * \param name the name of the pointer
+ * \param userdata the associated pointer
+ * \returns the previous value associated with `name`.
*
- * \sa SDL_GetWindowData()
+ * \sa SDL_GetWindowData
*/
extern DECLSPEC void* SDLCALL SDL_SetWindowData(SDL_Window * window,
const char *name,
void *userdata);
/**
- * \brief Retrieve the data pointer associated with a window.
+ * Retrieve the data pointer associated with a window.
*
- * \param window The window to query.
- * \param name The name of the pointer.
+ * \param window the window to query
+ * \param name the name of the pointer
+ * \returns the value associated with `name`.
*
- * \return The value associated with 'name'
- *
- * \sa SDL_SetWindowData()
+ * \sa SDL_SetWindowData
*/
extern DECLSPEC void *SDLCALL SDL_GetWindowData(SDL_Window * window,
const char *name);
/**
- * \brief Set the position of a window.
+ * Set the position of a window.
*
- * \param window The window to reposition.
- * \param x The x coordinate of the window in screen coordinates, or
- * ::SDL_WINDOWPOS_CENTERED or ::SDL_WINDOWPOS_UNDEFINED.
- * \param y The y coordinate of the window in screen coordinates, or
- * ::SDL_WINDOWPOS_CENTERED or ::SDL_WINDOWPOS_UNDEFINED.
+ * The window coordinate origin is the upper left of the display.
*
- * \note The window coordinate origin is the upper left of the display.
+ * \param window the window to reposition
+ * \param x the x coordinate of the window in screen coordinates, or
+ * `SDL_WINDOWPOS_CENTERED` or `SDL_WINDOWPOS_UNDEFINED`
+ * \param y the y coordinate of the window in screen coordinates, or
+ * `SDL_WINDOWPOS_CENTERED` or `SDL_WINDOWPOS_UNDEFINED`
*
- * \sa SDL_GetWindowPosition()
+ * \sa SDL_GetWindowPosition
*/
extern DECLSPEC void SDLCALL SDL_SetWindowPosition(SDL_Window * window,
int x, int y);
/**
- * \brief Get the position of a window.
+ * Get the position of a window.
*
- * \param window The window to query.
- * \param x Pointer to variable for storing the x position, in screen
- * coordinates. May be NULL.
- * \param y Pointer to variable for storing the y position, in screen
- * coordinates. May be NULL.
+ * If you do not need the value for one of the positions a NULL may be passed
+ * in the `x` or `y` parameter.
*
- * \sa SDL_SetWindowPosition()
+ * \param window the window to query
+ * \param x a pointer filled in with the x position of the window, in screen
+ * coordinates, may be NULL
+ * \param y a pointer filled in with the y position of the window, in screen
+ * coordinates, may be NULL
+ *
+ * \sa SDL_SetWindowPosition
*/
extern DECLSPEC void SDLCALL SDL_GetWindowPosition(SDL_Window * window,
int *x, int *y);
/**
- * \brief Set the size of a window's client area.
+ * Set the size of a window's client area.
*
- * \param window The window to resize.
- * \param w The width of the window, in screen coordinates. Must be >0.
- * \param h The height of the window, in screen coordinates. Must be >0.
+ * The window size in screen coordinates may differ from the size in pixels,
+ * if the window was created with `SDL_WINDOW_ALLOW_HIGHDPI` on a platform
+ * with high-dpi support (e.g. iOS or macOS). Use SDL_GL_GetDrawableSize() or
+ * SDL_GetRendererOutputSize() to get the real client area size in pixels.
*
- * \note Fullscreen windows automatically match the size of the display mode,
- * and you should use SDL_SetWindowDisplayMode() to change their size.
+ * Fullscreen windows automatically match the size of the display mode, and
+ * you should use SDL_SetWindowDisplayMode() to change their size.
*
- * The window size in screen coordinates may differ from the size in pixels, if
- * the window was created with SDL_WINDOW_ALLOW_HIGHDPI on a platform with
- * high-dpi support (e.g. iOS or OS X). Use SDL_GL_GetDrawableSize() or
- * SDL_GetRendererOutputSize() to get the real client area size in pixels.
+ * \param window the window to change
+ * \param w the width of the window in pixels, in screen coordinates, must be
+ * > 0
+ * \param h the height of the window in pixels, in screen coordinates, must be
+ * > 0
*
- * \sa SDL_GetWindowSize()
- * \sa SDL_SetWindowDisplayMode()
+ * \sa SDL_GetWindowSize
+ * \sa SDL_SetWindowDisplayMode
*/
extern DECLSPEC void SDLCALL SDL_SetWindowSize(SDL_Window * window, int w,
int h);
/**
- * \brief Get the size of a window's client area.
+ * Get the size of a window's client area.
*
- * \param window The window to query.
- * \param w Pointer to variable for storing the width, in screen
- * coordinates. May be NULL.
- * \param h Pointer to variable for storing the height, in screen
- * coordinates. May be NULL.
+ * NULL can safely be passed as the `w` or `h` parameter if the width or
+ * height value is not desired.
*
- * The window size in screen coordinates may differ from the size in pixels, if
- * the window was created with SDL_WINDOW_ALLOW_HIGHDPI on a platform with
- * high-dpi support (e.g. iOS or OS X). Use SDL_GL_GetDrawableSize() or
- * SDL_GetRendererOutputSize() to get the real client area size in pixels.
+ * The window size in screen coordinates may differ from the size in pixels,
+ * if the window was created with `SDL_WINDOW_ALLOW_HIGHDPI` on a platform
+ * with high-dpi support (e.g. iOS or macOS). Use SDL_GL_GetDrawableSize(),
+ * SDL_Vulkan_GetDrawableSize(), or SDL_GetRendererOutputSize() to get the
+ * real client area size in pixels.
*
- * \sa SDL_SetWindowSize()
+ * \param window the window to query the width and height from
+ * \param w a pointer filled in with the width of the window, in screen
+ * coordinates, may be NULL
+ * \param h a pointer filled in with the height of the window, in screen
+ * coordinates, may be NULL
+ *
+ * \sa SDL_GL_GetDrawableSize
+ * \sa SDL_Vulkan_GetDrawableSize
+ * \sa SDL_SetWindowSize
*/
extern DECLSPEC void SDLCALL SDL_GetWindowSize(SDL_Window * window, int *w,
int *h);
/**
- * \brief Get the size of a window's borders (decorations) around the client area.
+ * Get the size of a window's borders (decorations) around the client area.
*
- * \param window The window to query.
- * \param top Pointer to variable for storing the size of the top border. NULL is permitted.
- * \param left Pointer to variable for storing the size of the left border. NULL is permitted.
- * \param bottom Pointer to variable for storing the size of the bottom border. NULL is permitted.
- * \param right Pointer to variable for storing the size of the right border. NULL is permitted.
+ * Note: If this function fails (returns -1), the size values will be
+ * initialized to 0, 0, 0, 0 (if a non-NULL pointer is provided), as if the
+ * window in question was borderless.
*
- * \return 0 on success, or -1 if getting this information is not supported.
+ * This function also returns -1 if getting the information is not supported.
*
- * \note if this function fails (returns -1), the size values will be
- * initialized to 0, 0, 0, 0 (if a non-NULL pointer is provided), as
- * if the window in question was borderless.
+ * \param window the window to query the size values of the border
+ * (decorations) from
+ * \param top pointer to variable for storing the size of the top border; NULL
+ * is permitted
+ * \param left pointer to variable for storing the size of the left border;
+ * NULL is permitted
+ * \param bottom pointer to variable for storing the size of the bottom
+ * border; NULL is permitted
+ * \param right pointer to variable for storing the size of the right border;
+ * NULL is permitted
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.5.
+ *
+ * \sa SDL_GetWindowSize
*/
extern DECLSPEC int SDLCALL SDL_GetWindowBordersSize(SDL_Window * window,
int *top, int *left,
int *bottom, int *right);
/**
- * \brief Set the minimum size of a window's client area.
- *
- * \param window The window to set a new minimum size.
- * \param min_w The minimum width of the window, must be >0
- * \param min_h The minimum height of the window, must be >0
+ * Set the minimum size of a window's client area.
*
- * \note You can't change the minimum size of a fullscreen window, it
- * automatically matches the size of the display mode.
+ * \param window the window to change
+ * \param min_w the minimum width of the window in pixels
+ * \param min_h the minimum height of the window in pixels
*
- * \sa SDL_GetWindowMinimumSize()
- * \sa SDL_SetWindowMaximumSize()
+ * \sa SDL_GetWindowMinimumSize
+ * \sa SDL_SetWindowMaximumSize
*/
extern DECLSPEC void SDLCALL SDL_SetWindowMinimumSize(SDL_Window * window,
int min_w, int min_h);
/**
- * \brief Get the minimum size of a window's client area.
+ * Get the minimum size of a window's client area.
*
- * \param window The window to query.
- * \param w Pointer to variable for storing the minimum width, may be NULL
- * \param h Pointer to variable for storing the minimum height, may be NULL
+ * \param window the window to query
+ * \param w a pointer filled in with the minimum width of the window, may be
+ * NULL
+ * \param h a pointer filled in with the minimum height of the window, may be
+ * NULL
*
- * \sa SDL_GetWindowMaximumSize()
- * \sa SDL_SetWindowMinimumSize()
+ * \sa SDL_GetWindowMaximumSize
+ * \sa SDL_SetWindowMinimumSize
*/
extern DECLSPEC void SDLCALL SDL_GetWindowMinimumSize(SDL_Window * window,
int *w, int *h);
/**
- * \brief Set the maximum size of a window's client area.
+ * Set the maximum size of a window's client area.
*
- * \param window The window to set a new maximum size.
- * \param max_w The maximum width of the window, must be >0
- * \param max_h The maximum height of the window, must be >0
+ * \param window the window to change
+ * \param max_w the maximum width of the window in pixels
+ * \param max_h the maximum height of the window in pixels
*
- * \note You can't change the maximum size of a fullscreen window, it
- * automatically matches the size of the display mode.
- *
- * \sa SDL_GetWindowMaximumSize()
- * \sa SDL_SetWindowMinimumSize()
+ * \sa SDL_GetWindowMaximumSize
+ * \sa SDL_SetWindowMinimumSize
*/
extern DECLSPEC void SDLCALL SDL_SetWindowMaximumSize(SDL_Window * window,
int max_w, int max_h);
/**
- * \brief Get the maximum size of a window's client area.
+ * Get the maximum size of a window's client area.
*
- * \param window The window to query.
- * \param w Pointer to variable for storing the maximum width, may be NULL
- * \param h Pointer to variable for storing the maximum height, may be NULL
+ * \param window the window to query
+ * \param w a pointer filled in with the maximum width of the window, may be
+ * NULL
+ * \param h a pointer filled in with the maximum height of the window, may be
+ * NULL
*
- * \sa SDL_GetWindowMinimumSize()
- * \sa SDL_SetWindowMaximumSize()
+ * \sa SDL_GetWindowMinimumSize
+ * \sa SDL_SetWindowMaximumSize
*/
extern DECLSPEC void SDLCALL SDL_GetWindowMaximumSize(SDL_Window * window,
int *w, int *h);
/**
- * \brief Set the border state of a window.
+ * Set the border state of a window.
*
- * This will add or remove the window's SDL_WINDOW_BORDERLESS flag and
- * add or remove the border from the actual window. This is a no-op if the
- * window's border already matches the requested state.
+ * This will add or remove the window's `SDL_WINDOW_BORDERLESS` flag and add
+ * or remove the border from the actual window. This is a no-op if the
+ * window's border already matches the requested state.
*
- * \param window The window of which to change the border state.
- * \param bordered SDL_FALSE to remove border, SDL_TRUE to add border.
+ * You can't change the border state of a fullscreen window.
*
- * \note You can't change the border state of a fullscreen window.
+ * \param window the window of which to change the border state
+ * \param bordered SDL_FALSE to remove border, SDL_TRUE to add border
*
- * \sa SDL_GetWindowFlags()
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetWindowFlags
*/
extern DECLSPEC void SDLCALL SDL_SetWindowBordered(SDL_Window * window,
SDL_bool bordered);
/**
- * \brief Set the user-resizable state of a window.
+ * Set the user-resizable state of a window.
*
- * This will add or remove the window's SDL_WINDOW_RESIZABLE flag and
- * allow/disallow user resizing of the window. This is a no-op if the
- * window's resizable state already matches the requested state.
+ * This will add or remove the window's `SDL_WINDOW_RESIZABLE` flag and
+ * allow/disallow user resizing of the window. This is a no-op if the window's
+ * resizable state already matches the requested state.
*
- * \param window The window of which to change the resizable state.
- * \param resizable SDL_TRUE to allow resizing, SDL_FALSE to disallow.
+ * You can't change the resizable state of a fullscreen window.
*
- * \note You can't change the resizable state of a fullscreen window.
+ * \param window the window of which to change the resizable state
+ * \param resizable SDL_TRUE to allow resizing, SDL_FALSE to disallow
*
- * \sa SDL_GetWindowFlags()
+ * \since This function is available since SDL 2.0.5.
+ *
+ * \sa SDL_GetWindowFlags
*/
extern DECLSPEC void SDLCALL SDL_SetWindowResizable(SDL_Window * window,
SDL_bool resizable);
/**
- * \brief Show a window.
+ * Show a window.
*
- * \sa SDL_HideWindow()
+ * \param window the window to show
+ *
+ * \sa SDL_HideWindow
+ * \sa SDL_RaiseWindow
*/
extern DECLSPEC void SDLCALL SDL_ShowWindow(SDL_Window * window);
/**
- * \brief Hide a window.
+ * Hide a window.
*
- * \sa SDL_ShowWindow()
+ * \param window the window to hide
+ *
+ * \sa SDL_ShowWindow
*/
extern DECLSPEC void SDLCALL SDL_HideWindow(SDL_Window * window);
/**
- * \brief Raise a window above other windows and set the input focus.
+ * Raise a window above other windows and set the input focus.
+ *
+ * \param window the window to raise
*/
extern DECLSPEC void SDLCALL SDL_RaiseWindow(SDL_Window * window);
/**
- * \brief Make a window as large as possible.
+ * Make a window as large as possible.
*
- * \sa SDL_RestoreWindow()
+ * \param window the window to maximize
+ *
+ * \sa SDL_MinimizeWindow
+ * \sa SDL_RestoreWindow
*/
extern DECLSPEC void SDLCALL SDL_MaximizeWindow(SDL_Window * window);
/**
- * \brief Minimize a window to an iconic representation.
+ * Minimize a window to an iconic representation.
*
- * \sa SDL_RestoreWindow()
+ * \param window the window to minimize
+ *
+ * \sa SDL_MaximizeWindow
+ * \sa SDL_RestoreWindow
*/
extern DECLSPEC void SDLCALL SDL_MinimizeWindow(SDL_Window * window);
/**
- * \brief Restore the size and position of a minimized or maximized window.
+ * Restore the size and position of a minimized or maximized window.
*
- * \sa SDL_MaximizeWindow()
- * \sa SDL_MinimizeWindow()
+ * *You can add useful comments here*
+ *
+ * \param window the window to restore
+ *
+ * \sa SDL_MaximizeWindow
+ * \sa SDL_MinimizeWindow
*/
extern DECLSPEC void SDLCALL SDL_RestoreWindow(SDL_Window * window);
/**
- * \brief Set a window's fullscreen state.
+ * Set a window's fullscreen state.
*
- * \return 0 on success, or -1 if setting the display mode failed.
+ * `flags` may be `SDL_WINDOW_FULLSCREEN`, for "real" fullscreen with a
+ * videomode change; `SDL_WINDOW_FULLSCREEN_DESKTOP` for "fake" fullscreen
+ * that takes the size of the desktop; and 0 for windowed mode.
*
- * \sa SDL_SetWindowDisplayMode()
- * \sa SDL_GetWindowDisplayMode()
+ * \param window the window to change
+ * \param flags `SDL_WINDOW_FULLSCREEN`, `SDL_WINDOW_FULLSCREEN_DESKTOP` or 0
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetWindowDisplayMode
+ * \sa SDL_SetWindowDisplayMode
*/
extern DECLSPEC int SDLCALL SDL_SetWindowFullscreen(SDL_Window * window,
Uint32 flags);
/**
- * \brief Get the SDL surface associated with the window.
+ * Get the SDL surface associated with the window.
*
- * \return The window's framebuffer surface, or NULL on error.
+ * A new surface will be created with the optimal format for the window, if
+ * necessary. This surface will be freed when the window is destroyed. Do not
+ * free this surface.
*
- * A new surface will be created with the optimal format for the window,
- * if necessary. This surface will be freed when the window is destroyed.
+ * This surface will be invalidated if the window is resized. After resizing a
+ * window this function must be called again to return a valid surface.
*
- * \note You may not combine this with 3D or the rendering API on this window.
+ * You may not combine this with 3D or the rendering API on this window.
*
- * \sa SDL_UpdateWindowSurface()
- * \sa SDL_UpdateWindowSurfaceRects()
+ * This function is affected by `SDL_HINT_FRAMEBUFFER_ACCELERATION`.
+ *
+ * \param window the window to query
+ * \returns the surface associated with the window, or NULL on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_UpdateWindowSurface
+ * \sa SDL_UpdateWindowSurfaceRects
*/
extern DECLSPEC SDL_Surface * SDLCALL SDL_GetWindowSurface(SDL_Window * window);
/**
- * \brief Copy the window surface to the screen.
+ * Copy the window surface to the screen.
+ *
+ * This is the function you use to reflect any changes to the surface on the
+ * screen.
*
- * \return 0 on success, or -1 on error.
+ * This function is equivalent to the SDL 1.2 API SDL_Flip().
*
- * \sa SDL_GetWindowSurface()
- * \sa SDL_UpdateWindowSurfaceRects()
+ * \param window the window to update
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_GetWindowSurface
+ * \sa SDL_UpdateWindowSurfaceRects
*/
extern DECLSPEC int SDLCALL SDL_UpdateWindowSurface(SDL_Window * window);
/**
- * \brief Copy a number of rectangles on the window surface to the screen.
+ * Copy areas of the window surface to the screen.
+ *
+ * This is the function you use to reflect changes to portions of the surface
+ * on the screen.
+ *
+ * This function is equivalent to the SDL 1.2 API SDL_UpdateRects().
*
- * \return 0 on success, or -1 on error.
+ * \param window the window to update
+ * \param rects an array of SDL_Rect structures representing areas of the
+ * surface to copy
+ * \param numrects the number of rectangles
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_GetWindowSurface()
- * \sa SDL_UpdateWindowSurface()
+ * \sa SDL_GetWindowSurface
+ * \sa SDL_UpdateWindowSurface
*/
extern DECLSPEC int SDLCALL SDL_UpdateWindowSurfaceRects(SDL_Window * window,
const SDL_Rect * rects,
int numrects);
/**
- * \brief Set a window's input grab mode.
+ * Set a window's input grab mode.
*
- * \param window The window for which the input grab mode should be set.
- * \param grabbed This is SDL_TRUE to grab input, and SDL_FALSE to release input.
+ * When input is grabbed the mouse is confined to the window.
*
- * If the caller enables a grab while another window is currently grabbed,
- * the other window loses its grab in favor of the caller's window.
+ * If the caller enables a grab while another window is currently grabbed, the
+ * other window loses its grab in favor of the caller's window.
*
- * If SDL_HINT_GRAB_KEYBOARD=1, this also grabs keyboard input.
+ * \param window the window for which the input grab mode should be set
+ * \param grabbed SDL_TRUE to grab input or SDL_FALSE to release input
*
- * \sa SDL_GetWindowGrab()
- * \sa SDL_SetWindowKeyboardGrab()
- * \sa SDL_SetWindowMouseGrab()
+ * \sa SDL_GetGrabbedWindow
+ * \sa SDL_GetWindowGrab
*/
extern DECLSPEC void SDLCALL SDL_SetWindowGrab(SDL_Window * window,
SDL_bool grabbed);
/**
- * \brief Set a window's keyboard grab mode.
+ * Set a window's keyboard grab mode.
*
- * \param window The window for which the keyboard grab mode should be set.
- * \param grabbed This is SDL_TRUE to grab keyboard, and SDL_FALSE to release keyboard grab.
+ * If the caller enables a grab while another window is currently grabbed,
+ * the other window loses its grab in favor of the caller's window.
*
- * If the caller enables a grab while another window is currently grabbed,
- * the other window loses its grab in favor of the caller's window.
+ * \param window The window for which the keyboard grab mode should be set.
+ * \param grabbed This is SDL_TRUE to grab keyboard, and SDL_FALSE to release.
*
- * \sa SDL_GetWindowKeyboardGrab()
- * \sa SDL_SetWindowMouseGrab()
- * \sa SDL_SetWindowGrab()
+ * \sa SDL_GetWindowKeyboardGrab
+ * \sa SDL_SetWindowMouseGrab
+ * \sa SDL_SetWindowGrab
*/
extern DECLSPEC void SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window * window,
SDL_bool grabbed);
/**
- * \brief Set a window's mouse grab mode.
+ * Set a window's mouse grab mode.
*
- * \param window The window for which the mouse grab mode should be set.
- * \param grabbed This is SDL_TRUE to grab mouse, and SDL_FALSE to release mouse grab.
+ * \param window The window for which the mouse grab mode should be set.
+ * \param grabbed This is SDL_TRUE to grab mouse, and SDL_FALSE to release.
*
- * If the caller enables a grab while another window is currently grabbed,
- * the other window loses its grab in favor of the caller's window.
+ * If the caller enables a grab while another window is currently grabbed,
+ * the other window loses its grab in favor of the caller's window.
*
- * \sa SDL_GetWindowMouseGrab()
- * \sa SDL_SetWindowKeyboardGrab()
- * \sa SDL_SetWindowGrab()
+ * \sa SDL_GetWindowMouseGrab
+ * \sa SDL_SetWindowKeyboardGrab
+ * \sa SDL_SetWindowGrab
*/
extern DECLSPEC void SDLCALL SDL_SetWindowMouseGrab(SDL_Window * window,
SDL_bool grabbed);
/**
- * \brief Get a window's input grab mode.
+ * Get a window's input grab mode.
*
- * \return This returns SDL_TRUE if keyboard or mouse input is grabbed, and SDL_FALSE otherwise.
+ * \param window the window to query
+ * \returns SDL_TRUE if input is grabbed, SDL_FALSE otherwise.
*
- * \sa SDL_SetWindowGrab()
- * \sa SDL_GetWindowMouseGrab()
- * \sa SDL_GetWindowKeyboardGrab()
+ * \sa SDL_SetWindowGrab
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowGrab(SDL_Window * window);
/**
- * \brief Get a window's keyboard grab mode.
+ * Get a window's keyboard grab mode.
*
- * \return This returns SDL_TRUE if keyboard is grabbed, and SDL_FALSE otherwise.
+ * \param window the window to query
+ * \returns SDL_TRUE if keyboard is grabbed, and SDL_FALSE otherwise.
*
- * \sa SDL_SetWindowKeyboardGrab()
- * \sa SDL_GetWindowGrab()
+ * \sa SDL_SetWindowKeyboardGrab
+ * \sa SDL_GetWindowGrab
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowKeyboardGrab(SDL_Window * window);
/**
- * \brief Get a window's mouse grab mode.
+ * Get a window's mouse grab mode.
*
- * \return This returns SDL_TRUE if mouse is grabbed, and SDL_FALSE otherwise.
+ * \param window the window to query
+ * \returns This returns SDL_TRUE if mouse is grabbed, and SDL_FALSE otherwise.
*
- * \sa SDL_SetWindowKeyboardGrab()
- * \sa SDL_GetWindowGrab()
+ * \sa SDL_SetWindowKeyboardGrab
+ * \sa SDL_GetWindowGrab
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowMouseGrab(SDL_Window * window);
/**
- * \brief Get the window that currently has an input grab enabled.
+ * Get the window that currently has an input grab enabled.
*
- * \return This returns the window if input is grabbed, and NULL otherwise.
+ * \returns the window if input is grabbed or NULL otherwise.
*
- * \sa SDL_SetWindowGrab()
+ * \since This function is available since SDL 2.0.4.
+ *
+ * \sa SDL_GetWindowGrab
+ * \sa SDL_SetWindowGrab
*/
extern DECLSPEC SDL_Window * SDLCALL SDL_GetGrabbedWindow(void);
/**
- * \brief Set the brightness (gamma correction) for a window.
+ * Set the brightness (gamma multiplier) for a given window's display.
*
- * \return 0 on success, or -1 if setting the brightness isn't supported.
+ * Despite the name and signature, this method sets the brightness of the
+ * entire display, not an individual window. A window is considered to be
+ * owned by the display that contains the window's center pixel. (The index of
+ * this display can be retrieved using SDL_GetWindowDisplayIndex().) The
+ * brightness set will not follow the window if it is moved to another
+ * display.
*
- * \sa SDL_GetWindowBrightness()
- * \sa SDL_SetWindowGammaRamp()
+ * Many platforms will refuse to set the display brightness in modern times.
+ * You are better off using a shader to adjust gamma during rendering, or
+ * something similar.
+ *
+ * \param window the window used to select the display whose brightness will
+ * be changed
+ * \param brightness the brightness (gamma multiplier) value to set where 0.0
+ * is completely dark and 1.0 is normal brightness
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_GetWindowBrightness
+ * \sa SDL_SetWindowGammaRamp
*/
extern DECLSPEC int SDLCALL SDL_SetWindowBrightness(SDL_Window * window, float brightness);
/**
- * \brief Get the brightness (gamma correction) for a window.
+ * Get the brightness (gamma multiplier) for a given window's display.
+ *
+ * Despite the name and signature, this method retrieves the brightness of the
+ * entire display, not an individual window. A window is considered to be
+ * owned by the display that contains the window's center pixel. (The index of
+ * this display can be retrieved using SDL_GetWindowDisplayIndex().)
*
- * \return The last brightness value passed to SDL_SetWindowBrightness()
+ * \param window the window used to select the display whose brightness will
+ * be queried
+ * \returns the brightness for the display where 0.0 is completely dark and
+ * 1.0 is normal brightness.
*
- * \sa SDL_SetWindowBrightness()
+ * \sa SDL_SetWindowBrightness
*/
extern DECLSPEC float SDLCALL SDL_GetWindowBrightness(SDL_Window * window);
/**
- * \brief Set the opacity for a window
+ * Set the opacity for a window.
*
- * \param window The window which will be made transparent or opaque
- * \param opacity Opacity (0.0f - transparent, 1.0f - opaque) This will be
- * clamped internally between 0.0f and 1.0f.
+ * The parameter `opacity` will be clamped internally between 0.0f
+ * (transparent) and 1.0f (opaque).
*
- * \return 0 on success, or -1 if setting the opacity isn't supported.
+ * This function also returns -1 if setting the opacity isn't supported.
*
- * \sa SDL_GetWindowOpacity()
+ * \param window the window which will be made transparent or opaque
+ * \param opacity the opacity value (0.0f - transparent, 1.0f - opaque)
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.5.
+ *
+ * \sa SDL_GetWindowOpacity
*/
extern DECLSPEC int SDLCALL SDL_SetWindowOpacity(SDL_Window * window, float opacity);
/**
- * \brief Get the opacity of a window.
+ * Get the opacity of a window.
+ *
+ * If transparency isn't supported on this platform, opacity will be reported
+ * as 1.0f without error.
*
- * If transparency isn't supported on this platform, opacity will be reported
- * as 1.0f without error.
+ * The parameter `opacity` is ignored if it is NULL.
*
- * \param window The window in question.
- * \param out_opacity Opacity (0.0f - transparent, 1.0f - opaque)
+ * This function also returns -1 if an invalid window was provided.
*
- * \return 0 on success, or -1 on error (invalid window, etc).
+ * \param window the window to get the current opacity value from
+ * \param opacity the float filled in (0.0f - transparent, 1.0f - opaque)
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_SetWindowOpacity()
+ * \since This function is available since SDL 2.0.5.
+ *
+ * \sa SDL_SetWindowOpacity
*/
extern DECLSPEC int SDLCALL SDL_GetWindowOpacity(SDL_Window * window, float * out_opacity);
/**
- * \brief Sets the window as a modal for another window (TODO: reconsider this function and/or its name)
+ * Set the window as a modal for another window.
*
- * \param modal_window The window that should be modal
- * \param parent_window The parent window
+ * \param modal_window the window that should be set modal
+ * \param parent_window the parent window for the modal window
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \return 0 on success, or -1 otherwise.
+ * \since This function is available since SDL 2.0.5.
*/
extern DECLSPEC int SDLCALL SDL_SetWindowModalFor(SDL_Window * modal_window, SDL_Window * parent_window);
/**
- * \brief Explicitly sets input focus to the window.
+ * Explicitly set input focus to the window.
*
- * You almost certainly want SDL_RaiseWindow() instead of this function. Use
- * this with caution, as you might give focus to a window that's completely
- * obscured by other windows.
+ * You almost certainly want SDL_RaiseWindow() instead of this function. Use
+ * this with caution, as you might give focus to a window that is completely
+ * obscured by other windows.
*
- * \param window The window that should get the input focus
+ * \param window the window that should get the input focus
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \return 0 on success, or -1 otherwise.
- * \sa SDL_RaiseWindow()
+ * \since This function is available since SDL 2.0.5.
+ *
+ * \sa SDL_RaiseWindow
*/
extern DECLSPEC int SDLCALL SDL_SetWindowInputFocus(SDL_Window * window);
/**
- * \brief Set the gamma ramp for a window.
- *
- * \param window The window for which the gamma ramp should be set.
- * \param red The translation table for the red channel, or NULL.
- * \param green The translation table for the green channel, or NULL.
- * \param blue The translation table for the blue channel, or NULL.
- *
- * \return 0 on success, or -1 if gamma ramps are unsupported.
- *
- * Set the gamma translation table for the red, green, and blue channels
- * of the video hardware. Each table is an array of 256 16-bit quantities,
- * representing a mapping between the input and output for that channel.
- * The input is the index into the array, and the output is the 16-bit
- * gamma value at that index, scaled to the output color precision.
- *
- * \sa SDL_GetWindowGammaRamp()
+ * Set the gamma ramp for the display that owns a given window.
+ *
+ * Set the gamma translation table for the red, green, and blue channels of
+ * the video hardware. Each table is an array of 256 16-bit quantities,
+ * representing a mapping between the input and output for that channel. The
+ * input is the index into the array, and the output is the 16-bit gamma value
+ * at that index, scaled to the output color precision. Despite the name and
+ * signature, this method sets the gamma ramp of the entire display, not an
+ * individual window. A window is considered to be owned by the display that
+ * contains the window's center pixel. (The index of this display can be
+ * retrieved using SDL_GetWindowDisplayIndex().) The gamma ramp set will not
+ * follow the window if it is moved to another display.
+ *
+ * \param window the window used to select the display whose gamma ramp will
+ * be changed
+ * \param red a 256 element array of 16-bit quantities representing the
+ * translation table for the red channel, or NULL
+ * \param green a 256 element array of 16-bit quantities representing the
+ * translation table for the green channel, or NULL
+ * \param blue a 256 element array of 16-bit quantities representing the
+ * translation table for the blue channel, or NULL
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_GetWindowGammaRamp
*/
extern DECLSPEC int SDLCALL SDL_SetWindowGammaRamp(SDL_Window * window,
const Uint16 * red,
@@ -1064,19 +1403,25 @@ extern DECLSPEC int SDLCALL SDL_SetWindowGammaRamp(SDL_Window * window,
const Uint16 * blue);
/**
- * \brief Get the gamma ramp for a window.
+ * Get the gamma ramp for a given window's display.
*
- * \param window The window from which the gamma ramp should be queried.
- * \param red A pointer to a 256 element array of 16-bit quantities to hold
- * the translation table for the red channel, or NULL.
- * \param green A pointer to a 256 element array of 16-bit quantities to hold
- * the translation table for the green channel, or NULL.
- * \param blue A pointer to a 256 element array of 16-bit quantities to hold
- * the translation table for the blue channel, or NULL.
+ * Despite the name and signature, this method retrieves the gamma ramp of the
+ * entire display, not an individual window. A window is considered to be
+ * owned by the display that contains the window's center pixel. (The index of
+ * this display can be retrieved using SDL_GetWindowDisplayIndex().)
*
- * \return 0 on success, or -1 if gamma ramps are unsupported.
+ * \param window the window used to select the display whose gamma ramp will
+ * be queried
+ * \param red a 256 element array of 16-bit quantities filled in with the
+ * translation table for the red channel, or NULL
+ * \param green a 256 element array of 16-bit quantities filled in with the
+ * translation table for the green channel, or NULL
+ * \param blue a 256 element array of 16-bit quantities filled in with the
+ * translation table for the blue channel, or NULL
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \sa SDL_SetWindowGammaRamp()
+ * \sa SDL_SetWindowGammaRamp
*/
extern DECLSPEC int SDLCALL SDL_GetWindowGammaRamp(SDL_Window * window,
Uint16 * red,
@@ -1084,9 +1429,9 @@ extern DECLSPEC int SDLCALL SDL_GetWindowGammaRamp(SDL_Window * window,
Uint16 * blue);
/**
- * \brief Possible return values from the SDL_HitTest callback.
+ * Possible return values from the SDL_HitTest callback.
*
- * \sa SDL_HitTest
+ * \sa SDL_HitTest
*/
typedef enum
{
@@ -1103,82 +1448,115 @@ typedef enum
} SDL_HitTestResult;
/**
- * \brief Callback used for hit-testing.
+ * Callback used for hit-testing.
+ *
+ * \param win the SDL_Window where hit-testing was set on
+ * \param area an SDL_Point which should be hit-tested
+ * \param data what was passed as `callback_data` to SDL_SetWindowHitTest()
+ * \return an SDL_HitTestResult value.
*
- * \sa SDL_SetWindowHitTest
+ * \sa SDL_SetWindowHitTest
*/
typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win,
const SDL_Point *area,
void *data);
/**
- * \brief Provide a callback that decides if a window region has special properties.
+ * Provide a callback that decides if a window region has special properties.
*
- * Normally windows are dragged and resized by decorations provided by the
- * system window manager (a title bar, borders, etc), but for some apps, it
- * makes sense to drag them from somewhere else inside the window itself; for
- * example, one might have a borderless window that wants to be draggable
- * from any part, or simulate its own title bar, etc.
+ * Normally windows are dragged and resized by decorations provided by the
+ * system window manager (a title bar, borders, etc), but for some apps, it
+ * makes sense to drag them from somewhere else inside the window itself; for
+ * example, one might have a borderless window that wants to be draggable from
+ * any part, or simulate its own title bar, etc.
*
- * This function lets the app provide a callback that designates pieces of
- * a given window as special. This callback is run during event processing
- * if we need to tell the OS to treat a region of the window specially; the
- * use of this callback is known as "hit testing."
+ * This function lets the app provide a callback that designates pieces of a
+ * given window as special. This callback is run during event processing if we
+ * need to tell the OS to treat a region of the window specially; the use of
+ * this callback is known as "hit testing."
*
- * Mouse input may not be delivered to your application if it is within
- * a special area; the OS will often apply that input to moving the window or
- * resizing the window and not deliver it to the application.
+ * Mouse input may not be delivered to your application if it is within a
+ * special area; the OS will often apply that input to moving the window or
+ * resizing the window and not deliver it to the application.
*
- * Specifying NULL for a callback disables hit-testing. Hit-testing is
- * disabled by default.
+ * Specifying NULL for a callback disables hit-testing. Hit-testing is
+ * disabled by default.
*
- * Platforms that don't support this functionality will return -1
- * unconditionally, even if you're attempting to disable hit-testing.
+ * Platforms that don't support this functionality will return -1
+ * unconditionally, even if you're attempting to disable hit-testing.
*
- * Your callback may fire at any time, and its firing does not indicate any
- * specific behavior (for example, on Windows, this certainly might fire
- * when the OS is deciding whether to drag your window, but it fires for lots
- * of other reasons, too, some unrelated to anything you probably care about
- * _and when the mouse isn't actually at the location it is testing_).
- * Since this can fire at any time, you should try to keep your callback
- * efficient, devoid of allocations, etc.
+ * Your callback may fire at any time, and its firing does not indicate any
+ * specific behavior (for example, on Windows, this certainly might fire when
+ * the OS is deciding whether to drag your window, but it fires for lots of
+ * other reasons, too, some unrelated to anything you probably care about _and
+ * when the mouse isn't actually at the location it is testing_). Since this
+ * can fire at any time, you should try to keep your callback efficient,
+ * devoid of allocations, etc.
*
- * \param window The window to set hit-testing on.
- * \param callback The callback to call when doing a hit-test.
- * \param callback_data An app-defined void pointer passed to the callback.
- * \return 0 on success, -1 on error (including unsupported).
+ * \param window the window to set hit-testing on
+ * \param callback the function to call when doing a hit-test
+ * \param callback_data an app-defined void pointer passed to **callback**
+ * \returns 0 on success or -1 on error (including unsupported); call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.4.
*/
extern DECLSPEC int SDLCALL SDL_SetWindowHitTest(SDL_Window * window,
SDL_HitTest callback,
void *callback_data);
/**
- * \brief Destroy a window.
+ * Destroy a window.
+ *
+ * If `window` is NULL, this function will return immediately after setting
+ * the SDL error message to "Invalid window". See SDL_GetError().
+ *
+ * \param window the window to destroy
+ *
+ * \sa SDL_CreateWindow
+ * \sa SDL_CreateWindowFrom
*/
extern DECLSPEC void SDLCALL SDL_DestroyWindow(SDL_Window * window);
/**
- * \brief Returns whether the screensaver is currently enabled (default off).
+ * Check whether the screensaver is currently enabled.
+ *
+ * The screensaver is disabled by default since SDL 2.0.2. Before SDL 2.0.2
+ * the screensaver was enabled by default.
*
- * \sa SDL_EnableScreenSaver()
- * \sa SDL_DisableScreenSaver()
+ * The default can also be changed using `SDL_HINT_VIDEO_ALLOW_SCREENSAVER`.
+ *
+ * \returns SDL_TRUE if the screensaver is enabled, SDL_FALSE if it is
+ * disabled.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_DisableScreenSaver
+ * \sa SDL_EnableScreenSaver
*/
extern DECLSPEC SDL_bool SDLCALL SDL_IsScreenSaverEnabled(void);
/**
- * \brief Allow the screen to be blanked by a screensaver
+ * Allow the screen to be blanked by a screen saver.
*
- * \sa SDL_IsScreenSaverEnabled()
- * \sa SDL_DisableScreenSaver()
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_DisableScreenSaver
+ * \sa SDL_IsScreenSaverEnabled
*/
extern DECLSPEC void SDLCALL SDL_EnableScreenSaver(void);
/**
- * \brief Prevent the screen from being blanked by a screensaver
+ * Prevent the screen from being blanked by a screen saver.
+ *
+ * If you disable the screensaver, it is automatically re-enabled when SDL
+ * quits.
+ *
+ * \since This function is available since SDL 2.0.0.
*
- * \sa SDL_IsScreenSaverEnabled()
- * \sa SDL_EnableScreenSaver()
+ * \sa SDL_EnableScreenSaver
+ * \sa SDL_IsScreenSaverEnabled
*/
extern DECLSPEC void SDLCALL SDL_DisableScreenSaver(void);
@@ -1189,147 +1567,304 @@ extern DECLSPEC void SDLCALL SDL_DisableScreenSaver(void);
/* @{ */
/**
- * \brief Dynamically load an OpenGL library.
+ * Dynamically load an OpenGL library.
*
- * \param path The platform dependent OpenGL library name, or NULL to open the
- * default OpenGL library.
+ * This should be done after initializing the video driver, but before
+ * creating any OpenGL windows. If no OpenGL library is loaded, the default
+ * library will be loaded upon creation of the first OpenGL window.
*
- * \return 0 on success, or -1 if the library couldn't be loaded.
+ * If you do this, you need to retrieve all of the GL functions used in your
+ * program from the dynamic library using SDL_GL_GetProcAddress().
*
- * This should be done after initializing the video driver, but before
- * creating any OpenGL windows. If no OpenGL library is loaded, the default
- * library will be loaded upon creation of the first OpenGL window.
+ * \param path the platform dependent OpenGL library name, or NULL to open the
+ * default OpenGL library
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \note If you do this, you need to retrieve all of the GL functions used in
- * your program from the dynamic library using SDL_GL_GetProcAddress().
- *
- * \sa SDL_GL_GetProcAddress()
- * \sa SDL_GL_UnloadLibrary()
+ * \sa SDL_GL_GetProcAddress
+ * \sa SDL_GL_UnloadLibrary
*/
extern DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path);
/**
- * \brief Get the address of an OpenGL function.
+ * Get an OpenGL function by name.
+ *
+ * If the GL library is loaded at runtime with SDL_GL_LoadLibrary(), then all
+ * GL functions must be retrieved this way. Usually this is used to retrieve
+ * function pointers to OpenGL extensions.
+ *
+ * There are some quirks to looking up OpenGL functions that require some
+ * extra care from the application. If you code carefully, you can handle
+ * these quirks without any platform-specific code, though:
+
+ * - On Windows, function pointers are specific to the current GL context;
+ * this means you need to have created a GL context and made it current before
+ * calling SDL_GL_GetProcAddress(). If you recreate your context or create a
+ * second context, you should assume that any existing function pointers
+ * aren't valid to use with it. This is (currently) a Windows-specific
+ * limitation, and in practice lots of drivers don't suffer this limitation,
+ * but it is still the way the wgl API is documented to work and you should
+ * expect crashes if you don't respect it. Store a copy of the function
+ * pointers that comes and goes with context lifespan.
+ *
+ * - On X11, function pointers returned by this function are valid for any
+ * context, and can even be looked up before a context is created at all. This
+ * means that, for at least some common OpenGL implementations, if you look up
+ * a function that doesn't exist, you'll get a non-NULL result that is _NOT_
+ * safe to call. You must always make sure the function is actually available
+ * for a given GL context before calling it, by checking for the existence of
+ * the appropriate extension with SDL_GL_ExtensionSupported(), or verifying
+ * that the version of OpenGL you're using offers the function as core
+ * functionality.
+ *
+ * - Some OpenGL drivers, on all platforms, *will* return NULL if a function
+ * isn't supported, but you can't count on this behavior. Check for extensions
+ * you use, and if you get a NULL anyway, act as if that extension wasn't
+ * available. This is probably a bug in the driver, but you can code
+ * defensively for this scenario anyhow.
+ *
+ * - Just because you're on Linux/Unix, don't assume you'll be using X11.
+ * Next-gen display servers are waiting to replace it, and may or may not make
+ * the same promises about function pointers.
+ *
+ * - OpenGL function pointers must be declared `APIENTRY` as in the example
+ * code. This will ensure the proper calling convention is followed on
+ * platforms where this matters (Win32) thereby avoiding stack corruption.
+ *
+ * \param proc the name of an OpenGL function
+ * \returns a pointer to the named OpenGL function. The returned pointer
+ * should be cast to the appropriate function signature.
+ *
+ * \sa SDL_GL_ExtensionSupported
+ * \sa SDL_GL_LoadLibrary
+ * \sa SDL_GL_UnloadLibrary
*/
extern DECLSPEC void *SDLCALL SDL_GL_GetProcAddress(const char *proc);
/**
- * \brief Unload the OpenGL library previously loaded by SDL_GL_LoadLibrary().
+ * Unload the OpenGL library previously loaded by SDL_GL_LoadLibrary().
*
- * \sa SDL_GL_LoadLibrary()
+ * \sa SDL_GL_LoadLibrary
*/
extern DECLSPEC void SDLCALL SDL_GL_UnloadLibrary(void);
/**
- * \brief Return true if an OpenGL extension is supported for the current
- * context.
+ * Check if an OpenGL extension is supported for the current context.
+ *
+ * This function operates on the current GL context; you must have created a
+ * context and it must be current before calling this function. Do not assume
+ * that all contexts you create will have the same set of extensions
+ * available, or that recreating an existing context will offer the same
+ * extensions again.
+ *
+ * While it's probably not a massive overhead, this function is not an O(1)
+ * operation. Check the extensions you care about after creating the GL
+ * context and save that information somewhere instead of calling the function
+ * every time you need to know.
+ *
+ * \param extension the name of the extension to check
+ * \returns SDL_TRUE if the extension is supported, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 2.0.0.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GL_ExtensionSupported(const char
*extension);
/**
- * \brief Reset all previously set OpenGL context attributes to their default values
+ * Reset all previously set OpenGL context attributes to their default values.
+ *
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \sa SDL_GL_GetAttribute
+ * \sa SDL_GL_SetAttribute
+ * \sa <!-- #Remove this section if empty -->
*/
extern DECLSPEC void SDLCALL SDL_GL_ResetAttributes(void);
/**
- * \brief Set an OpenGL window attribute before window creation.
+ * Set an OpenGL window attribute before window creation.
+ *
+ * This function sets the OpenGL attribute `attr` to `value`. The
+ * requested attributes should be set before creating an OpenGL window. You
+ * should use SDL_GL_GetAttribute() to check the values after creating the
+ * OpenGL context, since the values obtained can differ from the requested
+ * ones.
+ *
+ * \param attr an SDL_GLattr enum value specifying the OpenGL attribute to set
+ * \param value the desired value for the attribute
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \return 0 on success, or -1 if the attribute could not be set.
+ * \sa SDL_GL_GetAttribute
+ * \sa SDL_GL_ResetAttributes
*/
extern DECLSPEC int SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value);
/**
- * \brief Get the actual value for an attribute from the current context.
+ * Get the actual value for an attribute from the current context.
*
- * \return 0 on success, or -1 if the attribute could not be retrieved.
- * The integer at \c value will be modified in either case.
+ * \param attr an SDL_GLattr enum value specifying the OpenGL attribute to get
+ * \param value a pointer filled in with the current value of `attr`
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \sa SDL_GL_ResetAttributes
+ * \sa SDL_GL_SetAttribute
*/
extern DECLSPEC int SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int *value);
/**
- * \brief Create an OpenGL context for use with an OpenGL window, and make it
- * current.
+ * Create an OpenGL context for an OpenGL window, and make it current.
+ *
+ * Windows users new to OpenGL should note that, for historical reasons, GL
+ * functions added after OpenGL version 1.1 are not available by default.
+ * Those functions must be loaded at run-time, either with an OpenGL
+ * extension-handling library or with SDL_GL_GetProcAddress() and its related
+ * functions.
+ *
+ * SDL_GLContext is an alias for `void *`. It's opaque to the application.
*
- * \sa SDL_GL_DeleteContext()
+ * \param window the window to associate with the context
+ * \returns the OpenGL context associated with `window` or NULL on error;
+ * call SDL_GetError() for more details.
+ *
+ * \sa SDL_GL_DeleteContext
+ * \sa SDL_GL_MakeCurrent
*/
extern DECLSPEC SDL_GLContext SDLCALL SDL_GL_CreateContext(SDL_Window *
window);
/**
- * \brief Set up an OpenGL context for rendering into an OpenGL window.
+ * Set up an OpenGL context for rendering into an OpenGL window.
+ *
+ * The context must have been created with a compatible window.
+ *
+ * \param window the window to associate with the context
+ * \param context the OpenGL context to associate with the window
+ * \returns 0 on success or a negative error code on failure; call
+ * SDL_GetError() for more information.
*
- * \note The context must have been created with a compatible window.
+ * \sa SDL_GL_CreateContext
*/
extern DECLSPEC int SDLCALL SDL_GL_MakeCurrent(SDL_Window * window,
SDL_GLContext context);
/**
- * \brief Get the currently active OpenGL window.
+ * Get the currently active OpenGL window.
+ *
+ * \returns the currently active OpenGL window on success or NULL on failure;
+ * call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
*/
extern DECLSPEC SDL_Window* SDLCALL SDL_GL_GetCurrentWindow(void);
/**
- * \brief Get the currently active OpenGL context.
+ * Get the currently active OpenGL context.
+ *
+ * \returns the currently active OpenGL context or NULL on failure; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GL_MakeCurrent
*/
extern DECLSPEC SDL_GLContext SDLCALL SDL_GL_GetCurrentContext(void);
/**
- * \brief Get the size of a window's underlying drawable in pixels (for use
- * with glViewport).
+ * Get the size of a window's underlying drawable in pixels.
*
- * \param window Window from which the drawable size should be queried
- * \param w Pointer to variable for storing the width in pixels, may be NULL
- * \param h Pointer to variable for storing the height in pixels, may be NULL
+ * This returns info useful for calling glViewport().
*
* This may differ from SDL_GetWindowSize() if we're rendering to a high-DPI
- * drawable, i.e. the window was created with SDL_WINDOW_ALLOW_HIGHDPI on a
- * platform with high-DPI support (Apple calls this "Retina"), and not disabled
- * by the SDL_HINT_VIDEO_HIGHDPI_DISABLED hint.
+ * drawable, i.e. the window was created with `SDL_WINDOW_ALLOW_HIGHDPI` on a
+ * platform with high-DPI support (Apple calls this "Retina"), and not
+ * disabled by the `SDL_HINT_VIDEO_HIGHDPI_DISABLED` hint.
*
- * \sa SDL_GetWindowSize()
- * \sa SDL_CreateWindow()
+ * \param window the window from which the drawable size should be queried
+ * \param w a pointer to variable for storing the width in pixels, may be NULL
+ * \param h a pointer to variable for storing the height in pixels, may be
+ * NULL
+ *
+ * \since This function is available since SDL 2.0.1.
+ *
+ * \sa SDL_CreateWindow
+ * \sa SDL_GetWindowSize
*/
extern DECLSPEC void SDLCALL SDL_GL_GetDrawableSize(SDL_Window * window, int *w,
int *h);
/**
- * \brief Set the swap interval for the current OpenGL context.
+ * Set the swap interval for the current OpenGL context.
*
- * \param interval 0 for immediate updates, 1 for updates synchronized with the
- * vertical retrace. If the system supports it, you may
- * specify -1 to allow late swaps to happen immediately
- * instead of waiting for the next retrace.
+ * Some systems allow specifying -1 for the interval, to enable adaptive
+ * vsync. Adaptive vsync works the same as vsync, but if you've already missed
+ * the vertical retrace for a given frame, it swaps buffers immediately, which
+ * might be less jarring for the user during occasional framerate drops. If
+ * application requests adaptive vsync and the system does not support it,
+ * this function will fail and return -1. In such a case, you should probably
+ * retry the call with 1 for the interval.
*
- * \return 0 on success, or -1 if setting the swap interval is not supported.
+ * Adaptive vsync is implemented for some glX drivers with
+ * GLX_EXT_swap_control_tear:
*
- * \sa SDL_GL_GetSwapInterval()
+ * https://www.opengl.org/registry/specs/EXT/glx_swap_control_tear.txt
+ *
+ * and for some Windows drivers with WGL_EXT_swap_control_tear:
+ *
+ * https://www.opengl.org/registry/specs/EXT/wgl_swap_control_tear.txt
+ *
+ * Read more on the Khronos wiki:
+ * https://www.khronos.org/opengl/wiki/Swap_Interval#Adaptive_Vsync
+ *
+ * \param interval 0 for immediate updates, 1 for updates synchronized with
+ * the vertical retrace, -1 for adaptive vsync
+ * \returns 0 on success or -1 if setting the swap interval is not supported;
+ * call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GL_GetSwapInterval
*/
extern DECLSPEC int SDLCALL SDL_GL_SetSwapInterval(int interval);
/**
- * \brief Get the swap interval for the current OpenGL context.
+ * Get the swap interval for the current OpenGL context.
*
- * \return 0 if there is no vertical retrace synchronization, 1 if the buffer
+ * If the system can't determine the swap interval, or there isn't a valid
+ * current context, this function will return 0 as a safe default.
+ *
+ * \returns 0 if there is no vertical retrace synchronization, 1 if the buffer
* swap is synchronized with the vertical retrace, and -1 if late
- * swaps happen immediately instead of waiting for the next retrace.
- * If the system can't determine the swap interval, or there isn't a
- * valid current context, this will return 0 as a safe default.
+ * swaps happen immediately instead of waiting for the next retrace;
+ * call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
*
- * \sa SDL_GL_SetSwapInterval()
+ * \sa SDL_GL_SetSwapInterval
*/
extern DECLSPEC int SDLCALL SDL_GL_GetSwapInterval(void);
/**
- * \brief Swap the OpenGL buffers for a window, if double-buffering is
- * supported.
+ * Update a window with OpenGL rendering.
+ *
+ * This is used with double-buffered OpenGL contexts, which are the default.
+ *
+ * On macOS, make sure you bind 0 to the draw framebuffer before swapping
+ * the window, otherwise nothing will happen. If you aren't using
+ * glBindFramebuffer(), this is the default and you won't have to do anything
+ * extra.
+ *
+ * \param window the window to change
*/
extern DECLSPEC void SDLCALL SDL_GL_SwapWindow(SDL_Window * window);
/**
- * \brief Delete an OpenGL context.
+ * Delete an OpenGL context.
+ *
+ * \param context the OpenGL context to be deleted
*
- * \sa SDL_GL_CreateContext()
+ * \sa SDL_GL_CreateContext
*/
extern DECLSPEC void SDLCALL SDL_GL_DeleteContext(SDL_GLContext context);
diff --git a/include/SDL_vulkan.h b/include/SDL_vulkan.h
index a3de1ce..6962574 100644
--- a/include/SDL_vulkan.h
+++ b/include/SDL_vulkan.h
@@ -66,201 +66,140 @@ typedef VkSurfaceKHR SDL_vulkanSurface; /* for compatibility with Tizen */
/* @{ */
/**
- * \brief Dynamically load a Vulkan loader library.
- *
- * \param [in] path The platform dependent Vulkan loader library name, or
- * \c NULL.
- *
- * \return \c 0 on success, or \c -1 if the library couldn't be loaded.
- *
- * If \a path is NULL SDL will use the value of the environment variable
- * \c SDL_VULKAN_LIBRARY, if set, otherwise it loads the default Vulkan
- * loader library.
- *
- * This should be called after initializing the video driver, but before
- * creating any Vulkan windows. If no Vulkan loader library is loaded, the
- * default library will be loaded upon creation of the first Vulkan window.
- *
- * \note It is fairly common for Vulkan applications to link with \a libvulkan
- * instead of explicitly loading it at run time. This will work with
- * SDL provided the application links to a dynamic library and both it
- * and SDL use the same search path.
- *
- * \note If you specify a non-NULL \c path, an application should retrieve all
- * of the Vulkan functions it uses from the dynamic library using
- * \c SDL_Vulkan_GetVkGetInstanceProcAddr() unless you can guarantee
- * \c path points to the same vulkan loader library the application
- * linked to.
- *
- * \note On Apple devices, if \a path is NULL, SDL will attempt to find
- * the vkGetInstanceProcAddr address within all the mach-o images of
- * the current process. This is because it is fairly common for Vulkan
- * applications to link with libvulkan (and historically MoltenVK was
- * provided as a static library). If it is not found then, on macOS, SDL
- * will attempt to load \c vulkan.framework/vulkan, \c libvulkan.1.dylib,
- * followed by \c libvulkan.dylib, in that order.
- * On iOS SDL will attempt to load \c libvulkan.dylib only. Applications
- * using a dynamic framework or .dylib must ensure it is included in its
- * application bundle.
- *
- * \note On non-Apple devices, application linking with a static libvulkan is
- * not supported. Either do not link to the Vulkan loader or link to a
- * dynamic library version.
- *
- * \note This function will fail if there are no working Vulkan drivers
- * installed.
- *
- * \sa SDL_Vulkan_GetVkGetInstanceProcAddr()
- * \sa SDL_Vulkan_UnloadLibrary()
+ * Dynamically load the Vulkan loader library.
+ *
+ * This should be called after initializing the video driver, but before
+ * creating any Vulkan windows. If no Vulkan loader library is loaded, the
+ * default library will be loaded upon creation of the first Vulkan window.
+ *
+ * It is fairly common for Vulkan applications to link with libvulkan instead
+ * of explicitly loading it at run time. This will work with SDL provided the
+ * application links to a dynamic library and both it and SDL use the same
+ * search path.
+ *
+ * If you specify a non-NULL `path`, an application should retrieve
+ * all of the Vulkan functions it uses from the dynamic library using
+ * SDL_Vulkan_GetVkGetInstanceProcAddr unless you can guarantee `path`
+ * points to the same vulkan loader library the application linked to.
+ *
+ * On Apple devices, if `path` is NULL, SDL will attempt to find the
+ * `vkGetInstanceProcAddr` address within all the Mach-O images of the
+ * current process. This is because it is fairly common for Vulkan
+ * applications to link with libvulkan (and historically MoltenVK was provided
+ * as a static library). If it is not found, on macOS, SDL will attempt
+ * to load `vulkan.framework/vulkan`, `libvulkan.1.dylib`,
+ * `MoltenVK.framework/MoltenVK`, and `libMoltenVK.dylib`, in that
+ * order. On iOS, SDL will attempt to load `libMoltenVK.dylib`.
+ * Applications using a dynamic framework or .dylib must ensure it is included
+ * in its application bundle.
+ *
+ * On non-Apple devices, application linking with a static libvulkan is not
+ * supported. Either do not link to the Vulkan loader or link to a dynamic
+ * library version.
+ *
+ * \param path The platform dependent Vulkan loader library name or NULL
+ * \returns 0 on success or -1 if the library couldn't be loaded; call
+ * SDL_GetError() for more information.
+ *
+ * \since This function is available in SDL 2.0.8
+ *
+ * \sa SDL_Vulkan_GetVkInstanceProcAddr
+ * \sa SDL_Vulkan_UnloadLibrary
*/
extern DECLSPEC int SDLCALL SDL_Vulkan_LoadLibrary(const char *path);
/**
- * \brief Get the address of the \c vkGetInstanceProcAddr function.
+ * Get the address of the `vkGetInstanceProcAddr` function.
*
- * \note This should be called after either calling SDL_Vulkan_LoadLibrary
- * or creating an SDL_Window with the SDL_WINDOW_VULKAN flag.
+ * This should be called after either calling SDL_Vulkan_LoadLibrary()
+ * or creating an SDL_Window with the `SDL_WINDOW_VULKAN` flag.
+ *
+ * \returns The function pointer for `vkGetInstanceProcAddr` or NULL on error.
*/
extern DECLSPEC void *SDLCALL SDL_Vulkan_GetVkGetInstanceProcAddr(void);
/**
- * \brief Unload the Vulkan loader library previously loaded by
- * \c SDL_Vulkan_LoadLibrary().
+ * Unload the Vulkan library previously loaded by SDL_Vulkan_LoadLibrary()
+ *
+ * \since This function is available in SDL 2.0.8
*
- * \sa SDL_Vulkan_LoadLibrary()
+ * \sa SDL_Vulkan_LoadLibrary
*/
extern DECLSPEC void SDLCALL SDL_Vulkan_UnloadLibrary(void);
/**
- * \brief Get the names of the Vulkan instance extensions needed to create
- * a surface with \c SDL_Vulkan_CreateSurface().
- *
- * \param [in] \c NULL or window Window for which the required Vulkan instance
- * extensions should be retrieved
- * \param [in,out] pCount pointer to an \c unsigned related to the number of
- * required Vulkan instance extensions
- * \param [out] pNames \c NULL or a pointer to an array to be filled with the
- * required Vulkan instance extensions
- *
- * \return \c SDL_TRUE on success, \c SDL_FALSE on error.
- *
- * If \a pNames is \c NULL, then the number of required Vulkan instance
- * extensions is returned in pCount. Otherwise, \a pCount must point to a
- * variable set to the number of elements in the \a pNames array, and on
- * return the variable is overwritten with the number of names actually
- * written to \a pNames. If \a pCount is less than the number of required
- * extensions, at most \a pCount structures will be written. If \a pCount
- * is smaller than the number of required extensions, \c SDL_FALSE will be
- * returned instead of \c SDL_TRUE, to indicate that not all the required
- * extensions were returned.
- *
- * \note If \c window is not NULL, it will be checked against its creation
- * flags to ensure that the Vulkan flag is present. This parameter
- * will be removed in a future major release.
- *
- * \note The returned list of extensions will contain \c VK_KHR_surface
- * and zero or more platform specific extensions
- *
- * \note The extension names queried here must be enabled when calling
- * VkCreateInstance, otherwise surface creation will fail.
- *
- * \note \c window should have been created with the \c SDL_WINDOW_VULKAN flag
- * or be \c NULL
- *
- * \code
- * unsigned int count;
- * // get count of required extensions
- * if(!SDL_Vulkan_GetInstanceExtensions(NULL, &count, NULL))
- * handle_error();
- *
- * static const char *const additionalExtensions[] =
- * {
- * VK_EXT_DEBUG_REPORT_EXTENSION_NAME, // example additional extension
- * };
- * size_t additionalExtensionsCount = sizeof(additionalExtensions) / sizeof(additionalExtensions[0]);
- * size_t extensionCount = count + additionalExtensionsCount;
- * const char **names = malloc(sizeof(const char *) * extensionCount);
- * if(!names)
- * handle_error();
- *
- * // get names of required extensions
- * if(!SDL_Vulkan_GetInstanceExtensions(NULL, &count, names))
- * handle_error();
- *
- * // copy additional extensions after required extensions
- * for(size_t i = 0; i < additionalExtensionsCount; i++)
- * names[i + count] = additionalExtensions[i];
- *
- * VkInstanceCreateInfo instanceCreateInfo = {};
- * instanceCreateInfo.enabledExtensionCount = extensionCount;
- * instanceCreateInfo.ppEnabledExtensionNames = names;
- * // fill in rest of instanceCreateInfo
- *
- * VkInstance instance;
- * // create the Vulkan instance
- * VkResult result = vkCreateInstance(&instanceCreateInfo, NULL, &instance);
- * free(names);
- * \endcode
- *
- * \sa SDL_Vulkan_CreateSurface()
+ * Get the names of the Vulkan instance extensions needed
+ * to create a surface with SDL_Vulkan_CreateSurface.
+ *
+ * If `pNames` is NULL, then the number of required Vulkan instance
+ * extensions is returned in `pCount`. Otherwise, `pCount` must point
+ * to a variable set to the number of elements in the `pNames` array, and
+ * on return the variable is overwritten with the number of names actually
+ * written to `pNames`. If `pCount` is less than the number of
+ * required extensions, at most `pCount` structures will be written. If
+ * `pCount` is smaller than the number of required extensions,
+ * SDL_FALSE will be returned instead of SDL_TRUE, to indicate
+ * that not all the required extensions were returned.
+ *
+ * The `window` parameter is currently needed to be valid as of
+ * SDL 2.0.8, however, this parameter will likely be removed in future
+ * releases
+ *
+ * \param window A window for which the required Vulkan instance extensions
+ * should be retrieved (will be deprecated in a future release)
+ * \param pCount A pointer to an unsigned int corresponding to the
+ * number of extensions to be returned
+ * \param names NULL or a pointer to an array to be filled with required
+ * Vulkan instance extensions
+ * \returns SDL_TRUE on success, SDL_FALSE on error.
+ *
+ * \since This function is available in SDL 2.0.8
+ *
+ * \sa SDL_Vulkan_CreateSurface
*/
extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_GetInstanceExtensions(SDL_Window *window,
unsigned int *pCount,
const char **pNames);
/**
- * \brief Create a Vulkan rendering surface for a window.
- *
- * \param [in] window SDL_Window to which to attach the rendering surface.
- * \param [in] instance handle to the Vulkan instance to use.
- * \param [out] surface pointer to a VkSurfaceKHR handle to receive the
- * handle of the newly created surface.
- *
- * \return \c SDL_TRUE on success, \c SDL_FALSE on error.
+ * Create a Vulkan rendering surface for a window.
*
- * \code
- * VkInstance instance;
- * SDL_Window *window;
+ * The `window` must have been created with the `SDL_WINDOW_VULKAN` flag and
+ * `instance` must have been created with extensions returned by
+ * SDL_Vulkan_GetInstanceExtensions() enabled.
*
- * // create instance and window
+ * \param window The window to which to attach the Vulkan surface
+ * \param instance The Vulkan instance handle
+ * \param surface A pointer to a VkSurfaceKHR handle to output the newly
+ * created surface
+ * \returns SDL_TRUE on success, SDL_FALSE on error.
*
- * // create the Vulkan surface
- * VkSurfaceKHR surface;
- * if(!SDL_Vulkan_CreateSurface(window, instance, &surface))
- * handle_error();
- * \endcode
+ * \since This function is available in SDL 2.0.8
*
- * \note \a window should have been created with the \c SDL_WINDOW_VULKAN flag.
- *
- * \note \a instance should have been created with the extensions returned
- * by \c SDL_Vulkan_CreateSurface() enabled.
- *
- * \sa SDL_Vulkan_GetInstanceExtensions()
+ * \sa SDL_Vulkan_GetInstanceExtensions
+ * \sa SDL_Vulkan_GetDrawableSize
*/
extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window,
VkInstance instance,
VkSurfaceKHR* surface);
/**
- * \brief Get the size of a window's underlying drawable in pixels (for use
- * with setting viewport, scissor & etc).
- *
- * \param window SDL_Window from which the drawable size should be queried
- * \param w Pointer to variable for storing the width in pixels,
- * may be NULL
- * \param h Pointer to variable for storing the height in pixels,
- * may be NULL
+ * Get the size of the window's underlying drawable dimensions in pixels.
*
* This may differ from SDL_GetWindowSize() if we're rendering to a high-DPI
- * drawable, i.e. the window was created with SDL_WINDOW_ALLOW_HIGHDPI on a
- * platform with high-DPI support (Apple calls this "Retina"), and not disabled
- * by the \c SDL_HINT_VIDEO_HIGHDPI_DISABLED hint.
+ * drawable, i.e. the window was created with `SDL_WINDOW_ALLOW_HIGHDPI`
+ * on a platform with high-DPI support (Apple calls this "Retina"), and not
+ * disabled by the `SDL_HINT_VIDEO_HIGHDPI_DISABLED` hint.
+ *
+ * \param window an SDL_Window for which the size is to be queried
+ * \param w Pointer to the variable to write the width to or NULL
+ * \param h Pointer to the variable to write the height to or NULL
*
- * \note On macOS high-DPI support must be enabled for an application by
- * setting NSHighResolutionCapable to true in its Info.plist.
+ * \since This function is available in SDL 2.0.8
*
- * \sa SDL_GetWindowSize()
- * \sa SDL_CreateWindow()
+ * \sa SDL_GetWindowSize
+ * \sa SDL_CreateWindow
+ * \sa SDL_Vulkan_CreateSurface
*/
extern DECLSPEC void SDLCALL SDL_Vulkan_GetDrawableSize(SDL_Window * window,
int *w, int *h);