Add DiscardFrameCapture to in-application API, bumped to version 1.4.0

docs/in_application_api.rst

@@ -415,6 +415,22 @@ 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.
 
+.. cpp:function:: void DiscardFrameCapture(RENDERDOC_DevicePointer device, RENDERDOC_WindowHandle wndHandle)
+
+    This function is similar to :cpp:func:`EndFrameCapture` but the capture contents will be discarded immediately, and not processed and written to disk. This will be more efficient than :cpp:func:`EndFrameCapture` if the frame capture is not needed.
+
+    :param RENDERDOC_DevicePointer device: is a handle to the API 'device' object that will be set active. May be NULL to wildcard match.
+    :param RENDERDOC_WindowHandle wndHandle: is a handle to the platform window handle that will be set active. May be NULL to wildcard match.
+
+.. note::
+
+    ``RENDERDOC_DevicePointer`` and ``RENDERDOC_WindowHandle`` are described above in :cpp:func:`SetActiveWindow`.
+    ``device`` and ``wndHandle`` can either or both be set to ``NULL`` to wildcard match against active device/window combinations. This wildcard matching can be used if the handle is difficult to obtain where frame captures are triggered.
+
+    Wildcard matching of `device` and `wndHandle` is described above in :cpp:func:`BeginFrameCapture`.
+
+    There will be undefined results if there is not an active frame capture for the device/window combination.
+
 .. 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.

renderdoc/api/app/renderdoc_app.h

@@ -513,6 +513,13 @@ typedef uint32_t(RENDERDOC_CC *pRENDERDOC_IsFrameCapturing)();
 typedef uint32_t(RENDERDOC_CC *pRENDERDOC_EndFrameCapture)(RENDERDOC_DevicePointer device,
                                                            RENDERDOC_WindowHandle wndHandle);
 
+// Ends capturing immediately and discard any data stored without saving to disk.
+//
+// This will return 1 if the capture was discarded, and 0 if there was an error or no capture
+// was in progress
+typedef uint32_t(RENDERDOC_CC *pRENDERDOC_DiscardFrameCapture)(RENDERDOC_DevicePointer device,
+                                                               RENDERDOC_WindowHandle wndHandle);
+
 //////////////////////////////////////////////////////////////////////////////////////////////////
 // RenderDoc API versions
 //
@@ -535,6 +542,7 @@ typedef enum RENDERDOC_Version {
   eRENDERDOC_API_Version_1_1_2 = 10102,    // RENDERDOC_API_1_1_2 = 1 01 02
   eRENDERDOC_API_Version_1_2_0 = 10200,    // RENDERDOC_API_1_2_0 = 1 02 00
   eRENDERDOC_API_Version_1_3_0 = 10300,    // RENDERDOC_API_1_3_0 = 1 03 00
+  eRENDERDOC_API_Version_1_4_0 = 10400,    // RENDERDOC_API_1_4_0 = 1 04 00
 } RENDERDOC_Version;
 
 // API version changelog:
