updated doc (adapting refresh not available for macOS)

added event and hotkey for adapting refresh rate
fixed endless loop in global hotkeys

docs/index.html

@@ -1377,6 +1377,13 @@
       <td>Alt + Enter</td>
       <td>Cmd + Enter</td>
     </tr>
+    <tr>
+      <td>Toggle adapting display refresh rate to game frame rate
+      </br>
+      Note: Not available for macOS.</td>
+      <td>Alt + r</td>
+      <td>Cmd + r</td>
+    </tr>
     <tr>
       <td><i>Decrease</i> overscan in fullscreen mode</td>
       <td>Shift + PageDown</td>
@@ -2221,7 +2228,8 @@
   <tr>
     <td><pre>-tia.fs_refresh &lt;1|0&gt;</pre></td>
     <td>While in fullscreen mode, adapt the display's refresh rate to the game's frame rate
-      to minimize judder.</td>
+      to minimize judder.</br>
+      Note: Not available for macOS.</td>
   </tr>
 
   <tr>
@@ -2954,7 +2962,8 @@
           <tr><td>Fullscreen</td><td>Self-explanatory - Note that colors may slightly change.
                   This depends on the OS and renderer used.</td><td>-fullscreen</td></tr>
           <tr><td>Stretch</td><td>In fullscreen mode, completely fill screen with the TIA image.</td><td>-tia.fs_stretch</td></tr>
-          <tr><td>Adapt display...</td><td>In fullscreen mode, adapt the display's refresh rate to the game's frame rate to minimize judder.</td><td>-tia.fs_refresh</td></tr>
+          <tr><td>Adapt display...</td><td>In fullscreen mode, adapt the display's refresh rate to the game's frame rate to minimize judder.
+                  </br>Note: Not available for macOS.</td><td>-tia.fs_refresh</td></tr>
           <tr><td>Overscan</td><td>In fullscreen mode, add overscan to the TIA image</td><td>-tia.fs_overscan</td></tr>
           <tr><td>V-Size adjust</td><td>Adjust height of the TIA image</td><td>-tia.vsizeadjust</td></tr>
         </table>

src/common/PKeyboardHandler.cxx

@@ -467,6 +467,7 @@ PhysicalKeyboardHandler::EventMappingArray PhysicalKeyboardHandler::DefaultCommo
   {Event::SoundToggle,              KBDK_RIGHTBRACKET, KBDM_CTRL},
 
   {Event::ToggleFullScreen,         KBDK_RETURN, MOD3},
+  {Event::ToggleAdaptRefresh,       KBDK_R, MOD3},
   {Event::OverscanDecrease,         KBDK_PAGEDOWN, KBDM_SHIFT},
   {Event::OverscanIncrease,         KBDK_PAGEUP, KBDM_SHIFT},
   //{Event::VidmodeStd,               KBDK_1, MOD3},

src/emucore/Event.hxx

@@ -123,6 +123,7 @@ class Event
       ToggleFrameStats, ToggleSAPortOrder, ExitGame,
       // add new events from here to avoid that user remapped events get overwritten
       SettingDecrease, SettingIncrease, PreviousSetting, NextSetting,
+      ToggleAdaptRefresh,
 
       LastType
     };

src/emucore/EventHandler.cxx

@@ -350,17 +350,25 @@ AdjustFunction EventHandler::cycleAdjustSetting(int direction)
     myOSystem.settings().getString("palette") == PaletteHandler::SETTING_CUSTOM;
   const bool isCustomFilter =
     myOSystem.settings().getInt("tv.filter") == int(NTSCFilter::Preset::CUSTOM);
+  bool repeat;
 
   do
   {
     myAdjustSetting =
       AdjustSetting(BSPF::clampw(int(myAdjustSetting) + direction, 0, int(AdjustSetting::MAX_ADJ)));
     // skip currently non-relevant adjustments
-  } while((myAdjustSetting == AdjustSetting::OVERSCAN && !isFullScreen)
+    repeat = (myAdjustSetting == AdjustSetting::OVERSCAN && !isFullScreen)
+  #ifdef ADAPTABLE_REFRESH_SUPPORT
+      || (myAdjustSetting == AdjustSetting::ADAPT_REFRESH && !isFullScreen)
+  #endif
       || (myAdjustSetting == AdjustSetting::PALETTE_PHASE && !isCustomPalette)
       || (myAdjustSetting >= AdjustSetting::NTSC_SHARPNESS
           && myAdjustSetting <= AdjustSetting::NTSC_BLEEDING
-              && !isCustomFilter));
+          && !isCustomFilter);
+    // avoid endless loop
+    if(repeat && !direction)
+      direction = 1;
+  } while(repeat);
 
   return getAdjustSetting(myAdjustSetting);
 }
@@ -376,6 +384,9 @@ AdjustFunction EventHandler::getAdjustSetting(AdjustSetting setting)
     std::bind(&Sound::adjustVolume, &myOSystem.sound(), _1),
     std::bind(&FrameBuffer::selectVidMode, &myOSystem.frameBuffer(), _1),
     std::bind(&FrameBuffer::toggleFullscreen, &myOSystem.frameBuffer(), _1),
