rawinput: modifiers (key combinations) (#813)

## Link to GitHub Issue or related Pull Request, if one exists
Fixes #635

## Description of change
Adds optional **button modifiers**, allowing a binding to require one or
more "modifier" buttons to be held before it activates.

- New "Modifiers" controller page in the overlay config to bind the
Modifier 1–4 source buttons.
- Each binding gains a 4-bit modifier_mask (Modifier 1-4). It is
persisted as an optional modifiers XML attribute on button nodes and
controller-preset entries. The attribute is optional and defaults to 0,
so existing config files and presets load unchanged and the feature is
off unless the user opts in.
- The button Edit properties popup gains a "Modifiers" dropdown to pick
which modifiers a binding requires. Doesn't apply to MIDI though.
- Input evaluation skips a binding whose required modifiers are not
held, falling through to its alternatives; velocity reporting uses the
same gated path.
- Controller-preset templates gain a "Modifiers" group for importing and
exporting.

## Testing

src/spice2x/cfg/api.cpp

@@ -3,7 +3,9 @@
 #include <cassert>
 #include <optional>
 
+#include "games/io.h"
 #include "launcher/superexit.h"
+#include "misc/eamuse.h"
 #include "rawinput/rawinput.h"
 #include "rawinput/piuio.h"
 #include "util/time.h"
@@ -62,7 +64,43 @@ std::vector<Button> GameAPI::Buttons::sortButtons(
     return sorted;
 }
 
-GameAPI::Buttons::State GameAPI::Buttons::getState(rawinput::RawInputManager *manager, Button &_button, bool check_alts) {
+namespace GameAPI::Buttons {
+    static State get_button_state(
+        rawinput::RawInputManager *manager,
+        Button &button,
+        bool check_alts,
+        bool check_modifiers);
+
+    static bool modifiers_pressed(rawinput::RawInputManager *manager, Button &button);
+}
+
+bool GameAPI::Buttons::modifiers_pressed(rawinput::RawInputManager *manager, Button &button) {
+    const auto modifier_mask = button.getModifierMask();
+    if (modifier_mask == 0) {
+        return true;
+    }
+
+    auto *modifier_buttons = games::get_buttons_modifiers(eamuse_get_game());
+    if (!modifier_buttons) {
+        return false;
+    }
+
+    for (uint8_t index = 0; index < games::ModifierButtons::Size; index++) {
+        if ((modifier_mask & (UINT8_C(1) << index)) != 0 &&
+            (index >= modifier_buttons->size() ||
+             get_button_state(manager, modifier_buttons->at(index), true, false) !=
+                 GameAPI::Buttons::BUTTON_PRESSED)) {
+            return false;
+        }
+    }
+    return true;
+}
+
+GameAPI::Buttons::State GameAPI::Buttons::get_button_state(
+        rawinput::RawInputManager *manager,
+        Button &_button,
+        bool check_alts,
+        bool check_modifiers) {
 
     // check override
     if (_button.override_enabled) {
@@ -76,6 +114,23 @@ GameAPI::Buttons::State GameAPI::Buttons::getState(rawinput::RawInputManager *ma
     std::optional<bool> window_has_focus;
     while (true) {
 
+        // skip bindings whose required modifiers are not held
+        //
+        // note that modifiers cannot process MIDI as the logic is written
+        // below, since MIDI buttons are event-based (on event, off event, etc)
+        // and cannot be correctly handled by a simple early return
+        // there is no explicit check for MIDI here, but the UI should have
+        // prevented it
+        if (check_modifiers && !modifiers_pressed(manager, *current_button)) {
+            button_count++;
+            if (!alternatives || alternatives->empty() ||
+                button_count - 1 >= alternatives->size()) {
+                return BUTTON_NOT_PRESSED;
+            }
+            current_button = &alternatives->at(button_count - 1);
+            continue;
+        }
+
         // naive behavior
         if (current_button->isNaive()) {
             GameAPI::Buttons::State state;
@@ -469,6 +524,10 @@ GameAPI::Buttons::State GameAPI::Buttons::getState(rawinput::RawInputManager *ma
     }
 }
 
+Buttons::State Buttons::getState(rawinput::RawInputManager *manager, Button &button, bool check_alts) {
+    return get_button_state(manager, button, check_alts, true);
+}
+
 Buttons::State Buttons::getState(std::unique_ptr<rawinput::RawInputManager> &manager, Button &button, bool check_alts) {
     if (manager) {
         return getState(manager.get(), button, check_alts);
@@ -484,17 +543,13 @@ static float getVelocityHelper(rawinput::RawInputManager *manager, Button &butto
         return button.override_velocity;
     }
 
-    // naive behavior
-    if (button.isNaive()) {
-        if (button.getInvert()) {
-            return (GetAsyncKeyState(button.getVKey()) & 0x8000) ? 0.f : 1.f;
-        } else {
-            return (GetAsyncKeyState(button.getVKey()) & 0x8000) ? 1.f : 0.f;
-        }
-    }
-
     // get button state
-    Buttons::State button_state = Buttons::getState(manager, button, false);
+    const auto button_state = Buttons::getState(manager, button, false);
+
+    // naive bindings report their digital state as full or zero velocity
+    if (button.isNaive()) {
+        return button_state == Buttons::BUTTON_PRESSED ? 1.f : 0.f;
+    }
 
     // check if button isn't being pressed
     if (button_state != Buttons::BUTTON_PRESSED) {

src/spice2x/cfg/button.cpp

@@ -299,7 +299,27 @@ std::string Button::getMidiNoteString() {
     return fmt::format("{}{}", note_names[index % 12], ((index / 12) - 1));
 }
 
-std::string Button::getDisplayString(rawinput::RawInputManager* manager) {
+std::string Button::getDisplayString(rawinput::RawInputManager *manager) {
+    auto binding_display = this->getBindingDisplayString(manager);
+    auto modifiers = this->getModifierMask();
+    if (binding_display.empty() || modifiers == 0) {
+        return binding_display;
+    }
+
+    std::string modifier_display;
+    for (unsigned int index = 1; modifiers != 0; index++, modifiers >>= 1) {
+        if ((modifiers & UINT8_C(1)) == 0) {
+            continue;
+        }
+        if (!modifier_display.empty()) {
+            modifier_display += "+";
+        }
+        modifier_display += fmt::format("Mod{}", index);
+    }
+    return modifier_display + "+" + binding_display;
+}
+
+std::string Button::getBindingDisplayString(rawinput::RawInputManager *manager) {
 
     // get VKey string
     auto vKey = (uint16_t) this->getVKey();

src/spice2x/cfg/button.h

@@ -49,6 +49,7 @@ private:
     std::string name;
     std::string device_identifier = "";
     unsigned short vKey = INVALID_VKEY;
+    uint8_t modifier_mask = 0;
 
     // default bindings are always naive
     unsigned short vKey_default = INVALID_VKEY;
@@ -65,6 +66,7 @@ private:
     unsigned short velocity_threshold = 0;
 
     std::string getMidiNoteString();
+    std::string getBindingDisplayString(rawinput::RawInputManager *manager);
 
 public:
     std::string getVKeyString();
@@ -111,6 +113,7 @@ public:
         device_identifier = "";
         analog_type = BAT_NONE;
         bat_threshold = 0;
+        modifier_mask = 0;
     }
 
     std::string getDisplayString(rawinput::RawInputManager* manager);
@@ -123,6 +126,14 @@ public:
         return this->name;
     }
 
+    inline uint8_t getModifierMask() const {
+        return this->modifier_mask;
+    }
+
+    inline void setModifierMask(uint8_t new_modifier_mask) {
+        this->modifier_mask = new_modifier_mask & UINT8_C(0x0F);
+    }
+
     inline const std::string &getDeviceIdentifier() const {
         return this->device_identifier;
     }

src/spice2x/cfg/config.cpp

@@ -165,6 +165,7 @@ bool Config::addGame(Game &game, bool save) {
                     int bat_threshold = 0;
                     int velocity_threshold = 0;
                     bool invert = false;
+                    unsigned int modifier_mask = 0;
                     tinyxml2::XMLError attrError = gameButtonNode->QueryIntAttribute("vkey", &vKey);
                     const char *devid = gameButtonNode->Attribute("devid");
                     gameButtonNode->QueryIntAttribute("analogtype", &analogType);
@@ -173,6 +174,7 @@ bool Config::addGame(Game &game, bool save) {
                     gameButtonNode->QueryIntAttribute("bat_threshold", &bat_threshold);
                     gameButtonNode->QueryIntAttribute("velocity_threshold", &velocity_threshold);
                     gameButtonNode->QueryBoolAttribute("invert", &invert);
+                    gameButtonNode->QueryUnsignedAttribute("modifiers", &modifier_mask);
                     if (attrError != tinyxml2::XMLError::XML_SUCCESS) {
                         gameButtonsNode->DeleteChild(gameButtonNode);
                         gameButtonNode = this->configFile.NewElement("button");
@@ -185,6 +187,7 @@ bool Config::addGame(Game &game, bool save) {
                         gameButtonNode->SetAttribute("bat_threshold", bat_threshold);
                         gameButtonNode->SetAttribute("velocity_threshold", velocity_threshold);
                         gameButtonNode->SetAttribute("invert", invert);
+                        gameButtonNode->SetAttribute("modifiers", button->getModifierMask());
                         gameButtonsNode->InsertEndChild(gameButtonNode);
                     } else {
                         button->setVKey(static_cast<unsigned short int>(vKey));
@@ -194,6 +197,7 @@ bool Config::addGame(Game &game, bool save) {
                         button->setBatThreshold(bat_threshold);
                         button->setVelocityThreshold(velocity_threshold);
                         button->setInvert(invert);
+                        button->setModifierMask(static_cast<uint8_t>(modifier_mask));
                         if (devid) {
                             button->setDeviceIdentifier(devid);
                         }
@@ -214,6 +218,7 @@ bool Config::addGame(Game &game, bool save) {
                 gameButtonNode->SetAttribute("bat_threshold", it.getBatThreshold());
                 gameButtonNode->SetAttribute("velocity_threshold", it.getVelocityThreshold());
                 gameButtonNode->SetAttribute("invert", it.getInvert());
+                gameButtonNode->SetAttribute("modifiers", it.getModifierMask());
                 gameButtonNode->SetAttribute("devid", it.getDeviceIdentifier().c_str());
                 gameButtonsNode->InsertEndChild(gameButtonNode);
             }
@@ -440,6 +445,7 @@ bool Config::addGame(Game &game, bool save) {
             gameButtonNode->SetAttribute("bat_threshold", it.getBatThreshold());
             gameButtonNode->SetAttribute("velocity_threshold", it.getVelocityThreshold());
             gameButtonNode->SetAttribute("invert", it.getInvert());
+            gameButtonNode->SetAttribute("modifiers", it.getModifierMask());
             gameButtonNode->SetAttribute("devid", it.getDeviceIdentifier().c_str());
             gameButtonsNode->InsertEndChild(gameButtonNode);
         }
@@ -552,6 +558,7 @@ bool Config::updateBinding(const Game &game, const Button &button, int alternati
                 gameButtonNode->SetAttribute("velocity_threshold", button.getVelocityThreshold());
                 gameButtonNode->SetAttribute("invert", button.getInvert());
                 gameButtonNode->SetAttribute("devid", button.getDeviceIdentifier().c_str());
+                gameButtonNode->SetAttribute("modifiers", button.getModifierMask());
                 break;
             }
         }
@@ -569,6 +576,7 @@ bool Config::updateBinding(const Game &game, const Button &button, int alternati
             gameButtonNode->SetAttribute("velocity_threshold", 0);
             gameButtonNode->SetAttribute("invert", false);
             gameButtonNode->SetAttribute("devid", "");
+            gameButtonNode->SetAttribute("modifiers", 0);
             gameButtonsNode->InsertEndChild(gameButtonNode);
         }
     }
@@ -964,6 +972,7 @@ std::vector<Button> Config::getButtons(const std::string &gameName) {
                 int bat_threshold = 0;
                 int velocity_threshold = 0;
                 bool invert = false;
+                unsigned int modifier_mask = 0;
                 gameButtonNode->QueryIntAttribute("vkey", &vKey);
                 gameButtonNode->QueryIntAttribute("analogtype", &analogType);
                 gameButtonNode->QueryDoubleAttribute("debounce_up", &debounce_up);
@@ -971,6 +980,7 @@ std::vector<Button> Config::getButtons(const std::string &gameName) {
                 gameButtonNode->QueryIntAttribute("bat_threshold", &bat_threshold);
                 gameButtonNode->QueryIntAttribute("velocity_threshold", &velocity_threshold);
                 gameButtonNode->QueryBoolAttribute("invert", &invert);
+                gameButtonNode->QueryUnsignedAttribute("modifiers", &modifier_mask);
                 const char *devid = gameButtonNode->Attribute("devid");
 
                 // find alternative
@@ -986,6 +996,7 @@ std::vector<Button> Config::getButtons(const std::string &gameName) {
                         alt.setBatThreshold(bat_threshold);
                         alt.setVelocityThreshold(velocity_threshold);
                         alt.setInvert(invert);
+                        alt.setModifierMask(static_cast<uint8_t>(modifier_mask));
                         if (devid) {
                             alt.setDeviceIdentifier(std::string(devid));
                         }
@@ -1005,6 +1016,7 @@ std::vector<Button> Config::getButtons(const std::string &gameName) {
                     button.setBatThreshold(bat_threshold);
                     button.setVelocityThreshold(velocity_threshold);
                     button.setInvert(invert);
+                    button.setModifierMask(static_cast<uint8_t>(modifier_mask));
                     if (devid) {
                         button.setDeviceIdentifier(devid);
                     }

src/spice2x/cfg/controller_presets.cpp

@@ -26,6 +26,7 @@ namespace overlay::windows {
         el->SetAttribute("debounce_down", entry.debounce_down);
         el->SetAttribute("bat_threshold", entry.bat_threshold);
         el->SetAttribute("velocity_threshold", entry.velocity_threshold);
+        el->SetAttribute("modifiers", entry.modifier_mask);
         parent->InsertEndChild(el);
     }
 
@@ -54,6 +55,10 @@ namespace overlay::windows {
         el->QueryIntAttribute("bat_threshold", &bat);
         entry.bat_threshold = bat;
 
+        unsigned int modifier_mask = 0;
+        el->QueryUnsignedAttribute("modifiers", &modifier_mask);
+        entry.modifier_mask = static_cast<uint8_t>(modifier_mask & UINT8_C(0x0F));
+
         return entry;
     }
 
@@ -160,6 +165,28 @@ namespace overlay::windows {
                 }
             }
 
+            // modifier buttons
+            auto *mod_el = tmpl_el->FirstChildElement("modifier_buttons");
+            if (mod_el) {
+                auto *btn_el = mod_el->FirstChildElement("button");
+                while (btn_el) {
+                    const char *btn_name = btn_el->Attribute("name");
+                    std::string btn_name_str = btn_name ? btn_name : "";
+
+                    TemplateButtonBinding *binding = nullptr;
+                    for (auto &b : tmpl.modifier_buttons) {
+                        if (b.name == btn_name_str) { binding = &b; break; }
+                    }
+                    if (!binding) {
+                        tmpl.modifier_buttons.push_back(
+                            {btn_name_str, read_button_entry(btn_el), {}});
+                    } else {
+                        binding->alternatives.push_back(read_button_entry(btn_el));
+                    }
+                    btn_el = btn_el->NextSiblingElement("button");
+                }
+            }
+
             // keypad buttons
             auto *kp_el = tmpl_el->FirstChildElement("keypad_buttons");
             if (kp_el) {
@@ -244,6 +271,7 @@ namespace overlay::windows {
     bool save_user_template(
         const ControllerTemplate &tmpl,
         const bool save_buttons,
+        const bool save_modifiers,
         const bool save_keypads,
         const bool save_analogs,
         const bool save_lights) {
@@ -300,6 +328,24 @@ namespace overlay::windows {
         }
         tmpl_el->InsertEndChild(buttons_el);
 
+        // modifier buttons - skip unbound entries
+        if (!tmpl.modifier_buttons.empty()) {
+            auto *mod_el = doc.NewElement("modifier_buttons");
+            if (save_modifiers) {
+                for (auto &btn : tmpl.modifier_buttons) {
+                    if (!btn.primary.is_unbound()) {
+                        write_button_entry(doc, mod_el, btn.name, btn.primary);
+                    }
+                    for (auto &alt : btn.alternatives) {
+                        if (!alt.is_unbound()) {
+                            write_button_entry(doc, mod_el, btn.name, alt);
+                        }
+                    }
+                }
+            }
+            tmpl_el->InsertEndChild(mod_el);
+        }
+
         // keypad buttons — skip unbound entries
         if (!tmpl.keypad_buttons.empty()) {
             auto *kp_el = doc.NewElement("keypad_buttons");