@@ -558,8 +566,10 @@ typedef enum RENDERDOC_Version {
 //         Refactor: Renamed eRENDERDOC_Option_VerifyMapWrites to
 //         eRENDERDOC_Option_VerifyBufferAccess, which now also controls initialisation to
 //         0xdddddddd of uninitialised buffer contents.
+// 1.4.0 - Added feature: DiscardFrameCapture() to discard a frame capture in progress and stop
+//         capturing without saving anything to disk.
 
-typedef struct RENDERDOC_API_1_3_0
+typedef struct RENDERDOC_API_1_4_0
 {
   pRENDERDOC_GetAPIVersion GetAPIVersion;
 
@@ -622,15 +632,19 @@ typedef struct RENDERDOC_API_1_3_0
 
   // new function in 1.2.0
   pRENDERDOC_SetCaptureFileComments SetCaptureFileComments;
-} RENDERDOC_API_1_3_0;
 
-typedef RENDERDOC_API_1_3_0 RENDERDOC_API_1_0_0;
-typedef RENDERDOC_API_1_3_0 RENDERDOC_API_1_0_1;
-typedef RENDERDOC_API_1_3_0 RENDERDOC_API_1_0_2;
-typedef RENDERDOC_API_1_3_0 RENDERDOC_API_1_1_0;
-typedef RENDERDOC_API_1_3_0 RENDERDOC_API_1_1_1;
-typedef RENDERDOC_API_1_3_0 RENDERDOC_API_1_1_2;
-typedef RENDERDOC_API_1_3_0 RENDERDOC_API_1_2_0;
+  // new function in 1.4.0
+  pRENDERDOC_DiscardFrameCapture DiscardFrameCapture;
+} RENDERDOC_API_1_4_0;
+
+typedef RENDERDOC_API_1_4_0 RENDERDOC_API_1_0_0;
+typedef RENDERDOC_API_1_4_0 RENDERDOC_API_1_0_1;
+typedef RENDERDOC_API_1_4_0 RENDERDOC_API_1_0_2;
+typedef RENDERDOC_API_1_4_0 RENDERDOC_API_1_1_0;
+typedef RENDERDOC_API_1_4_0 RENDERDOC_API_1_1_1;
+typedef RENDERDOC_API_1_4_0 RENDERDOC_API_1_1_2;
+typedef RENDERDOC_API_1_4_0 RENDERDOC_API_1_2_0;
+typedef RENDERDOC_API_1_4_0 RENDERDOC_API_1_3_0;
 
 //////////////////////////////////////////////////////////////////////////////////////////////////
 // RenderDoc API entry point

renderdoc/core/core.cpp

@@ -527,6 +527,18 @@ bool RenderDoc::EndFrameCapture(void *dev, void *wnd)
   return false;
 }
 
+bool RenderDoc::DiscardFrameCapture(void *dev, void *wnd)
+{
+  IFrameCapturer *frameCap = MatchFrameCapturer(dev, wnd);
+  if(frameCap)
+  {
+    bool ret = frameCap->DiscardFrameCapture(dev, wnd);
+    m_CapturesActive--;
+    return ret;
+  }
+  return false;
+}
+
 bool RenderDoc::IsTargetControlConnected()
 {
   SCOPED_LOCK(RenderDoc::Inst().m_SingleClientLock);
@@ -1322,6 +1334,10 @@ void RenderDoc::FinishCaptureWriting(RDCFile *rdc, uint32_t frameNumber)
 
     delete rdc;
   }
+  else
+  {
+    RDCLOG("Discarded capture, Frame %u", frameNumber);
+  }
 
   RenderDoc::Inst().SetProgress(CaptureProgress::FileWriting, 1.0f);
 }

renderdoc/core/core.h

@@ -61,6 +61,7 @@ struct IFrameCapturer
 {
   virtual void StartFrameCapture(void *dev, void *wnd) = 0;
   virtual bool EndFrameCapture(void *dev, void *wnd) = 0;
+  virtual bool DiscardFrameCapture(void *dev, void *wnd) = 0;
 };
 
 // In most cases you don't need to check these individually, use the utility functions below
@@ -534,6 +535,7 @@ public:
   bool IsFrameCapturing() { return m_CapturesActive > 0; }
   void SetActiveWindow(void *dev, void *wnd);
   bool EndFrameCapture(void *dev, void *wnd);
+  bool DiscardFrameCapture(void *dev, void *wnd);
 
   bool MatchClosestWindow(void *&dev, void *&wnd);
 

renderdoc/driver/d3d11/d3d11_device.cpp

@@ -1862,6 +1862,8 @@ bool WrappedID3D11Device::EndFrameCapture(void *dev, void *wnd)
 
     GetResourceManager()->ClearReferencedResources();
 
