summaryrefslogtreecommitdiffstatshomepage
path: root/3rdparty/bgfx/src/renderer_d3d9.cpp
diff options
context:
space:
mode:
Diffstat (limited to '3rdparty/bgfx/src/renderer_d3d9.cpp')
0 files changed, 0 insertions, 0 deletions
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
.. _luareference:

MAME Lua Class Reference
========================

.. contents::
    :local:
    :depth: 2


.. _luareference-intro:

Introduction
------------

Various aspects of MAME can be controlled using Lua scripting.  Many key classes
are exposed as Lua objects.

.. _luareference-intro-containers:

Containers
~~~~~~~~~~

Many properties yield container wrappers.  Container wrappers are cheap to
create, and provide an interface that is similar to a read-only table.  The
complexity of operations may vary.  Container wrappers usually provide most of
these operations:

#c
    Get the number of items in the container.
c[k]
    Returns the item corresponding to the key ``k``, or ``nil`` if the key is
    not present.
pairs(c)
    Iterate container by key and value.  The key is what you would pass to the
    index operator or the ``get`` method to get the value.
ipairs(c)
    Iterate container by index and value.  The index is what you would pass to
    the ``at`` method to get the value (this may be the same as the key for some
    containers).
c:empty()
    Returns a Boolean indicating whether there are no items in the container.
c:get(k)
    Returns the item corresponding to the key ``k``, or ``nil`` if the key is
    not present.  Usually equivalent to the index operator.
c:at(i)
    Returns the value at the 1-based index ``i``, or ``nil`` if it is out of
    range.
c:find(v)
    Returns the key for item ``v``, or ``nil`` if it is not in the container.
    The key is what you would pass to the index operator to get the value.
c:index_of(v)
    Returns the 1-based index for item ``v``, or ``nil`` if it is not in the
    container.  The index is what you would pass to the ``at`` method to get the
    value.


.. _luareference-core:

Core classes
------------

Many of MAME’s core classes used to implement an emulation session are available
to Lua scripts.

.. _luareference-core-notifiersub:

Notifier subscription
~~~~~~~~~~~~~~~~~~~~~

Wraps MAME’s ``util::notifier_subscription`` class, which manages a subscription
to a broadcast notification.

Methods
^^^^^^^

subscription:unsubscribe()
    Unsubscribes from notifications.  The subscription will become inactive and
    no future notifications will be received.

Properties
^^^^^^^^^^

subscription.is_active (read-only)
    A Boolean indicating whether the subscription is active.  A subscription
    becomes inactive after explicitly unsubscribing or if the underlying
    notifier is destroyed.

.. _luareference-core-attotime:

Attotime
~~~~~~~~

Wraps MAME’s ``attotime`` class, which represents a high-precision time
interval.  Attotime values support addition and subtraction with other attotime
values, and multiplication and division by integers.

Instantiation
^^^^^^^^^^^^^

emu.attotime()
    Creates an attotime value representing zero (i.e. no elapsed time).
emu.attotime(seconds, attoseconds)
    Creates an attotime with the specified whole and fractional parts.
emu.attotime(attotime)
    Creates a copy of an existing attotime value.
emu.attotime.from_double(seconds)
    Creates an attotime value representing the specified number of seconds.
emu.attotime.from_ticks(periods, frequency)
    Creates an attotime representing the specified number of periods of the
    specified frequency in Hertz.
emu.attotime.from_seconds(seconds)
    Creates an attotime value representing the specified whole number of
    seconds.
emu.attotime.from_msec(milliseconds)
    Creates an attotime value representing the specified whole number of
    milliseconds.
emu.attotime.from_usec(microseconds)
    Creates an attotime value representing the specified whole number of
    microseconds.
emu.attotime.from_nsec(nanoseconds)
    Creates an attotime value representing the specified whole number of
    nanoseconds.

Methods
^^^^^^^

t:as_double()
    Returns the time interval in seconds as a floating-point value.
t:as_hz()
    Interprets the interval as a period and returns the corresponding frequency
    in Hertz as a floating-point value.  Returns zero if ``t.is_never`` is true.
    The interval must not be zero.
t:as_khz()
    Interprets the interval as a period and returns the corresponding frequency
    kilohertz as a floating-point value.  Returns zero if ``t.is_never`` is
    true.  The interval must not be zero.
t:as_mhz()
    Interprets the interval as a period and returns the corresponding frequency
    megahertz as a floating-point value.  Returns zero if ``t.is_never`` is
    true.  The interval must not be zero.
t:as_ticks(frequency)
    Returns the interval as a whole number of periods at the specified
    frequency.  The frequency is specified in Hertz.

Properties
^^^^^^^^^^

t.is_zero (read-only)
    A Boolean indicating whether the value represents no elapsed time.
t.is_never (read-only)
    A Boolean indicating whether the value is greater than the maximum number of
    whole seconds that can be represented (treated as an unreachable time in the
    future or overflow).
t.attoseconds (read-only)
    The fraction seconds portion of the interval in attoseconds.
t.seconds (read-only)
    The number of whole seconds in the interval.
t.msec (read-only)
    The number of whole milliseconds in the fractional seconds portion of the
    interval.
t.usec (read-only)
    The number of whole microseconds in the fractional seconds portion of the
    interval.
t.nsec (read-only)
    The number of whole nanoseconds in the fractional seconds portion of the
    interval.

.. _luareference-core-mameman:

MAME machine manager
~~~~~~~~~~~~~~~~~~~~

Wraps MAME’s ``mame_machine_manager`` class, which holds the running machine, UI
manager, and other global components.

Instantiation
^^^^^^^^^^^^^

manager
    The MAME machine manager is available as a global variable in the Lua
    environment.

Properties
^^^^^^^^^^

manager.machine (read-only)
    The :ref:`running machine <luareference-core-machine>` for the current
    emulation session.
manager.ui (read-only)
    The :ref:`UI manager <luareference-core-uiman>` for the current session.
manager.options (read-only)
    The :ref:`emulation options <luareference-core-emuopts>` for the current
    session.
manager.plugins[] (read-only)
    Gets information about the :ref:`Lua plugins <luareference-core-plugin>`
    that are present, indexed by name.  The index get, ``at`` and ``index_of``
    methods have O(n) complexity.

.. _luareference-core-machine:

Running machine
~~~~~~~~~~~~~~~

Wraps MAME’s ``running_machine`` class, which represents an emulation session.
It provides access to the other core objects that implement an emulation session
as well as the emulated device tree.

Instantiation
^^^^^^^^^^^^^

manager.machine
    Gets the running machine instance for the current emulation session.

Methods
^^^^^^^

machine:exit()
    Schedules an exit from the current emulation session.  This will either
    return to the system selection menu or exit the application, depending on
    how it was started.  This method returns immediately, before the scheduled
    exit takes place.
machine:hard_reset()
    Schedules a hard reset.  This is implemented by tearing down the emulation
    session and starting another emulation session for the same system.  This
    method returns immediately, before the scheduled reset takes place.
machine:soft_reset()
    Schedules a soft reset.  This is implemented by calling the reset method of
    the root device, which is propagated down the device tree.  This method
    returns immediately, before the scheduled reset takes place.
machine:save(filename)
    Schedules saving machine state to the specified file.  If the file name is a
    relative path, it is considered to be relative to the first configured save
    state directory.  This method returns immediately, before the machine state
    is saved.  If this method is called when a save or load operation is already
    pending, the previously pending operation will be cancelled.
machine:load(filename)
    Schedules loading machine state from the specified file.  If the file name
    is a relative path, the configured save state directories will be searched.
    This method returns immediately, before the machine state is saved.  If this
    method is called when a save or load operation is already pending, the
    previously pending operation will be cancelled.
machine:popmessage([msg])
    Displays a pop-up message to the user.  If the message is not provided, the
    currently displayed pop-up message (if any) will be hidden.
machine:logerror(msg)
    Writes the message to the machine error log.  This may be displayed in a
    debugger window, written to a file, or written to the standard error output.

Properties
^^^^^^^^^^

machine.time (read-only)
    The elapsed emulated time for the current session as an
    :ref:`attotime <luareference-core-attotime>`.
machine.system (read-only)
    The :ref:`driver metadata <luareference-core-driver>` for the current
    system.
machine.parameters (read-only)
    The :ref:`parameters manager <luareference-core-paramman>` for the current
    emulation session.
machine.video (read-only)
    The :ref:`video manager <luareference-core-videoman>` for the current
    emulation session.
machine.sound (read-only)
    The :ref:`sound manager <luareference-core-soundman>` for the current
    emulation session.
machine.output (read-only)
    The :ref:`output manager <luareference-core-outputman>` for the current
    emulation session.
machine.memory (read-only)
    The :ref:`emulated memory manager <luareference-mem-manager>` for the
    current emulation session.
machine.ioport (read-only)
    The :ref:`I/O port manager <luareference-input-ioportman>` for the current
    emulation session.
machine.input (read-only)
    The :ref:`input manager <luareference-input-inputman>` for the current
    emulation session.
machine.natkeyboard (read-only)
    Gets the :ref:`natural keyboard manager <luareference-input-natkbd>`, used
    for controlling keyboard and keypad input to the emulated system.
machine.uiinput (read-only)
    The :ref:`UI input manager <luareference-input-uiinput>` for the current
    emulation session.
machine.render (read-only)
    The :ref:`render manager <luareference-render-manager>` for the current
    emulation session.
machine.debugger (read-only)
    The :ref:`debugger manager <luareference-debug-manager>` for the current
    emulation session, or ``nil`` if the debugger is not enabled.
machine.options (read-only)
    The user-specified :ref:`options <luareference-core-emuopts>` for the
    current emulation session.
machine.samplerate (read-only)
    The output audio sample rate in Hertz.
machine.paused (read-only)
    A Boolean indicating whether emulation is not currently running, usually
    because the session has been paused or the emulated system has not completed
    starting.
machine.exit_pending (read-only)
    A Boolean indicating whether the emulation session is scheduled to exit.
machine.hard_reset_pending (read-only)
    A Boolean indicating whether a hard reset of the emulated system is pending.
machine.devices (read-only)
    A :ref:`device enumerator <luareference-dev-enum>` that yields all
    :ref:`devices <luareference-dev-device>` in the emulated system.
machine.palettes (read-only)
    A :ref:`device enumerator <luareference-dev-enum>` that yields all
    :ref:`palette devices <luareference-dev-dipalette>` in the emulated system.
machine.screens (read-only)
    A :ref:`device enumerator <luareference-dev-enum>` that yields all
    :ref:`screen devices <luareference-dev-screen>` in the emulated system.
machine.cassettes (read-only)
    A :ref:`device enumerator <luareference-dev-enum>` that yields all
    :ref:`cassette image devices <luareference-dev-cass>` in the emulated
    system.
machine.images (read-only)
    A :ref:`device enumerator <luareference-dev-enum>` that yields all
    :ref:`media image devices <luareference-dev-diimage>` in the emulated system.
machine.slots (read-only)
    A :ref:`device enumerator <luareference-dev-enum>` that yields all
    :ref:`slot devices <luareference-dev-dislot>` in the emulated system.

.. _luareference-core-videoman:

Video manager
~~~~~~~~~~~~~

Wraps MAME’s ``video_manager`` class, which is responsible for coordinating
emulated video drawing, speed throttling, and reading host inputs.

Instantiation
^^^^^^^^^^^^^

manager.machine.video
    Gets the video manager for the current emulation session.

Methods
^^^^^^^

video:frame_update()
    Updates emulated screens, reads host inputs, and updates video output.
video:snapshot()
    Saves snapshot files according to the current configuration.  If MAME is
    configured to take native emulated screen snapshots, one snapshot will be
    saved for each emulated screen that is visible in a host window/screen with
    the current view configuration.  If MAME is not configured to use take
    native emulated screen snapshots or if the system has no emulated screens, a
    single snapshot will be saved using the currently selected snapshot view.
video:begin_recording([filename], [format])
    Stops any video recordings currently in progress and starts recording either
    the visible emulated screens or the current snapshot view, depending on
    whether MAME is configured to take native emulated screen snapshots.

    If the file name is not supplied, the configured snapshot file name is used.
    If the file name is a relative path, it is interpreted relative to the first
    configured snapshot directory.  If the format is supplied, it must be
    ``"avi"`` or ``"mng"``.  If the format is not supplied, it defaults to AVI.
video:end_recording()
    Stops any video recordings that are in progress.
video:snapshot_size()
    Returns the width and height in pixels of snapshots created with the current
    snapshot target configuration and emulated screen state.  This may be
    configured explicitly by the user, or calculated based on the selected
    snapshot view and the resolution of any visible emulated screens.
video:snapshot_pixels()
    Returns the pixels of a snapshot created using the current snapshot target
    configuration as 32-bit integers packed into a binary string in host Endian
    order.  Pixels are organised in row-major order, from left to right then top
    to bottom.  Pixel values are colours in RGB format packed into 32-bit
    integers.

Properties
^^^^^^^^^^

video.speed_factor (read-only)
    Configured emulation speed adjustment in per mille (i.e. the ratio to normal
    speed multiplied by 1,000).
video.throttled (read/write)
    A Boolean indicating whether MAME should wait before video updates to avoid
    running faster than the target speed.
video.throttle_rate (read/write)
    The target emulation speed as a ratio of full speed adjusted by the speed
    factor (i.e. 1 is normal speed adjusted by the speed factor, larger numbers
    are faster, and smaller numbers are slower).
video.frameskip (read/write)
    The number of emulated video frames to skip drawing out of every twelve, or
    -1 to automatically adjust the number of frames to skip to maintain the
    target emulation speed.
video.speed_percent (read-only)
    The current emulated speed as a percentage of the full speed adjusted by the
    speed factor.
video.effective_frameskip (read-only)
    The number of emulated frames that are skipped out of every twelve.
video.skip_this_frame (read-only)
    A Boolean indicating whether the video manager will skip drawing emulated
    screens for the current frame.
video.snap_native (read-only)
    A Boolean indicating whether the video manager will take native emulated
    screen snapshots.  In addition to the relevant configuration setting, the
    emulated system must have at least one emulated screen.
video.is_recording (read-only)
    A Boolean indicating whether any video recordings are currently in progress.
video.snapshot_target (read-only)
    The :ref:`render target <luareference-render-target>` used to produce
    snapshots and video recordings.

.. _luareference-core-soundman:

Sound manager
~~~~~~~~~~~~~

Wraps MAME’s ``sound_manager`` class, which manages the emulated sound stream
graph and coordinates sound output.

Instantiation
^^^^^^^^^^^^^

manager.machine.sound
    Gets the sound manager for the current emulation session.

Methods
^^^^^^^

sound:start_recording([filename])
    Starts recording to a WAV file.  Has no effect if currently recording.  If
    the file name is not supplied, uses the configured WAV file name (from
    command line or INI file), or has no effect if no WAV file name is
    configured.  Returns ``true`` if recording started, or ``false`` if
    recording is already in progress, opening the output file failed, or no file
    name was supplied or configured.
sound:stop_recording()
    Stops recording and closes the file if currently recording to a WAV file.
sound:get_samples()
    Returns the current contents of the output sample buffer as a binary string.
    Samples are 16-bit integers in host byte order.  Samples for left and right
    stereo channels are interleaved.

Properties
^^^^^^^^^^

sound.muted (read-only)
    A Boolean indicating whether sound output is muted for any reason.
sound.ui_mute (read/write)
    A Boolean indicating whether sound output is muted at the request of the
    user.
sound.debugger_mute (read/write)
    A Boolean indicating whether sound output is muted at the request of the
    debugger.
sound.system_mute (read/write)
    A Boolean indicating whether sound output is muted at the request of the
    emulated system.
sound.attenuation (read/write)
    The output volume attenuation in decibels.  Should generally be a negative
    integer or zero.
sound.recording (read-only)
    A Boolean indicating whether sound output is currently being recorded to a
    WAV file.

.. _luareference-core-outputman:

Output manager
~~~~~~~~~~~~~~

Wraps MAME’s ``output_manager`` class, providing access to system outputs that
can be used for interactive artwork or consumed by external programs.

Instantiation
^^^^^^^^^^^^^

manager.machine.output
    Gets the output manager for the current emulation session.

Methods
^^^^^^^

output:set_value(name, val)
    Sets the specified output value.  The value must be an integer.  The output
    will be created if it does not already exist.
output:set_indexed_value(prefix, index, val)
    Appends the index (formatted as a decimal integer) to the prefix and sets
    the value of the corresponding output.  The value must be an integer.  The
    output will be created if it does not already exist.
output:get_value(name)
    Returns the value of the specified output, or zero if it doesn’t exist.
output:get_indexed_value(prefix, index)
    Appends the index (formatted as a decimal integer) to the prefix and returns
    the value of the corresponding output, or zero if it doesn’t exist.
output:name_to_id(name)
    Gets the per-session unique integer ID for the specified output, or zero if
    it doesn’t exist.
output:id_to_name(id)
    Gets the name for the output with the specified per-session unique ID, or
    ``nil`` if it doesn’t exist.  This method has O(n) complexity, so avoid
    calling it when performance is important.

.. _luareference-core-paramman:

Parameters manager
~~~~~~~~~~~~~~~~~~

Wraps MAME’s ``parameters_manager`` class, which provides a simple key-value
store for metadata from system ROM definitions.

Instantiation
^^^^^^^^^^^^^

manager.machine.parameters
    Gets the parameters manager for the current emulation session.

Methods
^^^^^^^

parameters:lookup(tag)
    Gets the value for the specified parameter if it is set, or an empty string
    if it is not set.
parameters:add(tag, value)
    Sets the specified parameter if it is not set.  Has no effect if the
    specified parameter is already set.

.. _luareference-core-uiman:

UI manager
~~~~~~~~~~

Wraps MAME’s ``mame_ui_manager`` class, which handles menus and other user
interface functionality.

Instantiation
^^^^^^^^^^^^^

manager.ui
    Gets the UI manager for the current session.

Methods
^^^^^^^

ui:get_char_width(ch)
    Gets the width of a Unicode character as a proportion of the width of the UI
    container in the current font at the configured UI line height.
ui:get_string_width(str)
    Gets the width of a string as a proportion of the width of the UI container
    in the current font at the configured UI line height.
ui:set_aggressive_input_focus(enable)
    On some platforms, this controls whether MAME should accept input focus in
    more situations than when its windows have UI focus.
ui:get_general_input_setting(type, [player])
    Gets a description of the configured
    :ref:`input sequence <luareference-input-iptseq>` for the specified input
    type and player suitable for using in prompts.  The input type is an
    enumerated value.  The player number is a zero-based index.  If the player
    number is not supplied, it is assumed to be zero.

Properties
^^^^^^^^^^

ui.options (read-only)
    The UI :ref:`options <luareference-core-coreopts>` for the current session.
ui.line_height (read-only)
    The configured UI text line height as a proportion of the height of the UI
    container.
ui.menu_active (read-only)
    A Boolean indicating whether an interactive UI element is currently active.
    Examples include menus and slider controls.
ui.ui_active (read/write)
    A Boolean indicating whether UI control inputs are currently enabled.
ui.single_step (read/write)
    A Boolean controlling whether the emulated system should be automatically
    paused when the next frame is drawn.  This property is automatically reset
    when the automatic pause happens.
ui.show_fps (read/write)
    A Boolean controlling whether the current emulation speed and frame skipping
    settings should be displayed.
ui.show_profiler (read/write)
    A Boolean controlling whether profiling statistics should be displayed.

.. _luareference-core-driver:

System driver metadata
~~~~~~~~~~~~~~~~~~~~~~

Provides some metadata for an emulated system.

Instantiation
^^^^^^^^^^^^^

