Add string messages to returned result codes to display to user

* Most of the main entry points that can fail with relevant reasons now has a
  way of specifying a message to return with it. This message can be displayed
  to the user to give more information or context about an error.

docs/python_api/examples/renderdoc/decode_mesh.py

@@ -253,21 +253,21 @@ def loadCapture(filename):
 	cap = rd.OpenCaptureFile()
 
 	# Open a particular file - see also OpenBuffer to load from memory
-	status = cap.OpenFile(filename, '', None)
+	result = cap.OpenFile(filename, '', None)
 
 	# Make sure the file opened successfully
-	if status != rd.ReplayStatus.Succeeded:
-		raise RuntimeError("Couldn't open file: " + str(status))
+	if result != rd.ResultCode.Succeeded:
+		raise RuntimeError("Couldn't open file: " + str(result))
 
 	# Make sure we can replay
 	if not cap.LocalReplaySupport():
 		raise RuntimeError("Capture cannot be replayed")
 
 	# Initialise the replay
-	status,controller = cap.OpenCapture(rd.ReplayOptions(), None)
+	result,controller = cap.OpenCapture(rd.ReplayOptions(), None)
 
-	if status != rd.ReplayStatus.Succeeded:
-		raise RuntimeError("Couldn't initialise replay: " + str(status))
+	if result != rd.ResultCode.Succeeded:
+		raise RuntimeError("Couldn't initialise replay: " + str(result))
 
 	return (cap, controller)
 

docs/python_api/examples/renderdoc/display_window.py

@@ -12,21 +12,21 @@ def loadCapture(filename):
 	cap = rd.OpenCaptureFile()
 
 	# Open a particular file - see also OpenBuffer to load from memory
-	status = cap.OpenFile(filename, '', None)
+	result = cap.OpenFile(filename, '', None)
 
 	# Make sure the file opened successfully
-	if status != rd.ReplayStatus.Succeeded:
-		raise RuntimeError("Couldn't open file: " + str(status))
+	if result != rd.ResultCode.Succeeded:
+		raise RuntimeError("Couldn't open file: " + str(result))
 
 	# Make sure we can replay
 	if not cap.LocalReplaySupport():
 		raise RuntimeError("Capture cannot be replayed")
 
 	# Initialise the replay
-	status,controller = cap.OpenCapture(rd.ReplayOptions(), None)
+	result,controller = cap.OpenCapture(rd.ReplayOptions(), None)
 
-	if status != rd.ReplayStatus.Succeeded:
-		raise RuntimeError("Couldn't initialise replay: " + str(status))
+	if result != rd.ResultCode.Succeeded:
+		raise RuntimeError("Couldn't initialise replay: " + str(result))
 
 	return cap,controller
 

docs/python_api/examples/renderdoc/fetch_counters.py

@@ -69,21 +69,21 @@ def loadCapture(filename):
 	cap = rd.OpenCaptureFile()
 
 	# Open a particular file - see also OpenBuffer to load from memory
-	status = cap.OpenFile(filename, '', None)
+	result = cap.OpenFile(filename, '', None)
 
 	# Make sure the file opened successfully
-	if status != rd.ReplayStatus.Succeeded:
-		raise RuntimeError("Couldn't open file: " + str(status))
+	if result != rd.ResultCode.Succeeded:
+		raise RuntimeError("Couldn't open file: " + str(result))
 
 	# Make sure we can replay
 	if not cap.LocalReplaySupport():
 		raise RuntimeError("Capture cannot be replayed")
 
 	# Initialise the replay
-	status,controller = cap.OpenCapture(rd.ReplayOptions(), None)
+	result,controller = cap.OpenCapture(rd.ReplayOptions(), None)
 
-	if status != rd.ReplayStatus.Succeeded:
-		raise RuntimeError("Couldn't initialise replay: " + str(status))
+	if result != rd.ResultCode.Succeeded:
+		raise RuntimeError("Couldn't initialise replay: " + str(result))
 
 	return cap,controller
 

docs/python_api/examples/renderdoc/fetch_shader.py

@@ -60,21 +60,21 @@ def loadCapture(filename):
 	cap = rd.OpenCaptureFile()
 
 	# Open a particular file - see also OpenBuffer to load from memory
-	status = cap.OpenFile(filename, '', None)
+	result = cap.OpenFile(filename, '', None)
 
 	# Make sure the file opened successfully
