Add a new in-app API function ShowReplayUI to raise the UI window

* This is not guaranteed to work, e.g. on windows where for good reason
  background windows can't necessarily raise themselves.

docs/in_application_api.rst

@@ -1,7 +1,7 @@
 In-application API
 ==================
 
-Reference for RenderDoc in-application API version 1.4.2. This API is not necessary to use RenderDoc by default, but if you would like more control or custom triggering of captures this API can provide the mechanism to do so.
+Reference for RenderDoc in-application API version 1.5.0. This API is not necessary to use RenderDoc by default, but if you would like more control or custom triggering of captures this API can provide the mechanism to do so.
 
 Make sure to use a matching API header for your build - if you use a newer header, the API version may not be available. All RenderDoc builds supporting this API ship the header in their root directory.
 
@@ -364,6 +364,18 @@ The path follows the template set in :cpp:func:`SetCaptureFilePathTemplate` so i
     :param const char* cmdline: is an optional UTF-8 null-terminated string to be appended to the command line, e.g. a capture filename. If this parameter is NULL, the command line will be unmodified.
     :return: If the UI was successfully launched, this function will return the PID of the new process. Otherwise it will return ``0``.
 
+.. cpp:function:: uint32_t ShowReplayUI()
+
+    This function request that the currently connected replay UI raise its window to the top. This is only possible if an instance of the replay UI is currently connected, otherwise this function does nothing. This can be used in conjunction with IsTargetControlConnected and LaunchReplayUI to intelligently handle showing the UI after making a capture.
+
+    Given OS differences it is not guaranteed that the UI will be successfully raised even if the request is passed on. On some OSs it may only be highlighted or otherwise indicated to the user.
+
+    :return: If the request to be shown was passed onto the UI successfully this function will return ``1``. If there is no UI connected currently or some other error occurred it will return ``0``.
+
+.. note::
+
+    Added in API version 1.5.0
+
 .. cpp:function:: void SetActiveWindow(RENDERDOC_DevicePointer device, RENDERDOC_WindowHandle wndHandle)
 
     This function will explicitly set which window is considered active. The active window is the one that will be captured when the keybind to trigger a capture is pressed.
@@ -443,6 +455,10 @@ The path follows the template set in :cpp:func:`SetCaptureFilePathTemplate` so i
 
     There will be undefined results if there is not an active frame capture for the device/window combination.
 
+.. note::
+
+    Added in API version 1.4.0
+
 .. cpp:function:: void TriggerMultiFrameCapture(uint32_t numFrames)
 
     This function will trigger multiple sequential frame captures as if the user had pressed one of the capture hotkeys before each frame. The captures will be taken from the next frames presented to whichever window is considered current.
@@ -451,9 +467,18 @@ The path follows the template set in :cpp:func:`SetCaptureFilePathTemplate` so i
 
     :param uint32_t numFrames: the number of frames to capture, as an unsigned integer.
 
+.. note::
+
+    Added in API version 1.1.0
+
 .. cpp:function:: void SetCaptureFileComments(const char *filePath, const char *comments)
 
     This function adds an arbitrary comments field to an existing capture on disk, which will then be displayed in the UI to anyone opening the capture.
 
     :param const char* filePath: specifies the path to the capture file to set comments in, as UTF-8 null-terminated string. If this path is ``NULL`` or an empty string, the most recent capture file that has been created will be used.
     :param const char* comments: specifies the comments to set in the capture file, as UTF-8 null-terminated string.
+    
+.. note::
+
+    Added in API version 1.2.0
+

qrenderdoc/Code/Interface/QRDInterface.h

@@ -187,6 +187,12 @@ See the documentation for :meth:`RegisterShortcut` for what these shortcuts are
 )");
   virtual void UnregisterShortcut(const rdcstr &shortcut, QWidget *widget) = 0;
 