emu.driver_find(name)
    Gets the driver metadata for the system with the specified short name, or
    ``nil`` if no such system exists.
manager.machine.system
    Gets the driver metadata for the current system.

Properties
^^^^^^^^^^

driver.name (read-only)
    The short name of the system, as used on the command line, in configuration
    files, and when searching for resources.
driver.description (read-only)
    The full display name for the system.
driver.year (read-only)
    The release year for the system.  May contain question marks if not known
    definitively.
driver.manufacturer (read-only)
    The manufacturer, developer or distributor of the system.
driver.parent (read-only)
    The short name of parent system for organisation purposes, or ``"0"`` if the
    system has no parent.
driver.compatible_with (read-only)
    The short name of a system that this system is compatible with software for,
    or ``nil`` if the system is not listed as compatible with another system.
driver.source_file (read-only)
    The source file where this system driver is defined.  The path format
    depends on the toolchain the emulator was built with.
driver.rotation (read-only)
    A string indicating the rotation applied to all screens in the system after
    the screen orientation specified in the machine configuration is applied.
    Will be one of ``"rot0"``, ``"rot90"``, ``"rot180"`` or ``"rot270"``.
driver.not_working (read-only)
    A Boolean indicating whether the system is marked as not working.
driver.supports_save (read-only)
    A Boolean indicating whether the system supports save states.
driver.no_cocktail (read-only)
    A Boolean indicating whether screen flipping in cocktail mode is
    unsupported.
driver.is_bios_root (read-only)
    A Boolean indicating whether this system represents a system that runs
    software from removable media without media present.
driver.requires_artwork (read-only)
    A Boolean indicating whether the system requires external artwork to be
    usable.
driver.clickable_artwork (read-only)
    A Boolean indicating whether the system requires clickable artwork features
    to be usable.
driver.unofficial (read-only)
    A Boolean indicating whether this is an unofficial but common user
    modification to a system.
driver.no_sound_hw (read-only)
    A Boolean indicating whether the system has no sound output hardware.
driver.mechanical (read-only)
    A Boolean indicating whether the system depends on mechanical features that
    cannot be properly simulated.
driver.is_incomplete (read-only)
    A Boolean indicating whether the system is a prototype with incomplete
    functionality.

.. _luareference-core-plugin:

Lua plugin
~~~~~~~~~~

Provides a description of an available Lua plugin.

Instantiation
^^^^^^^^^^^^^

manager.plugins[name]
    Gets the description of the Lua plugin with the specified name, or ``nil``
    if no such plugin is available

Properties
^^^^^^^^^^

plugin.name (read-only)
    The short name of the plugin, used in configuration and when accessing the
    plugin programmatically.
plugin.description (read-only)
    The display name for the plugin.
plugin.type (read-only)
    The plugin type.  May be ``"plugin"`` for user-loadable plugins, or
    ``"library"`` for libraries providing common functionality to multiple
    plugins.
plugin.directory (read-only)
    The path to the directory containing the plugin’s files.
plugin.start (read-only)
    A Boolean indicating whether the plugin enabled.


.. _luareference-dev:

Devices
-------

Several device classes and device mix-ins classes are exposed to Lua.  Devices
can be looked up by tag or enumerated.

.. _luareference-dev-enum:

Device enumerators
~~~~~~~~~~~~~~~~~~

Device enumerators are special containers that allow iterating over devices and
looking up devices by tag.  A device enumerator can be created to find any kind
of device, to find devices of a particular type, or to find devices that
implement a particular interface.  When iterating using ``pairs`` or ``ipairs``,
devices are returned by walking the device tree depth-first in creation order.

The index get operator looks up a device by tag.  It returns ``nil`` if no
device with the specified tag is found, or if the device with the specified tag
does not meet the type/interface requirements of the device enumerator.  The
complexity is O(1) if the result is cached, but an uncached device lookup is
expensive.  The ``at`` method has O(n) complexity.

If you create a device enumerator with a starting point other than the root
machine device, passing an absolute tag or a tag containing parent references to
the index operator may return a device that would not be discovered by
iteration.  If you create a device enumerator with restricted depth, devices
that would not be found due to being too deep in the hierarchy can still be
looked up by tag.

Creating a device enumerator with depth restricted to zero can be used to
downcast a device or test whether a device implements a certain interface.  For
example this will test whether a device implements the media image interface:

.. code-block:: Lua

    image_intf = emu.image_enumerator(device, 0):at(1)
    if image_intf then
        print(string.format("Device %s mounts images", device.tag))
    end

Instantiation
^^^^^^^^^^^^^

manager.machine.devices
    Returns a device enumerator that will iterate over
    :ref:`devices <luareference-dev-device>` in the system.
manager.machine.palettes
    Returns a device enumerator that will iterate over
    :ref:`palette devices <luareference-dev-dipalette>` in the system.
manager.machine.screens
    Returns a device enumerator that will iterate over
    :ref:`screen devices <luareference-dev-screen>` in the system.
manager.machine.cassettes
    Returns a device enumerator that will iterate over
    :ref:`cassette image devices <luareference-dev-cass>` in the system.
manager.machine.images
    Returns a device enumerator that will iterate over
    :ref:`media image devices <luareference-dev-diimage>` in the system.
manager.machine.slots
    Returns a device enumerator that will iterate over
    :ref:`slot devices <luareference-dev-dislot>` in the system.
emu.device_enumerator(device, [depth])
    Returns a device enumerator that will iterate over
    :ref:`devices <luareference-dev-device>` in the sub-tree starting at the
    specified device.  The specified device will be included.  If the depth is
    provided, it must be an integer specifying the maximum number of levels to
    iterate below the specified device (i.e. 1 will limit iteration to the
    device and its immediate children).
emu.palette_enumerator(device, [depth])
    Returns a device enumerator that will iterate over
    :ref:`palette devices <luareference-dev-dipalette>` in the sub-tree starting
    at the specified device.  The specified device will be included if it is a
    palette device.  If the depth is provided, it must be an integer specifying
    the maximum number of levels to iterate below the specified device (i.e. 1
    will limit iteration to the device and its immediate children).
emu.screen_enumerator(device, [depth])
    Returns a device enumerator that will iterate over
    :ref:`screen devices <luareference-dev-screen>` in the sub-tree starting at
    the specified device.  The specified device will be included if it is a
    screen device.  If the depth is provided, it must be an integer specifying
    the maximum number of levels to iterate below the specified device (i.e. 1
    will limit iteration to the device and its immediate children).
emu.cassette_enumerator(device, [depth])
    Returns a device enumerator that will iterate over
    :ref:`cassette image devices <luareference-dev-cass>` in the sub-tree
    starting at the specified device.  The specified device will be included if
    it is a cassette image device.  If the depth is provided, it must be an
    integer specifying the maximum number of levels to iterate below the
    specified device (i.e. 1 will limit iteration to the device and its
    immediate children).
emu.image_enumerator(device, [depth])
    Returns a device enumerator that will iterate over
    :ref:`media image devices <luareference-dev-diimage>` in the sub-tree
    starting at the specified device.  The specified device will be included if
    it is a media image device.  If the depth is provided, it must be an integer
    specifying the maximum number of levels to iterate below the specified
    device (i.e. 1 will limit iteration to the device and its immediate
    children).
emu.slot_enumerator(device, [depth])
    Returns a device enumerator that will iterate over
    :ref:`slot devices <luareference-dev-dislot>` in the sub-tree starting at
    the specified device.  The specified device will be included if it is a
    slot device.  If the depth is provided, it must be an integer specifying the
    maximum number of levels to iterate below the specified device (i.e. 1 will
    limit iteration to the device and its immediate children).

.. _luareference-dev-device:

Device
~~~~~~

Wraps MAME’s ``device_t`` class, which is a base of all device classes.

Instantiation
^^^^^^^^^^^^^

manager.machine.devices[tag]
    Gets a device by tag relative to the root machine device, or ``nil`` if no
    such device exists.
manager.machine.devices[tag]:subdevice(tag)
    Gets a device by tag relative to another arbitrary device, or ``nil`` if no
    such device exists.

Methods
^^^^^^^

device:subtag(tag)
    Converts a tag relative to the device to an absolute tag.
device:siblingtag(tag)
    Converts a tag relative to the device’s parent device to an absolute tag.
device:memshare(tag)
    Gets a :ref:`memory share <luareference-mem-share>` by tag relative to the
    device, or ``nil`` if no such memory share exists.
device:membank(tag)
    Gets a :ref:`memory bank <luareference-mem-bank>` by tag relative to the
    device, or ``nil`` if no such memory bank exists.
device:memregion(tag)
    Gets a :ref:`memory region <luareference-mem-region>` by tag relative to the
    device, or ``nil`` if no such memory region exists.
device:ioport(tag)
    Gets an :ref:`I/O port <luareference-input-ioport>` by tag relative to the
    device, or ``nil`` if no such I/O port exists.
device:subdevice(tag)
    Gets a device by tag relative to the device.
device:siblingdevice(tag)
    Gets a device by tag relative to the device’s parent.
device:parameter(tag)
    Gets a parameter value by tag relative to the device, or an empty string if
    the parameter is not set.

Properties
^^^^^^^^^^

device.tag (read-only)
    The device’s absolute tag in canonical form.
device.basetag (read-only)
    The last component of the device’s tag (i.e. its tag relative to its
    immediate parent), or ``"root"`` for the root machine device.
device.name (read-only)
    The full display name for the device’s type.
device.shortname (read-only)
    The short name of the devices type (this is used, e.g. on the command line,
    when looking for resource like ROMs or artwork, and in various data files).
device.owner (read-only)
    The device’s immediate parent in the device tree, or ``nil`` for the root
    machine device.
device.configured (read-only)
    A Boolean indicating whether the device has completed configuration.
device.started (read-only)
    A Boolean indicating whether the device has completed starting.
device.debug (read-only)
    The :ref:`debugger interface <luareference-debug-devdebug>` to the device if
    it is a CPU device, or ``nil`` if it is not a CPU device or the debugger is
    not enabled.
device.state[] (read-only)
    The :ref:`state entries <luareference-dev-stateentry>` for devices that
    expose the register state interface, indexed by symbol, or ``nil`` for other
    devices.  The index operator and ``index_of`` methods have O(n) complexity;
    all other supported operations have O(1) complexity.
device.spaces[] (read-only)
    A table of the device’s :ref:`address spaces <luareference-mem-space>`,
    indexed by name.  Only valid for devices that implement the memory
    interface.  Note that the names are specific to the device type and have no
    special significance.

.. _luareference-dev-dipalette:

Palette device
~~~~~~~~~~~~~~

Wraps MAME’s ``device_palette_interface`` class, which represents a device that
translates pen values to colours.

Colours are represented in alpha/red/green/blue (ARGB) format.  Channel values
range from 0 (transparent or off) to 255 (opaque or full intensity), inclusive.
Colour channel values are not pre-multiplied by the alpha value.  Channel values
are packed into the bytes of 32-bit unsigned integers, in the order alpha, red,
green, blue from most-significant to least-significant byte.

Instantiation
^^^^^^^^^^^^^

manager.machine.palettes[tag]
    Gets a palette device by tag relative to the root machine device, or ``nil``
    if no such device exists or it is not a palette device.

Methods
^^^^^^^

palette:pen(index)
    Gets the remapped pen number for the specified palette index.
palette:pen_color(pen)
    Gets the colour for the specified pen number.
palette:pen_contrast(pen)
    Gets the contrast value for the specified pen number.  The contrast is a
    floating-point number.
palette:pen_indirect(index)
    Gets the indirect pen index for the specified palette index.
palette:indirect_color(index)
    Gets the indirect pen colour for the specified palette index.
palette:set_pen_color(pen, color)
    Sets the colour for the specified pen number.  The colour may be specified
    as a single packed 32-bit value; or as individual red, green and blue
    channel values, in that order.
palette:set_pen_red_level(pen, level)
    Sets the red channel value of the colour for the specified pen number.
    Other channel values are not affected.
palette:set_pen_green_level(pen, level)
    Sets the green channel value of the colour for the specified pen number.
    Other channel values are not affected.
palette:set_pen_blue_level(pen, level)
    Sets the blue channel value of the colour for the specified pen number.
    Other channel values are not affected.
palette:set_pen_contrast(pen, factor)
    Sets the contrast value for the specified pen number.  The value must be a
    floating-point number.
palette:set_pen_indirect(pen, index)
    Sets the indirect pen index for the specified pen number.
palette:set_indirect_color(index, color)
    Sets the indirect pen colour for the specified palette index.  The colour
    may be specified as a single packed 32-bit value; or as individual red,
    green and blue channel values, in that order.
palette:set_shadow_factor(factor)
    Sets the contrast value for the current shadow group.  The value must be a
    floating-point number.
palette:set_highlight_factor(factor)
    Sets the contrast value for the current highlight group.  The value must be
    a floating-point number.
palette:set_shadow_mode(mode)
    Sets the shadow mode.  The value is the index of the desired shadow table.

Properties
^^^^^^^^^^

palette.palette (read-only)
    The underlying :ref:`palette <luareference-render-palette>` managed by the
    device.
palette.entries (read-only)
    The number of colour entries in the palette.
palette.indirect_entries (read-only)
    The number of indirect pen entries in the palette.
palette.black_pen (read-only)
    The index of the fixed black pen entry.
palette.white_pen (read-only)
    The index of the fixed white pen.
palette.shadows_enabled (read-only)
    A Boolean indicating whether shadow colours are enabled.
palette.highlights_enabled (read-only)
    A Boolean indicating whether highlight colours are enabled.
palette.device (read-only)
    The underlying :ref:`device <luareference-dev-device>`.

.. _luareference-dev-screen:

Screen device
~~~~~~~~~~~~~

Wraps MAME’s ``screen_device`` class, which represents an emulated video output.

Instantiation
^^^^^^^^^^^^^

manager.machine.screens[tag]
    Gets a screen device by tag relative to the root machine device, or ``nil``
    if no such device exists or it is not a screen device.

Base classes
^^^^^^^^^^^^

* :ref:`luareference-dev-device`

Methods
^^^^^^^

screen:orientation()
    Returns the rotation angle in degrees (will be one of 0, 90, 180 or 270),
    whether the screen is flipped left-to-right, and whether the screen is
    flipped top-to-bottom.  This is the final screen orientation after the
    screen orientation specified in the machine configuration and the rotation
    for the system driver are applied.
screen:time_until_pos(v, [h])
    Gets the time remaining until the raster reaches the specified position.  If
    the horizontal component of the position is not specified, it defaults to
    zero (0, i.e. the beginning of the line).  The result is a floating-point
    number in units of seconds.
screen:time_until_vblank_start()
    Gets the time remaining until the start of the vertical blanking interval.
    The result is a floating-point number in units of seconds.
screen:time_until_vblank_end()
    Gets the time remaining until the end of the vertical blanking interval.
    The result is a floating-point number in units of seconds.
screen:snapshot([filename])
    Saves a screen snapshot in PNG format.  If no filename is supplied, the
    configured snapshot path and name format will be used.  If the supplied
    filename is not an absolute path, it is interpreted relative to the first
    configured snapshot path.  The filename may contain conversion specifiers
    that will be replaced by the system name or an incrementing number.

    Returns a file error if opening the snapshot file failed, or ``nil``
    otherwise.
screen:pixel(x, y)
    Gets the pixel at the specified location.  Coordinates are in pixels, with
    the origin at the top left corner of the visible area, increasing to the
    right and down.  Returns either a palette index or a colour in RGB format
    packed into a 32-bit integer.  Returns zero (0) if the specified point is
    outside the visible area.
screen:pixels()
    Returns all visible pixels, the visible area width and visible area height.

    Pixels are returned as 32-bit integers packed into a binary string in host
    Endian order.  Pixels are organised in row-major order, from left to right
    then top to bottom.  Pixels values are either palette indices or colours in
    RGB format packed into 32-bit integers.
screen:draw_box(left, top, right, bottom, [line], [fill])
    Draws an outlined rectangle with edges at the specified positions.

    Coordinates are floating-point numbers in units of emulated screen pixels,
    with the origin at (0, 0).  Note that emulated screen pixels often aren’t
    square.  The coordinate system is rotated if the screen is rotated, which is
    usually the case for vertical-format screens.  Before rotation, the origin
    is at the top left, and coordinates increase to the right and downwards.
    Coordinates are limited to the screen area.

    The fill and line colours are in alpha/red/green/blue (ARGB) format.
    Channel values are in the range 0 (transparent or off) to 255 (opaque or
    full intensity), inclusive.  Colour channel values are not pre-multiplied by
    the alpha value.  The channel values must be packed into the bytes of a
    32-bit unsigned integer, in the order alpha, red, green, blue from
    most-significant to least-significant byte.  If the line colour is not
    provided, the UI text colour is used; if the fill colour is not provided,
    the UI background colour is used.
screen:draw_line(x0, y0, x1, y1, [color])
    Draws a line from (x0, y0) to (x1, y1).

    Coordinates are floating-point numbers in units of emulated screen pixels,
    with the origin at (0, 0).  Note that emulated screen pixels often aren’t
    square.  The coordinate system is rotated if the screen is rotated, which is
    usually the case for vertical-format screens.  Before rotation, the origin
    is at the top left, and coordinates increase to the right and downwards.
    Coordinates are limited to the screen area.

    The line colour is in alpha/red/green/blue (ARGB) format.  Channel values
    are in the range 0 (transparent or off) to 255 (opaque or full intensity),
    inclusive.  Colour channel values are not pre-multiplied by the alpha value.
    The channel values must be packed into the bytes of a 32-bit unsigned
    integer, in the order alpha, red, green, blue from most-significant to
    least-significant byte.  If the line colour is not provided, the UI text
    colour is used.
screen:draw_text(x|justify, y, text, [foreground], [background])
    Draws text at the specified position.  If the screen is rotated the text
    will be rotated.

    If the first argument is a number, the text will be left-aligned at this X
    coordinate.  If the first argument is a string, it must be ``"left"``,
    ``"center"`` or ``"right"`` to draw the text left-aligned at the
    left edge of the screen, horizontally centred on the screen, or
    right-aligned at the right edge of the screen, respectively.  The second
    argument specifies the Y coordinate of the maximum ascent of the text.

    Coordinates are floating-point numbers in units of emulated screen pixels,
    with the origin at (0, 0).  Note that emulated screen pixels often aren’t
    square.  The coordinate system is rotated if the screen is rotated, which is
    usually the case for vertical-format screens.  Before rotation, the origin
    is at the top left, and coordinates increase to the right and downwards.
    Coordinates are limited to the screen area.

    The foreground and background colours are in alpha/red/green/blue (ARGB)
    format.  Channel values are in the range 0 (transparent or off) to 255
    (opaque or full intensity), inclusive.  Colour channel values are not
    pre-multiplied by the alpha value.  The channel values must be packed into
    the bytes of a 32-bit unsigned integer, in the order alpha, red, green, blue
    from most-significant to least-significant byte.  If the foreground colour
    is not provided, the UI text colour is used; if the background colour is not
    provided, it is fully transparent.

Properties
^^^^^^^^^^

screen.width (read-only)
    The width of the bitmap produced by the emulated screen in pixels.
screen.height (read-only)
    The height of the bitmap produced by the emulated screen in pixels.
screen.refresh (read-only)
    The screen’s configured refresh rate in Hertz (this may not reflect the
    current value).
screen.refresh_attoseconds (read-only)
    The screen’s configured refresh interval in attoseconds (this may not
    reflect the current value).
screen.xoffset (read-only)
    The screen’s default X position offset.  This is a floating-point number
    where one (1) corresponds to the X size of the screen’s container.  This may
    be useful for restoring the default after adjusting the X offset via the
    screen’s container.