+    GetResourceManager()->FreeInitialContents();
+
     // if it's a capture triggered from application code, immediately
     // give up as it's not reasonable to expect applications to detect and retry.
     // otherwise we can retry in case the next frame works.
@@ -1934,6 +1936,71 @@ bool WrappedID3D11Device::EndFrameCapture(void *dev, void *wnd)
   }
 }
 
+bool WrappedID3D11Device::DiscardFrameCapture(void *dev, void *wnd)
+{
+  SCOPED_LOCK(m_D3DLock);
+
+  if(!IsActiveCapturing(m_State))
+    return true;
+
+  RenderDoc::Inst().FinishCaptureWriting(NULL, m_CapturedFrames.back().frameNumber);
+
+  m_pImmediateContext->CleanupCapture();
+
+  for(auto it = m_DeferredContexts.begin(); it != m_DeferredContexts.end(); ++it)
+  {
+    WrappedID3D11DeviceContext *context = *it;
+
+    if(context)
+      context->CleanupCapture();
+    else
+      RDCERR("NULL deferred context in resource record!");
+  }
+
+  GetResourceManager()->ClearReferencedResources();
+
+  GetResourceManager()->FreeInitialContents();
+
+  m_pImmediateContext->FinishCapture();
+
+  m_CapturedFrames.pop_back();
+
+  for(auto it = m_DeferredContexts.begin(); it != m_DeferredContexts.end(); ++it)
+  {
+    WrappedID3D11DeviceContext *context = *it;
+
+    if(context)
+    {
+      context->FinishCapture();
+    }
+    else
+    {
+      RDCERR("NULL deferred context in resource record!");
+    }
+  }
+
+  m_pImmediateContext->FreeCaptureData();
+
+  m_State = CaptureState::BackgroundCapturing;
+
+  for(auto it = m_DeferredContexts.begin(); it != m_DeferredContexts.end(); ++it)
+  {
+    WrappedID3D11DeviceContext *context = *it;
+
+    if(context)
+      context->CleanupCapture();
+    else
+      RDCERR("NULL deferred context in resource record!");
+  }
+
+  GetResourceManager()->MarkUnwrittenResources();
+
+  if(m_pInfoQueue)
+    m_pInfoQueue->ClearStoredMessages();
+
+  return true;
+}
+
 void WrappedID3D11Device::LockForChunkFlushing()
 {
   // wait for the value to be 0 (no-one messing with chunks right now) and set to -1

renderdoc/driver/d3d11/d3d11_device.h

@@ -458,6 +458,7 @@ public:
 
   void StartFrameCapture(void *dev, void *wnd);
   bool EndFrameCapture(void *dev, void *wnd);
+  bool DiscardFrameCapture(void *dev, void *wnd);
 
   ID3DUserDefinedAnnotation *GetAnnotations() { return m_RealAnnotations; }
   // interface for DXGI

renderdoc/driver/d3d12/d3d12_device.cpp

@@ -1782,7 +1782,51 @@ bool WrappedID3D12Device::EndFrameCapture(void *dev, void *wnd)
 
   SAFE_DELETE(m_HeaderChunk);
 
-  m_State = CaptureState::BackgroundCapturing;
+  for(auto it = queues.begin(); it != queues.end(); ++it)
+    (*it)->ClearAfterCapture();
+
+  GetResourceManager()->MarkUnwrittenResources();
+
+  GetResourceManager()->ClearReferencedResources();
+
+  GetResourceManager()->FreeInitialContents();
+
+  GetResourceManager()->FlushPendingDirty();
+
+  FlushPendingDescriptorWrites();
+
+  return true;
+}
+
+bool WrappedID3D12Device::DiscardFrameCapture(void *dev, void *wnd)
+{
+  if(!IsActiveCapturing(m_State))
+    return true;
+
+  RenderDoc::Inst().FinishCaptureWriting(NULL, m_CapturedFrames.back().frameNumber);
+
+  m_CapturedFrames.pop_back();
+
+  std::vector<WrappedID3D12CommandQueue *> queues;
+
+  // transition back to IDLE and readback initial states atomically
+  {
+    SCOPED_WRITELOCK(m_CapTransitionLock);
+
+    m_State = CaptureState::BackgroundCapturing;
+
+    GPUSync();
+
+    {
+      SCOPED_LOCK(m_MapsLock);
+      for(auto it = m_Maps.begin(); it != m_Maps.end(); ++it)
+        GetWrapped(it->res)->FreeShadow();
+    }
+
+    queues = m_Queues;
+  }
+
+  SAFE_DELETE(m_HeaderChunk);
 
   for(auto it = queues.begin(); it != queues.end(); ++it)
     (*it)->ClearAfterCapture();

renderdoc/driver/d3d12/d3d12_device.h

@@ -552,6 +552,7 @@ public:
 
   void StartFrameCapture(void *dev, void *wnd);
   bool EndFrameCapture(void *dev, void *wnd);
+  bool DiscardFrameCapture(void *dev, void *wnd);
 
   template <typename SerialiserType>
   bool Serialise_BeginCaptureFrame(SerialiserType &ser);

renderdoc/driver/d3d8/d3d8_device.cpp

@@ -168,6 +168,12 @@ bool WrappedD3DDevice8::EndFrameCapture(void *dev, void *wnd)
   return false;
 }
 
