diff options
author | 2022-09-02 08:55:16 +1000 | |
---|---|---|
committer | 2022-09-02 08:55:16 +1000 | |
commit | 051c380fd14040c83a0d5b919e6289e70fef9df8 (patch) | |
tree | e247a309f4d1c66c07803c02d67ac89837211bd1 /docs/source/advanced | |
parent | 67f129e31518a50a801413f732991972d2c3538a (diff) |
Patched up some gaps in functionality and fixed some bugs.
ui: Added some missing functionality:
* Added an option to copy input device IDs to the relevant menus.
* Added an item for setting the software lists files path (-hashpath) to
the folder setup menu.
* Allow pasting text from clipboard in most places that allow typing
(searching, entering filenames, entering barcodes).
* Changed the software selection menu heading to be a bit less
misleading.
* Made barcode menu less eager to rebuild itself unnecessarily, and
removed some confusing and apparently pointless code.
Exposed more Lua bindings:
* Added low-level palette objects.
* Added indexed bitmap types.
* Added a bitmap method for extracting pixels from a rectangular area as a
packed binary string.
* Changed screen device pixels method to return width and height in
addition to the pixels.
osd: Added some functionality and cleaned up a little:
* Added a function for copying text to the clipboard.
* Moved function for converting Windows error codes to standard error
conditions to winutil.cpp so it can be used from more places.
* Removed duplicate declaration of osd_get_clipboard_text and made the
function noexcept (including fixing implementations).
* Made macOS implementation of osd_get_clipboard_text skip the encoding
conversion if it finds UTF-8 text first.
* Changed the default -uimodekey setting so it doesn't lose the "not
shift" that stops the default from interfering with UI paste.
Various bug fixes:
* util/unicode.cpp: Fixed the version of utf8_from_uchar that returns
std::string blowing up on invalid codepoints.
* util/bitmap.h: Fixed wrapping constructors for indexed bitmaps taking
the wrong parameter type (nothing was using them before).
* util/bitmap.cpp: Fixed potential use-after-free issues with bitmap
palettes.
* emu/input.cpp, emu/inputdev.cpp: Log 1-based device numbers, matching
what's shown in the internal UI and used in tokens in CFG files.
* emu/emumem.cpp: Added the bank tag to a fatal error message where it
was missing.
docs: Reworked and expanded documentation on configuring stable
controller IDs.
For translators, the changes are quite minor:
* There's a menu item for copying a device ID to the clipboard, and
associated success/failure messages.
* There's the menu item for setting the software list file search path.
* One of the lines in the software selection menu heading has changes as
it could be interpreted as implying it showed a software list name.
Diffstat (limited to 'docs/source/advanced')
-rw-r--r-- | docs/source/advanced/ctrlr_config.rst | 31 | ||||
-rw-r--r-- | docs/source/advanced/devicemap.rst | 124 |
2 files changed, 123 insertions, 32 deletions
diff --git a/docs/source/advanced/ctrlr_config.rst b/docs/source/advanced/ctrlr_config.rst index 6fdeddc8a8a..9e284f7f945 100644 --- a/docs/source/advanced/ctrlr_config.rst +++ b/docs/source/advanced/ctrlr_config.rst @@ -228,3 +228,34 @@ Here’s an example that overrides defaults for 280-ZZZAP: This sets the controls to steer left and right to the K and J keys, respectively, and disables the toggle setting for the gear shift input. + + +.. _ctrlrcfg-mapdevice: + +Assigning input device numbers +------------------------------ + +Use ``mapdevice`` elements with ``device`` and ``controller`` attributes to +assign stable numbers to input devices. Note that all devices explicitly +configured in this way must be connected when MAME starts for this to work as +expected. + +Set the ``device`` attribute to the device ID of the input device, and set the +``controller`` attribute to the desired input device token (device type and +number). + +Here’s an example numbering two light guns and two XInput game controllers: + +.. code-block:: XML + + <system name="default"> + <input> + <mapdevice device="VID_D209&PID_1601" controller="GUNCODE_1" /> + <mapdevice device="VID_D209&PID_1602" controller="GUNCODE_2" /> + <mapdevice device="XInput Player 1" controller="JOYCODE_1" /> + <mapdevice device="XInput Player 2" controller="JOYCODE_2" /> + </input> + </system> + +MAME applies ``mapdevice`` elements found inside any applicable ``system`` +element. diff --git a/docs/source/advanced/devicemap.rst b/docs/source/advanced/devicemap.rst index 38dcc3a2641..aaf1450d4ab 100644 --- a/docs/source/advanced/devicemap.rst +++ b/docs/source/advanced/devicemap.rst @@ -1,26 +1,52 @@ +.. _devicemap: + Stable Controller IDs -=============================== +===================== + +By default, MAME does not assign stable numbers to input devices. For instance, +a game pad controller may be assigned to “Joy 1” initially, but after +restarting, the same game pad may be reassigned to “Joy 3”. + +The reason is that MAME assigns numbers to input devices in the based on +enumeration order. Factors that can cause this to change include disconnecting +and reconnecting USB or Bluetooth devices, changing ports/hubs, and even just +restarting the computer. Input device numbers can be quite unpredictable. -By default, the mapping between devices and controller IDs is not stable. For instance, a gamepad controller may be assigned to "Joy 1" initially, but after a reboot, it may get re-assigned to "Joy 3". +This is where the ``mapdevice`` configuration setting comes into the picture. +By adding this setting to a :ref:`controller configuration file <ctrlrcfg>`, you +can ensure that a given input device is always assigned the same number in MAME. -The reason is that MAME enumerates attached devices and assigns controller IDs based on the enumeration order. Factors that can cause controller IDs to change include plugging / unplugging USB devices, changing ports / hubs and even system reboots. -It is quite cumbersome to ensure that controller IDs are always correct. +Using mapdevice +--------------- -That's where the "mapdevice" configuration setting comes into the picture. This setting allows you to map a device id to a controller ID, ensuring that the specified device always maps to the same controller ID in MAME. +The ``mapdevice`` XML element is added to the ``input`` XML element in the +controller configuration file. It requires two attributes, ``device`` and +``controller``. Note that ``mapdevice`` elements only take effect in the +controller configuration file (set using the :ref:`-ctrlr option +<mame-commandline-ctrlr>`) – they are ignored in system configuration files and +the default configuration file. -Usage of mapdevice ------------------- -The "mapdevice" xml element is specified under the input xml element in the controller configuration file. It requires two attributes, "device" and "controller". -NOTE: This setting only take effect when added to the **ctrlr** config file. +The ``device`` attribute specifies the device ID of the input device to match. +It may also be a substring of the device ID. To obtain the device ID for an +input device, select it in the :ref:`menus-inputdevices`, and then select **Copy +Device ID**. The device ID will be copied to the clipboard. You can also see +input device IDs by turning on verbose logging (more on this later). The format +of device IDs depends the type of device, selected input provider module and +operating system. Your input device IDs may look very different to the examples +here. -The "device" attribute specifies the id of the device to match. It may also be a substring of the id. To see the list of available devices, enable verbose output and available devices will then be listed to the console at startup (more on this below). +The ``controller`` attribute specifies the input token for the input device type +(i.e. ``JOYCODE``, ``GUNCODE``, ``MOUSECODE``) and number to assign to the +device, separated by an underscore. Numbering starts from 1. For example the +token for the first joystick device will be ``JOYCODE_1``, the second will be +``JOYCODE_2``, and so on. -The "controller" attribute specifies the MAME controller ID. It is made up of a controller class (i.e. ``JOYCODE``, ``GUNCODE``, ``MOUSECODE``) and controller index. For example: ``JOYCODE_1``. Example ------- -Here's an example: + +Here’s an example: | <mameconfig version="10"> | <system name="default"> @@ -40,37 +66,71 @@ Here's an example: In the above example, we have four device mappings specified: -The first two mapdevice entries map player 1 and 2 lightguns to Gun 1 and Gun 2, respectively. We use a substring of the full raw device names to match each devices. Note that, since this is XML, we needed to escape the ``&`` using ``&``. +* The first two ``mapdevice`` elements map player 1 and 2 light guns to Gun 1 + and Gun 2, respectively. We use a substring of the full device IDs to match + each devices. Note that, since this is XML, we needed to escape the + ampersands (``&``) as ``&``. +* The last two ``mapdevices`` elements map player 1 and player 2 gamepad + controllers to Joy 1 and Joy 2, respectively. In this case, these are XInput + game controllers. -The last two mapdevices entries map player 1 and player 2 gamepad controllers to Joy 1 and Joy 2, respectively. In this case, these are XInput devices. Listing Available Devices ------------------------- -How did we obtain the device id's in the above example? Easy! -Run MAME with -v parameter to enable verbose output. It will then list available devices include the corresponding "device id" to the console. +There are two ways to obtain device IDs: by copying them from the +:ref:`menus-inputdevices`, or by :ref:`turning on verbose logging +<mame-commandline-verbose>` and finding the messages logged when input devices +are added. + +To reach the Input Devices menu from the system selection menu, select **General +Settings**, and the select **Input Devices**. To reach the input devices menu +from the :ref:`main menu <menus-main>`, select **Input Settings**, then select +**Input Devices**. From the Input Devices menu, select a device, then select +**Copy Device ID** to copy its device ID to the clipboard. + +To use verbose logging, run MAME with the ``-v`` or ``-verbose`` option on the +command line. Search the output for messages starting with “Input: Adding…” +that show recognised input devices and their respective IDs. Here an example: -| Input: Adding Gun #0: -| Input: Adding Gun #1: -| Input: Adding Gun #2: HID-compliant mouse (**device id: \\?\HID#VID_045E&PID_0053#7&18297dcb&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd}**) -| Input: Adding Gun #3: HID-compliant mouse (**device id: \\?\HID#IrDeviceV2&Col08#2&2818a073&0&0007#{378de44c-56ef-11d1-bc8c-00a0c91405dd}**) -| Input: Adding Gun #4: HID-compliant mouse (**device id: \\?\HID#VID_D209&PID_1602&MI_02#8&389ab7f3&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd}**) -| Input: Adding Gun #5: HID-compliant mouse (**device id: \\?\HID#VID_D209&PID_1601&MI_02#9&375eebb1&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd}**) -| Input: Adding Gun #6: HID-compliant mouse (**device id: \\?\HID#VID_1241&PID_1111#8&198f3adc&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd}**) +| Input: Adding lightgun #1: +| Input: Adding lightgun #2: +| Input: Adding lightgun #3: HID-compliant mouse (**device id: \\\\?\\HID#VID_045E&PID_0053#7&18297dcb&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd}**) +| Input: Adding lightgun #4: HID-compliant mouse (**device id: \\\\?\\HID#IrDeviceV2&Col08#2&2818a073&0&0007#{378de44c-56ef-11d1-bc8c-00a0c91405dd}**) +| Input: Adding lightgun #5: HID-compliant mouse (**device id: \\\\?\\HID#VID_D209&PID_1602&MI_02#8&389ab7f3&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd}**) +| Input: Adding lightgun #6: HID-compliant mouse (**device id: \\\\?\\HID#VID_D209&PID_1601&MI_02#9&375eebb1&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd}**) +| Input: Adding lightgun #7: HID-compliant mouse (**device id: \\\\?\\HID#VID_1241&PID_1111#8&198f3adc&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd}**) | Skipping DirectInput for XInput compatible joystick Controller (XBOX 360 For Windows). -| Input: Adding Joy #0: ATRAK Device #1 (**device id: ATRAK Device #1**) +| Input: Adding joystick #1: ATRAK Device #1 (**device id: ATRAK Device #1**) | Skipping DirectInput for XInput compatible joystick Controller (XBOX 360 For Windows). -| Input: Adding Joy #1: ATRAK Device #2 (**device id: ATRAK Device #2**) -| Input: Adding Joy #2: XInput Player 1 (**device id: XInput Player 1**) -| Input: Adding Joy #3: XInput Player 2 (**device id: XInput Player 2**) +| Input: Adding joystick #2: ATRAK Device #2 (**device id: ATRAK Device #2**) +| Input: Adding joystick #3: XInput Player 1 (**device id: XInput Player 1**) +| Input: Adding joystick #4: XInput Player 2 (**device id: XInput Player 2**) | -Furthermore, when devices are mapped using mapdevice, you'll see that in the verbose logging too, such as: +Furthermore, when devices are reassigned using ``mapdevice`` elements in the +controller configuration file, you’ll see that in the verbose log output, too, +such as: -| Input: Remapped Gun #0: HID-compliant mouse (device id: \\?\HID#VID_D209&PID_1601&MI_02#9&375eebb1&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd}) -| Input: Remapped Gun #1: HID-compliant mouse (device id: \\?\HID#VID_D209&PID_1602&MI_02#8&389ab7f3&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd}) -| Input: Remapped Joy #0: XInput Player 1 (device id: XInput Player 1) -| Input: Remapped Joy #1: XInput Player 2 (device id: XInput Player 2) +| Input: Remapped lightgun #1: HID-compliant mouse (device id: \\\\?\\HID#VID_D209&PID_1601&MI_02#9&375eebb1&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd}) +| Input: Remapped lightgun #2: HID-compliant mouse (device id: \\\\?\\HID#VID_D209&PID_1602&MI_02#8&389ab7f3&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd}) +| Input: Remapped joystick #1: XInput Player 1 (device id: XInput Player 1) +| Input: Remapped joystick #2: XInput Player 2 (device id: XInput Player 2) | + +Note that the devices numbers in the verbose log output are zero-based, while +the device numbers shown in MAME’s user interface and set in configuration files + + +Limitations +----------- + +You can only assign stable numbers to devices if MAME receives stable, unique +device IDs from the input device provider and operating system. This is not +always the case. For example the SDL joystick provider is not capable of +providing unique IDs for many USB game controllers. + +If not all configured devices are connected when MAME starts, the devices that +are connected may not be numbered as expected. |