screen.yoffset (read-only)
    The screen’s default Y position offset.  This is a floating-point number
    where one (1) corresponds to the Y size of the screen’s container.  This may
    be useful for restoring the default after adjusting the Y offset via the
    screen’s container.
screen.xscale (read-only)
    The screen’s default X scale factor, as a floating-point number.  This may
    be useful for restoring the default after adjusting the X scale via the
    screen’s container.
screen.yscale (read-only)
    The screen’s default Y scale factor, as a floating-point number.  This may
    be useful for restoring the default after adjusting the Y scale via the
    screen’s container.
screen.pixel_period (read-only)
    The interval taken to draw a horizontal pixel, as a floating-point number in
    units of seconds.
screen.scan_period (read-only)
    The interval taken to draw a scan line (including the horizontal blanking
    interval), as a floating-point number in units of seconds.
screen.frame_period (read-only)
    The interval taken to draw a complete frame (including blanking intervals),
    as a floating-point number in units of seconds.
screen.frame_number (read-only)
    The current frame number for the screen.  This increments monotonically each
    frame interval.
screen.container (read-only)
    The :ref:`render container <luareference-render-container>` used to draw the
    screen.
screen.palette (read-only)
    The :ref:`palette device <luareference-dev-dipalette>` used to translate
    pixel values to colours, or ``nil`` if the screen uses a direct colour pixel
    format.

.. _luareference-dev-cass:

Cassette image device
~~~~~~~~~~~~~~~~~~~~~

Wraps MAME’s ``cassette_image_device`` class, representing a compact cassette
mechanism typically used by a home computer for program storage.

Instantiation
^^^^^^^^^^^^^

manager.machine.cassettes[tag]
    Gets a cassette image device by tag relative to the root machine device, or
    ``nil`` if no such device exists or it is not a cassette image device.

Base classes
^^^^^^^^^^^^

* :ref:`luareference-dev-device`
* :ref:`luareference-dev-diimage`

Methods
^^^^^^^

cassette:stop()
    Disables playback.
cassette:play()
    Enables playback.  The cassette will play if the motor is enabled.
cassette:forward()
    Sets forward play direction.
cassette:reverse()
    Sets reverse play direction.
cassette:seek(time, whence)
    Jump to the specified position on the tape.  The time is a floating-point
    number in units of seconds, relative to the point specified by the whence
    argument.  The whence argument must be one of ``"set"``, ``"cur"`` or
    ``"end"`` to seek relative to the start of the tape, the current position,
    or the end of the tape, respectively.

Properties
^^^^^^^^^^

cassette.is_stopped (read-only)
    A Boolean indicating whether the cassette is stopped (i.e. not recording and
    not playing).
cassette.is_playing (read-only)
    A Boolean indicating whether playback is enabled (i.e. the cassette will
    play if the motor is enabled).
cassette.is_recording (read-only)
    A Boolean indicating whether recording is enabled (i.e. the cassette will
    record if the motor is enabled).
cassette.motor_state (read/write)
    A Boolean indicating whether the cassette motor is enabled.
cassette.speaker_state (read/write)
    A Boolean indicating whether the cassette speaker is enabled.
cassette.position (read-only)
    The current position as a floating-point number in units of seconds relative
    to the start of the tape.
cassette.length (read-only)
    The length of the tape as a floating-point number in units of seconds, or
    zero (0) if no tape image is mounted.

.. _luareference-dev-diimage:

Image device interface
~~~~~~~~~~~~~~~~~~~~~~

Wraps MAME’s ``device_image_interface`` class which is a mix-in implemented by
devices that can load media image files.

Instantiation
^^^^^^^^^^^^^

manager.machine.images[tag]
    Gets an image device by tag relative to the root machine device, or ``nil``
    if no such device exists or it is not a media image device.

Methods
^^^^^^^

image:load(filename)
    Loads the specified file as a media image.  Returns ``"pass"`` or
    ``"fail"``.
image:load_software(name)
    Loads a media image described in a software list.  Returns ``"pass"`` or
    ``"fail"``.
image:unload()
    Unloads the mounted image.
image:create(filename)
    Creates and mounts a media image file with the specified name.  Returns
    ``"pass"`` or ``"fail"``.
image:display()
    Returns a “front panel display” string for the device, if supported.  This
    can be used to show status information, like the current head position or
    motor state.

Properties
^^^^^^^^^^

image.is_readable (read-only)
    A Boolean indicating whether the device supports reading.
image.is_writeable (read-only)
    A Boolean indicating whether the device supports writing.
image.must_be_loaded (read-only)
    A Boolean indicating whether the device requires a media image to be loaded
    in order to start.
image.is_reset_on_load (read-only)
    A Boolean indicating whether the device requires a hard reset to change
    media images (usually for cartridge slots that contain hardware in addition
    to memory chips).
image.image_type_name (read-only)
    A string for categorising the media device.
image.instance_name (read-only)
    The instance name of the device in the current configuration.  This is used
    for setting the media image to load on the command line or in INI files.
    This is not stable, it may have a number appended that may change depending
    on slot configuration.
image.brief_instance_name (read-only)
    The brief instance name of the device in the current configuration.  This is
    used for setting the media image to load on the command line or in INI
    files.  This is not stable, it may have a number appended that may change
    depending on slot configuration.
image.formatlist[] (read-only)
    The :ref:`media image formats <luareference-dev-imagefmt>` supported by the
    device, indexed by name.  The index operator and ``index_of`` methods have
    O(n) complexity; all other supported operations have O(1) complexity.
image.exists (read-only)
    A Boolean indicating whether a media image file is mounted.
image.readonly (read-only)
    A Boolean indicating whether a media image file is mounted in read-only
    mode.
image.filename (read-only)
    The full path to the mounted media image file, or ``nil`` if no media image
    is mounted.
image.crc (read-only)
    The 32-bit cyclic redundancy check of the content of the mounted image file
    if the mounted media image was not loaded from a software list, is mounted
    read-only and is not a CD-ROM, or zero (0) otherwise.
image.loaded_through_softlist (read-only)
    A Boolean indicating whether the mounted media image was loaded from a
    software list, or ``false`` if no media image is mounted.
image.software_list_name (read-only)
    The short name of the software list if the mounted media image was loaded
    from a software list.
image.software_longname (read-only)
    The full name of the software item if the mounted media image was loaded
    from a software list, or ``nil`` otherwise.
image.software_publisher (read-only)
    The publisher of the software item if the mounted media image was loaded
    from a software list, or ``nil`` otherwise.
image.software_year (read-only)
    The release year of the software item if the mounted media image was loaded
    from a software list, or ``nil`` otherwise.
image.software_parent (read-only)
    The short name of the parent software item if the mounted media image was
    loaded from a software list, or ``nil`` otherwise.
image.device (read-only)
    The underlying :ref:`device <luareference-dev-device>`.

.. _luareference-dev-dislot:

Slot device interface
~~~~~~~~~~~~~~~~~~~~~

Wraps MAME’s ``device_slot_interface`` class which is a mix-in implemented by
devices that instantiate a user-specified child device.

Instantiation
^^^^^^^^^^^^^

manager.machine.slots[tag]
    Gets an slot device by tag relative to the root machine device, or ``nil``
    if no such device exists or it is not a slot device.

Properties
^^^^^^^^^^

slot.fixed (read-only)
    A Boolean indicating whether this is a slot with a card specified in machine
    configuration that cannot be changed by the user.
slot.has_selectable_options (read-only)
    A Boolean indicating whether the slot has any user-selectable options (as
    opposed to options that can only be selected programmatically, typically for
    fixed slots or to load media images).
slot.options[] (read-only)
    The :ref:`slot options <luareference-dev-slotopt>` describing the child
    devices that can be instantiated by the slot, indexed by option value.  The
    ``at`` and ``index_of`` methods have O(n) complexity; all other supported
    operations have O(1) complexity.
slot.device (read-only)
    The underlying :ref:`device <luareference-dev-device>`.

.. _luareference-dev-stateentry:

Device state entry
~~~~~~~~~~~~~~~~~~

Wraps MAME’s ``device_state_entry`` class, which allows access to named
registers exposed by a :ref:`device <luareference-dev-device>`.  Supports
conversion to string for display.

Instantiation
^^^^^^^^^^^^^

manager.machine.devices[tag].state[symbol]
    Gets a state entry for a given device by symbol.

Properties
^^^^^^^^^^

entry.value (read/write)
    The numeric value of the state entry, as either an integer or floating-point
    number.  Attempting to set the value of a read-only state entry raises an
    error.
entry.symbol (read-only)
    The state entry’s symbolic name.
entry.visible (read-only)
    A Boolean indicating whether the state entry should be displayed in the
    debugger register view.
entry.writeable (read-only)
    A Boolean indicating whether it is possible to modify the state entry’s
    value.
entry.is_float (read-only)
    A Boolean indicating whether the state entry’s value is a floating-point
    number.
entry.datamask (read-only)
    A bit mask of the valid bits of the value for integer state entries.
entry.datasize (read-only)
    The size of the underlying value in bytes for integer state entries.
entry.max_length (read-only)
    The maximum display string length for the state entry.

.. _luareference-dev-imagefmt:

Media image format
~~~~~~~~~~~~~~~~~~

Wraps MAME’s ``image_device_format`` class, which describes a media file format
supported by a :ref:`media image device <luareference-dev-diimage>`.

Instantiation
^^^^^^^^^^^^^

manager.machine.images[tag].formatlist[name]
    Gets a media image format supported by a given device by name.

Properties
^^^^^^^^^^

format.name (read-only)
    An abbreviated name used to identify the format.  This often matches the
    primary filename extension used for the format.
format.description (read-only)
    The full display name of the format.
format.extensions[] (read-only)
    Yields a table of filename extensions used for the format.
format.option_spec (read-only)
    A string describing options available when creating a media image using this
    format.  The string is not intended to be human-readable.

.. _luareference-dev-slotopt:

Slot option
~~~~~~~~~~~

Wraps MAME’s ``device_slot_interface::slot_option`` class, which represents a
child device that a :ref:`slot device <luareference-dev-dislot>` can be
configured to instantiate.

Instantiation
^^^^^^^^^^^^^

manager.machine.slots[tag].options[name]
    Gets a slot option for a given :ref:`slot device <luareference-dev-dislot>`
    by name (i.e. the value used to select the option).

Properties
^^^^^^^^^^

option.name (read-only)
    The name of the slot option.  This is the value used to select this option
    on the command line or in an INI file.
option.device_fullname (read-only)
    The full display name of the device type instantiated by this option.
option.device_shortname (read-only)
    The short name of the device type instantiated by this option.
option.selectable (read-only)
    A Boolean indicating whether the option may be selected by the user (options
    that are not user-selectable are typically used for fixed slots or to load
    media images).
option.default_bios (read-only)
    The default BIOS setting for the device instantiated using this option, or
    ``nil`` if the default BIOS specified in the device’s ROM definitions will
    be used.
option.clock (read-only)
    The configured clock frequency for the device instantiated using this
    option.  This is an unsigned 32-bit integer.  If the eight most-significant
    bits are all set, it is a ratio of the parent device’s clock frequency, with
    the numerator in bits 12-23 and the denominator in bits 0-11.  If the eight
    most-significant bits are not all set, it is a frequency in Hertz.


.. _luareference-mem:

Memory system
-------------

MAME’s Lua interface exposes various memory system objects, including address
spaces, memory shares, memory banks, and memory regions.  Scripts can read from
and write to the emulated memory system.

.. _luareference-mem-manager:

Memory manager
~~~~~~~~~~~~~~

Wraps MAME’s ``memory_manager`` class, which allows the memory shares, banks and
regions in a system to be enumerated.

Instantiation
^^^^^^^^^^^^^

manager.machine.memory
    Gets the global memory manager instance for the emulated system.

Properties
^^^^^^^^^^

memory.shares[]
    The :ref:`memory shares <luareference-mem-share>` in the system, indexed by
    absolute tag.  The ``at`` and ``index_of`` methods have O(n) complexity; all
    other supported operations have O(1) complexity.
memory.banks[]
    The :ref:`memory banks <luareference-mem-bank>` in the system, indexed by
    absolute tag.  The ``at`` and ``index_of`` methods have O(n) complexity; all
    other supported operations have O(1) complexity.
memory.regions[]
    The :ref:`memory regions <luareference-mem-region>` in the system, indexed
    by absolute tag.  The ``at`` and ``index_of`` methods have O(n) complexity;
    all other supported operations have O(1) complexity.

.. _luareference-mem-space:

Address space
~~~~~~~~~~~~~

Wraps MAME’s ``address_space`` class, which represent’s an address space
belonging to a device.

Instantiation
^^^^^^^^^^^^^

manager.machine.devices[tag].spaces[name]
    Gets the address space with the specified name for a given device.  Note
    that names are specific to the device type.

Methods
^^^^^^^

space:read_i{8,16,32,64}(addr)
    Reads a signed integer value of the size in bits from the specified address.
space:read_u{8,16,32,64}(addr)
    Reads an unsigned integer value of the size in bits from the specified
    address.
space:write_i{8,16,32,64}(addr, val)
    Writes a signed integer value of the size in bits to the specified address.
space:write_u{8,16,32,64}(addr, val)
    Writes an unsigned integer value of the size in bits to the specified
    address.
space:readv_i{8,16,32,64}(addr)
    Reads a signed integer value of the size in bits from the specified virtual
    address.  The address is translated with the debug read intent.  Returns
    zero if address translation fails.
space:readv_u{8,16,32,64}(addr)
    Reads an unsigned integer value of the size in bits from the specified
    virtual address.  The address is translated with the debug read intent.
    Returns zero if address translation fails.
space:writev_i{8,16,32,64}(addr, val)
    Writes a signed integer value of the size in bits to the specified virtual
    address.  The address is translated with the debug write intent.  Does not
    write if address translation fails.
space:writev_u{8,16,32,64}(addr, val)
    Writes an unsigned integer value of the size in bits to the specified
    virtual address.  The address is translated with the debug write intent.
    Does not write if address translation fails.
space:read_direct_i{8,16,32,64}(addr)
    Reads a signed integer value of the size in bits from the specified address
    one byte at a time by obtaining a read pointer for each byte address.  If
    a read pointer cannot be obtained for a byte address, the corresponding
    result byte will be zero.
space:read_direct_u{8,16,32,64}(addr)
    Reads an unsigned integer value of the size in bits from the specified
    address one byte at a time by obtaining a read pointer for each byte
    address.  If a read pointer cannot be obtained for a byte address, the
    corresponding result byte will be zero.
space:write_direct_i{8,16,32,64}(addr, val)
    Writes a signed integer value of the size in bits to the specified address
    one byte at a time by obtaining a write pointer for each byte address.  If
    a write pointer cannot be obtained for a byte address, the corresponding
    byte will not be written.
space:write_direct_u{8,16,32,64}(addr, val)
    Writes an unsigned integer value of the size in bits to the specified
    address one byte at a time by obtaining a write pointer for each byte
    address.  If a write pointer cannot be obtained for a byte address, the
    corresponding byte will not be written.
space:read_range(start, end, width, [step])
    Reads a range of addresses as a binary string.  The end address must be
    greater than or equal to the start address.  The width must be 8, 16, 30 or
    64.  If the step is provided, it must be a positive number of elements.
space:add_change_notifier(callback)
    Add a callback to receive notifications for handler changes in address
    space.  The callback function is passed a single string as an argument,
    either ``r`` if read handlers have potentially changed, ``w`` if write
    handlers have potentially changed, or ``rw`` if both read and write handlers
    have potentially changed.

    Returns a :ref:`notifier subscription <luareference-core-notifiersub>`.
space:install_read_tap(start, end, name, callback)
    Installs a :ref:`pass-through handler <luareference-mem-tap>` that will
    receive notifications on reads from the specified range of addresses in the
    address space.  The start and end addresses are inclusive.  The name must be
    a string, and the callback must be a function.

    The callback is passed three arguments for the access offset, the data read,
    and the memory access mask.  The offset is the absolute offset into the
    address space.  To modify the data being read, return the modified value
    from the callback function as an integer.  If the callback does not return
    an integer, the data will not be modified.
space:install_write_tap(start, end, name, callback)
    Installs a :ref:`pass-through handler <luareference-mem-tap>` that will
    receive notifications on write to the specified range of addresses in the
    address space.  The start and end addresses are inclusive.  The name must be
    a string, and the callback must be a function.

    The callback is passed three arguments for the access offset, the data
    written, and the memory access mask.  The offset is the absolute offset into
    the address space.  To modify the data being written, return the modified
    value from the callback function as an integer.  If the callback does not
    return an integer, the data will not be modified.

Properties
^^^^^^^^^^

space.name (read-only)
    The display name for the address space.
space.shift (read-only)
    The address granularity for the address space specified as the shift
    required to translate a byte address to a native address.  Positive values
    shift towards the most significant bit (left) and negative values shift
    towards the least significant bit (right).
space.index (read-only)
    The zero-based space index.  Some space indices have special meanings for
    the debugger.
space.address_mask (read-only)
    The address mask for the space.
space.data_width (read-only)
    The data width for the space in bits.
space.endianness (read-only)
    The Endianness of the space (``"big"`` or ``"little"``).
space.map (read-only)
    The configured :ref:`address map <luareference-mem-map>` for the space or
    ``nil``.

.. _luareference-mem-tap:

Pass-through handler
~~~~~~~~~~~~~~~~~~~~

Tracks a pass-through handler installed in an
:ref:`address space <luareference-mem-space>`.  A memory pass-through handler
receives notifications on accesses to a specified range of addresses, and can
modify the data that is read or written if desired.

Instantiation
^^^^^^^^^^^^^

manager.machine.devices[tag].spaces[name]:install_read_tap(start, end, name, callback)
    Installs a pass-through handler that will receive notifications on reads
    from the specified range of addresses in an
    :ref:`address space <luareference-mem-space>`.
manager.machine.devices[tag].spaces[name]:install_write_tap(start, end, name, callback)
    Installs a pass-through handler that will receive notifications on writes to
    the specified range of addresses in an
    :ref:`address space <luareference-mem-space>`.

Methods
^^^^^^^

passthrough:reinstall()
    Reinstalls the pass-through handler in the address space.  May be necessary
    if the handler is removed due to other changes to handlers in the address
    space.
passthrough:remove()
    Removes the pass-through handler from the address space.  The associated
    callback will not be called in response to future memory accesses.

Properties
^^^^^^^^^^

passthrough.addrstart (read-only)
    The inclusive start address of the address range monitored by the
    pass-through handler (i.e. the lowest address that the handler will be
    notified for).
passthrough.addrend (read-only)
    The inclusive end address of the address range monitored by the pass-through
    handler (i.e. the highest address that the handler will be notified for).
passthrough.name (read-only)
    The display name for the pass-through handler.

.. _luareference-mem-map:

Address map
~~~~~~~~~~~

Wraps MAME’s ``address_map`` class, used to configure handlers for an address
space.

Instantiation
^^^^^^^^^^^^^

manager.machine.devices[tag].spaces[name].map
    Gets the configured address map for an address space, or ``nil`` if no map
    is configured.

Properties
^^^^^^^^^^

map.spacenum (read-only)
    The address space number of the address space the map is associated with.
map.device (read-only)
    The device that owns the address space the map is associated with.
map.unmap_value (read-only)
    The constant value to return from unmapped reads.
map.global_mask (read-only)
    Global mask to be applied to all addresses when accessing the space.
map.entries[] (read-only)
    The configured :ref:`entries <luareference-mem-mapentry>` in the address
    map.  Uses 1-based integer indices.  The index operator and the ``at``
    method have O(n) complexity.

