Updated RenderDoc.

3rdparty/renderdoc/renderdoc_app.h

@@ -1,7 +1,7 @@
 /******************************************************************************
  * The MIT License (MIT)
  *
- * Copyright (c) 2015-2018 Baldur Karlsson
+ * Copyright (c) 2019-2020 Baldur Karlsson
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -33,7 +33,7 @@
 #include <stdint.h>
 #endif
 
-#if defined(WIN32)
+#if defined(WIN32) || defined(__WIN32__) || defined(_WIN32) || defined(_MSC_VER)
 #define RENDERDOC_CC __cdecl
 #elif defined(__linux__)
 #define RENDERDOC_CC
@@ -72,7 +72,7 @@ extern "C" {
 // RenderDoc capture options
 //
 
-typedef enum {
+typedef enum RENDERDOC_CaptureOption {
   // Allow the application to enable vsync
   //
   // Default - enabled
@@ -126,15 +126,24 @@ typedef enum {
   //
   eRENDERDOC_Option_DelayForDebugger = 5,
 
-  // Verify any writes to mapped buffers, by checking the memory after the
+  // Verify buffer access. This includes checking the memory returned by a Map() call to
-  // bounds of the returned pointer to detect any modification.
+  // detect any out-of-bounds modification, as well as initialising buffers with undefined contents
+  // to a marker value to catch use of uninitialised memory.
+  //
+  // NOTE: This option is only valid for OpenGL and D3D11. Explicit APIs such as D3D12 and Vulkan do
+  // not do the same kind of interception & checking and undefined contents are really undefined.
   //
   // Default - disabled
   //
-  // 1 - Verify any writes to mapped buffers
+  // 1 - Verify buffer access
-  // 0 - No verification is performed, and overwriting bounds may cause
+  // 0 - No verification is performed, and overwriting bounds may cause crashes or corruption in
-  //     crashes or corruption in RenderDoc
+  //     RenderDoc.
-  eRENDERDOC_Option_VerifyMapWrites = 6,
+  eRENDERDOC_Option_VerifyBufferAccess = 6,
+
+  // The old name for eRENDERDOC_Option_VerifyBufferAccess was eRENDERDOC_Option_VerifyMapWrites.
+  // This option now controls the filling of uninitialised buffers with 0xdddddddd which was
+  // previously always enabled
+  eRENDERDOC_Option_VerifyMapWrites = eRENDERDOC_Option_VerifyBufferAccess,
 
   // Hooks any system API calls that create child processes, and injects
   // RenderDoc into them recursively with the same options.
@@ -155,6 +164,10 @@ typedef enum {
   // 0 - only the resources referenced by the captured frame are included
   eRENDERDOC_Option_RefAllResources = 8,
 
+  // **NOTE**: As of RenderDoc v1.1 this option has been deprecated. Setting or
+  // getting it will be ignored, to allow compatibility with older versions.
+  // In v1.1 the option acts as if it's always enabled.
+  //
   // By default RenderDoc skips saving initial states for resources where the
   // previous contents don't appear to be used, assuming that writes before
   // reads indicate previous contents aren't used.
@@ -173,7 +186,7 @@ typedef enum {
   // and replayed many times will not be available and may cause a failure to
   // capture.
   //
-  // Note this is only true for APIs where multithreading is difficult or
+  // NOTE: This is only true for APIs where multithreading is difficult or
   // discouraged. Newer APIs like Vulkan and D3D12 will ignore this option
   // and always capture all command lists since the API is heavily oriented
   // around it and the overheads have been reduced by API design.
@@ -191,6 +204,15 @@ typedef enum {
   // 0 - API debugging is displayed as normal
   eRENDERDOC_Option_DebugOutputMute = 11,
 
+  // Option to allow vendor extensions to be used even when they may be
+  // incompatible with RenderDoc and cause corrupted replays or crashes.
+  //
+  // Default - inactive
+  //
+  // No values are documented, this option should only be used when absolutely
+  // necessary as directed by a RenderDoc developer.
+  eRENDERDOC_Option_AllowUnsupportedVendorExtensions = 12,
+
 } RENDERDOC_CaptureOption;
 
 // Sets an option that controls how RenderDoc behaves on capture.
@@ -210,7 +232,7 @@ typedef uint32_t(RENDERDOC_CC *pRENDERDOC_GetCaptureOptionU32)(RENDERDOC_Capture
 // If the option is invalid, -FLT_MAX is returned
 typedef float(RENDERDOC_CC *pRENDERDOC_GetCaptureOptionF32)(RENDERDOC_CaptureOption opt);
 
-typedef enum {
+typedef enum RENDERDOC_InputButton {
   // '0' - '9' matches ASCII values
   eRENDERDOC_Key_0 = 0x30,
   eRENDERDOC_Key_1 = 0x31,
@@ -298,7 +320,7 @@ typedef void(RENDERDOC_CC *pRENDERDOC_SetFocusToggleKeys)(RENDERDOC_InputButton
 // If keys is NULL or num is 0, captures keys will be disabled
 typedef void(RENDERDOC_CC *pRENDERDOC_SetCaptureKeys)(RENDERDOC_InputButton *keys, int num);
 
-typedef enum {
+typedef enum RENDERDOC_OverlayBits {
   // This single bit controls whether the overlay is enabled or disabled globally
   eRENDERDOC_Overlay_Enabled = 0x1,
 
@@ -327,13 +349,17 @@ typedef uint32_t(RENDERDOC_CC *pRENDERDOC_GetOverlayBits)();
 // sets the overlay bits with an and & or mask
 typedef void(RENDERDOC_CC *pRENDERDOC_MaskOverlayBits)(uint32_t And, uint32_t Or);
 
-// this function will attempt to shut down RenderDoc.
+// this function will attempt to remove RenderDoc's hooks in the application.
 //
-// Note: that this will only work correctly if done immediately after
+// Note: that this can only work correctly if done immediately after
-// the dll is loaded, before any API work happens. RenderDoc will remove its
+// the module is loaded, before any API work happens. RenderDoc will remove its
 // injected hooks and shut down. Behaviour is undefined if this is called
-// after any API functions have been called.
+// after any API functions have been called, and there is still no guarantee of
-typedef void(RENDERDOC_CC *pRENDERDOC_Shutdown)();
+// success.
+typedef void(RENDERDOC_CC *pRENDERDOC_RemoveHooks)();
+
+// DEPRECATED: compatibility for code compiled against pre-1.4.1 headers.
+typedef pRENDERDOC_RemoveHooks pRENDERDOC_Shutdown;
 
 // This function will unload RenderDoc's crash handler.
 //
@@ -365,8 +391,8 @@ typedef void(RENDERDOC_CC *pRENDERDOC_SetCaptureFilePathTemplate)(const char *pa
 typedef const char *(RENDERDOC_CC *pRENDERDOC_GetCaptureFilePathTemplate)();
 
 // DEPRECATED: compatibility for code compiled against pre-1.1.2 headers.
-typedef void(RENDERDOC_CC *pRENDERDOC_SetLogFilePathTemplate)(const char *pathtemplate);
+typedef pRENDERDOC_SetCaptureFilePathTemplate pRENDERDOC_SetLogFilePathTemplate;
-typedef const char *(RENDERDOC_CC *pRENDERDOC_GetLogFilePathTemplate)();
+typedef pRENDERDOC_GetCaptureFilePathTemplate pRENDERDOC_GetLogFilePathTemplate;
 
 // returns the number of captures that have been made
 typedef uint32_t(RENDERDOC_CC *pRENDERDOC_GetNumCaptures)();
@@ -388,6 +414,17 @@ typedef uint32_t(RENDERDOC_CC *pRENDERDOC_GetNumCaptures)();
 typedef uint32_t(RENDERDOC_CC *pRENDERDOC_GetCapture)(uint32_t idx, char *filename,
                                                       uint32_t *pathlength, uint64_t *timestamp);
 
+// Sets the comments associated with a capture file. These comments are displayed in the
+// UI program when opening.
+//
+// filePath should be a path to the capture file to add comments to. If set to NULL or ""
+// the most recent capture file created made will be used instead.
+// comments should be a NULL-terminated UTF-8 string to add as comments.
+//
+// Any existing comments will be overwritten.
+typedef void(RENDERDOC_CC *pRENDERDOC_SetCaptureFileComments)(const char *filePath,
+                                                              const char *comments);
+
 // returns 1 if the RenderDoc UI is connected to this application, 0 otherwise
 typedef uint32_t(RENDERDOC_CC *pRENDERDOC_IsTargetControlConnected)();
 
@@ -395,7 +432,7 @@ typedef uint32_t(RENDERDOC_CC *pRENDERDOC_IsTargetControlConnected)();
 // This was renamed to IsTargetControlConnected in API 1.1.1, the old typedef is kept here for
 // backwards compatibility with old code, it is castable either way since it's ABI compatible
 // as the same function pointer type.
-typedef uint32_t(RENDERDOC_CC *pRENDERDOC_IsRemoteAccessConnected)();
+typedef pRENDERDOC_IsTargetControlConnected pRENDERDOC_IsRemoteAccessConnected;
 
 // This function will launch the Replay UI associated with the RenderDoc library injected
 // into the running application.
@@ -480,6 +517,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
 //
@@ -493,13 +537,17 @@ typedef uint32_t(RENDERDOC_CC *pRENDERDOC_EndFrameCapture)(RENDERDOC_DevicePoint
 // Note that this means the API returned can be higher than the one you might have requested.
 // e.g. if you are running against a newer RenderDoc that supports 1.0.1, it will be returned
 // instead of 1.0.0. You can check this with the GetAPIVersion entry point
-typedef enum {
+typedef enum RENDERDOC_Version {
   eRENDERDOC_API_Version_1_0_0 = 10000,    // RENDERDOC_API_1_0_0 = 1 00 00
   eRENDERDOC_API_Version_1_0_1 = 10001,    // RENDERDOC_API_1_0_1 = 1 00 01
   eRENDERDOC_API_Version_1_0_2 = 10002,    // RENDERDOC_API_1_0_2 = 1 00 02
   eRENDERDOC_API_Version_1_1_0 = 10100,    // RENDERDOC_API_1_1_0 = 1 01 00
   eRENDERDOC_API_Version_1_1_1 = 10101,    // RENDERDOC_API_1_1_1 = 1 01 01
   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
+  eRENDERDOC_API_Version_1_4_1 = 10401,    // RENDERDOC_API_1_4_1 = 1 04 01
 } RENDERDOC_Version;
 
 // API version changelog:
@@ -515,9 +563,19 @@ typedef enum {
 // 1.1.2 - Refactor: Renamed "log file" in function names to just capture, to clarify that these
 //         are captures and not debug logging files. This is the first API version in the v1.0
 //         branch.
+// 1.2.0 - Added feature: SetCaptureFileComments() to add comments to a capture file that will be
+//         displayed in the UI program on load.
+// 1.3.0 - Added feature: New capture option eRENDERDOC_Option_AllowUnsupportedVendorExtensions
+//         which allows users to opt-in to allowing unsupported vendor extensions to function.
+//         Should be used at the user's own risk.
+//         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.
+// 1.4.1 - Refactor: Renamed Shutdown to RemoveHooks to better clarify what is happening
 
-// eRENDERDOC_API_Version_1_1_0
+typedef struct RENDERDOC_API_1_4_1
-typedef struct
 {
   pRENDERDOC_GetAPIVersion GetAPIVersion;
 
@@ -533,18 +591,46 @@ typedef struct
   pRENDERDOC_GetOverlayBits GetOverlayBits;
   pRENDERDOC_MaskOverlayBits MaskOverlayBits;
 
-  pRENDERDOC_Shutdown Shutdown;
+  // Shutdown was renamed to RemoveHooks in 1.4.1.
+  // These unions allow old code to continue compiling without changes
+  union
+  {
+    pRENDERDOC_Shutdown Shutdown;
+    pRENDERDOC_RemoveHooks RemoveHooks;
+  };
   pRENDERDOC_UnloadCrashHandler UnloadCrashHandler;
 
-  pRENDERDOC_SetLogFilePathTemplate SetLogFilePathTemplate;
+  // Get/SetLogFilePathTemplate was renamed to Get/SetCaptureFilePathTemplate in 1.1.2.
-  pRENDERDOC_GetLogFilePathTemplate GetLogFilePathTemplate;
+  // These unions allow old code to continue compiling without changes
+  union
+  {
+    // deprecated name
+    pRENDERDOC_SetLogFilePathTemplate SetLogFilePathTemplate;
+    // current name
+    pRENDERDOC_SetCaptureFilePathTemplate SetCaptureFilePathTemplate;
+  };
+  union
+  {
+    // deprecated name
+    pRENDERDOC_GetLogFilePathTemplate GetLogFilePathTemplate;
+    // current name
+    pRENDERDOC_GetCaptureFilePathTemplate GetCaptureFilePathTemplate;
+  };
 
   pRENDERDOC_GetNumCaptures GetNumCaptures;
   pRENDERDOC_GetCapture GetCapture;
 
   pRENDERDOC_TriggerCapture TriggerCapture;
 
-  pRENDERDOC_IsRemoteAccessConnected IsRemoteAccessConnected;
+  // IsRemoteAccessConnected was renamed to IsTargetControlConnected in 1.1.1.
+  // This union allows old code to continue compiling without changes
+  union
+  {
+    // deprecated name
+    pRENDERDOC_IsRemoteAccessConnected IsRemoteAccessConnected;
+    // current name
+    pRENDERDOC_IsTargetControlConnected IsTargetControlConnected;
+  };
   pRENDERDOC_LaunchReplayUI LaunchReplayUI;
 
   pRENDERDOC_SetActiveWindow SetActiveWindow;
@@ -553,103 +639,25 @@ typedef struct
   pRENDERDOC_IsFrameCapturing IsFrameCapturing;
   pRENDERDOC_EndFrameCapture EndFrameCapture;
 
+  // new function in 1.1.0
   pRENDERDOC_TriggerMultiFrameCapture TriggerMultiFrameCapture;
-} RENDERDOC_API_1_1_0;
 
-typedef RENDERDOC_API_1_1_0 RENDERDOC_API_1_0_0;
+  // new function in 1.2.0
-typedef RENDERDOC_API_1_1_0 RENDERDOC_API_1_0_1;
+  pRENDERDOC_SetCaptureFileComments SetCaptureFileComments;
-typedef RENDERDOC_API_1_1_0 RENDERDOC_API_1_0_2;
 
-// although this structure is identical to RENDERDOC_API_1_1_0, the member
+  // new function in 1.4.0
-// IsRemoteAccessConnected was renamed to IsTargetControlConnected. So that
+  pRENDERDOC_DiscardFrameCapture DiscardFrameCapture;
-// old code can still compile with a new header, we must declare a new struct
+} RENDERDOC_API_1_4_1;
-// type. It can be casted back and forth though, so we will still return a
-// pointer to this type for all previous API versions - the above struct is
-// purely legacy for compilation compatibility
 
-// eRENDERDOC_API_Version_1_1_1
+typedef RENDERDOC_API_1_4_1 RENDERDOC_API_1_0_0;
-typedef struct
+typedef RENDERDOC_API_1_4_1 RENDERDOC_API_1_0_1;
-{
+typedef RENDERDOC_API_1_4_1 RENDERDOC_API_1_0_2;
-  pRENDERDOC_GetAPIVersion GetAPIVersion;
+typedef RENDERDOC_API_1_4_1 RENDERDOC_API_1_1_0;
-
+typedef RENDERDOC_API_1_4_1 RENDERDOC_API_1_1_1;
-  pRENDERDOC_SetCaptureOptionU32 SetCaptureOptionU32;
+typedef RENDERDOC_API_1_4_1 RENDERDOC_API_1_1_2;
-  pRENDERDOC_SetCaptureOptionF32 SetCaptureOptionF32;
+typedef RENDERDOC_API_1_4_1 RENDERDOC_API_1_2_0;
-
+typedef RENDERDOC_API_1_4_1 RENDERDOC_API_1_3_0;
-  pRENDERDOC_GetCaptureOptionU32 GetCaptureOptionU32;
+typedef RENDERDOC_API_1_4_1 RENDERDOC_API_1_4_0;
-  pRENDERDOC_GetCaptureOptionF32 GetCaptureOptionF32;
-
-  pRENDERDOC_SetFocusToggleKeys SetFocusToggleKeys;
-  pRENDERDOC_SetCaptureKeys SetCaptureKeys;
-
-  pRENDERDOC_GetOverlayBits GetOverlayBits;
-  pRENDERDOC_MaskOverlayBits MaskOverlayBits;
-
-  pRENDERDOC_Shutdown Shutdown;
-  pRENDERDOC_UnloadCrashHandler UnloadCrashHandler;
-
-  pRENDERDOC_SetLogFilePathTemplate SetLogFilePathTemplate;
-  pRENDERDOC_GetLogFilePathTemplate GetLogFilePathTemplate;
-
-  pRENDERDOC_GetNumCaptures GetNumCaptures;
-  pRENDERDOC_GetCapture GetCapture;
-
-  pRENDERDOC_TriggerCapture TriggerCapture;
-
-  pRENDERDOC_IsTargetControlConnected IsTargetControlConnected;
-  pRENDERDOC_LaunchReplayUI LaunchReplayUI;
-
-  pRENDERDOC_SetActiveWindow SetActiveWindow;
-
-  pRENDERDOC_StartFrameCapture StartFrameCapture;
-  pRENDERDOC_IsFrameCapturing IsFrameCapturing;
-  pRENDERDOC_EndFrameCapture EndFrameCapture;
-
-  pRENDERDOC_TriggerMultiFrameCapture TriggerMultiFrameCapture;
-} RENDERDOC_API_1_1_1;
-
-// similarly to above, we renamed Get/SetLogFilePathTemplate to Get/SetCaptureFilePathTemplate.
-// We thus declare a new struct so that code that was referencing the RENDERDOC_API_1_1_1 struct
-// can still compile without changes, but new code will use the new struct members
-
-// eRENDERDOC_API_Version_1_1_2
-typedef struct
-{
-  pRENDERDOC_GetAPIVersion GetAPIVersion;
-
-  pRENDERDOC_SetCaptureOptionU32 SetCaptureOptionU32;
-  pRENDERDOC_SetCaptureOptionF32 SetCaptureOptionF32;
-
-  pRENDERDOC_GetCaptureOptionU32 GetCaptureOptionU32;
-  pRENDERDOC_GetCaptureOptionF32 GetCaptureOptionF32;
-
-  pRENDERDOC_SetFocusToggleKeys SetFocusToggleKeys;
-  pRENDERDOC_SetCaptureKeys SetCaptureKeys;
-
-  pRENDERDOC_GetOverlayBits GetOverlayBits;
-  pRENDERDOC_MaskOverlayBits MaskOverlayBits;
-
-  pRENDERDOC_Shutdown Shutdown;
-  pRENDERDOC_UnloadCrashHandler UnloadCrashHandler;
-
-  pRENDERDOC_SetCaptureFilePathTemplate SetCaptureFilePathTemplate;
-  pRENDERDOC_GetCaptureFilePathTemplate GetCaptureFilePathTemplate;
-
-  pRENDERDOC_GetNumCaptures GetNumCaptures;
-  pRENDERDOC_GetCapture GetCapture;
-
-  pRENDERDOC_TriggerCapture TriggerCapture;
-
-  pRENDERDOC_IsTargetControlConnected IsTargetControlConnected;
-  pRENDERDOC_LaunchReplayUI LaunchReplayUI;
-
-  pRENDERDOC_SetActiveWindow SetActiveWindow;
-
-  pRENDERDOC_StartFrameCapture StartFrameCapture;
-  pRENDERDOC_IsFrameCapturing IsFrameCapturing;
-  pRENDERDOC_EndFrameCapture EndFrameCapture;
-
-  pRENDERDOC_TriggerMultiFrameCapture TriggerMultiFrameCapture;
-} RENDERDOC_API_1_1_2;
 
 //////////////////////////////////////////////////////////////////////////////////////////////////
 // RenderDoc API entry point