From 83c53890da57c71233873eb1e8f091de62c12725 Mon Sep 17 00:00:00 2001 From: baldurk Date: Mon, 7 Sep 2026 18:04:21 +0100 Subject: [PATCH] Mark accessors/return values that can be None with Optional[] * This helps with type checkers to know that things can be None or not (both to silence previous warnings about "unnecessary" checks that are actually necessary, and to ensure those checks aren't omitted by accident) --- docs/python_api/examples/history_debug.py | 2 +- docs/python_api/examples/history_debug.rst | 4 +- docs/stubgen.py | 36 +++++++++++++-- docs/verify-docstrings.py | 5 ++ qrenderdoc/Code/Interface/Extensions.h | 16 +++---- qrenderdoc/Code/Interface/QRDInterface.h | 44 +++++++++--------- qrenderdoc/Code/Interface/RemoteHost.h | 2 +- renderdoc/api/replay/data_types.h | 10 ++-- renderdoc/api/replay/pipestate.h | 2 +- renderdoc/api/replay/renderdoc_replay.h | 54 +++++++++++++--------- renderdoc/api/replay/shader_types.h | 2 +- renderdoc/api/replay/structured_data.h | 10 ++-- 12 files changed, 113 insertions(+), 74 deletions(-) diff --git a/docs/python_api/examples/history_debug.py b/docs/python_api/examples/history_debug.py index 7307134ea..9c1f50cd8 100644 --- a/docs/python_api/examples/history_debug.py +++ b/docs/python_api/examples/history_debug.py @@ -106,7 +106,7 @@ def prepare_history(): refl = pipe.GetShaderReflection(renderdoc.ShaderStage.Pixel) - if not refl.debugInfo.debuggable: + if refl is None or not refl.debugInfo.debuggable: print("Shader can't be debugged:") print(refl.debugInfo.debugStatus) return diff --git a/docs/python_api/examples/history_debug.rst b/docs/python_api/examples/history_debug.rst index 875b53103..da1e4ed61 100644 --- a/docs/python_api/examples/history_debug.rst +++ b/docs/python_api/examples/history_debug.rst @@ -117,7 +117,7 @@ Picking the first of these, we can then :ref:`move to that event ` .. highlight:: python .. code:: python - if not refl.debugInfo.debuggable: + if refl is None or not refl.debugInfo.debuggable: print("Shader can't be debugged:") print(refl.debugInfo.debugStatus) return @@ -342,4 +342,4 @@ This example can be found under the name "Pixel History & Shader Debug" in the p :download:`Download the example script `. -.. literalinclude:: history_debug.py \ No newline at end of file +.. literalinclude:: history_debug.py diff --git a/docs/stubgen.py b/docs/stubgen.py index 25696a548..3817fa796 100644 --- a/docs/stubgen.py +++ b/docs/stubgen.py @@ -106,6 +106,8 @@ def process_annotation(context: Any, deps: Optional[List[str]], annot: str) -> s return f"'{ret}'" return ret + callable = annot.startswith("Callable") or annot.startswith("typing.Callable") + # use non-eval path if possible, only available on python 3.14 though :( # we make a locals set from the module, and add top-level imported modules # so that e.g. datetime.datetime can be found @@ -129,7 +131,12 @@ def process_annotation(context: Any, deps: Optional[List[str]], annot: str) -> s # if the import failed, we have to use eval() except ImportError: try: - dep_type = eval(annot, globals(), locals) + eval_annot = annot + if callable: + eval_annot = eval_annot.replace("NoneType", "None") + # TypeVars will get printed as ~Type + eval_annot = eval_annot.replace("~", "") + dep_type = eval(eval_annot, globals(), locals) break except NameError as n: name = re.findall(r"'([^']*)'", str(n))[0] @@ -146,8 +153,20 @@ def process_annotation(context: Any, deps: Optional[List[str]], annot: str) -> s raise ValueError("Expected typing type in complex dependency") # add a dependency on the typing object itself + optional = union = False + # detect Optional[] / Union[] + if hasattr(dep_type, "__origin__") and dep_type.__origin__ is typing.Union: + # Union with just [x, None] is Optional + if type(None) in dep_type.__args__ and len(dep_type.__args__) == 2: + optional = True + else: + union = True if deps is not None: - if "_name" in dir(dep_type): + if optional: + deps.append(f"typing.Optional") + elif union: + deps.append(f"typing.Union") + elif "_name" in dir(dep_type): deps.append(f"typing.{dep_type._name}") else: deps.append(f"typing.{dep_type.__name__}") @@ -160,7 +179,8 @@ def process_annotation(context: Any, deps: Optional[List[str]], annot: str) -> s inner.append("...") continue if a is None or a is type(None): - inner.append("None") + if not optional: + inner.append("None") continue if a == Any: inner.append("Any") @@ -193,17 +213,23 @@ def process_annotation(context: Any, deps: Optional[List[str]], annot: str) -> s process_annotation(context, deps, f"{module}.{a.__name__}") # Callables must format their arguments and return type (the last argument) - if "Callable" in annot: + if callable: ret = inner[-1] del inner[-1] inner = ", ".join(inner) if "_name" in dir(dep_type): + assert dep_type._name is not None return f"{dep_type._name}[[{inner}], {ret}]" else: return f"{dep_type.__name__}[[{inner}], {ret}]" inner = ", ".join(inner) - if "_name" in dir(dep_type): + if optional: + return f"Optional[{inner}]" + elif union: + return f"Union[{inner}]" + elif "_name" in dir(dep_type): + assert dep_type._name is not None return f"{dep_type._name}[{inner}]" else: return f"{dep_type.__name__}[{inner}]" diff --git a/docs/verify-docstrings.py b/docs/verify-docstrings.py index 5198a0fc6..98a3d399e 100644 --- a/docs/verify-docstrings.py +++ b/docs/verify-docstrings.py @@ -117,6 +117,11 @@ def make_c_typeval(ret: str, pattern: bool, typelist: List[str]): elif ret[0:5] == 'List[': inner = make_c_typeval(ret[5:-1], pattern, typelist) ret = '(const )?rdcarray<{}> ?[&*]?'.format(inner) if pattern else 'rdcarray<{}>'.format(inner) + elif ret[0:9] == 'Optional[': + inner = make_c_typeval(ret[9:-1], pattern, typelist) + if 'std::function' in inner or (inner.startswith("RENDERDOC_") and inner.endswith("Callback")): + return inner + ret = '(const )?{} ?\\*?'.format(inner) if pattern else '{} *'.format(inner) elif ret[0:6] == 'Tuple[': inners = [make_c_typeval(i.strip(), pattern, typelist) for i in ret[6:-1].split(',')] if pattern: diff --git a/qrenderdoc/Code/Interface/Extensions.h b/qrenderdoc/Code/Interface/Extensions.h index 20879fe2b..5d07ba407 100644 --- a/qrenderdoc/Code/Interface/Extensions.h +++ b/qrenderdoc/Code/Interface/Extensions.h @@ -448,7 +448,7 @@ is a layout type widget, to allow customising how children are added. By default added in a vertical layout. :param str windowTitle: The title of any window with this widget as its root. -:param Callable[[CaptureContext, QWidget, str], None] closed=None: **Optional parameter**. A callback +:param Optional[Callable[[CaptureContext, QWidget, str], None]] closed=None: **Optional parameter**. A callback that will be called when the widget is closed by the user. This implicitly deletes the widget and all its children, which will no longer be valid even if a handle to them exists. @@ -792,7 +792,7 @@ The widget needs to be added to a parent to become part of a panel or window. DOCUMENT(R"(Create a normal button widget. -:param Callable[[CaptureContext, QWidget, str], None] pressed=None: **Optional parameter**. Callback +:param Optional[Callable[[CaptureContext, QWidget, str], None]] pressed=None: **Optional parameter**. Callback to be called when the button is pressed. Callback function signature must match :func:`WidgetCallback`. :return: The handle to the newly created widget. @@ -867,8 +867,8 @@ When a capture is closed and all outputs are destroyed, the widget will automati output so there is no need to do that manually. :param QWidget widget: The widget to set the output for. -:param renderdoc.ReplayOutput output: The new output to set, or ``None`` to unset any previous - output. +:param Optional[renderdoc.ReplayOutput] output: The new output to set, or ``None`` to unset any + previous output. )"); virtual void SetWidgetReplayOutput(QWidget *widget, IReplayOutput *output) = 0; @@ -890,7 +890,7 @@ checkerboard to be rendered instead. This is the default behaviour when a widget DOCUMENT(R"(Create a checkbox widget which can be toggled between unchecked and checked. When created the checkbox is unchecked. -:param Callable[[CaptureContext, QWidget, str], None] changed=None: **Optional parameter**. Callback +:param Optional[Callable[[CaptureContext, QWidget, str], None]] changed=None: **Optional parameter**. Callback to be called when the widget is toggled. Callback function signature must match :func:`WidgetCallback`. :return: The handle to the newly created widget. @@ -904,7 +904,7 @@ at most one radio box in any group of sibling radio boxes being checked. Upon creation the radio box is unchecked, even in a group of other radio boxes that are unchecked. If you want a default radio box to be checked, you should use :meth:`SetWidgetChecked`. -:param Callable[[CaptureContext, QWidget, str], None] changed=None: **Optional parameter**. Callback +:param Optional[Callable[[CaptureContext, QWidget, str], None]] changed=None: **Optional parameter**. Callback to be called when the widget is toggled. Callback function signature must match :func:`WidgetCallback`. :return: The handle to the newly created widget. @@ -976,7 +976,7 @@ happen. :param bool singleLine: ``True`` if the widget should be a single-line entry, otherwise it is a multi-line text box. -:param Callable[[CaptureContext, QWidget, str], None] changed=None: **Optional parameter**. Callback +:param Optional[Callable[[CaptureContext, QWidget, str], None]] changed=None: **Optional parameter**. Callback to be called when the text in the textbox is changed. Callback function signature must match :func:`WidgetCallback`. :return: The handle to the newly created widget. @@ -991,7 +991,7 @@ When created there are no pre-defined entries in the drop-down section. This can :param bool editable: ``True`` if the widget should allow the user to enter any text they wish as well as being able to select a pre-defined entry. -:param Callable[[CaptureContext, QWidget, str], None] changed=None: **Optional parameter**. Callback +:param Optional[Callable[[CaptureContext, QWidget, str], None]] changed=None: **Optional parameter**. Callback to be called when the text in the combobox is changed. This will be called both when a new option is selected or when the user edits the text. Callback function signature must match :func:`WidgetCallback`. diff --git a/qrenderdoc/Code/Interface/QRDInterface.h b/qrenderdoc/Code/Interface/QRDInterface.h index 03d6017b8..ab09e87ce 100644 --- a/qrenderdoc/Code/Interface/QRDInterface.h +++ b/qrenderdoc/Code/Interface/QRDInterface.h @@ -405,7 +405,7 @@ If no capture is loaded or the EID doesn't correspond to a known event, ``None`` :param int eventId: The EID to look up. :return: The action containing the EID, or ``None`` if no such EID exists. -:rtype: renderdoc.ActionDescription +:rtype: Optional[renderdoc.ActionDescription] )"); virtual const ActionDescription *GetActionForEID(uint32_t eventId) = 0; @@ -416,7 +416,7 @@ If no capture is loaded or the EID doesn't correspond to a known event, an empty returned. :param int eventId: The EID to look up. -:return: The formatted name of the specified event, or ``None`` if no such EID exists. +:return: The formatted name of the specified event, or an empty string if no such EID exists. :rtype: str )"); virtual rdcstr GetEventName(uint32_t eventId) = 0; @@ -450,11 +450,11 @@ expression. :param Callable[[CaptureContext,str,str,int,renderdoc.SDChunk,renderdoc.ActionDescription,str], bool] filter: The callback to call for each candidate event to perform filtering. Callback function signature must match :func:`EventFilterCallback`. -:param Callable[[CaptureContext,str,str], str] parser=None: **Optional parameter**. The callback to +:param Optional[Callable[[CaptureContext,str,str], str]] parser=None: **Optional parameter**. The callback to call when the parsing the parameters and checking for any errors. This can be ``None`` if no pre-parsing is required. Callback function signature must match :func:`FilterParseCallback`. -:param Callable[[CaptureContext,str,str], List[str]] completer=None: **Optional parameter**. The +:param Optional[Callable[[CaptureContext,str,str], List[str]]] completer=None: **Optional parameter**. The callback to call when trying to provide autocomplete suggestions. This can be ``None`` if no completion is desired/applicable. Callback function signature must match :func:`AutoCompleteCallback`. @@ -1256,7 +1256,7 @@ If the PID is unrecognised, no connection will be made. :param int pid: The PID of the child to connect to. :return: The connection window if successful, or ``None`` if no connection was made. -:rtype: CaptureConnection +:rtype: Optional[CaptureConnection] )"); virtual ICaptureConnection *ConnectToChild(uint32_t pid) = 0; @@ -1334,7 +1334,7 @@ QWidget. DOCUMENT(R"(Launches a capture of the current executable. :return: The connection window if successful, or ``None`` if no connection was made. -:rtype: CaptureConnection +:rtype: Optional[CaptureConnection] )"); virtual ICaptureConnection *Launch() = 0; @@ -1958,7 +1958,7 @@ struct IReplayManager DOCUMENT(R"(Retrieves the capture access handle for the currently open file. :return: The file handle active, or ``None`` if no capture is open. -:rtype: renderdoc.CaptureAccess +:rtype: Optional[renderdoc.CaptureAccess] )"); virtual ICaptureAccess *GetCaptureAccess() = 0; @@ -1969,7 +1969,7 @@ will be usable. :return: The file handle active, or ``None`` if no capture is open or the capture is only available remotely. -:rtype: renderdoc.CaptureFile +:rtype: Optional[renderdoc.CaptureFile] )"); virtual ICaptureFile *GetCaptureFile() = 0; @@ -2374,7 +2374,7 @@ recommended that you do not cache this object and use it only in local areas of non-blocking. :return: A blocking version of the :class:`renderdoc.ReplayController`. -:rtype: renderdoc.ReplayController +:rtype: Optional[renderdoc.ReplayController] )"); ////////////////////////////////////////////////////////////// // This function is implemented only for python! it will return NULL unconditionally @@ -2613,21 +2613,21 @@ more information for how this differs. DOCUMENT(R"(Retrieve the current action. :return: The current action, or ``None`` if no action is selected. -:rtype: renderdoc.ActionDescription +:rtype: Optional[renderdoc.ActionDescription] )"); virtual const ActionDescription *CurAction() = 0; DOCUMENT(R"(Retrieve the first action in the capture. :return: The first action. -:rtype: renderdoc.ActionDescription +:rtype: Optional[renderdoc.ActionDescription] )"); virtual const ActionDescription *GetFirstAction() = 0; DOCUMENT(R"(Retrieve the last action in the capture. :return: The last action. -:rtype: renderdoc.ActionDescription +:rtype: Optional[renderdoc.ActionDescription] )"); virtual const ActionDescription *GetLastAction() = 0; @@ -2642,7 +2642,7 @@ more information for how this differs. :param renderdoc.ResourceId id: The ID of the resource to query about. :return: The information about a resource, or ``None`` if the ID does not correspond to a resource. -:rtype: renderdoc.ResourceDescription +:rtype: Optional[renderdoc.ResourceDescription] )"); virtual const ResourceDescription *GetResource(ResourceId id) const = 0; @@ -2732,7 +2732,7 @@ considered out of date :param renderdoc.ResourceId id: The ID of the texture to query about. :return: The information about a texture, or ``None`` if the ID does not correspond to a texture. -:rtype: renderdoc.TextureDescription +:rtype: Optional[renderdoc.TextureDescription] )"); virtual TextureDescription *GetTexture(ResourceId id) = 0; @@ -2747,7 +2747,7 @@ considered out of date :param renderdoc.ResourceId id: The ID of the buffer to query about. :return: The information about a buffer, or ``None`` if the ID does not correspond to a buffer. -:rtype: renderdoc.BufferDescription +:rtype: Optional[renderdoc.BufferDescription] )"); virtual BufferDescription *GetBuffer(ResourceId id) = 0; @@ -2763,7 +2763,7 @@ considered out of date :param renderdoc.ResourceId id: The ID of the buffer to query about. :return: The information about a descriptor store, or ``None`` if the ID does not correspond to a descriptor store. -:rtype: renderdoc.DescriptorStoreDescription +:rtype: Optional[renderdoc.DescriptorStoreDescription] )"); virtual DescriptorStoreDescription *GetDescriptorStore(ResourceId id) = 0; @@ -2773,7 +2773,7 @@ considered out of date :param int eventId: The :data:`eventId ` to query for. :return: The information about the action, or ``None`` if the :data:`eventId ` doesn't correspond to an action. -:rtype: renderdoc.ActionDescription +:rtype: Optional[renderdoc.ActionDescription] )"); virtual const ActionDescription *GetAction(uint32_t eventId) = 0; @@ -2809,7 +2809,7 @@ The handle returned is invalidated when the capture is closed, or if :meth:`Open called. :return: The RGP interop connection handle. -:rtype: RGPInterop +:rtype: Optional[RGPInterop] )"); virtual IRGPInterop *GetRGPInterop() = 0; @@ -3413,7 +3413,7 @@ The return value will be ``None`` if the capture is not using the D3D11 API. You should determine the API of the capture first before fetching it. :return: The current D3D11 pipeline state. -:rtype: renderdoc.D3D11State +:rtype: Optional[renderdoc.D3D11State] )"); virtual const D3D11Pipe::State *CurD3D11PipelineState() = 0; @@ -3423,7 +3423,7 @@ The return value will be ``None`` if the capture is not using the D3D12 API. You should determine the API of the capture first before fetching it. :return: The current D3D12 pipeline state. -:rtype: renderdoc.D3D12State +:rtype: Optional[renderdoc.D3D12State] )"); virtual const D3D12Pipe::State *CurD3D12PipelineState() = 0; @@ -3433,7 +3433,7 @@ The return value will be ``None`` if the capture is not using the OpenGL API. You should determine the API of the capture first before fetching it. :return: The current OpenGL pipeline state. -:rtype: renderdoc.GLState +:rtype: Optional[renderdoc.GLState] )"); virtual const GLPipe::State *CurGLPipelineState() = 0; @@ -3443,7 +3443,7 @@ The return value will be ``None`` if the capture is not using the Vulkan API. You should determine the API of the capture first before fetching it. :return: The current Vulkan pipeline state. -:rtype: renderdoc.VKState +:rtype: Optional[renderdoc.VKState] )"); virtual const VKPipe::State *CurVulkanPipelineState() = 0; diff --git a/qrenderdoc/Code/Interface/RemoteHost.h b/qrenderdoc/Code/Interface/RemoteHost.h index 81b38b742..40ca3d78d 100644 --- a/qrenderdoc/Code/Interface/RemoteHost.h +++ b/qrenderdoc/Code/Interface/RemoteHost.h @@ -150,7 +150,7 @@ public: DOCUMENT(R"( :return: The :class:`~renderdoc.DeviceProtocolController` for this host, or ``None`` if no protocol is in use -:rtype: renderdoc.DeviceProtocolController +:rtype: Optional[renderdoc.DeviceProtocolController] )"); IDeviceProtocolController *Protocol() const { return m_protocol; } DOCUMENT(R"( diff --git a/renderdoc/api/replay/data_types.h b/renderdoc/api/replay/data_types.h index 619b6a8a3..d987cc0eb 100644 --- a/renderdoc/api/replay/data_types.h +++ b/renderdoc/api/replay/data_types.h @@ -893,7 +893,7 @@ typically it is one parent to many derived. DOCUMENT(R"(An optional set of annotations associated with this resource, may be ``None`` if annotations are not used. -:type: SDObject +:type: Optional[SDObject] )"); SDObject *annotations = NULL; @@ -1253,7 +1253,7 @@ markers added to the capture after load. DOCUMENT(R"(An optional set of annotations associated with this event, may be ``None`` if annotations are not used. -:type: SDObject +:type: Optional[SDObject] )"); SDObject *annotations = NULL; @@ -2526,19 +2526,19 @@ operation. DOCUMENT(R"(The parent of this action, or ``None`` if there is no parent for this action. -:type: ActionDescription +:type: Optional[ActionDescription] )"); const ActionDescription *parent = NULL; DOCUMENT(R"(The previous action in the frame, or ``None`` if this is the first action in the frame. -:type: ActionDescription +:type: Optional[ActionDescription] )"); const ActionDescription *previousAction = NULL; DOCUMENT(R"(The next action in the frame, or ``None`` if this is the last action in the frame. -:type: ActionDescription +:type: Optional[ActionDescription] )"); const ActionDescription *nextAction = NULL; diff --git a/renderdoc/api/replay/pipestate.h b/renderdoc/api/replay/pipestate.h index c52fbdebf..9f9fd1d2a 100644 --- a/renderdoc/api/replay/pipestate.h +++ b/renderdoc/api/replay/pipestate.h @@ -258,7 +258,7 @@ This returns ``None`` if no shader is bound. :param ShaderStage stage: The shader stage to fetch. :return: The reflection data for the given shader. -:rtype: ShaderReflection +:rtype: Optional[ShaderReflection] )"); const ShaderReflection *GetShaderReflection(ShaderStage stage) const; diff --git a/renderdoc/api/replay/renderdoc_replay.h b/renderdoc/api/replay/renderdoc_replay.h index 77a888406..333bb52fd 100644 --- a/renderdoc/api/replay/renderdoc_replay.h +++ b/renderdoc/api/replay/renderdoc_replay.h @@ -445,7 +445,7 @@ struct IReplayController :param WindowingData window: A :class:`WindowingData` describing the native window. :param ReplayOutputType type: What type of output to create :return: A handle to the created output, or ``None`` on failure -:rtype: ReplayOutput +:rtype: Optional[ReplayOutput] )"); virtual IReplayOutput *CreateOutput(WindowingData window, ReplayOutputType type) = 0; @@ -494,7 +494,7 @@ You should use :meth:`GetAPIProperties` to determine the API of the capture. See also :meth:`GetPipelineState`. :return: The current D3D11 pipeline state. -:rtype: D3D11State +:rtype: Optional[D3D11State] )"); virtual const D3D11Pipe::State *GetD3D11PipelineState() = 0; @@ -506,7 +506,7 @@ You should use :meth:`GetAPIProperties` to determine the API of the capture. See also :meth:`GetPipelineState`. :return: The current D3D12 pipeline state. -:rtype: D3D12State +:rtype: Optional[D3D12State] )"); virtual const D3D12Pipe::State *GetD3D12PipelineState() = 0; @@ -518,7 +518,7 @@ You should use :meth:`GetAPIProperties` to determine the API of the capture. See also :meth:`GetPipelineState`. :return: The current OpenGL pipeline state. -:rtype: GLState +:rtype: Optional[GLState] )"); virtual const GLPipe::State *GetGLPipelineState() = 0; @@ -530,7 +530,7 @@ You should use :meth:`GetAPIProperties` to determine the API of the capture. See also :meth:`GetPipelineState`. :return: The current Vulkan pipeline state. -:rtype: VKState +:rtype: Optional[VKState] )"); virtual const VKPipe::State *GetVulkanPipelineState() = 0; @@ -1223,7 +1223,7 @@ The details of the types of messages that can be received are listed under This function will block but only to a limited degree. If no message is waiting after a small time it will return with a No-op message to allow further processing. -:param Callable[[float], None] progress=None: **Optional parameter**. A callback that will be +:param Optional[Callable[[float], None]] progress=None: **Optional parameter**. A callback that will be repeatedly called with an updated progress value when a long blocking message is coming through, e.g. a capture copy. Can be ``None`` if no progress is desired. Callback function signature must match :func:`ProgressCallback`. @@ -1325,7 +1325,7 @@ separate thread. If this is ``False``, the function will not interact or block forever on user interaction and will always assume the input is effectively 'cancel' or empty. This may cause the symbol resolution to fail. -:param Callable[[float], None] progress=None: **Optional parameter**. A callback that will be +:param Optional[Callable[[float], None]] progress=None: **Optional parameter**. A callback that will be repeatedly called with an updated progress value for the resolver process. Can be ``None`` if no progress is desired. Callback function signature must match :func:`ProgressCallback`. @@ -1515,7 +1515,7 @@ This is primarily useful for when a capture is only stored locally and must be r the capture must be available on the machine where the replay happens. :param str filename: The path to the file on the local system. -:param Callable[[float], None] progress=None: **Optional parameter**. A callback that will be +:param Optional[Callable[[float], None]] progress=None: **Optional parameter**. A callback that will be repeatedly called with an updated progress value for the copy. Can be ``None`` if no progress is desired. Callback function signature must match :func:`ProgressCallback`. @@ -1531,7 +1531,7 @@ This function will block until the copy is fully complete, or an error has occur :param str remotepath: The remote path where the file should be copied from. :param str localpath: The local path where the file should be saved. -:param Callable[[float], None] progress=None: **Optional parameter**. A callback that will be +:param Optional[Callable[[float], None]] progress=None: **Optional parameter**. A callback that will be repeatedly called with an updated progress value for the copy. Can be ``None`` if no progress is desired. Callback function signature must match :func:`ProgressCallback`. @@ -1555,7 +1555,7 @@ or an error has occurred. :param str filename: 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 Callable[[float], None] progress=None: **Optional parameter**. A callback that will be +:param Optional[Callable[[float], None]] progress=None: **Optional parameter**. A callback that will be repeatedly called with an updated progress value for the opening. Can be ``None`` if no progress is desired. Callback function signature must match :func:`ProgressCallback`. @@ -1599,7 +1599,7 @@ empty or unrecognised. :param str filename: The filename of the file to open. :param str filetype: The format of the given file. -:param Callable[[float], None] progress=None: **Optional parameter**. A callback that will be +:param Optional[Callable[[float], None]] progress=None: **Optional parameter**. A callback that will be repeatedly called with an updated progress value if an import step occurs. Can be ``None`` if no progress is desired. Callback function signature must match :func:`ProgressCallback`. @@ -1617,7 +1617,7 @@ For the :paramref:`OpenBuffer.filetype` parameter, see :meth:`OpenFile`. :param bytes buffer: The buffer containing the data to process. :param str filetype: The format of the given file. -:param Callable[[float], None] progress=None: **Optional parameter**. A callback that will be +:param Optional[Callable[[float], None]] progress=None: **Optional parameter**. A callback that will be repeatedly called with an updated progress value if an import step occurs. Can be ``None`` if no progress is desired. Callback function signature must match :func:`ProgressCallback`. @@ -1648,12 +1648,12 @@ representation back to native RDC. :param str filename: The filename to save to. :param str filetype: The format to convert to. -:param SDFile file=None: **Optional parameter**. An optional :class:`SDFile` with the structured +:param Optional[SDFile] file=None: **Optional parameter**. An optional :class:`SDFile` with the structured data to source from. This is useful in case the format specifies that it doesn't need buffers, and you already have a :class:`ReplayController` open with the structured data. This saves the need to load the file again. If ``None`` then structured data will be fetched if not already present and used. -:param Callable[[float], None] progress=None: **Optional parameter**. A callback that will be +:param Optional[Callable[[float], None]] progress=None: **Optional parameter**. A callback that will be repeatedly called with an updated progress value for the conversion. Can be ``None`` if no progress is desired. Callback function signature must match :func:`ProgressCallback`. @@ -1743,7 +1743,7 @@ Once the replay is created, this :class:`CaptureFile` can be shut down, there is by the :class:`ReplayController`. :param ReplayOptions opts: The options controlling how the capture should be replayed. -:param Callable[[float], None] progress=None: **Optional parameter**. A callback that will be +:param Optional[Callable[[float], None]] progress=None: **Optional parameter**. A callback that will be repeatedly called with an updated progress value for the opening. Can be ``None`` if no progress is desired. Callback function signature must match :func:`ProgressCallback`. @@ -1974,7 +1974,7 @@ This function will block until the control connection is ready, or an error occu :param bool forceConnection: Force the connection and kick off any existing client that is currently connected. :return: A handle to the target control connection, or ``None`` if something went wrong. -:rtype: TargetControl +:rtype: Optional[TargetControl] )"); extern "C" RENDERDOC_API ITargetControl *RENDERDOC_CC RENDERDOC_CreateTargetControl( const rdcstr &URL, uint32_t ident, const rdcstr &clientName, bool forceConnection); @@ -2033,11 +2033,12 @@ This function will block until a remote connection tells the server to shut down :param str listenhost: The name of the interface to listen on. :param int port: The port to listen on, or ``0`` to listen on the default port. -:param Callable[[], bool] killReplay: A callback that returns a ``bool`` indicating if the server should - be shut down or not. +:param Optional[Callable[[], bool]] killReplay=None: **Optional parameter**. + A callback that returns a ``bool`` indicating if the server should be shut down or not. Callback function signature must match :func:`KillCallback`. -:param Callable[[bool], WindowingData] previewWindow: A callback that returns information for a preview window - when the server wants to display some preview of the ongoing replay. +:param Optional[Callable[[bool], WindowingData]] previewWindow=None: **Optional parameter**. + A callback that returns information for a preview window when the server wants to display + some preview of the ongoing replay. Callback function signature must match :func:`PreviewWindowCallback`. )"); extern "C" RENDERDOC_API void RENDERDOC_CC RENDERDOC_BecomeRemoteServer( @@ -2180,11 +2181,18 @@ struct VulkanLayerRegistrationInfo rdcarray otherJSONs; }; -DOCUMENT("INTERNAL: Determine vulkan layer registration status."); +DOCUMENT(R"(INTERNAL: Determine vulkan layer registration status. + +:param VulkanLayerRegistrationInfo x: Internal parameter +:rtype bool +)"); extern "C" RENDERDOC_API bool RENDERDOC_CC RENDERDOC_NeedVulkanLayerRegistration(VulkanLayerRegistrationInfo *info); -DOCUMENT("INTERNAL: Update vulkan layer registration."); +DOCUMENT(R"(INTERNAL: Update vulkan layer registration. + +:param bool x: Internal parameter +)"); extern "C" RENDERDOC_API void RENDERDOC_CC RENDERDOC_UpdateVulkanLayerRegistration(bool systemLevel); ////////////////////////////////////////////////////////////////////////// @@ -2439,7 +2447,7 @@ immediate use of it may block. :param str protocol: The protocol to fetch a controller for. :return: A handle to the protocol controller, or ``None`` if something went wrong such as an unsupported protocol being specified. -:rtype: DeviceProtocolController +:rtype: Optional[DeviceProtocolController] )"); extern "C" RENDERDOC_API IDeviceProtocolController *RENDERDOC_CC RENDERDOC_GetDeviceProtocolController(const rdcstr &protocol); diff --git a/renderdoc/api/replay/shader_types.h b/renderdoc/api/replay/shader_types.h index b050934f2..bcac54ebf 100644 --- a/renderdoc/api/replay/shader_types.h +++ b/renderdoc/api/replay/shader_types.h @@ -1120,7 +1120,7 @@ shader and generate new debug states. If this is ``None`` then the trace is invalid. -:type: ShaderDebugger +:type: Optional[ShaderDebugger] )"); ShaderDebugger *debugger = NULL; diff --git a/renderdoc/api/replay/structured_data.h b/renderdoc/api/replay/structured_data.h index c1d0f641f..5c30f4ad7 100644 --- a/renderdoc/api/replay/structured_data.h +++ b/renderdoc/api/replay/structured_data.h @@ -707,7 +707,7 @@ returned. :param str childName: The name to search for. :return: A reference to the child object if found, or ``None`` if not. -:rtype: SDObject +:rtype: Optional[SDObject] )"); inline SDObject *FindChild(const rdcstr &childName) { @@ -724,7 +724,7 @@ The order of the search is not guaranteed, so care should be taken when the name :param str childName: The name to search for. :return: A reference to the child object if found, or ``None`` if not. -:rtype: SDObject +:rtype: Optional[SDObject] )"); inline SDObject *FindChildRecursively(const rdcstr &childName) { @@ -801,7 +801,7 @@ manipulated by key path exclusively or not at all. :param str keyPath: The key path to search for and return. :return: Whether or not a child exists at the given key path -:rtype: SDObject +:rtype: Optional[SDObject] )"); inline const SDObject *FindChildByKeyPath(const rdcstr &keyPath) const { @@ -868,7 +868,7 @@ returned. :param int index: The index to look up. :return: A reference to the child object if valid, or ``None`` if not. -:rtype: SDObject +:rtype: Optional[SDObject] )"); inline SDObject *GetChild(size_t index) { @@ -884,7 +884,7 @@ returned. DOCUMENT(R"(Get the parent of this object. If this object has no parent, ``None`` is returned. :return: A reference to the parent object if valid, or ``None`` if not. -:rtype: SDObject +:rtype: Optional[SDObject] )"); inline SDObject *GetParent() { return m_Parent; } #if !defined(SWIG)