.. _luareference-mem-mapentry:

Address map entry
~~~~~~~~~~~~~~~~~

Wraps MAME’s ``address_map_entry`` class, representing an entry in a configured
address map.

Instantiation
^^^^^^^^^^^^^

manager.machine.devices[tag].spaces[name].map.entries[index]
    Gets an entry from the configured map for an address space.

Properties
^^^^^^^^^^

entry.address_start (read-only)
    Start address of the entry’s range.
entry.address_end (read-only)
    End address of the entry’s range (inclusive).
entry.address_mirror (read-only)
    Address mirror bits.
entry.address_mask (read-only)
    Address mask bits.  Only valid for handlers.
entry.mask (read-only)
    Lane mask, indicating which data lines on the bus are connected to the
    handler.
entry.cswidth (read-only)
    The trigger width for a handler that isn’t connected to all the data lines.
entry.read (read-only)
    :ref:`Additional data <luareference-memory-handlerdata>` for the read
    handler.
entry.write (read-only)
    :ref:`Additional data <luareference-memory-handlerdata>` for the write
    handler.
entry.share (read-only)
    Memory share tag for making RAM entries accessible or ``nil``.
entry.region (read-only)
    Explicit memory region tag for ROM entries, or ``nil``.  For ROM entries,
    ``nil`` infers the region from the device tag.
entry.region_offset (read-only)
    Starting offset in memory region for ROM entries.

.. _luareference-memory-handlerdata:

Address map handler data
~~~~~~~~~~~~~~~~~~~~~~~~

Wraps MAME’s ``map_handler_data`` class, which provides configuration data to
handlers in address maps.

Instantiation
^^^^^^^^^^^^^

manager.machine.devices[tag].spaces[name].map.entries[index].read
    Gets the read handler data for an address map entry.
manager.machine.devices[tag].spaces[name].map.entries[index].write
    Gets the write handler data for an address map entry.

Properties
^^^^^^^^^^

data.handlertype (read-only)
    Handler type.  Will be one of ``"none"``, ``"ram"``, ``"rom"``, ``"nop"``,
    ``"unmap"``, ``"delegate"``, ``"port"``, ``"bank"``, ``"submap"``, or
    ``"unknown"``.  Note that multiple handler type values can yield
    ``"delegate"`` or ``"unknown"``.
data.bits (read-only)
    Data width for the handler in bits.
data.name (read-only)
    Display name for the handler, or ``nil``.
data.tag (read-only)
    Tag for I/O ports and memory banks, or ``nil``.

.. _luareference-mem-share:

Memory share
~~~~~~~~~~~~

Wraps MAME’s ``memory_share`` class, representing a named allocated memory zone.

Instantiation
^^^^^^^^^^^^^

manager.machine.memory.shares[tag]
    Gets a memory share by absolute tag, or ``nil`` if no such memory share
    exists.
manager.machine.devices[tag]:memshare(tag)
    Gets a memory share by tag relative to a device, or ``nil`` if no such
    memory share exists.

Methods
^^^^^^^

share:read_i{8,16,32,64}(offs)
    Reads a signed integer value of the size in bits from the specified offset
    in the memory share.
share:read_u{8,16,32,64}(offs)
    Reads an unsigned integer value of the size in bits from the specified
    offset in the memory share.
share:write_i{8,16,32,64}(offs, val)
    Writes a signed integer value of the size in bits to the specified offset in
    the memory share.
share:write_u{8,16,32,64}(offs, val)
    Writes an unsigned integer value of the size in bits to the specified offset
    in the memory share.

Properties
^^^^^^^^^^

share.tag (read-only)
    The absolute tag of the memory share.
share.size (read-only)
    The size of the memory share in bytes.
share.length (read-only)
    The length of the memory share in native width elements.
share.endianness (read-only)
    The Endianness of the memory share (``"big"`` or ``"little"``).
share.bitwidth (read-only)
    The native element width of the memory share in bits.
share.bytewidth (read-only)
    The native element width of the memory share in bytes.

.. _luareference-mem-bank:

Memory bank
~~~~~~~~~~~

Wraps MAME’s ``memory_bank`` class, representing a named memory zone
indirection.

Instantiation
^^^^^^^^^^^^^

manager.machine.memory.banks[tag]
    Gets a memory region by absolute tag, or ``nil`` if no such memory bank
    exists.
manager.machine.devices[tag]:membank(tag)
    Gets a memory region by tag relative to a device, or ``nil`` if no such
    memory bank exists.

Properties
^^^^^^^^^^

bank.tag (read-only)
    The absolute tag of the memory bank.
bank.entry (read/write)
    The currently selected zero-based entry number.

.. _luareference-mem-region:

Memory region
~~~~~~~~~~~~~

Wraps MAME’s ``memory_region`` class, representing a memory region used to store
read-only data like ROMs or the result of fixed decryptions.

Instantiation
^^^^^^^^^^^^^

manager.machine.memory.regions[tag]
    Gets a memory region by absolute tag, or ``nil`` if no such memory region
    exists.
manager.machine.devices[tag]:memregion(tag)
    Gets a memory region by tag relative to a device, or ``nil`` if no such
    memory region exists.

Methods
^^^^^^^

region:read_i{8,16,32,64}(offs)
    Reads a signed integer value of the size in bits from the specified offset
    in the memory region.
region:read_u{8,16,32,64}(offs)
    Reads an unsigned integer value of the size in bits from the specified
    offset in the memory region.
region:write_i{8,16,32,64}(offs, val)
    Writes a signed integer value of the size in bits to the specified offset in
    the memory region.
region:write_u{8,16,32,64}(offs, val)
    Writes an unsigned integer value of the size in bits to the specified offset
    in the memory region.

Properties
^^^^^^^^^^

region.tag (read-only)
    The absolute tag of the memory region.
region.size (read-only)
    The size of the memory region in bytes.
region.length (read-only)
    The length of the memory region in native width elements.
region.endianness (read-only)
    The Endianness of the memory region (``"big"`` or ``"little"``).
region.bitwidth (read-only)
    The native element width of the memory region in bits.
region.bytewidth (read-only)
    The native element width of the memory region in bytes.


.. _luareference-input:

Input system
------------

Allows scripts to get input from the user, and access I/O ports in the emulated
system.

.. _luareference-input-ioportman:

I/O port manager
~~~~~~~~~~~~~~~~

Wraps MAME’s ``ioport_manager`` class, which provides access to emulated I/O
ports and handles input configuration.

Instantiation
^^^^^^^^^^^^^

manager.machine.ioport
    Gets the global I/O port manager instance for the emulated machine.

Methods
^^^^^^^

ioport:count_players()
    Returns the number of player controllers in the system.
ioport:type_pressed(type, [player])
    Returns a Boolean indicating whether the specified input is currently
    pressed.  The input type may be an enumerated value or an
    :ref:`input type <luareference-input-inputtype>` entry.  If the input type
    is an enumerated value, the player number may be supplied as a zero-based
    index; if the player number is not supplied, it is assumed to be zero.  If
    the input type is an input type entry, the player number may not be supplied
    separately.
ioport:type_name(type, [player])
    Returns the display name for the specified input type and player number.
    The input type is an enumerated value.  The player number is a zero-based
    index.  If the player number is not supplied, it is assumed to be zero.
ioport:type_group(type, player)
    Returns the input group for the specified input type and player number.  The
    input type is an enumerated value.  The player number is a zero-based index.
    Returns an integer giving the grouping for the input.  If the player number
    is not supplied, it is assumed to be zero.

    This should be called with values obtained from I/O port fields to provide
    canonical grouping in an input configuration UI.
ioport:type_seq(type, [player], [seqtype])
    Get the configured :ref:`input sequence <luareference-input-iptseq>` for the
    specified input type, player number and sequence type.  The input type may
    be an enumerated value or an
    :ref:`input type <luareference-input-inputtype>` entry.  If the input type
    is an enumerated value, the player number may be supplied as a zero-based
    index; if the player number is not supplied, it is assumed to be zero.  If
    the input type is an input type entry, the player number may not be supplied
    separately.  If the sequence type is supplied, it must be ``"standard"``,
    ``"increment"`` or ``"decrement"``; if it is not supplied, it is assumed to
    be ``"standard"``.

    This provides access to general input configuration.
ioport:set_type_seq(type, [player], seqtype, seq)
    Set the configured :ref:`input sequence <luareference-input-iptseq>` for the
    specified input type, player number and sequence type.  The input type may
    be an enumerated value or an
    :ref:`input type <luareference-input-inputtype>` entry.  If the input type
    is an enumerated value, the player number must be supplied as a zero-based
    index.  If the input type is an input type entry, the player number may not
    be supplied separately.  The sequence type must be ``"standard"``,
    ``"increment"`` or ``"decrement"``.

    This allows general input configuration to be set.
ioport:token_to_input_type(string)
    Returns the input type and player number for the specified input type token
    string.
ioport:input_type_to_token(type, [player])
    Returns the token string for the specified input type and player number.  If
    the player number is not supplied, it assumed to be zero.

Properties
^^^^^^^^^^

ioport.types[] (read-only)
    Gets the supported :ref:`input types <luareference-input-inputtype>`.  Keys
    are arbitrary indices.  All supported operations have O(1) complexity.
ioport.ports[]
    Gets the emulated :ref:`I/O ports <luareference-input-ioport>` in the
    system.  Keys are absolute tags.  The ``at`` and ``index_of`` methods have
    O(n) complexity; all other supported operations have O(1) complexity.

.. _luareference-input-natkbd:

Natural keyboard manager
~~~~~~~~~~~~~~~~~~~~~~~~

Wraps MAME’s ``natural_keyboard`` class, which manages emulated keyboard and
keypad inputs.

Instantiation
^^^^^^^^^^^^^

manager.machine.natkeyboard
    Gets the global natural keyboard manager instance for the emulated machine.

Methods
^^^^^^^

natkeyboard:post(text)
    Post literal text to the emulated machine.  The machine must have keyboard
    inputs with character bindings, and the correct keyboard input device must
    be enabled.
natkeyboard:post_coded(text)
    Post text to the emulated machine.  Brace-enclosed codes are interpreted in
    the text.  The machine must have keyboard inputs with character bindings,
    and the correct keyboard input device must be enabled.

    The recognised codes are ``{BACKSPACE}``, ``{BS}``, ``{BKSP}``, ``{DEL}``,
    ``{DELETE}``, ``{END}``, ``{ENTER}``, ``{ESC}``, ``{HOME}``, ``{INS}``,
    ``{INSERT}``, ``{PGDN}``, ``{PGUP}``, ``{SPACE}``, ``{TAB}``, ``{F1}``,
    ``{F2}``, ``{F3}``, ``{F4}``, ``{F5}``, ``{F6}``, ``{F7}``, ``{F8}``,
    ``{F9}``, ``{F10}``, ``{F11}``, ``{F12}``, and ``{QUOTE}``.
natkeyboard:paste()
    Post the contents of the host clipboard to the emulated machine.  The
    machine must have keyboard inputs with character bindings, and the correct
    keyboard input device must be enabled.
natkeyboard:dump()
    Returns a string with a human-readable description of the keyboard and
    keypad input devices in the system, whether they are enabled, and their
    character bindings.

Properties
^^^^^^^^^^

natkeyboard.empty (read-only)
    A Boolean indicating whether the natural keyboard manager’s input buffer is
    empty.
natkeyboard.full (read-only)
    A Boolean indicating whether the natural keyboard manager’s input buffer is
    full.
natkeyboard.can_post (read-only)
    A Boolean indicating whether the emulated system supports posting character
    data via the natural keyboard manager.
natkeyboard.is_posting (read-only)
    A Boolean indicating whether posted character data is currently being
    delivered to the emulated system.
natkeyboard.in_use (read/write)
    A Boolean indicating whether “natural keyboard” mode is enabled.  When
    “natural keyboard” mode is enabled, the natural keyboard manager translates
    host character input to emulated system keystrokes.
natkeyboard.keyboards[]
    Gets the :ref:`keyboard/keypad input devices <luareference-input-kbddev>` in
    the emulated system, indexed by absolute device tag.  Index get has O(n)
    complexity; all other supported operations have O(1) complexity.

.. _luareference-input-kbddev:

Keyboard input device
~~~~~~~~~~~~~~~~~~~~~

Represents a keyboard or keypad input device managed by the
:ref:`natural keyboard manager <luareference-input-natkbd>`.

Instantiation
^^^^^^^^^^^^^

manager.machine.natkeyboard.keyboards[tag]
    Gets the keyboard input device with the specified tag, or ``nil`` if the tag
    does not correspond to a keyboard input device.

Properties
^^^^^^^^^^

keyboard.device (read-only)
    The underlying device.
keyboard.tag (read-only)
    The absolute tag of the underlying device.
keyboard.basetag (read-only)
    The last component of the tag of the underlying device, or ``"root"`` for
    the root machine device.
keyboard.name (read-only)
    The human-readable description of the underlying device type.
keyboard.shortname (read-only)
    The identifier for the underlying device type.
keyboard.is_keypad (read-only)
    A Boolean indicating whether the underlying device has keypad inputs but no
    keyboard inputs.  This is used when determining which keyboard input devices
    should be enabled by default.
keyboard.enabled (read/write)
    A Boolean indicating whether the device’s keyboard and/or keypad inputs are
    enabled.

.. _luareference-input-ioport:

I/O port
~~~~~~~~

Wraps MAME’s ``ioport_port`` class, representing an emulated I/O port.

Instantiation
^^^^^^^^^^^^^

manager.machine.ioport.ports[tag]
    Gets an emulated I/O port by absolute tag, or ``nil`` if the tag does not
    correspond to an I/O port.
manager.machine.devices[devtag]:ioport(porttag)
    Gets an emulated I/O port by tag relative to a device, or ``nil`` if no such
    I/O port exists.

Methods
^^^^^^^

port:read()
    Read the current input value.  Returns a 32-bit integer.
port:write(value, mask)
    Write to the I/O port output fields that are set in the specified mask.  The
    value and mask must be 32-bit integers.  Note that this does not set values
    for input fields.
port:field(mask)
    Get the first :ref:`I/O port field <luareference-input-field>` corresponding
    to the bits that are set in the specified mask, or ``nil`` if there is no
    corresponding field.

Properties
^^^^^^^^^^

port.device (read-only)
    The device that owns the I/O port.
port.tag (read-only)
    The absolute tag of the I/O port
port.active (read-only)
    A mask indicating which bits of the I/O port correspond to active fields
    (i.e. not unused or unassigned bits).
port.live (read-only)
    The live state of the I/O port.
port.fields[] (read-only)
    Gets a table of :ref:`fields <luareference-input-field>` indexed by name.

.. _luareference-input-field:

I/O port field
~~~~~~~~~~~~~~

Wraps MAME’s ``ioport_field`` class, representing a field within an I/O port.

Instantiation
^^^^^^^^^^^^^

manager.machine.ioport.ports[tag]:field(mask)
    Gets a field for the given port by bit mask.
manager.machine.ioport.ports[tag].fields[name]
    Gets a field for the given port by display name.

Methods
^^^^^^^

field:set_value(value)
    Set the value of the I/O port field.  For digital fields, the value is
    compared to zero to determine whether the field should be active; for
    analog fields, the value must be right-aligned and in the correct range.
field:clear_value()
    Clear programmatically overridden value and restore the field’s regular
    behaviour.
field:set_input_seq(seqtype, seq)
    Set the :ref:`input sequence <luareference-input-iptseq>` for the
    specified sequence type.  This is used to configure per-machine input
    settings.  The sequence type must be ``"standard"``, ``"increment"`` or
    ``"decrement"``.
field:input_seq(seq_type)
    Get the configured :ref:`input sequence <luareference-input-iptseq>` for the
    specified sequence type.  This gets per-machine input assignments.  The
    sequence type must be ``"standard"``, ``"increment"`` or ``"decrement"``.
field:set_default_input_seq(seq_type, seq)
    Set the default :ref:`input sequence <luareference-input-iptseq>` for the
    specified sequence type.  This overrides the default input assignment for a
    specific input.  The sequence type must be ``"standard"``, ``"increment"``
    or ``"decrement"``.
field:default_input_seq(seq_type)
    Gets the default :ref:`input sequence <luareference-input-iptseq>` for the
    specified sequence type.  If the default assignment is not overridden, this
    gets the general input assignment.  The sequence type must be
    ``"standard"``, ``"increment"`` or ``"decrement"``.
field:keyboard_codes(shift)
    Gets a table of characters corresponding to the field for the specified
    shift state.  The shift state is a bit mask of active shift keys.

Properties
^^^^^^^^^^

field.device (read-only)
    The device that owns the port that the field belongs to.
field.port (read-only)
    The :ref:`I/O port <luareference-input-ioport>` that the field belongs to.
field.live (read-only)
    The :ref:`live state <luareference-input-fieldlive>` of the field.
field.type (read-only)
    The input type of the field.  This is an enumerated value.
field.name (read-only)
    The display name for the field.
field.default_name (read-only)
    The name for the field from the emulated system’s configuration (cannot be
    overridden by scripts or plugins).
field.player (read-only)
    Zero-based player number for the field.
field.mask (read-only)
    Bits in the I/O port corresponding to this field.
field.defvalue (read-only)
    The field’s default value.
field.minvalue (read-only)
    The minimum allowed value for analog fields, or ``nil`` for digital fields.
field.maxvalue (read-only)
    The maximum allowed value for analog fields, or ``nil`` for digital fields.
field.sensitivity (read-only)
    The sensitivity or gain for analog fields, or ``nil`` for digital fields.
field.way (read-only)
    The number of directions allowed by the restrictor plate/gate for a digital
    joystick, or zero (0) for other inputs.
field.type_class (read-only)
    The type class for the input field – one of ``"keyboard"``,
    ``"controller"``, ``"config"``, ``"dipswitch"`` or ``"misc"``.
field.is_analog (read-only)
    A Boolean indicating whether the field is an analog axis or positional
    control.
field.is_digital_joystick (read-only)
    A Boolean indicating whether the field corresponds to a digital joystick
    switch.
field.enabled (read-only)
    A Boolean indicating whether the field is enabled.
field.optional (read-only)
    A Boolean indicating whether the field is optional and not required to use
    the emulated system.
field.cocktail (read-only)
    A Boolean indicating whether the field is only used when the system is
    configured for a cocktail table cabinet.
field.toggle (read-only)
    A Boolean indicating whether the field corresponds to a hardware toggle
    switch or push-on, push-off button.
field.rotated (read-only)
    A Boolean indicating whether the field corresponds to a control that is
    rotated relative its standard orientation.
field.analog_reverse (read-only)
    A Boolean indicating whether the field corresponds to an analog control that
    increases in the opposite direction to the convention (e.g. larger values
    when a pedal is released or a joystick is moved to the left).
field.analog_reset (read-only)
    A Boolean indicating whether the field corresponds to an incremental
    position input (e.g. a dial or trackball axis) that should be reset to zero
    for every video frame.
field.analog_wraps (read-only)
    A Boolean indicating whether the field corresponds to an analog input that
    wraps from one end of its range to the other (e.g. an incremental position
    input like a dial or trackball axis).
field.analog_invert (read-only)
    A Boolean indicating whether the field corresponds to an analog input that
    has its value ones-complemented.
field.impulse (read-only)
    A Boolean indicating whether the field corresponds to a digital input that
    activates for a fixed amount of time.
field.crosshair_scale (read-only)
    The scale factor for translating the field’s range to crosshair position.  A
    value of one (1) translates the field’s full range to the full width or
    height the screen.
field.crosshair_offset (read-only)
    The offset for translating the field’s range to crosshair position.
