Add ReplayOptions struct to contain replay-time configuration

* Not currently exposed to the UI or used by the drivers, we just pass the
  default object through

renderdoc/api/replay/control_types.h

@@ -698,3 +698,74 @@ struct GPUDevice
 };
 
 DECLARE_REFLECTION_STRUCT(GPUDevice);
+
+DOCUMENT("The options controlling how replay of a capture should be performed");
+struct ReplayOptions
+{
+  DOCUMENT("");
+  ReplayOptions() = default;
+  ReplayOptions(const ReplayOptions &) = default;
+
+  DOCUMENT(R"(Replay with API validation enabled and use debug messages from there, ignoring any
+that may be contained in the capture.
+
+The default is not to do any validation.
+
+.. note:: RenderDoc does not handle invalid API use in the general case so validation should still
+  be performed at runtime in your program for ground truth results.
+)");
+  bool apiValidation = false;
+
+  DOCUMENT(R"(Force the selection of a GPU by vendor ID. This allows overriding which GPU is used to
+replay on, even if a different GPU would be the best match for the capture.
+
+When set to :data:`GPUVendor.Unknown`, specifies no particular vendor.
+
+See also :data:`forceGPUDeviceID` and :data:`forceGPUDriverName`. Available GPUs can be enumerated
+using :meth:`CaptureAccess.GetAvailableGPUs`.
+
+The default is not to do any override. The capture contains information about what GPU was used, and
+the closest matching GPU is used on replay.
+
+.. note::
+  If a GPU is forced that is not available or not supported for a given capture, such as when GPUs
+  are only available for some APIs and not others, the default GPU selection will be used. If a GPU
+  is available for a capture but fails to open however then there is no fallback to a default GPU.
+
+  OpenGL does not support GPU selection so the default method (which effectively does nothing) will
+  always be used.
+)");
+  GPUVendor forceGPUVendor = GPUVendor::Unknown;
+
+  DOCUMENT(R"(Force the selection of a GPU by device ID. This allows overriding which GPU is used to
+replay on.
+
+When set to 0, specifies no particular device.
+
+See :data:`forceGPUDeviceID` for a full explanation of GPU selection override.
+)");
+  uint32_t forceGPUDeviceID = 0;
+
+  DOCUMENT(R"(Force the selection of a GPU by driver name. This allows overriding which GPU is used
+to replay on.
+
+When set to an empty string, specifies no particular driver.
+
+See :data:`forceGPUDeviceID` for a full explanation of GPU selection override.
+)");
+  rdcstr forceGPUDriverName;
+
+  DOCUMENT(R"(How much optimisation should be done, potentially at the cost of correctness.
+
+The default is :data:`ReplayOptimisationLevel.Balanced`.
+)");
+  ReplayOptimisationLevel optimisation = ReplayOptimisationLevel::Balanced;
+
+// helpers for Qt, define constructor and cast. These will be defined in Qt code
+#if defined(RENDERDOC_QT_COMPAT)
+  ReplayOptions(const QVariant &var);
+  operator QVariant() const;
+#endif
+};
+
+DECLARE_REFLECTION_STRUCT(ReplayOptions);

renderdoc/api/replay/renderdoc_replay.h

@@ -1690,6 +1690,7 @@ or an error has occurred.
   or :data:`NoPreference` to indicate no preference for any proxy.
 :param str logfile: The path on the remote system where the file is. If the file is only available
   locally you can use :meth:`CopyCaptureToRemote` to transfer it over the remote connection.
+:param ReplayOptions opts: The options controlling how the capture should be replayed.
 :param ProgressCallback progress: A callback that will be repeatedly called with an updated progress
   value for the opening. Can be ``None`` if no progress is desired.
 :return: A tuple containing the status of opening the capture, whether success or failure, and the