+bool WrappedD3DDevice8::DiscardFrameCapture(void *dev, void *wnd)
+{
+  RDCERR("Capture not supported on D3D8");
+  return false;
+}
+
 HRESULT __stdcall WrappedD3DDevice8::TestCooperativeLevel()
 {
   return m_device->TestCooperativeLevel();

renderdoc/driver/d3d8/d3d8_device.h

@@ -40,6 +40,7 @@ public:
 
   void StartFrameCapture(void *dev, void *wnd);
   bool EndFrameCapture(void *dev, void *wnd);
+  bool DiscardFrameCapture(void *dev, void *wnd);
 
   void InternalRef() { InterlockedIncrement(&m_InternalRefcount); }
   void InternalRelease() { InterlockedDecrement(&m_InternalRefcount); }

renderdoc/driver/d3d9/d3d9_device.cpp

@@ -122,6 +122,12 @@ bool WrappedD3DDevice9::EndFrameCapture(void *dev, void *wnd)
   return false;
 }
 
+bool WrappedD3DDevice9::DiscardFrameCapture(void *dev, void *wnd)
+{
+  RDCERR("Capture not supported on D3D9");
+  return false;
+}
+
 HRESULT __stdcall WrappedD3DDevice9::TestCooperativeLevel()
 {
   return m_device->TestCooperativeLevel();

renderdoc/driver/d3d9/d3d9_device.h

@@ -38,6 +38,7 @@ public:
 
   void StartFrameCapture(void *dev, void *wnd);
   bool EndFrameCapture(void *dev, void *wnd);
+  bool DiscardFrameCapture(void *dev, void *wnd);
 
   void InternalRef() { InterlockedIncrement(&m_InternalRefcount); }
   void InternalRelease() { InterlockedDecrement(&m_InternalRefcount); }

renderdoc/driver/gl/gl_driver.cpp

@@ -1756,7 +1756,10 @@ void WrappedOpenGL::SwapBuffers(void *windowHandle)
   }
 
   if(IsActiveCapturing(m_State) && m_AppControlledCapture)
+  {
+    delete m_BackbufferImages[windowHandle];
     m_BackbufferImages[windowHandle] = SaveBackbufferImage();
+  }
 
   RenderDoc::Inst().AddActiveDriver(GetDriverType(), true);
 
@@ -2075,6 +2078,8 @@ bool WrappedOpenGL::EndFrameCapture(void *dev, void *wnd)
 
     GetResourceManager()->ClearReferencedResources();
 