field.user_value (read/write)
    The value for DIP switch or configuration settings.
field.settings[] (read-only)
    Gets a table of the currently enabled settings for a DIP switch or
    configuration field, indexed by value.

.. _luareference-input-fieldlive:

Live I/O port field state
~~~~~~~~~~~~~~~~~~~~~~~~~

Wraps MAME’s ``ioport_field_live`` class, representing the live state of an I/O
port field.

Instantiation
^^^^^^^^^^^^^

manager.machine.ioport.ports[tag]:field(mask).live
    Gets the live state for an I/O port field.

Properties
^^^^^^^^^^

live.name
    Display name for the field.

.. _luareference-input-inputtype:

Input type
~~~~~~~~~~

Wraps MAME’s ``input_type_entry`` class, representing an emulated input type or
emulator UI input type.  Input types are uniquely identified by the combination
of their enumerated type value and player index.

Instantiation
^^^^^^^^^^^^^

manager.machine.ioport.types[index]
    Gets a supported input type.

Properties
^^^^^^^^^^

type.type (read-only)
    An enumerated value representing the type of input.
type.group (read-only)
    An integer giving the grouping for the input type.  Should be used to
    provide canonical grouping in an input configuration UI.
type.player (read-only)
    The zero-based player number, or zero for non-player controls.
type.token (read-only)
    The token string for the input type, used in configuration files.
type.name (read-only)
    The display name for the input type.
type.is_analog (read-only)
    A Boolean indicating whether the input type is analog or digital.  Inputs
    that only have on and off states are considered digital, while all other
    inputs are considered analog, even if they can only represent discrete
    values or positions.

.. _luareference-input-inputman:

Input manager
~~~~~~~~~~~~~

Wraps MAME’s ``input_manager`` class, which reads host input devices and checks
whether configured inputs are active.

Instantiation
^^^^^^^^^^^^^

manager.machine.input
    Gets the global input manager instance for the emulated system.

Methods
^^^^^^^

input:code_value(code)
    Gets the current value for the host input corresponding to the specified
    code.  Returns a signed integer value, where zero is the neutral position.
input:code_pressed(code)
    Returns a Boolean indicating whether the host input corresponding to the
    specified code has a non-zero value (i.e. it is not in the neutral
    position).
input:code_pressed_once(code)
    Returns a Boolean indicating whether the host input corresponding to the
    specified code has moved away from the neutral position since the last time
    it was checked using this function.  The input manager can track a limited
    number of inputs this way.
input:code_name(code)
    Get display name for an input code.
input:code_to_token(code)
    Get token string for an input code.  This should be used when saving
    configuration.
input:code_from_token(token)
    Convert a token string to an input code.  Returns the invalid input code if
    the token is not valid or belongs to an input device that is not present.
input:seq_pressed(seq)
    Returns a Boolean indicating whether the supplied
    :ref:`input sequence <luareference-input-iptseq>` is currently pressed.
input:seq_clean(seq)
    Remove invalid elements from the supplied
    :ref:`input sequence <luareference-input-iptseq>`.  Returns the new, cleaned
    input sequence.
input:seq_name(seq)
    Get display text for an :ref:`input sequence <luareference-input-iptseq>`.
input:seq_to_tokens(seq)
    Convert an :ref:`input sequence <luareference-input-iptseq>` to a token
    string.  This should be used when saving configuration.
input:seq_from_tokens(tokens)
    Convert a token string to an
    :ref:`input sequence <luareference-input-iptseq>`.  This should be used when
    loading configuration.
input:axis_code_poller()
    Returns an :ref:`input code poller <luareference-input-codepoll>` for
    obtaining an analog host input code.
input:switch_code_poller()
    Returns an :ref:`input code poller <luareference-input-codepoll>` for
    obtaining a host switch input code.
input:keyboard_code_poller()
    Returns an :ref:`input code poller <luareference-input-codepoll>` for
    obtaining a host switch input code that only considers keyboard input
    devices.
input:axis_sequence_poller()
    Returns an :ref:`input sequence poller <luareference-input-seqpoll>` for
    obtaining an :ref:`input sequence <luareference-input-iptseq>` for
    configuring an analog input.
input:axis_sequence_poller()
    Returns an :ref:`input sequence poller <luareference-input-seqpoll>` for
    obtaining an :ref:`input sequence <luareference-input-iptseq>` for
    configuring a digital input.

Properties
^^^^^^^^^^

input.device_classes[] (read-only)
    Gets a table of host
    :ref:`input device classes <luareference-input-devclass>` indexed by name.

.. _luareference-input-codepoll:

Input code poller
~~~~~~~~~~~~~~~~~

Wraps MAME’s ``input_code_poller`` class, used to poll for host inputs being
activated.

Instantiation
^^^^^^^^^^^^^

manager.machine.input:axis_code_poller()
    Returns an input code poller that polls for analog inputs being activated.
manager.machine.input:switch_code_poller()
    Returns an input code poller that polls for host switch inputs being
    activated.
manager.machine.input:keyboard_code_poller()
    Returns an input code poller that polls for host switch inputs being
    activated, only considering keyboard input devices.

Methods
^^^^^^^

poller:reset()
    Resets the polling logic.  Active switch inputs are cleared and initial
    analog input positions are set.
poller:poll()
    Returns an input code corresponding to the first relevant host input that
    has been activated since the last time the method was called.  Returns the
    invalid input code if no relevant input has been activated.

.. _luareference-input-seqpoll:

Input sequence poller
~~~~~~~~~~~~~~~~~~~~~

Wraps MAME’s ``input_sequence_poller`` poller class, which allows users to
assign host input combinations to emulated inputs and other actions.

Instantiation
^^^^^^^^^^^^^

manager.machine.input:axis_sequence_poller()
    Returns an input sequence poller for assigning host inputs to an analog
    input.
manager.machine.input:switch_sequence_poller()
    Returns an input sequence poller for assigning host inputs to a switch
    input.

Methods
^^^^^^^

poller:start([seq])
    Start polling.  If a sequence is supplied, it is used as a starting
    sequence: for analog inputs, the user can cycle between the full range, and
    the positive and negative portions of an axis; for switch inputs, an “or”
    code is appended and the user can add an alternate host input combination.
poller:poll()
    Polls for for user input and updates the sequence if appropriate.  Returns a
    Boolean indicating whether sequence input is complete.  If this method
    returns false, you should continue polling.

Properties
^^^^^^^^^^

poller.sequence (read-only)
    The current :ref:`input sequence <luareference-input-iptseq>`.  This is
    updated while polling.  It is possible for the sequence to become invalid.
poller.valid (read-only)
    A Boolean indicating whether the current input sequence is valid.
poller.modified (read-only)
    A Boolean indicating whether the sequence was changed by any user input
    since starting polling.

.. _luareference-input-iptseq:

Input sequence
~~~~~~~~~~~~~~

Wraps MAME’s ``input_seq`` class, representing a combination of host inputs that
can be read or assigned to an emulated input.  Input sequences can be
manipulated using :ref:`input manager <luareference-input-inputman>` methods.
Use an :ref:`input sequence poller <luareference-input-seqpoll>` to obtain an
input sequence from the user.

Instantiation
^^^^^^^^^^^^^

emu.input_seq()
    Creates an empty input sequence.
emu.input_seq(seq)
    Creates a copy of an existing input sequence.

Methods
^^^^^^^

seq:reset()
    Clears the input sequence, removing all items.
seq:set_default()
    Sets the input sequence to a single item containing the metavalue specifying
    that the default setting should be used.

Properties
^^^^^^^^^^

seq.empty (read-only)
    A Boolean indicating whether the input sequence is empty (contains no items,
    indicating an unassigned input).
seq.length (read-only)
    The number of items in the input sequence.
seq.is_valid (read-only)
    A Boolean indicating whether the input sequence is a valid.  To be valid, it
    must contain at least one item, all items must be valid codes, all product
    groups must contain at least one item that is not negated, and items
    referring to absolute and relative axes must not be mixed within a product
    group.
seq.is_default (read-only)
    A Boolean indicating whether the input sequence specifies that the default
    setting should be used.

.. _luareference-input-devclass:

Host input device class
~~~~~~~~~~~~~~~~~~~~~~~

Wraps MAME’s ``input_class`` class, representing a category of host input
devices (e.g. keyboards or joysticks).

Instantiation
^^^^^^^^^^^^^

manager.machine.input.device_classes[name]
    Gets an input device class by name.

Properties
^^^^^^^^^^

devclass.name (read-only)
    The device class name.
devclass.enabled (read-only)
    A Boolean indicating whether the device class is enabled.
devclass.multi (read-only)
    A Boolean indicating whether the device class supports multiple devices, or
    inputs from all devices in the class are combined and treated as a single
    device.
devclass.devices[] (read-only)
    Gets a table of :ref:`host input devices <luareference-input-inputdev>` in
    the class.  Keys are one-based indices.

.. _luareference-input-inputdev:

Host input device
~~~~~~~~~~~~~~~~~

Wraps MAME’s ``input_device`` class, representing a host input device.

Instantiation
^^^^^^^^^^^^^

manager.machine.input.device_classes[name].devices[index]
    Gets a specific host input device.

Properties
^^^^^^^^^^

inputdev.name (read-only)
    Display name for the device.  This is not guaranteed to be unique.
inputdev.id (read-only)
    Unique identifier string for the device.  This may not be human-readable.
inputdev.devindex (read-only)
    Device index within the device class.  This is not necessarily the same as
    the index in the ``devices`` property of the device class – the ``devindex``
    indices may not be contiguous.
inputdev.items (read-only)
    Gets a table of :ref:`input items <luareference-input-inputitem>`, indexed
    by item ID.  The item ID is an enumerated value.

.. _luareference-input-inputitem:

Host input device item
~~~~~~~~~~~~~~~~~~~~~~

Wraps MAME’s ``input_device_item`` class, representing a single host input (e.g.
a key, button, or axis).

Instantiation
^^^^^^^^^^^^^

manager.machine.input.device_classes[name].devices[index].items[id]
    Gets an individual host input item.  The item ID is an enumerated value.

Properties
^^^^^^^^^^

item.name (read-only)
    The display name of the input item.  Note that this is just the name of the
    item itself, and does not include the device name.  The full display name
    for the item can be obtained by calling the ``code_name`` method on the
    :ref:`input manager <luareference-input-inputman>` with the item’s code.
item.code (read-only)
    The input item’s identification code.  This is used by several
    :ref:`input manager <luareference-input-inputman>` methods.
item.token (read-only)
    The input item’s token string.  Note that this is a token fragment for the
    item itself, and does not include the device portion.  The full token for
    the item can be obtained by calling the ``code_to_token`` method on the
    :ref:`input manager <luareference-input-inputman>` with the item’s code.
item.current (read-only)
    The item’s current value.  This is a signed integer where zero is the
    neutral position.

.. _luareference-input-uiinput:

UI input manager
~~~~~~~~~~~~~~~~

Wraps MAME’s ``ui_input_manager`` class, which is used for high-level input.

Instantiation
^^^^^^^^^^^^^

manager.machine.uiinput
    Gets the global UI input manager instance for the machine.

Methods
^^^^^^^

uiinput:reset()
    Clears pending events and UI input states.  Should be called when leaving a
    modal state where input is handled directly (e.g. configuring an input
    combination).
uiinput:find_mouse()
    Returns host system mouse pointer X position, Y position, button state, and
    the :ref:`render target <luareference-render-target>` it falls in.  The
    position is in host pixels, where zero is at the top/left.  The button state
    is a Boolean indicating whether the primary mouse button is pressed.

    If the mouse pointer is not over one of MAME’s windows, this may return the
    position and render target from when the mouse pointer was most recently
    over one of MAME’s windows.  The render target may be ``nil`` if the mouse
    pointer is not over one of MAME’s windows.
uiinput:pressed(type)
    Returns a Boolean indicating whether the specified UI input has been
    pressed.  The input type is an enumerated value.
uiinput:pressed_repeat(type, speed)
    Returns a Boolean indicating whether the specified UI input has been
    pressed or auto-repeat has been triggered at the specified speed.  The input
    type is an enumerated value; the speed is an interval in sixtieths of a
    second.

Properties
^^^^^^^^^^

uiinput.presses_enabled (read/write)
    Whether the UI input manager will check for UI inputs frame updates.


.. _luareference-render:

Render system
-------------

The render system is responsible for drawing what you see in MAME’s windows,
including emulated screens, artwork, and UI elements.

.. _luareference-render-bounds:

Render bounds
~~~~~~~~~~~~~

Wraps MAME’s ``render_bounds`` class, which represents a rectangle using
floating-point coordinates.

Instantiation
^^^^^^^^^^^^^

emu.render_bounds()
    Creates a render bounds object representing a unit square, with top left
    corner at (0, 0) and bottom right corner at (1, 1).  Note that render
    target coordinates don’t necessarily have equal X and Y scales, so this may
    not represent a square in the final output.
emu.render_bounds(left, top, right, bottom)
    Creates a render bounds object representing a rectangle with top left
    corner at (x0, y0) and bottom right corner at (x1, y1).

    The arguments must all be floating-point numbers.

Methods
^^^^^^^

bounds:includes(x, y)
    Returns a Boolean indicating whether the specified point falls within the
    rectangle.  The rectangle must be normalised for this to work (right greater
    than left and bottom greater than top).

    The arguments must both be floating-point numbers.
bounds:set_xy(left, top, right, bottom)
    Set the rectangle’s position and size in terms of the positions of the
    edges.

    The arguments must all be floating-point numbers.
bounds:set_wh(left, top, width, height)
    Set the rectangle’s position and size in terms of the top top left corner
    position, and the width and height.

    The arguments must all be floating-point numbers.

Properties
^^^^^^^^^^

bounds.x0 (read/write)
    The leftmost coordinate in the rectangle (i.e. the X coordinate of the left
    edge or the top left corner).
bounds.x1 (read/write)
    The rightmost coordinate in the rectangle (i.e. the X coordinate of the
    right edge or the bottom right corner).
bounds.y0 (read/write)
    The topmost coordinate in the rectangle (i.e. the Y coordinate of the top
    edge or the top left corner).
bounds.y1 (read/write)
    The bottommost coordinate in the rectangle (i.e. the Y coordinate of the
    bottom edge or the bottom right corner).
bounds.width (read/write)
    The width of the rectangle.  Setting this property changes the position of
    the rightmost edge.
bounds.height (read/write)
    The height of the rectangle.  Setting this property changes the position of
    the bottommost edge.
bounds.aspect (read-only)
    The width-to-height aspect ratio of the rectangle.  Note that this is often
    in render target coordinates which don’t necessarily have equal X and Y
    scales.  A rectangle representing a square in the final output doesn’t
    necessarily have an aspect ratio of 1.

.. _luareference-render-color:

Render colour
~~~~~~~~~~~~~

Wraps MAME’s ``render_color`` class, which represents an ARGB (alpha, red,
green, blue) format colour.  Channels are floating-point values ranging from
zero (0, transparent alpha or colour off) to one (1, opaque or full colour
intensity).  Colour channel values are not pre-multiplied by the alpha channel
value.

Instantiation
^^^^^^^^^^^^^

emu.render_color()
    Creates a render colour object representing opaque white (all channels set
    to 1).  This is the identity value – ARGB multiplication by this value will
    not change a colour.
emu.render_color(a, r, g, b)
    Creates a render colour object with the specified alpha, red, green and
    blue channel values.

    The arguments must all be floating-point numbers in the range from zero (0)
    to one (1), inclusive.

Methods
^^^^^^^

color:set(a, r, g, b)
    Sets the colour object’s alpha, red, green and blue channel values.

    The arguments must all be floating-point numbers in the range from zero (0)
    to one (1), inclusive.

Properties
^^^^^^^^^^

color.a (read/write)
    Alpha value, in the range of zero (0, transparent) to one (1, opaque).
color.r (read/write)
    Red channel value, in the range of zero (0, off) to one (1, full intensity).
color.g (read/write)
    Green channel value, in the range of zero (0, off) to one (1, full
    intensity).
color.b (read/write)
    Blue channel value, in the range of zero (0, off) to one (1, full
    intensity).

.. _luareference-render-palette:

Palette
~~~~~~~

Wraps MAME’s ``palette_t`` class, which represents a table of colours that can
be looked up by zero-based index.  Palettes always contain additional special
entries for black and white.

Each colour has an associated contrast adjustment value.  Each adjustment group
has associated brightness and contrast adjustment values.  The palette also has
overall brightness, contrast and gamma adjustment values.

Colours are represented in alpha/red/green/blue (ARGB) format.  Channel values
range from 0 (transparent or off) to 255 (opaque or full intensity), inclusive.
Colour channel values are not pre-multiplied by the alpha value.  Channel values
are packed into the bytes of 32-bit unsigned integers, in the order alpha, red,
green, blue from most-significant to least-significant byte.

Instantiation
^^^^^^^^^^^^^

emu.palette(colors, [groups])
    Creates a palette with the specified number of colours and
    brightness/contrast adjustment groups.  The number of colour groups defaults
    to one if not specified.  Colours are initialised to black, brightness
    adjustment is initialised to 0.0, contrast adjustment initialised to 1.0,
    and gamma adjustment is initialised to 1.0.

Methods
^^^^^^^

palette:entry_color(index)
    Gets the colour at the specified zero-based index.

    Index values range from zero to the number of colours in the palette minus
    one.  Returns black if the index is greater than or equal to the number of
    colours in the palette.
palette:entry_contrast(index)
    Gets the contrast adjustment for the colour at the specified zero-based
    index.  This is a floating-point number.

    Index values range from zero to the number of colours in the palette minus
    one.  Returns 1.0 if the index is greater than or equal to the number of
    colours in the palette.
palette:entry_adjusted_color(index, [group])
    Gets a colour with brightness, contrast and gamma adjustments applied.

    If the group is specified, colour index values range from zero to the number
    of colours in the palette minus one, and group values range from zero to the
    number of adjustment groups in the palette minus one.

    If the group is not specified, index values range from zero to the number of
    colours multiplied by the number of adjustment groups plus one.  Index
    values may be calculated by multiplying the zero-based group index by the
    number of colours in the palette, and adding the zero-based colour index.
    The last two index values correspond to the special entries for black and
    white, respectively.

    Returns black if the specified combination of index and adjustment group is
    invalid.
palette:entry_set_color(index, color)
    Sets the colour at the specified zero-based index.  The colour may be
    specified as a single packed 32-bit value; or as individual red, green and
    blue channel values, in that order.

    Index values range from zero to the number of colours in the palette minus
    one.  Raises an error if the index value is invalid.
palette:entry_set_red_level(index, level)
    Sets the red channel value of the colour at the specified zero-based index.
    Other channel values are not affected.

    Index values range from zero to the number of colours in the palette minus
    one.  Raises an error if the index value is invalid.
palette:entry_set_green_level(index, level)
    Sets the green channel value of the colour at the specified zero-based
    index.  Other channel values are not affected.

    Index values range from zero to the number of colours in the palette minus
    one.  Raises an error if the index value is invalid.
palette:entry_set_blue_level(index, level)
    Sets the blue channel value of the colour at the specified zero-based index.
    Other channel values are not affected.

    Index values range from zero to the number of colours in the palette minus
    one.  Raises an error if the index value is invalid.
palette:entry_set_contrast(index, level)
    Sets the contrast adjustment value for the colour at the specified
    zero-based index.  This must be a floating-point number.

    Index values range from zero to the number of colours in the palette minus
    one.  Raises an error if the index value is invalid.
palette:group_set_brightness(group, brightness)
    Sets the brightness adjustment value for the adjustment group at the
    specified zero-based index.  This must be a floating-point number.

    Group values range from zero to the number of adjustment groups in the
    palette minus one.  Raises an error if the index value is invalid.