@@ -1697,7 +1698,8 @@ or an error has occurred.
 :rtype: ``tuple`` of :class:`ReplayStatus` and :class:`ReplayController`
 )");
   virtual rdcpair<ReplayStatus, IReplayController *> OpenCapture(
-      uint32_t proxyid, const char *logfile, RENDERDOC_ProgressCallback progress) = 0;
+      uint32_t proxyid, const char *logfile, const ReplayOptions &opts,
+      RENDERDOC_ProgressCallback progress) = 0;
 
   DOCUMENT(R"(Close a capture analysis handle previously opened by :meth:`OpenCapture`.
 
@@ -1854,13 +1856,15 @@ This function will block until the capture is fully loaded and ready.
 Once the replay is created, this :class:`CaptureFile` can be shut down, there is no dependency on it
 by the :class:`ReplayController`.
 
+:param ReplayOptions opts: The options controlling how the capture should be replayed.
 :param ProgressCallback progress: A callback that will be repeatedly called with an updated progress
   value for the opening. Can be ``None`` if no progress is desired.
 :return: A tuple containing the status of opening the capture, whether success or failure, and the
   resulting :class:`ReplayController` handle if successful.
 :rtype: ``tuple`` of :class:`ReplayStatus` and :class:`ReplayController`.
 )");
-  virtual rdcpair<ReplayStatus, IReplayController *> OpenCapture(RENDERDOC_ProgressCallback progress) = 0;
+  virtual rdcpair<ReplayStatus, IReplayController *> OpenCapture(
+      const ReplayOptions &opts, RENDERDOC_ProgressCallback progress) = 0;
 
   DOCUMENT(R"(Returns the structured data for this capture.
 

renderdoc/api/replay/renderdoc_tostr.inl

@@ -948,6 +948,19 @@ rdcstr DoStringise(const SectionType &el)
   END_ENUM_STRINGISE();
 }
 
+template <>
+rdcstr DoStringise(const ReplayOptimisationLevel &el)
+{
+  BEGIN_ENUM_STRINGISE(ReplayOptimisationLevel);
+  {
+    STRINGISE_ENUM_CLASS_NAMED(NoOptimisation, "No Optimisation");
+    STRINGISE_ENUM_CLASS(Conservative);
+    STRINGISE_ENUM_CLASS(Balanced);
+    STRINGISE_ENUM_CLASS(Fastest);
+  }
+  END_ENUM_STRINGISE();
+}
+
 template <>
 rdcstr DoStringise(const D3DBufferViewFlags &el)
 {

renderdoc/api/replay/replay_enums.h

@@ -3436,6 +3436,41 @@ DECLARE_REFLECTION_ENUM(LogType);
 
 ITERABLE_OPERATORS(LogType);
 
+DOCUMENT(R"(The level of optimisation used in
+
+.. data:: NoOptimisation
+
+  Completely disabled, no optimisation will be used at all.
+
+.. data:: Conservative
+
+  Optimisation is used when it doesn't interfere with replay correctness.
+
+.. data:: Balanced
+
+  Optimisation is used when it has minimal impact on replay correctness. This could include e.g.
+  resources appearing cleared instead of containing contents from prior frames where those resources
+  are written to before being read.
+
+.. data:: Fastest
+
+  All possible optimisations are enabled as long as they do not cause invalid/incorrect replay.
+  This could result in side-effects like data from one replay being visible early in another replay,
+  if it's known that the data will be overwritten before being used.
+)");
+enum class ReplayOptimisationLevel : int32_t
+{
+  NoOptimisation,
+  First = NoOptimisation,
+  Conservative,
+  Balanced,
+  Fastest,
+  Count,
+};
+
+DECLARE_REFLECTION_ENUM(ReplayOptimisationLevel);
+ITERABLE_OPERATORS(ReplayOptimisationLevel);
+
 #if defined(ENABLE_PYTHON_FLAG_ENUMS)
 
 ENABLE_PYTHON_FLAG_ENUMS;