summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source
diff options
context:
space:
mode:
author Vas Crabb <vas@vastheman.com>2023-02-18 06:18:45 +1100
committer Vas Crabb <vas@vastheman.com>2023-02-18 06:18:45 +1100
commitd4589e0b29d6085072ff635d87c3d95c21813a58 (patch)
treec0d3283ecdd99bd380fc155f4e09b7f4bd573116 /docs/source
parent20d7135179ffe9959f4bfb759a0e5735b7aaaf15 (diff)
Input refactoring:
osd/modules/input, emu/inpttype.cpp: Made most default joystick assignments supplied by input modules. Input modules take available controls into consideration when generating default assignments. emu/inpttype.ipp: Added a separate "Back" UI input separate from Cancel. You may want an easier to hit combination for moving to the previous menu than for exiting or cancelling input. They both default to Escape. emu/inpttype.ipp: Added a UI Help control. Currently only used by analog inputs menu emu/inpttype.h: Moved I/O port field type enum to its own header and sorted UI controls so they appear in a more logical order. ui: Don't use UI Select to restore defaults - people should be getting used to the UI Clear input by now. UI Select cycles multi-value items instead. ui/inputmap.cpp: Don't use immediate cancel to cycle between clearing and restoring default assignment (use UI Clear instead). osd: Reduced the number of files needing to include the dreaded emu.h. Got some implementation out of headers.
Diffstat (limited to 'docs/source')
-rw-r--r--docs/source/advanced/bgfx.rst14
-rw-r--r--docs/source/advanced/ctrlr_config.rst4
-rw-r--r--docs/source/plugins/autofire.rst8
-rw-r--r--docs/source/plugins/inputmacro.rst6
-rw-r--r--docs/source/techspecs/luareference.rst4
-rw-r--r--docs/source/usingmame/mamemenus.rst49
-rw-r--r--docs/source/usingmame/ui.rst40
7 files changed, 66 insertions, 59 deletions
diff --git a/docs/source/advanced/bgfx.rst b/docs/source/advanced/bgfx.rst
index 388ea66c987..bb6e4205fa3 100644
--- a/docs/source/advanced/bgfx.rst
+++ b/docs/source/advanced/bgfx.rst
@@ -155,7 +155,7 @@ bgfx_screen_chains
we want to give each player their own full screen display (two physical
monitors) along with the LCD, we’ll go with::
- -numscreens 2 -view0 "Player 1" -view1 "Player 2" -video bgfx -bgfx_screen_chains hlsl,unfiltered,unfiltered:hlsl,unfiltered,unfiltered
+ -numscreens 2 -view0 "Player 1" -view1 "Player 2" -video bgfx -bgfx_screen_chains hlsl,unfiltered:hlsl,unfiltered
This sets up the view for each display respectively, keeping HLSL effect on
the CRT for each window (physical display) while going unfiltered for the
@@ -164,8 +164,7 @@ bgfx_screen_chains
If using only one window (one display), keep in mind the game still has
three screens, so we would use::
- bgfx_screen_chains hlsl,unfiltered,unfiltered``
-
+ bgfx_screen_chains hlsl,unfiltered,unfiltered
Note that the commas are on the outside edges, and any colons are in the
middle.
@@ -177,9 +176,6 @@ bgfx_shadow_mask
Tweaking BGFX HLSL Settings inside MAME
---------------------------------------
-*Warning: Currently BGFX HLSL settings are not saved or loaded from any
-configuration files. This is expected to change in the future.*
-
Start by loading MAME with the game of your choice (e.g. **mame pacman**).
The tilde key (**~**) brings up the on-screen display options. Use up and down
@@ -189,6 +185,12 @@ these settings.
Note that settings are individually changeable on a per-screen basis.
+BGFX slider settings are saved per-system in CFG files. If the
+``bgfx_screen_chains`` setting has been set (either in an INI file or on the
+command line), it will set the initial effects. If the ``bgfx_screen_chains``
+setting has not been set, MAME will use the effects you chose the last time you
+ran the system.
+
Using the included pillarbox filters
------------------------------------
diff --git a/docs/source/advanced/ctrlr_config.rst b/docs/source/advanced/ctrlr_config.rst
index 7c4f5073638..5973832d2ab 100644
--- a/docs/source/advanced/ctrlr_config.rst
+++ b/docs/source/advanced/ctrlr_config.rst
@@ -147,7 +147,7 @@ override the default control assignments for emulated inputs by type:
.. code-block:: XML
<input>
- <port type="UI_CONFIGURE">
+ <port type="UI_MENU">
<newseq type="standard">KEYCODE_TAB OR KEYCODE_1 KEYCODE_5</newseq>
</port>
<port type="UI_CANCEL">
@@ -170,7 +170,7 @@ override the default control assignments for emulated inputs by type:
This sets the following default input assignments:
-Config Menu (User Interface)
+Show/Hide Menu (User Interface)
Tab key, or 1 and 2 keys pressed simultaneously
UI Cancel (User Interface)
Escape key, or 2 and 6 keys pressed simultaneously
diff --git a/docs/source/plugins/autofire.rst b/docs/source/plugins/autofire.rst
index 3b22a9021e7..805b5700151 100644
--- a/docs/source/plugins/autofire.rst
+++ b/docs/source/plugins/autofire.rst
@@ -66,10 +66,10 @@ Experiment with different values to get the best effect.
When adding a new autofire button, there is a **Cancel** option that changes to
**Create** after you set the input and hotkey. Select **Create** to finish
creating the autofire button and return to the list of autofire buttons. The
-new autofire button will be added at the end of the list. Press the UI Cancel
-key (Escape/Esc on the keyboard by default), or select **Cancel** before setting
-the input/hotkey, to return to the previous menu without creating the new
-autofire button.
+new autofire button will be added at the end of the list. Press the UI Back key
+(Escape/Esc on the keyboard by default), or select **Cancel** before setting the
+input/hotkey, to return to the previous menu without creating the new autofire
+button.
When modifying an existing autofire button, select **Done** or press the UI
Cancel key to return to the list of autofire buttons. Changes take effect
diff --git a/docs/source/plugins/inputmacro.rst b/docs/source/plugins/inputmacro.rst
index dd66fef205e..1198315fd11 100644
--- a/docs/source/plugins/inputmacro.rst
+++ b/docs/source/plugins/inputmacro.rst
@@ -55,7 +55,7 @@ whole:
descriptive. Press the UI Select key (Return/Enter on the keyboard or the
first button on the first joystick by default) to edit the current name, or
press the UI Clear key to type a new name. Press the UI Select key before
- moving to another menu item to save the new name; press the UI Cancel key
+ moving to another menu item to save the new name; press the UI Back key
(Escape/Esc on the keyboard by default) to change discard the new name.
* Select **Activation combination** to set the control (or combination of
controls) you want to use to activate the macro. Keep in mind that regular
@@ -112,11 +112,11 @@ When creating a new macro, there is a **Cancel** option that changes to
**Create** after you set the activating sequence and the first input for the
initially created step. Select **Create** to finish creating the macro and
return to the list of input macros. The new macro will be added at the end of
-the list. Press the UI Cancel key, or select **Cancel** before setting the
+the list. Press the UI Back key, or select **Cancel** before setting the
activation sequence/input, to return to the previous menu without creating the
new macro.
-When editing an existing macro, select **Done** or press the UI Cancel key to
+When editing an existing macro, select **Done** or press the UI Back key to
return to the list of input macros. Changes take effect immediately.
diff --git a/docs/source/techspecs/luareference.rst b/docs/source/techspecs/luareference.rst
index dd63ab62de2..8ca4e984517 100644
--- a/docs/source/techspecs/luareference.rst
+++ b/docs/source/techspecs/luareference.rst
@@ -2549,6 +2549,10 @@ manager.machine.uiinput
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
diff --git a/docs/source/usingmame/mamemenus.rst b/docs/source/usingmame/mamemenus.rst
index a7010a082fe..672a9c7796a 100644
--- a/docs/source/usingmame/mamemenus.rst
+++ b/docs/source/usingmame/mamemenus.rst
@@ -12,17 +12,18 @@ Introduction
------------
To show the :ref:`main menu <menus-main>` while running an emulated system in
-MAME, press the **Config Menu** key or button (**Tab** by default). If the
-emulated system has keyboard inputs, you may need to press the **UI Toggle** key
-or button (**Scroll Lock**, or **Forward Delete** on macOS, by default) to
-enable user interface controls first. You can dismiss a menu by pressing the
-**UI Cancel** key or button (**Escape** by default). Dismissing a menu will
-return to its parent menu, or to the running system in the case of the main
-menu.
-
-You can hide a menu and return to the running system by pressing the **Config
-Menu** key or button. Pressing the **Config Menu** key or button again will
-jump back to the same menu. This is useful when testing changes to settings.
+MAME, press the **Show/Hide Menu** key or button (**Tab** by default). If the
+emulated system has keyboard inputs, you may need to press the
+**Toggle UI Controls** key or button (**Scroll Lock**, or **Forward Delete** on
+macOS, by default) to enable user interface controls first. You can dismiss a
+menu by pressing the **UI Back** key or button (**Escape** by default).
+Dismissing a menu will return to its parent menu, or to the running system in
+the case of the main menu.
+
+You can hide a menu and return to the running system by pressing the
+**Show/Hide Menu** key or button. Pressing the **Show/Hide Menu** key or button
+again will jump back to the same menu. This is useful when testing changes to
+settings.
Emulated system inputs are ignored while menus are displayed. You can still
pause or resume the running system while most menus are displayed by pressing
@@ -43,17 +44,17 @@ For more information on navigating menus, :ref:`see the relevant section
Main menu
---------
-The main menu is shown when you press the **Config Menu** key or button while
+The main menu is shown when you press the **Show/Hide Menu** key or button while
running an emulated system or while the system information screen is displayed.
It provides access to menus used to change settings, control various features,
and show information about the running system and MAME itself.
-If you press the **Config Menu** key or button to show the main menu while the
-system information screen is displayed, the emulated system will not start until
-the main menu is dismissed (either by selecting **Start System**, pressing the
-**UI Cancel** key or button, or pressing the **Config Menu** key or button).
-This can be useful for mounting media images or changing DIP switches and
-machine configuration settings before the emulated system starts.
+If you press the **Show/Hide Menu** key or button to show the main menu while
+the system information screen is displayed, the emulated system will not start
+until the main menu is dismissed (either by selecting **Start System**, pressing
+the **UI Back** key or button, or pressing the **Show/Hide Menu** key or
+button). This can be useful for mounting media images or changing DIP switches
+and machine configuration settings before the emulated system starts.
Input Settings
Shows the :ref:`Input Settings <menus-inputopts>` menu, where you can assign
@@ -127,13 +128,13 @@ Cheat
Plugin Options
Shows the Plugin Options menu, where you can access settings for enabled
plugins. This item is not shown if no plugins are enabled, or if the main
- menu is shown before the emulated system starts (by pressing the Config Menu
- key/button while the system information screen is displayed).
+ menu is shown before the emulated system starts (by pressing the Show/Hide
+ Menu key/button while the system information screen is displayed).
External DAT View
Shows the info viewer, which displays information loaded from various
external support files. This item is not shown if the :ref:`data plugin
<plugins-data>` is not enabled, or if the main menu is shown before the
- emulated system starts (by pressing the Config Menu key/button while the
+ emulated system starts (by pressing the Show/Hide Menu key/button while the
system information screen is displayed).
Add To Favorites/Remove From Favorites
Adds the running system to the favourites list, or removes it if it’s
@@ -144,13 +145,13 @@ About MAME
Select New System
Shows the system selection menu, where you can select a system to start a
new emulation session. This item is not shown if the main menu is shown
- before the emulated system starts (by pressing the Config Menu key/button
+ before the emulated system starts (by pressing the Show/Hide Menu key/button
while the system information screen is displayed).
Close Menu/Start System
Closes the main menu, returning control of the running system. Shows
**Start System** if the main menu is shown before the emulated system
- starts (by pressing the Config Menu key/button while the system information
- screen is displayed).
+ starts (by pressing the Show/Hide Menu key/button while the system
+ information screen is displayed).
.. _menus-inputopts:
diff --git a/docs/source/usingmame/ui.rst b/docs/source/usingmame/ui.rst
index f7ca2a41aa1..60bb55618a2 100644
--- a/docs/source/usingmame/ui.rst
+++ b/docs/source/usingmame/ui.rst
@@ -20,13 +20,13 @@ The default settings for the most important controls to know when running an
emulated system, and the settings they correspond to in case you want to change
them, are as follows:
-Scroll Lock, or Forward Delete on macOS (UI Toggle)
+Scroll Lock, or Forward Delete on macOS (Toggle UI Controls)
For emulated systems with keyboard inputs, enable or disable UI controls.
(MAME starts with UI controls disabled for systems with keyboard inputs
unless the :ref:`ui_active option <mame-commandline-uiactive>` is on.)
-Tab (Config Menu)
+Tab (Show/Hide Menu)
Show or hide the menu during emulation.
-Escape (UI Cancel)
+Escape (UI Back and UI Cancel)
Return to the system selection menu, or exit if MAME was started with a
system specified (from the command line or using an
:ref:`external front-end <frontends>`).
@@ -60,7 +60,7 @@ Return/Enter keypad Enter (UI Select)
Select the highlighted menu item.
Forward Delete, or Fn+Delete on some compact keyboards (UI Clear)
Clear setting or reset to default value.
-Escape (UI Cancel)
+Escape (UI Back and UI Cancel)
Clear the search if searching the menu, otherwise close the menu, returning
to the previous menu, or returning to the emulated system in the case of the
main menu (there’s usually an item at the bottom of the menu for the same
@@ -92,18 +92,24 @@ most important UI controls have joystick assignments by default:
* Move the first joystick left or right in the X axis to adjust settings.
* Press the first button on the first joystick to select the highlighted menu
item.
+* If the first joystick has at least three buttons, press the second button on
+ the first joystick to close the menu, returning to the previous menu, or
+ returning to the emulated system in the case of the main menu (there’s usually
+ an item at the bottom of the menu for the same purpose).
-For gamepad-style controllers, the left analog thumb stick usually controls UI
-navigation. You may find it convenient to assign directional pad controls to UI
-navigation in addition to or in place of the left thumb stick.
+For gamepad-style controllers, the left analog thumb stick and directional pad
+usually control UI navigation. Depending on the controller, the right analog
+thumb stick, triggers and additional buttons may automatically be assigned to UI
+inputs. Check the **User Interface** input assignments menu to see how controls
+are assigned.
If you want to be able to use MAME with a game controller without needing a
keyboard, you’ll need to assign joystick buttons (or combinations of buttons) to
these controls as well:
-* **Config Menu** to show or dismiss the menu during emulation
-* **UI Cancel** to close menus, return to the system selection menu, or exit
- MAME
+* **Show/Hide Menu** to show or hide the menu during emulation
+* **UI Back** to close menus
+* **UI Cancel** to return to the system selection menu or exit MAME
* **UI Clear** isn’t essential for basic emulation, but it’s used to clear or
reset some settings to defaults
* **UI Home**, **UI End**, **UI Page Up**, **UI Page Down**, **UI Previous
@@ -138,8 +144,8 @@ pointing device:
* Click toolbar items to select them, or hover over them to see a description.
If you have enough additional mouse buttons, you may want to assign button
-combinations to the **Config Menu**, **Pause** and/or **UI Cancel** inputs to
-make it possible to use MAME without a keyboard.
+combinations to the **Show/Hide Menu**, **Pause**, **UI Back** and/or
+**UI Cancel** inputs to make it possible to use MAME without a keyboard.
.. _ui-inptcfg:
@@ -220,10 +226,7 @@ input or a combination of inputs for a logical **and** operation:
* Press a key or button or move an analog control twice to add a **not** item to
the **and** operation. Pressing the same key or button or moving the same
analog control additional times toggles the **not** on and off.
-* Pressing **UI Cancel** (**Escape** by default) *before* activating any other
- controls clears the setting or restores the default assignment.
-* Press **UI Cancel** *after* activating another control to leave the setting
- unchanged.
+* Press **UI Cancel** (**Escape** by default) to leave the setting unchanged.
* The new setting is shown below the menu. Wait one second after activating an
input to accept the new setting.
@@ -344,10 +347,7 @@ When you select an axis setting, MAME will wait for you to enter an input:
direction of the control on or off.
* When appending to a setting, move an analog control other than the last
assigned control or press a key or button to add an **or** operation.
-* Pressing **UI Cancel** (**Escape** by default) *before* activating any other
- controls clears the setting or restores the default assignment.
-* Pressing **UI Cancel** *after* activating another control leaves the setting
- unchanged.
+* Pressing **UI Cancel** (**Escape** by default) leaves the setting unchanged.
* The new setting is shown below the menu. Wait one second after moving an
analog control to accept the new setting.