palette:group_set_contrast(group, contrast)
    Sets the contrast adjustment value for the adjustment group at the specified
    zero-based index.  This must be a floating-point number.

    Group values range from zero to the number of adjustment groups in the
    palette minus one.  Raises an error if the index value is invalid.

Properties
^^^^^^^^^^

palette.colors (read-only)
    The number of colour entries in each group of colours in the palette.
palette.groups (read-only)
    The number of groups of colours in the palette.
palette.max_index (read-only)
    The number of valid colour indices in the palette.
palette.black_entry (read-only)
    The index of the special entry for the colour black.
palette.white_entry (read-only)
    The index of the special entry for the colour white.
palette.brightness (write-only)
    The overall brightness adjustment for the palette.  This is a floating-point
    number.
palette.contrast (write-only)
    The overall contrast adjustment for the palette.  This is a floating-point
    number.
palette.gamma (write-only)
    The overall gamma adjustment for the palette.  This is a floating-point
    number.

.. _luareference-render-bitmap:

Bitmap
~~~~~~

Wraps implementations of MAME’s ``bitmap_t`` and ``bitmap_specific`` classes,
which represent two-dimensional bitmaps stored in row-major order.  Pixel
coordinates are zero-based, increasing to the right and down.  Several pixel
formats are supported.

Instantiation
^^^^^^^^^^^^^

emu.bitmap_ind8(palette, [width, height], [xslop, yslop])
    Creates an 8-bit indexed bitmap.  Each pixel is a zero-based, unsigned 8-bit
    index into a :ref:`palette <luareference-render-palette>`.

    If no width and height are specified, they are assumed to be zero.  If the
    width is specified, the height must also be specified.  The X and Y slop
    values set the amount of extra storage in pixels to reserve at the
    left/right of each row and top/bottom of each column, respectively.  If an X
    slop value is specified, a Y slop value must be specified as well.  If no X
    and Y slop values are specified, they are assumed to be zero (the storage
    will be sized to fit the bitmap content).  If the width and/or height is
    less than or equal to zero, no storage will be allocated, irrespective of
    the X and Y slop values, and the width and height of the bitmap will both be
    set to zero.

    The initial clipping rectangle is set to the entirety of the bitmap.
emu.bitmap_ind16(palette, [width, height], [xslop, yslop])
    Creates a 16-bit indexed bitmap.  Each pixel is a zero-based, unsigned
    16-bit index into a :ref:`palette <luareference-render-palette>`.

    If no width and height are specified, they are assumed to be zero.  If the
    width is specified, the height must also be specified.  The X and Y slop
    values set the amount of extra storage in pixels to reserve at the
    left/right of each row and top/bottom of each column, respectively.  If an X
    slop value is specified, a Y slop value must be specified as well.  If no X
    and Y slop values are specified, they are assumed to be zero (the storage
    will be sized to fit the bitmap content).  If the width and/or height is
    less than or equal to zero, no storage will be allocated, irrespective of
    the X and Y slop values, and the width and height of the bitmap will both be
    set to zero.

    The initial clipping rectangle is set to the entirety of the bitmap.
emu.bitmap_ind32(palette, [width, height], [xslop, yslop])
    Creates a 32-bit indexed bitmap.  Each pixel is a zero-based, unsigned
    32-bit index into a :ref:`palette <luareference-render-palette>`.

    If no width and height are specified, they are assumed to be zero.  If the
    width is specified, the height must also be specified.  The X and Y slop
    values set the amount of extra storage in pixels to reserve at the
    left/right of each row and top/bottom of each column, respectively.  If an X
    slop value is specified, a Y slop value must be specified as well.  If no X
    and Y slop values are specified, they are assumed to be zero (the storage
    will be sized to fit the bitmap content).  If the width and/or height is
    less than or equal to zero, no storage will be allocated, irrespective of
    the X and Y slop values, and the width and height of the bitmap will both be
    set to zero.

    The initial clipping rectangle is set to the entirety of the bitmap.
emu.bitmap_ind64(palette, [width, height], [xslop, yslop])
    Creates a 64-bit indexed bitmap.  Each pixel is a zero-based, unsigned
    64-bit index into a :ref:`palette <luareference-render-palette>`.

    If no width and height are specified, they are assumed to be zero.  If the
    width is specified, the height must also be specified.  The X and Y slop
    values set the amount of extra storage in pixels to reserve at the
    left/right of each row and top/bottom of each column, respectively.  If an X
    slop value is specified, a Y slop value must be specified as well.  If no X
    and Y slop values are specified, they are assumed to be zero (the storage
    will be sized to fit the bitmap content).  If the width and/or height is
    less than or equal to zero, no storage will be allocated, irrespective of
    the X and Y slop values, and the width and height of the bitmap will both be
    set to zero.

    The initial clipping rectangle is set to the entirety of the bitmap.
emu.bitmap_yuy16([width, height], [xslop], yslop])
    Creates a Y'CbCr format bitmap with 4:2:2 chroma subsampling (horizontal
    pairs of pixels have individual luma values but share chroma values).  Each
    pixel is a 16-bit integer value.  The most significant byte of the pixel
    value is the unsigned 8-bit Y' (luma) component of the pixel colour.  For
    each horizontal pair of pixels, the least significant byte of the first
    pixel (even zero-based X coordinate) value is the signed 8-bit Cb value for
    the pair of pixels, and the least significant byte of the second pixel (odd
    zero-based X coordinate) value is the signed 8-bit Cr value for the pair of
    pixels.

    If no width and height are specified, they are assumed to be zero.  If the
    width is specified, the height must also be specified.  The X and Y slop
    values set the amount of extra storage in pixels to reserve at the
    left/right of each row and top/bottom of each column, respectively.  If an X
    slop value is specified, a Y slop value must be specified as well.  If no X
    and Y slop values are specified, they are assumed to be zero (the storage
    will be sized to fit the bitmap content).  If the width and/or height is
    less than or equal to zero, no storage will be allocated, irrespective of
    the X and Y slop values, and the width and height of the bitmap will both be
    set to zero.

    The initial clipping rectangle is set to the entirety of the bitmap.
emu.bitmap_rgb32([width, height], [xslop, yslop])
    Creates an RGB format bitmap with no alpha (transparency) channel.  Each
    pixel is represented by a 32-bit integer value.  The most significant byte
    of the pixel value is ignored.  The remaining three bytes, from most
    significant to least significant, are the unsigned 8-bit unsigned red, green
    and blue channel values (larger values correspond to higher intensities).

    If no width and height are specified, they are assumed to be zero.  If the
    width is specified, the height must also be specified.  The X and Y slop
    values set the amount of extra storage in pixels to reserve at the
    left/right of each row and top/bottom of each column, respectively.  If an X
    slop value is specified, a Y slop value must be specified as well.  If no X
    and Y slop values are specified, they are assumed to be zero (the storage
    will be sized to fit the bitmap content).  If the width and/or height is
    less than or equal to zero, no storage will be allocated, irrespective of
    the X and Y slop values, and the width and height of the bitmap will both be
    set to zero.

    The initial clipping rectangle is set to the entirety of the bitmap.
emu.bitmap_argb32([width, height], [xslop, yslop])
    Creates an ARGB format bitmap.  Each pixel is represented by a 32-bit
    integer value.  The most significant byte of the pixel is the 8-bit unsigned
    alpha (transparency) channel value (smaller values are more transparent).
    The remaining three bytes, from most significant to least significant, are
    the unsigned 8-bit unsigned red, green and blue channel values (larger
    values correspond to higher intensities).  Colour channel values are not
    pre-multiplied by the alpha channel value.

    If no width and height are specified, they are assumed to be zero.  If the
    width is specified, the height must also be specified.  The X and Y slop
    values set the amount of extra storage in pixels to reserve at the
    left/right of each row and top/bottom of each column, respectively.  If an X
    slop value is specified, a Y slop value must be specified as well.  If no X
    and Y slop values are specified, they are assumed to be zero (the storage
    will be sized to fit the bitmap content).  If the width and/or height is
    less than or equal to zero, no storage will be allocated, irrespective of
    the X and Y slop values, and the width and height of the bitmap will both be
    set to zero.

    The initial clipping rectangle is set to the entirety of the bitmap.
emu.bitmap_ind8(source, [x0, y0, x1, y1])
    Creates an 8-bit indexed bitmap representing a view of a portion of an
    existing bitmap.  The initial clipping rectangle is set to the bounds of the
    view.  The source bitmap will be locked, preventing resizing and
    reallocation.

    If no coordinates are specified, the new bitmap will represent a view of the
    source bitmap’s current clipping rectangle.  If coordinates are specified,
    the new bitmap will represent a view of the rectangle with top left corner
    at (x0, y0) and bottom right corner at (x1, y1) in the source bitmap.
    Coordinates are in units of pixels.  The bottom right coordinates are
    inclusive.

    The source bitmap must be owned by the Lua script and must use the 8-bit
    indexed format.  Raises an error if coordinates are specified representing a
    rectangle not fully contained within the source bitmap’s clipping rectangle.
emu.bitmap_ind16(source, [x0, y0, x1, y1])
    Creates a 16-bit indexed bitmap representing a view of a portion of an
    existing bitmap.  The initial clipping rectangle is set to the bounds of the
    view.  The source bitmap will be locked, preventing resizing and
    reallocation.

    If no coordinates are specified, the new bitmap will represent a view of the
    source bitmap’s current clipping rectangle.  If coordinates are specified,
    the new bitmap will represent a view of the rectangle with top left corner
    at (x0, y0) and bottom right corner at (x1, y1) in the source bitmap.
    Coordinates are in units of pixels.  The bottom right coordinates are
    inclusive.

    The source bitmap must be owned by the Lua script and must use the 16-bit
    indexed format.  Raises an error if coordinates are specified representing a
    rectangle not fully contained within the source bitmap’s clipping rectangle.
emu.bitmap_ind32(source, [x0, y0, x1, y1])
    Creates a 32-bit indexed bitmap representing a view of a portion of an
    existing bitmap.  The initial clipping rectangle is set to the bounds of the
    view.  The source bitmap will be locked, preventing resizing and
    reallocation.

    If no coordinates are specified, the new bitmap will represent a view of the
    source bitmap’s current clipping rectangle.  If coordinates are specified,
    the new bitmap will represent a view of the rectangle with top left corner
    at (x0, y0) and bottom right corner at (x1, y1) in the source bitmap.
    Coordinates are in units of pixels.  The bottom right coordinates are
    inclusive.

    The source bitmap must be owned by the Lua script and must use the 32-bit
    indexed format.  Raises an error if coordinates are specified representing a
    rectangle not fully contained within the source bitmap’s clipping rectangle.
emu.bitmap_ind64(source, [x0, y0, x1, y1])
    Creates a 64-bit indexed bitmap representing a view of a portion of an
    existing bitmap.  The initial clipping rectangle is set to the bounds of the
    view.  The source bitmap will be locked, preventing resizing and
    reallocation.

    If no coordinates are specified, the new bitmap will represent a view of the
    source bitmap’s current clipping rectangle.  If coordinates are specified,
    the new bitmap will represent a view of the rectangle with top left corner
    at (x0, y0) and bottom right corner at (x1, y1) in the source bitmap.
    Coordinates are in units of pixels.  The bottom right coordinates are
    inclusive.

    The source bitmap must be owned by the Lua script and must use the 64-bit
    indexed format.  Raises an error if coordinates are specified representing a
    rectangle not fully contained within the source bitmap’s clipping rectangle.
emu.bitmap_yuy16(source, [x0, y0, x1, y1])
    Creates a Y'CbCr format bitmap with 4:2:2 chroma subsampling representing a
    view of a portion of an existing bitmap.  The initial clipping rectangle is
    set to the bounds of the view.  The source bitmap will be locked, preventing
    resizing and reallocation.

    If no coordinates are specified, the new bitmap will represent a view of the
    source bitmap’s current clipping rectangle.  If coordinates are specified,
    the new bitmap will represent a view of the rectangle with top left corner
    at (x0, y0) and bottom right corner at (x1, y1) in the source bitmap.
    Coordinates are in units of pixels.  The bottom right coordinates are
    inclusive.

    The source bitmap must be owned by the Lua script and must use the Y'CbCr
    format.  Raises an error if coordinates are specified representing a
    rectangle not fully contained within the source bitmap’s clipping rectangle.
emu.bitmap_rgb32(source, [x0, y0, x1, y1])
    Creates an RGB format bitmap with 4:2:2 chroma subsampling representing a
    view of a portion of an existing bitmap.  The initial clipping rectangle is
    set to the bounds of the view.  The source bitmap will be locked, preventing
    resizing and reallocation.

    If no coordinates are specified, the new bitmap will represent a view of the
    source bitmap’s current clipping rectangle.  If coordinates are specified,
    the new bitmap will represent a view of the rectangle with top left corner
    at (x0, y0) and bottom right corner at (x1, y1) in the source bitmap.
    Coordinates are in units of pixels.  The bottom right coordinates are
    inclusive.

    The source bitmap must be owned by the Lua script and must use the RGB
    format.  Raises an error if coordinates are specified representing a
    rectangle not fully contained within the source bitmap’s clipping rectangle.
emu.bitmap_argb32(source, [x0, y0, x1, y1])
    Creates an ARGB format bitmap with 4:2:2 chroma subsampling representing a
    view of a portion of an existing bitmap.  The initial clipping rectangle is
    set to the bounds of the view.  The source bitmap will be locked, preventing
    resizing and reallocation.

    If no coordinates are specified, the new bitmap will represent a view of the
    source bitmap’s current clipping rectangle.  If coordinates are specified,
    the new bitmap will represent a view of the rectangle with top left corner
    at (x0, y0) and bottom right corner at (x1, y1) in the source bitmap.
    Coordinates are in units of pixels.  The bottom right coordinates are
    inclusive.

    The source bitmap must be owned by the Lua script and must use the ARGB
    format.  Raises an error if coordinates are specified representing a
    rectangle not fully contained within the source bitmap’s clipping rectangle.

Methods
^^^^^^^

bitmap:cliprect()
    Returns the left, top, right and bottom coordinates of the bitmap’s clipping
    rectangle.  Coordinates are in units of pixels; the bottom and right
    coordinates are inclusive.
bitmap:reset()
    Sets the width and height to zero, and frees the pixel storage if the bitmap
    owns its own storage, or releases the source bitmap if the it represents a
    view of another bitmap.

    The bitmap must be owned by the Lua script.  Raises an error if the bitmap’s
    storage is referenced by another bitmap or a :ref:`texture
    <luareference-render-texture>`.
bitmap:allocate(width, height, [xslop, yslop])
    Reallocates storage for the bitmap, sets its width and height, and sets the
    clipping rectangle to the entirety of the bitmap.  If the bitmap already
    owns allocated storage, it will always be freed and reallocated; if the
    bitmap represents a view of another bitmap, the source bitmap will be
    released.  The storage will be filled with pixel value zero.

    The X and Y slop values set the amount of extra storage in pixels to reserve
    at the left/right of each row and top/bottom of each column, respectively.
    If an X slop value is specified, a Y slop value must be specified as well.
    If no X and Y slop values are specified, they are assumed to be zero (the
    storage will be sized to fit the bitmap content).  If the width and/or
    height is less than or equal to zero, no storage will be allocated,
    irrespective of the X and Y slop values, and the width and height of the
    bitmap will both be set to zero.

    The bitmap must be owned by the Lua script.  Raises an error if the bitmap’s
    storage is referenced by another bitmap or a :ref:`texture
    <luareference-render-texture>`.
bitmap:resize(width, height, [xslop, yslop])
    Changes the width and height, and sets the clipping rectangle to the
    entirety of the bitmap.

    The X and Y slop values set the amount of extra storage in pixels to reserve
    at the left/right of each row and top/bottom of each column, respectively.
    If an X slop value is specified, a Y slop value must be specified as well.
    If no X and Y slop values are specified, they are assumed to be zero (rows
    will be stored contiguously, and the top row will be placed at the beginning
    of the bitmap’s storage).

    If the bitmap already owns allocated storage and it is large enough for the
    updated size, it will be used without being freed; if it is too small for
    the updated size, it will always be freed and reallocated.  If the bitmap
    represents a view of another bitmap, the source bitmap will be released.  If
    storage is allocated, it will be filled with pixel value zero (if existing
    storage is used, its contents will not be changed).

    Raises an error if the bitmap’s storage is referenced by another bitmap or a
    :ref:`texture <luareference-render-texture>`.
bitmap:wrap(source, [x0, y0, x1, y1])
    Makes the bitmap represent a view of a portion of another bitmap and sets
    the clipping rectangle to the bounds of the view.

    If no coordinates are specified, the target bitmap will represent a view of
    the source bitmap’s current clipping rectangle.  If coordinates are
    specified, the target bitmap will represent a view of the rectangle with top
    left corner at (x0, y0) and bottom right corner at (x1, y1) in the source
    bitmap.  Coordinates are in units of pixels.  The bottom right coordinates
    are inclusive.

    The source bitmap will be locked, preventing resizing and reallocation.  If
    the target bitmap owns allocated storage, it will be freed; if it represents
    a view of another bitmap, the current source bitmap will be released.

    The source and target bitmaps must both be owned by the Lua script and must
    use the same pixel format.  Raises an error if coordinates are specified
    representing a rectangle not fully contained within the source bitmap’s
    clipping rectangle; if the bitmap’s storage is referenced by another bitmap
    or a :ref:`texture <luareference-render-texture>`; or if the source and
    target are the same bitmap.
bitmap:pix(x, y)
    Returns the colour value of the pixel at the specified location.
    Coordinates are zero-based in units of pixels.
bitmap:pixels([x0, y0, x1, y1])
    Returns the pixels, width and height of the portion of the bitmap with top
    left corner at (x0, y0) and bottom right corner at (x1, y1).  Coordinates
    are in units of pixels.  The bottom right coordinates are inclusive.  If
    coordinates are not specified, the bitmap’s clipping rectangle is used.

    Pixels are returned packed into a binary string in host Endian order.
    Pixels are organised in row-major order, from left to right then top to
    bottom.  The size and format of the pixel values depends on the format of
    the bitmap.  Raises an error if coordinates are specified representing a
    rectangle not fully contained within the bitmap’s clipping rectangle.
bitmap:fill(color, [x0, y0, x1, y1])
    Fills a portion of the bitmap with the specified colour value.  If
    coordinates are not specified, the clipping rectangle is filled; if
    coordinates are specified, the intersection of the clipping rectangle and
    the rectangle with top left corner at (x0, y0) and bottom right corner at
    (x1, y1) is filled.  Coordinates are in units of pixels.  The bottom right
    coordinates are inclusive.
bitmap:plot(x, y, color)
    Sets the colour value of the pixel at the specified location if it is within
    the clipping rectangle.  Coordinates are zero-based in units of pixels.
bitmap:plot_box(x, y, width, height, color)
    Fills the intersection of the clipping rectangle and the rectangle with top
    left (x, y) and the specified height and width with the specified colour
    value.  Coordinates and dimensions are in units of pixels.

Properties
^^^^^^^^^^

bitmap.palette (read/write)
    The :ref:`palette <luareference-render-palette>` used to translate pixel
    values to colours.  Only applicable for bitmaps that use indexed pixel
    formats.
bitmap.width (read-only)
    Width of the bitmap in pixels.
bitmap.height (read-only)
    Height of the bitmap in pixels.
bitmap.rowpixels (read-only)
    Row stride of the bitmap’s storage in pixels.  That is, the difference in
    pixel offsets of the pixels at the same horizontal location in consecutive
    rows.  May be greater than the width.