+  #ifdef ADAPTABLE_REFRESH_SUPPORT
+    std::bind(&FrameBuffer::toggleAdaptRefresh, &myOSystem.frameBuffer(), _1),
+  #endif
     std::bind(&FrameBuffer::changeOverscan, &myOSystem.frameBuffer(), _1),
     std::bind(&Console::selectFormat, &myOSystem.console(), _1),
     std::bind(&Console::changeVerticalCenter, &myOSystem.console(), _1),
@@ -658,6 +669,17 @@ void EventHandler::handleEvent(Event::Type event, Int32 value, bool repeated)
       }
       return;
 
+  #ifdef ADAPTABLE_REFRESH_SUPPORT
+    case Event::ToggleAdaptRefresh:
+      if(pressed && !repeated)
+      {
+        myOSystem.frameBuffer().toggleAdaptRefresh();
+        myAdjustSetting = AdjustSetting::ADAPT_REFRESH;
+        myAdjustActive = true;
+      }
+      return;
+  #endif
+
     case Event::OverscanDecrease:
       if(pressed)
       {
@@ -2218,6 +2240,9 @@ EventHandler::EmulActionList EventHandler::ourEmulActionList = { {
   { Event::KeyboardOnePound,        "P1 Keyboard #",                         "" },
   // Video
   { Event::ToggleFullScreen,        "Toggle fullscreen",                     "" },
+#ifdef ADAPTABLE_REFRESH_SUPPORT
+  { Event::ToggleAdaptRefresh,      "Toggle fullscreen refresh rate adapt",  "" },
+#endif
   { Event::OverscanDecrease,        "Decrease overscan in fullscreen mode",  "" },
   { Event::OverscanIncrease,        "Increase overscan in fullscreen mode",  "" },
   { Event::VidmodeDecrease,         "Previous zoom level",                   "" },
@@ -2361,7 +2386,7 @@ const Event::EventSet EventHandler::MiscEvents = {
 const Event::EventSet EventHandler::AudioVideoEvents = {
   Event::VolumeDecrease, Event::VolumeIncrease, Event::SoundToggle,
   Event::VidmodeDecrease, Event::VidmodeIncrease,
-  Event::ToggleFullScreen,
+  Event::ToggleFullScreen, Event::ToggleAdaptRefresh,
   Event::OverscanDecrease, Event::OverscanIncrease,
   Event::FormatDecrease, Event::FormatIncrease,
   Event::VCenterDecrease, Event::VCenterIncrease,

src/emucore/EventHandler.hxx

@@ -398,6 +398,9 @@ class EventHandler
       VOLUME,
       ZOOM,
       FULLSCREEN,
+    #ifdef ADAPTABLE_REFRESH_SUPPORT
+      ADAPT_REFRESH,
+    #endif
       OVERSCAN,
       TVFORMAT,
       VCENTER,
@@ -517,7 +520,12 @@ class EventHandler
     #else
       PNG_SIZE             = 0,
     #endif
-      EMUL_ACTIONLIST_SIZE = 156 + PNG_SIZE + COMBO_SIZE,
+    #ifdef ADAPTABLE_REFRESH_SUPPORT
+      REFRESH_SIZE         = 1,
+    #else
+      REFRESH_SIZE         = 0,
+    #endif
+      EMUL_ACTIONLIST_SIZE = 156 + PNG_SIZE + COMBO_SIZE + REFRESH_SIZE,
       MENU_ACTIONLIST_SIZE = 18
     ;
 

src/emucore/FrameBuffer.cxx

@@ -1008,6 +1008,35 @@ void FrameBuffer::toggleFullscreen(bool toggle)
   }
 }
 
+#ifdef ADAPTABLE_REFRESH_SUPPORT
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+void FrameBuffer::toggleAdaptRefresh(bool toggle)
+{
+  bool isAdaptRefresh = myOSystem.settings().getInt("tia.fs_refresh");
+
+  if(toggle)
+    isAdaptRefresh = !isAdaptRefresh;
+
+  if(myBufferType == BufferType::Emulator)
+  {
+    if(toggle)
+    {
+      myOSystem.settings().setValue("tia.fs_refresh", isAdaptRefresh);
+      // issue a complete framebuffer re-initialization
+      myOSystem.createFrameBuffer();
+    }
+
+    ostringstream msg;
+
+    msg << "Adapt refresh rate ";
+    msg << (isAdaptRefresh ? "enabled" : "disabled");
+    msg << " (" << refreshRate() << " Hz)";
+
+    showMessage(msg.str());
+  }
+}
+#endif
+
 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 void FrameBuffer::changeOverscan(int direction)
 {

src/emucore/FrameBuffer.hxx

@@ -269,6 +269,13 @@ class FrameBuffer
     */
     void toggleFullscreen(bool toggle = true);
 
+  #ifdef ADAPTABLE_REFRESH_SUPPORT
+    /**
+      Toggles between adapt fullscreen refresh rate on and off.
+    */
+    void FrameBuffer::toggleAdaptRefresh(bool toggle = true);
+  #endif
+
     /**
       Changes the fullscreen overscan.