+    GetResourceManager()->FreeInitialContents();
+
     // if it's a capture triggered from application code, immediately
     // give up as it's not reasonable to expect applications to detect and retry.
     // otherwise we can retry in case the next frame works.
@@ -2120,6 +2125,38 @@ bool WrappedOpenGL::EndFrameCapture(void *dev, void *wnd)
   }
 }
 
+bool WrappedOpenGL::DiscardFrameCapture(void *dev, void *wnd)
+{
+  if(!IsActiveCapturing(m_State))
+    return true;
+
+  SCOPED_LOCK(glLock);
+
+  RenderDoc::Inst().FinishCaptureWriting(NULL, m_CapturedFrames.back().frameNumber);
+
+  CleanupCapture();
+
+  GetResourceManager()->ClearReferencedResources();
+
+  GetResourceManager()->FreeInitialContents();
+
+  FinishCapture();
+
+  m_CapturedFrames.pop_back();
+
+  FreeCaptureData();
+
+  m_State = CaptureState::BackgroundCapturing;
+
+  GetResourceManager()->MarkUnwrittenResources();
+
+  for(auto it = m_BackbufferImages.begin(); it != m_BackbufferImages.end(); ++it)
+    delete it->second;
+  m_BackbufferImages.clear();
+
+  return true;
+}
+
 void WrappedOpenGL::FirstFrame(void *ctx, void *wndHandle)
 {
   // if we have to capture the first frame, begin capturing immediately

renderdoc/driver/gl/gl_driver.h

@@ -550,6 +550,7 @@ public:
   void ReplayMarkers(bool replay) { m_ReplayMarkers = replay; }
   void StartFrameCapture(void *dev, void *wnd);
   bool EndFrameCapture(void *dev, void *wnd);
+  bool DiscardFrameCapture(void *dev, void *wnd);
 
   // map with key being mip level, value being stored data
   typedef std::map<int, std::vector<byte>> CompressedDataStore;

renderdoc/driver/vulkan/vk_core.cpp

@@ -1717,6 +1717,57 @@ bool WrappedVulkan::EndFrameCapture(void *dev, void *wnd)
   return true;
 }
 
+bool WrappedVulkan::DiscardFrameCapture(void *dev, void *wnd)
+{
+  if(!IsActiveCapturing(m_State))
+    return true;
+
+  RenderDoc::Inst().FinishCaptureWriting(NULL, m_CapturedFrames.back().frameNumber);
+
+  m_CapturedFrames.pop_back();
+
+  // transition back to IDLE atomically
+  {
+    SCOPED_LOCK(m_CapTransitionLock);
+
+    m_State = CaptureState::BackgroundCapturing;
+
+    // m_SuccessfulCapture = false;
+
+    ObjDisp(GetDev())->DeviceWaitIdle(Unwrap(GetDev()));
+
+    {
+      SCOPED_LOCK(m_CoherentMapsLock);
+      for(auto it = m_CoherentMaps.begin(); it != m_CoherentMaps.end(); ++it)
+      {
+        FreeAlignedBuffer((*it)->memMapState->refData);
+        (*it)->memMapState->refData = NULL;
+        (*it)->memMapState->needRefData = false;
+      }
+    }
+  }
+
+  SAFE_DELETE(m_HeaderChunk);
+
+  // delete cmd buffers now - had to keep them alive until after serialiser flush.
+  for(size_t i = 0; i < m_CmdBufferRecords.size(); i++)
+    m_CmdBufferRecords[i]->Delete(GetResourceManager());
+
+  m_CmdBufferRecords.clear();
+
+  GetResourceManager()->MarkUnwrittenResources();
+
+  GetResourceManager()->ClearReferencedResources();
+
+  GetResourceManager()->FreeInitialContents();
+
+  GetResourceManager()->FlushPendingDirty();
+
+  FreeAllMemory(MemoryScope::InitialContents);
+
+  return true;
+}
+
 void WrappedVulkan::AdvanceFrame()
 {
   if(IsBackgroundCapturing(m_State))

renderdoc/driver/vulkan/vk_core.h

@@ -779,6 +779,7 @@ private:
 
   void StartFrameCapture(void *dev, void *wnd);
   bool EndFrameCapture(void *dev, void *wnd);
+  bool DiscardFrameCapture(void *dev, void *wnd);
 
   void AdvanceFrame();
   void Present(void *dev, void *wnd);

renderdoc/replay/app_api.cpp

@@ -233,28 +233,33 @@ static uint32_t EndFrameCapture(void *device, void *wndHandle)
   return RenderDoc::Inst().EndFrameCapture(device, wndHandle) ? 1 : 0;
 }
 