bitmap.rowbytes (read-only)
    Row stride of the bitmap’s storage in bytes.  That is, the difference in
    byte addresses of the pixels at the same horizontal location in consecutive
    rows.
bitmap.bpp (read-only)
    Size of the type used to represent pixels in the bitmap in bits (may be
    larger than the number of significant bits).
bitmap.valid (read-only)
    A Boolean indicating whether the bitmap has storage available (may be false
    for empty bitmaps).
bitmap.locked (read-only)
    A Boolean indicating whether the bitmap’s storage is referenced by another
    bitmap or a :ref:`texture <luareference-render-texture>`.

.. _luareference-render-texture:

Render texture
~~~~~~~~~~~~~~

Wraps MAME’s ``render_texture`` class, representing a texture that cam be drawn
in a :ref:`render container <luareference-render-container>`.  Render textures
must be freed before the emulation session ends.

Instantiation
^^^^^^^^^^^^^

manager.machine.render:texture_alloc(bitmap)
    Creates a render texture based on a :ref:`bitmap
    <luareference-render-bitmap>`.  The bitmap must be owned by the Lua script,
    and must use the Y'CbCr, RGB or ARGB format.  The bitmap’s storage will be
    locked, preventing resizing and reallocation.

Methods
^^^^^^^

texture:free()
    Frees the texture.  The storage of the underlying bitmap will be released.

Properties
^^^^^^^^^^

texture.valid (read-only)
    A Boolean indicating whether the texture is valid (false if the texture has
    been freed).

.. _luareference-render-manager:

Render manager
~~~~~~~~~~~~~~

Wraps MAME’s ``render_manager`` class, responsible for managing render targets
and textures.

Instantiation
^^^^^^^^^^^^^

manager.machine.render
    Gets the global render manager instance for the emulation session.

Methods
^^^^^^^

render:texture_alloc(bitmap)
    Creates a :ref:`render texture <luareference-render-texture>` based on a
    :ref:`bitmap <luareference-render-bitmap>`.  The bitmap must be owned by the
    Lua script, and must use the Y'CbCr, RGB or ARGB pixel format.  The bitmap’s
    storage will be locked, preventing resizing and reallocation.  Render
    textures must be freed before the emulation session ends.

Properties
^^^^^^^^^^

render.max_update_rate (read-only)
    The maximum update rate in Hertz.  This is a floating-point number.
render.ui_target (read-only)
    The :ref:`render target <luareference-render-target>` used to draw the user
    interface (including menus, sliders and pop-up messages).  This is usually
    the first host window or screen.
render.ui_container (read-only)
    The :ref:`render container <luareference-render-container>` used for drawing
    the user interface.
render.targets[] (read-only)
    The list of render targets, including output windows and screens, as well as
    hidden render targets used for things like rendering screenshots.  Uses
    1-based integer indices.  The index operator and the ``at`` method have O(n)
    complexity.

.. _luareference-render-target:

Render target
~~~~~~~~~~~~~

Wrap’s MAME’s ``render_target`` class, which represents a video output channel.
This could be a host window or screen, or a hidden target used for rendering
screenshots.

Instantiation
^^^^^^^^^^^^^

manager.machine.render.targets[index]
    Gets a render target by index.
manager.machine.render.ui_target
    Gets the render target used to display the user interface (including menus,
    sliders and pop-up messages).  This is usually the first host window or
    screen.
manager.machine.video.snapshot_target
    Gets the render target used to produce snapshots and video recordings.

Properties
^^^^^^^^^^

target.index (read-only)
    The 1-based index of the render target.  This has O(n) complexity.
target.width (read-only)
    The width of the render target in output pixels.  This is an integer.
target.height (read-only)
    The height of the render target in output pixels.  This is an integer.
target.pixel_aspect (read-only)
    The width-to-height aspect ratio of the render target’s pixels.  This is a
    floating-point number.
target.hidden (read-only)
    A Boolean indicating whether this is an internal render target that is not
    displayed to the user directly (e.g. the render target used to draw
    screenshots).
target.is_ui_target (read-only)
    A Boolean indicating whether this is the render target used to display the
    user interface.
target.max_update_rate (read/write)
    The maximum update rate for the render target in Hertz.
target.orientation (read/write)
    The target orientation flags.  This is an integer bit mask, where bit 0
    (0x01) is set to mirror horizontally, bit 1 (0x02) is set to mirror
    vertically, and bit 2 (0x04) is set to mirror along the top left-bottom
    right diagonal.
target.view_names[]
    The names of the available views for this render target.  Uses 1-based
    integer indices.  The ``find`` and ``index_of`` methods have O(n)
    complexity; all other supported operations have O(1) complexity.
target.current_view (read-only)
    The currently selected view for the render target.  This is a
    :ref:`layout view <luareference-render-layview>` object.
target.view_index (read/write)
    The 1-based index of the selected view for this render target.
target.visibility_mask (read-only)
    An integer bit mask indicating which item collections are currently visible
    for the current view.
target.screen_overlay (read/write)
    A Boolean indicating whether screen overlays are enabled.
target.zoom_to_screen (read/write)
    A Boolean indicating whether the render target is configured to scale so
    that the emulated screen(s) fill as much of the output window/screen as
    possible.

.. _luareference-render-container:

Render container
~~~~~~~~~~~~~~~~

Wraps MAME’s ``render_container`` class.

Instantiation
^^^^^^^^^^^^^

manager.machine.render.ui_container
    Gets the render container used to draw the user interface, including menus,
    sliders and pop-up messages.
manager.machine.screens[tag].container
    Gets the render container used to draw a given screen.

Methods
^^^^^^^

container:draw_box(left, top, right, bottom, [line], [fill])
    Draws an outlined rectangle with edges at the specified positions.

    Coordinates are floating-point numbers in the range of 0 (zero) to 1 (one),
    with (0, 0) at the top left and (1, 1) at the bottom right of the window or
    the screen that shows the user interface.  Note that the aspect ratio is
    usually not square.  Coordinates are limited to the window or screen area.

    The fill and line colours are in alpha/red/green/blue (ARGB) format.
    Channel values are in the range 0 (transparent or off) to 255 (opaque or
    full intensity), inclusive.  Colour channel values are not pre-multiplied by
    the alpha value.  The channel values must be packed into the bytes of a
    32-bit unsigned integer, in the order alpha, red, green, blue from
    most-significant to least-significant byte.  If the line colour is not
    provided, the UI text colour is used; if the fill colour is not provided,
    the UI background colour is used.
container:draw_line(x0, y0, x1, y1, [color])
    Draws a line from (x0, y0) to (x1, y1).

    Coordinates are floating-point numbers in the range of 0 (zero) to 1 (one),
    with (0, 0) at the top left and (1, 1) at the bottom right of the window or
    the screen that shows the user interface.  Note that the aspect ratio is
    usually not square.  Coordinates are limited to the window or screen area.

    The line colour is in alpha/red/green/blue (ARGB) format.  Channel values
    are in the range 0 (transparent or off) to 255 (opaque or full intensity),
    inclusive.  Colour channel values are not pre-multiplied by the alpha value.
    The channel values must be packed into the bytes of a 32-bit unsigned
    integer, in the order alpha, red, green, blue from most-significant to
    least-significant byte.  If the line colour is not provided, the UI text
    colour is used.
container:draw_quad(texture, x0, y0, x1, y1, [color])
    Draws a textured rectangle with top left corner at (x0, y0) and bottom right
    corner at (x1, y1).  If a colour is specified, the ARGB channel values of
    the texture’s pixels are multiplied by the corresponding values of the
    specified colour.

    Coordinates are floating-point numbers in the range of 0 (zero) to 1 (one),
    with (0, 0) at the top left and (1, 1) at the bottom right of the window or
    the screen that shows the user interface.  Note that the aspect ratio is
    usually not square.  If the rectangle extends beyond the container’s bounds,
    it will be cropped.

    The colour is in alpha/red/green/blue (ARGB) format.  Channel values are in
    the range 0 (transparent or off) to 255 (opaque or full intensity),
    inclusive.  Colour channel values are not pre-multiplied by the alpha value.
    The channel values must be packed into the bytes of a 32-bit unsigned
    integer, in the order alpha, red, green, blue from most-significant to
    least-significant byte.
container:draw_text(x|justify, y, text, [foreground], [background])
    Draws text at the specified position.  If the screen is rotated the text
    will be rotated.

    If the first argument is a number, the text will be left-aligned at this X
    coordinate.  If the first argument is a string, it must be ``"left"``,
    ``"center"`` or ``"right"`` to draw the text left-aligned at the
    left edge of the window or screen, horizontally centred in the window or
    screen, or right-aligned at the right edge of the window or screen,
    respectively.  The second argument specifies the Y coordinate of the maximum
    ascent of the text.

    Coordinates are floating-point numbers in the range of 0 (zero) to 1 (one),
    with (0, 0) at the top left and (1, 1) at the bottom right of the window or
    the screen that shows the user interface.  Note that the aspect ratio is
    usually not square.  Coordinates are limited to the window or screen area.

    The foreground and background colours are in alpha/red/green/blue (ARGB)
    format.  Channel values are in the range 0 (transparent or off) to 255
    (opaque or full intensity), inclusive.  Colour channel values are not
    pre-multiplied by the alpha value.  The channel values must be packed into
    the bytes of a 32-bit unsigned integer, in the order alpha, red, green, blue
    from most-significant to least-significant byte.  If the foreground colour
    is not provided, the UI text colour is used; if the background colour is not
    provided, it is fully transparent.

Properties
^^^^^^^^^^

container.user_settings (read/write)
    The container’s :ref:`user settings <luareference-render-contsettings>`.
    This can be used to control a number of image adjustments.
container.orientation (read/write)
    The container orientation flags.  This is an integer bit mask, where bit 0
    (0x01) is set to mirror horizontally, bit 1 (0x02) is set to mirror
    vertically, and bit 2 (0x04) is set to mirror along the top left-bottom
    right diagonal.
container.xscale (read/write)
    The container’s X scale factor.  This is a floating-point number.
container.yscale (read/write)
    The container’s Y scale factor.  This is a floating-point number.
container.xoffset (read/write)
    The container’s X offset.  This is a floating-point number where one (1)
    corresponds to the X size of the container.
container.yoffset (read/write)
    The container’s Y offset.  This is a floating-point number where one (1)
    corresponds to the Y size of the container.
container.is_empty (read-only)
    A Boolean indicating whether the container has no items.

.. _luareference-render-contsettings:

Container user settings
~~~~~~~~~~~~~~~~~~~~~~~

Wraps MAME’s ``render_container::user_settings`` class, representing image
adjustments applied to a
:ref:`render container <luareference-render-container>`.

Instantiation
^^^^^^^^^^^^^

manager.machine.screens[tag].container
    Gets the current container user settings for a given screen.

Properties
^^^^^^^^^^

settings.orientation (read/write)
    The container orientation flags.  This is an integer bit mask, where bit 0
    (0x01) is set to mirror horizontally, bit 1 (0x02) is set to mirror
    vertically, and bit 2 (0x04) is set to mirror along the top left-bottom
    right diagonal.
settings.brightness (read/write)
    The brightness adjustment applied to the container.  This is a
    floating-point number.
settings.contrast (read/write)
    The contrast adjustment applied to the container.  This is a floating-point
    number.
settings.gamma (read/write)
    The gamma adjustment applied to the container.  This is a floating-point
    number.
settings.xscale (read/write)
    The container’s X scale factor.  This is a floating-point number.
settings.yscale (read/write)
    The container’s Y scale factor.  This is a floating-point number.
settings.xoffset (read/write)
    The container’s X offset.  This is a floating-point number where one (1)
    represents the X size of the container.
settings.yoffset (read/write)
    The container’s Y offset.  This is a floating-point number where one (1)
    represents the Y size of the container.

.. _luareference-render-layfile:

Layout file
~~~~~~~~~~~

Wraps MAME’s ``layout_file`` class, representing the views loaded from a layout
file for use by a render target.

Instantiation
^^^^^^^^^^^^^

A layout file object is supplied to its layout script in the ``file`` variable.
Layout file objects are not instantiated directly from Lua scripts.

Methods
^^^^^^^

layout:set_resolve_tags_callback(cb)
    Set a function to perform additional tasks after the emulated machine has
    finished starting, tags in the layout views have been resolved, and the
    default view item handlers have been set up.  The function must accept no
    arguments.

    Call with ``nil`` to remove the callback.

Properties
^^^^^^^^^^

layout.device (read-only)
    The device that caused the layout file to be loaded.  Usually the root
    machine device for external layouts.
layout.views[] (read-only)
    The :ref:`views <luareference-render-layview>` created from the layout file.
    Views are indexed by unqualified name (i.e. the value of the ``name``
    attribute).  Views are ordered how they appear in the layout file when
    iterating or using the ``at`` method.  The index get, ``at`` and
    ``index_of`` methods have O(n) complexity.

    Note that not all views in the XML file may be created.  For example views
    that reference screens provided by slot card devices will not be created if
    said slot card devices are not present in the system.

.. _luareference-render-layview:

Layout view
~~~~~~~~~~~

Wraps MAME’s ``layout_view`` class, representing a view that can be displayed in
a render target.  Views are created from XML layout files, which may be loaded
from external artwork, internal to MAME, or automatically generated based on the
screens in the emulated system.

Instantiation
^^^^^^^^^^^^^

manager.machine.render.targets[index].current_view
    Gets the currently selected view for a given render target.
file.views[name]
    Gets the view with the specified name from a
    :ref:`layout file <luareference-render-layfile>`.  This is how layout
    scripts generally obtain views.

Methods
^^^^^^^

view:has_screen(screen)
    Returns a Boolean indicating whether the screen is present in the view.
    This is true for screens that are present but not visible because the user
    has hidden the item collection they belong to.
view:set_prepare_items_callback(cb)
    Set a function to perform additional tasks before the view items are added
    to the render target in preparation for drawing a video frame.  The function
    must accept no arguments.  Call with ``nil`` to remove the callback.
view:set_preload_callback(cb)
    Set a function to perform additional tasks after preloading visible view
    items.  The function must accept no arguments.  Call with ``nil`` to remove
    the callback.

    This function may be called when the user selects a view or makes an item
    collection visible.  It may be called multiple times for a view, so avoid
    repeating expensive tasks.
view:set_recomputed_callback(cb)
    Set a function to perform additional tasks after the view’s dimensions are
    recomputed.  The function must accept no arguments.  Call with ``nil`` to
    remove the callback.

    View coordinates are recomputed in various events, including the window
    being resized, entering or leaving full-screen mode, and changing the zoom
    to screen area setting.

Properties
^^^^^^^^^^

view.items[] (read-only)
    The screen and layout element :ref:`items <luareference-render-layitem>` in
    the view.  This container does not support iteration by key using ``pairs``;
    only iteration by index using ``ipairs`` is supported.  The key is the value
    of the ``id`` attribute if present.  Only items with ``id`` attributes can
    be looked up by key.  The index get method has O(1) complexity, and the
    ``at`` and ``index_of`` methods have O(n) complexity.
view.name (read-only)
    The display name for the view.  This may be qualified to indicate the device
    that caused the layout file to be loaded when it isn’t the root machine
    device.
view.unqualified_name (read-only)
    The unqualified name of the view, exactly as it appears in the ``name``
    attribute in the XML layout file.
view.visible_screen_count (read-only)
    The number of screens items currently enabled in the view.
view.effective_aspect (read-only)
    The effective width-to-height aspect ratio of the view in its current
    configuration.
view.bounds (read-only)
    A :ref:`render bounds <luareference-render-bounds>` object representing the
    effective bounds of the view in its current configuration.  The coordinates
    are in view units, which are arbitrary but assumed to have square aspect
    ratio.
view.has_art
    A Boolean indicating whether the view has any non-screen items, including
    items that are not visible because the user has hidden the item collection
    that they belong to.

.. _luareference-render-layitem:

Layout view item
~~~~~~~~~~~~~~~~

Wraps MAME’s ``layout_view_item`` class, representing an item in a view.  An
item is drawn as a rectangular textured surface.  The texture is supplied by an
emulated screen or a layout element.

Instantiation
^^^^^^^^^^^^^

layout.views[name].items[id]
    Get a view item by ID.  The item must have an ``id`` attribute in the XML
    layout file to be looked up by ID.

Methods
^^^^^^^

item:set_state(state)
    Set the value used as the element state and animation state in the absence
    of bindings.  The argument must be an integer.
item:set_element_state_callback(cb)
    Set a function to call to obtain the element state for the item.  The
    function must accept no arguments and return an integer.  Call with ``nil``
    to restore the default element state callback (based on bindings in the XML
    layout file).

    Note that the function must not access the item’s ``element_state``
    property, as this will result in infinite recursion.

    This callback will not be used to obtain the animation state for the item,
    even if the item lacks explicit animation state bindings in the XML layout
    file.
item:set_animation_state_callback(cb)
    Set a function to call to obtain the animation state for the item.  The
    function must accept no arguments and return an integer.  Call with ``nil``
    to restore the default animation state callback (based on bindings in the
    XML layout file).

    Note that the function must not access the item’s ``animation_state``
    property, as this will result in infinite recursion.
item:set_bounds_callback(cb)
    Set a function to call to obtain the bounds for the item.  The function must
    accept no arguments and return a
    :ref:`render bounds <luareference-render-bounds>` object in render target
    coordinates.  Call with ``nil`` to restore the default bounds callback
    (based on the item’s animation state and ``bounds`` child elements in the
    XML layout file).

    Note that the function must not access the item’s ``bounds`` property, as
    this will result in infinite recursion.
item:set_color_callback(cb)
    Set a function to call to obtain the multiplier colour for the item.  The
    function must accept no arguments and return a
    :ref:`render colour <luareference-render-color>` object.  Call with ``nil``
    to restore the default colour callback (based on the item’s animation state
    and ``color`` child elements in the XML layout file).

    Note that the function must not access the item’s ``color`` property, as
    this will result in infinite recursion.
item:set_scroll_size_x_callback(cb)
    Set a function to call to obtain the size of the horizontal scroll window as
    a proportion of the associated element’s width.  The function must accept no
    arguments and return a floating-point value.  Call with ``nil`` to restore
    the default horizontal scroll window size callback (based on the ``xscroll``
    child element in the XML layout file).

    Note that the function must not access the item’s ``scroll_size_x``
    property, as this will result in infinite recursion.
item:set_scroll_size_y_callback(cb)
    Set a function to call to obtain the size of the vertical scroll window as a
    proportion of the associated element’s height.  The function must accept no
    arguments and return a floating-point value.  Call with ``nil`` to restore
    the default vertical scroll window size callback (based on the ``yscroll``
    child element in the XML layout file).

    Note that the function must not access the item’s ``scroll_size_y``
    property, as this will result in infinite recursion.
item:set_scroll_pos_x_callback(cb)
    Set a function to call to obtain the horizontal scroll position.  A value of
    zero places the horizontal scroll window at the left edge of the associated
    element.  If the item does not wrap horizontally, a value of 1.0 places the
    horizontal scroll window at the right edge of the associated element; if the
    item wraps horizontally, a value of 1.0 corresponds to wrapping back to the
    left edge of the associated element.  The function must accept no arguments
    and return a floating-point value.  Call with ``nil`` to restore the default
    horizontal scroll position callback (based on bindings in the ``xscroll``
    child element in the XML layout file).

    Note that the function must not access the item’s ``scroll_pos_x`` property,
    as this will result in infinite recursion.
item:set_scroll_pos_y_callback(cb)
    Set a function to call to obtain the vertical scroll position.  A value of
    zero places the vertical scroll window at the top edge of the associated
    element.  If the item does not wrap vertically, a value of 1.0 places the
    vertical scroll window at the bottom edge of the associated element; if the
    item wraps vertically, a value of 1.0 corresponds to wrapping back to the
    left edge of the associated element.  The function must accept no arguments
    and return a floating-point value.  Call with ``nil`` to restore the default
    vertical scroll position callback (based on bindings in the ``yscroll``
    child element in the XML layout file).

    Note that the function must not access the item’s ``scroll_pos_y`` property,
    as this will result in infinite recursion.

Properties
^^^^^^^^^^

item.id (read-only)
    Get the optional item identifier.  This is the value of the ``id`` attribute
    in the XML layout file if present, or ``nil``.
item.bounds_animated (read-only)
    A Boolean indicating whether the item’s bounds depend on its animation
    state.
item.color_animated (read-only)
    A Boolean indicating whether the item’s colour depends on its animation
    state.
item.bounds (read-only)
    The item’s bounds for the current state.  This is a
    :ref:`render bounds <luareference-render-bounds>` object in render target
    coordinates.
item.color (read-only)
    The item’s colour for the current state.  The colour of the screen or
    element texture is multiplied by this colour.  This is a
    :ref:`render colour <luareference-render-color>` object.
item.scroll_wrap_x (read-only)
    A Boolean indicating whether the item wraps horizontally.
item.scroll_wrap_y (read-only)
    A Boolean indicating whether the item wraps vertically.
item.scroll_size_x (read/write)
    Get the item’s horizontal scroll window size for the current state, or set
    the horizontal scroll window size to use in the absence of bindings.  This
    is a floating-point value representing a proportion of the associated
    element’s width.
item.scroll_size_y (read/write)
    Get the item’s vertical scroll window size for the current state, or set the
    vertical scroll window size to use in the absence of bindings.  This is a
    floating-point value representing a proportion of the associated element’s
    height.
item.scroll_pos_x (read/write)
    Get the item’s horizontal scroll position for the current state, or set the
    horizontal scroll position size to use in the absence of bindings.  This is
    a floating-point value.
item.scroll_pos_y (read/write)
    Get the item’s vertical scroll position for the current state, or set the
    vertical position size to use in the absence of bindings.  This is a
    floating-point value.
item.blend_mode (read-only)
    Get the item’s blend mode.  This is an integer value, where 0 means no
    blending, 1 means alpha blending, 2 means RGB multiplication, 3 means
    additive blending, and -1 allows the items within a container to specify
    their own blending modes.
item.orientation (read-only)
    Get the item orientation flags.  This is an integer bit mask, where bit 0
    (0x01) is set to mirror horizontally, bit 1 (0x02) is set to mirror
    vertically, and bit 2 (0x04) is set to mirror along the top left-bottom
    right diagonal.
item.element_state (read-only)
    Get the current element state.  This will call the element state callback
    function to handle bindings.
item.animation_state (read-only)
    Get the current animation state.  This will call the animation state
    callback function to handle bindings.


.. _luareference-debug:

Debugger
--------

Some of MAME’s core debugging features can be controlled from Lua script.  The
debugger must be enabled to use the debugger features (usually by passing
``-debug`` on the command line).

.. _luareference-debug-symtable:

Symbol table
~~~~~~~~~~~~

Wrap’s MAME’s ``symbol_table`` class, providing named symbols that can be used
in expressions.  Note that symbol tables can be created and used even when the
debugger is not enabled.

Instantiation
^^^^^^^^^^^^^

emu.symbol_table(machine)
    Creates a new symbol table in the context of the specified machine,
emu.symbol_table(parent, [device])
    Creates a new symbol table with the specified parent symbol table.  If a
    device is specified and it implements ``device_memory_interface``, it will
    be used as the base for looking up address spaces and memory regions.  Note
    that if a device that does not implement ``device_memory_interface`` is
    supplied, it will not be used (address spaces and memory regions will be
    looked up relative to the root device).
emu.symbol_table(device)
    Creates a new symbol table in the context of the specified device.  If the
    device implements ``device_memory_interface``, it will be used as the base
    for looking up address spaces and memory regions.  Note that if a device
    that does not implement ``device_memory_interface`` is supplied, it will
    only be used to determine the machine context (address spaces and memory
    regions will be looked up relative to the root device).

Methods
^^^^^^^

symbols:set_memory_modified_func(cb)
    Set a function to call when memory is modified via the symbol table.  No
    arguments are passed to the function and any return values are ignored.
    Call with ``nil`` to remove the callback.
symbols:add(name, [value])
    Adds a named integer symbol.  The name must be a string.  If a value is
    supplied, it must be an integer.  If a value is supplied, a read-only symbol
    is added with the supplied value.  If no value is supplied, a read/write
    symbol is created with and initial value of zero.  If a symbol entry with
    the specified name already exists in the symbol table, it will be replaced.

    Returns the new :ref:`symbol entry <luareference-debug-symentry>`.
symbols:add(name, getter, [setter], [format])
    Adds a named integer symbol using getter and optional setter callbacks.  The
    name must be a string.  The getter must be a function returning an integer
    for the symbol value.  If supplied, the setter must be a function that
    accepts a single integer argument for the new value of the symbol.  A format
    string for displaying the symbol value may optionally be supplied.  If a
    symbol entry with the specified name already exists in the symbol table, it
    will be replaced.

    Returns the new :ref:`symbol entry <luareference-debug-symentry>`.
symbols:add(name, minparams, maxparams, execute)
    Adds a named function symbol.  The name must be a string.  The minimum and
    maximum numbers of parameters must be integers.  If a symbol entry with the
    specified name already exists in the symbol table, it will be replaced.

    Returns the new :ref:`symbol entry <luareference-debug-symentry>`.
symbols:find(name)
    Returns the :ref:`symbol entry <luareference-debug-symentry>` with the
    specified name, or ``nil`` if there is no symbol with the specified name in
    the symbol table.
symbols:find_deep(name)
    Returns the :ref:`symbol entry <luareference-debug-symentry>` with the
    specified name, or ``nil`` if there is no symbol with the specified name in
    the symbol table or any of its parent symbol tables.
symbols:value(name)
    Returns the integer value of the symbol with the specified name, or zero if
    there is no symbol with the specified name in the symbol table or any of its
    parent symbol tables.  Raises an error if the symbol with specified name is
    a function symbol.
symbols:set_value(name, value)
    Sets the value of the symbol with the specified name.  Raises an error if
    the symbol with the specified name is a read-only integer symbol or if it is
    a function symbol.  Has no effect if there is no symbol with the specified
    name in the symbol table or any of its parent symbol tables.
symbols:memory_value(name, space, offset, size, disable_se)
    Read a value from memory.  Supply the name or tag of the address space or
    memory region to read from, or ``nil`` to use the address space or memory
    region implied by the ``space`` argument.  See
    :ref:`memory accesses in debugger expressions <debugger-express-mem>` for
    access type specifications that can be used for the ``space`` argument.
    The access size is specified in bytes, and must be 1, 2, 4 or 8.  The
    ``disable_se`` argument specifies whether memory access side effects should
    be disabled.
symbols:set_memory_value(name, space, offset, value, size, disable_se)
    Write a value to memory.  Supply the name or tag of the address space or
    memory region to write to, or ``nil`` to use the address space or memory
    region implied by the ``space`` argument.  See
    :ref:`memory accesses in debugger expressions <debugger-express-mem>` for
    access type specifications that can be used for the ``space`` argument.
    The access size is specified in bytes, and must be 1, 2, 4 or 8.  The
    ``disable_se`` argument specifies whether memory access side effects should
    be disabled.
symbols:read_memory(space, address, size, apply_translation)
    Read a value from an address space.  The access size is specified in bytes,
    and must be 1, 2, 4, or 8.  If the ``apply_translation`` argument is true,
    the address will be translated with debug read intention.  Returns a value
    of the requested size with all bits set if address translation fails.
symbols:write_memory(space, address, data, size, apply_translation)
    Write a value to an address space.  The access size is specified in bytes,
    and must be 1, 2, 4, or 8.  If the ``apply_translation`` argument is true,
    the address will be translated with debug write intention.  The symbol
    table’s memory modified function will be called after the value is written.
    The value will not be written and the symbol table’s memory modified
    function will not be called if address translation fails.

Properties
^^^^^^^^^^

symbols.entries[]
    The :ref:`symbol entries <luareference-debug-symentry>` in the symbol table,
    indexed by name.  The ``at`` and ``index_of`` methods have O(n) complexity;
    all other supported operations have O(1) complexity.
symbols.parent (read-only)
    The parent symbol table, or ``nil`` if the symbol table has no parent.

.. _luareference-debug-expression:

Parsed expression
~~~~~~~~~~~~~~~~~

Wraps MAME’s ``parsed_expression`` class, which represents a tokenised debugger
expression.  Note that parsed expressions can be created and used even when the
debugger is not enabled.

Instantiation
^^^^^^^^^^^^^

emu.parsed_expression(symbols)
    Creates an empty expression that will use the supplied
    :ref:`symbol table <luareference-debug-symtable>` to look up symbols.
emu.parsed_expression(symbols, string, [default_base])
    Creates an expression by parsing the supplied string, looking up symbols in
    the supplied :ref:`symbol table <luareference-debug-symtable>`.  If the
    default base for interpreting integer literals is not supplied, 16 is used
    (hexadecimal).  Raises an :ref:`expression error
    <luareference-debug-expressionerror>` if the string contains syntax errors
    or uses undefined symbols.

Methods
^^^^^^^

expression:set_default_base(base)
    Set the default base for interpreting numeric literals.  The base must be a
    positive integer.
expression:parse(string)
    Parse a debugger expression string.  Replaces the current contents of the
    expression if it is not empty.  Raises an :ref:`expression error
    <luareference-debug-expressionerror>` if the string contains syntax errors
    or uses undefined symbols.  The previous content of the expression is not
    preserved when attempting to parse an invalid expression string.
expression:execute()
    Evaluates the expression, returning an unsigned integer result.  Raises an
    :ref:`expression error <luareference-debug-expressionerror>` if the
    expression cannot be evaluated (e.g. attempting to call a function with an
    invalid number of arguments).

Properties
^^^^^^^^^^

expression.is_empty (read-only)
    A Boolean indicating whether the expression contains no tokens.
expression.original_string (read-only)
    The original string that was parsed to create the expression.
expression.symbols (read/write)
    The :ref:`symbol table <luareference-debug-symtable>` used for to look up
    symbols in the expression.

.. _luareference-debug-symentry:

Symbol entry
~~~~~~~~~~~~

Wraps MAME’s ``symbol_entry`` class, which represents an entry in a
:ref:`symbol table <luareference-debug-symtable>`.  Note that symbol entries
must not be used after the symbol table they belong to is destroyed.

Instantiation
^^^^^^^^^^^^^

symbols:add(name, [value])
    Adds an integer symbol to a
    :ref:`symbol table <luareference-debug-symtable>`, returning the new symbol
    entry.
symbols:add(name, getter, [setter], [format])
    Adds an integer symbol to a
    :ref:`symbol table <luareference-debug-symtable>`, returning the new symbol
    entry.
symbols:add(name, minparams, maxparams, execute)
    Adds function symbol to a
    :ref:`symbol table <luareference-debug-symtable>`, returning the new symbol
    entry.

Properties
^^^^^^^^^^

entry.name (read-only)
    The name of the symbol entry.
entry.format (read-only)
    The format string used to convert the symbol entry to text for display.
entry.is_function (read-only)
    A Boolean indicating whether the symbol entry is a callable function.
entry.is_lval (read-only)
    A Boolean indicating whether the symbol entry is an integer symbol that can
    be set (i.e. whether it can be used on the left-hand side of assignment
    expressions).
entry.value (read/write)
    The integer value of the symbol entry.  Attempting to set the value raises
    an error if the symbol entry is read-only.  Attempting to get or set the
    value of a function symbol raises an error.

.. _luareference-debug-manager:

Debugger manager
~~~~~~~~~~~~~~~~

Wraps MAME’s ``debugger_manager`` class, providing the main interface to control
the debugger.

Instantiation
^^^^^^^^^^^^^

manager.machine.debugger
    Returns the global debugger manager instance, or ``nil`` if the debugger is
    not enabled.

Methods
^^^^^^^

debugger:command(str)
    Execute a debugger console command.  The argument is the command string.
    The output is sent to both the debugger console and the Lua console.

Properties
^^^^^^^^^^

debugger.consolelog[] (read-only)
    The lines in the console log (output from debugger commands).  This
    container only supports index and length operations.
debugger.errorlog[] (read-only)
    The lines in the error log (``logerror`` output).  This container only
    supports index and length operations.
debugger.visible_cpu (read/write)
    The CPU device with debugger focus.  Changes become visible in the debugger
    console after the next step.  Setting to a device that is not a CPU has no
    effect.
debugger.execution_state (read/write)
    Either ``"run"`` if the emulated system is running, or ``"stop"`` if it is
    stopped in the debugger.

.. _luareference-debug-devdebug:

Device debugger interface
~~~~~~~~~~~~~~~~~~~~~~~~~

Wraps MAME’s ``device_debug`` class, providing the debugger interface to an
emulated CPU device.

Instantiation
^^^^^^^^^^^^^

manager.machine.devices[tag].debug
    Returns the debugger interface for an emulated CPU device, or ``nil`` if the
    device is not a CPU.

Methods
^^^^^^^

debug:step([cnt])
    Step by the specified number of instructions.  If the instruction count is
    not provided, it defaults to a single instruction.
debug:go()
    Run the emulated CPU.
debug:bpset(addr, [cond], [act])
    Set a breakpoint at the specified address, with an optional condition and
    action.  If the action is not specified, it defaults to just breaking into
    the debugger.  Returns the breakpoint number for the new breakpoint.

    If specified, the condition must be a debugger expression that will be
    evaluated each time the breakpoint is hit.  Execution will only be stopped
    if the expression evaluates to a non-zero value.  If the condition is not
    specified, it defaults to always active.
debug:bpenable([bp])
    Enable the specified breakpoint, or all breakpoints for the device if no
    breakpoint number is specified.  Returns whether the specified number
    matched a breakpoint if a breakpoint number is specified, or ``nil`` if no
    breakpoint number is specified.
debug:bpdisable([bp])
    Disable the specified breakpoint, or all breakpoints for the device if no
    breakpoint number is specified.  Returns whether the specified number
    matched a breakpoint if a breakpoint number is specified, or ``nil`` if no
    breakpoint number is specified.
debug:bpclear([bp])
    Clear the specified breakpoint, or all breakpoints for the device if no
    breakpoint number is specified.  Returns whether the specified number
    matched a breakpoint if a breakpoint number is specified, or ``nil`` if no
    breakpoint number is specified.
debug:bplist()
    Returns a table of breakpoints for the device.  The keys are the breakpoint
    numbers, and the values are
    :ref:`breakpoint objects <luareference-debug-breakpoint>`.
debug:wpset(space, type, addr, len, [cond], [act])
    Set a watchpoint over the specified address range, with an optional
    condition and action.  The type must be ``"r"``, ``"w"`` or ``"rw"`` for a
    read, write or read/write breakpoint.  If the action is not specified, it
    defaults to just breaking into the debugger.  Returns the watchpoint number
    for the new watchpoint.

    If specified, the condition must be a debugger expression that will be
    evaluated each time the breakpoint is hit.  Execution will only be stopped
    if the expression evaluates to a non-zero value.  The variable 'wpaddr' is
    set to the address that actually triggered the watchpoint, the variable
    'wpdata' is set to the data that is being read or written, and the variable
    'wpsize' is set to the size of the data in bytes.  If the condition is not
    specified, it defaults to always active.
debug:wpenable([wp])
    Enable the specified watchpoint, or all watchpoints for the device if no
    watchpoint number is specified.  Returns whether the specified number
    matched a watchpoint if a watchpoint number is specified, or ``nil`` if no
    watchpoint number is specified.
debug:wpdisable([wp])
    Disable the specified watchpoint, or all watchpoints for the device if no
    watchpoint number is specified.  Returns whether the specified number
    matched a watchpoint if a watchpoint number is specified, or ``nil`` if no
    watchpoint number is specified.
debug:wpclear([wp])
    Clear the specified watchpoint, or all watchpoints for the device if no
    watchpoint number is specified.  Returns whether the specified number
    matched a watchpoint if a watchpoint number is specified, or ``nil`` if no
    watchpoint number is specified.
debug:wplist(space)
    Returns a table of watchpoints for the specified address space of the
    device.  The keys are the watchpoint numbers, and the values are
    :ref:`watchpoint objects <luareference-debug-watchpoint>`.

.. _luareference-debug-breakpoint:

Breakpoint
~~~~~~~~~~

Wraps MAME’s ``debug_breakpoint`` class, representing a breakpoint for an
emulated CPU device.

Instantiation
^^^^^^^^^^^^^

manager.machine.devices[tag].debug:bplist()[bp]
    Gets the specified breakpoint for an emulated CPU device, or ``nil`` if no
    breakpoint corresponds to the specified index.

Properties
^^^^^^^^^^

breakpoint.index (read-only)
    The breakpoint’s index.  The can be used to enable, disable or clear the
    breakpoint via the
    :ref:`CPU debugger interface <luareference-debug-devdebug>`.
breakpoint.enabled (read/write)
    A Boolean indicating whether the breakpoint is currently enabled.
breakpoint.address (read-only)
    The breakpoint’s address.
breakpoint.condition (read-only)
    A debugger expression evaluated each time the breakpoint is hit.  The action
    will only be triggered if this expression evaluates to a non-zero value.  An
    empty string if no condition was specified.
breakpoint.action (read-only)
    An action the debugger will run when the breakpoint is hit and the condition
    evaluates to a non-zero value.  An empty string if no action was specified.

.. _luareference-debug-watchpoint:

Watchpoint
~~~~~~~~~~

Wraps MAME’s ``debug_watchpoint`` class, representing a watchpoint for an
emulated CPU device.

Instantiation
^^^^^^^^^^^^^

manager.machine.devices[tag].debug:wplist(space)[wp]
    Gets the specified watchpoint for an address space of an emulated CPU
    device, or ``nil`` if no watchpoint in the address space corresponds to the
    specified index.

Properties
^^^^^^^^^^

watchpoint.index (read-only)
    The watchpoint’s index.  The can be used to enable, disable or clear the
    watchpoint via the
    :ref:`CPU debugger interface <luareference-debug-devdebug>`.
watchpoint.enabled (read/write)
    A Boolean indicating whether the watchpoint is currently enabled.
watchpoint.type (read-only)
    Either ``"r"``, ``"w"`` or ``"rw"`` for a read, write or read/write
    watchpoint.
watchpoint.address (read-only)
    The starting address of the watchpoint’s address range.
watchpoint.length (read-only)
    The length of the watchpoint’s address range.
watchpoint.condition (read-only)
    A debugger expression evaluated each time the watchpoint is hit.  The action
    will only be triggered if this expression evaluates to a non-zero value.  An
    empty string if no condition was specified.
watchpoint.action (read-only)
    An action the debugger will run when the watchpoint is hit and the condition
    evaluates to a non-zero value.  An empty string if no action was specified.

.. _luareference-debug-expressionerror:

Expression error
~~~~~~~~~~~~~~~~

Wraps MAME’s ``expression_error`` class, describing an error occurring while
parsing or executing a debugger expression.  Raised on errors when using
:ref:`parsed expressions <luareference-debug-expression>`.  Can be converted to
a string to provide a description of the error.

Properties
^^^^^^^^^^

err.code (read-only)
    An implementation-dependent number representing the category of error.
    Should not be displayed to the user.
err.offset (read-only)
    The offset within the expression string where the error was encountered.