+  DOCUMENT(R"(Attempts to bring the main window to the front to the user's focus.
+
+This may not be possible on all OSs, so the function is not guaranteed to succeed.
+)");
+  virtual void BringToFront() = 0;
+
 protected:
   IMainWindow() = default;
   ~IMainWindow() = default;

qrenderdoc/Windows/Dialogs/LiveCapture.cpp

@@ -1390,6 +1390,11 @@ void LiveCapture::connectionThreadEntry()
       uint32_t windows = msg.capturableWindowCount;
       GUIInvoke::call(this, [this, windows]() { ui->cycleActiveWindow->setEnabled(windows > 1); });
     }
+
+    if(msg.type == TargetControlMessageType::RequestShow)
+    {
+      GUIInvoke::call(this, [this]() { m_Main->BringToFront(); });
+    }
   }
 
   if(conn)

qrenderdoc/Windows/MainWindow.cpp

@@ -1642,6 +1642,15 @@ ToolWindowManager::AreaReference MainWindow::leftToolArea()
   return ToolWindowManager::AreaReference(ToolWindowManager::LastUsedArea);
 }
 
+void MainWindow::BringToFront()
+{
+  // un-minimise if necessary
+  setWindowState(windowState() & ~Qt::WindowMinimized);
+  show();
+  raise();
+  activateWindow();
+}
+
 void MainWindow::LoadInitialLayout()
 {
   bool loaded = LoadLayout(0);

qrenderdoc/Windows/MainWindow.h

@@ -82,6 +82,8 @@ public:
   QWidget *Widget() override { return this; }
   void RegisterShortcut(const rdcstr &shortcut, QWidget *widget, ShortcutCallback callback) override;
   void UnregisterShortcut(const rdcstr &shortcut, QWidget *widget) override;
+  void BringToFront() override;
+
   // ICaptureViewer
   void OnCaptureLoaded() override;
   void OnCaptureClosed() override;

renderdoc/api/app/renderdoc_app.h

@@ -525,6 +525,15 @@ typedef uint32_t(RENDERDOC_CC *pRENDERDOC_EndFrameCapture)(RENDERDOC_DevicePoint
 typedef uint32_t(RENDERDOC_CC *pRENDERDOC_DiscardFrameCapture)(RENDERDOC_DevicePointer device,
                                                                RENDERDOC_WindowHandle wndHandle);
 
+// Requests that the replay UI show itself (if hidden or not the current top window). This can be
+// used in conjunction with IsTargetControlConnected and LaunchReplayUI to intelligently handle
+// showing the UI after making a capture.
+//
+// This will return 1 if the request was successfully passed on, though it's not guaranteed that
+// the UI will be on top in all cases depending on OS rules. It will return 0 if there is no current
+// target control connection to make such a request, or if there was another error
+typedef uint32_t(RENDERDOC_CC *pRENDERDOC_ShowReplayUI)();
+
 //////////////////////////////////////////////////////////////////////////////////////////////////
 // RenderDoc API versions
 //
@@ -550,6 +559,7 @@ typedef enum RENDERDOC_Version {
   eRENDERDOC_API_Version_1_4_0 = 10400,    // RENDERDOC_API_1_4_0 = 1 04 00
   eRENDERDOC_API_Version_1_4_1 = 10401,    // RENDERDOC_API_1_4_1 = 1 04 01
   eRENDERDOC_API_Version_1_4_2 = 10402,    // RENDERDOC_API_1_4_2 = 1 04 02
+  eRENDERDOC_API_Version_1_5_0 = 10500,    // RENDERDOC_API_1_5_0 = 1 05 00
 } RENDERDOC_Version;
 
 // API version changelog:
@@ -577,8 +587,9 @@ typedef enum RENDERDOC_Version {
 //         capturing without saving anything to disk.
 // 1.4.1 - Refactor: Renamed Shutdown to RemoveHooks to better clarify what is happening
 // 1.4.2 - Refactor: Renamed 'draws' to 'actions' in callstack capture option.
+// 1.5.0 - Added feature: ShowReplayUI() to request that the replay UI show itself if connected
 
-typedef struct RENDERDOC_API_1_4_1
+typedef struct RENDERDOC_API_1_5_0
 {
   pRENDERDOC_GetAPIVersion GetAPIVersion;
 
@@ -650,18 +661,22 @@ typedef struct RENDERDOC_API_1_4_1
 
   // new function in 1.4.0
   pRENDERDOC_DiscardFrameCapture DiscardFrameCapture;
-} RENDERDOC_API_1_4_2;
 
-typedef RENDERDOC_API_1_4_2 RENDERDOC_API_1_0_0;
-typedef RENDERDOC_API_1_4_2 RENDERDOC_API_1_0_1;
-typedef RENDERDOC_API_1_4_2 RENDERDOC_API_1_0_2;
-typedef RENDERDOC_API_1_4_2 RENDERDOC_API_1_1_0;
-typedef RENDERDOC_API_1_4_2 RENDERDOC_API_1_1_1;
-typedef RENDERDOC_API_1_4_2 RENDERDOC_API_1_1_2;
-typedef RENDERDOC_API_1_4_2 RENDERDOC_API_1_2_0;
-typedef RENDERDOC_API_1_4_2 RENDERDOC_API_1_3_0;
-typedef RENDERDOC_API_1_4_2 RENDERDOC_API_1_4_0;
-typedef RENDERDOC_API_1_4_2 RENDERDOC_API_1_4_0;
+  // new function in 1.5.0
+  pRENDERDOC_ShowReplayUI ShowReplayUI;
+} RENDERDOC_API_1_5_0;
+
+typedef RENDERDOC_API_1_5_0 RENDERDOC_API_1_0_0;
+typedef RENDERDOC_API_1_5_0 RENDERDOC_API_1_0_1;
+typedef RENDERDOC_API_1_5_0 RENDERDOC_API_1_0_2;
+typedef RENDERDOC_API_1_5_0 RENDERDOC_API_1_1_0;
+typedef RENDERDOC_API_1_5_0 RENDERDOC_API_1_1_1;
+typedef RENDERDOC_API_1_5_0 RENDERDOC_API_1_1_2;
+typedef RENDERDOC_API_1_5_0 RENDERDOC_API_1_2_0;
+typedef RENDERDOC_API_1_5_0 RENDERDOC_API_1_3_0;
+typedef RENDERDOC_API_1_5_0 RENDERDOC_API_1_4_0;
+typedef RENDERDOC_API_1_5_0 RENDERDOC_API_1_4_1;
+typedef RENDERDOC_API_1_5_0 RENDERDOC_API_1_4_2;
 
 //////////////////////////////////////////////////////////////////////////////////////////////////
 // RenderDoc API entry point

renderdoc/api/replay/replay_enums.h

@@ -3744,6 +3744,10 @@ DOCUMENT(R"(The type of message received from or sent to an application target c
 .. data:: CapturableWindowCount
 
   The number of capturable windows has changed.
+
+.. data:: RequestShow
+
+  The client has requested that the controller show itself (raise its window to the top).
 )");
 enum class TargetControlMessageType : uint32_t
 {
@@ -3756,7 +3760,8 @@ enum class TargetControlMessageType : uint32_t
   RegisterAPI,
   NewChild,
   CaptureProgress,
-  CapturableWindowCount
+  CapturableWindowCount,
+  RequestShow,
 };
 
 DECLARE_REFLECTION_ENUM(TargetControlMessageType);

renderdoc/core/core.cpp

@@ -861,14 +861,24 @@ bool RenderDoc::DiscardFrameCapture(void *dev, void *wnd)
 
 bool RenderDoc::IsTargetControlConnected()
 {
-  SCOPED_LOCK(RenderDoc::Inst().m_SingleClientLock);
-  return !RenderDoc::Inst().m_SingleClientName.empty();
+  SCOPED_LOCK(m_SingleClientLock);
+  return !m_SingleClientName.empty();
 }
 
 rdcstr RenderDoc::GetTargetControlUsername()
 {
-  SCOPED_LOCK(RenderDoc::Inst().m_SingleClientLock);
-  return RenderDoc::Inst().m_SingleClientName;
+  SCOPED_LOCK(m_SingleClientLock);
+  return m_SingleClientName;
+}
+
+bool RenderDoc::ShowReplayUI()
+{
+  SCOPED_LOCK(m_SingleClientLock);
+  if(m_SingleClientName.empty())
+    return false;
+
+  m_RequestControllerShow = true;
+  return true;
 }
 
 void RenderDoc::Tick()

renderdoc/core/core.h

@@ -522,6 +522,8 @@ public:
   bool IsTargetControlConnected();
   rdcstr GetTargetControlUsername();
 
+  bool ShowReplayUI();
+
   void Tick();
 
   void AddFrameCapturer(void *dev, void *wnd, IFrameCapturer *cap);
@@ -701,6 +703,7 @@ private:
   volatile bool m_ControlClientThreadShutdown;
   Threading::CriticalSection m_SingleClientLock;
   rdcstr m_SingleClientName;
+  bool m_RequestControllerShow = false;
 
   uint64_t m_TimeBase;
   double m_TimeFrequency;

renderdoc/core/target_control.cpp

@@ -32,7 +32,7 @@
 #include "replay/replay_driver.h"
 #include "serialise/serialiser.h"
 
-static const uint32_t TargetControlProtocolVersion = 6;
+static const uint32_t TargetControlProtocolVersion = 7;
 
 static bool IsProtocolVersionSupported(const uint32_t protocolVersion)
 {
@@ -52,6 +52,10 @@ static bool IsProtocolVersionSupported(const uint32_t protocolVersion)
   if(protocolVersion == 5)
     return true;
 
+  // 6 -> 7 add 'request show' packet
+  if(protocolVersion == 6)
+    return true;
+
   if(protocolVersion == TargetControlProtocolVersion)
     return true;
 
@@ -72,7 +76,8 @@ enum PacketType : uint32_t
   ePacket_NewChild,
   ePacket_CaptureProgress,
   ePacket_CycleActiveWindow,
-  ePacket_CapturableWindowCount
+  ePacket_CapturableWindowCount,
+  ePacket_RequestShow
 };
 
 DECLARE_REFLECTION_ENUM(PacketType);
@@ -288,6 +293,27 @@ void RenderDoc::TargetControlClientThread(uint32_t version, Network::Socket *cli
         SERIALISE_ELEMENT(curWindows);
       }
     }
+    else if(version >= 7)
+    {
+      bool requestShow = false;
+
+      {
+        SCOPED_LOCK(RenderDoc::Inst().m_SingleClientLock);
+        if(RenderDoc::Inst().m_RequestControllerShow)
+        {
+          requestShow = RenderDoc::Inst().m_RequestControllerShow;
+          RenderDoc::Inst().m_RequestControllerShow = false;
+        }
+      }
+
+      if(requestShow)
+      {
+        WRITE_DATA_SCOPE();
+        {
+          SCOPED_SERIALISE_CHUNK(ePacket_RequestShow);
+        }
+      }
+    }
 
     if(curtime > pingtime)
     {
@@ -872,6 +898,12 @@ public:
       reader.EndChunk();
       return msg;
     }
+    else if(type == ePacket_RequestShow)
+    {
+      msg.type = TargetControlMessageType::RequestShow;
+      reader.EndChunk();
+      return msg;
+    }
     else
     {
       RDCERR("Unexpected packed received: %d", type);

renderdoc/replay/app_api.cpp

@@ -239,28 +239,33 @@ static uint32_t DiscardFrameCapture(void *device, void *wndHandle)
   return RenderDoc::Inst().DiscardFrameCapture(device, wndHandle) ? 1 : 0;
 }
 
+static uint32_t ShowReplayUI()
+{
+  return RenderDoc::Inst().ShowReplayUI() ? 1 : 0;
+}
+
 // defined in capture_options.cpp
 int RENDERDOC_CC SetCaptureOptionU32(RENDERDOC_CaptureOption opt, uint32_t val);
 int RENDERDOC_CC SetCaptureOptionF32(RENDERDOC_CaptureOption opt, float val);
 uint32_t RENDERDOC_CC GetCaptureOptionU32(RENDERDOC_CaptureOption opt);
 float RENDERDOC_CC GetCaptureOptionF32(RENDERDOC_CaptureOption opt);
 
-void RENDERDOC_CC GetAPIVersion_1_4_2(int *major, int *minor, int *patch)
+void RENDERDOC_CC GetAPIVersion_1_5_0(int *major, int *minor, int *patch)
 {
   if(major)
     *major = 1;
   if(minor)
-    *minor = 4;
+    *minor = 5;
   if(patch)
-    *patch = 2;
+    *patch = 0;
 }
 
-RENDERDOC_API_1_4_2 api_1_4_2;
-void Init_1_4_2()
+RENDERDOC_API_1_5_0 api_1_5_0;
+void Init_1_5_0()
 {
-  RENDERDOC_API_1_4_2 &api = api_1_4_2;
+  RENDERDOC_API_1_5_0 &api = api_1_5_0;
 
-  api.GetAPIVersion = &GetAPIVersion_1_4_2;
+  api.GetAPIVersion = &GetAPIVersion_1_5_0;
 
   api.SetCaptureOptionU32 = &SetCaptureOptionU32;
   api.SetCaptureOptionF32 = &SetCaptureOptionF32;
@@ -299,6 +304,8 @@ void Init_1_4_2()
   api.SetCaptureFileComments = &SetCaptureFileComments;
 
   api.DiscardFrameCapture = &DiscardFrameCapture;
+
+  api.ShowReplayUI = &ShowReplayUI;
 }
 
 extern "C" RENDERDOC_API int RENDERDOC_CC RENDERDOC_GetAPI(RENDERDOC_Version version,
@@ -325,17 +332,18 @@ extern "C" RENDERDOC_API int RENDERDOC_CC RENDERDOC_GetAPI(RENDERDOC_Version ver
     ret = 1;                                                       \
   }
 
-  API_VERSION_HANDLE(1_0_0, 1_4_2);
-  API_VERSION_HANDLE(1_0_1, 1_4_2);
-  API_VERSION_HANDLE(1_0_2, 1_4_2);
-  API_VERSION_HANDLE(1_1_0, 1_4_2);
-  API_VERSION_HANDLE(1_1_1, 1_4_2);
-  API_VERSION_HANDLE(1_1_2, 1_4_2);
-  API_VERSION_HANDLE(1_2_0, 1_4_2);
-  API_VERSION_HANDLE(1_3_0, 1_4_2);
-  API_VERSION_HANDLE(1_4_0, 1_4_2);
-  API_VERSION_HANDLE(1_4_1, 1_4_2);
-  API_VERSION_HANDLE(1_4_2, 1_4_2);
+  API_VERSION_HANDLE(1_0_0, 1_5_0);
+  API_VERSION_HANDLE(1_0_1, 1_5_0);
+  API_VERSION_HANDLE(1_0_2, 1_5_0);
+  API_VERSION_HANDLE(1_1_0, 1_5_0);
+  API_VERSION_HANDLE(1_1_1, 1_5_0);
+  API_VERSION_HANDLE(1_1_2, 1_5_0);
+  API_VERSION_HANDLE(1_2_0, 1_5_0);
+  API_VERSION_HANDLE(1_3_0, 1_5_0);
+  API_VERSION_HANDLE(1_4_0, 1_5_0);
+  API_VERSION_HANDLE(1_4_1, 1_5_0);
+  API_VERSION_HANDLE(1_4_2, 1_5_0);
+  API_VERSION_HANDLE(1_5_0, 1_5_0);
 
 #undef API_VERSION_HANDLE