+static uint32_t DiscardFrameCapture(void *device, void *wndHandle)
+{
+  return RenderDoc::Inst().DiscardFrameCapture(device, wndHandle) ? 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_3_0(int *major, int *minor, int *patch)
+void RENDERDOC_CC GetAPIVersion_1_4_0(int *major, int *minor, int *patch)
 {
   if(major)
     *major = 1;
   if(minor)
-    *minor = 3;
+    *minor = 4;
   if(patch)
     *patch = 0;
 }
 
-RENDERDOC_API_1_3_0 api_1_3_0;
-void Init_1_3_0()
+RENDERDOC_API_1_4_0 api_1_4_0;
+void Init_1_4_0()
 {
-  RENDERDOC_API_1_3_0 &api = api_1_3_0;
+  RENDERDOC_API_1_4_0 &api = api_1_4_0;
 
-  api.GetAPIVersion = &GetAPIVersion_1_3_0;
+  api.GetAPIVersion = &GetAPIVersion_1_4_0;
 
   api.SetCaptureOptionU32 = &SetCaptureOptionU32;
   api.SetCaptureOptionF32 = &SetCaptureOptionF32;
@@ -291,6 +296,8 @@ void Init_1_3_0()
   api.TriggerMultiFrameCapture = &TriggerMultiFrameCapture;
 
   api.SetCaptureFileComments = &SetCaptureFileComments;
+
+  api.DiscardFrameCapture = &DiscardFrameCapture;
 }
 
 extern "C" RENDERDOC_API int RENDERDOC_CC RENDERDOC_GetAPI(RENDERDOC_Version version,
@@ -317,14 +324,15 @@ extern "C" RENDERDOC_API int RENDERDOC_CC RENDERDOC_GetAPI(RENDERDOC_Version ver
     ret = 1;                                                       \
   }
 
-  API_VERSION_HANDLE(1_0_0, 1_3_0);
-  API_VERSION_HANDLE(1_0_1, 1_3_0);
-  API_VERSION_HANDLE(1_0_2, 1_3_0);
-  API_VERSION_HANDLE(1_1_0, 1_3_0);
-  API_VERSION_HANDLE(1_1_1, 1_3_0);
-  API_VERSION_HANDLE(1_1_2, 1_3_0);
-  API_VERSION_HANDLE(1_2_0, 1_3_0);
-  API_VERSION_HANDLE(1_3_0, 1_3_0);
+  API_VERSION_HANDLE(1_0_0, 1_4_0);
+  API_VERSION_HANDLE(1_0_1, 1_4_0);
+  API_VERSION_HANDLE(1_0_2, 1_4_0);
+  API_VERSION_HANDLE(1_1_0, 1_4_0);
+  API_VERSION_HANDLE(1_1_1, 1_4_0);
+  API_VERSION_HANDLE(1_1_2, 1_4_0);
+  API_VERSION_HANDLE(1_2_0, 1_4_0);
+  API_VERSION_HANDLE(1_3_0, 1_4_0);
+  API_VERSION_HANDLE(1_4_0, 1_4_0);
 
 #undef API_VERSION_HANDLE