-	if status != rd.ReplayStatus.Succeeded:
-		raise RuntimeError("Couldn't open file: " + str(status))
+	if result != rd.ResultCode.Succeeded:
+		raise RuntimeError("Couldn't open file: " + str(result))
 
 	# Make sure we can replay
 	if not cap.LocalReplaySupport():
 		raise RuntimeError("Capture cannot be replayed")
 
 	# Initialise the replay
-	status,controller = cap.OpenCapture(rd.ReplayOptions(), None)
+	result,controller = cap.OpenCapture(rd.ReplayOptions(), None)
 
-	if status != rd.ReplayStatus.Succeeded:
-		raise RuntimeError("Couldn't initialise replay: " + str(status))
+	if result != rd.ResultCode.Succeeded:
+		raise RuntimeError("Couldn't initialise replay: " + str(result))
 
 	return (cap, controller)
 

docs/python_api/examples/renderdoc/iter_actions.py

@@ -63,21 +63,21 @@ def loadCapture(filename):
 	cap = rd.OpenCaptureFile()
 
 	# Open a particular file - see also OpenBuffer to load from memory
-	status = cap.OpenFile(filename, '', None)
+	result = cap.OpenFile(filename, '', None)
 
 	# Make sure the file opened successfully
-	if status != rd.ReplayStatus.Succeeded:
-		raise RuntimeError("Couldn't open file: " + str(status))
+	if result != rd.ResultCode.Succeeded:
+		raise RuntimeError("Couldn't open file: " + str(result))
 
 	# Make sure we can replay
 	if not cap.LocalReplaySupport():
 		raise RuntimeError("Capture cannot be replayed")
 
 	# Initialise the replay
-	status,controller = cap.OpenCapture(rd.ReplayOptions(), None)
+	result,controller = cap.OpenCapture(rd.ReplayOptions(), None)
 
-	if status != rd.ReplayStatus.Succeeded:
-		raise RuntimeError("Couldn't initialise replay: " + str(status))
+	if result != rd.ResultCode.Succeeded:
+		raise RuntimeError("Couldn't initialise replay: " + str(result))
 
 	return cap,controller
 

docs/python_api/examples/renderdoc/remote_capture.py

@@ -58,23 +58,23 @@ else:
     URL = hostname
 
 # Let's try to connect
-status,remote = rd.CreateRemoteServerConnection(URL)
+result,remote = rd.CreateRemoteServerConnection(URL)
 
-if status == rd.ReplayStatus.NetworkIOFailed and protocol is not None:
+if result == rd.ResultCode.NetworkIOFailed and protocol is not None:
     # If there's just no I/O, most likely the server is not running. If we have
     # a protocol, we can try to start the remote server
     print("Couldn't connect to remote server, trying to start it")
 
-    status = protocol.StartRemoteServer(URL)
+    result = protocol.StartRemoteServer(URL)
 
-    if status != rd.ReplayStatus.Succeeded:
-        raise RuntimeError(f"Couldn't launch remote server, got error {str(status)}")
+    if result != rd.ResultCode.Succeeded:
+        raise RuntimeError(f"Couldn't launch remote server, got error {str(result)}")
 
     # Try to connect again!
-    status,remote = rd.CreateRemoteServerConnection(URL)
+    result,remote = rd.CreateRemoteServerConnection(URL)
 
-if status != rd.ReplayStatus.Succeeded:
-    raise RuntimeError(f"Couldn't connect to remote server, got error {str(status)}")
+if result != rd.ResultCode.Succeeded:
+    raise RuntimeError(f"Couldn't connect to remote server, got error {str(result)}")
 
 # We now have a remote connection. This works regardless of whether it's a device
 # with a protocol or not. In fact we are done with the protocol at this point
@@ -101,9 +101,9 @@ print(f"Running {exe}")
 
 result = remote.ExecuteAndInject(exe, workingDir, cmdLine, env, opts)
 
-if result.status != rd.ReplayStatus.Succeeded:
+if result.result != rd.ResultCode.Succeeded:
     remote.ShutdownServerAndConnection()
-    raise RuntimeError(f"Couldn't launch {exe}, got error {str(result.status)}")
+    raise RuntimeError(f"Couldn't launch {exe}, got error {str(result.result)}")
 
 # Spin up a thread to keep the remote server connection alive while we make a capture,
 # as it will time out after 5 seconds of inactivity
@@ -171,11 +171,11 @@ print(f"Got new capture at {cap_path} which is frame {msg.newCapture.frameNumber
 #
 # The path must be remote - if the capture isn't freshly created then you need
 # to copy it with remote.CopyCaptureToRemote()
-status,controller = remote.OpenCapture(rd.RemoteServer.NoPreference, cap_path, rd.ReplayOptions(), None)
+result,controller = remote.OpenCapture(rd.RemoteServer.NoPreference, cap_path, rd.ReplayOptions(), None)
 
-if status != rd.ReplayStatus.Succeeded:
+if result != rd.ResultCode.Succeeded:
     remote.ShutdownServerAndConnection()
-    raise RuntimeError(f"Couldn't open {cap_path}, got error {str(result.status)}")
+    raise RuntimeError(f"Couldn't open {cap_path}, got error {str(result)}")
 
 # We can now use replay as normal.
 #

docs/python_api/examples/renderdoc/remote_capture.rst

@@ -43,18 +43,18 @@ If the connection fails, normally we must fail but if we have a device protocol
 .. highlight:: python
 .. code:: python
 
-  if status == rd.ReplayStatus.NetworkIOFailed and protocol is not None:
+  if result == rd.ResultCode.NetworkIOFailed and protocol is not None:
     # If there's just no I/O, most likely the server is not running. If we have
     # a protocol, we can try to start the remote server
     print("Couldn't connect to remote server, trying to start it")
 
-    status = protocol.StartRemoteServer(URL)
+    result = protocol.StartRemoteServer(URL)
 
-    if status != rd.ReplayStatus.Succeeded:
-      raise RuntimeError(f"Couldn't launch remote server, got error {str(status)}")
+    if result != rd.ResultCode.Succeeded:
+      raise RuntimeError(f"Couldn't launch remote server, got error {str(result)}")
 
     # Try to connect again!
-    status,remote = rd.CreateRemoteServerConnection(URL)
+    result,remote = rd.CreateRemoteServerConnection(URL)
 
 .. note::
 

docs/python_api/examples/renderdoc/save_texture.py

@@ -78,21 +78,21 @@ def loadCapture(filename):
 	cap = rd.OpenCaptureFile()
 
 	# Open a particular file - see also OpenBuffer to load from memory
-	status = cap.OpenFile(filename, '', None)
+	result = cap.OpenFile(filename, '', None)
 
 	# Make sure the file opened successfully
-	if status != rd.ReplayStatus.Succeeded:
-		raise RuntimeError("Couldn't open file: " + str(status))
+	if result != rd.ResultCode.Succeeded:
+		raise RuntimeError("Couldn't open file: " + str(result))
 
 	# Make sure we can replay
 	if not cap.LocalReplaySupport():
 		raise RuntimeError("Capture cannot be replayed")
 
 	# Initialise the replay
-	status,controller = cap.OpenCapture(rd.ReplayOptions(), None)
+	result,controller = cap.OpenCapture(rd.ReplayOptions(), None)
 
-	if status != rd.ReplayStatus.Succeeded:
-		raise RuntimeError("Couldn't initialise replay: " + str(status))
+	if result != rd.ResultCode.Succeeded:
+		raise RuntimeError("Couldn't initialise replay: " + str(result))
 
 	return (cap, controller)
 

docs/python_api/examples/renderdoc_intro.py

@@ -6,21 +6,21 @@ rd.InitialiseReplay(rd.GlobalEnvironment(), [])
 cap = rd.OpenCaptureFile()
 
 # Open a particular file - see also OpenBuffer to load from memory
-status = cap.OpenFile('test.rdc', '', None)
+result = cap.OpenFile('test.rdc', '', None)
 
 # Make sure the file opened successfully
-if status != rd.ReplayStatus.Succeeded:
-    raise RuntimeError("Couldn't open file: " + str(status))
+if result != rd.ResultCode.Succeeded:
+    raise RuntimeError("Couldn't open file: " + str(result))
 
 # Make sure we can replay
 if not cap.LocalReplaySupport():
     raise RuntimeError("Capture cannot be replayed")
 
 # Initialise the replay
-status,controller = cap.OpenCapture(rd.ReplayOptions(), None)
+result,controller = cap.OpenCapture(rd.ReplayOptions(), None)
 
-if status != rd.ReplayStatus.Succeeded:
-    raise RuntimeError("Couldn't initialise replay: " + str(status))
+if result != rd.ResultCode.Succeeded:
+    raise RuntimeError("Couldn't initialise replay: " + str(result))
 
 # Now we can use the controller!
 print("%d top-level actions" % len(controller.GetRootActions()))

docs/python_api/examples/renderdoc_intro.rst

@@ -63,7 +63,7 @@ Before doing anything, we must initialise the replay API. We do that by calling
 
 To begin with, we use :py:meth:`~renderdoc.OpenCaptureFile` to obtain a :py:class:`~renderdoc.CaptureFile` instance. This gives us access to control over a capture file at a meta level. For more information see the :py:class:`CaptureFile` reference - the interface can also be used to create.
 
-To open a file, use :py:meth:`~renderdoc.CaptureFile.OpenFile` on the :py:class:`~renderdoc.CaptureFile` instance. This function allows conversion from other formats via an importer, but here we'll use it just for opening a regular ``rdc`` file. It returns a :py:class:`~renderdoc.ReplayStatus` which can be used to determine what went wrong in the event that there was a problem. We then check that the capture uses an API which can be replayed locally - for example not every platform supports ``D3D11``, so on linux this would return no local replay support.
+To open a file, use :py:meth:`~renderdoc.CaptureFile.OpenFile` on the :py:class:`~renderdoc.CaptureFile` instance. This function allows conversion from other formats via an importer, but here we'll use it just for opening a regular ``rdc`` file. It returns a :py:class:`~renderdoc.ResultDetails` which can be used to determine what went wrong in the event that there was a problem. We then check that the capture uses an API which can be replayed locally - for example not every platform supports ``D3D11``, so on linux this would return no local replay support.
 
 .. highlight:: python
 .. code:: python
@@ -72,11 +72,11 @@ To open a file, use :py:meth:`~renderdoc.CaptureFile.OpenFile` on the :py:class:
     cap = rd.OpenCaptureFile()
 
     # Open a particular file - see also OpenBuffer to load from memory
-    status = cap.OpenFile('test.rdc', '', None)
+    result = cap.OpenFile('test.rdc', '', None)
 
     # Make sure the file opened successfully
-    if status != rd.ReplayStatus.Succeeded:
-        raise RuntimeError("Couldn't open file: " + str(status))
+    if result != rd.ResultCode.Succeeded:
+        raise RuntimeError("Couldn't open file: " + str(result))
 
     # Make sure we can replay
     if not cap.LocalReplaySupport():
@@ -85,7 +85,7 @@ To open a file, use :py:meth:`~renderdoc.CaptureFile.OpenFile` on the :py:class:
 Accessing Capture Analysis
 --------------------------
 
-Once the capture has been loaded, we can now begin the replay analysis. To do that we use :py:meth:`~renderdoc.CaptureFile.OpenCapture` which returns a tuple of :py:class:`~renderdoc.ReplayStatus` and :py:class:`~renderdoc.ReplayController`.
+Once the capture has been loaded, we can now begin the replay analysis. To do that we use :py:meth:`~renderdoc.CaptureFile.OpenCapture` which returns a tuple of :py:class:`~renderdoc.ResultDetails` and :py:class:`~renderdoc.ReplayController`.
 
 This function call will open the capture and begin to replay it, and initialise the analysis. The :py:class:`~renderdoc.ReplayController` returned is the interface to the majority of RenderDoc's replaying functionality.
 
@@ -93,10 +93,10 @@ This function call will open the capture and begin to replay it, and initialise
 .. code:: python
 
     # Initialise the replay
-    status,controller = cap.OpenCapture(rd.ReplayOptions(), None)
+    result,controller = cap.OpenCapture(rd.ReplayOptions(), None)
 
-    if status != rd.ReplayStatus.Succeeded:
-        raise RuntimeError("Couldn't initialise replay: " + str(status))
+    if result != rd.ResultCode.Succeeded:
+        raise RuntimeError("Couldn't initialise replay: " + str(result))
 
     # Now we can use the controller!
     print("%d top-level actions" % len(controller.GetRootActions()))

docs/python_api/renderdoc/replay.rst

@@ -14,6 +14,12 @@ Initialisation and Shutdown
 .. autoclass:: renderdoc.GlobalEnvironment
   :members:
 
+.. autoclass:: renderdoc.ResultCode
+  :members:
+
+.. autoclass:: renderdoc.ResultDetails
+  :members:
+
 Capture File Access
 -------------------
 
@@ -25,9 +31,6 @@ Capture File Access
 .. autoclass:: renderdoc.CaptureFile
   :members:
 
-.. autoclass:: renderdoc.ReplayStatus
-  :members:
-
 .. autoclass:: renderdoc.ReplaySupport
   :members: